| < draft-ietf-core-coap-17.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: November 27, 2013 C. Bormann | Expires: December 30, 2013 C. Bormann | |||
| Universitaet Bremen TZI | Universitaet Bremen TZI | |||
| May 26, 2013 | June 28, 2013 | |||
| Constrained Application Protocol (CoAP) | Constrained Application Protocol (CoAP) | |||
| draft-ietf-core-coap-17 | 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 is designed to easily interface with HTTP | Internet media types. CoAP is designed to easily interface with HTTP | |||
| for integration with the Web while meeting specialized requirements | for integration with the Web while meeting specialized requirements | |||
| such 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 November 27, 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 | |||
| skipping to change at page 2, line 26 ¶ | skipping to change at page 2, line 29 ¶ | |||
| 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 . . . . . . . . . . . . . . . . . 12 | 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 . . . . . . . . . . . . . . . . . . . . . . 17 | 3.1. Option Format . . . . . . . . . . . . . . . . . . . . . . 17 | |||
| 3.2. Option Value Formats . . . . . . . . . . . . . . . . . . 19 | 3.2. Option Value Formats . . . . . . . . . . . . . . . . . . 19 | |||
| 4. Message Transmission . . . . . . . . . . . . . . . . . . . . 20 | 4. Message Transmission . . . . . . . . . . . . . . . . . . . . 20 | |||
| 4.1. Messages and Endpoints . . . . . . . . . . . . . . . . . 20 | 4.1. Messages and Endpoints . . . . . . . . . . . . . . . . . 20 | |||
| 4.2. Messages Transmitted Reliably . . . . . . . . . . . . . . 21 | 4.2. Messages Transmitted Reliably . . . . . . . . . . . . . . 20 | |||
| 4.3. Messages Transmitted Without Reliability . . . . . . . . 22 | 4.3. Messages Transmitted Without Reliability . . . . . . . . 22 | |||
| 4.4. Message Correlation . . . . . . . . . . . . . . . . . . . 23 | 4.4. Message Correlation . . . . . . . . . . . . . . . . . . . 23 | |||
| 4.5. Message Deduplication . . . . . . . . . . . . . . . . . . 24 | 4.5. Message Deduplication . . . . . . . . . . . . . . . . . . 24 | |||
| 4.6. Message Size . . . . . . . . . . . . . . . . . . . . . . 25 | 4.6. Message Size . . . . . . . . . . . . . . . . . . . . . . 24 | |||
| 4.7. Congestion Control . . . . . . . . . . . . . . . . . . . 26 | 4.7. Congestion Control . . . . . . . . . . . . . . . . . . . 25 | |||
| 4.8. Transmission Parameters . . . . . . . . . . . . . . . . . 27 | 4.8. Transmission Parameters . . . . . . . . . . . . . . . . . 26 | |||
| 4.8.1. Changing The Parameters . . . . . . . . . . . . . . . 27 | 4.8.1. Changing The Parameters . . . . . . . . . . . . . . . 27 | |||
| 4.8.2. Time Values derived from Transmission Parameters . . 28 | 4.8.2. Time Values derived from Transmission Parameters . . 28 | |||
| 5. Request/Response Semantics . . . . . . . . . . . . . . . . . 30 | 5. Request/Response Semantics . . . . . . . . . . . . . . . . . 30 | |||
| 5.1. Requests . . . . . . . . . . . . . . . . . . . . . . . . 30 | 5.1. Requests . . . . . . . . . . . . . . . . . . . . . . . . 30 | |||
| 5.2. Responses . . . . . . . . . . . . . . . . . . . . . . . . 31 | 5.2. Responses . . . . . . . . . . . . . . . . . . . . . . . . 30 | |||
| 5.2.1. Piggy-backed . . . . . . . . . . . . . . . . . . . . 32 | 5.2.1. Piggy-backed . . . . . . . . . . . . . . . . . . . . 32 | |||
| 5.2.2. Separate . . . . . . . . . . . . . . . . . . . . . . 32 | 5.2.2. Separate . . . . . . . . . . . . . . . . . . . . . . 32 | |||
| 5.2.3. Non-confirmable . . . . . . . . . . . . . . . . . . . 34 | 5.2.3. Non-confirmable . . . . . . . . . . . . . . . . . . . 33 | |||
| 5.3. Request/Response Matching . . . . . . . . . . . . . . . . 34 | 5.3. Request/Response Matching . . . . . . . . . . . . . . . . 33 | |||
| 5.3.1. Token . . . . . . . . . . . . . . . . . . . . . . . . 34 | 5.3.1. Token . . . . . . . . . . . . . . . . . . . . . . . . 34 | |||
| 5.3.2. Request/Response Matching Rules . . . . . . . . . . . 35 | 5.3.2. Request/Response Matching Rules . . . . . . . . . . . 35 | |||
| 5.4. Options . . . . . . . . . . . . . . . . . . . . . . . . . 35 | 5.4. Options . . . . . . . . . . . . . . . . . . . . . . . . . 35 | |||
| 5.4.1. Critical/Elective . . . . . . . . . . . . . . . . . . 36 | 5.4.1. Critical/Elective . . . . . . . . . . . . . . . . . . 36 | |||
| 5.4.2. Proxy Unsafe/Safe-to-Forward and NoCacheKey . . . . . 37 | 5.4.2. Proxy Unsafe/Safe-to-Forward and NoCacheKey . . . . . 37 | |||
| 5.4.3. Length . . . . . . . . . . . . . . . . . . . . . . . 38 | 5.4.3. Length . . . . . . . . . . . . . . . . . . . . . . . 38 | |||
| 5.4.4. Default Values . . . . . . . . . . . . . . . . . . . 38 | 5.4.4. Default Values . . . . . . . . . . . . . . . . . . . 38 | |||
| 5.4.5. Repeatable Options . . . . . . . . . . . . . . . . . 38 | 5.4.5. Repeatable Options . . . . . . . . . . . . . . . . . 38 | |||
| 5.4.6. Option Numbers . . . . . . . . . . . . . . . . . . . 38 | 5.4.6. Option Numbers . . . . . . . . . . . . . . . . . . . 38 | |||
| 5.5. Payloads and Representations . . . . . . . . . . . . . . 39 | 5.5. Payloads and Representations . . . . . . . . . . . . . . 39 | |||
| 5.5.1. Representation . . . . . . . . . . . . . . . . . . . 39 | 5.5.1. Representation . . . . . . . . . . . . . . . . . . . 39 | |||
| 5.5.2. Diagnostic Payload . . . . . . . . . . . . . . . . . 40 | 5.5.2. Diagnostic Payload . . . . . . . . . . . . . . . . . 40 | |||
| 5.5.3. Selected Representation . . . . . . . . . . . . . . . 40 | 5.5.3. Selected Representation . . . . . . . . . . . . . . . 40 | |||
| 5.5.4. Content Negotiation . . . . . . . . . . . . . . . . . 41 | 5.5.4. Content Negotiation . . . . . . . . . . . . . . . . . 40 | |||
| 5.6. Caching . . . . . . . . . . . . . . . . . . . . . . . . . 41 | 5.6. Caching . . . . . . . . . . . . . . . . . . . . . . . . . 41 | |||
| 5.6.1. Freshness Model . . . . . . . . . . . . . . . . . . . 42 | 5.6.1. Freshness Model . . . . . . . . . . . . . . . . . . . 42 | |||
| 5.6.2. Validation Model . . . . . . . . . . . . . . . . . . 42 | 5.6.2. Validation Model . . . . . . . . . . . . . . . . . . 42 | |||
| 5.7. Proxying . . . . . . . . . . . . . . . . . . . . . . . . 43 | 5.7. Proxying . . . . . . . . . . . . . . . . . . . . . . . . 43 | |||
| 5.7.1. Proxy Operation . . . . . . . . . . . . . . . . . . . 43 | 5.7.1. Proxy Operation . . . . . . . . . . . . . . . . . . . 43 | |||
| 5.7.2. Forward-Proxies . . . . . . . . . . . . . . . . . . . 45 | 5.7.2. Forward-Proxies . . . . . . . . . . . . . . . . . . . 45 | |||
| 5.7.3. Reverse-Proxies . . . . . . . . . . . . . . . . . . . 45 | 5.7.3. Reverse-Proxies . . . . . . . . . . . . . . . . . . . 45 | |||
| 5.8. Method Definitions . . . . . . . . . . . . . . . . . . . 46 | 5.8. Method Definitions . . . . . . . . . . . . . . . . . . . 46 | |||
| 5.8.1. GET . . . . . . . . . . . . . . . . . . . . . . . . . 46 | 5.8.1. GET . . . . . . . . . . . . . . . . . . . . . . . . . 46 | |||
| 5.8.2. POST . . . . . . . . . . . . . . . . . . . . . . . . 46 | 5.8.2. POST . . . . . . . . . . . . . . . . . . . . . . . . 46 | |||
| 5.8.3. PUT . . . . . . . . . . . . . . . . . . . . . . . . . 47 | 5.8.3. PUT . . . . . . . . . . . . . . . . . . . . . . . . . 46 | |||
| 5.8.4. DELETE . . . . . . . . . . . . . . . . . . . . . . . 47 | 5.8.4. DELETE . . . . . . . . . . . . . . . . . . . . . . . 47 | |||
| 5.9. Response Code Definitions . . . . . . . . . . . . . . . . 47 | 5.9. Response Code Definitions . . . . . . . . . . . . . . . . 47 | |||
| 5.9.1. Success 2.xx . . . . . . . . . . . . . . . . . . . . 47 | 5.9.1. Success 2.xx . . . . . . . . . . . . . . . . . . . . 47 | |||
| 5.9.2. Client Error 4.xx . . . . . . . . . . . . . . . . . . 49 | 5.9.2. Client Error 4.xx . . . . . . . . . . . . . . . . . . 49 | |||
| 5.9.3. Server Error 5.xx . . . . . . . . . . . . . . . . . . 50 | 5.9.3. Server Error 5.xx . . . . . . . . . . . . . . . . . . 50 | |||
| 5.10. Option Definitions . . . . . . . . . . . . . . . . . . . 51 | 5.10. Option Definitions . . . . . . . . . . . . . . . . . . . 51 | |||
| 5.10.1. Uri-Host, Uri-Port, Uri-Path and Uri-Query . . . . . 52 | 5.10.1. Uri-Host, Uri-Port, Uri-Path and Uri-Query . . . . . 52 | |||
| 5.10.2. Proxy-Uri and Proxy-Scheme . . . . . . . . . . . . . 53 | 5.10.2. Proxy-Uri and Proxy-Scheme . . . . . . . . . . . . . 53 | |||
| 5.10.3. Content-Format . . . . . . . . . . . . . . . . . . . 54 | 5.10.3. Content-Format . . . . . . . . . . . . . . . . . . . 53 | |||
| 5.10.4. Accept . . . . . . . . . . . . . . . . . . . . . . . 54 | 5.10.4. Accept . . . . . . . . . . . . . . . . . . . . . . . 54 | |||
| 5.10.5. Max-Age . . . . . . . . . . . . . . . . . . . . . . . 54 | 5.10.5. Max-Age . . . . . . . . . . . . . . . . . . . . . . 54 | |||
| 5.10.6. ETag . . . . . . . . . . . . . . . . . . . . . . . . 55 | 5.10.6. ETag . . . . . . . . . . . . . . . . . . . . . . . . 54 | |||
| 5.10.7. Location-Path and Location-Query . . . . . . . . . . 56 | 5.10.7. Location-Path and Location-Query . . . . . . . . . . 55 | |||
| 5.10.8. Conditional Request Options . . . . . . . . . . . . . 56 | 5.10.8. Conditional Request Options . . . . . . . . . . . . 56 | |||
| 6. CoAP URIs . . . . . . . . . . . . . . . . . . . . . . . . . . 58 | 5.10.9. Size1 Option . . . . . . . . . . . . . . . . . . . . 57 | |||
| 6. CoAP URIs . . . . . . . . . . . . . . . . . . . . . . . . . . 57 | ||||
| 6.1. coap URI Scheme . . . . . . . . . . . . . . . . . . . . . 58 | 6.1. coap URI Scheme . . . . . . . . . . . . . . . . . . . . . 58 | |||
| 6.2. coaps URI Scheme . . . . . . . . . . . . . . . . . . . . 59 | 6.2. coaps URI Scheme . . . . . . . . . . . . . . . . . . . . 59 | |||
| 6.3. Normalization and Comparison Rules . . . . . . . . . . . 59 | 6.3. Normalization and Comparison Rules . . . . . . . . . . . 59 | |||
| 6.4. Decomposing URIs into Options . . . . . . . . . . . . . . 60 | 6.4. Decomposing URIs into Options . . . . . . . . . . . . . . 60 | |||
| 6.5. Composing URIs from Options . . . . . . . . . . . . . . . 61 | 6.5. Composing URIs from Options . . . . . . . . . . . . . . . 61 | |||
| 7. Discovery . . . . . . . . . . . . . . . . . . . . . . . . . . 62 | 7. Discovery . . . . . . . . . . . . . . . . . . . . . . . . . . 62 | |||
| 7.1. Service Discovery . . . . . . . . . . . . . . . . . . . . 62 | 7.1. Service Discovery . . . . . . . . . . . . . . . . . . . . 62 | |||
| 7.2. Resource Discovery . . . . . . . . . . . . . . . . . . . 63 | 7.2. Resource Discovery . . . . . . . . . . . . . . . . . . . 63 | |||
| 7.2.1. 'ct' Attribute . . . . . . . . . . . . . . . . . . . 63 | 7.2.1. 'ct' Attribute . . . . . . . . . . . . . . . . . . . 63 | |||
| 8. Multicast CoAP . . . . . . . . . . . . . . . . . . . . . . . 64 | 8. Multicast CoAP . . . . . . . . . . . . . . . . . . . . . . . 64 | |||
| 8.1. Messaging Layer . . . . . . . . . . . . . . . . . . . . . 64 | 8.1. Messaging Layer . . . . . . . . . . . . . . . . . . . . . 64 | |||
| 8.2. Request/Response Layer . . . . . . . . . . . . . . . . . 64 | 8.2. Request/Response Layer . . . . . . . . . . . . . . . . . 65 | |||
| 8.2.1. Caching . . . . . . . . . . . . . . . . . . . . . . . 65 | 8.2.1. Caching . . . . . . . . . . . . . . . . . . . . . . . 66 | |||
| 8.2.2. Proxying . . . . . . . . . . . . . . . . . . . . . . 66 | 8.2.2. Proxying . . . . . . . . . . . . . . . . . . . . . . 66 | |||
| 9. Securing CoAP . . . . . . . . . . . . . . . . . . . . . . . . 66 | 9. Securing CoAP . . . . . . . . . . . . . . . . . . . . . . . . 66 | |||
| 9.1. DTLS-secured CoAP . . . . . . . . . . . . . . . . . . . . 68 | 9.1. DTLS-secured CoAP . . . . . . . . . . . . . . . . . . . . 68 | |||
| 9.1.1. Messaging Layer . . . . . . . . . . . . . . . . . . . 69 | 9.1.1. Messaging Layer . . . . . . . . . . . . . . . . . . . 69 | |||
| 9.1.2. Request/Response Layer . . . . . . . . . . . . . . . 69 | 9.1.2. Request/Response Layer . . . . . . . . . . . . . . . 69 | |||
| 9.1.3. Endpoint Identity . . . . . . . . . . . . . . . . . . 70 | 9.1.3. Endpoint Identity . . . . . . . . . . . . . . . . . . 70 | |||
| 10. Cross-Protocol Proxying between CoAP and HTTP . . . . . . . . 73 | 10. Cross-Protocol Proxying between CoAP and HTTP . . . . . . . . 73 | |||
| 10.1. CoAP-HTTP Proxying . . . . . . . . . . . . . . . . . . . 74 | 10.1. CoAP-HTTP Proxying . . . . . . . . . . . . . . . . . . . 74 | |||
| 10.1.1. GET . . . . . . . . . . . . . . . . . . . . . . . . . 74 | 10.1.1. GET . . . . . . . . . . . . . . . . . . . . . . . . 74 | |||
| 10.1.2. PUT . . . . . . . . . . . . . . . . . . . . . . . . . 75 | 10.1.2. PUT . . . . . . . . . . . . . . . . . . . . . . . . 75 | |||
| 10.1.3. DELETE . . . . . . . . . . . . . . . . . . . . . . . 75 | 10.1.3. DELETE . . . . . . . . . . . . . . . . . . . . . . . 75 | |||
| 10.1.4. POST . . . . . . . . . . . . . . . . . . . . . . . . 75 | 10.1.4. POST . . . . . . . . . . . . . . . . . . . . . . . . 75 | |||
| 10.2. HTTP-CoAP Proxying . . . . . . . . . . . . . . . . . . . 76 | 10.2. HTTP-CoAP Proxying . . . . . . . . . . . . . . . . . . . 76 | |||
| 10.2.1. OPTIONS and TRACE . . . . . . . . . . . . . . . . . . 76 | 10.2.1. OPTIONS and TRACE . . . . . . . . . . . . . . . . . 76 | |||
| 10.2.2. GET . . . . . . . . . . . . . . . . . . . . . . . . . 76 | 10.2.2. GET . . . . . . . . . . . . . . . . . . . . . . . . 76 | |||
| 10.2.3. HEAD . . . . . . . . . . . . . . . . . . . . . . . . 77 | 10.2.3. HEAD . . . . . . . . . . . . . . . . . . . . . . . . 77 | |||
| 10.2.4. POST . . . . . . . . . . . . . . . . . . . . . . . . 77 | 10.2.4. POST . . . . . . . . . . . . . . . . . . . . . . . . 77 | |||
| 10.2.5. PUT . . . . . . . . . . . . . . . . . . . . . . . . . 78 | 10.2.5. PUT . . . . . . . . . . . . . . . . . . . . . . . . 78 | |||
| 10.2.6. DELETE . . . . . . . . . . . . . . . . . . . . . . . 78 | 10.2.6. DELETE . . . . . . . . . . . . . . . . . . . . . . . 78 | |||
| 10.2.7. CONNECT . . . . . . . . . . . . . . . . . . . . . . . 78 | 10.2.7. CONNECT . . . . . . . . . . . . . . . . . . . . . . 78 | |||
| 11. Security Considerations . . . . . . . . . . . . . . . . . . . 78 | 11. Security Considerations . . . . . . . . . . . . . . . . . . . 78 | |||
| 11.1. Protocol Parsing, Processing URIs . . . . . . . . . . . . 78 | 11.1. Protocol Parsing, Processing URIs . . . . . . . . . . . 78 | |||
| 11.2. Proxying and Caching . . . . . . . . . . . . . . . . . . 79 | 11.2. Proxying and Caching . . . . . . . . . . . . . . . . . . 79 | |||
| 11.3. Risk of amplification . . . . . . . . . . . . . . . . . . 80 | 11.3. Risk of amplification . . . . . . . . . . . . . . . . . 80 | |||
| 11.4. IP Address Spoofing Attacks . . . . . . . . . . . . . . . 81 | 11.4. IP Address Spoofing Attacks . . . . . . . . . . . . . . 81 | |||
| 11.5. Cross-Protocol Attacks . . . . . . . . . . . . . . . . . 82 | 11.5. Cross-Protocol Attacks . . . . . . . . . . . . . . . . . 82 | |||
| 11.6. Constrained node considerations . . . . . . . . . . . . . 84 | 11.6. Constrained node considerations . . . . . . . . . . . . 84 | |||
| 12. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 84 | 12. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 84 | |||
| 12.1. CoAP Code Registries . . . . . . . . . . . . . . . . . . 84 | 12.1. CoAP Code Registries . . . . . . . . . . . . . . . . . . 84 | |||
| 12.1.1. Method Codes . . . . . . . . . . . . . . . . . . . . 85 | 12.1.1. Method Codes . . . . . . . . . . . . . . . . . . . . 85 | |||
| 12.1.2. Response Codes . . . . . . . . . . . . . . . . . . . 86 | 12.1.2. Response Codes . . . . . . . . . . . . . . . . . . . 85 | |||
| 12.2. Option Number Registry . . . . . . . . . . . . . . . . . 87 | 12.2. Option Number Registry . . . . . . . . . . . . . . . . . 87 | |||
| 12.3. Content-Format Registry . . . . . . . . . . . . . . . . . 89 | 12.3. Content-Format Registry . . . . . . . . . . . . . . . . 89 | |||
| 12.4. URI Scheme Registration . . . . . . . . . . . . . . . . . 90 | 12.4. URI Scheme Registration . . . . . . . . . . . . . . . . 90 | |||
| 12.5. Secure URI Scheme Registration . . . . . . . . . . . . . 91 | 12.5. Secure URI Scheme Registration . . . . . . . . . . . . . 91 | |||
| 12.6. Service Name and Port Number Registration . . . . . . . . 92 | 12.6. Service Name and Port Number Registration . . . . . . . 92 | |||
| 12.7. Secure Service Name and Port Number Registration . . . . 93 | 12.7. Secure Service Name and Port Number Registration . . . . 93 | |||
| 12.8. Multicast Address Registration . . . . . . . . . . . . . 94 | 12.8. Multicast Address Registration . . . . . . . . . . . . . 94 | |||
| 13. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 94 | 13. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 94 | |||
| 14. References . . . . . . . . . . . . . . . . . . . . . . . . . 95 | 14. References . . . . . . . . . . . . . . . . . . . . . . . . . 95 | |||
| 14.1. Normative References . . . . . . . . . . . . . . . . . . 95 | 14.1. Normative References . . . . . . . . . . . . . . . . . . 95 | |||
| 14.2. Informative References . . . . . . . . . . . . . . . . . 97 | 14.2. Informative References . . . . . . . . . . . . . . . . . 97 | |||
| Appendix A. Examples . . . . . . . . . . . . . . . . . . . . . . 100 | Appendix A. Examples . . . . . . . . . . . . . . . . . . . . . . 100 | |||
| Appendix B. URI Examples . . . . . . . . . . . . . . . . . . . . 106 | Appendix B. URI Examples . . . . . . . . . . . . . . . . . . . . 105 | |||
| Appendix C. Changelog . . . . . . . . . . . . . . . . . . . . . 108 | Appendix C. Changelog . . . . . . . . . . . . . . . . . . . . . 107 | |||
| Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 118 | 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 such as | networks (e.g. 6LoWPAN, [RFC4944]). Constrained networks such as | |||
| 6LoWPAN support the fragmentation of IPv6 packets into small link- | 6LoWPAN support the fragmentation of IPv6 packets into small link- | |||
| layer frames, however incurring significant reduction in packet | layer frames, however incurring significant reduction in packet | |||
| delivery probability. One design goal of CoAP has been to keep | delivery probability. One design goal of CoAP has been to keep | |||
| message overhead small, thus limiting the need for fragmentation. | 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 | |||
| skipping to change at page 7, line 43 ¶ | skipping to change at page 7, line 43 ¶ | |||
| 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 | CoAP-to-CoAP Proxy | |||
| A proxy that maps from a CoAP request to a CoAP request, i.e. uses | A proxy that maps from a CoAP request to a CoAP request, i.e. | |||
| the CoAP protocol both on the server and the client side. | uses the CoAP protocol both on the server and the client side. | |||
| Contrast to cross-proxy. | 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 | |||
| skipping to change at page 8, line 29 ¶ | skipping to change at page 8, line 29 ¶ | |||
| message does not indicate success or failure of any request | message does not indicate success or failure of any request | |||
| encapsulated in the Confirmable message, but the Acknowledgement | encapsulated in the Confirmable message, but the Acknowledgement | |||
| message may also carry a Piggy-Backed Response (q.v.). | 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 | |||
| ultimately receiving the message in order to properly process the | ultimately receiving the message in order to properly process the | |||
| message (Section 5.4.1). Note that the implementation of critical | message (Section 5.4.1). Note that the implementation of critical | |||
| options is, as the name "Option" implies, generally optional: | options is, as the name "Option" implies, generally optional: | |||
| unsupported critical options lead to an error response or summary | unsupported critical options lead to an error response or summary | |||
| rejection of the message. | 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 | |||
| skipping to change at page 10, line 27 ¶ | 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 | |||
| skipping to change at page 11, line 17 ¶ | skipping to change at page 11, line 19 ¶ | |||
| 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 (in | sends an Acknowledgement message (ACK) with the same Message ID (in | |||
| this example, 0x7d34) from the corresponding endpoint; see Figure 2. | this example, 0x7d34) from the corresponding endpoint; see Figure 2. | |||
| When 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 (in this example, | still have a Message ID for duplicate detection (in this example, | |||
| 0x01a0); see Figure 3. When a recipient is not able to process a | 0x01a0); see Figure 3. When a recipient is not able to process a | |||
| Non-confirmable message, it may 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 runs over 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. | |||
| skipping to change at page 12, line 28 ¶ | skipping to change at page 12, line 31 ¶ | |||
| 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. (There is no need for | response, detailed in Section 5.2.1. (There is no need for | |||
| separately acknowledging a piggy-backed response, as the client will | separately acknowledging a piggy-backed response, as the client will | |||
| retransmit the request if the Acknowledgement message carrying the | retransmit the request if the Acknowledgement message carrying the | |||
| piggy-backed response is lost.) Two examples for a basic GET request | piggy-backed response is lost.) Two examples for a basic GET request | |||
| with piggy-backed response are shown in Figure 4, one successful, one | with piggy-backed response are shown in Figure 4, one successful, one | |||
| resulting in a 4.04 (Not Found) response. | 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 | |||
| If a request is sent in a Non-confirmable message, then the response | If a request is sent in a Non-confirmable message, then the response | |||
| is sent using a new Non-confirmable message, although the server may | is sent using a new Non-confirmable message, although the server may | |||
| instead send a Confirmable message. This type of exchange is | instead send a Confirmable message. This type of 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 | Methods beyond the basic four can be added to CoAP in separate | |||
| specifications. New methods do not necessarily have to use requests | specifications. New methods do not necessarily have to use requests | |||
| and responses in pairs. Even for existing methods, a single request | and responses in pairs. Even for existing methods, a single request | |||
| may yield multiple responses, e.g. for a multicast request | may yield multiple responses, e.g. for a multicast request | |||
| (Section 8) or with the Observe option [I-D.ietf-core-observe]. | (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 relate | making use of default values for efficiency. Response codes relate | |||
| to a small subset of HTTP response codes with a few CoAP specific | to a small subset of HTTP response codes with a few CoAP 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 | |||
| skipping to change at page 15, line 9 ¶ | skipping to change at page 15, line 17 ¶ | |||
| 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 compact 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. (UDP-lite | specification of which is out of this document's scope. (UDP-lite | |||
| [RFC3828] and UDP zero checksum [RFC6936] are not supported by CoAP.) | [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 | |||
| skipping to change at page 16, line 24 ¶ | skipping to change at page 16, line 27 ¶ | |||
| 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, split into a 3-bit class (most | Code: 8-bit unsigned integer, split into a 3-bit class (most | |||
| significant bits) and a 5-bit detail (least significant bits), | significant bits) and a 5-bit detail (least significant bits), | |||
| documented as c.dd where c is a digit from 0 to 7 for the 3-bit | documented as c.dd where c is a digit from 0 to 7 for the 3-bit | |||
| subfield and dd are two digits from 00 to 31 for the 5-bit | subfield and dd are two digits from 00 to 31 for the 5-bit | |||
| subfield. Indicates if the message carries a request (0.01-0.31) | subfield. The class can indicate a request (0), a success | |||
| or a response (2.00-5.31), or is empty (0.00). (All other code | response (2), a client error response (4), or a server error | |||
| values are reserved.) In case of a request, the Code field | response (5). (All other class values are reserved.) As a | |||
| indicates the Request Method; in case of a response a Response | special case, Code 0.00 indicates an Empty message. In case of a | |||
| Code. Possible values are maintained in the CoAP Code Registries | request, the Code field indicates the Request Method; in case of a | |||
| (Section 12.1). The semantics of requests and responses are | response a Response Code. Possible values are maintained in the | |||
| defined in Section 5. | 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 18, line 36 ¶ | 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 48 ¶ | 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 51 ¶ | 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 | |||
| Registries (Section 12.1). | Registries (Section 12.1). | |||
| An empty message has the Code field set to 0.00. The Token Length | An Empty message has the Code field set to 0.00. The Token Length | |||
| field MUST be set to 0 and bytes of data MUST NOT be present after | field MUST be set to 0 and bytes of data MUST NOT be present after | |||
| the Message ID field. If there are any bytes, they MUST be processed | the Message ID field. If there are any bytes, they MUST be processed | |||
| as a message 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, unless it is used only | always carries either a request or response, unless it is used only | |||
| to elicit a Reset message in which case it is empty. A recipient | to elicit a Reset message in which case it is Empty. A recipient | |||
| MUST acknowledge a Confirmable message with an Acknowledgement | MUST acknowledge a Confirmable message with an Acknowledgement | |||
| message or, if it lacks context to process the message properly | message or, if it lacks context to process the message properly | |||
| (including the case where the message is empty, uses a code with a | (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 | 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 (including the case where the Acknowledgement | or Reset message (including the case where the Acknowledgement | |||
| carries a request or a code with a reserved class, or the Reset | carries a request or a code with a reserved class, or the Reset | |||
| message is not empty) is effected by silently ignoring it. More | message is not Empty) is effected by silently ignoring it. More | |||
| generally, recipients of Acknowledgement and Reset messages MUST NOT | generally, recipients of Acknowledgement and Reset messages MUST NOT | |||
| respond with either Acknowledgement or Reset messages. | 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 | |||
| skipping to change at page 22, line 4 ¶ | skipping to change at page 21, line 37 ¶ | |||
| 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 duration (often not an integral number of seconds) | to a random duration (often not an integral number of seconds) | |||
| between ACK_TIMEOUT and (ACK_TIMEOUT * ACK_RANDOM_FACTOR) (see | between ACK_TIMEOUT and (ACK_TIMEOUT * ACK_RANDOM_FACTOR) (see | |||
| Section 4.8), and the retransmission counter is set to 0. When the | Section 4.8), and the retransmission counter is set to 0. When the | |||
| timeout is triggered and the retransmission counter is less than | timeout is triggered and the retransmission counter is less than | |||
| MAX_RETRANSMIT, the message is retransmitted, the retransmission | MAX_RETRANSMIT, the message is retransmitted, the retransmission | |||
| counter is incremented, and the timeout is doubled. If the | counter is incremented, and the timeout is doubled. If the | |||
| retransmission counter reaches MAX_RETRANSMIT on a timeout, or if the | retransmission counter reaches MAX_RETRANSMIT on a timeout, or if the | |||
| endpoint receives a Reset message, then the attempt to transmit the | endpoint receives a Reset message, then the attempt to transmit the | |||
| message is canceled and the application process informed of failure. | message is canceled and the application process informed of failure. | |||
| On the other hand, if the endpoint receives an acknowledgement in | On the other hand, if the endpoint receives an acknowledgement in | |||
| time, transmission is considered successful. | time, transmission is considered successful. | |||
| This specification makes no strong requirements on the accuracy of | This specification makes no strong requirements on the accuracy of | |||
| the clocks used to implement the above binary exponential backoff | the clocks used to implement the above binary exponential backoff | |||
| algorithm. In particular, an endpoint may be late for a specific | algorithm. In particular, an endpoint may be late for a specific | |||
| retransmission due to its sleep schedule, and maybe catch up on the | retransmission due to its sleep schedule, and maybe catch up on the | |||
| next one. However, the minimum spacing before another retransmission | next one. However, the minimum spacing before another retransmission | |||
| is ACK_TIMEOUT, and the entire sequence of (re-)transmissions MUST | 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 | 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. | 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 MUST | turn rely on this cross-layer behavior from a requester, i.e. it | |||
| retain the state to create the ACK for the request, if needed, even | MUST retain the state to create the ACK for the request, if needed, | |||
| if a Confirmable response was already acknowledged by the requester. | even if a Confirmable response was already acknowledged by the | |||
| requester. | ||||
| Another reason for giving up retransmission MAY be the receipt of | Another reason for giving up retransmission MAY be the receipt of | |||
| ICMP errors. If it is desired to take account of ICMP errors, to | ICMP errors. If it is desired to take account of ICMP errors, to | |||
| mitigate potential spoofing attacks, implementations SHOULD take care | mitigate potential spoofing attacks, implementations SHOULD take care | |||
| to check the information about the original datagram in the ICMP | to check the information about the original datagram in the ICMP | |||
| message, including port numbers and CoAP header information such as | message, including port numbers and CoAP header information such as | |||
| message type and code, Message ID, and Token; if this is not possible | 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 | due to limitations of the UDP service API, ICMP errors SHOULD be | |||
| ignored. Packet Too Big errors [RFC4443] ("fragmentation needed and | ignored. Packet Too Big errors [RFC4443] ("fragmentation needed and | |||
| DF set" for IPv4 [RFC0792]) cannot properly occur and SHOULD be | DF set" for IPv4 [RFC0792]) cannot properly occur and SHOULD be | |||
| skipping to change at page 23, line 6 ¶ | skipping to change at page 22, line 40 ¶ | |||
| 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, uses a code with a reserved class (1, 6 or 7), or has a | Empty, uses a code with a reserved class (1, 6 or 7), or has a | |||
| message format error), it MUST reject the message; rejecting a Non- | message format error), it MUST reject the message; rejecting a Non- | |||
| confirmable message MAY involve sending a matching Reset message, and | confirmable message MAY involve sending a matching Reset message, and | |||
| apart from the Reset message the rejected message MUST be silently | apart from the Reset message the rejected message MUST be silently | |||
| ignored. | 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 | 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 | 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"). | normal operation, but only to elicit a Reset message ("CoAP ping"). | |||
| +----------+-----+-----+-----+-----+ | +----------+-----+-----+-----+-----+ | |||
| | | CON | NON | ACK | RST | | | | CON | NON | ACK | RST | | |||
| +----------+-----+-----+-----+-----+ | +----------+-----+-----+-----+-----+ | |||
| | Request | X | X | - | - | | | Request | X | X | - | - | | |||
| | Response | X | X | X | - | | | Response | X | X | X | - | | |||
| | Empty | * | - | X | X | | | Empty | * | - | X | X | | |||
| +----------+-----+-----+-----+-----+ | +----------+-----+-----+-----+-----+ | |||
| skipping to change at page 26, line 46 ¶ | 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 29, line 7 ¶ | skipping to change at page 28, line 46 ¶ | |||
| 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 31, line 14 ¶ | 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, CoAP code numbers including the response code are | diagnostics, CoAP code numbers including the response code are | |||
| skipping to change at page 33, line 25 ¶ | skipping to change at page 33, line 13 ¶ | |||
| effectively is a promise that the request will be acted upon later. | 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. Once | Acknowledgement to the Confirmable request as an Empty message. Once | |||
| the server sends back an empty Acknowledgement, it MUST NOT send back | the server sends back an Empty Acknowledgement, it MUST NOT send back | |||
| the response in another Acknowledgement, even if the client | the response in another Acknowledgement, even if the client | |||
| retransmits another identical request. If a retransmitted request is | retransmits another identical request. If a retransmitted request is | |||
| received (perhaps because the original Acknowledgement was delayed), | received (perhaps because the original Acknowledgement was delayed), | |||
| another empty Acknowledgement is sent and any response MUST be sent | another Empty Acknowledgement is sent and any response MUST be sent | |||
| as a separate response. | as a separate response. | |||
| If the server then sends a Confirmable response, the client's | If the server then sends a Confirmable response, the client's | |||
| Acknowledgement to that response MUST also be an empty message (one | 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 34, line 10 ¶ | 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) SHOULD use a non-trivial, randomized token to guard | (Section 9) SHOULD use a non-trivial, randomized token to guard | |||
| against spoofing of responses (Section 11.4). This protective use of | against spoofing of responses (Section 11.4). This protective use of | |||
| tokens is the reason they are allowed to be up to 8 bytes in size. | tokens is the reason they are allowed to be up to 8 bytes in size. | |||
| The actual size of the random component to be used for the Token | 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 | depends on the security requirements of the client and the level of | |||
| threat posed by spoofing of responses. A client that is connected to | threat posed by spoofing of responses. A client that is connected to | |||
| the general Internet SHOULD use at least 32 bits of randomness; | the general Internet SHOULD use at least 32 bits of randomness; | |||
| keeping in mind that not being directly connected to the Internet is | keeping in mind that not being directly connected to the Internet is | |||
| not necessarily sufficient protection against spoofing. (Note that | not necessarily sufficient protection against spoofing. (Note that | |||
| the Message ID adds little in protection as it is usually | the Message ID adds little in protection as it is usually | |||
| sequentially assigned, i.e. guessable, and can be circumvented by | sequentially assigned, i.e. guessable, and can be circumvented by | |||
| spoofing a separate response.) Clients that want to optimize the | spoofing a separate response.) Clients that want to optimize the | |||
| Token length may further want to detect the level of ongoing attacks | Token length may further want to detect the level of ongoing attacks | |||
| (e.g., by tallying recent Token mismatches in incoming messages) and | (e.g., by tallying recent Token mismatches in incoming messages) and | |||
| adjust the Token length upwards appropriately. [RFC4086] discusses | adjust the Token length upwards appropriately. [RFC4086] discusses | |||
| randomness requirements for security. | 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 | |||
| skipping to change at page 36, line 15 ¶ | 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 39, line 6 ¶ | skipping to change at page 38, line 47 ¶ | |||
| 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/ | mask to indicate if an option is Critical/Elective, Unsafe/Safe-to- | |||
| Safe-to-Forward and in the case of Safe-to-Forward, also a Cache-Key | Forward and in the case of Safe-to-Forward, also a Cache-Key | |||
| indication as shown by the following figure. In the following text, | 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 | the bit mask is expressed as a single byte that is applied to the | |||
| least significant byte of the option number in unsigned integer | least significant byte of the option number in unsigned integer | |||
| representation. When bit 7 (the least significant bit) is 1, an | 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-to-Forward when 0). When bit | an option is Unsafe (and likewise Safe-to-Forward when 0). When bit | |||
| 6 is 0, i.e., the option is not Unsafe, it is not a Cache-Key | 6 is 0, i.e., the option is not Unsafe, it is not a Cache-Key | |||
| (NoCacheKey) if and only if bits 3-5 are all set to 1; all other bit | (NoCacheKey) if and only if bits 3-5 are all set to 1; all other bit | |||
| combinations mean that it indeed is a Cache-Key. These classes of | combinations mean that it indeed is a Cache-Key. These classes of | |||
| options are 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 (Least Significant Byte) | 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); | |||
| skipping to change at page 44, line 43 ¶ | skipping to change at page 44, line 40 ¶ | |||
| server, considering the time the resource representation spent in the | server, considering the time the resource representation spent in the | |||
| cache. E.g., the Max-Age Option could be adjusted by the proxy for | cache. E.g., the Max-Age Option could be adjusted by the proxy 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-to-Forward options that it does not recognize. Similarly, | Safe-to-Forward options that it does not recognize. Similarly, | |||
| Unsafe options in a response that are not recognized by the CoAP-to- | Unsafe options in a response that are not recognized by the CoAP-to- | |||
| CoAP proxy server MUST lead to a 5.02 (Bad Gateway) response. Again, | CoAP proxy server MUST lead to a 5.02 (Bad Gateway) response. Again, | |||
| Safe-to-Forward options that are not recognized MUST be forwarded. | Safe-to-Forward options that are not recognized MUST be forwarded. | |||
| skipping to change at page 45, line 50 ¶ | 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 50, line 22 ¶ | 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 52, line 4 ¶ | skipping to change at page 51, line 30 ¶ | |||
| The individual CoAP options are summarized in Table 4 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-Forward (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 | | ||||
| +-----+---+---+---+---+----------------+--------+--------+----------+ | ||||
| | 1 | x | | | x | If-Match | opaque | 0-8 | (none) | | ||||
| | 3 | x | x | - | | Uri-Host | string | 1-255 | (see | | ||||
| | | | | | | | | | below) | | ||||
| | 4 | | | | x | ETag | opaque | 1-8 | (none) | | ||||
| | 5 | x | | | | If-None-Match | empty | 0 | (none) | | ||||
| | 7 | x | x | - | | Uri-Port | uint | 0-2 | (see | | ||||
| | | | | | | | | | below) | | ||||
| | 8 | | | | x | Location-Path | string | 0-255 | (none) | | ||||
| | 11 | x | x | - | x | Uri-Path | string | 0-255 | (none) | | ||||
| | 12 | | | | | Content-Format | uint | 0-2 | (none) | | ||||
| | 14 | | x | - | | Max-Age | uint | 0-4 | 60 | | ||||
| | 15 | x | x | - | x | Uri-Query | string | 0-255 | (none) | | ||||
| | 16 | | | | | Accept | uint | 0-2 | (none) | | ||||
| | 20 | | | | x | Location-Query | string | 0-255 | (none) | | ||||
| | 35 | x | x | - | | Proxy-Uri | string | 1-1034 | (none) | | ||||
| | 39 | x | x | - | | Proxy-Scheme | string | 1-255 | (none) | | ||||
| +-----+---+---+---+---+----------------+--------+--------+----------+ | ||||
| +-----+----+---+---+---+----------------+--------+--------+---------+ | ||||
| | No. | C | U | N | R | Name | Format | Length | Default | | ||||
| +-----+----+---+---+---+----------------+--------+--------+---------+ | ||||
| | 1 | x | | | x | If-Match | opaque | 0-8 | (none) | | ||||
| | 3 | x | x | - | | Uri-Host | string | 1-255 | (see | | ||||
| | | | | | | | | | below) | | ||||
| | 4 | | | | x | ETag | opaque | 1-8 | (none) | | ||||
| | 5 | x | | | | If-None-Match | empty | 0 | (none) | | ||||
| | 7 | x | x | - | | Uri-Port | uint | 0-2 | (see | | ||||
| | | | | | | | | | below) | | ||||
| | 8 | | | | x | Location-Path | string | 0-255 | (none) | | ||||
| | 11 | x | x | - | x | Uri-Path | string | 0-255 | (none) | | ||||
| | 12 | | | | | Content-Format | uint | 0-2 | (none) | | ||||
| | 14 | | x | - | | Max-Age | uint | 0-4 | 60 | | ||||
| | 15 | x | x | - | x | Uri-Query | string | 0-255 | (none) | | ||||
| | 17 | x | | | | Accept | uint | 0-2 | (none) | | ||||
| | 20 | | | | x | Location-Query | string | 0-255 | (none) | | ||||
| | 35 | x | x | - | | Proxy-Uri | string | 1-1034 | (none) | | ||||
| | 39 | x | x | - | | Proxy-Scheme | string | 1-255 | (none) | | ||||
| | 60 | | | x | | Size1 | uint | 0-4 | (none) | | ||||
| +-----+----+---+---+---+----------------+--------+--------+---------+ | ||||
| C=Critical, U=Unsafe, N=NoCacheKey, R=Repeatable | C=Critical, U=Unsafe, N=NoCacheKey, R=Repeatable | |||
| Table 4: 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 | |||
| skipping to change at page 53, line 21 ¶ | 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 54, line 22 ¶ | skipping to change at page 53, line 48 ¶ | |||
| the desired URI other than the scheme component actually can be | the desired URI other than the scheme component actually can be | |||
| expressed using Uri-* options; e.g., to represent a URI with a | expressed using Uri-* options; e.g., to represent a URI with a | |||
| userinfo component in the authority, only Proxy-Uri can be used. | 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.) | |||
| 5.10.6. ETag | 5.10.6. ETag | |||
| An entity-tag is intended for use as a resource-local identifier for | An entity-tag is intended for use as a resource-local identifier for | |||
| differentiating between representations of the same resource that | differentiating between representations of the same resource that | |||
| vary over time. It is generated by the server providing the | vary over time. It is generated by the server providing the | |||
| resource, which may generate it in any number of ways including a | resource, which may generate it in any number of ways including a | |||
| skipping to change at page 55, line 51 ¶ | 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 56, line 30 ¶ | 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 58, line 5 ¶ | skipping to change at page 57, line 32 ¶ | |||
| 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. | |||
| (It is not very useful to combine If-Match and If-None-Match options | (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.) | in one request, because the condition will then never be fulfilled.) | |||
| 6. CoAP URIs | 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 63, line 16 ¶ | skipping to change at page 63, line 15 ¶ | |||
| 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 | |||
| skipping to change at page 64, line 5 ¶ | skipping to change at page 64, line 5 ¶ | |||
| 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. A more general | defined by a series of deltas to Unicast CoAP. A more general | |||
| discussion of group communication with CoAP is in | discussion of group communication with CoAP is in | |||
| [I-D.ietf-core-groupcomm]. | [I-D.ietf-core-groupcomm]. | |||
| skipping to change at page 65, line 26 ¶ | skipping to change at page 65, line 31 ¶ | |||
| 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 68, line 16 ¶ | 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 70, line 8 ¶ | skipping to change at page 70, line 10 ¶ | |||
| This means the response to a DTLS secured request MUST always be DTLS | This means the response to a DTLS secured request MUST always be DTLS | |||
| secured using the same security session and epoch. Any attempt to | secured using the same security session and epoch. Any attempt to | |||
| supply a NoSec response to a DTLS request simply does not match the | supply a NoSec response to a DTLS request simply does not match the | |||
| request and (unless it does match an unrelated NoSec request) | request and (unless it does match an unrelated NoSec request) | |||
| therefore MUST be rejected. | 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]. | |||
| skipping to change at page 79, line 29 ¶ | skipping to change at page 79, line 30 ¶ | |||
| 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 80, line 20 ¶ | 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. | directed at the victim. | |||
| 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. | |||
| skipping to change at page 80, line 42 ¶ | skipping to change at page 80, line 42 ¶ | |||
| Therefore, large amplification factors SHOULD NOT be provided in the | Therefore, large amplification factors SHOULD NOT be provided in the | |||
| response if the request is not authenticated. A CoAP server can | response if the request is not authenticated. A CoAP server can | |||
| reduce the amount of amplification it provides to an attacker by | reduce the amount of amplification it provides to an attacker by | |||
| using slicing/blocking modes of CoAP [I-D.ietf-core-block] and | using slicing/blocking modes of CoAP [I-D.ietf-core-block] and | |||
| offering large resource representations only in relatively small | offering large resource representations only in relatively small | |||
| slices. E.g., for a 1000 byte resource, a 10-byte request might | slices. E.g., for a 1000 byte resource, a 10-byte request might | |||
| result in an 80-byte response (with a 64-byte block) instead of a | result in an 80-byte response (with a 64-byte block) instead of a | |||
| 1016-byte response, considerably reducing the 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 81, line 20 ¶ | 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 an ACK in response to a CON message, thus potentially | 2. spoofing an ACK in response to a CON message, thus potentially | |||
| preventing the sender of the CON message from retransmitting, and | preventing the sender of the CON message from retransmitting, and | |||
| drowning out the actual response; or | drowning out the actual response; or | |||
| 3. spoofing the entire response with forged payload/options (this | 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, | |||
| skipping to change at page 83, line 43 ¶ | 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 15: 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 85, line 6 ¶ | skipping to change at page 85, line 5 ¶ | |||
| Values in the two sub-registries are eight-bit values notated as | Values in the two sub-registries are eight-bit values notated as | |||
| three decimal digits c.dd separated by a period between the first and | 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 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 | the code class; the second and third digit dd denote a decimal number | |||
| between 00 and 31 for the detail. | between 00 and 31 for the detail. | |||
| All Code values are assigned by sub-registries according to the | All Code values are assigned by sub-registries according to the | |||
| following ranges: | following ranges: | |||
| 0.00 Indicates an empty message (see Section 4.1). | 0.00 Indicates an Empty message (see Section 4.1). | |||
| 0.01-0.31 Indicates a request. Values in this range are assigned by | 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). | |||
| 1.00-1.31 Reserved | 1.00-1.31 Reserved | |||
| 2.00-5.31 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). | |||
| skipping to change at page 86, line 6 ¶ | skipping to change at page 86, line 4 ¶ | |||
| Review 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 2.00-5.31, a description of the Response Code, and a reference | range 2.00-5.31, a description of the Response Code, and a reference | |||
| to 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 | | |||
| +------+----------------------------+-----------+ | +------+------------------------------+-----------+ | |||
| | 2.01 | Created | [RFCXXXX] | | | 2.01 | Created | [RFCXXXX] | | |||
| | 2.02 | Deleted | [RFCXXXX] | | | 2.02 | Deleted | [RFCXXXX] | | |||
| | 2.03 | Valid | [RFCXXXX] | | | 2.03 | Valid | [RFCXXXX] | | |||
| | 2.04 | Changed | [RFCXXXX] | | | 2.04 | Changed | [RFCXXXX] | | |||
| | 2.05 | Content | [RFCXXXX] | | | 2.05 | Content | [RFCXXXX] | | |||
| | 4.00 | Bad Request | [RFCXXXX] | | | 4.00 | Bad Request | [RFCXXXX] | | |||
| | 4.01 | Unauthorized | [RFCXXXX] | | | 4.01 | Unauthorized | [RFCXXXX] | | |||
| | 4.02 | Bad Option | [RFCXXXX] | | | 4.02 | Bad Option | [RFCXXXX] | | |||
| | 4.03 | Forbidden | [RFCXXXX] | | | 4.03 | Forbidden | [RFCXXXX] | | |||
| | 4.04 | Not Found | [RFCXXXX] | | | 4.04 | Not Found | [RFCXXXX] | | |||
| | 4.05 | Method Not Allowed | [RFCXXXX] | | | 4.05 | Method Not Allowed | [RFCXXXX] | | |||
| | 4.06 | Not Acceptable | [RFCXXXX] | | | 4.06 | Not Acceptable | [RFCXXXX] | | |||
| | 4.12 | Precondition Failed | [RFCXXXX] | | | 4.12 | Precondition Failed | [RFCXXXX] | | |||
| | 4.13 | Request Entity Too Large | [RFCXXXX] | | | 4.13 | Request Entity Too Large | [RFCXXXX] | | |||
| | 4.15 | Unsupported Content-Format | [RFCXXXX] | | | 4.15 | Unsupported Content-Format | [RFCXXXX] | | |||
| | 5.00 | Internal Server Error | [RFCXXXX] | | | 5.00 | Internal Server Error | [RFCXXXX] | | |||
| | 5.01 | Not Implemented | [RFCXXXX] | | | 5.01 | Not Implemented | [RFCXXXX] | | |||
| | 5.02 | Bad Gateway | [RFCXXXX] | | | 5.02 | Bad Gateway | [RFCXXXX] | | |||
| | 5.03 | Service Unavailable | [RFCXXXX] | | | 5.03 | Service Unavailable | [RFCXXXX] | | |||
| | 5.04 | Gateway Timeout | [RFCXXXX] | | | 5.04 | Gateway Timeout | [RFCXXXX] | | |||
| | 5.05 | Proxying Not Supported | [RFCXXXX] | | | 5.05 | Proxying Not Supported | [RFCXXXX] | | |||
| +------+----------------------------+-----------+ | +------+------------------------------+-----------+ | |||
| Table 6: CoAP Response Codes | Table 6: CoAP Response Codes | |||
| The Response Codes 3.00-3.31 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 sub-registry is "IETF | The IANA policy for future additions to this sub-registry is "IETF | |||
| Review 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 | |||
| skipping to change at page 88, line 5 ¶ | skipping to change at page 87, line 35 ¶ | |||
| This document defines a sub-registry for the Option Numbers used in | This document defines a sub-registry for the Option Numbers used in | |||
| CoAP options within the "CoRE Parameters" registry. The name of the | CoAP options within the "CoRE Parameters" registry. The name of the | |||
| sub-registry is "CoAP Option Numbers". | sub-registry is "CoAP Option Numbers". | |||
| Each entry in the sub-registry must include the Option Number, the | Each entry in the sub-registry must include the Option Number, the | |||
| name 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 sub-registry are as follows: | Initial entries in this sub-registry are as follows: | |||
| +--------+----------------+-----------+ | +--------+------------------+-----------+ | |||
| | Number | Name | Reference | | | Number | Name | Reference | | |||
| +--------+----------------+-----------+ | +--------+------------------+-----------+ | |||
| | 0 | (Reserved) | [RFCXXXX] | | | 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 7: CoAP Option Numbers | Table 7: CoAP Option Numbers | |||
| The IANA policy for future additions to this sub-registry is split | The IANA policy for future additions to this sub-registry is split | |||
| into three tiers as follows. The range of 0..255 is reserved for | into three tiers as follows. The range of 0..255 is reserved for | |||
| options defined by the IETF (IETF Review or IESG approval). The | options defined by the IETF (IETF Review or IESG approval). The | |||
| range of 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 | |||
| skipping to change at page 89, line 31 ¶ | skipping to change at page 89, line 15 ¶ | |||
| 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 sub-registry for a subset of Internet media types | a sub-registry for a subset of Internet media types to be used in | |||
| to 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 sub-registry is "CoAP | numeric identifier. The name of the sub-registry is "CoAP Content- | |||
| Content-Formats", within the "CoRE Parameters" registry. | Formats", within the "CoRE Parameters" registry. | |||
| Each entry in the sub-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 sub-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 9: 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. | |||
| skipping to change at page 91, line 9 ¶ | 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 92, line 26 ¶ | 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 94, line 51 ¶ | 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 | Special thanks also to the IESG reviewers, Adrian Farrel, Martin | |||
| Stiemerling, Pete Resnick, Richard Barnes, Sean Turner, Spencer | Stiemerling, Pete Resnick, Richard Barnes, Sean Turner, Spencer | |||
| Dawkins, Stephen Farrell, and Ted Lemon, who contributed in-depth | Dawkins, Stephen Farrell, and Ted Lemon, who contributed in-depth | |||
| reviews. | 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.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 96, line 19 ¶ | 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 97, line 7 ¶ | skipping to change at page 96, line 46 ¶ | |||
| [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, | [RFC5480] Turner, S., Brown, D., Yiu, K., Housley, R., and T. Polk, | |||
| "Elliptic Curve Cryptography Subject Public Key | "Elliptic Curve Cryptography Subject Public Key | |||
| Information", RFC 5480, March 2009. | 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 | |||
| skipping to change at page 97, line 30 ¶ | skipping to change at page 97, line 20 ¶ | |||
| [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., | [RFC6920] Farrell, S., Kutscher, D., Dannewitz, C., Ohlman, B., | |||
| Keranen, A., and P. Hallam-Baker, "Naming Things with | Keranen, A., and P. Hallam-Baker, "Naming Things with | |||
| Hashes", RFC 6920, April 2013. | 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-25 (work in progress), | CoAP", draft-bormann-coap-misc-22 (work in progress), | |||
| May 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] | [I-D.ietf-core-groupcomm] | |||
| Rahman, A. and E. Dijk, "Group Communication for CoAP", | Rahman, A. and E. Dijk, "Group Communication for CoAP", | |||
| draft-ietf-core-groupcomm-07 (work in progress), May 2013. | 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-04 | Constrained Node Networks", draft-ietf-lwig-terminology-04 | |||
| (work in progress), April 2013. | (work in progress), April 2013. | |||
| [I-D.ietf-tls-multiple-cert-status-extension] | [I-D.ietf-tls-multiple-cert-status-extension] | |||
| Pettersen, Y., "The TLS Multiple Certificate Status | Pettersen, Y., "The TLS Multiple Certificate Status | |||
| Request Extension", | Request Extension", draft-ietf-tls-multiple-cert-status- | |||
| draft-ietf-tls-multiple-cert-status-extension-08 (work in | extension-08 (work in progress), April 2013. | |||
| 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. | |||
| [RFC0792] Postel, J., "Internet Control Message Protocol", STD 5, | [RFC0792] Postel, J., "Internet Control Message Protocol", STD 5, | |||
| RFC 792, September 1981. | RFC 792, September 1981. | |||
| [RFC0793] Postel, J., "Transmission Control Protocol", STD 7, | [RFC0793] Postel, J., "Transmission Control Protocol", STD 7, RFC | |||
| RFC 793, September 1981. | 793, September 1981. | |||
| [RFC2560] Myers, M., Ankney, R., Malpani, A., Galperin, S., and C. | [RFC2560] Myers, M., Ankney, R., Malpani, A., Galperin, S., and C. | |||
| Adams, "X.509 Internet Public Key Infrastructure Online | Adams, "X.509 Internet Public Key Infrastructure Online | |||
| Certificate Status Protocol - OCSP", RFC 2560, June 1999. | 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 | [RFC3828] Larzon, L-A., Degermark, M., Pink, S., Jonsson, L-E., and | |||
| G. Fairhurst, "The Lightweight User Datagram Protocol | G. Fairhurst, "The Lightweight User Datagram Protocol | |||
| (UDP-Lite)", RFC 3828, July 2004. | (UDP-Lite)", RFC 3828, July 2004. | |||
| [RFC4086] Eastlake, D., Schiller, J., and S. Crocker, "Randomness | [RFC4086] Eastlake, D., Schiller, J., and S. Crocker, "Randomness | |||
| skipping to change at page 99, line 45 ¶ | skipping to change at page 99, line 35 ¶ | |||
| 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 | [RFC4821] Mathis, M. and J. Heffner, "Packetization Layer Path MTU | |||
| Discovery", RFC 4821, March 2007. | 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 | [RFC5489] Badra, M. and I. Hajjeh, "ECDHE_PSK Cipher Suites for | |||
| Transport Layer Security (TLS)", RFC 5489, March 2009. | Transport Layer Security (TLS)", RFC 5489, March 2009. | |||
| [RFC6090] McGrew, D., Igoe, K., and M. Salter, "Fundamental Elliptic | [RFC6090] McGrew, D., Igoe, K., and M. Salter, "Fundamental Elliptic | |||
| Curve Cryptography Algorithms", RFC 6090, February 2011. | 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 | [RFC6936] Fairhurst, G. and M. Westerlund, "Applicability Statement | |||
| for the Use of IPv6 UDP Datagrams with Zero Checksums", | for the Use of IPv6 UDP Datagrams with Zero Checksums", | |||
| RFC 6936, April 2013. | 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 16 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=0.01, MID=0x7d34) | +----->| Header: GET (T=CON, Code=0.01, MID=0x7d34) | |||
| | GET | Uri-Path: "temperature" | | GET | Uri-Path: "temperature" | |||
| skipping to change at page 105, line 46 ¶ | skipping to change at page 104, line 46 ¶ | |||
| | | | | | | |||
| |<-----+ Header: 2.05 Content (T=NON, Code=2.05, 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 22: Non-confirmable request; Non-confirmable response | Figure 22: Non-confirmable request; Non-confirmable response | |||
| In Figure 23, 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=0.01, MID=0x7d41) | +------>| | | | Header: GET (T=NON, Code=0.01, MID=0x7d41) | |||
| | GET | | | | Token: 0x86 | | GET | | | | Token: 0x86 | |||
| skipping to change at page 107, 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 108, 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 | Changes from ietf-15 to ietf-16: Address comments from the IESG | |||
| reviews. These should not impact interoperability. | reviews. These should not impact interoperability. | |||
| o Clarify that once there has been an empty ACK, all further ACKs to | o Clarify that once there has been an empty ACK, all further ACKs to | |||
| the same message also must be empty (#301). | the same message also must be empty (#301). | |||
| o Define Cache-key properly (#302). | o Define Cache-key properly (#302). | |||
| o Clarify that ACKs don't get retransmitted, the CONs do (#303). | o Clarify that ACKs don't get retransmitted, the CONs do (#303). | |||
| skipping to change at page 111, line 51 ¶ | 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 116, line 5 ¶ | 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. 137 change blocks. | ||||
| 401 lines changed or deleted | 424 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/ | ||||