| < draft-ietf-core-coap-15.txt | draft-ietf-core-coap-18.txt > | |||
|---|---|---|---|---|
| CoRE Working Group Z. Shelby | CoRE Working Group Z. Shelby | |||
| Internet-Draft Sensinode | Internet-Draft Sensinode | |||
| Intended status: Standards Track K. Hartke | Intended status: Standards Track K. Hartke | |||
| Expires: October 16, 2013 C. Bormann | Expires: December 30, 2013 C. Bormann | |||
| Universitaet Bremen TZI | Universitaet Bremen TZI | |||
| April 14, 2013 | June 28, 2013 | |||
| Constrained Application Protocol (CoAP) | Constrained Application Protocol (CoAP) | |||
| draft-ietf-core-coap-15 | draft-ietf-core-coap-18 | |||
| Abstract | Abstract | |||
| The Constrained Application Protocol (CoAP) is a specialized web | The Constrained Application Protocol (CoAP) is a specialized web | |||
| transfer protocol for use with constrained nodes and constrained | transfer protocol for use with constrained nodes and constrained | |||
| (e.g., low-power, lossy) networks. The nodes often have 8-bit | (e.g., low-power, lossy) networks. The nodes often have 8-bit | |||
| microcontrollers with small amounts of ROM and RAM, while constrained | microcontrollers with small amounts of ROM and RAM, while constrained | |||
| networks such as 6LoWPAN often have high packet error rates and a | networks such as 6LoWPAN often have high packet error rates and a | |||
| typical throughput of 10s of kbit/s. The protocol is designed for | typical throughput of 10s of kbit/s. The protocol is designed for | |||
| machine-to-machine (M2M) applications such as smart energy and | machine-to-machine (M2M) applications such as smart energy and | |||
| building automation. | building automation. | |||
| CoAP provides a request/response interaction model between | CoAP provides a request/response interaction model between | |||
| application endpoints, supports built-in discovery of services and | application endpoints, supports built-in discovery of services and | |||
| resources, and includes key concepts of the Web such as URIs and | resources, and includes key concepts of the Web such as URIs and | |||
| Internet media types. CoAP easily interfaces with HTTP for | Internet media types. CoAP is designed to easily interface with HTTP | |||
| integration with the Web while meeting specialized requirements such | for integration with the Web while meeting specialized requirements | |||
| as multicast support, very low overhead and simplicity for | such as multicast support, very low overhead and simplicity for | |||
| constrained environments. | constrained environments. | |||
| Status of this Memo | Status of This Memo | |||
| This Internet-Draft is submitted in full conformance with the | This Internet-Draft is submitted in full conformance with the | |||
| provisions of BCP 78 and BCP 79. | provisions of BCP 78 and BCP 79. | |||
| Internet-Drafts are working documents of the Internet Engineering | Internet-Drafts are working documents of the Internet Engineering | |||
| Task Force (IETF). Note that other groups may also distribute | Task Force (IETF). Note that other groups may also distribute | |||
| working documents as Internet-Drafts. The list of current Internet- | working documents as Internet-Drafts. The list of current Internet- | |||
| Drafts is at http://datatracker.ietf.org/drafts/current/. | Drafts is at http://datatracker.ietf.org/drafts/current/. | |||
| Internet-Drafts are draft documents valid for a maximum of six months | Internet-Drafts are draft documents valid for a maximum of six months | |||
| and may be updated, replaced, or obsoleted by other documents at any | and may be updated, replaced, or obsoleted by other documents at any | |||
| time. It is inappropriate to use Internet-Drafts as reference | time. It is inappropriate to use Internet-Drafts as reference | |||
| material or to cite them other than as "work in progress." | material or to cite them other than as "work in progress." | |||
| This Internet-Draft will expire on October 16, 2013. | This Internet-Draft will expire on December 30, 2013. | |||
| Copyright Notice | Copyright Notice | |||
| Copyright (c) 2013 IETF Trust and the persons identified as the | Copyright (c) 2013 IETF Trust and the persons identified as the | |||
| document authors. All rights reserved. | document authors. All rights reserved. | |||
| This document is subject to BCP 78 and the IETF Trust's Legal | This document is subject to BCP 78 and the IETF Trust's Legal | |||
| Provisions Relating to IETF Documents | Provisions Relating to IETF Documents | |||
| (http://trustee.ietf.org/license-info) in effect on the date of | (http://trustee.ietf.org/license-info) in effect on the date of | |||
| publication of this document. Please review these documents | publication of this document. Please review these documents | |||
| carefully, as they describe your rights and restrictions with respect | carefully, as they describe your rights and restrictions with respect | |||
| to this document. Code Components extracted from this document must | to this document. Code Components extracted from this document must | |||
| include Simplified BSD License text as described in Section 4.e of | include Simplified BSD License text as described in Section 4.e of | |||
| the Trust Legal Provisions and are provided without warranty as | the Trust Legal Provisions and are provided without warranty as | |||
| described in the Simplified BSD License. | described in the Simplified BSD License. | |||
| Table of Contents | Table of Contents | |||
| 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 5 | 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 5 | |||
| 1.1. Features . . . . . . . . . . . . . . . . . . . . . . . . 5 | 1.1. Features . . . . . . . . . . . . . . . . . . . . . . . . 5 | |||
| 1.2. Terminology . . . . . . . . . . . . . . . . . . . . . . . 6 | 1.2. Terminology . . . . . . . . . . . . . . . . . . . . . . . 6 | |||
| 2. Constrained Application Protocol . . . . . . . . . . . . . . 9 | 2. Constrained Application Protocol . . . . . . . . . . . . . . 9 | |||
| 2.1. Messaging Model . . . . . . . . . . . . . . . . . . . . . 10 | 2.1. Messaging Model . . . . . . . . . . . . . . . . . . . . . 10 | |||
| 2.2. Request/Response Model . . . . . . . . . . . . . . . . . 11 | 2.2. Request/Response Model . . . . . . . . . . . . . . . . . 12 | |||
| 2.3. Intermediaries and Caching . . . . . . . . . . . . . . . 14 | 2.3. Intermediaries and Caching . . . . . . . . . . . . . . . 14 | |||
| 2.4. Resource Discovery . . . . . . . . . . . . . . . . . . . 14 | 2.4. Resource Discovery . . . . . . . . . . . . . . . . . . . 15 | |||
| 3. Message Format . . . . . . . . . . . . . . . . . . . . . . . 15 | 3. Message Format . . . . . . . . . . . . . . . . . . . . . . . 15 | |||
| 3.1. Option Format . . . . . . . . . . . . . . . . . . . . . . 16 | 3.1. Option Format . . . . . . . . . . . . . . . . . . . . . . 17 | |||
| 3.2. Option Value Formats . . . . . . . . . . . . . . . . . . 18 | 3.2. Option Value Formats . . . . . . . . . . . . . . . . . . 19 | |||
| 4. Message Transmission . . . . . . . . . . . . . . . . . . . . 19 | 4. Message Transmission . . . . . . . . . . . . . . . . . . . . 20 | |||
| 4.1. Messages and Endpoints . . . . . . . . . . . . . . . . . 20 | 4.1. Messages and Endpoints . . . . . . . . . . . . . . . . . 20 | |||
| 4.2. Messages Transmitted Reliably . . . . . . . . . . . . . . 20 | 4.2. Messages Transmitted Reliably . . . . . . . . . . . . . . 20 | |||
| 4.3. Messages Transmitted Without Reliability . . . . . . . . 21 | 4.3. Messages Transmitted Without Reliability . . . . . . . . 22 | |||
| 4.4. Message Correlation . . . . . . . . . . . . . . . . . . . 22 | 4.4. Message Correlation . . . . . . . . . . . . . . . . . . . 23 | |||
| 4.5. Message Deduplication . . . . . . . . . . . . . . . . . . 22 | 4.5. Message Deduplication . . . . . . . . . . . . . . . . . . 24 | |||
| 4.6. Message Size . . . . . . . . . . . . . . . . . . . . . . 23 | 4.6. Message Size . . . . . . . . . . . . . . . . . . . . . . 24 | |||
| 4.7. Congestion Control . . . . . . . . . . . . . . . . . . . 24 | 4.7. Congestion Control . . . . . . . . . . . . . . . . . . . 25 | |||
| 4.8. Transmission Parameters . . . . . . . . . . . . . . . . . 25 | 4.8. Transmission Parameters . . . . . . . . . . . . . . . . . 26 | |||
| 4.8.1. Changing The Parameters . . . . . . . . . . . . . . . 25 | 4.8.1. Changing The Parameters . . . . . . . . . . . . . . . 27 | |||
| 4.8.2. Time Values derived from Transmission Parameters . . 26 | 4.8.2. Time Values derived from Transmission Parameters . . 28 | |||
| 5. Request/Response Semantics . . . . . . . . . . . . . . . . . 28 | 5. Request/Response Semantics . . . . . . . . . . . . . . . . . 30 | |||
| 5.1. Requests . . . . . . . . . . . . . . . . . . . . . . . . 29 | 5.1. Requests . . . . . . . . . . . . . . . . . . . . . . . . 30 | |||
| 5.2. Responses . . . . . . . . . . . . . . . . . . . . . . . . 29 | 5.2. Responses . . . . . . . . . . . . . . . . . . . . . . . . 30 | |||
| 5.2.1. Piggy-backed . . . . . . . . . . . . . . . . . . . . 30 | 5.2.1. Piggy-backed . . . . . . . . . . . . . . . . . . . . 32 | |||
| 5.2.2. Separate . . . . . . . . . . . . . . . . . . . . . . 31 | 5.2.2. Separate . . . . . . . . . . . . . . . . . . . . . . 32 | |||
| 5.2.3. Non-confirmable . . . . . . . . . . . . . . . . . . . 32 | 5.2.3. Non-confirmable . . . . . . . . . . . . . . . . . . . 33 | |||
| 5.3. Request/Response Matching . . . . . . . . . . . . . . . . 32 | 5.3. Request/Response Matching . . . . . . . . . . . . . . . . 33 | |||
| 5.3.1. Token . . . . . . . . . . . . . . . . . . . . . . . . 32 | 5.3.1. Token . . . . . . . . . . . . . . . . . . . . . . . . 34 | |||
| 5.3.2. Request/Response Matching Rules . . . . . . . . . . . 33 | 5.3.2. Request/Response Matching Rules . . . . . . . . . . . 35 | |||
| 5.4. Options . . . . . . . . . . . . . . . . . . . . . . . . . 33 | ||||
| 5.4.1. Critical/Elective . . . . . . . . . . . . . . . . . . 34 | 5.4. Options . . . . . . . . . . . . . . . . . . . . . . . . . 35 | |||
| 5.4.2. Proxy Unsafe/Safe and Cache-Key . . . . . . . . . . . 35 | 5.4.1. Critical/Elective . . . . . . . . . . . . . . . . . . 36 | |||
| 5.4.3. Length . . . . . . . . . . . . . . . . . . . . . . . 36 | 5.4.2. Proxy Unsafe/Safe-to-Forward and NoCacheKey . . . . . 37 | |||
| 5.4.4. Default Values . . . . . . . . . . . . . . . . . . . 36 | 5.4.3. Length . . . . . . . . . . . . . . . . . . . . . . . 38 | |||
| 5.4.5. Repeatable Options . . . . . . . . . . . . . . . . . 36 | 5.4.4. Default Values . . . . . . . . . . . . . . . . . . . 38 | |||
| 5.4.6. Option Numbers . . . . . . . . . . . . . . . . . . . 36 | 5.4.5. Repeatable Options . . . . . . . . . . . . . . . . . 38 | |||
| 5.5. Payloads and Representations . . . . . . . . . . . . . . 37 | 5.4.6. Option Numbers . . . . . . . . . . . . . . . . . . . 38 | |||
| 5.5.1. Representation . . . . . . . . . . . . . . . . . . . 37 | 5.5. Payloads and Representations . . . . . . . . . . . . . . 39 | |||
| 5.5.2. Diagnostic Payload . . . . . . . . . . . . . . . . . 38 | 5.5.1. Representation . . . . . . . . . . . . . . . . . . . 39 | |||
| 5.5.3. Selected Representation . . . . . . . . . . . . . . . 38 | 5.5.2. Diagnostic Payload . . . . . . . . . . . . . . . . . 40 | |||
| 5.5.4. Content Negotiation . . . . . . . . . . . . . . . . . 39 | 5.5.3. Selected Representation . . . . . . . . . . . . . . . 40 | |||
| 5.6. Caching . . . . . . . . . . . . . . . . . . . . . . . . . 39 | 5.5.4. Content Negotiation . . . . . . . . . . . . . . . . . 40 | |||
| 5.6.1. Freshness Model . . . . . . . . . . . . . . . . . . . 40 | 5.6. Caching . . . . . . . . . . . . . . . . . . . . . . . . . 41 | |||
| 5.6.2. Validation Model . . . . . . . . . . . . . . . . . . 40 | 5.6.1. Freshness Model . . . . . . . . . . . . . . . . . . . 42 | |||
| 5.7. Proxying . . . . . . . . . . . . . . . . . . . . . . . . 40 | 5.6.2. Validation Model . . . . . . . . . . . . . . . . . . 42 | |||
| 5.7.1. Proxy Operation . . . . . . . . . . . . . . . . . . . 41 | 5.7. Proxying . . . . . . . . . . . . . . . . . . . . . . . . 43 | |||
| 5.7.2. Forward-Proxies . . . . . . . . . . . . . . . . . . . 42 | 5.7.1. Proxy Operation . . . . . . . . . . . . . . . . . . . 43 | |||
| 5.7.3. Reverse-Proxies . . . . . . . . . . . . . . . . . . . 43 | 5.7.2. Forward-Proxies . . . . . . . . . . . . . . . . . . . 45 | |||
| 5.8. Method Definitions . . . . . . . . . . . . . . . . . . . 43 | 5.7.3. Reverse-Proxies . . . . . . . . . . . . . . . . . . . 45 | |||
| 5.8.1. GET . . . . . . . . . . . . . . . . . . . . . . . . . 44 | 5.8. Method Definitions . . . . . . . . . . . . . . . . . . . 46 | |||
| 5.8.2. POST . . . . . . . . . . . . . . . . . . . . . . . . 44 | 5.8.1. GET . . . . . . . . . . . . . . . . . . . . . . . . . 46 | |||
| 5.8.3. PUT . . . . . . . . . . . . . . . . . . . . . . . . . 44 | 5.8.2. POST . . . . . . . . . . . . . . . . . . . . . . . . 46 | |||
| 5.8.4. DELETE . . . . . . . . . . . . . . . . . . . . . . . 45 | 5.8.3. PUT . . . . . . . . . . . . . . . . . . . . . . . . . 46 | |||
| 5.9. Response Code Definitions . . . . . . . . . . . . . . . . 45 | 5.8.4. DELETE . . . . . . . . . . . . . . . . . . . . . . . 47 | |||
| 5.9.1. Success 2.xx . . . . . . . . . . . . . . . . . . . . 45 | 5.9. Response Code Definitions . . . . . . . . . . . . . . . . 47 | |||
| 5.9.2. Client Error 4.xx . . . . . . . . . . . . . . . . . . 46 | 5.9.1. Success 2.xx . . . . . . . . . . . . . . . . . . . . 47 | |||
| 5.9.3. Server Error 5.xx . . . . . . . . . . . . . . . . . . 48 | 5.9.2. Client Error 4.xx . . . . . . . . . . . . . . . . . . 49 | |||
| 5.10. Option Definitions . . . . . . . . . . . . . . . . . . . 48 | 5.9.3. Server Error 5.xx . . . . . . . . . . . . . . . . . . 50 | |||
| 5.10.1. Uri-Host, Uri-Port, Uri-Path and Uri-Query . . . . . 49 | 5.10. Option Definitions . . . . . . . . . . . . . . . . . . . 51 | |||
| 5.10.2. Proxy-Uri and Proxy-Scheme . . . . . . . . . . . . . 50 | 5.10.1. Uri-Host, Uri-Port, Uri-Path and Uri-Query . . . . . 52 | |||
| 5.10.3. Content-Format . . . . . . . . . . . . . . . . . . . 51 | 5.10.2. Proxy-Uri and Proxy-Scheme . . . . . . . . . . . . . 53 | |||
| 5.10.4. Accept . . . . . . . . . . . . . . . . . . . . . . . 51 | 5.10.3. Content-Format . . . . . . . . . . . . . . . . . . . 53 | |||
| 5.10.5. Max-Age . . . . . . . . . . . . . . . . . . . . . . . 51 | 5.10.4. Accept . . . . . . . . . . . . . . . . . . . . . . . 54 | |||
| 5.10.6. ETag . . . . . . . . . . . . . . . . . . . . . . . . 52 | 5.10.5. Max-Age . . . . . . . . . . . . . . . . . . . . . . 54 | |||
| 5.10.7. Location-Path and Location-Query . . . . . . . . . . 53 | 5.10.6. ETag . . . . . . . . . . . . . . . . . . . . . . . . 54 | |||
| 5.10.8. Conditional Request Options . . . . . . . . . . . . . 54 | 5.10.7. Location-Path and Location-Query . . . . . . . . . . 55 | |||
| 6. CoAP URIs . . . . . . . . . . . . . . . . . . . . . . . . . . 55 | 5.10.8. Conditional Request Options . . . . . . . . . . . . 56 | |||
| 6.1. coap URI Scheme . . . . . . . . . . . . . . . . . . . . . 55 | 5.10.9. Size1 Option . . . . . . . . . . . . . . . . . . . . 57 | |||
| 6.2. coaps URI Scheme . . . . . . . . . . . . . . . . . . . . 56 | 6. CoAP URIs . . . . . . . . . . . . . . . . . . . . . . . . . . 57 | |||
| 6.3. Normalization and Comparison Rules . . . . . . . . . . . 56 | 6.1. coap URI Scheme . . . . . . . . . . . . . . . . . . . . . 58 | |||
| 6.4. Decomposing URIs into Options . . . . . . . . . . . . . . 57 | 6.2. coaps URI Scheme . . . . . . . . . . . . . . . . . . . . 59 | |||
| 6.5. Composing URIs from Options . . . . . . . . . . . . . . . 58 | 6.3. Normalization and Comparison Rules . . . . . . . . . . . 59 | |||
| 7. Discovery . . . . . . . . . . . . . . . . . . . . . . . . . . 59 | 6.4. Decomposing URIs into Options . . . . . . . . . . . . . . 60 | |||
| 7.1. Service Discovery . . . . . . . . . . . . . . . . . . . . 59 | 6.5. Composing URIs from Options . . . . . . . . . . . . . . . 61 | |||
| 7.2. Resource Discovery . . . . . . . . . . . . . . . . . . . 60 | 7. Discovery . . . . . . . . . . . . . . . . . . . . . . . . . . 62 | |||
| 7.2.1. 'ct' Attribute . . . . . . . . . . . . . . . . . . . 60 | 7.1. Service Discovery . . . . . . . . . . . . . . . . . . . . 62 | |||
| 8. Multicast CoAP . . . . . . . . . . . . . . . . . . . . . . . 61 | 7.2. Resource Discovery . . . . . . . . . . . . . . . . . . . 63 | |||
| 8.1. Messaging Layer . . . . . . . . . . . . . . . . . . . . . 61 | 7.2.1. 'ct' Attribute . . . . . . . . . . . . . . . . . . . 63 | |||
| 8.2. Request/Response Layer . . . . . . . . . . . . . . . . . 61 | ||||
| 8.2.1. Caching . . . . . . . . . . . . . . . . . . . . . . . 62 | 8. Multicast CoAP . . . . . . . . . . . . . . . . . . . . . . . 64 | |||
| 8.2.2. Proxying . . . . . . . . . . . . . . . . . . . . . . 63 | 8.1. Messaging Layer . . . . . . . . . . . . . . . . . . . . . 64 | |||
| 9. Securing CoAP . . . . . . . . . . . . . . . . . . . . . . . . 63 | 8.2. Request/Response Layer . . . . . . . . . . . . . . . . . 65 | |||
| 9.1. DTLS-secured CoAP . . . . . . . . . . . . . . . . . . . . 64 | 8.2.1. Caching . . . . . . . . . . . . . . . . . . . . . . . 66 | |||
| 9.1.1. Messaging Layer . . . . . . . . . . . . . . . . . . . 66 | 8.2.2. Proxying . . . . . . . . . . . . . . . . . . . . . . 66 | |||
| 9.1.2. Request/Response Layer . . . . . . . . . . . . . . . 66 | 9. Securing CoAP . . . . . . . . . . . . . . . . . . . . . . . . 66 | |||
| 9.1.3. Endpoint Identity . . . . . . . . . . . . . . . . . . 66 | 9.1. DTLS-secured CoAP . . . . . . . . . . . . . . . . . . . . 68 | |||
| 10. Cross-Protocol Proxying between CoAP and HTTP . . . . . . . . 68 | 9.1.1. Messaging Layer . . . . . . . . . . . . . . . . . . . 69 | |||
| 10.1. CoAP-HTTP Proxying . . . . . . . . . . . . . . . . . . . 69 | 9.1.2. Request/Response Layer . . . . . . . . . . . . . . . 69 | |||
| 10.1.1. GET . . . . . . . . . . . . . . . . . . . . . . . . . 70 | 9.1.3. Endpoint Identity . . . . . . . . . . . . . . . . . . 70 | |||
| 10.1.2. PUT . . . . . . . . . . . . . . . . . . . . . . . . . 70 | 10. Cross-Protocol Proxying between CoAP and HTTP . . . . . . . . 73 | |||
| 10.1.3. DELETE . . . . . . . . . . . . . . . . . . . . . . . 71 | 10.1. CoAP-HTTP Proxying . . . . . . . . . . . . . . . . . . . 74 | |||
| 10.1.4. POST . . . . . . . . . . . . . . . . . . . . . . . . 71 | 10.1.1. GET . . . . . . . . . . . . . . . . . . . . . . . . 74 | |||
| 10.2. HTTP-CoAP Proxying . . . . . . . . . . . . . . . . . . . 71 | 10.1.2. PUT . . . . . . . . . . . . . . . . . . . . . . . . 75 | |||
| 10.2.1. OPTIONS and TRACE . . . . . . . . . . . . . . . . . . 72 | 10.1.3. DELETE . . . . . . . . . . . . . . . . . . . . . . . 75 | |||
| 10.2.2. GET . . . . . . . . . . . . . . . . . . . . . . . . . 72 | 10.1.4. POST . . . . . . . . . . . . . . . . . . . . . . . . 75 | |||
| 10.2.3. HEAD . . . . . . . . . . . . . . . . . . . . . . . . 72 | 10.2. HTTP-CoAP Proxying . . . . . . . . . . . . . . . . . . . 76 | |||
| 10.2.4. POST . . . . . . . . . . . . . . . . . . . . . . . . 73 | 10.2.1. OPTIONS and TRACE . . . . . . . . . . . . . . . . . 76 | |||
| 10.2.5. PUT . . . . . . . . . . . . . . . . . . . . . . . . . 73 | 10.2.2. GET . . . . . . . . . . . . . . . . . . . . . . . . 76 | |||
| 10.2.6. DELETE . . . . . . . . . . . . . . . . . . . . . . . 73 | 10.2.3. HEAD . . . . . . . . . . . . . . . . . . . . . . . . 77 | |||
| 10.2.7. CONNECT . . . . . . . . . . . . . . . . . . . . . . . 73 | 10.2.4. POST . . . . . . . . . . . . . . . . . . . . . . . . 77 | |||
| 11. Security Considerations . . . . . . . . . . . . . . . . . . . 74 | 10.2.5. PUT . . . . . . . . . . . . . . . . . . . . . . . . 78 | |||
| 11.1. Protocol Parsing, Processing URIs . . . . . . . . . . . . 74 | 10.2.6. DELETE . . . . . . . . . . . . . . . . . . . . . . . 78 | |||
| 11.2. Proxying and Caching . . . . . . . . . . . . . . . . . . 74 | 10.2.7. CONNECT . . . . . . . . . . . . . . . . . . . . . . 78 | |||
| 11.3. Risk of amplification . . . . . . . . . . . . . . . . . . 75 | 11. Security Considerations . . . . . . . . . . . . . . . . . . . 78 | |||
| 11.4. IP Address Spoofing Attacks . . . . . . . . . . . . . . . 76 | 11.1. Protocol Parsing, Processing URIs . . . . . . . . . . . 78 | |||
| 11.5. Cross-Protocol Attacks . . . . . . . . . . . . . . . . . 77 | 11.2. Proxying and Caching . . . . . . . . . . . . . . . . . . 79 | |||
| 12. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 79 | 11.3. Risk of amplification . . . . . . . . . . . . . . . . . 80 | |||
| 12.1. CoAP Code Registry . . . . . . . . . . . . . . . . . . . 79 | 11.4. IP Address Spoofing Attacks . . . . . . . . . . . . . . 81 | |||
| 12.1.1. Method Codes . . . . . . . . . . . . . . . . . . . . 80 | 11.5. Cross-Protocol Attacks . . . . . . . . . . . . . . . . . 82 | |||
| 12.1.2. Response Codes . . . . . . . . . . . . . . . . . . . 81 | 11.6. Constrained node considerations . . . . . . . . . . . . 84 | |||
| 12.2. Option Number Registry . . . . . . . . . . . . . . . . . 82 | 12. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 84 | |||
| 12.3. Content-Format Registry . . . . . . . . . . . . . . . . . 84 | 12.1. CoAP Code Registries . . . . . . . . . . . . . . . . . . 84 | |||
| 12.4. URI Scheme Registration . . . . . . . . . . . . . . . . . 85 | 12.1.1. Method Codes . . . . . . . . . . . . . . . . . . . . 85 | |||
| 12.5. Secure URI Scheme Registration . . . . . . . . . . . . . 86 | 12.1.2. Response Codes . . . . . . . . . . . . . . . . . . . 85 | |||
| 12.6. Service Name and Port Number Registration . . . . . . . . 87 | 12.2. Option Number Registry . . . . . . . . . . . . . . . . . 87 | |||
| 12.7. Secure Service Name and Port Number Registration . . . . 88 | 12.3. Content-Format Registry . . . . . . . . . . . . . . . . 89 | |||
| 12.8. Multicast Address Registration . . . . . . . . . . . . . 89 | 12.4. URI Scheme Registration . . . . . . . . . . . . . . . . 90 | |||
| 13. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 89 | 12.5. Secure URI Scheme Registration . . . . . . . . . . . . . 91 | |||
| 14. References . . . . . . . . . . . . . . . . . . . . . . . . . 90 | 12.6. Service Name and Port Number Registration . . . . . . . 92 | |||
| 14.1. Normative References . . . . . . . . . . . . . . . . . . 90 | 12.7. Secure Service Name and Port Number Registration . . . . 93 | |||
| 14.2. Informative References . . . . . . . . . . . . . . . . . 92 | 12.8. Multicast Address Registration . . . . . . . . . . . . . 94 | |||
| Appendix A. Examples . . . . . . . . . . . . . . . . . . . . . . 94 | 13. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 94 | |||
| Appendix B. URI Examples . . . . . . . . . . . . . . . . . . . . 100 | 14. References . . . . . . . . . . . . . . . . . . . . . . . . . 95 | |||
| Appendix C. Changelog . . . . . . . . . . . . . . . . . . . . . 102 | 14.1. Normative References . . . . . . . . . . . . . . . . . . 95 | |||
| Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 111 | 14.2. Informative References . . . . . . . . . . . . . . . . . 97 | |||
| Appendix A. Examples . . . . . . . . . . . . . . . . . . . . . . 100 | ||||
| Appendix B. URI Examples . . . . . . . . . . . . . . . . . . . . 105 | ||||
| Appendix C. Changelog . . . . . . . . . . . . . . . . . . . . . 107 | ||||
| Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 117 | ||||
| 1. Introduction | 1. Introduction | |||
| The use of web services (web APIs) on the Internet has become | The use of web services (web APIs) on the Internet has become | |||
| ubiquitous in most applications, and depends on the fundamental | ubiquitous in most applications, and depends on the fundamental | |||
| Representational State Transfer [REST] architecture of the web. | Representational State Transfer [REST] architecture of the web. | |||
| The Constrained RESTful Environments (CoRE) work aims at realizing | The Constrained RESTful Environments (CoRE) work aims at realizing | |||
| the REST architecture in a suitable form for the most constrained | the REST architecture in a suitable form for the most constrained | |||
| nodes (e.g. 8-bit microcontrollers with limited RAM and ROM) and | nodes (e.g. 8-bit microcontrollers with limited RAM and ROM) and | |||
| networks (e.g. 6LoWPAN, [RFC4944]). Constrained networks like | networks (e.g. 6LoWPAN, [RFC4944]). Constrained networks such as | |||
| 6LoWPAN support the expensive fragmentation of IPv6 packets into | 6LoWPAN support the fragmentation of IPv6 packets into small link- | |||
| small link-layer frames. One design goal of CoAP has been to keep | layer frames, however incurring significant reduction in packet | |||
| message overhead small, thus limiting the use of fragmentation. | delivery probability. One design goal of CoAP has been to keep | |||
| message overhead small, thus limiting the need for fragmentation. | ||||
| One of the main goals of CoAP is to design a generic web protocol for | One of the main goals of CoAP is to design a generic web protocol for | |||
| the special requirements of this constrained environment, especially | the special requirements of this constrained environment, especially | |||
| considering energy, building automation and other machine-to-machine | considering energy, building automation and other machine-to-machine | |||
| (M2M) applications. The goal of CoAP is not to blindly compress HTTP | (M2M) applications. The goal of CoAP is not to blindly compress HTTP | |||
| [RFC2616], but rather to realize a subset of REST common with HTTP | [RFC2616], but rather to realize a subset of REST common with HTTP | |||
| but optimized for M2M applications. Although CoAP could be used for | but optimized for M2M applications. Although CoAP could be used for | |||
| compressing simple HTTP interfaces, it more importantly also offers | refashioning simple HTTP interfaces into a more compact protocol, it | |||
| features for M2M such as built-in discovery, multicast support and | more importantly also offers features for M2M such as built-in | |||
| asynchronous message exchanges. | discovery, multicast support and asynchronous message exchanges. | |||
| This document specifies the Constrained Application Protocol (CoAP), | This document specifies the Constrained Application Protocol (CoAP), | |||
| which easily translates to HTTP for integration with the existing web | which easily translates to HTTP for integration with the existing web | |||
| while meeting specialized requirements such as multicast support, | while meeting specialized requirements such as multicast support, | |||
| very low overhead and simplicity for constrained environments and M2M | very low overhead and simplicity for constrained environments and M2M | |||
| applications. | applications. | |||
| 1.1. Features | 1.1. Features | |||
| CoAP has the following main features: | CoAP has the following main features: | |||
| skipping to change at page 7, line 42 ¶ | skipping to change at page 7, line 42 ¶ | |||
| application-layer protocols. | application-layer protocols. | |||
| Reverse-Proxy | Reverse-Proxy | |||
| A "reverse-proxy" is an endpoint that stands in for one or more | A "reverse-proxy" is an endpoint that stands in for one or more | |||
| other server(s) and satisfies requests on behalf of these, doing | other server(s) and satisfies requests on behalf of these, doing | |||
| any necessary translations. Unlike a forward-proxy, the client | any necessary translations. Unlike a forward-proxy, the client | |||
| may not be aware that it is communicating with a reverse-proxy; a | may not be aware that it is communicating with a reverse-proxy; a | |||
| reverse-proxy receives requests as if it was the origin server for | reverse-proxy receives requests as if it was the origin server for | |||
| the target resource. | the target resource. | |||
| CoAP-to-CoAP Proxy | ||||
| A proxy that maps from a CoAP request to a CoAP request, i.e. | ||||
| uses the CoAP protocol both on the server and the client side. | ||||
| Contrast to cross-proxy. | ||||
| Cross-Proxy | Cross-Proxy | |||
| A cross-protocol proxy, or "cross-proxy" for short, is a proxy | A cross-protocol proxy, or "cross-proxy" for short, is a proxy | |||
| that translates between different protocols, such as a CoAP-to- | that translates between different protocols, such as a CoAP-to- | |||
| HTTP proxy or an HTTP-to-CoAP proxy. While this specification | HTTP proxy or an HTTP-to-CoAP proxy. While this specification | |||
| makes very specific demands of CoAP-to-CoAP proxies, there is more | makes very specific demands of CoAP-to-CoAP proxies, there is more | |||
| variation possible in cross-proxies. | variation possible in cross-proxies. | |||
| Confirmable Message | Confirmable Message | |||
| Some messages require an acknowledgement. These messages are | Some messages require an acknowledgement. These messages are | |||
| called "Confirmable". When no packets are lost, each Confirmable | called "Confirmable". When no packets are lost, each Confirmable | |||
| message elicits exactly one return message of type Acknowledgement | message elicits exactly one return message of type Acknowledgement | |||
| or type Reset. | or type Reset. | |||
| Non-confirmable Message | Non-confirmable Message | |||
| Some other messages do not require an acknowledgement. This is | Some other messages do not require an acknowledgement. This is | |||
| particularly true for messages that are repeated regularly for | particularly true for messages that are repeated regularly for | |||
| application requirements, such as repeated readings from a sensor. | application requirements, such as repeated readings from a sensor. | |||
| Acknowledgement Message | Acknowledgement Message | |||
| An Acknowledgement message acknowledges that a specific | An Acknowledgement message acknowledges that a specific | |||
| Confirmable Message arrived. It does not indicate success or | Confirmable message arrived. By itself, an Acknowledgement | |||
| failure of any encapsulated request. | message does not indicate success or failure of any request | |||
| encapsulated in the Confirmable message, but the Acknowledgement | ||||
| message may also carry a Piggy-Backed Response (q.v.). | ||||
| Reset Message | Reset Message | |||
| A Reset message indicates that a specific message (Confirmable or | A Reset message indicates that a specific message (Confirmable or | |||
| Non-confirmable) was received, but some context is missing to | Non-confirmable) was received, but some context is missing to | |||
| properly process it. This condition is usually caused when the | properly process it. This condition is usually caused when the | |||
| receiving node has rebooted and has forgotten some state that | receiving node has rebooted and has forgotten some state that | |||
| would be required to interpret the message. Provoking a Reset | would be required to interpret the message. Provoking a Reset | |||
| message (e.g., by sending an empty Confirmable message) is also | message (e.g., by sending an Empty Confirmable message) is also | |||
| useful as an inexpensive check of the liveness of an endpoint | useful as an inexpensive check of the liveness of an endpoint | |||
| ("CoAP ping"). | ("CoAP ping"). | |||
| Piggy-backed Response | Piggy-backed Response | |||
| A Piggy-backed Response is included right in a CoAP | A Piggy-backed Response is included right in a CoAP | |||
| Acknowledgement (ACK) message that is sent to acknowledge receipt | Acknowledgement (ACK) message that is sent to acknowledge receipt | |||
| of the Request for this Response (Section 5.2.1). | of the Request for this Response (Section 5.2.1). | |||
| Separate Response | Separate Response | |||
| When a Confirmable message carrying a Request is acknowledged with | When a Confirmable message carrying a Request is acknowledged with | |||
| an empty message (e.g., because the server doesn't have the answer | an Empty message (e.g., because the server doesn't have the answer | |||
| right away), a Separate Response is sent in a separate message | right away), a Separate Response is sent in a separate message | |||
| exchange (Section 5.2.2). | exchange (Section 5.2.2). | |||
| Empty Message | ||||
| A message with a Code of 0.00; neither a request nor a response. | ||||
| An Empty message only contains the four-byte header. | ||||
| Critical Option | Critical Option | |||
| An option that would need to be understood by the endpoint | An option that would need to be understood by the endpoint | |||
| receiving the message in order to properly process the message | ultimately receiving the message in order to properly process the | |||
| (Section 5.4.1). Note that the implementation of critical options | message (Section 5.4.1). Note that the implementation of critical | |||
| is, as the name "Option" implies, generally optional: unsupported | options is, as the name "Option" implies, generally optional: | |||
| critical options lead to an error response or summary rejection of | ||||
| the message. | unsupported critical options lead to an error response or summary | |||
| rejection of the message. | ||||
| Elective Option | Elective Option | |||
| An option that is intended to be ignored by an endpoint that does | An option that is intended to be ignored by an endpoint that does | |||
| not understand it. Processing the message even without | not understand it. Processing the message even without | |||
| understanding the option is acceptable (Section 5.4.1). | understanding the option is acceptable (Section 5.4.1). | |||
| Unsafe Option | Unsafe Option | |||
| An option that would need to be understood by a proxy receiving | An option that would need to be understood by a proxy receiving | |||
| the message in order to safely forward the message | the message in order to safely forward the message | |||
| (Section 5.4.2). | (Section 5.4.2). Not every critical option is an unsafe option. | |||
| Safe Option | Safe-to-Forward Option | |||
| An option that is intended to be safe for forwarding by a proxy | An option that is intended to be safe for forwarding by a proxy | |||
| that does not understand it. Forwarding the message even without | that does not understand it. Forwarding the message even without | |||
| understanding the option is acceptable (Section 5.4.2). | understanding the option is acceptable (Section 5.4.2). | |||
| Resource Discovery | Resource Discovery | |||
| The process where a CoAP client queries a server for its list of | The process where a CoAP client queries a server for its list of | |||
| hosted resources (i.e., links, Section 7). | hosted resources (i.e., links, Section 7). | |||
| Content-Format | Content-Format | |||
| The combination of an Internet media type, potentially with | The combination of an Internet media type, potentially with | |||
| specific parameters given, and a content-coding (which is often | specific parameters given, and a content-coding (which is often | |||
| the identity content-coding), identified by a numeric identifier | the identity content-coding), identified by a numeric identifier | |||
| defined by the CoAP Content-Format registry. When the focus is | defined by the CoAP Content-Format Registry. When the focus is | |||
| less on the numeric identifier than on the combination of these | less on the numeric identifier than on the combination of these | |||
| characteristics of a resource representation, this is also called | characteristics of a resource representation, this is also called | |||
| "representation format". | "representation format". | |||
| Additional terminology for constrained nodes and constrained node | Additional terminology for constrained nodes and constrained node | |||
| networks can be found in [I-D.ietf-lwig-terminology]. | networks can be found in [I-D.ietf-lwig-terminology]. | |||
| In this specification, the term "byte" is used in its now customary | In this specification, the term "byte" is used in its now customary | |||
| sense as a synonym for "octet". | sense as a synonym for "octet". | |||
| skipping to change at page 10, line 22 ¶ | skipping to change at page 10, line 29 ¶ | |||
| confirmable messages, and responses can be carried in these as well | confirmable messages, and responses can be carried in these as well | |||
| as piggy-backed in Acknowledgement messages. | as piggy-backed in Acknowledgement messages. | |||
| One could think of CoAP logically as using a two-layer approach, a | One could think of CoAP logically as using a two-layer approach, a | |||
| CoAP messaging layer used to deal with UDP and the asynchronous | CoAP messaging layer used to deal with UDP and the asynchronous | |||
| nature of the interactions, and the request/response interactions | nature of the interactions, and the request/response interactions | |||
| using Method and Response codes (see Figure 1). CoAP is however a | using Method and Response codes (see Figure 1). CoAP is however a | |||
| single protocol, with messaging and request/response just features of | single protocol, with messaging and request/response just features of | |||
| the CoAP header. | the CoAP header. | |||
| +----------------------+ | +----------------------+ | |||
| | Application | | | Application | | |||
| +----------------------+ | +----------------------+ | |||
| +----------------------+ \ | +----------------------+ \ | |||
| | Requests/Responses | | | | Requests/Responses | | | |||
| |----------------------| | CoAP | |----------------------| | CoAP | |||
| | Messages | | | | Messages | | | |||
| +----------------------+ / | +----------------------+ / | |||
| +----------------------+ | +----------------------+ | |||
| | UDP | | | UDP | | |||
| +----------------------+ | +----------------------+ | |||
| Figure 1: Abstract layering of CoAP | Figure 1: Abstract layering of CoAP | |||
| 2.1. Messaging Model | 2.1. Messaging Model | |||
| The CoAP messaging model is based on the exchange of messages over | The CoAP messaging model is based on the exchange of messages over | |||
| UDP between endpoints. | UDP between endpoints. | |||
| CoAP uses a short fixed-length binary header (4 bytes) that may be | CoAP uses a short fixed-length binary header (4 bytes) that may be | |||
| followed by compact binary options and a payload. This message | followed by compact binary options and a payload. This message | |||
| format is shared by requests and responses. The CoAP message format | format is shared by requests and responses. The CoAP message format | |||
| is specified in Section 3. Each message contains a Message ID used | is specified in Section 3. Each message contains a Message ID used | |||
| to detect duplicates and for optional reliability. | to detect duplicates and for optional reliability. (The Message ID | |||
| is compact; its 16-bit size enables up to about 250 messages per | ||||
| second from one endpoint to another with default protocol | ||||
| parameters.) | ||||
| Reliability is provided by marking a message as Confirmable (CON). A | Reliability is provided by marking a message as Confirmable (CON). A | |||
| Confirmable message is retransmitted using a default timeout and | Confirmable message is retransmitted using a default timeout and | |||
| exponential back-off between retransmissions, until the recipient | exponential back-off between retransmissions, until the recipient | |||
| sends an Acknowledgement message (ACK) with the same Message ID (for | sends an Acknowledgement message (ACK) with the same Message ID (in | |||
| example, 0x7d34) from the corresponding endpoint; see Figure 2. When | this example, 0x7d34) from the corresponding endpoint; see Figure 2. | |||
| a recipient is not at all able to process a Confirmable message | When a recipient is not at all able to process a Confirmable message | |||
| (i.e., not even able to provide a suitable error response), it | (i.e., not even able to provide a suitable error response), it | |||
| replies with a Reset message (RST) instead of an Acknowledgement | replies with a Reset message (RST) instead of an Acknowledgement | |||
| (ACK). | (ACK). | |||
| Client Server | Client Server | |||
| | | | | | | |||
| | CON [0x7d34] | | | CON [0x7d34] | | |||
| +----------------->| | +----------------->| | |||
| | | | | | | |||
| | ACK [0x7d34] | | | ACK [0x7d34] | | |||
| |<-----------------+ | |<-----------------+ | |||
| | | | | | | |||
| Figure 2: Reliable message transmission | Figure 2: Reliable message transmission | |||
| A message that does not require reliable transmission, for example | A message that does not require reliable transmission, for example | |||
| each single measurement out of a stream of sensor data, can be sent | each single measurement out of a stream of sensor data, can be sent | |||
| as a Non-confirmable message (NON). These are not acknowledged, but | as a Non-confirmable message (NON). These are not acknowledged, but | |||
| still have a Message ID for duplicate detection; see Figure 3. When | still have a Message ID for duplicate detection (in this example, | |||
| a recipient is not able to process a Non-confirmable message, it may | 0x01a0); see Figure 3. When a recipient is not able to process a | |||
| reply with a Reset message (RST). | Non-confirmable message, it may reply with a Reset message (RST). | |||
| Client Server | Client Server | |||
| | | | | | | |||
| | NON [0x01a0] | | | NON [0x01a0] | | |||
| +----------------->| | +----------------->| | |||
| | | | | | | |||
| Figure 3: Unreliable message transmission | Figure 3: Unreliable message transmission | |||
| See Section 4 for details of CoAP messages. | See Section 4 for details of CoAP messages. | |||
| As CoAP is based on UDP, it also supports the use of multicast IP | As CoAP runs over UDP, it also supports the use of multicast IP | |||
| destination addresses, enabling multicast CoAP requests. Section 8 | destination addresses, enabling multicast CoAP requests. Section 8 | |||
| discusses the proper use of CoAP messages with multicast addresses | discusses the proper use of CoAP messages with multicast addresses | |||
| and precautions for avoiding response congestion. | and precautions for avoiding response congestion. | |||
| Several security modes are defined for CoAP in Section 9 ranging from | Several security modes are defined for CoAP in Section 9 ranging from | |||
| no security to certificate-based security. This document specifies a | no security to certificate-based security. This document specifies a | |||
| binding to DTLS for securing the protocol; the use of IPsec with CoAP | binding to DTLS for securing the protocol; the use of IPsec with CoAP | |||
| is discussed in [I-D.bormann-core-ipsec-for-coap]. | is discussed in [I-D.bormann-core-ipsec-for-coap]. | |||
| 2.2. Request/Response Model | 2.2. Request/Response Model | |||
| CoAP request and response semantics are carried in CoAP messages, | CoAP request and response semantics are carried in CoAP messages, | |||
| which include either a Method code or Response code, respectively. | which include either a Method code or Response code, respectively. | |||
| Optional (or default) request and response information, such as the | Optional (or default) request and response information, such as the | |||
| URI and payload media type are carried as CoAP options. A Token is | URI and payload media type are carried as CoAP options. A Token is | |||
| used to match responses to requests independently from the underlying | used to match responses to requests independently from the underlying | |||
| messages (Section 5.3). | messages (Section 5.3). (Note that the Token is a concept separate | |||
| from the Message ID.) | ||||
| A request is carried in a Confirmable (CON) or Non-confirmable (NON) | A request is carried in a Confirmable (CON) or Non-confirmable (NON) | |||
| message, and if immediately available, the response to a request | message, and if immediately available, the response to a request | |||
| carried in a Confirmable message is carried in the resulting | carried in a Confirmable message is carried in the resulting | |||
| Acknowledgement (ACK) message. This is called a piggy-backed | Acknowledgement (ACK) message. This is called a piggy-backed | |||
| response, detailed in Section 5.2.1. Two examples for a basic GET | response, detailed in Section 5.2.1. (There is no need for | |||
| request with piggy-backed response are shown in Figure 4, one | separately acknowledging a piggy-backed response, as the client will | |||
| successful, one resulting in a 4.04 (Not Found) response. | retransmit the request if the Acknowledgement message carrying the | |||
| piggy-backed response is lost.) Two examples for a basic GET request | ||||
| with piggy-backed response are shown in Figure 4, one successful, one | ||||
| resulting in a 4.04 (Not Found) response. | ||||
| Client Server Client Server | Client Server Client Server | |||
| | | | | | | | | | | |||
| | CON [0xbc90] | | CON [0xbc91] | | | CON [0xbc90] | | CON [0xbc91] | | |||
| | GET /temperature | | GET /temperature | | | GET /temperature | | GET /temperature | | |||
| | (Token 0x71) | | (Token 0x72) | | | (Token 0x71) | | (Token 0x72) | | |||
| +----------------->| +----------------->| | +----------------->| +----------------->| | |||
| | | | | | | | | | | |||
| | ACK [0xbc90] | | ACK [0xbc91] | | | ACK [0xbc90] | | ACK [0xbc91] | | |||
| | 2.05 Content | | 4.04 Not Found | | | 2.05 Content | | 4.04 Not Found | | |||
| | (Token 0x71) | | (Token 0x72) | | | (Token 0x71) | | (Token 0x72) | | |||
| | "22.5 C" | | "Not found" | | | "22.5 C" | | "Not found" | | |||
| |<-----------------+ |<-----------------+ | |<-----------------+ |<-----------------+ | |||
| | | | | | | | | | | |||
| Figure 4: Two GET requests with piggy-backed responses | Figure 4: Two GET requests with piggy-backed responses | |||
| If the server is not able to respond immediately to a request carried | If the server is not able to respond immediately to a request carried | |||
| in a Confirmable message, it simply responds with an empty | in a Confirmable message, it simply responds with an Empty | |||
| Acknowledgement message so that the client can stop retransmitting | Acknowledgement message so that the client can stop retransmitting | |||
| the request. When the response is ready, the server sends it in a | the request. When the response is ready, the server sends it in a | |||
| new Confirmable message (which then in turn needs to be acknowledged | new Confirmable message (which then in turn needs to be acknowledged | |||
| by the client). This is called a separate response, as illustrated | by the client). This is called a separate response, as illustrated | |||
| in Figure 5 and described in more detail in Section 5.2.2. | in Figure 5 and described in more detail in Section 5.2.2. | |||
| Client Server | Client Server | |||
| | | | | | | |||
| | CON [0x7a10] | | | CON [0x7a10] | | |||
| | GET /temperature | | | GET /temperature | | |||
| | (Token 0x73) | | | (Token 0x73) | | |||
| +----------------->| | +----------------->| | |||
| | | | | | | |||
| | ACK [0x7a10] | | | ACK [0x7a10] | | |||
| |<-----------------+ | |<-----------------+ | |||
| | | | | | | |||
| ... Time Passes ... | ... Time Passes ... | |||
| | | | | | | |||
| | CON [0x23bb] | | | CON [0x23bb] | | |||
| | 2.05 Content | | | 2.05 Content | | |||
| | (Token 0x73) | | | (Token 0x73) | | |||
| | "22.5 C" | | | "22.5 C" | | |||
| |<-----------------+ | |<-----------------+ | |||
| | | | | | | |||
| | ACK [0x23bb] | | | ACK [0x23bb] | | |||
| +----------------->| | +----------------->| | |||
| | | | | | | |||
| Figure 5: A GET request with a separate response | Figure 5: A GET request with a separate response | |||
| Likewise, if a request is sent in a Non-confirmable message, then the | If a request is sent in a Non-confirmable message, then the response | |||
| response is usually sent using a new Non-confirmable message, | is sent using a new Non-confirmable message, although the server may | |||
| although the server may send a Confirmable message. This type of | instead send a Confirmable message. This type of exchange is | |||
| exchange is illustrated in Figure 6. | illustrated in Figure 6. | |||
| Client Server | Client Server | |||
| | | | | | | |||
| | NON [0x7a11] | | | NON [0x7a11] | | |||
| | GET /temperature | | | GET /temperature | | |||
| | (Token 0x74) | | | (Token 0x74) | | |||
| +----------------->| | +----------------->| | |||
| | | | | | | |||
| | NON [0x23bc] | | | NON [0x23bc] | | |||
| | 2.05 Content | | | 2.05 Content | | |||
| | (Token 0x74) | | | (Token 0x74) | | |||
| | "22.5 C" | | | "22.5 C" | | |||
| |<-----------------+ | |<-----------------+ | |||
| | | | | | | |||
| Figure 6: A NON request and response | Figure 6: A NON request and response | |||
| CoAP makes use of GET, PUT, POST and DELETE methods in a similar | CoAP makes use of GET, PUT, POST and DELETE methods in a similar | |||
| manner to HTTP, with the semantics specified in Section 5.8. (Note | manner to HTTP, with the semantics specified in Section 5.8. (Note | |||
| that the detailed semantics of CoAP methods are "almost, but not | that the detailed semantics of CoAP methods are "almost, but not | |||
| entirely unlike" [HHGTTG] those of HTTP methods: Intuition taken from | entirely unlike" [HHGTTG] those of HTTP methods: Intuition taken from | |||
| HTTP experience generally does apply well, but there are enough | HTTP experience generally does apply well, but there are enough | |||
| differences that make it worthwhile to actually read the present | differences that make it worthwhile to actually read the present | |||
| specification.) | specification.) | |||
| Methods beyond the basic four can be added to CoAP in separate | ||||
| specifications. New methods do not necessarily have to use requests | ||||
| and responses in pairs. Even for existing methods, a single request | ||||
| may yield multiple responses, e.g. for a multicast request | ||||
| (Section 8) or with the Observe option [I-D.ietf-core-observe]. | ||||
| URI support in a server is simplified as the client already parses | URI support in a server is simplified as the client already parses | |||
| the URI and splits it into host, port, path and query components, | the URI and splits it into host, port, path and query components, | |||
| making use of default values for efficiency. Response codes | making use of default values for efficiency. Response codes relate | |||
| correspond to a small subset of HTTP response codes with a few CoAP | to a small subset of HTTP response codes with a few CoAP specific | |||
| specific codes added, as defined in Section 5.9. | codes added, as defined in Section 5.9. | |||
| 2.3. Intermediaries and Caching | 2.3. Intermediaries and Caching | |||
| The protocol supports the caching of responses in order to | The protocol supports the caching of responses in order to | |||
| efficiently fulfill requests. Simple caching is enabled using | efficiently fulfill requests. Simple caching is enabled using | |||
| freshness and validity information carried with CoAP responses. A | freshness and validity information carried with CoAP responses. A | |||
| cache could be located in an endpoint or an intermediary. Caching | cache could be located in an endpoint or an intermediary. Caching | |||
| functionality is specified in Section 5.6. | functionality is specified in Section 5.6. | |||
| Proxying is useful in constrained networks for several reasons, | Proxying is useful in constrained networks for several reasons, | |||
| including network traffic limiting, to improve performance, to access | including network traffic limiting, to improve performance, to access | |||
| resources of sleeping devices or for security reasons. The proxying | resources of sleeping devices or for security reasons. The proxying | |||
| of requests on behalf of another CoAP endpoint is supported in the | of requests on behalf of another CoAP endpoint is supported in the | |||
| protocol. When using a proxy, the URI of the resource to request is | protocol. When using a proxy, the URI of the resource to request is | |||
| included in the request, while the destination IP address is set to | included in the request, while the destination IP address is set to | |||
| the address of the proxy. See Section 5.7 for more information on | the address of the proxy. See Section 5.7 for more information on | |||
| proxy functionality. | proxy functionality. | |||
| As CoAP was designed according to the REST architecture and thus | As CoAP was designed according to the REST architecture [REST] and | |||
| exhibits functionality similar to that of the HTTP protocol, it is | thus exhibits functionality similar to that of the HTTP protocol, it | |||
| quite straightforward to map from CoAP to HTTP and from HTTP to CoAP. | is quite straightforward to map from CoAP to HTTP and from HTTP to | |||
| Such a mapping may be used to realize an HTTP REST interface using | CoAP. Such a mapping may be used to realize an HTTP REST interface | |||
| CoAP, or for converting between HTTP and CoAP. This conversion can | using CoAP, or for converting between HTTP and CoAP. This conversion | |||
| be carried out by a cross-protocol proxy ("cross-proxy"), which | can be carried out by a cross-protocol proxy ("cross-proxy"), which | |||
| converts the method or response code, media type, and options to the | converts the method or response code, media type, and options to the | |||
| corresponding HTTP feature. Section 10 provides more detail about | corresponding HTTP feature. Section 10 provides more detail about | |||
| HTTP mapping. | HTTP mapping. | |||
| 2.4. Resource Discovery | 2.4. Resource Discovery | |||
| Resource discovery is important for machine-to-machine interactions, | Resource discovery is important for machine-to-machine interactions, | |||
| and is supported using the CoRE Link Format [RFC6690] as discussed in | and is supported using the CoRE Link Format [RFC6690] as discussed in | |||
| Section 7. | Section 7. | |||
| 3. Message Format | 3. Message Format | |||
| CoAP is based on the exchange of short messages which, by default, | CoAP is based on the exchange of compact messages which, by default, | |||
| are transported over UDP (i.e. each CoAP message occupies the data | are transported over UDP (i.e. each CoAP message occupies the data | |||
| section of one UDP datagram). CoAP may also be used over Datagram | section of one UDP datagram). CoAP may also be used over Datagram | |||
| Transport Layer Security (DTLS) (see Section 9.1). It could also be | Transport Layer Security (DTLS) (see Section 9.1). It could also be | |||
| used over other transports such as SMS, TCP or SCTP, the | used over other transports such as SMS, TCP or SCTP, the | |||
| specification of which is out of this document's scope. | specification of which is out of this document's scope. (UDP-lite | |||
| [RFC3828] and UDP zero checksum [RFC6936] are not supported by CoAP.) | ||||
| CoAP messages are encoded in a simple binary format. The message | CoAP messages are encoded in a simple binary format. The message | |||
| format starts with a fixed-size 4-byte header. This is followed by a | format starts with a fixed-size 4-byte header. This is followed by a | |||
| variable-length Token value which can be between 0 and 8 bytes long. | variable-length Token value which can be between 0 and 8 bytes long. | |||
| Following the Token value comes a sequence of zero or more CoAP | Following the Token value comes a sequence of zero or more CoAP | |||
| Options in Type-Length-Value (TLV) format, optionally followed by a | Options in Type-Length-Value (TLV) format, optionally followed by a | |||
| payload which takes up the rest of the datagram. | payload which takes up the rest of the datagram. | |||
| 0 1 2 3 | 0 1 2 3 | |||
| 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 | 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 | |||
| skipping to change at page 15, line 32 ¶ | skipping to change at page 16, line 4 ¶ | |||
| 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 | 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 | |||
| +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | |||
| |Ver| T | TKL | Code | Message ID | | |Ver| T | TKL | Code | Message ID | | |||
| +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | |||
| | Token (if any, TKL bytes) ... | | Token (if any, TKL bytes) ... | |||
| +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | |||
| | Options (if any) ... | | Options (if any) ... | |||
| +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | |||
| |1 1 1 1 1 1 1 1| Payload (if any) ... | |1 1 1 1 1 1 1 1| Payload (if any) ... | |||
| +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | |||
| Figure 7: Message Format | Figure 7: Message Format | |||
| The fields in the header are defined as follows: | The fields in the header are defined as follows: | |||
| Version (Ver): 2-bit unsigned integer. Indicates the CoAP version | Version (Ver): 2-bit unsigned integer. Indicates the CoAP version | |||
| number. Implementations of this specification MUST set this field | number. Implementations of this specification MUST set this field | |||
| to 1. Other values are reserved for future versions. | to 1 (01 binary). Other values are reserved for future versions. | |||
| Messages with unknown version numbers MUST be silently ignored. | ||||
| Type (T): 2-bit unsigned integer. Indicates if this message is of | Type (T): 2-bit unsigned integer. Indicates if this message is of | |||
| type Confirmable (0), Non-confirmable (1), Acknowledgement (2) or | type Confirmable (0), Non-confirmable (1), Acknowledgement (2) or | |||
| Reset (3). The semantics of these message types are defined in | Reset (3). The semantics of these message types are defined in | |||
| Section 4. | Section 4. | |||
| Token Length (TKL): 4-bit unsigned integer. Indicates the length of | Token Length (TKL): 4-bit unsigned integer. Indicates the length of | |||
| the variable-length Token field (0-8 bytes). Lengths 9-15 are | the variable-length Token field (0-8 bytes). Lengths 9-15 are | |||
| reserved, MUST NOT be sent, and MUST be processed as a message | reserved, MUST NOT be sent, and MUST be processed as a message | |||
| format error. | format error. | |||
| Code: 8-bit unsigned integer. Indicates if the message carries a | Code: 8-bit unsigned integer, split into a 3-bit class (most | |||
| request (1-31) or a response (64-191), or is empty (0). (All | significant bits) and a 5-bit detail (least significant bits), | |||
| other code values are reserved.) In case of a request, the Code | documented as c.dd where c is a digit from 0 to 7 for the 3-bit | |||
| field indicates the Request Method; in case of a response a | subfield and dd are two digits from 00 to 31 for the 5-bit | |||
| Response Code. Possible values are maintained in the CoAP Code | subfield. The class can indicate a request (0), a success | |||
| Registry (Section 12.1). The semantics of requests and responses | response (2), a client error response (4), or a server error | |||
| are defined in Section 5. | response (5). (All other class values are reserved.) As a | |||
| special case, Code 0.00 indicates an Empty message. In case of a | ||||
| request, the Code field indicates the Request Method; in case of a | ||||
| response a Response Code. Possible values are maintained in the | ||||
| CoAP Code Registries (Section 12.1). The semantics of requests | ||||
| and responses are defined in Section 5. | ||||
| Message ID: 16-bit unsigned integer in network byte order. Used for | Message ID: 16-bit unsigned integer in network byte order. Used for | |||
| the detection of message duplication, and to match messages of | the detection of message duplication, and to match messages of | |||
| type Acknowledgement/Reset to messages of type Confirmable/ | type Acknowledgement/Reset to messages of type Confirmable/Non- | |||
| Non-confirmable. The rules for generating a Message ID and | confirmable. The rules for generating a Message ID and matching | |||
| matching messages are defined in Section 4. | messages are defined in Section 4. | |||
| The header is followed by the Token value, which may be 0 to 8 bytes, | The header is followed by the Token value, which may be 0 to 8 bytes, | |||
| as given by the Token Length field. The Token value is used to | as given by the Token Length field. The Token value is used to | |||
| correlate requests and responses. The rules for generating a Token | correlate requests and responses. The rules for generating a Token | |||
| and correlating requests and responses are defined in Section 5.3.1. | and correlating requests and responses are defined in Section 5.3.1. | |||
| Header and Token are followed by zero or more Options (Section 3.1). | Header and Token are followed by zero or more Options (Section 3.1). | |||
| An Option can be followed by the end of the message, by another | An Option can be followed by the end of the message, by another | |||
| Option, or by the Payload Marker and the payload. | Option, or by the Payload Marker and the payload. | |||
| skipping to change at page 17, line 46 ¶ | skipping to change at page 18, line 23 ¶ | |||
| +-------------------------------+ | +-------------------------------+ | |||
| Figure 8: Option Format | Figure 8: Option Format | |||
| The fields in an option are defined as follows: | The fields in an option are defined as follows: | |||
| Option Delta: 4-bit unsigned integer. A value between 0 and 12 | Option Delta: 4-bit unsigned integer. A value between 0 and 12 | |||
| indicates the Option Delta. Three values are reserved for special | indicates the Option Delta. Three values are reserved for special | |||
| constructs: | constructs: | |||
| 13: An 8-bit unsigned integer follows the initial byte and | 13: An 8-bit unsigned integer follows the initial byte and | |||
| indicates the Option Delta minus 13. | indicates the Option Delta minus 13. | |||
| 14: A 16-bit unsigned integer in network byte order follows the | 14: A 16-bit unsigned integer in network byte order follows the | |||
| initial byte and indicates the Option Delta minus 269. | initial byte and indicates the Option Delta minus 269. | |||
| 15: Reserved for the Payload Marker. If the field is set to this | 15: Reserved for the Payload Marker. If the field is set to | |||
| value but the entire byte is not the payload marker, this MUST | this value but the entire byte is not the payload marker, | |||
| be processed as a message format error. | this MUST be processed as a message format error. | |||
| The resulting Option Delta is used as the difference between the | The resulting Option Delta is used as the difference between the | |||
| Option Number of this option and that of the previous option (or | Option Number of this option and that of the previous option (or | |||
| zero for the first option). In other words, the Option Number is | zero for the first option). In other words, the Option Number is | |||
| calculated by simply summing the Option Delta values of this and | calculated by simply summing the Option Delta values of this and | |||
| all previous options before it. | all previous options before it. | |||
| Option Length: 4-bit unsigned integer. A value between 0 and 12 | Option Length: 4-bit unsigned integer. A value between 0 and 12 | |||
| indicates the length of the Option Value, in bytes. Three values | indicates the length of the Option Value, in bytes. Three values | |||
| are reserved for special constructs: | are reserved for special constructs: | |||
| 13: An 8-bit unsigned integer precedes the Option Value and | 13: An 8-bit unsigned integer precedes the Option Value and | |||
| indicates the Option Length minus 13. | indicates the Option Length minus 13. | |||
| 14: A 16-bit unsigned integer in network byte order precedes the | 14: A 16-bit unsigned integer in network byte order precedes the | |||
| Option Value and indicates the Option Length minus 269. | Option Value and indicates the Option Length minus 269. | |||
| 15: Reserved for future use. If the field is set to this value, | 15: Reserved for future use. If the field is set to this value, | |||
| it MUST be processed as a message format error. | it MUST be processed as a message format error. | |||
| Value: A sequence of exactly Option Length bytes. The length and | Value: A sequence of exactly Option Length bytes. The length and | |||
| format of the Option Value depend on the respective option, which | format of the Option Value depend on the respective option, which | |||
| MAY define variable length values. See Section 3.2 for the | MAY define variable length values. See Section 3.2 for the | |||
| formats used in this document; options defined in other documents | formats used in this document; options defined in other documents | |||
| MAY make use of other option value formats. | MAY make use of other option value formats. | |||
| 3.2. Option Value Formats | 3.2. Option Value Formats | |||
| The options defined in this document make use of the following option | The options defined in this document make use of the following option | |||
| skipping to change at page 19, line 12 ¶ | skipping to change at page 19, line 35 ¶ | |||
| numbers of bytes; if it has a choice, a sender SHOULD | numbers of bytes; if it has a choice, a sender SHOULD | |||
| represent the integer with as few bytes as possible, i.e., | represent the integer with as few bytes as possible, i.e., | |||
| without leading zero bytes. For example, the number 0 is | without leading zero bytes. For example, the number 0 is | |||
| represented with an empty option value (a zero-length | represented with an empty option value (a zero-length | |||
| sequence of bytes), and the number 1 by a single byte with | sequence of bytes), and the number 1 by a single byte with | |||
| the numerical value of 1 (bit combination 00000001 in most | the numerical value of 1 (bit combination 00000001 in most | |||
| significant bit first notation). A recipient MUST be | significant bit first notation). A recipient MUST be | |||
| prepared to process values with leading zero bytes. | prepared to process values with leading zero bytes. | |||
| Implementation Note: The exceptional behavior permitted | Implementation Note: The exceptional behavior permitted | |||
| for the sender is intended for highly | for the sender is intended for highly constrained, | |||
| constrained, templated implementations (e.g., | templated implementations (e.g., hardware | |||
| hardware implementations) that use fixed size | implementations) that use fixed size options in the | |||
| options in the templates. | templates. | |||
| string: A Unicode string which is encoded using UTF-8 [RFC3629] in | string: A Unicode string which is encoded using UTF-8 [RFC3629] in | |||
| Net-Unicode form [RFC5198]. | Net-Unicode form [RFC5198]. | |||
| Note that here and in all other places where UTF-8 encoding | Note that here and in all other places where UTF-8 encoding | |||
| is used in the CoAP protocol, the intention is that the | is used in the CoAP protocol, the intention is that the | |||
| encoded strings can be directly used and compared as opaque | encoded strings can be directly used and compared as opaque | |||
| byte strings by CoAP protocol implementations. There is no | byte strings by CoAP protocol implementations. There is no | |||
| expectation and no need to perform normalization within a | expectation and no need to perform normalization within a | |||
| CoAP implementation (except where Unicode strings that are | CoAP implementation (except where Unicode strings that are | |||
| skipping to change at page 20, line 19 ¶ | skipping to change at page 20, line 37 ¶ | |||
| used for CoAP. For the transports defined in this specification, the | used for CoAP. For the transports defined in this specification, the | |||
| endpoint is identified depending on the security mode used (see | endpoint is identified depending on the security mode used (see | |||
| Section 9): With no security, the endpoint is solely identified by an | Section 9): With no security, the endpoint is solely identified by an | |||
| IP address and a UDP port number. With other security modes, the | IP address and a UDP port number. With other security modes, the | |||
| endpoint is identified as defined by the security mode. | endpoint is identified as defined by the security mode. | |||
| There are different types of messages. The type of a message is | There are different types of messages. The type of a message is | |||
| specified by the Type field of the CoAP Header. | specified by the Type field of the CoAP Header. | |||
| Separate from the message type, a message may carry a request, a | Separate from the message type, a message may carry a request, a | |||
| response, or be empty. This is signaled by the Request/Response Code | response, or be Empty. This is signaled by the Request/Response Code | |||
| field in the CoAP Header and is relevant to the request/response | field in the CoAP Header and is relevant to the request/response | |||
| model. Possible values for the field are maintained in the CoAP Code | model. Possible values for the field are maintained in the CoAP Code | |||
| Registry (Section 12.1). | Registries (Section 12.1). | |||
| An empty message has the Code field set to 0. The Token Length field | An Empty message has the Code field set to 0.00. The Token Length | |||
| MUST be set to 0 and no bytes MUST be present after the Message ID | field MUST be set to 0 and bytes of data MUST NOT be present after | |||
| field. If there are any bytes, they MUST be processed as a message | the Message ID field. If there are any bytes, they MUST be processed | |||
| format error. | as a message format error. | |||
| 4.2. Messages Transmitted Reliably | 4.2. Messages Transmitted Reliably | |||
| The reliable transmission of a message is initiated by marking the | The reliable transmission of a message is initiated by marking the | |||
| message as Confirmable in the CoAP header. A Confirmable message | message as Confirmable in the CoAP header. A Confirmable message | |||
| always carries either a request or response and MUST NOT be empty, | always carries either a request or response, unless it is used only | |||
| unless it is used only to elicit a Reset message. A recipient MUST | to elicit a Reset message in which case it is Empty. A recipient | |||
| acknowledge such a message with an Acknowledgement message or, if it | MUST acknowledge a Confirmable message with an Acknowledgement | |||
| lacks context to process the message properly (including the case | message or, if it lacks context to process the message properly | |||
| where the message is empty or has a message format error), MUST | (including the case where the message is Empty, uses a code with a | |||
| reserved class (1, 6 or 7), or has a message format error), MUST | ||||
| reject it; rejecting a Confirmable message is effected by sending a | reject it; rejecting a Confirmable message is effected by sending a | |||
| matching Reset message and otherwise ignoring it. The | matching Reset message and otherwise ignoring it. The | |||
| Acknowledgement message MUST echo the Message ID of the Confirmable | Acknowledgement message MUST echo the Message ID of the Confirmable | |||
| message, and MUST carry a response or be empty (see Section 5.2.1 and | message, and MUST carry a response or be Empty (see Section 5.2.1 and | |||
| Section 5.2.2). The Reset message MUST echo the Message ID of the | Section 5.2.2). The Reset message MUST echo the Message ID of the | |||
| Confirmable message, and MUST be empty. Rejecting an Acknowledgement | Confirmable message, and MUST be Empty. Rejecting an Acknowledgement | |||
| or Reset message is effected by silently ignoring it. More | or Reset message (including the case where the Acknowledgement | |||
| generally, Acknowledgement and Reset messages MUST NOT elicit any | carries a request or a code with a reserved class, or the Reset | |||
| Acknowledgement or Reset message from their recipient. | message is not Empty) is effected by silently ignoring it. More | |||
| generally, recipients of Acknowledgement and Reset messages MUST NOT | ||||
| respond with either Acknowledgement or Reset messages. | ||||
| The sender retransmits the Confirmable message at exponentially | The sender retransmits the Confirmable message at exponentially | |||
| increasing intervals, until it receives an acknowledgement (or Reset | increasing intervals, until it receives an acknowledgement (or Reset | |||
| message), or runs out of attempts. | message), or runs out of attempts. | |||
| Retransmission is controlled by two things that a CoAP endpoint MUST | Retransmission is controlled by two things that a CoAP endpoint MUST | |||
| keep track of for each Confirmable message it sends while waiting for | keep track of for each Confirmable message it sends while waiting for | |||
| an acknowledgement (or reset): a timeout and a retransmission | an acknowledgement (or reset): a timeout and a retransmission | |||
| counter. For a new Confirmable message, the initial timeout is set | counter. For a new Confirmable message, the initial timeout is set | |||
| to a random number between ACK_TIMEOUT and (ACK_TIMEOUT * | to a random duration (often not an integral number of seconds) | |||
| ACK_RANDOM_FACTOR) (see Section 4.8), and the retransmission counter | between ACK_TIMEOUT and (ACK_TIMEOUT * ACK_RANDOM_FACTOR) (see | |||
| is set to 0. When the timeout is triggered and the retransmission | Section 4.8), and the retransmission counter is set to 0. When the | |||
| counter is less than MAX_RETRANSMIT, the message is retransmitted, | timeout is triggered and the retransmission counter is less than | |||
| the retransmission counter is incremented, and the timeout is | MAX_RETRANSMIT, the message is retransmitted, the retransmission | |||
| doubled. If the retransmission counter reaches MAX_RETRANSMIT on a | counter is incremented, and the timeout is doubled. If the | |||
| timeout, or if the endpoint receives a Reset message, then the | retransmission counter reaches MAX_RETRANSMIT on a timeout, or if the | |||
| attempt to transmit the message is canceled and the application | endpoint receives a Reset message, then the attempt to transmit the | |||
| process informed of failure. On the other hand, if the endpoint | message is canceled and the application process informed of failure. | |||
| receives an acknowledgement in time, transmission is considered | On the other hand, if the endpoint receives an acknowledgement in | |||
| successful. | time, transmission is considered successful. | |||
| This specification makes no strong requirements on the accuracy of | ||||
| the clocks used to implement the above binary exponential backoff | ||||
| algorithm. In particular, an endpoint may be late for a specific | ||||
| retransmission due to its sleep schedule, and maybe catch up on the | ||||
| next one. However, the minimum spacing before another retransmission | ||||
| is ACK_TIMEOUT, and the entire sequence of (re-)transmissions MUST | ||||
| stay in the envelope of MAX_TRANSMIT_SPAN (see Section 4.8.2), even | ||||
| if that means a sender may miss an opportunity to transmit. | ||||
| A CoAP endpoint that sent a Confirmable message MAY give up in | A CoAP endpoint that sent a Confirmable message MAY give up in | |||
| attempting to obtain an ACK even before the MAX_RETRANSMIT counter | attempting to obtain an ACK even before the MAX_RETRANSMIT counter | |||
| value is reached: E.g., the application has canceled the request as | value is reached: E.g., the application has canceled the request as | |||
| it no longer needs a response, or there is some other indication that | it no longer needs a response, or there is some other indication that | |||
| the CON message did arrive. In particular, a CoAP request message | the CON message did arrive. In particular, a CoAP request message | |||
| may have elicited a separate response, in which case it is clear to | may have elicited a separate response, in which case it is clear to | |||
| the requester that only the ACK was lost and a retransmission of the | the requester that only the ACK was lost and a retransmission of the | |||
| request would serve no purpose. However, a responder MUST NOT in | request would serve no purpose. However, a responder MUST NOT in | |||
| turn rely on this cross-layer behavior from a requester, i.e. it | turn rely on this cross-layer behavior from a requester, i.e. it | |||
| SHOULD retain the state to create the ACK for the request, if needed, | MUST retain the state to create the ACK for the request, if needed, | |||
| even if a Confirmable response was already acknowledged by the | even if a Confirmable response was already acknowledged by the | |||
| requester. | requester. | |||
| Another reason for giving up retransmission MAY be the receipt of | ||||
| ICMP errors. If it is desired to take account of ICMP errors, to | ||||
| mitigate potential spoofing attacks, implementations SHOULD take care | ||||
| to check the information about the original datagram in the ICMP | ||||
| message, including port numbers and CoAP header information such as | ||||
| message type and code, Message ID, and Token; if this is not possible | ||||
| due to limitations of the UDP service API, ICMP errors SHOULD be | ||||
| ignored. Packet Too Big errors [RFC4443] ("fragmentation needed and | ||||
| DF set" for IPv4 [RFC0792]) cannot properly occur and SHOULD be | ||||
| ignored if the implementation note in Section 4.6 is followed; | ||||
| otherwise, they SHOULD feed into a path MTU discovery algorithm | ||||
| [RFC4821]. Source Quench and Time Exceeded ICMP messages SHOULD be | ||||
| ignored. Host, network, port or protocol unreachable errors, or | ||||
| parameter problem errors MAY, after appropriate vetting, be used to | ||||
| inform the application of a failure in sending. | ||||
| 4.3. Messages Transmitted Without Reliability | 4.3. Messages Transmitted Without Reliability | |||
| Some messages do not require an acknowledgement. This is | Some messages do not require an acknowledgement. This is | |||
| particularly true for messages that are repeated regularly for | particularly true for messages that are repeated regularly for | |||
| application requirements, such as repeated readings from a sensor | application requirements, such as repeated readings from a sensor | |||
| where eventual success is sufficient. | where eventual success is sufficient. | |||
| As a more lightweight alternative, a message can be transmitted less | As a more lightweight alternative, a message can be transmitted less | |||
| reliably by marking the message as Non-confirmable. A Non- | reliably by marking the message as Non-confirmable. A Non- | |||
| confirmable message always carries either a request or response and | confirmable message always carries either a request or response and | |||
| MUST NOT be empty. A Non-confirmable message MUST NOT be | MUST NOT be Empty. A Non-confirmable message MUST NOT be | |||
| acknowledged by the recipient. If a recipient lacks context to | acknowledged by the recipient. If a recipient lacks context to | |||
| process the message properly (including the case where the message is | process the message properly (including the case where the message is | |||
| empty or has a message format error), it MUST reject the message; | Empty, uses a code with a reserved class (1, 6 or 7), or has a | |||
| rejecting a Non-confirmable message MAY involve sending a matching | message format error), it MUST reject the message; rejecting a Non- | |||
| Reset message, and apart from the Reset message the rejected message | confirmable message MAY involve sending a matching Reset message, and | |||
| MUST be silently ignored. | apart from the Reset message the rejected message MUST be silently | |||
| ignored. | ||||
| At the CoAP level, there is no way for the sender to detect if a Non- | At the CoAP level, there is no way for the sender to detect if a Non- | |||
| confirmable message was received or not. A sender MAY choose to | confirmable message was received or not. A sender MAY choose to | |||
| transmit multiple copies of a Non-confirmable message within | transmit multiple copies of a Non-confirmable message within | |||
| MAX_TRANSMIT_SPAN (limited by the provisions of Section 4.7, in | MAX_TRANSMIT_SPAN (limited by the provisions of Section 4.7, in | |||
| particular by PROBING_RATE if no response is received), or the | particular by PROBING_RATE if no response is received), or the | |||
| network may duplicate the message in transit. To enable the receiver | network may duplicate the message in transit. To enable the receiver | |||
| to act only once on the message, Non-confirmable messages specify a | to act only once on the message, Non-confirmable messages specify a | |||
| Message ID as well. (This Message ID is drawn from the same number | Message ID as well. (This Message ID is drawn from the same number | |||
| space as the Message IDs for Confirmable messages.) | space as the Message IDs for Confirmable messages.) | |||
| Summarizing Section 4.2 and Section 4.3, the four message types can | ||||
| be used as in Table 1. "*" means that the combination is not used in | ||||
| normal operation, but only to elicit a Reset message ("CoAP ping"). | ||||
| +----------+-----+-----+-----+-----+ | ||||
| | | CON | NON | ACK | RST | | ||||
| +----------+-----+-----+-----+-----+ | ||||
| | Request | X | X | - | - | | ||||
| | Response | X | X | X | - | | ||||
| | Empty | * | - | X | X | | ||||
| +----------+-----+-----+-----+-----+ | ||||
| Table 1: Usage of message types | ||||
| 4.4. Message Correlation | 4.4. Message Correlation | |||
| An Acknowledgement or Reset message is related to a Confirmable | An Acknowledgement or Reset message is related to a Confirmable | |||
| message or Non-confirmable message by means of a Message ID along | message or Non-confirmable message by means of a Message ID along | |||
| with additional address information of the corresponding endpoint. | with additional address information of the corresponding endpoint. | |||
| The Message ID is a 16-bit unsigned integer that is generated by the | The Message ID is a 16-bit unsigned integer that is generated by the | |||
| sender of a Confirmable or Non-confirmable message and included in | sender of a Confirmable or Non-confirmable message and included in | |||
| the CoAP header. The Message ID MUST be echoed in the | the CoAP header. The Message ID MUST be echoed in the | |||
| Acknowledgement or Reset message by the recipient. | Acknowledgement or Reset message by the recipient. | |||
| skipping to change at page 22, line 33 ¶ | skipping to change at page 23, line 46 ¶ | |||
| same endpoint) within the EXCHANGE_LIFETIME (Section 4.8.2). | same endpoint) within the EXCHANGE_LIFETIME (Section 4.8.2). | |||
| Implementation Note: Several implementation strategies can be | Implementation Note: Several implementation strategies can be | |||
| employed for generating Message IDs. In the simplest case a CoAP | employed for generating Message IDs. In the simplest case a CoAP | |||
| endpoint generates Message IDs by keeping a single Message ID | endpoint generates Message IDs by keeping a single Message ID | |||
| variable, which is changed each time a new Confirmable or Non- | variable, which is changed each time a new Confirmable or Non- | |||
| confirmable message is sent regardless of the destination address | confirmable message is sent regardless of the destination address | |||
| or port. Endpoints dealing with large numbers of transactions | or port. Endpoints dealing with large numbers of transactions | |||
| could keep multiple Message ID variables, for example per prefix | could keep multiple Message ID variables, for example per prefix | |||
| or destination address (note that some receiving endpoints may not | or destination address (note that some receiving endpoints may not | |||
| be able to distinguish unicast and multicast packets adressed to | be able to distinguish unicast and multicast packets addressed to | |||
| it, so endpoints generating Message IDs need to make sure these do | it, so endpoints generating Message IDs need to make sure these do | |||
| not overlap). The initial variable value should be randomized. | not overlap). It is strongly recommended that the initial value | |||
| of the variable (e.g., on startup) be randomized, in order to make | ||||
| successful off-path attacks on the protocol less likely. | ||||
| For an Acknowledgement or Reset message to match a Confirmable or | For an Acknowledgement or Reset message to match a Confirmable or | |||
| Non-confirmable message, the Message ID and source endpoint of the | Non-confirmable message, the Message ID and source endpoint of the | |||
| Acknowledgement or Reset message MUST match the Message ID and | Acknowledgement or Reset message MUST match the Message ID and | |||
| destination endpoint of the Confirmable or Non-confirmable message. | destination endpoint of the Confirmable or Non-confirmable message. | |||
| 4.5. Message Deduplication | 4.5. Message Deduplication | |||
| A recipient MUST be prepared to receive the same Confirmable message | A recipient might receive the same Confirmable message (as indicated | |||
| (as indicated by the Message ID and source endpoint) multiple times | by the Message ID and source endpoint) multiple times within the | |||
| within the EXCHANGE_LIFETIME (Section 4.8.2), for example, when its | EXCHANGE_LIFETIME (Section 4.8.2), for example, when its | |||
| Acknowledgement went missing or didn't reach the original sender | Acknowledgement went missing or didn't reach the original sender | |||
| before the first timeout. The recipient SHOULD acknowledge each | before the first timeout. The recipient SHOULD acknowledge each | |||
| duplicate copy of a Confirmable message using the same | duplicate copy of a Confirmable message using the same | |||
| Acknowledgement or Reset message, but SHOULD process any request or | Acknowledgement or Reset message, but SHOULD process any request or | |||
| response in the message only once. This rule MAY be relaxed in case | response in the message only once. This rule MAY be relaxed in case | |||
| the Confirmable message transports a request that is idempotent (see | the Confirmable message transports a request that is idempotent (see | |||
| Section 5.1) or can be handled in an idempotent fashion. Examples | Section 5.1) or can be handled in an idempotent fashion. Examples | |||
| for relaxed message deduplication: | for relaxed message deduplication: | |||
| o A server MAY relax the requirement to answer all retransmissions | o A server might relax the requirement to answer all retransmissions | |||
| of an idempotent request with the same response (Section 4.2), so | of an idempotent request with the same response (Section 4.2), so | |||
| that it does not have to maintain state for Message IDs. For | that it does not have to maintain state for Message IDs. For | |||
| example, an implementation might want to process duplicate | example, an implementation might want to process duplicate | |||
| transmissions of a GET, PUT or DELETE request as separate requests | transmissions of a GET, PUT or DELETE request as separate requests | |||
| if the effort incurred by duplicate processing is less expensive | if the effort incurred by duplicate processing is less expensive | |||
| than keeping track of previous responses would be. | than keeping track of previous responses would be. | |||
| o A constrained server MAY even want to relax this requirement for | o A constrained server might even want to relax this requirement for | |||
| certain non-idempotent requests if the application semantics make | certain non-idempotent requests if the application semantics make | |||
| this trade-off favorable. For example, if the result of a POST | this trade-off favorable. For example, if the result of a POST | |||
| request is just the creation of some short-lived state at the | request is just the creation of some short-lived state at the | |||
| server, it may be less expensive to incur this effort multiple | server, it may be less expensive to incur this effort multiple | |||
| times for a request than keeping track of whether a previous | times for a request than keeping track of whether a previous | |||
| transmission of the same request already was processed. | transmission of the same request already was processed. | |||
| A recipient MUST be prepared to receive the same Non-confirmable | A recipient might receive the same Non-confirmable message (as | |||
| message (as indicated by the Message ID and source endpoint) multiple | indicated by the Message ID and source endpoint) multiple times | |||
| times within NON_LIFETIME (Section 4.8.2). As a general rule that | within NON_LIFETIME (Section 4.8.2). As a general rule that MAY be | |||
| MAY be relaxed based on the specific semantics of a message, the | relaxed based on the specific semantics of a message, the recipient | |||
| recipient SHOULD silently ignore any duplicated Non-confirmable | SHOULD silently ignore any duplicated Non-confirmable message, and | |||
| message, and SHOULD process any request or response in the message | SHOULD process any request or response in the message only once. | |||
| only once. | ||||
| 4.6. Message Size | 4.6. Message Size | |||
| While specific link layers make it beneficial to keep CoAP messages | While specific link layers make it beneficial to keep CoAP messages | |||
| small enough to fit into their link layer packets (see Section 1), | small enough to fit into their link layer packets (see Section 1), | |||
| this is a matter of implementation quality. The CoAP specification | this is a matter of implementation quality. The CoAP specification | |||
| itself provides only an upper bound to the message size. Messages | itself provides only an upper bound to the message size. Messages | |||
| larger than an IP fragment result in undesired packet fragmentation. | larger than an IP packet result in undesirable packet fragmentation. | |||
| A CoAP message, appropriately encapsulated, SHOULD fit within a | A CoAP message, appropriately encapsulated, SHOULD fit within a | |||
| single IP packet (i.e., avoid IP fragmentation) and (by fitting into | single IP packet (i.e., avoid IP fragmentation) and (by fitting into | |||
| one UDP payload) obviously MUST fit within a single IP datagram. If | one UDP payload) obviously needs to fit within a single IP datagram. | |||
| the Path MTU is not known for a destination, an IP MTU of 1280 bytes | If the Path MTU is not known for a destination, an IP MTU of 1280 | |||
| SHOULD be assumed; if nothing is known about the size of the headers, | bytes SHOULD be assumed; if nothing is known about the size of the | |||
| good upper bounds are 1152 bytes for the message size and 1024 bytes | headers, good upper bounds are 1152 bytes for the message size and | |||
| for the payload size. | 1024 bytes for the payload size. | |||
| Implementation Note: CoAP's choice of message size parameters works | Implementation Note: CoAP's choice of message size parameters works | |||
| well with IPv6 and with most of today's IPv4 paths. (However, | well with IPv6 and with most of today's IPv4 paths. (However, | |||
| with IPv4, it is harder to absolutely ensure that there is no IP | with IPv4, it is harder to absolutely ensure that there is no IP | |||
| fragmentation. If IPv4 support on unusual networks is a | fragmentation. If IPv4 support on unusual networks is a | |||
| consideration, implementations may want to limit themselves to | consideration, implementations may want to limit themselves to | |||
| more conservative IPv4 datagram sizes such as 576 bytes; worse, | more conservative IPv4 datagram sizes such as 576 bytes; worse, | |||
| the absolute minimum value of the IP MTU for IPv4 is as low as 68 | the absolute minimum value of the IP MTU for IPv4 is as low as 68 | |||
| bytes, which would leave only 40 bytes minus security overhead for | bytes, which would leave only 40 bytes minus security overhead for | |||
| a UDP payload. Implementations extremely focused on this problem | a UDP payload. Implementations extremely focused on this problem | |||
| set might also set the IPv4 DF bit and perform some form of path | set might also set the IPv4 DF bit and perform some form of path | |||
| MTU discovery; this should generally be unnecessary in most | MTU discovery [RFC4821]; this should generally be unnecessary in | |||
| realistic use cases for CoAP, however.) A more important kind of | most realistic use cases for CoAP, however.) A more important | |||
| fragmentation in many constrained networks is that on the | kind of fragmentation in many constrained networks is that on the | |||
| adaptation layer (e.g., 6LoWPAN L2 packets are limited to 127 | adaptation layer (e.g., 6LoWPAN L2 packets are limited to 127 | |||
| bytes including various overheads); this may motivate | bytes including various overheads); this may motivate | |||
| implementations to be frugal in their packet sizes and to move to | implementations to be frugal in their packet sizes and to move to | |||
| block-wise transfers [I-D.ietf-core-block] when approaching three- | block-wise transfers [I-D.ietf-core-block] when approaching three- | |||
| digit message sizes. | digit message sizes. | |||
| Message sizes are also of considerable importance to | Message sizes are also of considerable importance to | |||
| implementations on constrained nodes. Many implementations will | implementations on constrained nodes. Many implementations will | |||
| need to allocate a buffer for incoming messages. If an | need to allocate a buffer for incoming messages. If an | |||
| implementation is too constrained to allow for allocating the | implementation is too constrained to allow for allocating the | |||
| above-mentioned upper bound, it could apply the following | above-mentioned upper bound, it could apply the following | |||
| implementation strategy: Implementations receiving a datagram into | implementation strategy for messages not using DTLS security: | |||
| a buffer that is too small are usually able to determine if the | Implementations receiving a datagram into a buffer that is too | |||
| trailing portion of a datagram was discarded and to retrieve the | small are usually able to determine if the trailing portion of a | |||
| initial portion. So, if not all of the payload, at least the CoAP | datagram was discarded and to retrieve the initial portion. So, | |||
| header and options are likely to fit within the buffer. A server | if not all of the payload, at least the CoAP header and options | |||
| can thus fully interpret a request and return a 4.13 (Request | are likely to fit within the buffer. A server can thus fully | |||
| Entity Too Large, see Section 5.9.2.9) response code if the | interpret a request and return a 4.13 (Request Entity Too Large, | |||
| payload was truncated. A client sending an idempotent request and | see Section 5.9.2.9) response code if the payload was truncated. | |||
| receiving a response larger than would fit in the buffer can | A client sending an idempotent request and receiving a response | |||
| repeat the request with a suitable value for the Block Option | larger than would fit in the buffer can repeat the request with a | |||
| [I-D.ietf-core-block]. | suitable value for the Block Option [I-D.ietf-core-block]. | |||
| 4.7. Congestion Control | 4.7. Congestion Control | |||
| Basic congestion control for CoAP is provided by the exponential | Basic congestion control for CoAP is provided by the exponential | |||
| back-off mechanism in Section 4.2. | back-off mechanism in Section 4.2. | |||
| In order not to cause congestion, Clients (including proxies) MUST | In order not to cause congestion, Clients (including proxies) MUST | |||
| strictly limit the number of simultaneous outstanding interactions | strictly limit the number of simultaneous outstanding interactions | |||
| that they maintain to a given server (including proxies) to NSTART. | that they maintain to a given server (including proxies) to NSTART. | |||
| An outstanding interaction is either a CON for which an ACK has not | An outstanding interaction is either a CON for which an ACK has not | |||
| yet been received but is still expected (message layer) or a request | yet been received but is still expected (message layer) or a request | |||
| for which neither a response nor an Acknowledgment message has yet | for which neither a response nor an Acknowledgment message has yet | |||
| been received but is still expected (which may both occur at the same | been received but is still expected (which may both occur at the same | |||
| skipping to change at page 25, line 19 ¶ | skipping to change at page 26, line 34 ¶ | |||
| EXCHANGE_LIFETIME. The specific algorithm by which a client stops to | EXCHANGE_LIFETIME. The specific algorithm by which a client stops to | |||
| "expect" a response to a Confirmable request that was acknowledged, | "expect" a response to a Confirmable request that was acknowledged, | |||
| or to a Non-confirmable request, is not defined. Unless this is | or to a Non-confirmable request, is not defined. Unless this is | |||
| modified by additional congestion control optimizations, it MUST be | modified by additional congestion control optimizations, it MUST be | |||
| chosen in such a way that an endpoint does not exceed an average data | chosen in such a way that an endpoint does not exceed an average data | |||
| rate of PROBING_RATE in sending to another endpoint that does not | rate of PROBING_RATE in sending to another endpoint that does not | |||
| respond. | respond. | |||
| Note: CoAP places the onus of congestion control mostly on the | Note: CoAP places the onus of congestion control mostly on the | |||
| clients. However, clients may malfunction or actually be | clients. However, clients may malfunction or actually be | |||
| attackers, e.g. to perform amplification attacks (Section 11.3). | attackers, e.g. to perform amplification attacks (Section 11.3). | |||
| To limit the damage (to the network and to its own energy | To limit the damage (to the network and to its own energy | |||
| resources), a server SHOULD implement some rate limiting for its | resources), a server SHOULD implement some rate limiting for its | |||
| response transmission based on reasonable assumptions about | response transmission based on reasonable assumptions about | |||
| application requirements. This is most helpful if the rate limit | application requirements. This is most helpful if the rate limit | |||
| can be made effective for the misbehaving endpoints, only. | can be made effective for the misbehaving endpoints, only. | |||
| 4.8. Transmission Parameters | 4.8. Transmission Parameters | |||
| Message transmission is controlled by the following parameters: | Message transmission is controlled by the following parameters: | |||
| skipping to change at page 25, line 41 ¶ | skipping to change at page 27, line 8 ¶ | |||
| | name | default value | | | name | default value | | |||
| +-------------------+---------------+ | +-------------------+---------------+ | |||
| | ACK_TIMEOUT | 2 seconds | | | ACK_TIMEOUT | 2 seconds | | |||
| | ACK_RANDOM_FACTOR | 1.5 | | | ACK_RANDOM_FACTOR | 1.5 | | |||
| | MAX_RETRANSMIT | 4 | | | MAX_RETRANSMIT | 4 | | |||
| | NSTART | 1 | | | NSTART | 1 | | |||
| | DEFAULT_LEISURE | 5 seconds | | | DEFAULT_LEISURE | 5 seconds | | |||
| | PROBING_RATE | 1 Byte/second | | | PROBING_RATE | 1 Byte/second | | |||
| +-------------------+---------------+ | +-------------------+---------------+ | |||
| Table 1: CoAP Protocol Parameters | Table 2: CoAP Protocol Parameters | |||
| 4.8.1. Changing The Parameters | 4.8.1. Changing The Parameters | |||
| The values for ACK_TIMEOUT, ACK_RANDOM_FACTOR, MAX_RETRANSMIT, | The values for ACK_TIMEOUT, ACK_RANDOM_FACTOR, MAX_RETRANSMIT, | |||
| NSTART, DEFAULT_LEISURE, and PROBING_RATE may be configured to values | NSTART, DEFAULT_LEISURE (Section 8.2), and PROBING_RATE may be | |||
| specific to the application environment (including dynamically | configured to values specific to the application environment | |||
| adjusted values), however the configuration method is out of scope of | (including dynamically adjusted values), however the configuration | |||
| this document. It is recommended that an application environment use | method is out of scope of this document. It is RECOMMENDED that an | |||
| consistent values for these parameters. | application environment use consistent values for these parameters; | |||
| the specific effects of operating with inconsistent values in an | ||||
| application environment are outside the scope of the present | ||||
| specification. | ||||
| The transmission parameters have been chosen to achieve a behavior in | The transmission parameters have been chosen to achieve a behavior in | |||
| the presence of congestion that is safe in the Internet. If a | the presence of congestion that is safe in the Internet. If a | |||
| configuration desires to use different values, the onus is on the | configuration desires to use different values, the onus is on the | |||
| configuration to ensure these congestion control properties are not | configuration to ensure these congestion control properties are not | |||
| violated. In particular, a decrease of ACK_TIMEOUT below 1 second | violated. In particular, a decrease of ACK_TIMEOUT below 1 second | |||
| would violate the guidelines of [RFC5405]. | would violate the guidelines of [RFC5405]. | |||
| ([I-D.allman-tcpm-rto-consider] provides some additional background.) | ([I-D.allman-tcpm-rto-consider] provides some additional background.) | |||
| CoAP was designed to enable implementations that do not maintain | CoAP was designed to enable implementations that do not maintain | |||
| round-trip-time (RTT) measurements. However, where it is desired to | round-trip-time (RTT) measurements. However, where it is desired to | |||
| skipping to change at page 26, line 47 ¶ | skipping to change at page 28, line 18 ¶ | |||
| influences the timing of retransmissions, which in turn influences | influences the timing of retransmissions, which in turn influences | |||
| how long certain information items need to be kept by an | how long certain information items need to be kept by an | |||
| implementation. To be able to unambiguously reference these derived | implementation. To be able to unambiguously reference these derived | |||
| time values, we give them names as follows: | time values, we give them names as follows: | |||
| o MAX_TRANSMIT_SPAN is the maximum time from the first transmission | o MAX_TRANSMIT_SPAN is the maximum time from the first transmission | |||
| of a Confirmable message to its last retransmission. For the | of a Confirmable message to its last retransmission. For the | |||
| default transmission parameters, the value is (2+4+8+16)*1.5 = 45 | default transmission parameters, the value is (2+4+8+16)*1.5 = 45 | |||
| seconds, or more generally: | seconds, or more generally: | |||
| ACK_TIMEOUT * (2 ** MAX_RETRANSMIT - 1) * ACK_RANDOM_FACTOR | ACK_TIMEOUT * ((2 ** MAX_RETRANSMIT) - 1) * ACK_RANDOM_FACTOR | |||
| o MAX_TRANSMIT_WAIT is the maximum time from the first transmission | o MAX_TRANSMIT_WAIT is the maximum time from the first transmission | |||
| of a Confirmable message to the time when the sender gives up on | of a Confirmable message to the time when the sender gives up on | |||
| receiving an acknowledgement or reset. For the default | receiving an acknowledgement or reset. For the default | |||
| transmission parameters, the value is (2+4+8+16+32)*1.5 = 93 | transmission parameters, the value is (2+4+8+16+32)*1.5 = 93 | |||
| seconds, or more generally: | seconds, or more generally: | |||
| ACK_TIMEOUT * (2 ** (MAX_RETRANSMIT + 1) - 1) * | ACK_TIMEOUT * ((2 ** (MAX_RETRANSMIT + 1)) - 1) * | |||
| ACK_RANDOM_FACTOR | ACK_RANDOM_FACTOR | |||
| In addition, some assumptions need to be made on the characteristics | In addition, some assumptions need to be made on the characteristics | |||
| of the network and the nodes. | of the network and the nodes. | |||
| o MAX_LATENCY is the maximum time a datagram is expected to take | o MAX_LATENCY is the maximum time a datagram is expected to take | |||
| from the start of its transmission to the completion of its | from the start of its transmission to the completion of its | |||
| reception. This constant is related to the MSL (Maximum Segment | reception. This constant is related to the MSL (Maximum Segment | |||
| Lifetime) of [RFC0793], which is "arbitrarily defined to be 2 | Lifetime) of [RFC0793], which is "arbitrarily defined to be 2 | |||
| minutes" ([RFC0793] glossary, page 81). Note that this is not | minutes" ([RFC0793] glossary, page 81). Note that this is not | |||
| necessarily smaller than MAX_TRANSMIT_WAIT, as MAX_LATENCY is not | necessarily smaller than MAX_TRANSMIT_WAIT, as MAX_LATENCY is not | |||
| intended to describe a situation when the protocol works well, but | intended to describe a situation when the protocol works well, but | |||
| the worst case situation against which the protocol has to guard. | the worst case situation against which the protocol has to guard. | |||
| We, also arbitrarily, define MAX_LATENCY to be 100 seconds. Apart | We, also arbitrarily, define MAX_LATENCY to be 100 seconds. Apart | |||
| from being reasonably realistic for the bulk of configurations as | from being reasonably realistic for the bulk of configurations as | |||
| well as close to the historic choice for TCP, this value also | well as close to the historic choice for TCP, this value also | |||
| allows Message ID lifetime timers to be represented in 8 bits | allows Message ID lifetime timers to be represented in 8 bits | |||
| (when measured in seconds). In these calculations, there is no | (when measured in seconds). In these calculations, there is no | |||
| assumption that the direction of the transmission is irrelevant | assumption that the direction of the transmission is irrelevant | |||
| (i.e. that the network is symmetric), just that the same value can | (i.e. that the network is symmetric), just that the same value | |||
| reasonably be used as a maximum value for both directions. If | can reasonably be used as a maximum value for both directions. If | |||
| that is not the case, the following calculations become only | that is not the case, the following calculations become only | |||
| slightly more complex. | slightly more complex. | |||
| o PROCESSING_DELAY is the time a node takes to turn around a | o PROCESSING_DELAY is the time a node takes to turn around a | |||
| Confirmable message into an acknowledgement. We assume the node | Confirmable message into an acknowledgement. We assume the node | |||
| will attempt to send an ACK before having the sender time out, so | will attempt to send an ACK before having the sender time out, so | |||
| as a conservative assumption we set it equal to ACK_TIMEOUT. | as a conservative assumption we set it equal to ACK_TIMEOUT. | |||
| o MAX_RTT is the maximum round-trip time, or: | o MAX_RTT is the maximum round-trip time, or: | |||
| 2 * MAX_LATENCY + PROCESSING_DELAY | (2 * MAX_LATENCY) + PROCESSING_DELAY | |||
| From these values, we can derive the following values relevant to the | From these values, we can derive the following values relevant to the | |||
| protocol operation: | protocol operation: | |||
| o EXCHANGE_LIFETIME is the time from starting to send a Confirmable | o EXCHANGE_LIFETIME is the time from starting to send a Confirmable | |||
| message to the time when an acknowledgement is no longer expected, | message to the time when an acknowledgement is no longer expected, | |||
| i.e. message layer information about the message exchange can be | i.e. message layer information about the message exchange can be | |||
| purged. EXCHANGE_LIFETIME includes a MAX_TRANSMIT_SPAN, a | purged. EXCHANGE_LIFETIME includes a MAX_TRANSMIT_SPAN, a | |||
| MAX_LATENCY forward, PROCESSING_DELAY, and a MAX_LATENCY for the | MAX_LATENCY forward, PROCESSING_DELAY, and a MAX_LATENCY for the | |||
| way back. Note that there is no need to consider | way back. Note that there is no need to consider | |||
| MAX_TRANSMIT_WAIT if the configuration is chosen such that the | MAX_TRANSMIT_WAIT if the configuration is chosen such that the | |||
| last waiting period (ACK_TIMEOUT * (2 ** MAX_RETRANSMIT) or the | last waiting period (ACK_TIMEOUT * (2 ** MAX_RETRANSMIT) or the | |||
| difference between MAX_TRANSMIT_SPAN and MAX_TRANSMIT_WAIT) is | difference between MAX_TRANSMIT_SPAN and MAX_TRANSMIT_WAIT) is | |||
| less than MAX_LATENCY -- which is a likely choice, as MAX_LATENCY | less than MAX_LATENCY -- which is a likely choice, as MAX_LATENCY | |||
| is a worst case value unlikely to be met in the real world. In | is a worst case value unlikely to be met in the real world. In | |||
| this case, EXCHANGE_LIFETIME simplifies to: | this case, EXCHANGE_LIFETIME simplifies to: | |||
| skipping to change at page 28, line 26 ¶ | skipping to change at page 29, line 45 ¶ | |||
| NON message multiple times, in particular for multicast | NON message multiple times, in particular for multicast | |||
| applications. While the period of re-use is not bounded by the | applications. While the period of re-use is not bounded by the | |||
| specification, an expectation of reliable detection of duplication | specification, an expectation of reliable detection of duplication | |||
| at the receiver is in the timescales of MAX_TRANSMIT_SPAN. | at the receiver is in the timescales of MAX_TRANSMIT_SPAN. | |||
| Therefore, for this purpose, it is safer to use the value: | Therefore, for this purpose, it is safer to use the value: | |||
| MAX_TRANSMIT_SPAN + MAX_LATENCY | MAX_TRANSMIT_SPAN + MAX_LATENCY | |||
| or 145 seconds with the default transmission parameters; however, | or 145 seconds with the default transmission parameters; however, | |||
| an implementation that just wants to use a single timeout value | an implementation that just wants to use a single timeout value | |||
| for retiring Messagen IDs can safely use the larger value for | for retiring Message IDs can safely use the larger value for | |||
| EXCHANGE_LIFETIME. | EXCHANGE_LIFETIME. | |||
| Table 2 summarizes the derived parameters introduced in this | Table 3 summarizes the derived parameters introduced in this | |||
| subsection with their default values. | subsection with their default values. | |||
| +-------------------+---------------+ | +-------------------+---------------+ | |||
| | name | default value | | | name | default value | | |||
| +-------------------+---------------+ | +-------------------+---------------+ | |||
| | MAX_TRANSMIT_SPAN | 45 s | | | MAX_TRANSMIT_SPAN | 45 s | | |||
| | MAX_TRANSMIT_WAIT | 93 s | | | MAX_TRANSMIT_WAIT | 93 s | | |||
| | MAX_LATENCY | 100 s | | | MAX_LATENCY | 100 s | | |||
| | PROCESSING_DELAY | 2 s | | | PROCESSING_DELAY | 2 s | | |||
| | MAX_RTT | 202 s | | | MAX_RTT | 202 s | | |||
| | EXCHANGE_LIFETIME | 247 s | | | EXCHANGE_LIFETIME | 247 s | | |||
| | NON_LIFETIME | 145 s | | | NON_LIFETIME | 145 s | | |||
| +-------------------+---------------+ | +-------------------+---------------+ | |||
| Table 2: Derived Protocol Parameters | Table 3: Derived Protocol Parameters | |||
| 5. Request/Response Semantics | 5. Request/Response Semantics | |||
| CoAP operates under a similar request/response model as HTTP: a CoAP | CoAP operates under a similar request/response model as HTTP: a CoAP | |||
| endpoint in the role of a "client" sends one or more CoAP requests to | endpoint in the role of a "client" sends one or more CoAP requests to | |||
| a "server", which services the requests by sending CoAP responses. | a "server", which services the requests by sending CoAP responses. | |||
| Unlike HTTP, requests and responses are not sent over a previously | Unlike HTTP, requests and responses are not sent over a previously | |||
| established connection, but exchanged asynchronously over CoAP | established connection, but exchanged asynchronously over CoAP | |||
| messages. | messages. | |||
| 5.1. Requests | 5.1. Requests | |||
| A CoAP request consists of the method to be applied to the resource, | A CoAP request consists of the method to be applied to the resource, | |||
| the identifier of the resource, a payload and Internet media type (if | the identifier of the resource, a payload and Internet media type (if | |||
| any), and optional meta-data about the request. | any), and optional meta-data about the request. | |||
| skipping to change at page 29, line 33 ¶ | skipping to change at page 31, line 4 ¶ | |||
| dependent on the target resource; it usually results in a new | dependent on the target resource; it usually results in a new | |||
| resource being created or the target resource being updated. | resource being created or the target resource being updated. | |||
| A request is initiated by setting the Code field in the CoAP header | A request is initiated by setting the Code field in the CoAP header | |||
| of a Confirmable or a Non-confirmable message to a Method Code and | of a Confirmable or a Non-confirmable message to a Method Code and | |||
| including request information. | including request information. | |||
| The methods used in requests are described in detail in Section 5.8. | The methods used in requests are described in detail in Section 5.8. | |||
| 5.2. Responses | 5.2. Responses | |||
| After receiving and interpreting a request, a server responds with a | After receiving and interpreting a request, a server responds with a | |||
| CoAP response, which is matched to the request by means of a client- | CoAP response, which is matched to the request by means of a client- | |||
| generated token (Section 5.3, note that this is different from the | generated token (Section 5.3, note that this is different from the | |||
| Message ID that matches a Confirmable message to its | Message ID that matches a Confirmable message to its | |||
| Acknowledgement). | Acknowledgement). | |||
| A response is identified by the Code field in the CoAP header being | A response is identified by the Code field in the CoAP header being | |||
| set to a Response Code. Similar to the HTTP Status Code, the CoAP | set to a Response Code. Similar to the HTTP Status Code, the CoAP | |||
| Response Code indicates the result of the attempt to understand and | Response Code indicates the result of the attempt to understand and | |||
| satisfy the request. These codes are fully defined in Section 5.9. | satisfy the request. These codes are fully defined in Section 5.9. | |||
| The Response Code numbers to be set in the Code field of the CoAP | The Response Code numbers to be set in the Code field of the CoAP | |||
| header are maintained in the CoAP Response Code Registry | header are maintained in the CoAP Response Code Registry | |||
| (Section 12.1.2). | (Section 12.1.2). | |||
| 0 | 0 | |||
| 0 1 2 3 4 5 6 7 | 0 1 2 3 4 5 6 7 | |||
| +-+-+-+-+-+-+-+-+ | +-+-+-+-+-+-+-+-+ | |||
| |class| detail | | |class| detail | | |||
| +-+-+-+-+-+-+-+-+ | +-+-+-+-+-+-+-+-+ | |||
| Figure 9: Structure of a Response Code | Figure 9: Structure of a Response Code | |||
| The upper three bits of the 8-bit Response Code number define the | The upper three bits of the 8-bit Response Code number define the | |||
| class of response. The lower five bits do not have any | class of response. The lower five bits do not have any | |||
| categorization role; they give additional detail to the overall class | categorization role; they give additional detail to the overall class | |||
| (Figure 9). | (Figure 9). | |||
| As a human readable notation for specifications and protocol | As a human readable notation for specifications and protocol | |||
| diagnostics, the response code is documented in the format "c.dd", | diagnostics, CoAP code numbers including the response code are | |||
| where "c" is the class in decimal, and "dd" is the detail as a two- | documented in the format "c.dd", where "c" is the class in decimal, | |||
| digit decimal. For example, "Forbidden" is written as 4.03 -- | and "dd" is the detail as a two-digit decimal. For example, | |||
| indicating a value of 4*32+3, hexadecimal 0x83 or decimal 131. | "Forbidden" is written as 4.03 -- indicating an 8-bit code value of | |||
| hexadecimal 0x83 (4*0x20+3) or decimal 131 (4*32+3). | ||||
| There are 3 classes: | There are 3 classes of response codes: | |||
| 2 - Success: The request was successfully received, understood, and | 2 - Success: The request was successfully received, understood, and | |||
| accepted. | accepted. | |||
| 4 - Client Error: The request contains bad syntax or cannot be | 4 - Client Error: The request contains bad syntax or cannot be | |||
| fulfilled. | fulfilled. | |||
| 5 - Server Error: The server failed to fulfill an apparently valid | 5 - Server Error: The server failed to fulfill an apparently valid | |||
| request. | request. | |||
| The response codes are designed to be extensible: Response Codes in | The response codes are designed to be extensible: Response Codes in | |||
| the Client Error and Server Error class that are unrecognized by an | the Client Error and Server Error class that are unrecognized by an | |||
| endpoint MUST be treated as being equivalent to the generic Response | endpoint are treated as being equivalent to the generic Response Code | |||
| Code of that class (4.00 and 5.00, respectively). However, there is | of that class (4.00 and 5.00, respectively). However, there is no | |||
| no generic Response Code indicating success, so a Response Code in | generic Response Code indicating success, so a Response Code in the | |||
| the Success class that is unrecognized by an endpoint can only be | Success class that is unrecognized by an endpoint can only be used to | |||
| used to determine that the request was successful without any further | determine that the request was successful without any further | |||
| details. | details. | |||
| The possible response codes are described in detail in Section 5.9. | The possible response codes are described in detail in Section 5.9. | |||
| Responses can be sent in multiple ways, which are defined in the | Responses can be sent in multiple ways, which are defined in the | |||
| following subsections. | following subsections. | |||
| 5.2.1. Piggy-backed | 5.2.1. Piggy-backed | |||
| In the most basic case, the response is carried directly in the | In the most basic case, the response is carried directly in the | |||
| skipping to change at page 31, line 31 ¶ | skipping to change at page 32, line 46 ¶ | |||
| It may not be possible to return a piggy-backed response in all | It may not be possible to return a piggy-backed response in all | |||
| cases. For example, a server might need longer to obtain the | cases. For example, a server might need longer to obtain the | |||
| representation of the resource requested than it can wait sending | representation of the resource requested than it can wait sending | |||
| back the Acknowledgement message, without risking the client to | back the Acknowledgement message, without risking the client to | |||
| repeatedly retransmit the request message (see also the discussion of | repeatedly retransmit the request message (see also the discussion of | |||
| PROCESSING_DELAY in Section 4.8.2). The Response to a request | PROCESSING_DELAY in Section 4.8.2). The Response to a request | |||
| carried in a Non-confirmable message is always sent separately (as | carried in a Non-confirmable message is always sent separately (as | |||
| there is no Acknowledgement message). | there is no Acknowledgement message). | |||
| The server maybe initiates the attempt to obtain the resource | One way to implement this in a server is to initiate the attempt to | |||
| representation and times out an acknowledgement timer, or it | obtain the resource representation and, while that is in progress, | |||
| immediately sends an acknowledgement knowing in advance that there | time out an acknowledgement timer. A server may also immediately | |||
| will be no piggy-backed response. The acknowledgement effectively is | send an acknowledgement knowing in advance that there will be no | |||
| a promise that the request will be acted upon. | piggy-backed response. In both cases, the acknowledgement | |||
| effectively is a promise that the request will be acted upon later. | ||||
| When the server finally has obtained the resource representation, it | When the server finally has obtained the resource representation, it | |||
| sends the response. When it is desired that this message is not | sends the response. When it is desired that this message is not | |||
| lost, it is sent as a Confirmable message from the server to the | lost, it is sent as a Confirmable message from the server to the | |||
| client and answered by the client with an Acknowledgement, echoing | client and answered by the client with an Acknowledgement, echoing | |||
| the new Message ID chosen by the server. (It may also be sent as a | the new Message ID chosen by the server. (It may also be sent as a | |||
| Non-confirmable message; see Section 5.2.3.) | Non-confirmable message; see Section 5.2.3.) | |||
| When the server chooses to use a separate response, it sends the | When the server chooses to use a separate response, it sends the | |||
| Acknowledgement to the Confirmable request as an empty message. If | Acknowledgement to the Confirmable request as an Empty message. Once | |||
| the server then sends a Confirmable response, the client's | the server sends back an Empty Acknowledgement, it MUST NOT send back | |||
| Acknowledgement to that response MUST also be an empty message (one | the response in another Acknowledgement, even if the client | |||
| retransmits another identical request. If a retransmitted request is | ||||
| received (perhaps because the original Acknowledgement was delayed), | ||||
| another Empty Acknowledgement is sent and any response MUST be sent | ||||
| as a separate response. | ||||
| If the server then sends a Confirmable response, the client's | ||||
| Acknowledgement to that response MUST also be an Empty message (one | ||||
| that carries neither a request nor a response). The server MUST stop | that carries neither a request nor a response). The server MUST stop | |||
| retransmitting its response on any matching Acknowledgement (silently | retransmitting its response on any matching Acknowledgement (silently | |||
| ignoring any response code or payload) or Reset message. | ignoring any response code or payload) or Reset message. | |||
| Implementation Notes: Note that, as the underlying datagram | Implementation Notes: Note that, as the underlying datagram | |||
| transport may not be sequence-preserving, the Confirmable message | transport may not be sequence-preserving, the Confirmable message | |||
| carrying the response may actually arrive before or after the | carrying the response may actually arrive before or after the | |||
| Acknowledgement message for the request; for the purposes of | Acknowledgement message for the request; for the purposes of | |||
| terminating the retransmission sequence, this also serves as an | terminating the retransmission sequence, this also serves as an | |||
| acknowledgement. Note also that, while the CoAP protocol itself | acknowledgement. Note also that, while the CoAP protocol itself | |||
| skipping to change at page 32, line 24 ¶ | skipping to change at page 33, line 46 ¶ | |||
| transport protocol that could be instructed to run a keep-alive | transport protocol that could be instructed to run a keep-alive | |||
| mechanism, the requester may want to set up a timeout that is | mechanism, the requester may want to set up a timeout that is | |||
| unrelated to CoAP's retransmission timers in case the server is | unrelated to CoAP's retransmission timers in case the server is | |||
| destroyed or otherwise unable to send the response.) | destroyed or otherwise unable to send the response.) | |||
| 5.2.3. Non-confirmable | 5.2.3. Non-confirmable | |||
| If the request message is Non-confirmable, then the response SHOULD | If the request message is Non-confirmable, then the response SHOULD | |||
| be returned in a Non-confirmable message as well. However, an | be returned in a Non-confirmable message as well. However, an | |||
| endpoint MUST be prepared to receive a Non-confirmable response | endpoint MUST be prepared to receive a Non-confirmable response | |||
| (preceded or followed by an empty Acknowledgement message) in reply | (preceded or followed by an Empty Acknowledgement message) in reply | |||
| to a Confirmable request, or a Confirmable response in reply to a | to a Confirmable request, or a Confirmable response in reply to a | |||
| Non-confirmable request. | Non-confirmable request. | |||
| 5.3. Request/Response Matching | 5.3. Request/Response Matching | |||
| Regardless of how a response is sent, it is matched to the request by | Regardless of how a response is sent, it is matched to the request by | |||
| means of a token that is included by the client in the request, along | means of a token that is included by the client in the request, along | |||
| with additional address information of the corresponding endpoint. | with additional address information of the corresponding endpoint. | |||
| 5.3.1. Token | 5.3.1. Token | |||
| The Token is used to match a response with a request. The token | The Token is used to match a response with a request. The token | |||
| value is a sequence of 0 to 8 bytes. (Note that every message | value is a sequence of 0 to 8 bytes. (Note that every message | |||
| carries a token, even if it is of zero length.) Every request | carries a token, even if it is of zero length.) Every request | |||
| carries a client-generated token, which the server MUST echo in any | carries a client-generated token, which the server MUST echo in any | |||
| resulting response without modification. | resulting response without modification. | |||
| A token is intended for use as a client-local identifier for | A token is intended for use as a client-local identifier for | |||
| differentiating between concurrent requests (see Section 5.3); it | differentiating between concurrent requests (see Section 5.3); it | |||
| could have been called a "request ID". | could have been called a "request ID". | |||
| The client SHOULD generate tokens in such a way that tokens currently | The client SHOULD generate tokens in such a way that tokens currently | |||
| in use for a given source/destination endpoint pair are unique. | in use for a given source/destination endpoint pair are unique. | |||
| (Note that a client implementation can use the same token for any | (Note that a client implementation can use the same token for any | |||
| request if it uses a different endpoint each time, e.g. a different | request if it uses a different endpoint each time, e.g. a different | |||
| source port number.) An empty token value is appropriate e.g. when | source port number.) An empty token value is appropriate e.g. when | |||
| no other tokens are in use to a destination, or when requests are | no other tokens are in use to a destination, or when requests are | |||
| made serially per destination and receive piggy-backed responses. | made serially per destination and receive piggy-backed responses. | |||
| There are however multiple possible implementation strategies to | There are however multiple possible implementation strategies to | |||
| fulfill this. | fulfill this. | |||
| A client sending a request without using transport layer security | A client sending a request without using transport layer security | |||
| (Section 9) may want to use a non-trivial, randomized token if it is | (Section 9) SHOULD use a non-trivial, randomized token to guard | |||
| desirable to guard against spoofing of responses (Section 11.4). | against spoofing of responses (Section 11.4). This protective use of | |||
| This protective use of tokens is the reason they are allowed to be up | tokens is the reason they are allowed to be up to 8 bytes in size. | |||
| to 8 bytes in size. | The actual size of the random component to be used for the Token | |||
| depends on the security requirements of the client and the level of | ||||
| threat posed by spoofing of responses. A client that is connected to | ||||
| the general Internet SHOULD use at least 32 bits of randomness; | ||||
| keeping in mind that not being directly connected to the Internet is | ||||
| not necessarily sufficient protection against spoofing. (Note that | ||||
| the Message ID adds little in protection as it is usually | ||||
| sequentially assigned, i.e. guessable, and can be circumvented by | ||||
| spoofing a separate response.) Clients that want to optimize the | ||||
| Token length may further want to detect the level of ongoing attacks | ||||
| (e.g., by tallying recent Token mismatches in incoming messages) and | ||||
| adjust the Token length upwards appropriately. [RFC4086] discusses | ||||
| randomness requirements for security. | ||||
| An endpoint receiving a token it did not generate MUST treat it as | An endpoint receiving a token it did not generate MUST treat it as | |||
| opaque and make no assumptions about its content or structure. | opaque and make no assumptions about its content or structure. | |||
| 5.3.2. Request/Response Matching Rules | 5.3.2. Request/Response Matching Rules | |||
| The exact rules for matching a response to a request are as follows: | The exact rules for matching a response to a request are as follows: | |||
| 1. The source endpoint of the response MUST be the same as the | 1. The source endpoint of the response MUST be the same as the | |||
| destination endpoint of the original request. | destination endpoint of the original request. | |||
| skipping to change at page 33, line 40 ¶ | skipping to change at page 35, line 28 ¶ | |||
| In case a message carrying a response is unexpected (the client is | In case a message carrying a response is unexpected (the client is | |||
| not waiting for a response from the identified endpoint, at the | not waiting for a response from the identified endpoint, at the | |||
| endpoint addressed, and/or with the given token), the response is | endpoint addressed, and/or with the given token), the response is | |||
| rejected (Section 4.2, Section 4.3). | rejected (Section 4.2, Section 4.3). | |||
| Implementation Note: A client that receives a response in a CON | Implementation Note: A client that receives a response in a CON | |||
| message may want to clean up the message state right after sending | message may want to clean up the message state right after sending | |||
| the ACK. If that ACK is lost and the server retransmits the CON, | the ACK. If that ACK is lost and the server retransmits the CON, | |||
| the client may no longer have any state to correlate this response | the client may no longer have any state to correlate this response | |||
| to, making the retransmission an unexpected message; the client | to, making the retransmission an unexpected message; the client | |||
| may send a Reset message so it does not receive any more | will likely send a Reset message so it does not receive any more | |||
| retransmissions. This behavior is normal and not an indication of | retransmissions. This behavior is normal and not an indication of | |||
| an error. (Clients that are not aggressively optimized in their | an error. (Clients that are not aggressively optimized in their | |||
| state memory usage will still have message state that will | state memory usage will still have message state that will | |||
| identify the second CON as a retransmission. Clients that | identify the second CON as a retransmission. Clients that | |||
| actually expect more messages from the server | actually expect more messages from the server | |||
| [I-D.ietf-core-observe] will have to keep state in any case.) | [I-D.ietf-core-observe] will have to keep state in any case.) | |||
| 5.4. Options | 5.4. Options | |||
| Both requests and responses may include a list of one or more | Both requests and responses may include a list of one or more | |||
| skipping to change at page 34, line 16 ¶ | skipping to change at page 36, line 4 ¶ | |||
| CoAP defines a single set of options that are used in both requests | CoAP defines a single set of options that are used in both requests | |||
| and responses: | and responses: | |||
| o Content-Format | o Content-Format | |||
| o ETag | o ETag | |||
| o Location-Path | o Location-Path | |||
| o Location-Query | o Location-Query | |||
| o Max-Age | o Max-Age | |||
| o Proxy-Uri | o Proxy-Uri | |||
| o Proxy-Scheme | o Proxy-Scheme | |||
| o Uri-Host | o Uri-Host | |||
| o Uri-Path | o Uri-Path | |||
| o Uri-Port | o Uri-Port | |||
| o Uri-Query | o Uri-Query | |||
| o Accept | o Accept | |||
| o If-Match | o If-Match | |||
| o If-None-Match | o If-None-Match | |||
| o Size1 | ||||
| The semantics of these options along with their properties are | The semantics of these options along with their properties are | |||
| defined in detail in Section 5.10. | defined in detail in Section 5.10. | |||
| Not all options are defined for use with all methods and response | Not all options are defined for use with all methods and response | |||
| codes. The possible options for methods and response codes are | codes. The possible options for methods and response codes are | |||
| defined in Section 5.8 and Section 5.9 respectively. In case an | defined in Section 5.8 and Section 5.9 respectively. In case an | |||
| option is not defined for a method or response code, it MUST NOT be | option is not defined for a method or response code, it MUST NOT be | |||
| included by a sender and MUST be treated like an unrecognized option | included by a sender and MUST be treated like an unrecognized option | |||
| by a recipient. | by a recipient. | |||
| skipping to change at page 35, line 27 ¶ | skipping to change at page 37, line 19 ¶ | |||
| o Unrecognized options of class "critical" that occur in a Non- | o Unrecognized options of class "critical" that occur in a Non- | |||
| confirmable message MUST cause the message to be rejected | confirmable message MUST cause the message to be rejected | |||
| (Section 4.3). | (Section 4.3). | |||
| Note that, whether critical or elective, an option is never | Note that, whether critical or elective, an option is never | |||
| "mandatory" (it is always optional): These rules are defined in order | "mandatory" (it is always optional): These rules are defined in order | |||
| to enable implementations to stop processing options they do not | to enable implementations to stop processing options they do not | |||
| understand or implement. | understand or implement. | |||
| Critical/Elective rules apply to non-proxying endpoints. A proxy | Critical/Elective rules apply to non-proxying endpoints. A proxy | |||
| processes options based on Unsafe/Safe classes as defined in | processes options based on Unsafe/Safe-to-Forward classes as defined | |||
| Section 5.7. | in Section 5.7. | |||
| 5.4.2. Proxy Unsafe/Safe and Cache-Key | 5.4.2. Proxy Unsafe/Safe-to-Forward and NoCacheKey | |||
| In addition to an option being marked as Critical or Elective, | In addition to an option being marked as Critical or Elective, | |||
| options are also classified based on how a proxy is to deal with the | options are also classified based on how a proxy is to deal with the | |||
| option if it does not recognize it. For this purpose, an option can | option if it does not recognize it. For this purpose, an option can | |||
| either be considered Unsafe to Forward (UnSafe is set) or Safe to | either be considered Unsafe to Forward (UnSafe is set) or Safe-to- | |||
| Forward (UnSafe is clear). | Forward (UnSafe is clear). | |||
| In addition, for options that are marked Safe to Forward, the option | In addition, for an option that is marked Safe-to-Forward, the option | |||
| indicates whether it is intended to be part of the Cache-Key in a | number indicates whether it is intended to be part of the Cache-Key | |||
| request (some of the NoCacheKey bits are 0) or not (all NoCacheKey | (Section 5.6) in a request or not; if some of the NoCacheKey bits are | |||
| bits are 1; see Section 5.4.6). | 0, it is, if all NoCacheKey bits are 1, it is not (see | |||
| Section 5.4.6). | ||||
| Note: The Cache-Key indication is relevant only for proxies that do | Note: The Cache-Key indication is relevant only for proxies that do | |||
| not implement the given option as a request option and instead | not implement the given option as a request option and instead | |||
| rely on the Safe/Unsafe indication only. E.g., for ETag, actually | rely on the Unsafe/Safe-to-Forward indication only. E.g., for | |||
| using the request option as a cache key is grossly inefficient, | ETag, actually using the request option as a part of the Cache-Key | |||
| but it is the best thing one can do if ETag is not implemented by | is grossly inefficient, but it is the best thing one can do if | |||
| a proxy, as the response is going to differ based on the presence | ETag is not implemented by a proxy, as the response is going to | |||
| of the request option. A more useful proxy that does implement | differ based on the presence of the request option. A more useful | |||
| the ETag request option is not using ETag as a cache key. | proxy that does implement the ETag request option is not using | |||
| ETag as a part of the Cache-Key. | ||||
| NoCacheKey is indicated in three bits so that only one out of | NoCacheKey is indicated in three bits so that only one out of | |||
| eight codepoints is qualified as NoCacheKey, assuming this is the | eight codepoints is qualified as NoCacheKey, assuming this is the | |||
| less likely case. | less likely case. | |||
| Proxy behavior with regard to these classes is defined in | Proxy behavior with regard to these classes is defined in | |||
| Section 5.7. | Section 5.7. | |||
| 5.4.3. Length | 5.4.3. Length | |||
| skipping to change at page 36, line 40 ¶ | skipping to change at page 38, line 33 ¶ | |||
| default value for the option. | default value for the option. | |||
| 5.4.5. Repeatable Options | 5.4.5. Repeatable Options | |||
| The definition of some options specifies that those options are | The definition of some options specifies that those options are | |||
| repeatable. An option that is repeatable MAY be included one or more | repeatable. An option that is repeatable MAY be included one or more | |||
| times in a message. An option that is not repeatable MUST NOT be | times in a message. An option that is not repeatable MUST NOT be | |||
| included more than once in a message. | included more than once in a message. | |||
| If a message includes an option with more occurrences than the option | If a message includes an option with more occurrences than the option | |||
| is defined for, the additional option occurrences MUST be treated | is defined for, each supernumerary option occurrence that appears | |||
| like an unrecognized option (see Section 5.4.1). | subsequently in the message MUST be treated like an unrecognized | |||
| option (see Section 5.4.1). | ||||
| 5.4.6. Option Numbers | 5.4.6. Option Numbers | |||
| An Option is identified by an option number, which also provides some | An Option is identified by an option number, which also provides some | |||
| additional semantics information: e.g., odd numbers indicate a | additional semantics information: e.g., odd numbers indicate a | |||
| critical option, while even numbers indicate an elective option. | critical option, while even numbers indicate an elective option. | |||
| Note that this is not just a convention, it is a feature of the | Note that this is not just a convention, it is a feature of the | |||
| protocol: Whether an option is elective or critical is entirely | protocol: Whether an option is elective or critical is entirely | |||
| determined by whether its option number is even or odd. | determined by whether its option number is even or odd. | |||
| More generally speaking, an Option number is constructed with a bit | More generally speaking, an Option number is constructed with a bit | |||
| mask to indicate if an option is Critical/Elective, Unsafe/Safe and | mask to indicate if an option is Critical/Elective, Unsafe/Safe-to- | |||
| in the case of Safe, also a Cache-Key indication as shown by the | Forward and in the case of Safe-to-Forward, also a Cache-Key | |||
| following figure. When bit 7 (the least significant bit) is 1, an | indication as shown by the following figure. In the following text, | |||
| the bit mask is expressed as a single byte that is applied to the | ||||
| least significant byte of the option number in unsigned integer | ||||
| representation. When bit 7 (the least significant bit) is 1, an | ||||
| option is Critical (and likewise Elective when 0). When bit 6 is 1, | option is Critical (and likewise Elective when 0). When bit 6 is 1, | |||
| an option is Unsafe (and likewise Safe when 0). When bit 6 is 0, | an option is Unsafe (and likewise Safe-to-Forward when 0). When bit | |||
| i.e., the option is not Unsafe, it is not a Cache-Key (NoCacheKey) if | 6 is 0, i.e., the option is not Unsafe, it is not a Cache-Key | |||
| and only if bits 3-5 are all set to 1; all other bit combinations | (NoCacheKey) if and only if bits 3-5 are all set to 1; all other bit | |||
| mean that it indeed is a Cache-Key. These classes of options are | combinations mean that it indeed is a Cache-Key. These classes of | |||
| explained in the next sections. | options are explained in the next sections. | |||
| 0 1 2 3 4 5 6 7 | 0 1 2 3 4 5 6 7 | |||
| +---+---+---+---+---+---+---+---+ | +---+---+---+---+---+---+---+---+ | |||
| | | NoCacheKey| U | C | | | | NoCacheKey| U | C | | |||
| +---+---+---+---+---+---+---+---+ | +---+---+---+---+---+---+---+---+ | |||
| Figure 10: Option Number Mask | Figure 10: Option Number Mask (Least Significant Byte) | |||
| An endpoint may use an equivalent of the C code in Figure 11 to | An endpoint may use an equivalent of the C code in Figure 11 to | |||
| derive the characteristics of an option number "onum". | derive the characteristics of an option number "onum". | |||
| Critical = (onum & 1); | Critical = (onum & 1); | |||
| UnSafe = (onum & 2); | UnSafe = (onum & 2); | |||
| NoCacheKey = ((onum & 0x1e) == 0x1c); | NoCacheKey = ((onum & 0x1e) == 0x1c); | |||
| Figure 11: Determining Characteristics from an Option Number | Figure 11: Determining Characteristics from an Option Number | |||
| skipping to change at page 37, line 43 ¶ | skipping to change at page 39, line 40 ¶ | |||
| 5.5. Payloads and Representations | 5.5. Payloads and Representations | |||
| Both requests and responses may include a payload, depending on the | Both requests and responses may include a payload, depending on the | |||
| method or response code respectively. If a method or response code | method or response code respectively. If a method or response code | |||
| is not defined to have a payload, then a sender MUST NOT include one, | is not defined to have a payload, then a sender MUST NOT include one, | |||
| and a recipient MUST ignore it. | and a recipient MUST ignore it. | |||
| 5.5.1. Representation | 5.5.1. Representation | |||
| The payload of requests or of responses indicating success is | The payload of requests or of responses indicating success is | |||
| typically a representation of a resource or the result of the | typically a representation of a resource ("resource representation") | |||
| requested action. Its format is specified by the Internet media type | or the result of the requested action ("action result"). Its format | |||
| and content coding given by the Content-Format Option. In the | is specified by the Internet media type and content coding given by | |||
| absence of this option, no default value is assumed and the format | the Content-Format Option. In the absence of this option, no default | |||
| will need to be inferred by the application (e.g., from the | value is assumed and the format will need to be inferred by the | |||
| application context). Payload "sniffing" SHOULD only be attempted if | application (e.g., from the application context). Payload "sniffing" | |||
| no content type is given. | SHOULD only be attempted if no content type is given. | |||
| Implementation Note: On a quality of implementation level, there is | Implementation Note: On a quality of implementation level, there is | |||
| a strong expectation that a Content-Format indication will be | a strong expectation that a Content-Format indication will be | |||
| provided with resource representations whenever possible. This is | provided with resource representations whenever possible. This is | |||
| not a "SHOULD"-level requirement solely because it is not a | not a "SHOULD"-level requirement solely because it is not a | |||
| protocol requirement, and it also would be difficult to outline | protocol requirement, and it also would be difficult to outline | |||
| exactly in what cases this expectation can be violated. | exactly in what cases this expectation can be violated. | |||
| For responses indicating a client or server error, the payload is | For responses indicating a client or server error, the payload is | |||
| considered a representation of the result of the requested action | considered a representation of the result of the requested action | |||
| skipping to change at page 40, line 5 ¶ | skipping to change at page 42, line 5 ¶ | |||
| of the request used to obtain the stored response (which includes | of the request used to obtain the stored response (which includes | |||
| the request URI), except that there is no need for a match of any | the request URI), except that there is no need for a match of any | |||
| request options marked as NoCacheKey (Section 5.4) or recognized | request options marked as NoCacheKey (Section 5.4) or recognized | |||
| by the Cache and fully interpreted with respect to its specified | by the Cache and fully interpreted with respect to its specified | |||
| cache behavior (such as the ETag request option, Section 5.10.6, | cache behavior (such as the ETag request option, Section 5.10.6, | |||
| see also Section 5.4.2), and | see also Section 5.4.2), and | |||
| o the stored response is either fresh or successfully validated as | o the stored response is either fresh or successfully validated as | |||
| defined below. | defined below. | |||
| The set of request options that is used for matching the cache entry | ||||
| is also collectively referred to as the "Cache-Key". For URI schemes | ||||
| other than coap and coaps, matching of those options that constitute | ||||
| the request URI may be performed under rules specific to the URI | ||||
| scheme. | ||||
| 5.6.1. Freshness Model | 5.6.1. Freshness Model | |||
| When a response is "fresh" in the cache, it can be used to satisfy | When a response is "fresh" in the cache, it can be used to satisfy | |||
| subsequent requests without contacting the origin server, thereby | subsequent requests without contacting the origin server, thereby | |||
| improving efficiency. | improving efficiency. | |||
| The mechanism for determining freshness is for an origin server to | The mechanism for determining freshness is for an origin server to | |||
| provide an explicit expiration time in the future, using the Max-Age | provide an explicit expiration time in the future, using the Max-Age | |||
| Option (see Section 5.10.5). The Max-Age Option indicates that the | Option (see Section 5.10.5). The Max-Age Option indicates that the | |||
| response is to be considered not fresh after its age is greater than | response is to be considered not fresh after its age is greater than | |||
| skipping to change at page 41, line 31 ¶ | skipping to change at page 43, line 38 ¶ | |||
| "cross"). | "cross"). | |||
| HTTP proxies, besides acting as HTTP proxies, often offer a | HTTP proxies, besides acting as HTTP proxies, often offer a | |||
| transport protocol proxying function ("CONNECT") to enable end-to- | transport protocol proxying function ("CONNECT") to enable end-to- | |||
| end transport layer security through the proxy. No such function | end transport layer security through the proxy. No such function | |||
| is defined for CoAP-to-CoAP proxies in this specification, as | is defined for CoAP-to-CoAP proxies in this specification, as | |||
| forwarding of UDP packets is unlikely to be of much value in | forwarding of UDP packets is unlikely to be of much value in | |||
| Constrained RESTful environments. See also Section 10.2.7 for the | Constrained RESTful environments. See also Section 10.2.7 for the | |||
| cross-proxy case. | cross-proxy case. | |||
| When a client uses a proxy to make a request that will use a secure | ||||
| URI scheme (e.g., coaps or https), the request towards the proxy | ||||
| SHOULD be sent using DTLS security except where equivalent lower | ||||
| layer security is used for the leg between the client and the proxy. | ||||
| 5.7.1. Proxy Operation | 5.7.1. Proxy Operation | |||
| A proxy generally needs a way to determine potential request | A proxy generally needs a way to determine potential request | |||
| parameters for a request to a destination based on the request it | parameters for a request to a destination based on the request it | |||
| received. This way is fully specified for a forward-proxy, but may | received. This way is fully specified for a forward-proxy, but may | |||
| depend on the specific configuration for a reverse-proxy. In | depend on the specific configuration for a reverse-proxy. In | |||
| particular, the client of a reverse-proxy generally does not indicate | particular, the client of a reverse-proxy generally does not indicate | |||
| a locator for the destination, necessitating some form of namespace | a locator for the destination, necessitating some form of namespace | |||
| translation in the reverse-proxy. However, some aspects of the | translation in the reverse-proxy. However, some aspects of the | |||
| operation of proxies are common to all its forms. | operation of proxies are common to all its forms. | |||
| If a proxy does not employ a cache, then it simply forwards the | If a proxy does not employ a cache, then it simply forwards the | |||
| translated request to the determined destination. Otherwise, if it | translated request to the determined destination. Otherwise, if it | |||
| does employ a cache but does not have a stored response that matches | does employ a cache but does not have a stored response that matches | |||
| the translated request and is considered fresh, then it needs to | the translated request and is considered fresh, then it needs to | |||
| refresh its cache according to Section 5.6. For options in the | refresh its cache according to Section 5.6. For options in the | |||
| request that the proxy recognizes, it knows whether the option is | request that the proxy recognizes, it knows whether the option is | |||
| intended to act as part of the key used in looking up the cached | intended to act as part of the key used in looking up the cached | |||
| value or not. E.g., since requests for different Uri-Path values | value or not. E.g., since requests for different Uri-Path values | |||
| address different resources, Uri-Path values are always parts of the | address different resources, Uri-Path values are always part of the | |||
| cache key, while, e.g., Token values are never part of the cache key. | Cache-Key, while, e.g., Token values are never part of the Cache-Key. | |||
| For options that the proxy does not recognize but that are marked | For options that the proxy does not recognize but that are marked | |||
| Safe in the option number, the option also indicates whether it is to | Safe-to-Forward in the option number, the option also indicates | |||
| be included in the cache key (NoCacheKey is not all set) or not | whether it is to be included in the Cache-Key (NoCacheKey is not all | |||
| (NoCacheKey is all set). (Options that are unrecognized and marked | set) or not (NoCacheKey is all set). (Options that are unrecognized | |||
| Unsafe lead to 4.02 Bad Option.) | and marked Unsafe lead to 4.02 Bad Option.) | |||
| If the request to the destination times out, then a 5.04 (Gateway | If the request to the destination times out, then a 5.04 (Gateway | |||
| Timeout) response MUST be returned. If the request to the | Timeout) response MUST be returned. If the request to the | |||
| destination returns a response that cannot be processed by the proxy | destination returns a response that cannot be processed by the proxy | |||
| (e.g, due to unrecognized critical options, message format errors), | (e.g, due to unrecognized critical options, message format errors), | |||
| then a 5.02 (Bad Gateway) response MUST be returned. Otherwise, the | then a 5.02 (Bad Gateway) response MUST be returned. Otherwise, the | |||
| proxy returns the response to the client. | proxy returns the response to the client. | |||
| If a response is generated out of a cache, it MUST be generated with | If a response is generated out of a cache, the generated (or implied) | |||
| a Max-Age Option that does not extend the max-age originally set by | Max-Age Option MUST NOT extend the max-age originally set by the | |||
| the server, considering the time the resource representation spent in | server, considering the time the resource representation spent in the | |||
| the cache. E.g., the Max-Age Option could be adjusted by the proxy | cache. E.g., the Max-Age Option could be adjusted by the proxy for | |||
| for each response using the formula: | each response using the formula: | |||
| proxy-max-age = original-max-age - cache-age | proxy-max-age = original-max-age - cache-age | |||
| For example if a request is made to a proxied resource that was | For example if a request is made to a proxied resource that was | |||
| refreshed 20 seconds ago and had an original Max-Age of 60 seconds, | refreshed 20 seconds ago and had an original Max-Age of 60 seconds, | |||
| then that resource's proxied max-age is now 40 seconds. Considering | then that resource's proxied max-age is now 40 seconds. Considering | |||
| potential network delays on the way from the origin server, a proxy | potential network delays on the way from the origin server, a proxy | |||
| SHOULD be conservative in the max-age values offered. | should be conservative in the max-age values offered. | |||
| All options present in a proxy request MUST be processed at the | All options present in a proxy request MUST be processed at the | |||
| proxy. Unsafe options in a request that are not recognized by the | proxy. Unsafe options in a request that are not recognized by the | |||
| proxy MUST lead to a 4.02 (Bad Option) response being returned by the | proxy MUST lead to a 4.02 (Bad Option) response being returned by the | |||
| proxy. A CoAP-to-CoAP proxy MUST forward to the origin server all | proxy. A CoAP-to-CoAP proxy MUST forward to the origin server all | |||
| Safe options that it does not recognize. Similarly, Unsafe options | Safe-to-Forward options that it does not recognize. Similarly, | |||
| in a response that are not recognized by the CoAP-to-CoAP proxy | Unsafe options in a response that are not recognized by the CoAP-to- | |||
| server MUST lead to a 5.02 (Bad Gateway) response. Again, Safe | CoAP proxy server MUST lead to a 5.02 (Bad Gateway) response. Again, | |||
| options that are not recognized MUST be forwarded. | Safe-to-Forward options that are not recognized MUST be forwarded. | |||
| Additional considerations for cross-protocol proxying between CoAP | Additional considerations for cross-protocol proxying between CoAP | |||
| and HTTP are discussed in Section 10. | and HTTP are discussed in Section 10. | |||
| 5.7.2. Forward-Proxies | 5.7.2. Forward-Proxies | |||
| CoAP distinguishes between requests made (as if) to an origin server | CoAP distinguishes between requests made (as if) to an origin server | |||
| and a request made through a forward-proxy. CoAP requests to a | and a request made through a forward-proxy. CoAP requests to a | |||
| forward-proxy are made as normal Confirmable or Non-confirmable | forward-proxy are made as normal Confirmable or Non-confirmable | |||
| requests to the forward-proxy endpoint, but specify the request URI | requests to the forward-proxy endpoint, but specify the request URI | |||
| skipping to change at page 43, line 36 ¶ | skipping to change at page 45, line 46 ¶ | |||
| 5.7.3. Reverse-Proxies | 5.7.3. Reverse-Proxies | |||
| Reverse-proxies do not make use of the Proxy-Uri or Proxy-Scheme | Reverse-proxies do not make use of the Proxy-Uri or Proxy-Scheme | |||
| options, but need to determine the destination (next hop) of a | options, but need to determine the destination (next hop) of a | |||
| request from information in the request and information in their | request from information in the request and information in their | |||
| configuration. E.g., a reverse-proxy might offer various resources | configuration. E.g., a reverse-proxy might offer various resources | |||
| the existence of which it has learned through resource discovery as | the existence of which it has learned through resource discovery as | |||
| if they were its own resources. The reverse-proxy is free to build a | if they were its own resources. The reverse-proxy is free to build a | |||
| namespace for the URIs that identify these resources. A reverse- | namespace for the URIs that identify these resources. A reverse- | |||
| proxy may also build a namespace that gives the client more control | proxy may also build a namespace that gives the client more control | |||
| over where the request goes, e.g. by embedding host identifiers and | over where the request goes, e.g. by embedding host identifiers and | |||
| port numbers into the URI path of the resources offered. | port numbers into the URI path of the resources offered. | |||
| In processing the response, a reverse-proxy has to be careful that | In processing the response, a reverse-proxy has to be careful that | |||
| ETag option values from different sources are not mixed up on one | ETag option values from different sources are not mixed up on one | |||
| resource offered to its clients. In many cases, the ETag can be | resource offered to its clients. In many cases, the ETag can be | |||
| forwarded unchanged. If the mapping from a resource offered by the | forwarded unchanged. If the mapping from a resource offered by the | |||
| reverse-proxy to resources offered by its various origin servers is | reverse-proxy to resources offered by its various origin servers is | |||
| not unique, the reverse-proxy may need to generate a new ETag, making | not unique, the reverse-proxy may need to generate a new ETag, making | |||
| sure the semantics of this option are properly preserved. | sure the semantics of this option are properly preserved. | |||
| skipping to change at page 45, line 46 ¶ | skipping to change at page 48, line 7 ¶ | |||
| If the response includes one or more Location-Path and/or Location- | If the response includes one or more Location-Path and/or Location- | |||
| Query Options, the values of these options specify the location at | Query Options, the values of these options specify the location at | |||
| which the resource was created. Otherwise, the resource was created | which the resource was created. Otherwise, the resource was created | |||
| at the request URI. A cache receiving this response MUST mark any | at the request URI. A cache receiving this response MUST mark any | |||
| stored response for the created resource as not fresh. | stored response for the created resource as not fresh. | |||
| This response is not cacheable. | This response is not cacheable. | |||
| 5.9.1.2. 2.02 Deleted | 5.9.1.2. 2.02 Deleted | |||
| Like HTTP 204 "No Content", but only used in response to DELETE | Like HTTP 204 "No Content", but only used in response to requests | |||
| requests. The payload returned with the response, if any, is a | that cause the resource to cease being available, such as DELETE and | |||
| representation of the action result. | in certain circumstances POST. The payload returned with the | |||
| response, if any, is a representation of the action result. | ||||
| This response is not cacheable. However, a cache MUST mark any | This response is not cacheable. However, a cache MUST mark any | |||
| stored response for the deleted resource as not fresh. | stored response for the deleted resource as not fresh. | |||
| 5.9.1.3. 2.03 Valid | 5.9.1.3. 2.03 Valid | |||
| Related to HTTP 304 "Not Modified", but only used to indicate that | Related to HTTP 304 "Not Modified", but only used to indicate that | |||
| the response identified by the entity-tag identified by the included | the response identified by the entity-tag identified by the included | |||
| ETag Option is valid. Accordingly, the response MUST include an ETag | ETag Option is valid. Accordingly, the response MUST include an ETag | |||
| Option, and MUST NOT include a payload. | Option, and MUST NOT include a payload. | |||
| When a cache that recognizes and processes the ETag response option | When a cache that recognizes and processes the ETag response option | |||
| receives a 2.03 (Valid) response, it MUST update the stored response | receives a 2.03 (Valid) response, it MUST update the stored response | |||
| with the value of the Max-Age Option included in the response | with the value of the Max-Age Option included in the response | |||
| (explicitly, or implicitly as a default value; see also | (explicitly, or implicitly as a default value; see also | |||
| Section 5.6.2). For each type of Safe option present in the | Section 5.6.2). For each type of Safe-to-Forward option present in | |||
| response, the (possibly empty) set of options of this type that are | the response, the (possibly empty) set of options of this type that | |||
| present in the stored response MUST be replaced with the set of | are present in the stored response MUST be replaced with the set of | |||
| options of this type in the response received. (Unsafe options may | options of this type in the response received. (Unsafe options may | |||
| trigger similar option specific processing as defined by the option.) | trigger similar option specific processing as defined by the option.) | |||
| 5.9.1.4. 2.04 Changed | 5.9.1.4. 2.04 Changed | |||
| Like HTTP 204 "No Content", but only used in response to POST and PUT | Like HTTP 204 "No Content", but only used in response to POST and PUT | |||
| requests. The payload returned with the response, if any, is a | requests. The payload returned with the response, if any, is a | |||
| representation of the action result. | representation of the action result. | |||
| This response is not cacheable. However, a cache MUST mark any | This response is not cacheable. However, a cache MUST mark any | |||
| skipping to change at page 47, line 13 ¶ | skipping to change at page 49, line 25 ¶ | |||
| Option to determine freshness (see Section 5.6.1). They cannot be | Option to determine freshness (see Section 5.6.1). They cannot be | |||
| validated. | validated. | |||
| 5.9.2.1. 4.00 Bad Request | 5.9.2.1. 4.00 Bad Request | |||
| Like HTTP 400 "Bad Request". | Like HTTP 400 "Bad Request". | |||
| 5.9.2.2. 4.01 Unauthorized | 5.9.2.2. 4.01 Unauthorized | |||
| The client is not authorized to perform the requested action. The | The client is not authorized to perform the requested action. The | |||
| client SHOULD NOT repeat the request without previously improving its | client SHOULD NOT repeat the request without first improving its | |||
| authentication status to the server. Which specific mechanism can be | authentication status to the server. Which specific mechanism can be | |||
| used for this is outside this document's scope; see also Section 9. | used for this is outside this document's scope; see also Section 9. | |||
| 5.9.2.3. 4.02 Bad Option | 5.9.2.3. 4.02 Bad Option | |||
| The request could not be understood by the server due to one or more | The request could not be understood by the server due to one or more | |||
| unrecognized or malformed options. The client SHOULD NOT repeat the | unrecognized or malformed options. The client SHOULD NOT repeat the | |||
| request without modification. | request without modification. | |||
| 5.9.2.4. 4.03 Forbidden | 5.9.2.4. 4.03 Forbidden | |||
| skipping to change at page 47, line 48 ¶ | skipping to change at page 50, line 17 ¶ | |||
| Like HTTP 406 "Not Acceptable", but with no response entity. | Like HTTP 406 "Not Acceptable", but with no response entity. | |||
| 5.9.2.8. 4.12 Precondition Failed | 5.9.2.8. 4.12 Precondition Failed | |||
| Like HTTP 412 "Precondition Failed". | Like HTTP 412 "Precondition Failed". | |||
| 5.9.2.9. 4.13 Request Entity Too Large | 5.9.2.9. 4.13 Request Entity Too Large | |||
| Like HTTP 413 "Request Entity Too Large". | Like HTTP 413 "Request Entity Too Large". | |||
| The response SHOULD include a Size1 Option (Section 5.10.9) to | ||||
| indicate the maximum size of request entity the server is able and | ||||
| willing to handle, unless the server is not in a position to make | ||||
| this information available. | ||||
| 5.9.2.10. 4.15 Unsupported Content-Format | 5.9.2.10. 4.15 Unsupported Content-Format | |||
| Like HTTP 415 "Unsupported Media Type". | Like HTTP 415 "Unsupported Media Type". | |||
| 5.9.3. Server Error 5.xx | 5.9.3. Server Error 5.xx | |||
| This class of response code indicates cases in which the server is | This class of response code indicates cases in which the server is | |||
| aware that it has erred or is incapable of performing the request. | aware that it has erred or is incapable of performing the request. | |||
| These response codes are applicable to any request method. | These response codes are applicable to any request method. | |||
| skipping to change at page 48, line 31 ¶ | skipping to change at page 51, line 4 ¶ | |||
| 5.9.3.2. 5.01 Not Implemented | 5.9.3.2. 5.01 Not Implemented | |||
| Like HTTP 501 "Not Implemented". | Like HTTP 501 "Not Implemented". | |||
| 5.9.3.3. 5.02 Bad Gateway | 5.9.3.3. 5.02 Bad Gateway | |||
| Like HTTP 502 "Bad Gateway". | Like HTTP 502 "Bad Gateway". | |||
| 5.9.3.4. 5.03 Service Unavailable | 5.9.3.4. 5.03 Service Unavailable | |||
| Like HTTP 503 "Service Unavailable", but using the Max-Age Option in | Like HTTP 503 "Service Unavailable", but using the Max-Age Option in | |||
| place of the "Retry-After" header field to indicate the number of | place of the "Retry-After" header field to indicate the number of | |||
| seconds after which to retry. | seconds after which to retry. | |||
| 5.9.3.5. 5.04 Gateway Timeout | 5.9.3.5. 5.04 Gateway Timeout | |||
| Like HTTP 504 "Gateway Timeout". | Like HTTP 504 "Gateway Timeout". | |||
| 5.9.3.6. 5.05 Proxying Not Supported | 5.9.3.6. 5.05 Proxying Not Supported | |||
| The server is unable or unwilling to act as a forward-proxy for the | The server is unable or unwilling to act as a forward-proxy for the | |||
| URI specified in the Proxy-Uri Option or using Proxy-Scheme (see | URI specified in the Proxy-Uri Option or using Proxy-Scheme (see | |||
| Section 5.10.2). | Section 5.10.2). | |||
| 5.10. Option Definitions | 5.10. Option Definitions | |||
| The individual CoAP options are summarized in Table 3 and explained | The individual CoAP options are summarized in Table 4 and explained | |||
| in the subsections of this section. | in the subsections of this section. | |||
| In this table, the C, U, and N columns indicate the properties, | In this table, the C, U, and N columns indicate the properties, | |||
| Critical, UnSafe, and NoCacheKey, respectively. Since NoCacheKey | Critical, UnSafe, and NoCacheKey, respectively. Since NoCacheKey | |||
| only has a meaning for options that are safe to foward (not marked | only has a meaning for options that are Safe-to-Forward (not marked | |||
| Unsafe), the column is filled with a dash for UnSafe options. (The | Unsafe), the column is filled with a dash for UnSafe options. (The | |||
| present specification does not define any NoCacheKey options, but the | present specification does not define any NoCacheKey options, but the | |||
| format of the table is intended to be useful for additional | format of the table is intended to be useful for additional | |||
| specifications.) | specifications.) | |||
| +-----+---+---+---+---+----------------+--------+--------+----------+ | +-----+----+---+---+---+----------------+--------+--------+---------+ | |||
| | No. | C | U | N | R | Name | Format | Length | Default | | | No. | C | U | N | R | Name | Format | Length | Default | | |||
| +-----+---+---+---+---+----------------+--------+--------+----------+ | +-----+----+---+---+---+----------------+--------+--------+---------+ | |||
| | 1 | x | | | x | If-Match | opaque | 0-8 | (none) | | | 1 | x | | | x | If-Match | opaque | 0-8 | (none) | | |||
| | 3 | x | x | - | | Uri-Host | string | 1-255 | (see | | | 3 | x | x | - | | Uri-Host | string | 1-255 | (see | | |||
| | | | | | | | | | below) | | | | | | | | | | | below) | | |||
| | 4 | | | | x | ETag | opaque | 1-8 | (none) | | | 4 | | | | x | ETag | opaque | 1-8 | (none) | | |||
| | 5 | x | | | | If-None-Match | empty | 0 | (none) | | | 5 | x | | | | If-None-Match | empty | 0 | (none) | | |||
| | 7 | x | x | - | | Uri-Port | uint | 0-2 | (see | | | 7 | x | x | - | | Uri-Port | uint | 0-2 | (see | | |||
| | | | | | | | | | below) | | | | | | | | | | | below) | | |||
| | 8 | | | | x | Location-Path | string | 0-255 | (none) | | | 8 | | | | x | Location-Path | string | 0-255 | (none) | | |||
| | 11 | x | x | - | x | Uri-Path | string | 0-255 | (none) | | | 11 | x | x | - | x | Uri-Path | string | 0-255 | (none) | | |||
| | 12 | | | | | Content-Format | uint | 0-2 | (none) | | | 12 | | | | | Content-Format | uint | 0-2 | (none) | | |||
| | 14 | | x | - | | Max-Age | uint | 0-4 | 60 | | | 14 | | x | - | | Max-Age | uint | 0-4 | 60 | | |||
| | 15 | x | x | - | x | Uri-Query | string | 0-255 | (none) | | | 15 | x | x | - | x | Uri-Query | string | 0-255 | (none) | | |||
| | 16 | | | | | Accept | uint | 0-2 | (none) | | | 17 | x | | | | Accept | uint | 0-2 | (none) | | |||
| | 20 | | | | x | Location-Query | string | 0-255 | (none) | | | 20 | | | | x | Location-Query | string | 0-255 | (none) | | |||
| | 35 | x | x | - | | Proxy-Uri | string | 1-1034 | (none) | | | 35 | x | x | - | | Proxy-Uri | string | 1-1034 | (none) | | |||
| | 39 | x | x | - | | Proxy-Scheme | string | 1-255 | (none) | | | 39 | x | x | - | | Proxy-Scheme | string | 1-255 | (none) | | |||
| +-----+---+---+---+---+----------------+--------+--------+----------+ | | 60 | | | x | | Size1 | uint | 0-4 | (none) | | |||
| +-----+----+---+---+---+----------------+--------+--------+---------+ | ||||
| C=Critical, U=Unsafe, N=No-Cache-Key, R=Repeatable | C=Critical, U=Unsafe, N=NoCacheKey, R=Repeatable | |||
| Table 3: Options | Table 4: Options | |||
| 5.10.1. Uri-Host, Uri-Port, Uri-Path and Uri-Query | 5.10.1. Uri-Host, Uri-Port, Uri-Path and Uri-Query | |||
| The Uri-Host, Uri-Port, Uri-Path and Uri-Query Options are used to | The Uri-Host, Uri-Port, Uri-Path and Uri-Query Options are used to | |||
| specify the target resource of a request to a CoAP origin server. | specify the target resource of a request to a CoAP origin server. | |||
| The options encode the different components of the request URI in a | The options encode the different components of the request URI in a | |||
| way that no percent-encoding is visible in the option values and that | way that no percent-encoding is visible in the option values and that | |||
| the full URI can be reconstructed at any involved endpoint. The | the full URI can be reconstructed at any involved endpoint. The | |||
| syntax of CoAP URIs is defined in Section 6. | syntax of CoAP URIs is defined in Section 6. | |||
| skipping to change at page 50, line 27 ¶ | skipping to change at page 52, line 47 ¶ | |||
| The default value of the Uri-Host Option is the IP literal | The default value of the Uri-Host Option is the IP literal | |||
| representing the destination IP address of the request message. | representing the destination IP address of the request message. | |||
| Likewise, the default value of the Uri-Port Option is the destination | Likewise, the default value of the Uri-Port Option is the destination | |||
| UDP port. The default values for the Uri-Host and Uri-Port Options | UDP port. The default values for the Uri-Host and Uri-Port Options | |||
| are sufficient for requests to most servers. Explicit Uri-Host and | are sufficient for requests to most servers. Explicit Uri-Host and | |||
| Uri-Port Options are typically used when an endpoint hosts multiple | Uri-Port Options are typically used when an endpoint hosts multiple | |||
| virtual servers. | virtual servers. | |||
| The Uri-Path and Uri-Query Option can contain any character sequence. | The Uri-Path and Uri-Query Option can contain any character sequence. | |||
| No percent-encoding is performed. The value of a Uri-Path Option | No percent-encoding is performed. The value of a Uri-Path Option | |||
| MUST NOT be "." or ".." (as the request URI must be resolved before | MUST NOT be "." or ".." (as the request URI must be resolved before | |||
| parsing it into options). | parsing it into options). | |||
| The steps for constructing the request URI from the options are | The steps for constructing the request URI from the options are | |||
| defined in Section 6.5. Note that an implementation does not | defined in Section 6.5. Note that an implementation does not | |||
| necessarily have to construct the URI; it can simply look up the | necessarily have to construct the URI; it can simply look up the | |||
| target resource by looking at the individual options. | target resource by looking at the individual options. | |||
| Examples can be found in Appendix B. | Examples can be found in Appendix B. | |||
| 5.10.2. Proxy-Uri and Proxy-Scheme | 5.10.2. Proxy-Uri and Proxy-Scheme | |||
| skipping to change at page 51, line 16 ¶ | skipping to change at page 53, line 37 ¶ | |||
| The Proxy-Uri Option MUST take precedence over any of the Uri-Host, | The Proxy-Uri Option MUST take precedence over any of the Uri-Host, | |||
| Uri-Port, Uri-Path or Uri-Query options (which MUST NOT be included | Uri-Port, Uri-Path or Uri-Query options (which MUST NOT be included | |||
| at the same time in a request containing the Proxy-Uri Option). | at the same time in a request containing the Proxy-Uri Option). | |||
| As a special case to simplify many proxy clients, the absolute-URI | As a special case to simplify many proxy clients, the absolute-URI | |||
| can be constructed from the Uri-* options. When a Proxy-Scheme | can be constructed from the Uri-* options. When a Proxy-Scheme | |||
| Option is present, the absolute-URI is constructed as follows: A CoAP | Option is present, the absolute-URI is constructed as follows: A CoAP | |||
| URI is constructed from the Uri-* options as defined in Section 6.5. | URI is constructed from the Uri-* options as defined in Section 6.5. | |||
| In the resulting URI, the initial scheme up to, but not including the | In the resulting URI, the initial scheme up to, but not including the | |||
| following colon is then replaced by the content of the Proxy-Scheme | following colon is then replaced by the content of the Proxy-Scheme | |||
| Option. | Option. Note that this case is only applicable if the components of | |||
| the desired URI other than the scheme component actually can be | ||||
| expressed using Uri-* options; e.g., to represent a URI with a | ||||
| userinfo component in the authority, only Proxy-Uri can be used. | ||||
| 5.10.3. Content-Format | 5.10.3. Content-Format | |||
| The Content-Format Option indicates the representation format of the | The Content-Format Option indicates the representation format of the | |||
| message payload. The representation format is given as a numeric | message payload. The representation format is given as a numeric | |||
| content format identifier that is defined in the CoAP Content Format | content format identifier that is defined in the CoAP Content Format | |||
| registry (Section 12.3). In the absence of the option, no default | Registry (Section 12.3). In the absence of the option, no default | |||
| value is assumed, i.e. the representation format of any | value is assumed, i.e. the representation format of any | |||
| representation message payload is indeterminate (Section 5.5). | representation message payload is indeterminate (Section 5.5). | |||
| 5.10.4. Accept | 5.10.4. Accept | |||
| The CoAP Accept option can be used to indicate which Content-Format | The CoAP Accept option can be used to indicate which Content-Format | |||
| is acceptable to the client. The representation format is given as a | is acceptable to the client. The representation format is given as a | |||
| numeric Content-Format identifier that is defined in the CoAP | numeric Content-Format identifier that is defined in the CoAP | |||
| Content-Format registry (Section 12.3). If no Accept option is | Content-Format Registry (Section 12.3). If no Accept option is | |||
| given, the client does not express a preference (thus no default | given, the client does not express a preference (thus no default | |||
| value is assumed). The client prefers the representation returned by | value is assumed). The client prefers the representation returned by | |||
| the server to be in the Content-Format indicated. The server SHOULD | the server to be in the Content-Format indicated. The server returns | |||
| return the preferred Content-Format if available. If the preferred | the preferred Content-Format if available. If the preferred Content- | |||
| Content-Format cannot be returned, then a 4.06 "Not Acceptable" | Format cannot be returned, then a 4.06 "Not Acceptable" MUST be sent | |||
| SHOULD be sent as a response. | as a response, unless another error code takes precedence for this | |||
| response. | ||||
| Note that as a server might not support the Accept option (and thus | ||||
| would ignore it as it is elective), the client needs to be prepared | ||||
| to receive a representation in a different Content-Format. The | ||||
| client can simply discard a representation it can not make use of. | ||||
| 5.10.5. Max-Age | 5.10.5. Max-Age | |||
| The Max-Age Option indicates the maximum time a response may be | The Max-Age Option indicates the maximum time a response may be | |||
| cached before it MUST be considered not fresh (see Section 5.6.1). | cached before it is considered not fresh (see Section 5.6.1). | |||
| The option value is an integer number of seconds between 0 and | The option value is an integer number of seconds between 0 and | |||
| 2**32-1 inclusive (about 136.1 years). A default value of 60 seconds | 2**32-1 inclusive (about 136.1 years). A default value of 60 seconds | |||
| is assumed in the absence of the option in a response. | is assumed in the absence of the option in a response. | |||
| The value is intended to be current at the time of transmission. | The value is intended to be current at the time of transmission. | |||
| Servers that provide resources with strict tolerances on the value of | Servers that provide resources with strict tolerances on the value of | |||
| Max-Age SHOULD update the value before each retransmission. (See | Max-Age SHOULD update the value before each retransmission. (See | |||
| also Section 5.7.1.) | also Section 5.7.1.) | |||
| skipping to change at page 53, line 5 ¶ | skipping to change at page 55, line 26 ¶ | |||
| 5.10.6.2. ETag as a Request Option | 5.10.6.2. ETag as a Request Option | |||
| In a GET request, an endpoint that has one or more representations | In a GET request, an endpoint that has one or more representations | |||
| previously obtained from the resource, and has obtained ETag response | previously obtained from the resource, and has obtained ETag response | |||
| options with these, can specify an instance of the ETag Option for | options with these, can specify an instance of the ETag Option for | |||
| one or more of these stored responses. | one or more of these stored responses. | |||
| A server can issue a 2.03 Valid response (Section 5.9.1.3) in place | A server can issue a 2.03 Valid response (Section 5.9.1.3) in place | |||
| of a 2.05 Content response if one of the ETags given is the entity- | of a 2.05 Content response if one of the ETags given is the entity- | |||
| tag for the current representation, i.e. is valid; the 2.03 Valid | tag for the current representation, i.e. is valid; the 2.03 Valid | |||
| response then echoes this specific ETag in a response option. | response then echoes this specific ETag in a response option. | |||
| In effect, a client can determine if any of the stored | In effect, a client can determine if any of the stored | |||
| representations is current (see Section 5.6.2) without needing to | representations is current (see Section 5.6.2) without needing to | |||
| transfer them again. | transfer them again. | |||
| The ETag Option MAY occur zero, one or more times in a request. | The ETag Option MAY occur zero, one or more times in a request. | |||
| 5.10.7. Location-Path and Location-Query | 5.10.7. Location-Path and Location-Query | |||
| skipping to change at page 53, line 33 ¶ | skipping to change at page 56, line 6 ¶ | |||
| If a response with one or more Location-Path and/or Location-Query | If a response with one or more Location-Path and/or Location-Query | |||
| Options passes through a cache that interprets these options and the | Options passes through a cache that interprets these options and the | |||
| implied URI identifies one or more currently stored responses, those | implied URI identifies one or more currently stored responses, those | |||
| entries MUST be marked as not fresh. | entries MUST be marked as not fresh. | |||
| Each Location-Path Option specifies one segment of the absolute path | Each Location-Path Option specifies one segment of the absolute path | |||
| to the resource, and each Location-Query Option specifies one | to the resource, and each Location-Query Option specifies one | |||
| argument parameterizing the resource. The Location-Path and | argument parameterizing the resource. The Location-Path and | |||
| Location-Query Option can contain any character sequence. No | Location-Query Option can contain any character sequence. No | |||
| percent-encoding is performed. The value of a Location-Path Option | percent-encoding is performed. The value of a Location-Path Option | |||
| MUST NOT be "." or "..". | MUST NOT be "." or "..". | |||
| The steps for constructing the location URI from the options are | The steps for constructing the location URI from the options are | |||
| analogous to Section 6.5, except that the first five steps are | analogous to Section 6.5, except that the first five steps are | |||
| skipped and the result is a relative URI-reference, which is then | skipped and the result is a relative URI-reference, which is then | |||
| interpreted relative to the request URI. Note that the relative URI- | interpreted relative to the request URI. Note that the relative URI- | |||
| reference constructed this way always includes an absolute-path | reference constructed this way always includes an absolute-path | |||
| (e.g., leaving out Location-Path but supplying Location-Query means | (e.g., leaving out Location-Path but supplying Location-Query means | |||
| the path component in the URI is "/"). | the path component in the URI is "/"). | |||
| The options that are used to compute the relative URI-reference are | The options that are used to compute the relative URI-reference are | |||
| skipping to change at page 54, line 12 ¶ | skipping to change at page 56, line 31 ¶ | |||
| and/or Location-Query and are not supported, then a 4.02 (Bad Option) | and/or Location-Query and are not supported, then a 4.02 (Bad Option) | |||
| error MUST be returned. | error MUST be returned. | |||
| 5.10.8. Conditional Request Options | 5.10.8. Conditional Request Options | |||
| Conditional request options enable a client to ask the server to | Conditional request options enable a client to ask the server to | |||
| perform the request only if certain conditions specified by the | perform the request only if certain conditions specified by the | |||
| option are fulfilled. | option are fulfilled. | |||
| For each of these options, if the condition given is not fulfilled, | For each of these options, if the condition given is not fulfilled, | |||
| then the the server MUST NOT perform the requested method. Instead, | then the server MUST NOT perform the requested method. Instead, the | |||
| the server MUST respond with the 4.12 (Precondition Failed) response | server MUST respond with the 4.12 (Precondition Failed) response | |||
| code. | code. | |||
| If the condition is fulfilled, the server performs the request method | If the condition is fulfilled, the server performs the request method | |||
| as if the conditional request options were not present. | as if the conditional request options were not present. | |||
| If the request would, without the conditional request options, result | If the request would, without the conditional request options, result | |||
| in anything other than a 2.xx or 4.12 response code, then any | in anything other than a 2.xx or 4.12 response code, then any | |||
| conditional request options MAY be ignored. | conditional request options MAY be ignored. | |||
| 5.10.8.1. If-Match | 5.10.8.1. If-Match | |||
| skipping to change at page 55, line 8 ¶ | skipping to change at page 57, line 29 ¶ | |||
| The If-None-Match Option MAY be used to make a request conditional on | The If-None-Match Option MAY be used to make a request conditional on | |||
| the non-existence of the target resource. If-None-Match is useful | the non-existence of the target resource. If-None-Match is useful | |||
| for resource creation requests, such as PUT requests, as a means for | for resource creation requests, such as PUT requests, as a means for | |||
| protecting against accidental overwrites when multiple clients are | protecting against accidental overwrites when multiple clients are | |||
| acting in parallel on the same resource. The If-None-Match Option | acting in parallel on the same resource. The If-None-Match Option | |||
| carries no value. | carries no value. | |||
| If the target resource does exist, then the condition is not | If the target resource does exist, then the condition is not | |||
| fulfilled. | fulfilled. | |||
| 6. CoAP URIs | (It is not very useful to combine If-Match and If-None-Match options | |||
| in one request, because the condition will then never be fulfilled.) | ||||
| 5.10.9. Size1 Option | ||||
| The Size1 option provides size information about the resource | ||||
| representation in a request. The option value is an integer number | ||||
| of bytes. Its main use is with block-wise transfers | ||||
| [I-D.ietf-core-block]. In the present specification, it is used in | ||||
| 4.13 responses (Section 5.9.2.9) to indicate the maximum size of | ||||
| request entity that the server is able and willing to handle. | ||||
| 6. CoAP URIs | ||||
| CoAP uses the "coap" and "coaps" URI schemes for identifying CoAP | CoAP uses the "coap" and "coaps" URI schemes for identifying CoAP | |||
| resources and providing a means of locating the resource. Resources | resources and providing a means of locating the resource. Resources | |||
| are organized hierarchically and governed by a potential CoAP origin | are organized hierarchically and governed by a potential CoAP origin | |||
| server listening for CoAP requests ("coap") or DTLS-secured CoAP | server listening for CoAP requests ("coap") or DTLS-secured CoAP | |||
| requests ("coaps") on a given UDP port. The CoAP server is | requests ("coaps") on a given UDP port. The CoAP server is | |||
| identified via the generic syntax's authority component, which | identified via the generic syntax's authority component, which | |||
| includes a host component and optional UDP port number. The | includes a host component and optional UDP port number. The | |||
| remainder of the URI is considered to be identifying a resource which | remainder of the URI is considered to be identifying a resource which | |||
| can be operated on by the methods defined by the CoAP protocol. The | can be operated on by the methods defined by the CoAP protocol. The | |||
| "coap" and "coaps" URI schemes can thus be compared to the "http" and | "coap" and "coaps" URI schemes can thus be compared to the "http" and | |||
| skipping to change at page 56, line 33 ¶ | skipping to change at page 59, line 27 ¶ | |||
| ignoring descriptiveness. | ignoring descriptiveness. | |||
| 6.2. coaps URI Scheme | 6.2. coaps URI Scheme | |||
| coaps-URI = "coaps:" "//" host [ ":" port ] path-abempty | coaps-URI = "coaps:" "//" host [ ":" port ] path-abempty | |||
| [ "?" query ] | [ "?" query ] | |||
| All of the requirements listed above for the "coap" scheme are also | All of the requirements listed above for the "coap" scheme are also | |||
| requirements for the "coaps" scheme, except that a default UDP port | requirements for the "coaps" scheme, except that a default UDP port | |||
| of [IANA_TBD_PORT] is assumed if the port subcomponent is empty or | of [IANA_TBD_PORT] is assumed if the port subcomponent is empty or | |||
| not given, and the UDP datagrams MUST be secured for privacy through | not given, and the UDP datagrams MUST be secured through the use of | |||
| the use of DTLS as described in Section 9.1. | DTLS as described in Section 9.1. | |||
| Considerations for caching of responses to "coaps" identified | Considerations for caching of responses to "coaps" identified | |||
| requests are discussed in Section 11.2. | requests are discussed in Section 11.2. | |||
| Resources made available via the "coaps" scheme have no shared | Resources made available via the "coaps" scheme have no shared | |||
| identity with the "coap" scheme even if their resource identifiers | identity with the "coap" scheme even if their resource identifiers | |||
| indicate the same authority (the same host listening to the same UDP | indicate the same authority (the same host listening to the same UDP | |||
| port). They are distinct name spaces and are considered to be | port). They are distinct name spaces and are considered to be | |||
| distinct origin servers. | distinct origin servers. | |||
| skipping to change at page 57, line 22 ¶ | skipping to change at page 60, line 18 ¶ | |||
| For example, the following three URIs are equivalent, and cause the | For example, the following three URIs are equivalent, and cause the | |||
| same options and option values to appear in the CoAP messages: | same options and option values to appear in the CoAP messages: | |||
| coap://example.com:5683/~sensors/temp.xml | coap://example.com:5683/~sensors/temp.xml | |||
| coap://EXAMPLE.com/%7Esensors/temp.xml | coap://EXAMPLE.com/%7Esensors/temp.xml | |||
| coap://EXAMPLE.com:/%7esensors/temp.xml | coap://EXAMPLE.com:/%7esensors/temp.xml | |||
| 6.4. Decomposing URIs into Options | 6.4. Decomposing URIs into Options | |||
| The steps to parse a request's options from a string /url/ are as | The steps to parse a request's options from a string |url| are as | |||
| follows. These steps either result in zero or more of the Uri-Host, | follows. These steps either result in zero or more of the Uri-Host, | |||
| Uri-Port, Uri-Path and Uri-Query Options being included in the | Uri-Port, Uri-Path and Uri-Query Options being included in the | |||
| request, or they fail. | request, or they fail. | |||
| 1. If the /url/ string is not an absolute URI ([RFC3986]), then fail | 1. If the |url| string is not an absolute URI ([RFC3986]), then fail | |||
| this algorithm. | this algorithm. | |||
| 2. Resolve the /url/ string using the process of reference | 2. Resolve the |url| string using the process of reference | |||
| resolution defined by [RFC3986]. At this stage the URL is in | resolution defined by [RFC3986]. At this stage the URL is in | |||
| ASCII encoding [RFC0020], even though the decoded components will | ASCII encoding [RFC0020], even though the decoded components will | |||
| be interpreted in UTF-8 [RFC3629] after step 5, 8 and 9. | be interpreted in UTF-8 [RFC3629] after step 5, 8 and 9. | |||
| NOTE: It doesn't matter what it is resolved relative to, since we | NOTE: It doesn't matter what it is resolved relative to, since we | |||
| already know it is an absolute URL at this point. | already know it is an absolute URL at this point. | |||
| 3. If /url/ does not have a <scheme> component whose value, when | 3. If |url| does not have a <scheme> component whose value, when | |||
| converted to ASCII lowercase, is "coap" or "coaps", then fail | converted to ASCII lowercase, is "coap" or "coaps", then fail | |||
| this algorithm. | this algorithm. | |||
| 4. If /url/ has a <fragment> component, then fail this algorithm. | 4. If |url| has a <fragment> component, then fail this algorithm. | |||
| 5. If the <host> component of /url/ does not represent the request's | 5. If the <host> component of |url| does not represent the request's | |||
| destination IP address as an IP-literal or IPv4address, include a | destination IP address as an IP-literal or IPv4address, include a | |||
| Uri-Host Option and let that option's value be the value of the | Uri-Host Option and let that option's value be the value of the | |||
| <host> component of /url/, converted to ASCII lowercase, and then | <host> component of |url|, converted to ASCII lowercase, and then | |||
| converting all percent-encodings ("%" followed by two hexadecimal | converting all percent-encodings ("%" followed by two hexadecimal | |||
| digits) to the corresponding characters. | digits) to the corresponding characters. | |||
| NOTE: In the usual case where the request's destination IP | NOTE: In the usual case where the request's destination IP | |||
| address is derived from the host part, this ensures that a Uri- | address is derived from the host part, this ensures that a Uri- | |||
| Host Option is only used for a <host> component of the form reg- | Host Option is only used for a <host> component of the form reg- | |||
| name. | name. | |||
| 6. If /url/ has a <port> component, then let /port/ be that | 6. If |url| has a <port> component, then let |port| be that | |||
| component's value interpreted as a decimal integer; otherwise, | component's value interpreted as a decimal integer; otherwise, | |||
| let /port/ be the default port for the scheme. | let |port| be the default port for the scheme. | |||
| 7. If /port/ does not equal the request's destination UDP port, | 7. If |port| does not equal the request's destination UDP port, | |||
| include a Uri-Port Option and let that option's value be /port/. | include a Uri-Port Option and let that option's value be |port|. | |||
| 8. If the value of the <path> component of /url/ is empty or | 8. If the value of the <path> component of |url| is empty or | |||
| consists of a single slash character (U+002F SOLIDUS "/"), then | consists of a single slash character (U+002F SOLIDUS "/"), then | |||
| move to the next step. | move to the next step. | |||
| Otherwise, for each segment in the <path> component, include a | Otherwise, for each segment in the <path> component, include a | |||
| Uri-Path Option and let that option's value be the segment (not | Uri-Path Option and let that option's value be the segment (not | |||
| including the delimiting slash characters) after converting each | including the delimiting slash characters) after converting each | |||
| percent-encoding ("%" followed by two hexadecimal digits) to the | percent-encoding ("%" followed by two hexadecimal digits) to the | |||
| corresponding byte. | corresponding byte. | |||
| 9. If /url/ has a <query> component, then, for each argument in the | 9. If |url| has a <query> component, then, for each argument in the | |||
| <query> component, include a Uri-Query Option and let that | <query> component, include a Uri-Query Option and let that | |||
| option's value be the argument (not including the question mark | option's value be the argument (not including the question mark | |||
| and the delimiting ampersand characters) after converting each | and the delimiting ampersand characters) after converting each | |||
| percent-encoding to the corresponding byte. | percent-encoding to the corresponding byte. | |||
| Note that these rules completely resolve any percent-encoding. | Note that these rules completely resolve any percent-encoding. | |||
| 6.5. Composing URIs from Options | 6.5. Composing URIs from Options | |||
| The steps to construct a URI from a request's options are as follows. | The steps to construct a URI from a request's options are as follows. | |||
| These steps either result in a URI, or they fail. In these steps, | These steps either result in a URI, or they fail. In these steps, | |||
| percent-encoding a character means replacing each of its (UTF-8 | percent-encoding a character means replacing each of its (UTF-8 | |||
| encoded) bytes by a "%" character followed by two hexadecimal digits | encoded) bytes by a "%" character followed by two hexadecimal digits | |||
| representing the byte, where the digits A-F are in upper case (as | representing the byte, where the digits A-F are in upper case (as | |||
| defined in [RFC3986] Section 2.1; to reduce variability, the | defined in [RFC3986] Section 2.1; to reduce variability, the | |||
| hexadecimal notation for percent-encoding in CoAP URIs MUST use | hexadecimal notation for percent-encoding in CoAP URIs MUST use | |||
| uppercase letters). The definitions of "unreserved" and "sub-delims" | uppercase letters). The definitions of "unreserved" and "sub-delims" | |||
| are adopted from [RFC3986]. | are adopted from [RFC3986]. | |||
| 1. If the request is secured using DTLS, let /url/ be the string | 1. If the request is secured using DTLS, let |url| be the string | |||
| "coaps://". Otherwise, let /url/ be the string "coap://". | "coaps://". Otherwise, let |url| be the string "coap://". | |||
| 2. If the request includes a Uri-Host Option, let /host/ be that | 2. If the request includes a Uri-Host Option, let |host| be that | |||
| option's value, where any non-ASCII characters are replaced by | option's value, where any non-ASCII characters are replaced by | |||
| their corresponding percent-encoding. If /host/ is not a valid | their corresponding percent-encoding. If |host| is not a valid | |||
| reg-name or IP-literal or IPv4address, fail the algorithm. If | reg-name or IP-literal or IPv4address, fail the algorithm. If | |||
| the request does not include a Uri-Host Option, let /host/ be | the request does not include a Uri-Host Option, let |host| be | |||
| the IP-literal (making use of the conventions of [RFC5952]) or | the IP-literal (making use of the conventions of [RFC5952]) or | |||
| IPv4address representing the request's destination IP address. | IPv4address representing the request's destination IP address. | |||
| 3. Append /host/ to /url/. | 3. Append |host| to |url|. | |||
| 4. If the request includes a Uri-Port Option, let /port/ be that | 4. If the request includes a Uri-Port Option, let |port| be that | |||
| option's value. Otherwise, let /port/ be the request's | option's value. Otherwise, let |port| be the request's | |||
| destination UDP port. | destination UDP port. | |||
| 5. If /port/ is not the default port for the scheme, then append a | 5. If |port| is not the default port for the scheme, then append a | |||
| single U+003A COLON character (:) followed by the decimal | single U+003A COLON character (:) followed by the decimal | |||
| representation of /port/ to /url/. | representation of |port| to |url|. | |||
| 6. Let /resource name/ be the empty string. For each Uri-Path | 6. Let |resource name| be the empty string. For each Uri-Path | |||
| Option in the request, append a single character U+002F SOLIDUS | Option in the request, append a single character U+002F SOLIDUS | |||
| (/) followed by the option's value to /resource name/, after | (/) followed by the option's value to |resource name|, after | |||
| converting any character that is not either in the "unreserved" | converting any character that is not either in the "unreserved" | |||
| set, "sub-delims" set, a U+003A COLON (:) or U+0040 COMMERCIAL | set, "sub-delims" set, a U+003A COLON (:) or U+0040 COMMERCIAL | |||
| AT (@) character, to its percent-encoded form. | AT (@) character, to its percent-encoded form. | |||
| 7. If /resource name/ is the empty string, set it to a single | 7. If |resource name| is the empty string, set it to a single | |||
| character U+002F SOLIDUS (/). | character U+002F SOLIDUS (/). | |||
| 8. For each Uri-Query Option in the request, append a single | 8. For each Uri-Query Option in the request, append a single | |||
| character U+003F QUESTION MARK (?) (first option) or U+0026 | character U+003F QUESTION MARK (?) (first option) or U+0026 | |||
| AMPERSAND (&) (subsequent options) followed by the option's | AMPERSAND (&) (subsequent options) followed by the option's | |||
| value to /resource name/, after converting any character that is | value to |resource name|, after converting any character that is | |||
| not either in the "unreserved" set, "sub-delims" set (except | not either in the "unreserved" set, "sub-delims" set (except | |||
| U+0026 AMPERSAND (&)), a U+003A COLON (:), U+0040 COMMERCIAL AT | U+0026 AMPERSAND (&)), a U+003A COLON (:), U+0040 COMMERCIAL AT | |||
| (@), U+002F SOLIDUS (/) or U+003F QUESTION MARK (?) character, | (@), U+002F SOLIDUS (/) or U+003F QUESTION MARK (?) character, | |||
| to its percent-encoded form. | to its percent-encoded form. | |||
| 9. Append /resource name/ to /url/. | 9. Append |resource name| to |url|. | |||
| 10. Return /url/. | 10. Return |url|. | |||
| Note that these steps have been designed to lead to a URI in normal | Note that these steps have been designed to lead to a URI in normal | |||
| form (see Section 6.3). | form (see Section 6.3). | |||
| 7. Discovery | 7. Discovery | |||
| 7.1. Service Discovery | 7.1. Service Discovery | |||
| As a part of discovering the services offered by a CoAP server, a | As a part of discovering the services offered by a CoAP server, a | |||
| client has to learn about the endpoint used by a server. | client has to learn about the endpoint used by a server. | |||
| A server is discovered by a client by the client knowing or learning | A server is discovered by a client by the client (knowing or) | |||
| a URI that references a resource in the namespace of the server. | learning a URI that references a resource in the namespace of the | |||
| Alternatively, clients can use Multicast CoAP (see Section 8) and the | server. Alternatively, clients can use Multicast CoAP (see | |||
| "All CoAP Nodes" multicast address to find CoAP servers. | Section 8) and the "All CoAP Nodes" multicast address to find CoAP | |||
| servers. | ||||
| Unless the port subcomponent in a "coap" or "coaps" URI indicates the | Unless the port subcomponent in a "coap" or "coaps" URI indicates the | |||
| UDP port at which the CoAP server is located, the server is assumed | UDP port at which the CoAP server is located, the server is assumed | |||
| to be reachable at the default port. | to be reachable at the default port. | |||
| The CoAP default port number 5683 MUST be supported by a server that | The CoAP default port number 5683 MUST be supported by a server that | |||
| offers resources for resource discovery (see Section 7.2 below) and | offers resources for resource discovery (see Section 7.2 below) and | |||
| SHOULD be supported for providing access to other resources. The | SHOULD be supported for providing access to other resources. The | |||
| default port number [IANA_TBD_PORT] for DTLS-secured CoAP MAY be | default port number [IANA_TBD_PORT] for DTLS-secured CoAP MAY be | |||
| supported by a server for resource discovery and for providing access | supported by a server for resource discovery and for providing access | |||
| to other resources. In addition other endpoints may be hosted at | to other resources. In addition other endpoints may be hosted at | |||
| other ports, e.g. in the dynamic port space. | other ports, e.g. in the dynamic port space. | |||
| Implementation Note: When a CoAP server is hosted by a 6LoWPAN node, | Implementation Note: When a CoAP server is hosted by a 6LoWPAN node, | |||
| header compression efficiency is improved when it also supports a | header compression efficiency is improved when it also supports a | |||
| port number in the 61616-61631 compressed UDP port space defined | port number in the 61616-61631 compressed UDP port space defined | |||
| in [RFC4944] (note that, as its UDP port differs from the default | in [RFC4944] (note that, as its UDP port differs from the default | |||
| port, it is a different endpoint from the server at the default | port, it is a different endpoint from the server at the default | |||
| port). | port). | |||
| 7.2. Resource Discovery | 7.2. Resource Discovery | |||
| The discovery of resources offered by a CoAP endpoint is extremely | The discovery of resources offered by a CoAP endpoint is extremely | |||
| important in machine-to-machine applications where there are no | important in machine-to-machine applications where there are no | |||
| humans in the loop and static interfaces result in fragility. A CoAP | humans in the loop and static interfaces result in fragility. To | |||
| endpoint SHOULD support the CoRE Link Format of discoverable | maximize interoperability in a CoRE environment, a CoAP endpoint | |||
| resources as described in [RFC6690]. It is up to the server which | SHOULD support the CoRE Link Format of discoverable resources as | |||
| resources are made discoverable (if any). | described in [RFC6690], except where fully manual configuration is | |||
| desired. It is up to the server which resources are made | ||||
| discoverable (if any). | ||||
| 7.2.1. 'ct' Attribute | 7.2.1. 'ct' Attribute | |||
| This section defines a new Web Linking [RFC5988] attribute for use | This section defines a new Web Linking [RFC5988] attribute for use | |||
| with [RFC6690]. The Content-Format code "ct" attribute provides a | with [RFC6690]. The Content-Format code "ct" attribute provides a | |||
| hint about the Content-Formats this resource returns. Note that this | hint about the Content-Formats this resource returns. Note that this | |||
| is only a hint, and does not override the Content-Format Option of a | is only a hint, and does not override the Content-Format Option of a | |||
| CoAP response obtained by actually requesting the representation of | CoAP response obtained by actually requesting the representation of | |||
| the resource. The value is in the CoAP identifier code format as a | the resource. The value is in the CoAP identifier code format as a | |||
| decimal ASCII integer and MUST be in the range of 0-65535 (16-bit | decimal ASCII integer and MUST be in the range of 0-65535 (16-bit | |||
| unsigned integer). For example application/xml would be indicated as | unsigned integer). For example application/xml would be indicated as | |||
| "ct=41". If no Content-Format code attribute is present then nothing | "ct=41". If no Content-Format code attribute is present then nothing | |||
| about the type can be assumed. The Content-Format code attribute MAY | about the type can be assumed. The Content-Format code attribute MAY | |||
| include a space-separated sequence of Content-Format codes, | include a space-separated sequence of Content-Format codes, | |||
| indicating that multiple content-formats are available. The syntax | indicating that multiple content-formats are available. The syntax | |||
| of the attribute value is summarized in the production ct-value in | of the attribute value is summarized in the production ct-value in | |||
| Figure 12, where cardinal, SP and DQUOTE are defined as in [RFC6690]. | Figure 12, where cardinal, SP and DQUOTE are defined as in [RFC6690]. | |||
| ct-value = cardinal | ct-value = cardinal | |||
| / DQUOTE cardinal *( 1*SP cardinal ) DQUOTE | / DQUOTE cardinal *( 1*SP cardinal ) DQUOTE | |||
| Figure 12 | Figure 12 | |||
| 8. Multicast CoAP | 8. Multicast CoAP | |||
| CoAP supports making requests to a IP multicast group. This is | CoAP supports making requests to a IP multicast group. This is | |||
| defined by a series of deltas to Unicast CoAP. | defined by a series of deltas to Unicast CoAP. A more general | |||
| discussion of group communication with CoAP is in | ||||
| [I-D.ietf-core-groupcomm]. | ||||
| CoAP endpoints that offer services that they want other endpoints to | CoAP endpoints that offer services that they want other endpoints to | |||
| be able to find using multicast service discovery, join one or more | be able to find using multicast service discovery, join one or more | |||
| of the appropriate all-CoAP-nodes multicast addresses (Section 12.8) | of the appropriate all-CoAP-nodes multicast addresses (Section 12.8) | |||
| and listen on the default CoAP port. Note that an endpoint might | and listen on the default CoAP port. Note that an endpoint might | |||
| receive multicast requests on other multicast addresses, including | receive multicast requests on other multicast addresses, including | |||
| the all-nodes IPv6 address (or via broadcast on IPv4); an endpoint | the all-nodes IPv6 address (or via broadcast on IPv4); an endpoint | |||
| MUST therefore be prepared to receive such messages but MAY ignore | MUST therefore be prepared to receive such messages but MAY ignore | |||
| them if multicast service discovery is not desired. | them if multicast service discovery is not desired. | |||
| 8.1. Messaging Layer | 8.1. Messaging Layer | |||
| A multicast request is characterized by being transported in a CoAP | A multicast request is characterized by being transported in a CoAP | |||
| message that is addressed to an IP multicast address instead of a | message that is addressed to an IP multicast address instead of a | |||
| CoAP endpoint. Such multicast requests MUST be Non-confirmable. | CoAP endpoint. Such multicast requests MUST be Non-confirmable. | |||
| A server SHOULD be aware that a request arrived via multicast, e.g. | A server SHOULD be aware that a request arrived via multicast, e.g. | |||
| by making use of modern APIs such as IPV6_RECVPKTINFO [RFC3542], if | by making use of modern APIs such as IPV6_RECVPKTINFO [RFC3542], if | |||
| available. | available. | |||
| When a server is aware that a request arrived via multicast, it MUST | To avoid an implosion of error responses, when a server is aware that | |||
| NOT return a RST in reply to NON. If it is not aware, it MAY return | a request arrived via multicast, it MUST NOT return a RST in reply to | |||
| a RST in reply to NON as usual. Because such a Reset message will | NON. If it is not aware, it MAY return a RST in reply to NON as | |||
| look identical to an RST for a unicast message from the sender, the | usual. Because such a Reset message will look identical to an RST | |||
| sender MUST avoid using a Message ID that is also still active from | for a unicast message from the sender, the sender MUST avoid using a | |||
| this endpoint with any unicast endpoint that might receive the | Message ID that is also still active from this endpoint with any | |||
| multicast message. | unicast endpoint that might receive the multicast message. | |||
| At the time of writing, multicast messages can only be carried in | ||||
| UDP, not in DTLS. This means that the security modes defined for | ||||
| CoAP in this document are not applicable to multicast. | ||||
| 8.2. Request/Response Layer | 8.2. Request/Response Layer | |||
| When a server is aware that a request arrived via multicast, the | When a server is aware that a request arrived via multicast, the | |||
| server MAY always pretend it did not receive the request, in | server MAY always ignore the request, in particular if it doesn't | |||
| particular if it doesn't have anything useful to respond (e.g., if it | have anything useful to respond (e.g., if it only has an empty | |||
| only has an empty payload or an error response). The decision for | payload or an error response). The decision for this may depend on | |||
| this may depend on the application. (For example, in [RFC6690] query | the application. (For example, in [RFC6690] query filtering, a | |||
| filtering, a server should not respond to a multicast request if the | server should not respond to a multicast request if the filter does | |||
| filter does not match.) | not match. More examples are in [I-D.ietf-core-groupcomm].) | |||
| If a server does decide to respond to a multicast request, it should | If a server does decide to respond to a multicast request, it should | |||
| not respond immediately. Instead, it should pick a duration for the | not respond immediately. Instead, it should pick a duration for the | |||
| period of time during which it intends to respond. For purposes of | period of time during which it intends to respond. For purposes of | |||
| this exposition, we call the length of this period the Leisure. The | this exposition, we call the length of this period the Leisure. The | |||
| specific value of this Leisure may depend on the application, or MAY | specific value of this Leisure may depend on the application, or MAY | |||
| be derived as described below. The server SHOULD then pick a random | be derived as described below. The server SHOULD then pick a random | |||
| point of time within the chosen Leisure period to send back the | point of time within the chosen Leisure period to send back the | |||
| unicast response to the multicast request. If further responses need | unicast response to the multicast request. If further responses need | |||
| to be sent based on the same multicast address membership, a new | to be sent based on the same multicast address membership, a new | |||
| leisure period starts at the earliest after the previous one | leisure period starts at the earliest after the previous one | |||
| finishes. | finishes. | |||
| To compute a value for Leisure, the server should have a group size | To compute a value for Leisure, the server should have a group size | |||
| estimate G, a target data transfer rate R (which both should be | estimate G, a target data transfer rate R (which both should be | |||
| chosen conservatively) and an estimated response size S; a rough | chosen conservatively) and an estimated response size S; a rough | |||
| lower bound for Leisure can then be computed as | lower bound for Leisure can then be computed as | |||
| lb_Leisure = S * G / R | ||||
| lb_Leisure = S * G / R | ||||
| E.g., for a multicast request with link-local scope on an 2.4 GHz | E.g., for a multicast request with link-local scope on an 2.4 GHz | |||
| IEEE 802.15.4 (6LoWPAN) network, G could be (relatively | IEEE 802.15.4 (6LoWPAN) network, G could be (relatively | |||
| conservatively) set to 100, S to 100 bytes, and the target rate to 8 | conservatively) set to 100, S to 100 bytes, and the target rate to 8 | |||
| kbit/s = 1 kB/s. The resulting lower bound for the Leisure is 10 | kbit/s = 1 kB/s. The resulting lower bound for the Leisure is 10 | |||
| seconds. | seconds. | |||
| If a CoAP endpoint does not have suitable data to compute a value for | If a CoAP endpoint does not have suitable data to compute a value for | |||
| Leisure, it MAY resort to DEFAULT_LEISURE. | Leisure, it MAY resort to DEFAULT_LEISURE. | |||
| skipping to change at page 62, line 48 ¶ | skipping to change at page 66, line 10 ¶ | |||
| embedded in the representation and, the request URI (base URI) | embedded in the representation and, the request URI (base URI) | |||
| relative to which the response is interpreted, is formed by replacing | relative to which the response is interpreted, is formed by replacing | |||
| the multicast address in the Host component of the original request | the multicast address in the Host component of the original request | |||
| URI by the literal IP address of the endpoint actually responding. | URI by the literal IP address of the endpoint actually responding. | |||
| 8.2.1. Caching | 8.2.1. Caching | |||
| When a client makes a multicast request, it always makes a new | When a client makes a multicast request, it always makes a new | |||
| request to the multicast group (since there may be new group members | request to the multicast group (since there may be new group members | |||
| that joined meanwhile or ones that did not get the previous request). | that joined meanwhile or ones that did not get the previous request). | |||
| It MAY update the cache with the received responses. Then it uses | It MAY update a cache with the received responses. Then it uses both | |||
| both cached-still-fresh and 'new' responses as the result of the | cached-still-fresh and 'new' responses as the result of the request. | |||
| request. | ||||
| A response received in reply to a GET request to a multicast group | A response received in reply to a GET request to a multicast group | |||
| MAY be used to satisfy a subsequent request on the related unicast | MAY be used to satisfy a subsequent request on the related unicast | |||
| request URI. The unicast request URI is obtained by replacing the | request URI. The unicast request URI is obtained by replacing the | |||
| authority part of the request URI with the transport layer source | authority part of the request URI with the transport layer source | |||
| address of the response message. | address of the response message. | |||
| A cache MAY revalidate a response by making a GET request on the | A cache MAY revalidate a response by making a GET request on the | |||
| related unicast request URI. | related unicast request URI. | |||
| skipping to change at page 63, line 27 ¶ | skipping to change at page 66, line 35 ¶ | |||
| 8.2.2. Proxying | 8.2.2. Proxying | |||
| When a forward-proxy receives a request with a Proxy-Uri or URI | When a forward-proxy receives a request with a Proxy-Uri or URI | |||
| constructed from Proxy-Scheme that indicates a multicast address, the | constructed from Proxy-Scheme that indicates a multicast address, the | |||
| proxy obtains a set of responses as described above and sends all | proxy obtains a set of responses as described above and sends all | |||
| responses (both cached-still-fresh and new) back to the original | responses (both cached-still-fresh and new) back to the original | |||
| client. | client. | |||
| This specification does not provide a way to indicate the unicast- | This specification does not provide a way to indicate the unicast- | |||
| modified request URI (base URI) in responses thus forwarded. A | modified request URI (base URI) in responses thus forwarded. | |||
| proposal to address this can be found in section 3 of | Proxying multicast requests is discussed in more detail in | |||
| [I-D.bormann-coap-misc]. | [I-D.ietf-core-groupcomm]; one proposal to address the base URI issue | |||
| can be found in section 3 of [I-D.bormann-coap-misc]. | ||||
| 9. Securing CoAP | 9. Securing CoAP | |||
| This section defines the DTLS binding for CoAP. | This section defines the DTLS binding for CoAP. | |||
| During the provisioning phase, a CoAP device is provided with the | During the provisioning phase, a CoAP device is provided with the | |||
| security information that it needs, including keying materials and | security information that it needs, including keying materials and | |||
| access control lists. This specification defines provisioning for | access control lists. This specification defines provisioning for | |||
| the RawPublicKey mode in Section 9.1.3.2.1. At the end of the | the RawPublicKey mode in Section 9.1.3.2.1. At the end of the | |||
| provisioning phase, the device will be in one of four security modes | provisioning phase, the device will be in one of four security modes | |||
| with the following information for the given mode. The NoSec and | with the following information for the given mode. The NoSec and | |||
| RawPublicKey modes are mandatory to implement for this specification. | RawPublicKey modes are mandatory to implement for this specification. | |||
| NoSec: There is no protocol level security (DTLS is disabled). | NoSec: There is no protocol level security (DTLS is disabled). | |||
| Alternative techniques to provide lower layer security SHOULD be | Alternative techniques to provide lower layer security SHOULD be | |||
| used when appropriate. The use of IPsec is discussed in | used when appropriate. The use of IPsec is discussed in | |||
| [I-D.bormann-core-ipsec-for-coap]. | [I-D.bormann-core-ipsec-for-coap]. Certain link layers in use | |||
| with constrained nodes also provide link layer security, which may | ||||
| be appropriate with proper key management. | ||||
| PreSharedKey: DTLS is enabled and there is a list of pre-shared keys | PreSharedKey: DTLS is enabled and there is a list of pre-shared keys | |||
| [RFC4279] and each key includes a list of which nodes it can be | [RFC4279] and each key includes a list of which nodes it can be | |||
| used to communicate with as described in Section 9.1.3.1. At the | used to communicate with as described in Section 9.1.3.1. At the | |||
| extreme there may be one key for each node this CoAP node needs to | extreme there may be one key for each node this CoAP node needs to | |||
| communicate with (1:1 node/key ratio). | communicate with (1:1 node/key ratio). Conversely, if more than | |||
| two entities share a specific pre-shared key, this key only | ||||
| enables the entities to authenticate as a member of that group and | ||||
| not as a specific peer. | ||||
| RawPublicKey: DTLS is enabled and the device has an asymmetric key | RawPublicKey: DTLS is enabled and the device has an asymmetric key | |||
| pair without a certificate (a raw public key) that is validated | pair without a certificate (a raw public key) that is validated | |||
| using an out-of-band mechanism [I-D.ietf-tls-oob-pubkey] as | using an out-of-band mechanism [I-D.ietf-tls-oob-pubkey] as | |||
| described in Section 9.1.3.2. The device also has an identity | described in Section 9.1.3.2. The device also has an identity | |||
| calculated from the public key and a list of identities of the | calculated from the public key and a list of identities of the | |||
| nodes it can communicate with. | nodes it can communicate with. | |||
| Certificate: DTLS is enabled and the device has an asymmetric key | Certificate: DTLS is enabled and the device has an asymmetric key | |||
| pair with an X.509 certificate [RFC5280] that binds it to its | pair with an X.509 certificate [RFC5280] that binds it to its | |||
| skipping to change at page 65, line 7 ¶ | skipping to change at page 68, line 21 ¶ | |||
| Just as HTTP is secured using Transport Layer Security (TLS) over | Just as HTTP is secured using Transport Layer Security (TLS) over | |||
| TCP, CoAP is secured using Datagram TLS (DTLS) [RFC6347] over UDP | TCP, CoAP is secured using Datagram TLS (DTLS) [RFC6347] over UDP | |||
| (see Figure 13). This section defines the CoAP binding to DTLS, | (see Figure 13). This section defines the CoAP binding to DTLS, | |||
| along with the minimal mandatory-to-implement configurations | along with the minimal mandatory-to-implement configurations | |||
| appropriate for constrained environments. The binding is defined by | appropriate for constrained environments. The binding is defined by | |||
| a series of deltas to Unicast CoAP. DTLS is in practice TLS with | a series of deltas to Unicast CoAP. DTLS is in practice TLS with | |||
| added features to deal with the unreliable nature of the UDP | added features to deal with the unreliable nature of the UDP | |||
| transport. | transport. | |||
| +----------------------+ | +----------------------+ | |||
| | Application | | | Application | | |||
| +----------------------+ | +----------------------+ | |||
| +----------------------+ | +----------------------+ | |||
| | Requests/Responses | | | Requests/Responses | | |||
| |----------------------| CoAP | |----------------------| CoAP | |||
| | Messages | | | Messages | | |||
| +----------------------+ | +----------------------+ | |||
| +----------------------+ | +----------------------+ | |||
| | DTLS | | | DTLS | | |||
| +----------------------+ | +----------------------+ | |||
| +----------------------+ | +----------------------+ | |||
| | UDP | | | UDP | | |||
| +----------------------+ | +----------------------+ | |||
| Figure 13: Abstract layering of DTLS-secured CoAP | Figure 13: Abstract layering of DTLS-secured CoAP | |||
| In some constrained nodes (limited flash and/or RAM) and networks | In some constrained nodes (limited flash and/or RAM) and networks | |||
| (limited bandwidth or high scalability requirements), and depending | (limited bandwidth or high scalability requirements), and depending | |||
| on the specific cipher suites in use, all modes of DTLS may not be | on the specific cipher suites in use, all modes of DTLS may not be | |||
| applicable. Some DTLS cipher suites can add significant | applicable. Some DTLS cipher suites can add significant | |||
| implementation complexity as well as some initial handshake overhead | implementation complexity as well as some initial handshake overhead | |||
| needed when setting up the security association. Once the initial | needed when setting up the security association. Once the initial | |||
| handshake is completed, DTLS adds a limited per-datagram overhead of | handshake is completed, DTLS adds a limited per-datagram overhead of | |||
| skipping to change at page 66, line 39 ¶ | skipping to change at page 69, line 49 ¶ | |||
| DTLS connection when they need to recover resources but in general | DTLS connection when they need to recover resources but in general | |||
| they should keep the connection up for as long as possible. Closing | they should keep the connection up for as long as possible. Closing | |||
| the DTLS connection after every CoAP message exchange is very | the DTLS connection after every CoAP message exchange is very | |||
| inefficient. | inefficient. | |||
| 9.1.2. Request/Response Layer | 9.1.2. Request/Response Layer | |||
| The following rules are added for matching a response to a request: | The following rules are added for matching a response to a request: | |||
| The DTLS session MUST be the same and the epoch MUST be the same. | The DTLS session MUST be the same and the epoch MUST be the same. | |||
| This means the response to a DTLS secured request MUST always be DTLS | ||||
| secured using the same security session and epoch. Any attempt to | ||||
| supply a NoSec response to a DTLS request simply does not match the | ||||
| request and (unless it does match an unrelated NoSec request) | ||||
| therefore MUST be rejected. | ||||
| 9.1.3. Endpoint Identity | 9.1.3. Endpoint Identity | |||
| Devices SHOULD support the Server Name Indication (SNI) to indicate | Devices SHOULD support the Server Name Indication (SNI) to indicate | |||
| their Authority Name in the SNI HostName field as defined in Section | their Authority Name in the SNI HostName field as defined in | |||
| 3 of [RFC6066]. This is needed so that when a host that acts as a | Section 3 of [RFC6066]. This is needed so that when a host that acts | |||
| virtual server for multiple Authorities receives a new DTLS | as a virtual server for multiple Authorities receives a new DTLS | |||
| connection, it knows which keys to use for the DTLS session. | connection, it knows which keys to use for the DTLS session. | |||
| 9.1.3.1. Pre-Shared Keys | 9.1.3.1. Pre-Shared Keys | |||
| When forming a connection to a new node, the system selects an | When forming a connection to a new node, the system selects an | |||
| appropriate key based on which nodes it is trying to reach and then | appropriate key based on which nodes it is trying to reach and then | |||
| forms a DTLS session using a PSK (Pre-Shared Key) mode of DTLS. | forms a DTLS session using a PSK (Pre-Shared Key) mode of DTLS. | |||
| Implementations in these modes MUST support the mandatory to | Implementations in these modes MUST support the mandatory to | |||
| implement cipher suite TLS_PSK_WITH_AES_128_CCM_8 as specified in | implement cipher suite TLS_PSK_WITH_AES_128_CCM_8 as specified in | |||
| [RFC6655]. | [RFC6655]. | |||
| Depending on the commissioning model, applications may need to define | ||||
| an application profile for identity hints as required and detailed in | ||||
| [RFC4279] (Section 5.2) to enable the use of PSK identity hints. | ||||
| The security considerations of [RFC4279] (Section 7) apply. In | The security considerations of [RFC4279] (Section 7) apply. In | |||
| particular, applications should carefully weigh whether they need | particular, applications should carefully weigh whether they need | |||
| Perfect Forward Secrecy (PFS) or not and select an appropriate cipher | Perfect Forward Secrecy (PFS) or not and select an appropriate cipher | |||
| suite (7.1). The entropy of the PSK must be sufficient to mitigate | suite (7.1). The entropy of the PSK must be sufficient to mitigate | |||
| against brute-force and (where the PSK is not chosen randomly but by | against brute-force and (where the PSK is not chosen randomly but by | |||
| a human) dictionary attacks (7.2). The cleartext communication of | a human) dictionary attacks (7.2). The cleartext communication of | |||
| client identities may leak data or compromise privacy (7.3). | client identities may leak data or compromise privacy (7.3). | |||
| 9.1.3.2. Raw Public Key Certificates | 9.1.3.2. Raw Public Key Certificates | |||
| In this mode the device has an asymmetric key pair but without an | In this mode the device has an asymmetric key pair but without an | |||
| X.509 certificate (called a raw public key). A device MAY be | X.509 certificate (called a raw public key); e.g., the asymmetric key | |||
| configured with multiple raw public keys. The type and length of the | pair is generated by the manufacturer and installed on the device | |||
| raw public key depends on the cipher suite used. Implementations in | (see also Section 11.6). A device MAY be configured with multiple | |||
| RawPublicKey mode MUST support the mandatory to implement cipher | raw public keys. The type and length of the raw public key depends | |||
| suite TLS_ECDHE_ECDSA_WITH_AES_128_CCM_8 as specified in | on the cipher suite used. Implementations in RawPublicKey mode MUST | |||
| [I-D.mcgrew-tls-aes-ccm-ecc], [RFC5246], [RFC4492]. Some guidance | support the mandatory to implement cipher suite | |||
| relevant to the implementation of this cipher suite can be found in | TLS_ECDHE_ECDSA_WITH_AES_128_CCM_8 as specified in | |||
| [W3CXMLSEC]. The mechanism for using raw public keys with TLS is | [I-D.mcgrew-tls-aes-ccm-ecc], [RFC5246], [RFC4492]. The key used | |||
| specified in [I-D.ietf-tls-oob-pubkey]. | MUST be ECDSA-capable. The curve secp256r1 MUST be supported | |||
| [RFC4492]; this curve is equivalent to the NIST P-256 curve. The | ||||
| hash algorithm is SHA-256. Implementations MUST use the Supported | ||||
| Elliptic Curves Extension and Supported Point Format extensions | ||||
| [RFC4492]; the uncompressed point format MUST be supported; [RFC6090] | ||||
| can be used as an implementation method. Some guidance relevant to | ||||
| the implementation of this cipher suite can be found in [W3CXMLSEC]. | ||||
| The mechanism for using raw public keys with TLS is specified in | ||||
| [I-D.ietf-tls-oob-pubkey]. | ||||
| Implementation Note: Specifically, this means the extensions listed | ||||
| in Figure 14 with at least the values listed will be present in | ||||
| the DTLS handshake. | ||||
| Extension: elliptic_curves | ||||
| Type: elliptic_curves (0x000a) | ||||
| Length: 4 | ||||
| Elliptic Curves Length: 2 | ||||
| Elliptic curves (1 curve) | ||||
| Elliptic curve: secp256r1 (0x0017) | ||||
| Extension: ec_point_formats | ||||
| Type: ec_point_formats (0x000b) | ||||
| Length: 2 | ||||
| EC point formats Length: 1 | ||||
| Elliptic curves point formats (1) | ||||
| EC point format: uncompressed (0) | ||||
| Extension: signature_algorithms | ||||
| Type: signature_algorithms (0x000d) | ||||
| Length: 4 | ||||
| Data (4 bytes): 00 02 04 03 | ||||
| HashAlgorithm: sha256 (4) | ||||
| SignatureAlgorithm: ecdsa (3) | ||||
| Figure 14: DTLS extensions present for | ||||
| TLS_ECDHE_ECDSA_WITH_AES_128_CCM_8 | ||||
| 9.1.3.2.1. Provisioning | 9.1.3.2.1. Provisioning | |||
| The RawPublicKey mode was designed to be easily provisioned in M2M | The RawPublicKey mode was designed to be easily provisioned in M2M | |||
| deployments. It is assumed that each device has an appropriate | deployments. It is assumed that each device has an appropriate | |||
| asymmetric public key pair installed. An identifier is calculated | asymmetric public key pair installed. An identifier is calculated by | |||
| from the public key as described in Section 2 of | the endpoint from the public key as described in Section 2 of | |||
| [I-D.farrell-decade-ni]. All implementations that support checking | [RFC6920]. All implementations that support checking RawPublicKey | |||
| RawPublicKey identities MUST support at least the sha-256-120 mode | identities MUST support at least the sha-256-120 mode (SHA-256 | |||
| (SHA-256 truncated to 120 bits). Implementations SHOULD support also | truncated to 120 bits). Implementations SHOULD support also longer | |||
| longer length identifiers and MAY support shorter lengths. Note that | length identifiers and MAY support shorter lengths. Note that the | |||
| the shorter lengths provide less security against attacks and their | shorter lengths provide less security against attacks and their use | |||
| use is NOT RECOMMENDED. | is NOT RECOMMENDED. | |||
| Depending on how identifiers are given to the system that verifies | Depending on how identifiers are given to the system that verifies | |||
| them, support for URI, binary, and/or human-speakable format | them, support for URI, binary, and/or human-speakable format | |||
| [I-D.farrell-decade-ni] needs to be implemented. All implementations | ||||
| SHOULD support the binary mode and implementations that have a user | [RFC6920] needs to be implemented. All implementations SHOULD | |||
| support the binary mode and implementations that have a user | ||||
| interface SHOULD also support the human-speakable format. | interface SHOULD also support the human-speakable format. | |||
| During provisioning, the identifier of each node is collected, for | During provisioning, the identifier of each node is collected, for | |||
| example by reading a barcode on the outside of the device or by | example by reading a barcode on the outside of the device or by | |||
| obtaining a pre-compiled list of the identifiers. These identifiers | obtaining a pre-compiled list of the identifiers. These identifiers | |||
| are then installed in the corresponding endpoint, for example an M2M | are then installed in the corresponding endpoint, for example an M2M | |||
| data collection server. The identifier is used for two purposes, to | data collection server. The identifier is used for two purposes, to | |||
| associate the endpoint with further device information and to perform | associate the endpoint with further device information and to perform | |||
| access control. During provisioning, an access control list of | access control. During (initial and ongoing) provisioning, an access | |||
| identifiers the device may start DTLS sessions with SHOULD also be | control list of identifiers the device may start DTLS sessions with | |||
| installed. | SHOULD also be installed and maintained. | |||
| 9.1.3.3. X.509 Certificates | 9.1.3.3. X.509 Certificates | |||
| Implementations in Certificate Mode MUST support the mandatory to | Implementations in Certificate Mode MUST support the mandatory to | |||
| implement cipher suite TLS_ECDHE_ECDSA_WITH_AES_128_CCM_8 as | implement cipher suite TLS_ECDHE_ECDSA_WITH_AES_128_CCM_8 as | |||
| specified in [RFC5246]. | specified in [I-D.mcgrew-tls-aes-ccm-ecc], [RFC5246], [RFC4492]. | |||
| Namely, the certificate includes a SubjectPublicKeyInfo that | ||||
| indicates an algorithm of id-ecPublicKey with namedCurves secp256r1 | ||||
| [RFC5480]; the public key format is uncompressed [RFC5480]; the hash | ||||
| algorithm is SHA-256; if included the key usage extension indicates | ||||
| digitalSignature. Certificates MUST be signed with ECDSA using | ||||
| secp256r1, and the signature MUST use SHA-256. The key used MUST be | ||||
| ECDSA-capable. The curve secp256r1 MUST be supported [RFC4492]; this | ||||
| curve is equivalent to the NIST P-256 curve. The hash algorithm is | ||||
| SHA-256. Implementations MUST use the Supported Elliptic Curves | ||||
| Extension and Supported Point Format extensions [RFC4492]; the | ||||
| uncompressed point format MUST be supported; [RFC6090] can be used as | ||||
| an implementation method. | ||||
| The Authority Name in the certificate is the name that would be used | The Authority Name in the certificate would be built out of a long | |||
| in the Host part of a CoAP URI. It is worth noting that this would | term unique identifier for the device such as the EUI-64 [EUI64]. | |||
| typically not be either an IP address or DNS name built in the usual | The Authority Name could also be based on the FQDN that was used as | |||
| way but would instead be built out of a long term unique identifier | the Host part of the CoAP URI. However, the device's IP address | |||
| for the device such as the EUI-64 [EUI64]. The discovery process | should not typically be used as the Authority name as it would change | |||
| used in the system would build up the mapping between IP addresses of | over time. The discovery process used in the system would build up | |||
| the given devices and the Authority Name for each device. Some | the mapping between IP addresses of the given devices and the | |||
| devices could have more than one Authority and would need more than a | Authority Name for each device. Some devices could have more than | |||
| single certificate. | one Authority and would need more than a single certificate. | |||
| When a new connection is formed, the certificate from the remote | When a new connection is formed, the certificate from the remote | |||
| device needs to be verified. If the CoAP node has a source of | device needs to be verified. If the CoAP node has a source of | |||
| absolute time, then the node SHOULD check that the validity dates of | absolute time, then the node SHOULD check that the validity dates of | |||
| the certificate are within range. The certificate MUST also be | the certificate are within range. The certificate MUST be validated | |||
| signed by an appropriate chain of trust. If the certificate contains | as appropriate for the security requirements, using functionality | |||
| a SubjectAltName, then the Authority Name MUST match at least one of | equivalent to the algorithm specified in [RFC5280] section 6. If the | |||
| the authority names of any CoAP URI found in a field of URI type in | certificate contains a SubjectAltName, then the Authority Name MUST | |||
| the SubjectAltName set. If there is no SubjectAltName in the | match at least one of the authority names of any CoAP URI found in a | |||
| certificate, then the Authoritative Name must match the CN found in | field of URI type in the SubjectAltName set. If there is no | |||
| the certificate using the matching rules defined in [RFC2818] with | SubjectAltName in the certificate, then the Authoritative Name MUST | |||
| the exception that certificates with wildcards are not allowed. | match the CN found in the certificate using the matching rules | |||
| defined in [RFC2818] with the exception that certificates with | ||||
| wildcards are not allowed. | ||||
| CoRE support for certificate status checking requires further study. | ||||
| As a mapping of OCSP [RFC2560] onto CoAP is not currently defined and | ||||
| OCSP may also not be easily applicable in all environments, an | ||||
| alternative approach may be using the TLS Certificate Status Request | ||||
| extension ([RFC6066] section 8, also known as "OCSP stapling") or | ||||
| preferably the Multiple Certificate Status Extension | ||||
| ([I-D.ietf-tls-multiple-cert-status-extension]), if available. | ||||
| If the system has a shared key in addition to the certificate, then a | If the system has a shared key in addition to the certificate, then a | |||
| cipher suite that includes the shared key such as | cipher suite that includes the shared key such as | |||
| TLS_RSA_PSK_WITH_AES_128_CBC_SHA [RFC4279] SHOULD be used. | TLS_ECDHE_PSK_WITH_AES_128_CBC_SHA [RFC5489] SHOULD be used. | |||
| 10. Cross-Protocol Proxying between CoAP and HTTP | 10. Cross-Protocol Proxying between CoAP and HTTP | |||
| CoAP supports a limited subset of HTTP functionality, and thus cross- | CoAP supports a limited subset of HTTP functionality, and thus cross- | |||
| protocol proxying to HTTP is straightforward. There might be several | protocol proxying to HTTP is straightforward. There might be several | |||
| reasons for proxying between CoAP and HTTP, for example when | reasons for proxying between CoAP and HTTP, for example when | |||
| designing a web interface for use over either protocol or when | designing a web interface for use over either protocol or when | |||
| realizing a CoAP-HTTP proxy. Likewise, CoAP could equally be proxied | realizing a CoAP-HTTP proxy. Likewise, CoAP could equally be proxied | |||
| to other protocols such as XMPP [RFC6120] or SIP [RFC3264]; the | to other protocols such as XMPP [RFC6120] or SIP [RFC3264]; the | |||
| definition of these mechanisms is out of scope of this specification. | definition of these mechanisms is out of scope of this specification. | |||
| skipping to change at page 69, line 40 ¶ | skipping to change at page 74, line 21 ¶ | |||
| therefore lead to wider applicability of a proxy. A separate | therefore lead to wider applicability of a proxy. A separate | |||
| specification may define a convention for URIs operating such a HTTP- | specification may define a convention for URIs operating such a HTTP- | |||
| CoAP reverse proxy [I-D.castellani-core-http-mapping]. | CoAP reverse proxy [I-D.castellani-core-http-mapping]. | |||
| 10.1. CoAP-HTTP Proxying | 10.1. CoAP-HTTP Proxying | |||
| If a request contains a Proxy-Uri or Proxy-Scheme Option with an | If a request contains a Proxy-Uri or Proxy-Scheme Option with an | |||
| 'http' or 'https' URI [RFC2616], then the receiving CoAP endpoint | 'http' or 'https' URI [RFC2616], then the receiving CoAP endpoint | |||
| (called "the proxy" henceforth) is requested to perform the operation | (called "the proxy" henceforth) is requested to perform the operation | |||
| specified by the request method on the indicated HTTP resource and | specified by the request method on the indicated HTTP resource and | |||
| return the result to the client. | return the result to the client. (See also Section 5.7 for how the | |||
| request to the proxy is formulated, including security requirements.) | ||||
| This section specifies for any CoAP request the CoAP response that | This section specifies for any CoAP request the CoAP response that | |||
| the proxy should return to the client. How the proxy actually | the proxy should return to the client. How the proxy actually | |||
| satisfies the request is an implementation detail, although the | satisfies the request is an implementation detail, although the | |||
| typical case is expected to be the proxy translating and forwarding | typical case is expected to be the proxy translating and forwarding | |||
| the request to an HTTP origin server. | the request to an HTTP origin server. | |||
| Since HTTP and CoAP share the basic set of request methods, | Since HTTP and CoAP share the basic set of request methods, | |||
| performing a CoAP request on an HTTP resource is not so different | performing a CoAP request on an HTTP resource is not so different | |||
| from performing it on a CoAP resource. The meanings of the | from performing it on a CoAP resource. The meanings of the | |||
| skipping to change at page 74, line 30 ¶ | skipping to change at page 79, line 10 ¶ | |||
| to remotely crash a node, or even remotely execute arbitrary code on | to remotely crash a node, or even remotely execute arbitrary code on | |||
| it. CoAP attempts to narrow the opportunities for introducing such | it. CoAP attempts to narrow the opportunities for introducing such | |||
| vulnerabilities by reducing parser complexity, by giving the entire | vulnerabilities by reducing parser complexity, by giving the entire | |||
| range of encodable values a meaning where possible, and by | range of encodable values a meaning where possible, and by | |||
| aggressively reducing complexity that is often caused by unnecessary | aggressively reducing complexity that is often caused by unnecessary | |||
| choice between multiple representations that mean the same thing. | choice between multiple representations that mean the same thing. | |||
| Much of the URI processing has been moved to the clients, further | Much of the URI processing has been moved to the clients, further | |||
| reducing the opportunities for introducing vulnerabilities into the | reducing the opportunities for introducing vulnerabilities into the | |||
| servers. Even so, the URI processing code in CoAP implementations is | servers. Even so, the URI processing code in CoAP implementations is | |||
| likely to be a large source of remaining vulnerabilities and should | likely to be a large source of remaining vulnerabilities and should | |||
| be implemented with special care. The most complex parser remaining | be implemented with special care. CoAP access control | |||
| could be the one for the CoRE Link Format, although this also has | implementations need to ensure they don't introduce vulnerabilities | |||
| been designed with a goal of reduced implementation complexity | through discrepancies between the code deriving access control | |||
| [RFC6690]. (See also section 15.2 of [RFC2616].) | decisions from a URI and the code finally serving up the resource | |||
| addressed by the URI. The most complex parser remaining could be the | ||||
| one for the CoRE Link Format, although this also has been designed | ||||
| with a goal of reduced implementation complexity [RFC6690]. (See | ||||
| also section 15.2 of [RFC2616].) | ||||
| 11.2. Proxying and Caching | 11.2. Proxying and Caching | |||
| As mentioned in 15.7 of [RFC2616], proxies are by their very nature | As mentioned in 15.7 of [RFC2616], proxies are by their very nature | |||
| men-in-the-middle, breaking any IPsec or DTLS protection that a | men-in-the-middle, breaking any IPsec or DTLS protection that a | |||
| direct CoAP message exchange might have. They are therefore | direct CoAP message exchange might have. They are therefore | |||
| interesting targets for breaking confidentiality or integrity of CoAP | interesting targets for breaking confidentiality or integrity of CoAP | |||
| message exchanges. As noted in [RFC2616], they are also interesting | message exchanges. As noted in [RFC2616], they are also interesting | |||
| targets for breaking availability. | targets for breaking availability. | |||
| The threat to confidentiality and integrity of request/response data | The threat to confidentiality and integrity of request/response data | |||
| is amplified where proxies also cache. Note that CoAP does not | is amplified where proxies also cache. Note that CoAP does not | |||
| define any of the cache-suppressing Cache-Control options that | define any of the cache-suppressing Cache-Control options that HTTP/ | |||
| HTTP/1.1 provides to better protect sensitive data. | 1.1 provides to better protect sensitive data. | |||
| For a caching implementation, any access control considerations that | For a caching implementation, any access control considerations that | |||
| would apply to making the request that generated the cache entry also | would apply to making the request that generated the cache entry also | |||
| need to be applied to the value in the cache. This is relevant for | need to be applied to the value in the cache. This is relevant for | |||
| clients that implement multiple security domains, as well as for | clients that implement multiple security domains, as well as for | |||
| proxies that may serve multiple clients. Also, a caching proxy MUST | proxies that may serve multiple clients. Also, a caching proxy MUST | |||
| NOT make cached values available to requests that have lesser | NOT make cached values available to requests that have lesser | |||
| transport security properties than to which it would make available | transport security properties than to which it would make available | |||
| the process of forwarding the request in the first place. | the process of forwarding the request in the first place. | |||
| skipping to change at page 75, line 37 ¶ | skipping to change at page 80, line 20 ¶ | |||
| attack packet into a larger attack packet, an approach known as | attack packet into a larger attack packet, an approach known as | |||
| amplification. There is therefore a danger that CoAP nodes could | amplification. There is therefore a danger that CoAP nodes could | |||
| become implicated in denial of service (DoS) attacks by using the | become implicated in denial of service (DoS) attacks by using the | |||
| amplifying properties of the protocol: An attacker that is attempting | amplifying properties of the protocol: An attacker that is attempting | |||
| to overload a victim but is limited in the amount of traffic it can | to overload a victim but is limited in the amount of traffic it can | |||
| generate, can use amplification to generate a larger amount of | generate, can use amplification to generate a larger amount of | |||
| traffic. | traffic. | |||
| This is particularly a problem in nodes that enable NoSec access, | This is particularly a problem in nodes that enable NoSec access, | |||
| that are accessible from an attacker and can access potential victims | that are accessible from an attacker and can access potential victims | |||
| (e.g. on the general Internet), as the UDP protocol provides no way | (e.g. on the general Internet), as the UDP protocol provides no way | |||
| to verify the source address given in the request packet. An | to verify the source address given in the request packet. An | |||
| attacker need only place the IP address of the victim in the source | attacker need only place the IP address of the victim in the source | |||
| address of a suitable request packet to generate a larger packet | address of a suitable request packet to generate a larger packet | |||
| directed at the victim. Such large amplification factors SHOULD NOT | directed at the victim. | |||
| be done in the response if the request is not authenticated. | ||||
| As a mitigating factor, many constrained networks will only be able | As a mitigating factor, many constrained networks will only be able | |||
| to generate a small amount of traffic, which may make CoAP nodes less | to generate a small amount of traffic, which may make CoAP nodes less | |||
| attractive for this attack. However, the limited capacity of the | attractive for this attack. However, the limited capacity of the | |||
| constrained network makes the network itself a likely victim of an | constrained network makes the network itself a likely victim of an | |||
| amplification attack. | amplification attack. | |||
| A CoAP server can reduce the amount of amplification it provides to | Therefore, large amplification factors SHOULD NOT be provided in the | |||
| an attacker by using slicing/blocking modes of CoAP | response if the request is not authenticated. A CoAP server can | |||
| reduce the amount of amplification it provides to an attacker by | ||||
| [I-D.ietf-core-block] and offering large resource representations | using slicing/blocking modes of CoAP [I-D.ietf-core-block] and | |||
| only in relatively small slices. E.g., for a 1000 byte resource, a | offering large resource representations only in relatively small | |||
| 10-byte request might result in an 80-byte response (with a 64-byte | slices. E.g., for a 1000 byte resource, a 10-byte request might | |||
| block) instead of a 1016-byte response, considerably reducing the | result in an 80-byte response (with a 64-byte block) instead of a | |||
| amplification provided. | 1016-byte response, considerably reducing the amplification provided. | |||
| CoAP also supports the use of multicast IP addresses in requests, an | CoAP also supports the use of multicast IP addresses in requests, an | |||
| important requirement for M2M. Multicast CoAP requests may be the | important requirement for M2M. Multicast CoAP requests may be the | |||
| source of accidental or deliberate denial of service attacks, | source of accidental or deliberate denial of service attacks, | |||
| especially over constrained networks. This specification attempts to | especially over constrained networks. This specification attempts to | |||
| reduce the amplification effects of multicast requests by limiting | reduce the amplification effects of multicast requests by limiting | |||
| when a response is returned. To limit the possibility of malicious | when a response is returned. To limit the possibility of malicious | |||
| use, CoAP servers SHOULD NOT accept multicast requests that can not | use, CoAP servers SHOULD NOT accept multicast requests that can not | |||
| be authenticated in some way, cryptographically or by some multicast | be authenticated in some way, cryptographically or by some multicast | |||
| boundary limiting the potential sources. If possible a CoAP server | boundary limiting the potential sources. If possible a CoAP server | |||
| SHOULD limit the support for multicast requests to the specific | SHOULD limit the support for multicast requests to the specific | |||
| resources where the feature is required. | resources where the feature is required. | |||
| skipping to change at page 76, line 38 ¶ | skipping to change at page 81, line 20 ¶ | |||
| FF0x::1, which are received by every IPv6 node. Implementations | FF0x::1, which are received by every IPv6 node. Implementations | |||
| SHOULD make use of modern APIs such as IPV6_RECVPKTINFO [RFC3542], if | SHOULD make use of modern APIs such as IPV6_RECVPKTINFO [RFC3542], if | |||
| available, to make this determination. | available, to make this determination. | |||
| 11.4. IP Address Spoofing Attacks | 11.4. IP Address Spoofing Attacks | |||
| Due to the lack of a handshake in UDP, a rogue endpoint which is free | Due to the lack of a handshake in UDP, a rogue endpoint which is free | |||
| to read and write messages carried by the constrained network (i.e. | to read and write messages carried by the constrained network (i.e. | |||
| NoSec or PreSharedKey deployments with nodes/key ratio > 1:1), may | NoSec or PreSharedKey deployments with nodes/key ratio > 1:1), may | |||
| easily attack a single endpoint, a group of endpoints, as well as the | easily attack a single endpoint, a group of endpoints, as well as the | |||
| whole network e.g. by: | whole network e.g. by: | |||
| 1. spoofing RST in response to a CON or NON message, thus making an | 1. spoofing RST in response to a CON or NON message, thus making an | |||
| endpoint "deaf"; or | endpoint "deaf"; or | |||
| 2. spoofing the entire response with forged payload/options (this | 2. spoofing an ACK in response to a CON message, thus potentially | |||
| preventing the sender of the CON message from retransmitting, and | ||||
| drowning out the actual response; or | ||||
| 3. spoofing the entire response with forged payload/options (this | ||||
| has different levels of impact: from single response disruption, | has different levels of impact: from single response disruption, | |||
| to much bolder attacks on the supporting infrastructure, e.g. | to much bolder attacks on the supporting infrastructure, e.g. | |||
| poisoning proxy caches, or tricking validation / lookup | poisoning proxy caches, or tricking validation / lookup | |||
| interfaces in resource directories and, more generally, any | interfaces in resource directories and, more generally, any | |||
| component that stores global network state and uses CoAP as the | component that stores global network state and uses CoAP as the | |||
| messaging facility to handle state set/update's is a potential | messaging facility to handle state set/update's is a potential | |||
| target.); or | target.); or | |||
| 3. spoofing a multicast request for a target node which may result | 4. spoofing a multicast request for a target node which may result | |||
| in both network congestion/collapse and victim DoS'ing / forced | in both network congestion/collapse and victim DoS'ing / forced | |||
| wakeup from sleeping; or | wakeup from sleeping; or | |||
| 4. spoofing observe messages, etc. | 5. spoofing observe messages, etc. | |||
| Response spoofing by off-path attackers can be detected and mitigated | Response spoofing by off-path attackers can be detected and mitigated | |||
| even without transport layer security by choosing a non-trivial, | even without transport layer security by choosing a non-trivial, | |||
| randomized token in the request (Section 5.3.1). [RFC4086] discusses | randomized token in the request (Section 5.3.1). [RFC4086] discusses | |||
| randomness requirements for security. | randomness requirements for security. | |||
| In principle, other kinds of spoofing can be detected by CoAP only in | In principle, other kinds of spoofing can be detected by CoAP only in | |||
| case CON semantics is used, because of unexpected ACK/RSTs coming | case CON semantics is used, because of unexpected ACK/RSTs coming | |||
| from the deceived endpoint. But this imposes keeping track of the | from the deceived endpoint. But this imposes keeping track of the | |||
| used Message IDs which is not always possible, and moreover detection | used Message IDs which is not always possible, and moreover detection | |||
| skipping to change at page 79, line 21 ¶ | skipping to change at page 83, line 43 ¶ | |||
| +--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+ | +--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+ | |||
| | QDCOUNT | (options 0) | | QDCOUNT | (options 0) | |||
| +--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+ | +--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+ | |||
| | ANCOUNT | (options 0) | | ANCOUNT | (options 0) | |||
| +--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+ | +--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+ | |||
| | NSCOUNT | (options 0) | | NSCOUNT | (options 0) | |||
| +--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+ | +--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+ | |||
| | ARCOUNT | (options 0) | | ARCOUNT | (options 0) | |||
| +--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+ | +--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+ | |||
| Figure 14: DNS Header vs. CoAP Message | Figure 15: DNS Header vs. CoAP Message | |||
| In general, for any pair of protocols, one of the protocols can very | In general, for any pair of protocols, one of the protocols can very | |||
| well have been designed in a way that enables an attacker to cause | well have been designed in a way that enables an attacker to cause | |||
| the generation of replies that look like messages of the other | the generation of replies that look like messages of the other | |||
| protocol. It is often much harder to ensure or prove the absence of | protocol. It is often much harder to ensure or prove the absence of | |||
| viable attacks than to generate examples that may not yet completely | viable attacks than to generate examples that may not yet completely | |||
| enable an attack but might be further developed by more creative | enable an attack but might be further developed by more creative | |||
| minds. Cross-protocol attacks can therefore only be completely | minds. Cross-protocol attacks can therefore only be completely | |||
| mitigated if endpoints don't authorize actions desired by an attacker | mitigated if endpoints don't authorize actions desired by an attacker | |||
| just based on trusting the source IP address of a packet. | just based on trusting the source IP address of a packet. | |||
| skipping to change at page 79, line 43 ¶ | skipping to change at page 84, line 17 ¶ | |||
| for CoAP security not only needs to firewall off the CoAP endpoints | for CoAP security not only needs to firewall off the CoAP endpoints | |||
| but also all other endpoints that might be incited to send UDP | but also all other endpoints that might be incited to send UDP | |||
| messages to CoAP endpoints using some other UDP-based protocol. | messages to CoAP endpoints using some other UDP-based protocol. | |||
| In addition to the considerations above, the security considerations | In addition to the considerations above, the security considerations | |||
| for DTLS with respect to cross-protocol attacks apply. E.g., if the | for DTLS with respect to cross-protocol attacks apply. E.g., if the | |||
| same DTLS security association ("connection") is used to carry data | same DTLS security association ("connection") is used to carry data | |||
| of multiple protocols, DTLS no longer provides protection against | of multiple protocols, DTLS no longer provides protection against | |||
| cross-protocol attacks between these protocols. | cross-protocol attacks between these protocols. | |||
| 11.6. Constrained node considerations | ||||
| Implementers on constrained nodes often find themselves without a | ||||
| good source of entropy [RFC4086]. If that is the case, the node MUST | ||||
| NOT be used for processes that require good entropy, such as key | ||||
| generation. Instead, keys should be generated externally and added | ||||
| to the device during manufacturing or commissioning. | ||||
| Due to their low processing power, constrained nodes are particularly | ||||
| susceptible to timing attacks. Special care must be taken in | ||||
| implementation of cryptographic primitives. | ||||
| Large numbers of constrained nodes will be installed in exposed | ||||
| environments and will have little resistance to tampering, including | ||||
| recovery of keying materials. This needs to be considered when | ||||
| defining the scope of credentials assigned to them. In particular, | ||||
| assigning a shared key to a group of nodes may make any single | ||||
| constrained node a target for subverting the entire group. | ||||
| 12. IANA Considerations | 12. IANA Considerations | |||
| 12.1. CoAP Code Registry | 12.1. CoAP Code Registries | |||
| This document defines a registry for the values of the Code field in | This document defines two sub-registries for the values of the Code | |||
| the CoAP header. The name of the registry is "CoAP Codes". | field in the CoAP header within the Constrained RESTful Environments | |||
| (CoRE) Parameters ("CoRE Parameters") registry. | ||||
| All values are assigned by sub-registries according to the following | Values in the two sub-registries are eight-bit values notated as | |||
| ranges: | three decimal digits c.dd separated by a period between the first and | |||
| the second digit; the first digit c is between 0 and 7 and denotes | ||||
| the code class; the second and third digit dd denote a decimal number | ||||
| between 00 and 31 for the detail. | ||||
| 0 Indicates an empty message (see Section 4.1). | All Code values are assigned by sub-registries according to the | |||
| following ranges: | ||||
| 1-31 Indicates a request. Values in this range are assigned by | 0.00 Indicates an Empty message (see Section 4.1). | |||
| 0.01-0.31 Indicates a request. Values in this range are assigned by | ||||
| the "CoAP Method Codes" sub-registry (see Section 12.1.1). | the "CoAP Method Codes" sub-registry (see Section 12.1.1). | |||
| 32-63 Reserved | 1.00-1.31 Reserved | |||
| 64-191 Indicates a response. Values in this range are assigned by | 2.00-5.31 Indicates a response. Values in this range are assigned by | |||
| the "CoAP Response Codes" sub-registry (see | the "CoAP Response Codes" sub-registry (see | |||
| Section 12.1.2). | Section 12.1.2). | |||
| 192-255 Reserved | 6.00-7.31 Reserved | |||
| 12.1.1. Method Codes | 12.1.1. Method Codes | |||
| The name of the sub-registry is "CoAP Method Codes". | The name of the sub-registry is "CoAP Method Codes". | |||
| Each entry in the sub-registry must include the Method Code in the | Each entry in the sub-registry must include the Method Code in the | |||
| range 1-31, the name of the method, and a reference to the method's | range 0.01-0.31, the name of the method, and a reference to the | |||
| documentation. | method's documentation. | |||
| Initial entries in this sub-registry are as follows: | Initial entries in this sub-registry are as follows: | |||
| +------+--------+-----------+ | +------+--------+-----------+ | |||
| | Code | Name | Reference | | | Code | Name | Reference | | |||
| +------+--------+-----------+ | +------+--------+-----------+ | |||
| | 1 | GET | [RFCXXXX] | | | 0.01 | GET | [RFCXXXX] | | |||
| | 2 | POST | [RFCXXXX] | | | 0.02 | POST | [RFCXXXX] | | |||
| | 3 | PUT | [RFCXXXX] | | | 0.03 | PUT | [RFCXXXX] | | |||
| | 4 | DELETE | [RFCXXXX] | | | 0.04 | DELETE | [RFCXXXX] | | |||
| +------+--------+-----------+ | +------+--------+-----------+ | |||
| Table 4: CoAP Method Codes | Table 5: CoAP Method Codes | |||
| All other Method Codes are Unassigned. | All other Method Codes are Unassigned. | |||
| The IANA policy for future additions to this registry is "IETF Review | The IANA policy for future additions to this sub-registry is "IETF | |||
| or IESG approval" as described in [RFC5226]. | Review or IESG approval" as described in [RFC5226]. | |||
| The documentation of a method code should specify the semantics of a | The documentation of a method code should specify the semantics of a | |||
| request with that code, including the following properties: | request with that code, including the following properties: | |||
| o The response codes the method returns in the success case. | o The response codes the method returns in the success case. | |||
| o Whether the method is idempotent, safe, or both. | o Whether the method is idempotent, safe, or both. | |||
| 12.1.2. Response Codes | 12.1.2. Response Codes | |||
| The name of the sub-registry is "CoAP Response Codes". | The name of the sub-registry is "CoAP Response Codes". | |||
| Each entry in the sub-registry must include the Response Code in the | Each entry in the sub-registry must include the Response Code in the | |||
| range 64-191, a description of the Response Code, and a reference to | range 2.00-5.31, a description of the Response Code, and a reference | |||
| the Response Code's documentation. | to the Response Code's documentation. | |||
| Initial entries in this sub-registry are as follows: | Initial entries in this sub-registry are as follows: | |||
| +------+---------------------------------+-----------+ | +------+------------------------------+-----------+ | |||
| | Code | Description | Reference | | | Code | Description | Reference | | |||
| +------+---------------------------------+-----------+ | +------+------------------------------+-----------+ | |||
| | 65 | 2.01 Created | [RFCXXXX] | | | 2.01 | Created | [RFCXXXX] | | |||
| | 66 | 2.02 Deleted | [RFCXXXX] | | | 2.02 | Deleted | [RFCXXXX] | | |||
| | 67 | 2.03 Valid | [RFCXXXX] | | | 2.03 | Valid | [RFCXXXX] | | |||
| | 68 | 2.04 Changed | [RFCXXXX] | | | 2.04 | Changed | [RFCXXXX] | | |||
| | 69 | 2.05 Content | [RFCXXXX] | | | 2.05 | Content | [RFCXXXX] | | |||
| | 128 | 4.00 Bad Request | [RFCXXXX] | | | 4.00 | Bad Request | [RFCXXXX] | | |||
| | 129 | 4.01 Unauthorized | [RFCXXXX] | | | 4.01 | Unauthorized | [RFCXXXX] | | |||
| | 130 | 4.02 Bad Option | [RFCXXXX] | | | 4.02 | Bad Option | [RFCXXXX] | | |||
| | 131 | 4.03 Forbidden | [RFCXXXX] | | | 4.03 | Forbidden | [RFCXXXX] | | |||
| | 132 | 4.04 Not Found | [RFCXXXX] | | | 4.04 | Not Found | [RFCXXXX] | | |||
| | 133 | 4.05 Method Not Allowed | [RFCXXXX] | | | 4.05 | Method Not Allowed | [RFCXXXX] | | |||
| | 134 | 4.06 Not Acceptable | [RFCXXXX] | | | 4.06 | Not Acceptable | [RFCXXXX] | | |||
| | 140 | 4.12 Precondition Failed | [RFCXXXX] | | | 4.12 | Precondition Failed | [RFCXXXX] | | |||
| | 141 | 4.13 Request Entity Too Large | [RFCXXXX] | | | 4.13 | Request Entity Too Large | [RFCXXXX] | | |||
| | 143 | 4.15 Unsupported Content-Format | [RFCXXXX] | | | 4.15 | Unsupported Content-Format | [RFCXXXX] | | |||
| | 160 | 5.00 Internal Server Error | [RFCXXXX] | | | 5.00 | Internal Server Error | [RFCXXXX] | | |||
| | 161 | 5.01 Not Implemented | [RFCXXXX] | | | 5.01 | Not Implemented | [RFCXXXX] | | |||
| | 162 | 5.02 Bad Gateway | [RFCXXXX] | | | 5.02 | Bad Gateway | [RFCXXXX] | | |||
| | 163 | 5.03 Service Unavailable | [RFCXXXX] | | | 5.03 | Service Unavailable | [RFCXXXX] | | |||
| | 164 | 5.04 Gateway Timeout | [RFCXXXX] | | | 5.04 | Gateway Timeout | [RFCXXXX] | | |||
| | 165 | 5.05 Proxying Not Supported | [RFCXXXX] | | | 5.05 | Proxying Not Supported | [RFCXXXX] | | |||
| +------+---------------------------------+-----------+ | +------+------------------------------+-----------+ | |||
| Table 5: CoAP Response Codes | Table 6: CoAP Response Codes | |||
| The Response Codes 96-127 are Reserved for future use. All other | The Response Codes 3.00-3.31 are Reserved for future use. All other | |||
| Response Codes are Unassigned. | Response Codes are Unassigned. | |||
| The IANA policy for future additions to this registry is "IETF Review | The IANA policy for future additions to this sub-registry is "IETF | |||
| or IESG approval" as described in [RFC5226]. | Review or IESG approval" as described in [RFC5226]. | |||
| The documentation of a response code should specify the semantics of | The documentation of a response code should specify the semantics of | |||
| a response with that code, including the following properties: | a response with that code, including the following properties: | |||
| o The methods the response code applies to. | o The methods the response code applies to. | |||
| o Whether payload is required, optional or not allowed. | o Whether payload is required, optional or not allowed. | |||
| o The semantics of the payload. For example, the payload of a 2.05 | o The semantics of the payload. For example, the payload of a 2.05 | |||
| (Content) response is a representation of the target resource; the | (Content) response is a representation of the target resource; the | |||
| skipping to change at page 82, line 30 ¶ | skipping to change at page 87, line 26 ¶ | |||
| model. | model. | |||
| o Whether the response is validatable according to the validation | o Whether the response is validatable according to the validation | |||
| model. | model. | |||
| o Whether the response causes a cache to mark responses stored for | o Whether the response causes a cache to mark responses stored for | |||
| the request URI as not fresh. | the request URI as not fresh. | |||
| 12.2. Option Number Registry | 12.2. Option Number Registry | |||
| This document defines a registry for the Option Numbers used in CoAP | This document defines a sub-registry for the Option Numbers used in | |||
| options. The name of the registry is "CoAP Option Numbers". | CoAP options within the "CoRE Parameters" registry. The name of the | |||
| sub-registry is "CoAP Option Numbers". | ||||
| Each entry in the registry must include the Option Number, the name | Each entry in the sub-registry must include the Option Number, the | |||
| of the option and a reference to the option's documentation. | name of the option and a reference to the option's documentation. | |||
| Initial entries in this registry are as follows: | Initial entries in this sub-registry are as follows: | |||
| +--------+----------------+-----------+ | +--------+------------------+-----------+ | |||
| | Number | Name | Reference | | | Number | Name | Reference | | |||
| +--------+----------------+-----------+ | +--------+------------------+-----------+ | |||
| | 0 | (Reserved) | | | | 0 | (Reserved) | [RFCXXXX] | | |||
| | 1 | If-Match | [RFCXXXX] | | | 1 | If-Match | [RFCXXXX] | | |||
| | 3 | Uri-Host | [RFCXXXX] | | | 3 | Uri-Host | [RFCXXXX] | | |||
| | 4 | ETag | [RFCXXXX] | | | 4 | ETag | [RFCXXXX] | | |||
| | 5 | If-None-Match | [RFCXXXX] | | | 5 | If-None-Match | [RFCXXXX] | | |||
| | 7 | Uri-Port | [RFCXXXX] | | | 7 | Uri-Port | [RFCXXXX] | | |||
| | 8 | Location-Path | [RFCXXXX] | | | 8 | Location-Path | [RFCXXXX] | | |||
| | 11 | Uri-Path | [RFCXXXX] | | | 11 | Uri-Path | [RFCXXXX] | | |||
| | 12 | Content-Format | [RFCXXXX] | | | 12 | Content-Format | [RFCXXXX] | | |||
| | 14 | Max-Age | [RFCXXXX] | | | 14 | Max-Age | [RFCXXXX] | | |||
| | 15 | Uri-Query | [RFCXXXX] | | | 15 | Uri-Query | [RFCXXXX] | | |||
| | 16 | Accept | [RFCXXXX] | | | 17 | Accept | [RFCXXXX] | | |||
| | 20 | Location-Query | [RFCXXXX] | | | 20 | Location-Query | [RFCXXXX] | | |||
| | 35 | Proxy-Uri | [RFCXXXX] | | | 35 | Proxy-Uri | [RFCXXXX] | | |||
| | 39 | Proxy-Scheme | [RFCXXXX] | | | 39 | Proxy-Scheme | [RFCXXXX] | | |||
| | 128 | (Reserved) | [RFCXXXX] | | | 60 | Size1 | [RFCXXXX] | | |||
| | 132 | (Reserved) | [RFCXXXX] | | | 128 | (Reserved) | [RFCXXXX] | | |||
| | 136 | (Reserved) | [RFCXXXX] | | | 132 | (Reserved) | [RFCXXXX] | | |||
| | 140 | (Reserved) | [RFCXXXX] | | | 136 | (Reserved) | [RFCXXXX] | | |||
| +--------+----------------+-----------+ | | 140 | (Reserved) | [RFCXXXX] | | |||
| +--------+------------------+-----------+ | ||||
| Table 6: CoAP Option Numbers | Table 7: CoAP Option Numbers | |||
| The IANA policy for future additions to this registry is split into | The IANA policy for future additions to this sub-registry is split | |||
| three tiers as follows. The range of 0..255 is reserved for options | into three tiers as follows. The range of 0..255 is reserved for | |||
| defined by the IETF (IETF Review or IESG approval). The range of | options defined by the IETF (IETF Review or IESG approval). The | |||
| 256..2047 is reserved for commonly used options with public | range of 256..2047 is reserved for commonly used options with public | |||
| specifications (Specification Required). The range of 2048..64999 is | specifications (Specification Required). The range of 2048..64999 is | |||
| for all other options including private or vendor specific ones, | for all other options including private or vendor specific ones, | |||
| which undergo a Designated Expert review to help ensure that the | which undergo a Designated Expert review to help ensure that the | |||
| option semantics are defined correctly. The option numbers between | option semantics are defined correctly. The option numbers between | |||
| 65000 and 65535 inclusive are reserved for experiments. They are not | 65000 and 65535 inclusive are reserved for experiments. They are not | |||
| meant for vendor specific use of any kind and MUST NOT be used in | meant for vendor specific use of any kind and MUST NOT be used in | |||
| operational deployments. | operational deployments. | |||
| +---------------+------------------------------+ | +---------------+------------------------------+ | |||
| | Option Number | Policy [RFC5226] | | | Option Number | Policy [RFC5226] | | |||
| +---------------+------------------------------+ | +---------------+------------------------------+ | |||
| | 0..255 | IETF Review or IESG approval | | | 0..255 | IETF Review or IESG approval | | |||
| | 256..2047 | Specification Required | | | 256..2047 | Specification Required | | |||
| | 2048..64999 | Designated Expert | | | 2048..64999 | Designated Expert | | |||
| | 65000..65535 | Reserved for experiments | | | 65000..65535 | Reserved for experiments | | |||
| +---------------+------------------------------+ | +---------------+------------------------------+ | |||
| Table 7: CoAP Option Number Registry Policy | Table 8: CoAP Option Number Registry Policy | |||
| The documentation of an Option Number should specify the semantics of | The documentation of an Option Number should specify the semantics of | |||
| an option with that number, including the following properties: | an option with that number, including the following properties: | |||
| o The meaning of the option in a request. | o The meaning of the option in a request. | |||
| o The meaning of the option in a response. | o The meaning of the option in a response. | |||
| o Whether the option is critical or elective, as determined by the | o Whether the option is critical or elective, as determined by the | |||
| Option Number. | Option Number. | |||
| o Whether the option is Safe, and, if yes, whether it is part of the | o Whether the option is Safe-to-Forward, and, if yes, whether it is | |||
| Cache-Key, as determined by the Option Number (see Section 5.4.2). | part of the Cache-Key, as determined by the Option Number (see | |||
| Section 5.4.2). | ||||
| o The format and length of the option's value. | o The format and length of the option's value. | |||
| o Whether the option must occur at most once or whether it can occur | o Whether the option must occur at most once or whether it can occur | |||
| multiple times. | multiple times. | |||
| o The default value, if any. For a critical option with a default | o The default value, if any. For a critical option with a default | |||
| value, a discussion on how the default value enables processing by | value, a discussion on how the default value enables processing by | |||
| implementations not implementing the critical option | implementations not implementing the critical option | |||
| (Section 5.4.4). | (Section 5.4.4). | |||
| 12.3. Content-Format Registry | 12.3. Content-Format Registry | |||
| Internet media types are identified by a string, such as | Internet media types are identified by a string, such as "application | |||
| "application/xml" [RFC2046]. In order to minimize the overhead of | /xml" [RFC2046]. In order to minimize the overhead of using these | |||
| using these media types to indicate the format of payloads, this | media types to indicate the format of payloads, this document defines | |||
| document defines a registry for a subset of Internet media types to | a sub-registry for a subset of Internet media types to be used in | |||
| be used in CoAP and assigns each, in combination with a content- | CoAP and assigns each, in combination with a content-coding, a | |||
| coding, a numeric identifier. The name of the registry is "CoAP | numeric identifier. The name of the sub-registry is "CoAP Content- | |||
| Content-Formats". | Formats", within the "CoRE Parameters" registry. | |||
| Each entry in the registry must include the media type registered | Each entry in the sub-registry must include the media type registered | |||
| with IANA, the numeric identifier in the range 0-65535 to be used for | with IANA, the numeric identifier in the range 0-65535 to be used for | |||
| that media type in CoAP, the content-coding associated with this | that media type in CoAP, the content-coding associated with this | |||
| identifier, and a reference to a document describing what a payload | identifier, and a reference to a document describing what a payload | |||
| with that media type means semantically. | with that media type means semantically. | |||
| CoAP does not include a separate way to convey content-encoding | CoAP does not include a separate way to convey content-encoding | |||
| information with a request or response, and for that reason the | information with a request or response, and for that reason the | |||
| content-encoding is also specified for each identifier (if any). If | content-encoding is also specified for each identifier (if any). If | |||
| multiple content-encodings will be used with a media type, then a | multiple content-encodings will be used with a media type, then a | |||
| separate Content-Format identifier for each is to be registered. | separate Content-Format identifier for each is to be registered. | |||
| Similarly, other parameters related to an Internet media type, such | Similarly, other parameters related to an Internet media type, such | |||
| as level, can be defined for a CoAP Content-Format entry. | as level, can be defined for a CoAP Content-Format entry. | |||
| Initial entries in this registry are as follows: | Initial entries in this sub-registry are as follows: | |||
| +--------------------+----------+-----+-----------------------------+ | +------------------+----------+-------+-----------------------------+ | |||
| | Media type | Encoding | Id. | Reference | | | Media type | Encoding | Id. | Reference | | |||
| +--------------------+----------+-----+-----------------------------+ | +------------------+----------+-------+-----------------------------+ | |||
| | text/plain; | - | 0 | [RFC2046][RFC3676][RFC5147] | | | text/plain; | - | 0 | [RFC2046][RFC3676][RFC5147] | | |||
| | charset=utf-8 | | | | | | charset=utf-8 | | | | | |||
| | application/ | - | 40 | [RFC6690] | | | application/ | - | 40 | [RFC6690] | | |||
| | link-format | | | | | | link-format | | | | | |||
| | application/xml | - | 41 | [RFC3023] | | | application/xml | - | 41 | [RFC3023] | | |||
| | application/ | - | 42 | [RFC2045][RFC2046] | | | application/ | - | 42 | [RFC2045][RFC2046] | | |||
| | octet-stream | | | | | | octet-stream | | | | | |||
| | application/exi | - | 47 | [EXIMIME] | | | application/exi | - | 47 | [EXIMIME] | | |||
| | application/json | - | 50 | [RFC4627] | | | application/json | - | 50 | [RFC4627] | | |||
| +--------------------+----------+-----+-----------------------------+ | +------------------+----------+-------+-----------------------------+ | |||
| Table 8: CoAP Content-Formats | Table 9: CoAP Content-Formats | |||
| The identifiers between 65000 and 65535 inclusive are reserved for | The identifiers between 65000 and 65535 inclusive are reserved for | |||
| experiments. They are not meant for vendor specific use of any kind | experiments. They are not meant for vendor specific use of any kind | |||
| and MUST NOT be used in operational deployments. The identifiers | and MUST NOT be used in operational deployments. The identifiers | |||
| between 256 and 9999 are reserved for future use in IETF | between 256 and 9999 are reserved for future use in IETF | |||
| specifications (IETF review or IESG approval). All other identifiers | specifications (IETF review or IESG approval). All other identifiers | |||
| are Unassigned. | are Unassigned. | |||
| Because the name space of single-byte identifiers is so small, the | Because the name space of single-byte identifiers is so small, the | |||
| IANA policy for future additions in the range 0-255 inclusive to the | IANA policy for future additions in the range 0-255 inclusive to the | |||
| registry is "Expert Review" as described in [RFC5226]. The IANA | sub-registry is "Expert Review" as described in [RFC5226]. The IANA | |||
| policy for additions in the range 10000-64999 inclusive is "First | policy for additions in the range 10000-64999 inclusive is "First | |||
| Come First Served" as described in [RFC5226]. | Come First Served" as described in [RFC5226]. | |||
| In machine to machine applications, it is not expected that generic | In machine to machine applications, it is not expected that generic | |||
| Internet media types such as text/plain, application/xml or | Internet media types such as text/plain, application/xml or | |||
| application/octet-stream are useful for real applications in the long | application/octet-stream are useful for real applications in the long | |||
| term. It is recommended that M2M applications making use of CoAP | term. It is recommended that M2M applications making use of CoAP | |||
| will request new Internet media types from IANA indicating semantic | will request new Internet media types from IANA indicating semantic | |||
| information about how to create or parse a payload. For example, a | information about how to create or parse a payload. For example, a | |||
| Smart Energy application payload carried as XML might request a more | Smart Energy application payload carried as XML might request a more | |||
| skipping to change at page 86, line 6 ¶ | skipping to change at page 91, line 4 ¶ | |||
| 12.4. URI Scheme Registration | 12.4. URI Scheme Registration | |||
| This document requests the registration of the Uniform Resource | This document requests the registration of the Uniform Resource | |||
| Identifier (URI) scheme "coap". The registration request complies | Identifier (URI) scheme "coap". The registration request complies | |||
| with [RFC4395]. | with [RFC4395]. | |||
| URI scheme name. | URI scheme name. | |||
| coap | coap | |||
| Status. | Status. | |||
| Permanent. | Permanent. | |||
| URI scheme syntax. | URI scheme syntax. | |||
| Defined in Section 6.1 of [RFCXXXX]. | Defined in Section 6.1 of [RFCXXXX]. | |||
| URI scheme semantics. | URI scheme semantics. | |||
| The "coap" URI scheme provides a way to identify resources that | The "coap" URI scheme provides a way to identify resources that | |||
| are potentially accessible over the Constrained Application | are potentially accessible over the Constrained Application | |||
| Protocol (CoAP). The resources can be located by contacting the | Protocol (CoAP). The resources can be located by contacting the | |||
| governing CoAP server and operated on by sending CoAP requests to | governing CoAP server and operated on by sending CoAP requests to | |||
| the server. This scheme can thus be compared to the "http" URI | the server. This scheme can thus be compared to the "http" URI | |||
| scheme [RFC2616]. See Section 6 of [RFCXXXX] for the details of | scheme [RFC2616]. See Section 6 of [RFCXXXX] for the details of | |||
| operation. | operation. | |||
| Encoding considerations. | Encoding considerations. | |||
| The scheme encoding conforms to the encoding rules established for | The scheme encoding conforms to the encoding rules established for | |||
| URIs in [RFC3986], i.e. internationalized and reserved characters | URIs in [RFC3986], i.e. internationalized and reserved characters | |||
| are expressed using UTF-8-based percent-encoding. | are expressed using UTF-8-based percent-encoding. | |||
| Applications/protocols that use this URI scheme name. | Applications/protocols that use this URI scheme name. | |||
| The scheme is used by CoAP endpoints to access CoAP resources. | The scheme is used by CoAP endpoints to access CoAP resources. | |||
| Interoperability considerations. | Interoperability considerations. | |||
| None. | None. | |||
| Security considerations. | Security considerations. | |||
| See Section 11.1 of [RFCXXXX]. | See Section 11.1 of [RFCXXXX]. | |||
| skipping to change at page 87, line 23 ¶ | skipping to change at page 92, line 20 ¶ | |||
| are potentially accessible over the Constrained Application | are potentially accessible over the Constrained Application | |||
| Protocol (CoAP) using Datagram Transport Layer Security (DTLS) for | Protocol (CoAP) using Datagram Transport Layer Security (DTLS) for | |||
| transport security. The resources can be located by contacting | transport security. The resources can be located by contacting | |||
| the governing CoAP server and operated on by sending CoAP requests | the governing CoAP server and operated on by sending CoAP requests | |||
| to the server. This scheme can thus be compared to the "https" | to the server. This scheme can thus be compared to the "https" | |||
| URI scheme [RFC2616]. See Section 6 of [RFCXXXX] for the details | URI scheme [RFC2616]. See Section 6 of [RFCXXXX] for the details | |||
| of operation. | of operation. | |||
| Encoding considerations. | Encoding considerations. | |||
| The scheme encoding conforms to the encoding rules established for | The scheme encoding conforms to the encoding rules established for | |||
| URIs in [RFC3986], i.e. internationalized and reserved characters | URIs in [RFC3986], i.e. internationalized and reserved characters | |||
| are expressed using UTF-8-based percent-encoding. | are expressed using UTF-8-based percent-encoding. | |||
| Applications/protocols that use this URI scheme name. | Applications/protocols that use this URI scheme name. | |||
| The scheme is used by CoAP endpoints to access CoAP resources | The scheme is used by CoAP endpoints to access CoAP resources | |||
| using DTLS. | using DTLS. | |||
| Interoperability considerations. | Interoperability considerations. | |||
| None. | None. | |||
| Security considerations. | Security considerations. | |||
| skipping to change at page 89, line 48 ¶ | skipping to change at page 94, line 44 ¶ | |||
| 13. Acknowledgements | 13. Acknowledgements | |||
| Brian Frank was a contributor to and co-author of previous drafts of | Brian Frank was a contributor to and co-author of previous drafts of | |||
| this specification. | this specification. | |||
| Special thanks to Peter Bigot, Esko Dijk and Cullen Jennings for | Special thanks to Peter Bigot, Esko Dijk and Cullen Jennings for | |||
| substantial contributions to the ideas and text in the document, | substantial contributions to the ideas and text in the document, | |||
| along with countless detailed reviews and discussions. | along with countless detailed reviews and discussions. | |||
| Thanks to Ed Beroset, Angelo P. Castellani, Gilbert Clark, Robert | Thanks to Ed Beroset, Angelo P. Castellani, Gilbert Clark, Robert | |||
| Cragie, Esko Dijk, Lisa Dusseault, Mehmet Ersue, Thomas Fossati, Tom | Cragie, Esko Dijk, Lisa Dusseault, Mehmet Ersue, Thomas Fossati, Tom | |||
| Herbst, Richard Kelsey, Ari Keranen, Matthias Kovatsch, Salvatore | Herbst, Richard Kelsey, Ari Keranen, Matthias Kovatsch, Salvatore | |||
| Loreto, Kerry Lynn, Alexey Melnikov, Guido Moritz, Petri Mutka, Colin | Loreto, Kerry Lynn, Alexey Melnikov, Guido Moritz, Petri Mutka, Colin | |||
| O'Flynn, Charles Palmer, Adriano Pezzuto, Robert Quattlebaum, Akbar | O'Flynn, Charles Palmer, Adriano Pezzuto, Robert Quattlebaum, Akbar | |||
| Rahman, Eric Rescorla, Dan Romascanu, David Ryan, Szymon Sasin, | Rahman, Eric Rescorla, Dan Romascanu, David Ryan, Szymon Sasin, | |||
| Michael Scharf, Dale Seed, Robby Simpson, Peter van der Stok, Michael | Michael Scharf, Dale Seed, Robby Simpson, Peter van der Stok, Michael | |||
| Stuber, Linyi Tian, Gilman Tolle, Matthieu Vial and Alper Yegin for | Stuber, Linyi Tian, Gilman Tolle, Matthieu Vial and Alper Yegin for | |||
| helpful comments and discussions that have shaped the document. | helpful comments and discussions that have shaped the document. | |||
| Special thanks also to the IESG reviewers, Adrian Farrel, Martin | ||||
| Stiemerling, Pete Resnick, Richard Barnes, Sean Turner, Spencer | ||||
| Dawkins, Stephen Farrell, and Ted Lemon, who contributed in-depth | ||||
| reviews. | ||||
| Some of the text has been borrowed from the working documents of the | Some of the text has been borrowed from the working documents of the | |||
| IETF httpbis working group. | IETF httpbis working group. | |||
| 14. References | 14. References | |||
| 14.1. Normative References | 14.1. Normative References | |||
| [I-D.farrell-decade-ni] | ||||
| Farrell, S., Kutscher, D., Dannewitz, C., Ohlman, B., | ||||
| Keraenen, A., and P. Hallam-Baker, "Naming Things with | ||||
| Hashes", draft-farrell-decade-ni-10 (work in progress), | ||||
| August 2012. | ||||
| [I-D.ietf-tls-oob-pubkey] | [I-D.ietf-tls-oob-pubkey] | |||
| Wouters, P., Tschofenig, H., Gilmore, J., Weiler, S., and | Wouters, P., Tschofenig, H., Gilmore, J., Weiler, S., and | |||
| T. Kivinen, "Out-of-Band Public Key Validation for | T. Kivinen, "Out-of-Band Public Key Validation for | |||
| Transport Layer Security (TLS)", | Transport Layer Security (TLS)", draft-ietf-tls-oob- | |||
| draft-ietf-tls-oob-pubkey-07 (work in progress), | pubkey-07 (work in progress), February 2013. | |||
| February 2013. | ||||
| [I-D.mcgrew-tls-aes-ccm-ecc] | [I-D.mcgrew-tls-aes-ccm-ecc] | |||
| McGrew, D., Bailey, D., Campagna, M., and R. Dugal, "AES- | McGrew, D., Bailey, D., Campagna, M., and R. Dugal, "AES- | |||
| CCM ECC Cipher Suites for TLS", | CCM ECC Cipher Suites for TLS", draft-mcgrew-tls-aes-ccm- | |||
| draft-mcgrew-tls-aes-ccm-ecc-06 (work in progress), | ecc-06 (work in progress), February 2013. | |||
| February 2013. | ||||
| [RFC0768] Postel, J., "User Datagram Protocol", STD 6, RFC 768, | [RFC0768] Postel, J., "User Datagram Protocol", STD 6, RFC 768, | |||
| August 1980. | August 1980. | |||
| [RFC2045] Freed, N. and N. Borenstein, "Multipurpose Internet Mail | [RFC2045] Freed, N. and N.S. Borenstein, "Multipurpose Internet Mail | |||
| Extensions (MIME) Part One: Format of Internet Message | Extensions (MIME) Part One: Format of Internet Message | |||
| Bodies", RFC 2045, November 1996. | Bodies", RFC 2045, November 1996. | |||
| [RFC2046] Freed, N. and N. Borenstein, "Multipurpose Internet Mail | [RFC2046] Freed, N. and N. Borenstein, "Multipurpose Internet Mail | |||
| Extensions (MIME) Part Two: Media Types", RFC 2046, | Extensions (MIME) Part Two: Media Types", RFC 2046, | |||
| November 1996. | November 1996. | |||
| [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate | [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate | |||
| Requirement Levels", BCP 14, RFC 2119, March 1997. | Requirement Levels", BCP 14, RFC 2119, March 1997. | |||
| skipping to change at page 91, line 17 ¶ | skipping to change at page 96, line 9 ¶ | |||
| [RFC3023] Murata, M., St. Laurent, S., and D. Kohn, "XML Media | [RFC3023] Murata, M., St. Laurent, S., and D. Kohn, "XML Media | |||
| Types", RFC 3023, January 2001. | Types", RFC 3023, January 2001. | |||
| [RFC3629] Yergeau, F., "UTF-8, a transformation format of ISO | [RFC3629] Yergeau, F., "UTF-8, a transformation format of ISO | |||
| 10646", STD 63, RFC 3629, November 2003. | 10646", STD 63, RFC 3629, November 2003. | |||
| [RFC3676] Gellens, R., "The Text/Plain Format and DelSp Parameters", | [RFC3676] Gellens, R., "The Text/Plain Format and DelSp Parameters", | |||
| RFC 3676, February 2004. | RFC 3676, February 2004. | |||
| [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform | [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform | |||
| Resource Identifier (URI): Generic Syntax", STD 66, | Resource Identifier (URI): Generic Syntax", STD 66, RFC | |||
| RFC 3986, January 2005. | 3986, January 2005. | |||
| [RFC4279] Eronen, P. and H. Tschofenig, "Pre-Shared Key Ciphersuites | [RFC4279] Eronen, P. and H. Tschofenig, "Pre-Shared Key Ciphersuites | |||
| for Transport Layer Security (TLS)", RFC 4279, | for Transport Layer Security (TLS)", RFC 4279, December | |||
| December 2005. | 2005. | |||
| [RFC4395] Hansen, T., Hardie, T., and L. Masinter, "Guidelines and | [RFC4395] Hansen, T., Hardie, T., and L. Masinter, "Guidelines and | |||
| Registration Procedures for New URI Schemes", BCP 35, | Registration Procedures for New URI Schemes", BCP 35, RFC | |||
| RFC 4395, February 2006. | 4395, February 2006. | |||
| [RFC5147] Wilde, E. and M. Duerst, "URI Fragment Identifiers for the | [RFC5147] Wilde, E. and M. Duerst, "URI Fragment Identifiers for the | |||
| text/plain Media Type", RFC 5147, April 2008. | text/plain Media Type", RFC 5147, April 2008. | |||
| [RFC5198] Klensin, J. and M. Padlipsky, "Unicode Format for Network | [RFC5198] Klensin, J. and M. Padlipsky, "Unicode Format for Network | |||
| Interchange", RFC 5198, March 2008. | Interchange", RFC 5198, March 2008. | |||
| [RFC5226] Narten, T. and H. Alvestrand, "Guidelines for Writing an | [RFC5226] Narten, T. and H. Alvestrand, "Guidelines for Writing an | |||
| IANA Considerations Section in RFCs", BCP 26, RFC 5226, | IANA Considerations Section in RFCs", BCP 26, RFC 5226, | |||
| May 2008. | May 2008. | |||
| skipping to change at page 91, line 49 ¶ | skipping to change at page 96, line 41 ¶ | |||
| Specifications: ABNF", STD 68, RFC 5234, January 2008. | Specifications: ABNF", STD 68, RFC 5234, January 2008. | |||
| [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security | [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security | |||
| (TLS) Protocol Version 1.2", RFC 5246, August 2008. | (TLS) Protocol Version 1.2", RFC 5246, August 2008. | |||
| [RFC5280] Cooper, D., Santesson, S., Farrell, S., Boeyen, S., | [RFC5280] Cooper, D., Santesson, S., Farrell, S., Boeyen, S., | |||
| Housley, R., and W. Polk, "Internet X.509 Public Key | Housley, R., and W. Polk, "Internet X.509 Public Key | |||
| Infrastructure Certificate and Certificate Revocation List | Infrastructure Certificate and Certificate Revocation List | |||
| (CRL) Profile", RFC 5280, May 2008. | (CRL) Profile", RFC 5280, May 2008. | |||
| [RFC5480] Turner, S., Brown, D., Yiu, K., Housley, R., and T. Polk, | ||||
| "Elliptic Curve Cryptography Subject Public Key | ||||
| Information", RFC 5480, March 2009. | ||||
| [RFC5785] Nottingham, M. and E. Hammer-Lahav, "Defining Well-Known | [RFC5785] Nottingham, M. and E. Hammer-Lahav, "Defining Well-Known | |||
| Uniform Resource Identifiers (URIs)", RFC 5785, | Uniform Resource Identifiers (URIs)", RFC 5785, April | |||
| April 2010. | 2010. | |||
| [RFC5952] Kawamura, S. and M. Kawashima, "A Recommendation for IPv6 | [RFC5952] Kawamura, S. and M. Kawashima, "A Recommendation for IPv6 | |||
| Address Text Representation", RFC 5952, August 2010. | Address Text Representation", RFC 5952, August 2010. | |||
| [RFC5988] Nottingham, M., "Web Linking", RFC 5988, October 2010. | [RFC5988] Nottingham, M., "Web Linking", RFC 5988, October 2010. | |||
| [RFC6066] Eastlake, D., "Transport Layer Security (TLS) Extensions: | [RFC6066] Eastlake, D., "Transport Layer Security (TLS) Extensions: | |||
| Extension Definitions", RFC 6066, January 2011. | Extension Definitions", RFC 6066, January 2011. | |||
| [RFC6347] Rescorla, E. and N. Modadugu, "Datagram Transport Layer | [RFC6347] Rescorla, E. and N. Modadugu, "Datagram Transport Layer | |||
| Security Version 1.2", RFC 6347, January 2012. | Security Version 1.2", RFC 6347, January 2012. | |||
| [RFC6690] Shelby, Z., "Constrained RESTful Environments (CoRE) Link | [RFC6690] Shelby, Z., "Constrained RESTful Environments (CoRE) Link | |||
| Format", RFC 6690, August 2012. | Format", RFC 6690, August 2012. | |||
| [RFC6920] Farrell, S., Kutscher, D., Dannewitz, C., Ohlman, B., | ||||
| Keranen, A., and P. Hallam-Baker, "Naming Things with | ||||
| Hashes", RFC 6920, April 2013. | ||||
| 14.2. Informative References | 14.2. Informative References | |||
| [EUI64] "GUIDELINES FOR 64-BIT GLOBAL IDENTIFIER (EUI-64) | [EUI64] , "GUIDELINES FOR 64-BIT GLOBAL IDENTIFIER (EUI-64) | |||
| REGISTRATION AUTHORITY", April 2010, <http:// | REGISTRATION AUTHORITY", April 2010, <http:// | |||
| standards.ieee.org/regauth/oui/tutorials/EUI64.html>. | standards.ieee.org/regauth/oui/tutorials/EUI64.html>. | |||
| [EXIMIME] "Efficient XML Interchange (EXI) Format 1.0", | [EXIMIME] , "Efficient XML Interchange (EXI) Format 1.0", December | |||
| December 2009, <http://www.w3.org/TR/2009/ | 2009, <http://www.w3.org/TR/2009/CR-exi-20091208/ | |||
| CR-exi-20091208/#mediaTypeRegistration>. | #mediaTypeRegistration>. | |||
| [HHGTTG] Adams, D., "The Hitchhiker's Guide to the Galaxy", | [HHGTTG] Adams, D., "The Hitchhiker's Guide to the Galaxy", October | |||
| October 1979. | 1979. | |||
| [I-D.allman-tcpm-rto-consider] | [I-D.allman-tcpm-rto-consider] | |||
| Allman, M., "Retransmission Timeout Considerations", | Allman, M., "Retransmission Timeout Considerations", | |||
| draft-allman-tcpm-rto-consider-01 (work in progress), | draft-allman-tcpm-rto-consider-01 (work in progress), May | |||
| May 2012. | 2012. | |||
| [I-D.bormann-coap-misc] | [I-D.bormann-coap-misc] | |||
| Bormann, C. and K. Hartke, "Miscellaneous additions to | Bormann, C. and K. Hartke, "Miscellaneous additions to | |||
| CoAP", draft-bormann-coap-misc-24 (work in progress), | CoAP", draft-bormann-coap-misc-22 (work in progress), | |||
| March 2013. | December 2012. | |||
| [I-D.bormann-core-ipsec-for-coap] | [I-D.bormann-core-ipsec-for-coap] | |||
| Bormann, C., "Using CoAP with IPsec", | Bormann, C., "Using CoAP with IPsec", draft-bormann-core- | |||
| draft-bormann-core-ipsec-for-coap-00 (work in progress), | ipsec-for-coap-00 (work in progress), December 2012. | |||
| December 2012. | ||||
| [I-D.castellani-core-http-mapping] | [I-D.castellani-core-http-mapping] | |||
| Castellani, A., Loreto, S., Rahman, A., Fossati, T., and | Castellani, A., Loreto, S., Rahman, A., Fossati, T., and | |||
| E. Dijk, "Best Practices for HTTP-CoAP Mapping | E. Dijk, "Best Practices for HTTP-CoAP Mapping | |||
| Implementation", draft-castellani-core-http-mapping-07 | Implementation", draft-castellani-core-http-mapping-07 | |||
| (work in progress), February 2013. | (work in progress), February 2013. | |||
| [I-D.ietf-core-block] | [I-D.ietf-core-block] | |||
| Bormann, C. and Z. Shelby, "Blockwise transfers in CoAP", | Bormann, C. and Z. Shelby, "Blockwise transfers in CoAP", | |||
| draft-ietf-core-block-11 (work in progress), March 2013. | draft-ietf-core-block-10 (work in progress), October 2012. | |||
| [I-D.ietf-core-groupcomm] | ||||
| Rahman, A. and E. Dijk, "Group Communication for CoAP", | ||||
| draft-ietf-core-groupcomm-06 (work in progress), April | ||||
| 2013. | ||||
| [I-D.ietf-core-observe] | [I-D.ietf-core-observe] | |||
| Hartke, K., "Observing Resources in CoAP", | Hartke, K., "Observing Resources in CoAP", draft-ietf- | |||
| draft-ietf-core-observe-08 (work in progress), | core-observe-08 (work in progress), February 2013. | |||
| February 2013. | ||||
| [I-D.ietf-lwig-terminology] | [I-D.ietf-lwig-terminology] | |||
| Bormann, C., Ersue, M., and A. Keraenen, "Terminology for | Bormann, C., Ersue, M., and A. Keraenen, "Terminology for | |||
| Constrained Node Networks", draft-ietf-lwig-terminology-03 | Constrained Node Networks", draft-ietf-lwig-terminology-04 | |||
| (work in progress), March 2013. | (work in progress), April 2013. | |||
| [I-D.ietf-tls-multiple-cert-status-extension] | ||||
| Pettersen, Y., "The TLS Multiple Certificate Status | ||||
| Request Extension", draft-ietf-tls-multiple-cert-status- | ||||
| extension-08 (work in progress), April 2013. | ||||
| [REST] Fielding, R., "Architectural Styles and the Design of | [REST] Fielding, R., "Architectural Styles and the Design of | |||
| Network-based Software Architectures", Ph.D. Dissertation, | Network-based Software Architectures", Ph.D. Dissertation, | |||
| University of California, Irvine, 2000, <http:// | University of California, Irvine, 2000, <http:// | |||
| www.ics.uci.edu/~fielding/pubs/dissertation/ | www.ics.uci.edu/~fielding/pubs/dissertation/ | |||
| fielding_dissertation.pdf>. | fielding_dissertation.pdf>. | |||
| [RFC0020] Cerf, V., "ASCII format for network interchange", RFC 20, | [RFC0020] Cerf, V., "ASCII format for network interchange", RFC 20, | |||
| October 1969. | October 1969. | |||
| [RFC0793] Postel, J., "Transmission Control Protocol", STD 7, | [RFC0792] Postel, J., "Internet Control Message Protocol", STD 5, | |||
| RFC 793, September 1981. | RFC 792, September 1981. | |||
| [RFC0793] Postel, J., "Transmission Control Protocol", STD 7, RFC | ||||
| 793, September 1981. | ||||
| [RFC2560] Myers, M., Ankney, R., Malpani, A., Galperin, S., and C. | ||||
| Adams, "X.509 Internet Public Key Infrastructure Online | ||||
| Certificate Status Protocol - OCSP", RFC 2560, June 1999. | ||||
| [RFC2818] Rescorla, E., "HTTP Over TLS", RFC 2818, May 2000. | [RFC2818] Rescorla, E., "HTTP Over TLS", RFC 2818, May 2000. | |||
| [RFC3264] Rosenberg, J. and H. Schulzrinne, "An Offer/Answer Model | [RFC3264] Rosenberg, J. and H. Schulzrinne, "An Offer/Answer Model | |||
| with Session Description Protocol (SDP)", RFC 3264, | with Session Description Protocol (SDP)", RFC 3264, June | |||
| June 2002. | 2002. | |||
| [RFC3542] Stevens, W., Thomas, M., Nordmark, E., and T. Jinmei, | [RFC3542] Stevens, W., Thomas, M., Nordmark, E., and T. Jinmei, | |||
| "Advanced Sockets Application Program Interface (API) for | "Advanced Sockets Application Program Interface (API) for | |||
| IPv6", RFC 3542, May 2003. | IPv6", RFC 3542, May 2003. | |||
| [RFC3828] Larzon, L-A., Degermark, M., Pink, S., Jonsson, L-E., and | ||||
| G. Fairhurst, "The Lightweight User Datagram Protocol | ||||
| (UDP-Lite)", RFC 3828, July 2004. | ||||
| [RFC4086] Eastlake, D., Schiller, J., and S. Crocker, "Randomness | [RFC4086] Eastlake, D., Schiller, J., and S. Crocker, "Randomness | |||
| Requirements for Security", BCP 106, RFC 4086, June 2005. | Requirements for Security", BCP 106, RFC 4086, June 2005. | |||
| [RFC4443] Conta, A., Deering, S., and M. Gupta, "Internet Control | ||||
| Message Protocol (ICMPv6) for the Internet Protocol | ||||
| Version 6 (IPv6) Specification", RFC 4443, March 2006. | ||||
| [RFC4492] Blake-Wilson, S., Bolyard, N., Gupta, V., Hawk, C., and B. | [RFC4492] Blake-Wilson, S., Bolyard, N., Gupta, V., Hawk, C., and B. | |||
| Moeller, "Elliptic Curve Cryptography (ECC) Cipher Suites | Moeller, "Elliptic Curve Cryptography (ECC) Cipher Suites | |||
| for Transport Layer Security (TLS)", RFC 4492, May 2006. | for Transport Layer Security (TLS)", RFC 4492, May 2006. | |||
| [RFC4627] Crockford, D., "The application/json Media Type for | [RFC4627] Crockford, D., "The application/json Media Type for | |||
| JavaScript Object Notation (JSON)", RFC 4627, July 2006. | JavaScript Object Notation (JSON)", RFC 4627, July 2006. | |||
| [RFC4821] Mathis, M. and J. Heffner, "Packetization Layer Path MTU | ||||
| Discovery", RFC 4821, March 2007. | ||||
| [RFC4944] Montenegro, G., Kushalnagar, N., Hui, J., and D. Culler, | [RFC4944] Montenegro, G., Kushalnagar, N., Hui, J., and D. Culler, | |||
| "Transmission of IPv6 Packets over IEEE 802.15.4 | "Transmission of IPv6 Packets over IEEE 802.15.4 | |||
| Networks", RFC 4944, September 2007. | Networks", RFC 4944, September 2007. | |||
| [RFC5405] Eggert, L. and G. Fairhurst, "Unicast UDP Usage Guidelines | [RFC5405] Eggert, L. and G. Fairhurst, "Unicast UDP Usage Guidelines | |||
| for Application Designers", BCP 145, RFC 5405, | for Application Designers", BCP 145, RFC 5405, November | |||
| November 2008. | 2008. | |||
| [RFC5489] Badra, M. and I. Hajjeh, "ECDHE_PSK Cipher Suites for | ||||
| Transport Layer Security (TLS)", RFC 5489, March 2009. | ||||
| [RFC6090] McGrew, D., Igoe, K., and M. Salter, "Fundamental Elliptic | ||||
| Curve Cryptography Algorithms", RFC 6090, February 2011. | ||||
| [RFC6120] Saint-Andre, P., "Extensible Messaging and Presence | [RFC6120] Saint-Andre, P., "Extensible Messaging and Presence | |||
| Protocol (XMPP): Core", RFC 6120, March 2011. | Protocol (XMPP): Core", RFC 6120, March 2011. | |||
| [RFC6282] Hui, J. and P. Thubert, "Compression Format for IPv6 | [RFC6282] Hui, J. and P. Thubert, "Compression Format for IPv6 | |||
| Datagrams over IEEE 802.15.4-Based Networks", RFC 6282, | Datagrams over IEEE 802.15.4-Based Networks", RFC 6282, | |||
| September 2011. | September 2011. | |||
| [RFC6335] Cotton, M., Eggert, L., Touch, J., Westerlund, M., and S. | [RFC6335] Cotton, M., Eggert, L., Touch, J., Westerlund, M., and S. | |||
| Cheshire, "Internet Assigned Numbers Authority (IANA) | Cheshire, "Internet Assigned Numbers Authority (IANA) | |||
| Procedures for the Management of the Service Name and | Procedures for the Management of the Service Name and | |||
| Transport Protocol Port Number Registry", BCP 165, | Transport Protocol Port Number Registry", BCP 165, RFC | |||
| RFC 6335, August 2011. | 6335, August 2011. | |||
| [RFC6655] McGrew, D. and D. Bailey, "AES-CCM Cipher Suites for | [RFC6655] McGrew, D. and D. Bailey, "AES-CCM Cipher Suites for | |||
| Transport Layer Security (TLS)", RFC 6655, July 2012. | Transport Layer Security (TLS)", RFC 6655, July 2012. | |||
| [RFC6936] Fairhurst, G. and M. Westerlund, "Applicability Statement | ||||
| for the Use of IPv6 UDP Datagrams with Zero Checksums", | ||||
| RFC 6936, April 2013. | ||||
| [W3CXMLSEC] | [W3CXMLSEC] | |||
| Wenning, R., "Report of the XML Security PAG", | Wenning, R., "Report of the XML Security PAG", October | |||
| October 2012, | 2012, <http://www.w3.org/2011/xmlsec-pag/pagreport.html>. | |||
| <http://www.w3.org/2011/xmlsec-pag/pagreport.html>. | ||||
| Appendix A. Examples | Appendix A. Examples | |||
| This section gives a number of short examples with message flows for | This section gives a number of short examples with message flows for | |||
| GET requests. These examples demonstrate the basic operation, the | GET requests. These examples demonstrate the basic operation, the | |||
| operation in the presence of retransmissions, and multicast. | operation in the presence of retransmissions, and multicast. | |||
| Figure 15 shows a basic GET request causing a piggy-backed response: | Figure 16 shows a basic GET request causing a piggy-backed response: | |||
| The client sends a Confirmable GET request for the resource | The client sends a Confirmable GET request for the resource coap:// | |||
| coap://server/temperature to the server with a Message ID of 0x7d34. | server/temperature to the server with a Message ID of 0x7d34. The | |||
| The request includes one Uri-Path Option (Delta 0 + 11 = 11, Length | request includes one Uri-Path Option (Delta 0 + 11 = 11, Length 11, | |||
| 11, Value "temperature"); the Token is left empty. This request is a | Value "temperature"); the Token is left empty. This request is a | |||
| total of 16 bytes long. A 2.05 (Content) response is returned in the | total of 16 bytes long. A 2.05 (Content) response is returned in the | |||
| Acknowledgement message that acknowledges the Confirmable request, | Acknowledgement message that acknowledges the Confirmable request, | |||
| echoing both the Message ID 0x7d34 and the empty Token value. The | echoing both the Message ID 0x7d34 and the empty Token value. The | |||
| response includes a Payload of "22.3 C" and is 11 bytes long. | response includes a Payload of "22.3 C" and is 11 bytes long. | |||
| Client Server | Client Server | |||
| | | | | | | |||
| | | | | | | |||
| +----->| Header: GET (T=CON, Code=1, MID=0x7d34) | +----->| Header: GET (T=CON, Code=0.01, MID=0x7d34) | |||
| | GET | Uri-Path: "temperature" | | GET | Uri-Path: "temperature" | |||
| | | | | | | |||
| | | | | | | |||
| |<-----+ Header: 2.05 Content (T=ACK, Code=69, MID=0x7d34) | |<-----+ Header: 2.05 Content (T=ACK, Code=2.05, MID=0x7d34) | |||
| | 2.05 | Payload: "22.3 C" | | 2.05 | Payload: "22.3 C" | |||
| | | | | | | |||
| 0 1 2 3 | 0 1 2 3 | |||
| 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 | 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 | |||
| +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | |||
| | 1 | 0 | 0 | GET=1 | MID=0x7d34 | | | 1 | 0 | 0 | GET=1 | MID=0x7d34 | | |||
| +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | |||
| | 11 | 11 | "temperature" (11 B) ... | | 11 | 11 | "temperature" (11 B) ... | |||
| +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | |||
| 0 1 2 3 | 0 1 2 3 | |||
| 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 | 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 | |||
| +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | |||
| | 1 | 2 | 0 | 2.05=69 | MID=0x7d34 | | | 1 | 2 | 0 | 2.05=69 | MID=0x7d34 | | |||
| +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | |||
| |1 1 1 1 1 1 1 1| "22.3 C" (6 B) ... | |1 1 1 1 1 1 1 1| "22.3 C" (6 B) ... | |||
| +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | |||
| Figure 15: Confirmable request; piggy-backed response | Figure 16: Confirmable request; piggy-backed response | |||
| Figure 16 shows a similar example, but with the inclusion of an non- | Figure 17 shows a similar example, but with the inclusion of an non- | |||
| empty Token (Value 0x20) in the request and the response, increasing | empty Token (Value 0x20) in the request and the response, increasing | |||
| the sizes to 17 and 12 bytes, respectively. | the sizes to 17 and 12 bytes, respectively. | |||
| Client Server | Client Server | |||
| | | | | | | |||
| | | | | | | |||
| +----->| Header: GET (T=CON, Code=1, MID=0x7d35) | +----->| Header: GET (T=CON, Code=0.01, MID=0x7d35) | |||
| | GET | Token: 0x20 | | GET | Token: 0x20 | |||
| | | Uri-Path: "temperature" | | | Uri-Path: "temperature" | |||
| | | | | | | |||
| | | | | | | |||
| |<-----+ Header: 2.05 Content (T=ACK, Code=69, MID=0x7d35) | |<-----+ Header: 2.05 Content (T=ACK, Code=2.05, MID=0x7d35) | |||
| | 2.05 | Token: 0x20 | | 2.05 | Token: 0x20 | |||
| | | Payload: "22.3 C" | | | Payload: "22.3 C" | |||
| | | | | | | |||
| 0 1 2 3 | 0 1 2 3 | |||
| 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 | 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 | |||
| +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | |||
| | 1 | 0 | 1 | GET=1 | MID=0x7d35 | | | 1 | 0 | 1 | GET=1 | MID=0x7d35 | | |||
| +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | |||
| | 0x20 | | | 0x20 | | |||
| skipping to change at page 96, line 38 ¶ | skipping to change at page 102, line 10 ¶ | |||
| 0 1 2 3 | 0 1 2 3 | |||
| 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 | 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 | |||
| +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | |||
| | 1 | 2 | 1 | 2.05=69 | MID=0x7d35 | | | 1 | 2 | 1 | 2.05=69 | MID=0x7d35 | | |||
| +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | |||
| | 0x20 | | | 0x20 | | |||
| +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | |||
| |1 1 1 1 1 1 1 1| "22.3 C" (6 B) ... | |1 1 1 1 1 1 1 1| "22.3 C" (6 B) ... | |||
| +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | |||
| Figure 16: Confirmable request; piggy-backed response | Figure 17: Confirmable request; piggy-backed response | |||
| In Figure 17, the Confirmable GET request is lost. After ACK_TIMEOUT | In Figure 18, the Confirmable GET request is lost. After ACK_TIMEOUT | |||
| seconds, the client retransmits the request, resulting in a piggy- | seconds, the client retransmits the request, resulting in a piggy- | |||
| backed response as in the previous example. | backed response as in the previous example. | |||
| Client Server | Client Server | |||
| | | | | | | |||
| | | | | | | |||
| +----X | Header: GET (T=CON, Code=1, MID=0x7d36) | +----X | Header: GET (T=CON, Code=0.01, MID=0x7d36) | |||
| | GET | Token: 0x31 | | GET | Token: 0x31 | |||
| | | Uri-Path: "temperature" | | | Uri-Path: "temperature" | |||
| TIMEOUT | | TIMEOUT | | |||
| | | | | | | |||
| +----->| Header: GET (T=CON, Code=1, MID=0x7d36) | +----->| Header: GET (T=CON, Code=0.01, MID=0x7d36) | |||
| | GET | Token: 0x31 | | GET | Token: 0x31 | |||
| | | Uri-Path: "temperature" | | | Uri-Path: "temperature" | |||
| | | | | | | |||
| | | | | | | |||
| |<-----+ Header: 2.05 Content (T=ACK, Code=69, MID=0x7d36) | |<-----+ Header: 2.05 Content (T=ACK, Code=2.05, MID=0x7d36) | |||
| | 2.05 | Token: 0x31 | | 2.05 | Token: 0x31 | |||
| | | Payload: "22.3 C" | | | Payload: "22.3 C" | |||
| | | | | | | |||
| Figure 17: Confirmable request (retransmitted); piggy-backed response | Figure 18: Confirmable request (retransmitted); piggy-backed response | |||
| In Figure 18, the first Acknowledgement message from the server to | In Figure 19, the first Acknowledgement message from the server to | |||
| the client is lost. After ACK_TIMEOUT seconds, the client | the client is lost. After ACK_TIMEOUT seconds, the client | |||
| retransmits the request. | retransmits the request. | |||
| Client Server | Client Server | |||
| | | | | | | |||
| | | | | | | |||
| +----->| Header: GET (T=CON, Code=1, MID=0x7d37) | +----->| Header: GET (T=CON, Code=0.01, MID=0x7d37) | |||
| | GET | Token: 0x42 | | GET | Token: 0x42 | |||
| | | Uri-Path: "temperature" | | | Uri-Path: "temperature" | |||
| | | | | | | |||
| | | | | | | |||
| | X----+ Header: 2.05 Content (T=ACK, Code=69, MID=0x7d37) | | X----+ Header: 2.05 Content (T=ACK, Code=2.05, MID=0x7d37) | |||
| | 2.05 | Token: 0x42 | | 2.05 | Token: 0x42 | |||
| | | Payload: "22.3 C" | | | Payload: "22.3 C" | |||
| TIMEOUT | | TIMEOUT | | |||
| | | | | | | |||
| +----->| Header: GET (T=CON, Code=1, MID=0x7d37) | +----->| Header: GET (T=CON, Code=0.01, MID=0x7d37) | |||
| | GET | Token: 0x42 | | GET | Token: 0x42 | |||
| | | Uri-Path: "temperature" | | | Uri-Path: "temperature" | |||
| | | | | | | |||
| | | | | | | |||
| |<-----+ Header: 2.05 Content (T=ACK, Code=69, MID=0x7d37) | |<-----+ Header: 2.05 Content (T=ACK, Code=2.05, MID=0x7d37) | |||
| | 2.05 | Token: 0x42 | | 2.05 | Token: 0x42 | |||
| | | Payload: "22.3 C" | | | Payload: "22.3 C" | |||
| | | | | | | |||
| Figure 18: Confirmable request; piggy-backed response (retransmitted) | Figure 19: Confirmable request; piggy-backed response (retransmitted) | |||
| In Figure 19, the server acknowledges the Confirmable request and | ||||
| In Figure 20, the server acknowledges the Confirmable request and | ||||
| sends a 2.05 (Content) response separately in a Confirmable message. | sends a 2.05 (Content) response separately in a Confirmable message. | |||
| Note that the Acknowledgement message and the Confirmable response do | Note that the Acknowledgement message and the Confirmable response do | |||
| not necessarily arrive in the same order as they were sent. The | not necessarily arrive in the same order as they were sent. The | |||
| client acknowledges the Confirmable response. | client acknowledges the Confirmable response. | |||
| Client Server | Client Server | |||
| | | | | | | |||
| | | | | | | |||
| +----->| Header: GET (T=CON, Code=1, MID=0x7d38) | +----->| Header: GET (T=CON, Code=0.01, MID=0x7d38) | |||
| | GET | Token: 0x53 | | GET | Token: 0x53 | |||
| | | Uri-Path: "temperature" | | | Uri-Path: "temperature" | |||
| | | | | | | |||
| | | | | | | |||
| |<- - -+ Header: (T=ACK, Code=0, MID=0x7d38) | |<- - -+ Header: (T=ACK, Code=0.00, MID=0x7d38) | |||
| | | | | | | |||
| | | | | | | |||
| |<-----+ Header: 2.05 Content (T=CON, Code=69, MID=0xad7b) | |<-----+ Header: 2.05 Content (T=CON, Code=2.05, MID=0xad7b) | |||
| | 2.05 | Token: 0x53 | | 2.05 | Token: 0x53 | |||
| | | Payload: "22.3 C" | | | Payload: "22.3 C" | |||
| | | | | | | |||
| | | | | | | |||
| +- - ->| Header: (T=ACK, Code=0, MID=0xad7b) | +- - ->| Header: (T=ACK, Code=0.00, MID=0xad7b) | |||
| | | | | | | |||
| Figure 19: Confirmable request; separate response | Figure 20: Confirmable request; separate response | |||
| Figure 20 shows an example where the client loses its state (e.g., | Figure 21 shows an example where the client loses its state (e.g., | |||
| crashes and is rebooted) right after sending a Confirmable request, | crashes and is rebooted) right after sending a Confirmable request, | |||
| so the separate response arriving some time later comes unexpected. | so the separate response arriving some time later comes unexpected. | |||
| In this case, the client rejects the Confirmable response with a | In this case, the client rejects the Confirmable response with a | |||
| Reset message. Note that the unexpected ACK is silently ignored. | Reset message. Note that the unexpected ACK is silently ignored. | |||
| Client Server | Client Server | |||
| | | | | | | |||
| | | | | | | |||
| +----->| Header: GET (T=CON, Code=1, MID=0x7d39) | +----->| Header: GET (T=CON, Code=0.01, MID=0x7d39) | |||
| | GET | Token: 0x64 | | GET | Token: 0x64 | |||
| | | Uri-Path: "temperature" | | | Uri-Path: "temperature" | |||
| CRASH | | CRASH | | |||
| | | | | | | |||
| |<- - -+ Header: (T=ACK, Code=0, MID=0x7d39) | |<- - -+ Header: (T=ACK, Code=0.00, MID=0x7d39) | |||
| | | | | | | |||
| | | | | | | |||
| |<-----+ Header: 2.05 Content (T=CON, Code=69, MID=0xad7c) | |<-----+ Header: 2.05 Content (T=CON, Code=2.05, MID=0xad7c) | |||
| | 2.05 | Token: 0x64 | | 2.05 | Token: 0x64 | |||
| | | Payload: "22.3 C" | | | Payload: "22.3 C" | |||
| | | | | | | |||
| | | | | | | |||
| +- - ->| Header: (T=RST, Code=0, MID=0xad7c) | +- - ->| Header: (T=RST, Code=0.00, MID=0xad7c) | |||
| | | | | | | |||
| Figure 20: Confirmable request; separate response (unexpected) | Figure 21: Confirmable request; separate response (unexpected) | |||
| Figure 21 shows a basic GET request where the request and the | Figure 22 shows a basic GET request where the request and the | |||
| response are Non-confirmable, so both may be lost without notice. | response are Non-confirmable, so both may be lost without notice. | |||
| Client Server | Client Server | |||
| | | | | | | |||
| | | | | | | |||
| +----->| Header: GET (T=NON, Code=1, MID=0x7d40) | +----->| Header: GET (T=NON, Code=0.01, MID=0x7d40) | |||
| | GET | Token: 0x75 | | GET | Token: 0x75 | |||
| | | Uri-Path: "temperature" | | | Uri-Path: "temperature" | |||
| | | | | | | |||
| | | | | | | |||
| |<-----+ Header: 2.05 Content (T=NON, Code=69, MID=0xad7d) | |<-----+ Header: 2.05 Content (T=NON, Code=2.05, MID=0xad7d) | |||
| | 2.05 | Token: 0x75 | | 2.05 | Token: 0x75 | |||
| | | Payload: "22.3 C" | | | Payload: "22.3 C" | |||
| | | | | | | |||
| Figure 21: Non-confirmable request; Non-confirmable response | Figure 22: Non-confirmable request; Non-confirmable response | |||
| In Figure 22, the client sends a Non-confirmable GET request to a | In Figure 23, the client sends a Non-confirmable GET request to a | |||
| multicast address: all nodes in link-local scope. There are 3 | multicast address: all nodes in link-local scope. There are 3 | |||
| servers on the link: A, B and C. Servers A and B have a matching | servers on the link: A, B and C. Servers A and B have a matching | |||
| resource, therefore they send back a Non-confirmable 2.05 (Content) | resource, therefore they send back a Non-confirmable 2.05 (Content) | |||
| response. The response sent by B is lost. C does not have matching | response. The response sent by B is lost. C does not have matching | |||
| response, therefore it sends a Non-confirmable 4.04 (Not Found) | response, therefore it sends a Non-confirmable 4.04 (Not Found) | |||
| response. | response. | |||
| Client ff02::1 A B C | Client ff02::1 A B C | |||
| | | | | | | | | | | | | |||
| | | | | | | | | | | | | |||
| +------>| | | | Header: GET (T=NON, Code=1, MID=0x7d41) | +------>| | | | Header: GET (T=NON, Code=0.01, MID=0x7d41) | |||
| | GET | | | | Token: 0x86 | | GET | | | | Token: 0x86 | |||
| | | | | Uri-Path: "temperature" | | | | | Uri-Path: "temperature" | |||
| | | | | | | | | | | |||
| | | | | | | | | | | |||
| |<------------+ | | Header: 2.05 (T=NON, Code=69, MID=0x60b1) | |<------------+ | | Header: 2.05 (T=NON, Code=2.05, MID=0x60b1) | |||
| | 2.05 | | | Token: 0x86 | | 2.05 | | | Token: 0x86 | |||
| | | | | Payload: "22.3 C" | | | | | Payload: "22.3 C" | |||
| | | | | | | | | | | |||
| | | | | | | | | | | |||
| | X------------+ | Header: 2.05 (T=NON, Code=69, MID=0x01a0) | | X------------+ | Header: 2.05 (T=NON, Code=2.05, MID=0x01a0) | |||
| | 2.05 | | | Token: 0x86 | | 2.05 | | | Token: 0x86 | |||
| | | | | Payload: "20.9 C" | | | | | Payload: "20.9 C" | |||
| | | | | | | | | | | |||
| | | | | | | | | | | |||
| |<------------------+ Header: 4.04 (T=NON, Code=132, MID=0x952a) | |<------------------+ Header: 4.04 (T=NON, Code=4.04, MID=0x952a) | |||
| | 4.04 | | | Token: 0x86 | | 4.04 | | | Token: 0x86 | |||
| | | | | | | | | | | |||
| Figure 22: Non-confirmable request (multicast); Non-confirmable | Figure 23: Non-confirmable request (multicast); Non-confirmable | |||
| response | response | |||
| Appendix B. URI Examples | Appendix B. URI Examples | |||
| The following examples demonstrate different sets of Uri options, and | The following examples demonstrate different sets of Uri options, and | |||
| the result after constructing an URI from them. In addition to the | the result after constructing an URI from them. In addition to the | |||
| options, Section 6.5 refers to the destination IP address and port, | options, Section 6.5 refers to the destination IP address and port, | |||
| but not all paths of the algorithm cause the destination IP address | but not all paths of the algorithm cause the destination IP address | |||
| and port to be included in the URI. | and port to be included in the URI. | |||
| skipping to change at page 101, line 32 ¶ | skipping to change at page 106, line 32 ¶ | |||
| Destination IP Address = [2001:db8::2:1] | Destination IP Address = [2001:db8::2:1] | |||
| Destination UDP Port = 5683 | Destination UDP Port = 5683 | |||
| Uri-Host = "xn--18j4d.example" | Uri-Host = "xn--18j4d.example" | |||
| Uri-Path = the string composed of the Unicode characters U+3053 | Uri-Path = the string composed of the Unicode characters U+3053 | |||
| U+3093 U+306b U+3061 U+306f, usually represented in UTF-8 as | U+3093 U+306b U+3061 U+306f, usually represented in UTF-8 as | |||
| E38193E38293E381ABE381A1E381AF hexadecimal | E38193E38293E381ABE381A1E381AF hexadecimal | |||
| Output: | Output: | |||
| coap:// | coap://xn--18j4d.example/ | |||
| xn--18j4d.example/%E3%81%93%E3%82%93%E3%81%AB%E3%81%A1%E3%81%AF | %E3%81%93%E3%82%93%E3%81%AB%E3%81%A1%E3%81%AF | |||
| (The line break has been inserted for readability; it is not | (The line break has been inserted for readability; it is not | |||
| part of the URI.) | part of the URI.) | |||
| o Input: | o Input: | |||
| Destination IP Address = 198.51.100.1 | Destination IP Address = 198.51.100.1 | |||
| Destination UDP Port = 61616 | Destination UDP Port = 61616 | |||
| Uri-Path = "" | Uri-Path = "" | |||
| Uri-Path = "/" | Uri-Path = "/" | |||
| skipping to change at page 102, line 9 ¶ | skipping to change at page 107, line 9 ¶ | |||
| Uri-Query = "?&" | Uri-Query = "?&" | |||
| Output: | Output: | |||
| coap://198.51.100.1:61616//%2F//?%2F%2F&?%26 | coap://198.51.100.1:61616//%2F//?%2F%2F&?%26 | |||
| Appendix C. Changelog | Appendix C. Changelog | |||
| (To be removed by RFC editor before publication.) | (To be removed by RFC editor before publication.) | |||
| Changes from ietf-17 to ietf-18: Address comments from the IESG | ||||
| reviews. | ||||
| o Accept is now critical. | ||||
| o Add Size1 option for 4.13 responses. | ||||
| Changes from ietf-15 to ietf-16: Address comments from the IESG | ||||
| reviews. These should not impact interoperability. | ||||
| o Clarify that once there has been an empty ACK, all further ACKs to | ||||
| the same message also must be empty (#301). | ||||
| o Define Cache-key properly (#302). | ||||
| o Clarify that ACKs don't get retransmitted, the CONs do (#303). | ||||
| o Clarify: NON is like separate for CON (#304). | ||||
| o Don't use decimal response codes, keep the 3+5 structure | ||||
| throughout (#305). | ||||
| o RFC 2119 usage in 4.5 (#306) and 8.2 (#307). | ||||
| o Ensure all protocol reactions to reserved or prohibited values are | ||||
| defined (#308). | ||||
| o URI matching rules may be scheme specific (#309). | ||||
| o Don't dally beyond MAX_TRANSMIT_SPAN during retransmission (#310). | ||||
| o More about selecting a token length for anti-spoofing (#311). | ||||
| o Discuss spoofing ACKs (#312). | ||||
| o Qualify partial discard strategy implementation note as UDP only | ||||
| (#313). | ||||
| o Explicitly point out that UDP and DTLS don't mix (#314). | ||||
| o Point out security consideration re URIs and access control | ||||
| (#315). | ||||
| o Point to RFC5280 section 6 (#316). | ||||
| o Add a paragraph about cert status checking (#317). | ||||
| o RSA is out, ECDHE is in for cert-with-PSK, too (#318). | ||||
| o Point out that requests and responses don't always come in pairs | ||||
| (#319). | ||||
| o Clarify when there is a need for Unicode normalization (#320). | ||||
| o Point out that Uri-Host doesn't handle user-part (#321). | ||||
| o Clarify the use of non-FQDN Authority Names in certificates. | ||||
| o Numerous editorial improvements and clarifications. | ||||
| Changes from ietf-14 to ietf-15: Address comments from IETF last- | Changes from ietf-14 to ietf-15: Address comments from IETF last- | |||
| call, mostly implementation notes and editorial improvements. These | call, mostly implementation notes and editorial improvements. These | |||
| should not impact interoperability. | should not impact interoperability. | |||
| o Clarify bytes/characters and UTF-8/ASCII in "Decomposing URIs into | o Clarify bytes/characters and UTF-8/ASCII in "Decomposing URIs into | |||
| Options" (#282). | Options" (#282). | |||
| o Make reference to ECC/CCM DTLS ciphersuite normative (#286). | o Make reference to ECC/CCM DTLS ciphersuite normative (#286). | |||
| o Add a quick warning that bytewise scanning for a payload marker is | o Add a quick warning that bytewise scanning for a payload marker is | |||
| skipping to change at page 104, line 46 ¶ | skipping to change at page 111, line 5 ¶ | |||
| o Fixed misleading language that was introduced in 5.10.2 in coap-07 | o Fixed misleading language that was introduced in 5.10.2 in coap-07 | |||
| re Uri-Host and Uri-Port (#208). | re Uri-Host and Uri-Port (#208). | |||
| o Segments and arguments can have a length of zero characters | o Segments and arguments can have a length of zero characters | |||
| (#213). | (#213). | |||
| o The Location-* options describe together describe one location. | o The Location-* options describe together describe one location. | |||
| The location is a relative URI, not an "absolute path URI" (#218). | The location is a relative URI, not an "absolute path URI" (#218). | |||
| o The value of the Location-Path Option must not be '.' or '..' | o The value of the Location-Path Option must not be '.' or '..' | |||
| (#218). | (#218). | |||
| o Added a sentence on constructing URIs from Location-* options | o Added a sentence on constructing URIs from Location-* options | |||
| (#231). | (#231). | |||
| o Reserved option numbers for future Location-* options (#230). | o Reserved option numbers for future Location-* options (#230). | |||
| o Fixed response codes with payload inconsistency (#233). | o Fixed response codes with payload inconsistency (#233). | |||
| o Added advice on default values for critical options (#207). | o Added advice on default values for critical options (#207). | |||
| skipping to change at page 108, line 51 ¶ | skipping to change at page 114, line 51 ¶ | |||
| o Added text on critical options in cached states (#83). | o Added text on critical options in cached states (#83). | |||
| o HTTP mapping sections improved (#88). | o HTTP mapping sections improved (#88). | |||
| o Added text on reverse proxies (#72). | o Added text on reverse proxies (#72). | |||
| o Some security text on multicast added (#54). | o Some security text on multicast added (#54). | |||
| o Trust model text added to introduction (#58, #60). | o Trust model text added to introduction (#58, #60). | |||
| o AES-CCM vs. AES-CCB text added (#55). | o AES-CCM vs. AES-CCB text added (#55). | |||
| o Text added about device capabilities (#59). | o Text added about device capabilities (#59). | |||
| o DTLS section improvements (#87). | o DTLS section improvements (#87). | |||
| o Caching semantics aligned with RFC2616 (#78). | o Caching semantics aligned with RFC2616 (#78). | |||
| o Uri-Path Option split into multiple path segments. | o Uri-Path Option split into multiple path segments. | |||
| o MAX_RETRANSMIT changed to 4 to adjust for RESPONSE_TIME = 2. | o MAX_RETRANSMIT changed to 4 to adjust for RESPONSE_TIME = 2. | |||
| End of changes. 315 change blocks. | ||||
| 872 lines changed or deleted | 1226 lines changed or added | |||
This html diff was produced by rfcdiff 1.48. The latest version is available from http://tools.ietf.org/tools/rfcdiff/ | ||||