< draft-ietf-core-coap   rfc7252.txt 
CoRE Working Group Z. Shelby Internet Engineering Task Force (IETF) Z. Shelby
Internet-Draft Sensinode Request for Comments: 7252 ARM
Intended status: Standards Track K. Hartke Category: Standards Track K. Hartke
Expires: December 30, 2013 C. Bormann ISSN: 2070-1721 C. Bormann
Universitaet Bremen TZI Universitaet Bremen TZI
June 28, 2013 June 2014
Constrained Application Protocol (CoAP) The Constrained Application Protocol (CoAP)
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 IPv6 over Low-Power Wireless Personal Area Networks
typical throughput of 10s of kbit/s. The protocol is designed for (6LoWPANs) often have high packet error rates and a typical
machine-to-machine (M2M) applications such as smart energy and throughput of 10s of kbit/s. The protocol is designed for machine-
building automation. to-machine (M2M) applications such as smart energy and 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 is an Internet Standards Track document.
provisions of BCP 78 and BCP 79.
Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF). Note that other groups may also distribute
working documents as Internet-Drafts. The list of current Internet-
Drafts is at http://datatracker.ietf.org/drafts/current/.
Internet-Drafts are draft documents valid for a maximum of six months This document is a product of the Internet Engineering Task Force
and may be updated, replaced, or obsoleted by other documents at any (IETF). It represents the consensus of the IETF community. It has
time. It is inappropriate to use Internet-Drafts as reference received public review and has been approved for publication by the
material or to cite them other than as "work in progress." Internet Engineering Steering Group (IESG). Further information on
Internet Standards is available in Section 2 of RFC 5741.
This Internet-Draft will expire on December 30, 2013. Information about the current status of this document, any errata,
and how to provide feedback on it may be obtained at
http://www.rfc-editor.org/info/rfc7252.
Copyright Notice Copyright Notice
Copyright (c) 2013 IETF Trust and the persons identified as the Copyright (c) 2014 IETF Trust and the persons identified as the
document authors. All rights reserved. document authors. All rights reserved.
This document is subject to BCP 78 and the IETF Trust's Legal This document is subject to BCP 78 and the IETF Trust's Legal
Provisions Relating to IETF Documents Provisions Relating to IETF Documents
(http://trustee.ietf.org/license-info) in effect on the date of (http://trustee.ietf.org/license-info) in effect on the date of
publication of this document. Please review these documents publication of this document. Please review these documents
carefully, as they describe your rights and restrictions with respect carefully, as they describe your rights and restrictions with respect
to this document. Code Components extracted from this document must to this document. Code Components extracted from this document must
include Simplified BSD License text as described in Section 4.e of include Simplified BSD License text as described in Section 4.e of
the Trust Legal Provisions and are provided without warranty as the Trust Legal Provisions and are provided without warranty as
described in the Simplified BSD License. described in the Simplified BSD License.
Table of Contents Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 5 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 5
1.1. Features . . . . . . . . . . . . . . . . . . . . . . . . 5 1.1. Features . . . . . . . . . . . . . . . . . . . . . . . . 5
1.2. Terminology . . . . . . . . . . . . . . . . . . . . . . . 6 1.2. Terminology . . . . . . . . . . . . . . . . . . . . . . . 6
2. Constrained Application Protocol . . . . . . . . . . . . . . 9 2. Constrained Application Protocol . . . . . . . . . . . . . . 10
2.1. Messaging Model . . . . . . . . . . . . . . . . . . . . . 10 2.1. Messaging Model . . . . . . . . . . . . . . . . . . . . . 11
2.2. Request/Response Model . . . . . . . . . . . . . . . . . 12 2.2. Request/Response Model . . . . . . . . . . . . . . . . . 12
2.3. Intermediaries and Caching . . . . . . . . . . . . . . . 14 2.3. Intermediaries and Caching . . . . . . . . . . . . . . . 15
2.4. Resource Discovery . . . . . . . . . . . . . . . . . . . 15 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 . . . . . . . . . . . . . . 20 4.2. Messages Transmitted Reliably . . . . . . . . . . . . . . 21
4.3. Messages Transmitted Without Reliability . . . . . . . . 22 4.3. Messages Transmitted without Reliability . . . . . . . . 23
4.4. Message Correlation . . . . . . . . . . . . . . . . . . . 23 4.4. Message Correlation . . . . . . . . . . . . . . . . . . . 24
4.5. Message Deduplication . . . . . . . . . . . . . . . . . . 24 4.5. Message Deduplication . . . . . . . . . . . . . . . . . . 24
4.6. Message Size . . . . . . . . . . . . . . . . . . . . . . 24 4.6. Message Size . . . . . . . . . . . . . . . . . . . . . . 25
4.7. Congestion Control . . . . . . . . . . . . . . . . . . . 25 4.7. Congestion Control . . . . . . . . . . . . . . . . . . . 26
4.8. Transmission Parameters . . . . . . . . . . . . . . . . . 26 4.8. Transmission Parameters . . . . . . . . . . . . . . . . . 27
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 . . . . . . . . . . . . . . . . . 31
5.1. Requests . . . . . . . . . . . . . . . . . . . . . . . . 30 5.1. Requests . . . . . . . . . . . . . . . . . . . . . . . . 31
5.2. Responses . . . . . . . . . . . . . . . . . . . . . . . . 30 5.2. Responses . . . . . . . . . . . . . . . . . . . . . . . . 31
5.2.1. Piggy-backed . . . . . . . . . . . . . . . . . . . . 32 5.2.1. Piggybacked . . . . . . . . . . . . . . . . . . . . . 33
5.2.2. Separate . . . . . . . . . . . . . . . . . . . . . . 32 5.2.2. Separate . . . . . . . . . . . . . . . . . . . . . . 33
5.2.3. Non-confirmable . . . . . . . . . . . . . . . . . . . 33 5.2.3. Non-confirmable . . . . . . . . . . . . . . . . . . . 34
5.3. Request/Response Matching . . . . . . . . . . . . . . . . 33 5.3. Request/Response Matching . . . . . . . . . . . . . . . . 34
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 . . . . . . . . . . . . . . . . . . . . . . . . . 36
5.4.1. Critical/Elective . . . . . . . . . . . . . . . . . . 36 5.4.1. Critical/Elective . . . . . . . . . . . . . . . . . . 37
5.4.2. Proxy Unsafe/Safe-to-Forward and NoCacheKey . . . . . 37 5.4.2. Proxy Unsafe or Safe-to-Forward and NoCacheKey . . . 38
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 . . . . . . . . . . . . . . . . . 39
5.4.6. Option Numbers . . . . . . . . . . . . . . . . . . . 38 5.4.6. Option Numbers . . . . . . . . . . . . . . . . . . . 39
5.5. Payloads and Representations . . . . . . . . . . . . . . 39 5.5. Payloads and Representations . . . . . . . . . . . . . . 40
5.5.1. Representation . . . . . . . . . . . . . . . . . . . 39 5.5.1. Representation . . . . . . . . . . . . . . . . . . . 40
5.5.2. Diagnostic Payload . . . . . . . . . . . . . . . . . 40 5.5.2. Diagnostic Payload . . . . . . . . . . . . . . . . . 41
5.5.3. Selected Representation . . . . . . . . . . . . . . . 40 5.5.3. Selected Representation . . . . . . . . . . . . . . . 41
5.5.4. Content Negotiation . . . . . . . . . . . . . . . . . 40 5.5.4. Content Negotiation . . . . . . . . . . . . . . . . . 41
5.6. Caching . . . . . . . . . . . . . . . . . . . . . . . . . 41 5.6. Caching . . . . . . . . . . . . . . . . . . . . . . . . . 42
5.6.1. Freshness Model . . . . . . . . . . . . . . . . . . . 42 5.6.1. Freshness Model . . . . . . . . . . . . . . . . . . . 43
5.6.2. Validation Model . . . . . . . . . . . . . . . . . . 42 5.6.2. Validation Model . . . . . . . . . . . . . . . . . . 43
5.7. Proxying . . . . . . . . . . . . . . . . . . . . . . . . 43 5.7. Proxying . . . . . . . . . . . . . . . . . . . . . . . . 44
5.7.1. Proxy Operation . . . . . . . . . . . . . . . . . . . 43 5.7.1. Proxy Operation . . . . . . . . . . . . . . . . . . . 44
5.7.2. Forward-Proxies . . . . . . . . . . . . . . . . . . . 45 5.7.2. Forward-Proxies . . . . . . . . . . . . . . . . . . . 46
5.7.3. Reverse-Proxies . . . . . . . . . . . . . . . . . . . 45 5.7.3. Reverse-Proxies . . . . . . . . . . . . . . . . . . . 46
5.8. Method Definitions . . . . . . . . . . . . . . . . . . . 46 5.8. Method Definitions . . . . . . . . . . . . . . . . . . . 47
5.8.1. GET . . . . . . . . . . . . . . . . . . . . . . . . . 46 5.8.1. GET . . . . . . . . . . . . . . . . . . . . . . . . . 47
5.8.2. POST . . . . . . . . . . . . . . . . . . . . . . . . 46 5.8.2. POST . . . . . . . . . . . . . . . . . . . . . . . . 47
5.8.3. PUT . . . . . . . . . . . . . . . . . . . . . . . . . 46 5.8.3. PUT . . . . . . . . . . . . . . . . . . . . . . . . . 48
5.8.4. DELETE . . . . . . . . . . . . . . . . . . . . . . . 47 5.8.4. DELETE . . . . . . . . . . . . . . . . . . . . . . . 48
5.9. Response Code Definitions . . . . . . . . . . . . . . . . 47 5.9. Response Code Definitions . . . . . . . . . . . . . . . . 48
5.9.1. Success 2.xx . . . . . . . . . . . . . . . . . . . . 47 5.9.1. Success 2.xx . . . . . . . . . . . . . . . . . . . . 48
5.9.2. Client Error 4.xx . . . . . . . . . . . . . . . . . . 49 5.9.2. Client Error 4.xx . . . . . . . . . . . . . . . . . . 50
5.9.3. Server Error 5.xx . . . . . . . . . . . . . . . . . . 50 5.9.3. Server Error 5.xx . . . . . . . . . . . . . . . . . . 51
5.10. Option Definitions . . . . . . . . . . . . . . . . . . . 51 5.10. Option Definitions . . . . . . . . . . . . . . . . . . . 52
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 . . . . 53
5.10.2. Proxy-Uri and Proxy-Scheme . . . . . . . . . . . . . 53 5.10.2. Proxy-Uri and Proxy-Scheme . . . . . . . . . . . . . 54
5.10.3. Content-Format . . . . . . . . . . . . . . . . . . . 53 5.10.3. Content-Format . . . . . . . . . . . . . . . . . . . 55
5.10.4. Accept . . . . . . . . . . . . . . . . . . . . . . . 54 5.10.4. Accept . . . . . . . . . . . . . . . . . . . . . . . 55
5.10.5. Max-Age . . . . . . . . . . . . . . . . . . . . . . 54 5.10.5. Max-Age . . . . . . . . . . . . . . . . . . . . . . 55
5.10.6. ETag . . . . . . . . . . . . . . . . . . . . . . . . 54 5.10.6. ETag . . . . . . . . . . . . . . . . . . . . . . . . 56
5.10.7. Location-Path and Location-Query . . . . . . . . . . 55 5.10.7. Location-Path and Location-Query . . . . . . . . . . 57
5.10.8. Conditional Request Options . . . . . . . . . . . . 56 5.10.8. Conditional Request Options . . . . . . . . . . . . 57
5.10.9. Size1 Option . . . . . . . . . . . . . . . . . . . . 57 5.10.9. Size1 Option . . . . . . . . . . . . . . . . . . . . 59
6. CoAP URIs . . . . . . . . . . . . . . . . . . . . . . . . . . 57 6. CoAP URIs . . . . . . . . . . . . . . . . . . . . . . . . . . 59
6.1. coap URI Scheme . . . . . . . . . . . . . . . . . . . . . 58 6.1. coap URI Scheme . . . . . . . . . . . . . . . . . . . . . 59
6.2. coaps URI Scheme . . . . . . . . . . . . . . . . . . . . 59 6.2. coaps URI Scheme . . . . . . . . . . . . . . . . . . . . 60
6.3. Normalization and Comparison Rules . . . . . . . . . . . 59 6.3. Normalization and Comparison Rules . . . . . . . . . . . 61
6.4. Decomposing URIs into Options . . . . . . . . . . . . . . 60 6.4. Decomposing URIs into Options . . . . . . . . . . . . . . 61
6.5. Composing URIs from Options . . . . . . . . . . . . . . . 61 6.5. Composing URIs from Options . . . . . . . . . . . . . . . 62
7. Discovery . . . . . . . . . . . . . . . . . . . . . . . . . . 62 7. Discovery . . . . . . . . . . . . . . . . . . . . . . . . . . 64
7.1. Service Discovery . . . . . . . . . . . . . . . . . . . . 62 7.1. Service Discovery . . . . . . . . . . . . . . . . . . . . 64
7.2. Resource Discovery . . . . . . . . . . . . . . . . . . . 63 7.2. Resource Discovery . . . . . . . . . . . . . . . . . . . 64
7.2.1. 'ct' Attribute . . . . . . . . . . . . . . . . . . . 63 7.2.1. 'ct' Attribute . . . . . . . . . . . . . . . . . . . 64
8. Multicast CoAP . . . . . . . . . . . . . . . . . . . . . . . 64 8. Multicast CoAP . . . . . . . . . . . . . . . . . . . . . . . 65
8.1. Messaging Layer . . . . . . . . . . . . . . . . . . . . . 64 8.1. Messaging Layer . . . . . . . . . . . . . . . . . . . . . 65
8.2. Request/Response Layer . . . . . . . . . . . . . . . . . 65 8.2. Request/Response Layer . . . . . . . . . . . . . . . . . 66
8.2.1. Caching . . . . . . . . . . . . . . . . . . . . . . . 66 8.2.1. Caching . . . . . . . . . . . . . . . . . . . . . . . 67
8.2.2. Proxying . . . . . . . . . . . . . . . . . . . . . . 66 8.2.2. Proxying . . . . . . . . . . . . . . . . . . . . . . 67
9. Securing CoAP . . . . . . . . . . . . . . . . . . . . . . . . 66 9. Securing CoAP . . . . . . . . . . . . . . . . . . . . . . . . 68
9.1. DTLS-secured CoAP . . . . . . . . . . . . . . . . . . . . 68 9.1. DTLS-Secured CoAP . . . . . . . . . . . . . . . . . . . . 69
9.1.1. Messaging Layer . . . . . . . . . . . . . . . . . . . 69 9.1.1. Messaging Layer . . . . . . . . . . . . . . . . . . . 70
9.1.2. Request/Response Layer . . . . . . . . . . . . . . . 69 9.1.2. Request/Response Layer . . . . . . . . . . . . . . . 71
9.1.3. Endpoint Identity . . . . . . . . . . . . . . . . . . 70 9.1.3. Endpoint Identity . . . . . . . . . . . . . . . . . . 71
10. Cross-Protocol Proxying between CoAP and HTTP . . . . . . . . 73 10. Cross-Protocol Proxying between CoAP and HTTP . . . . . . . . 74
10.1. CoAP-HTTP Proxying . . . . . . . . . . . . . . . . . . . 74 10.1. CoAP-HTTP Proxying . . . . . . . . . . . . . . . . . . . 75
10.1.1. GET . . . . . . . . . . . . . . . . . . . . . . . . 74 10.1.1. GET . . . . . . . . . . . . . . . . . . . . . . . . 76
10.1.2. PUT . . . . . . . . . . . . . . . . . . . . . . . . 75 10.1.2. PUT . . . . . . . . . . . . . . . . . . . . . . . . 77
10.1.3. DELETE . . . . . . . . . . . . . . . . . . . . . . . 75 10.1.3. DELETE . . . . . . . . . . . . . . . . . . . . . . . 77
10.1.4. POST . . . . . . . . . . . . . . . . . . . . . . . . 75 10.1.4. POST . . . . . . . . . . . . . . . . . . . . . . . . 77
10.2. HTTP-CoAP Proxying . . . . . . . . . . . . . . . . . . . 76 10.2. HTTP-CoAP Proxying . . . . . . . . . . . . . . . . . . . 77
10.2.1. OPTIONS and TRACE . . . . . . . . . . . . . . . . . 76 10.2.1. OPTIONS and TRACE . . . . . . . . . . . . . . . . . 78
10.2.2. GET . . . . . . . . . . . . . . . . . . . . . . . . 76 10.2.2. GET . . . . . . . . . . . . . . . . . . . . . . . . 78
10.2.3. HEAD . . . . . . . . . . . . . . . . . . . . . . . . 77 10.2.3. HEAD . . . . . . . . . . . . . . . . . . . . . . . . 79
10.2.4. POST . . . . . . . . . . . . . . . . . . . . . . . . 77 10.2.4. POST . . . . . . . . . . . . . . . . . . . . . . . . 79
10.2.5. PUT . . . . . . . . . . . . . . . . . . . . . . . . 78 10.2.5. PUT . . . . . . . . . . . . . . . . . . . . . . . . 79
10.2.6. DELETE . . . . . . . . . . . . . . . . . . . . . . . 78 10.2.6. DELETE . . . . . . . . . . . . . . . . . . . . . . . 80
10.2.7. CONNECT . . . . . . . . . . . . . . . . . . . . . . 78 10.2.7. CONNECT . . . . . . . . . . . . . . . . . . . . . . 80
11. Security Considerations . . . . . . . . . . . . . . . . . . . 78 11. Security Considerations . . . . . . . . . . . . . . . . . . . 80
11.1. Protocol Parsing, Processing URIs . . . . . . . . . . . 78 11.1. Parsing the Protocol and Processing URIs . . . . . . . . 80
11.2. Proxying and Caching . . . . . . . . . . . . . . . . . . 79 11.2. Proxying and Caching . . . . . . . . . . . . . . . . . . 81
11.3. Risk of amplification . . . . . . . . . . . . . . . . . 80 11.3. Risk of Amplification . . . . . . . . . . . . . . . . . 81
11.4. IP Address Spoofing Attacks . . . . . . . . . . . . . . 81 11.4. IP Address Spoofing Attacks . . . . . . . . . . . . . . 83
11.5. Cross-Protocol Attacks . . . . . . . . . . . . . . . . . 82 11.5. Cross-Protocol Attacks . . . . . . . . . . . . . . . . . 84
11.6. Constrained node considerations . . . . . . . . . . . . 84 11.6. Constrained-Node Considerations . . . . . . . . . . . . 86
12. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 84 12. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 86
12.1. CoAP Code Registries . . . . . . . . . . . . . . . . . . 84 12.1. CoAP Code Registries . . . . . . . . . . . . . . . . . . 86
12.1.1. Method Codes . . . . . . . . . . . . . . . . . . . . 85 12.1.1. Method Codes . . . . . . . . . . . . . . . . . . . . 87
12.1.2. Response Codes . . . . . . . . . . . . . . . . . . . 85 12.1.2. Response Codes . . . . . . . . . . . . . . . . . . . 88
12.2. Option Number Registry . . . . . . . . . . . . . . . . . 87 12.2. CoAP Option Numbers Registry . . . . . . . . . . . . . . 89
12.3. Content-Format Registry . . . . . . . . . . . . . . . . 89 12.3. CoAP Content-Formats Registry . . . . . . . . . . . . . 91
12.4. URI Scheme Registration . . . . . . . . . . . . . . . . 90 12.4. URI Scheme Registration . . . . . . . . . . . . . . . . 93
12.5. Secure URI Scheme Registration . . . . . . . . . . . . . 91 12.5. Secure URI Scheme Registration . . . . . . . . . . . . . 94
12.6. Service Name and Port Number Registration . . . . . . . 92 12.6. Service Name and Port Number Registration . . . . . . . 95
12.7. Secure Service Name and Port Number Registration . . . . 93 12.7. Secure Service Name and Port Number Registration . . . . 96
12.8. Multicast Address Registration . . . . . . . . . . . . . 94 12.8. Multicast Address Registration . . . . . . . . . . . . . 97
13. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 94 13. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 97
14. References . . . . . . . . . . . . . . . . . . . . . . . . . 95 14. References . . . . . . . . . . . . . . . . . . . . . . . . . 98
14.1. Normative References . . . . . . . . . . . . . . . . . . 95 14.1. Normative References . . . . . . . . . . . . . . . . . . 98
14.2. Informative References . . . . . . . . . . . . . . . . . 97 14.2. Informative References . . . . . . . . . . . . . . . . . 100
Appendix A. Examples . . . . . . . . . . . . . . . . . . . . . . 100 Appendix A. Examples . . . . . . . . . . . . . . . . . . . . . . 104
Appendix B. URI Examples . . . . . . . . . . . . . . . . . . . . 105 Appendix B. URI Examples . . . . . . . . . . . . . . . . . . . . 110
Appendix C. Changelog . . . . . . . . . . . . . . . . . . . . . 107
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 117
1. Introduction 1. Introduction
The use of web services (web APIs) on the Internet has become The use of web services (web APIs) on the Internet has become
ubiquitous in most applications, and depends on the fundamental ubiquitous in most applications and depends on the fundamental
Representational State Transfer [REST] architecture of the web. Representational State Transfer [REST] architecture of the Web.
The Constrained RESTful Environments (CoRE) work aims at realizing The work on Constrained RESTful Environments (CoRE) 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, this causes 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
but optimized for M2M applications. Although CoAP could be used for but optimized for M2M applications. Although CoAP could be used for
refashioning simple HTTP interfaces into a more compact protocol, it refashioning simple HTTP interfaces into a more compact protocol,
more importantly also offers features for M2M such as built-in more importantly it also offers features for M2M such as built-in
discovery, multicast support and asynchronous message exchanges. discovery, multicast support, and asynchronous message exchanges.
This document specifies the Constrained Application Protocol (CoAP), This document specifies the Constrained Application Protocol (CoAP),
which easily translates to HTTP for integration with the existing web which easily translates to HTTP for integration with the existing Web
while meeting specialized requirements such as multicast support, while meeting specialized requirements such as multicast support,
very low overhead and simplicity for constrained environments and M2M very low overhead, and simplicity for constrained environments and
applications. M2M applications.
1.1. Features 1.1. Features
CoAP has the following main features: CoAP has the following main features:
o Constrained web protocol fulfilling M2M requirements. o Web protocol fulfilling M2M requirements in constrained
environments
o UDP [RFC0768] binding with optional reliability supporting unicast o UDP [RFC0768] binding with optional reliability supporting unicast
and multicast requests. and multicast requests.
o Asynchronous message exchanges. o Asynchronous message exchanges.
o Low header overhead and parsing complexity. o Low header overhead and parsing complexity.
o URI and Content-type support. o URI and Content-type support.
skipping to change at page 6, line 20 skipping to change at page 6, line 18
o Security binding to Datagram Transport Layer Security (DTLS) o Security binding to Datagram Transport Layer Security (DTLS)
[RFC6347]. [RFC6347].
1.2. Terminology 1.2. Terminology
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
"SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and
"OPTIONAL" in this document are to be interpreted as described in "OPTIONAL" in this document are to be interpreted as described in
[RFC2119] when they appear in ALL CAPS. These words may also appear [RFC2119] when they appear in ALL CAPS. These words may also appear
in this document in lower case as plain English words, absent their in this document in lowercase, absent their normative meanings.
normative meanings.
This specification requires readers to be familiar with all the terms This specification requires readers to be familiar with all the terms
and concepts that are discussed in [RFC2616], including "resource", and concepts that are discussed in [RFC2616], including "resource",
"representation", "cache", and "fresh". In addition, this "representation", "cache", and "fresh". (Having been completed
specification defines the following terminology: before the updated set of HTTP RFCs, RFC 7230 to RFC 7235, became
available, this specification specifically references the predecessor
version -- RFC 2616.) In addition, this specification defines the
following terminology:
Endpoint Endpoint
An entity participating in the CoAP protocol. Colloquially, an An entity participating in the CoAP protocol. Colloquially, an
endpoint lives on a "Node", although "Host" would be more endpoint lives on a "Node", although "Host" would be more
consistent with Internet standards usage, and is further consistent with Internet standards usage, and is further
identified by transport layer multiplexing information that can identified by transport-layer multiplexing information that can
include a UDP port number and a security association include a UDP port number and a security association
(Section 4.1). (Section 4.1).
Sender Sender
The originating endpoint of a message. When the aspect of The originating endpoint of a message. When the aspect of
identification of the specific sender is in focus, also "source identification of the specific sender is in focus, also "source
endpoint". endpoint".
Recipient Recipient
The destination endpoint of a message. When the aspect of The destination endpoint of a message. When the aspect of
skipping to change at page 7, line 10 skipping to change at page 7, line 10
Server Server
The destination endpoint of a request; the originating endpoint of The destination endpoint of a request; the originating endpoint of
a response. a response.
Origin Server Origin Server
The server on which a given resource resides or is to be created. The server on which a given resource resides or is to be created.
Intermediary Intermediary
A CoAP endpoint that acts both as a server and as a client towards A CoAP endpoint that acts both as a server and as a client towards
(possibly via further intermediaries) an origin server. A common an origin server (possibly via further intermediaries). A common
form of an intermediary is a proxy; several classes of such form of an intermediary is a proxy; several classes of such
proxies are discussed in this specification. proxies are discussed in this specification.
Proxy Proxy
An intermediary that mainly is concerned with forwarding requests An intermediary that mainly is concerned with forwarding requests
and relaying back responses, possibly performing caching, and relaying back responses, possibly performing caching,
namespace translation, or protocol translation in the process. As namespace translation, or protocol translation in the process. As
opposed to intermediaries in the general sense, proxies generally opposed to intermediaries in the general sense, proxies generally
do not implement specific application semantics. Based on the do not implement specific application semantics. Based on the
position in the overall structure of the request forwarding, there position in the overall structure of the request forwarding, there
are two common forms of proxy: forward-proxy and reverse-proxy. are two common forms of proxy: forward-proxy and reverse-proxy.
In some cases, a single endpoint might act as an origin server, In some cases, a single endpoint might act as an origin server,
forward-proxy, or reverse-proxy, switching behavior based on the forward-proxy, or reverse-proxy, switching behavior based on the
nature of each request. nature of each request.
Forward-Proxy Forward-Proxy
A "forward-proxy" is an endpoint selected by a client, usually via An endpoint selected by a client, usually via local configuration
local configuration rules, to perform requests on behalf of the rules, to perform requests on behalf of the client, doing any
client, doing any necessary translations. Some translations are necessary translations. Some translations are minimal, such as
minimal, such as for proxy requests for "coap" URIs, whereas other for proxy requests for "coap" URIs, whereas other requests might
requests might require translation to and from entirely different require translation to and from entirely different application-
application-layer protocols. layer protocols.
Reverse-Proxy Reverse-Proxy
A "reverse-proxy" is an endpoint that stands in for one or more An endpoint that stands in for one or more other server(s) and
other server(s) and satisfies requests on behalf of these, doing satisfies requests on behalf of these, doing any necessary
any necessary translations. Unlike a forward-proxy, the client translations. Unlike a forward-proxy, the client may not be aware
may not be aware that it is communicating with a reverse-proxy; a that it is communicating with a reverse-proxy; a reverse-proxy
reverse-proxy receives requests as if it was the origin server for receives requests as if it were the origin server for the target
the target resource. resource.
CoAP-to-CoAP Proxy CoAP-to-CoAP Proxy
A proxy that maps from a CoAP request to a CoAP request, i.e. A proxy that maps from a CoAP request to a CoAP request, i.e.,
uses the CoAP protocol both on the server and the client side. 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.
skipping to change at page 8, line 21 skipping to change at page 8, line 21
Non-confirmable Message Non-confirmable Message
Some other messages do not require an acknowledgement. This is Some other messages do not require an acknowledgement. This is
particularly true for messages that are repeated regularly for particularly true for messages that are repeated regularly for
application requirements, such as repeated readings from a sensor. application requirements, such as repeated readings from a sensor.
Acknowledgement Message Acknowledgement Message
An Acknowledgement message acknowledges that a specific An Acknowledgement message acknowledges that a specific
Confirmable message arrived. By itself, an Acknowledgement Confirmable message arrived. By itself, an Acknowledgement
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 Piggybacked Response (see below).
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 Piggybacked Response
A Piggy-backed Response is included right in a CoAP A piggybacked Response is included right in a CoAP Acknowledgement
Acknowledgement (ACK) message that is sent to acknowledge receipt (ACK) message that is sent to acknowledge receipt of the Request
of the Request for this Response (Section 5.2.1). 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 Empty Message
A message with a Code of 0.00; neither a request nor a response. A message with a Code of 0.00; neither a request nor a response.
An Empty message only contains the four-byte header. An Empty message only contains the 4-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 9, line 25 skipping to change at page 9, line 30
the message in order to safely forward the message the message in order to safely forward the message
(Section 5.4.2). Not every critical option is an unsafe option. (Section 5.4.2). Not every critical option is an unsafe option.
Safe-to-Forward Option Safe-to-Forward Option
An option that is intended to be safe for forwarding by a proxy An option that is intended to be safe for forwarding by a proxy
that does not understand it. Forwarding the message even without that does not understand it. Forwarding the message even without
understanding the option is acceptable (Section 5.4.2). understanding the option is acceptable (Section 5.4.2).
Resource Discovery Resource Discovery
The process where a CoAP client queries a server for its list of The process where a CoAP client queries a server for its list of
hosted resources (i.e., links, Section 7). hosted resources (i.e., links as defined in Section 7).
Content-Format Content-Format
The combination of an Internet media type, potentially with The combination of an Internet media type, potentially with
specific parameters given, and a content-coding (which is often specific parameters given, and a content-coding (which is often
the identity content-coding), identified by a numeric identifier the identity content-coding), identified by a numeric identifier
defined by the CoAP Content-Format Registry. When the focus is defined by the "CoAP Content-Formats" registry. When the focus is
less on the numeric identifier than on the combination of these less on the numeric identifier than on the combination of these
characteristics of a resource representation, this is also called characteristics of a resource representation, this is also called
"representation format". "representation format".
Additional terminology for constrained nodes and constrained node Additional terminology for constrained nodes and constrained-node
networks can be found in [I-D.ietf-lwig-terminology]. networks can be found in [RFC7228].
In this specification, the term "byte" is used in its now customary In this specification, the term "byte" is used in its now customary
sense as a synonym for "octet". sense as a synonym for "octet".
All multi-byte integers in this protocol are interpreted in network All multi-byte integers in this protocol are interpreted in network
byte order. byte order.
Where arithmetic is used, this specification uses the notation Where arithmetic is used, this specification uses the notation
familiar from the programming language C, except that the operator familiar from the programming language C, except that the operator
"**" stands for exponentiation. "**" stands for exponentiation.
2. Constrained Application Protocol 2. Constrained Application Protocol
The interaction model of CoAP is similar to the client/server model The interaction model of CoAP is similar to the client/server model
of HTTP. However, machine-to-machine interactions typically result of HTTP. However, machine-to-machine interactions typically result
in a CoAP implementation acting in both client and server roles. A in a CoAP implementation acting in both client and server roles. A
CoAP request is equivalent to that of HTTP, and is sent by a client CoAP request is equivalent to that of HTTP and is sent by a client to
to request an action (using a method code) on a resource (identified request an action (using a Method Code) on a resource (identified by
by a URI) on a server. The server then sends a response with a a URI) on a server. The server then sends a response with a Response
response code; this response may include a resource representation. Code; this response may include a resource representation.
Unlike HTTP, CoAP deals with these interchanges asynchronously over a Unlike HTTP, CoAP deals with these interchanges asynchronously over a
datagram-oriented transport such as UDP. This is done logically datagram-oriented transport such as UDP. This is done logically
using a layer of messages that supports optional reliability (with using a layer of messages that supports optional reliability (with
exponential back-off). CoAP defines four types of messages: exponential back-off). CoAP defines four types of messages:
Confirmable, Non-confirmable, Acknowledgement, Reset; method codes Confirmable, Non-confirmable, Acknowledgement, Reset. Method Codes
and response codes included in some of these messages make them carry and Response Codes included in some of these messages make them carry
requests or responses. The basic exchanges of the four types of requests or responses. The basic exchanges of the four types of
messages are somewhat orthogonal to the request/response messages are somewhat orthogonal to the request/response
interactions; requests can be carried in Confirmable and Non- interactions; requests can be carried in Confirmable and Non-
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 piggybacked 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 as just features
the CoAP header. of the CoAP header.
+----------------------+ +----------------------+
| Application | | Application |
+----------------------+ +----------------------+
+----------------------+ \ +----------------------+ \
| Requests/Responses | | | Requests/Responses | |
|----------------------| | CoAP |----------------------| | CoAP
| Messages | | | Messages | |
+----------------------+ / +----------------------+ /
+----------------------+ +----------------------+
| UDP | | UDP |
+----------------------+ +----------------------+
Figure 1: Abstract layering of CoAP Figure 1: Abstract Layering of CoAP
2.1. Messaging Model 2.1. Messaging Model
The CoAP messaging model is based on the exchange of messages over The CoAP messaging model is based on the exchange of messages over
UDP between endpoints. UDP between endpoints.
CoAP uses a short fixed-length binary header (4 bytes) that may be CoAP uses a short fixed-length binary header (4 bytes) that may be
followed by compact binary options and a payload. This message followed by compact binary options and a payload. This message
format is shared by requests and responses. The CoAP message format format is shared by requests and responses. The CoAP message format
is specified in Section 3. Each message contains a Message ID used is specified in Section 3. Each message contains a Message ID used
skipping to change at page 11, line 19 skipping to change at page 11, line 29
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.
Several security modes are defined for CoAP in Section 9 ranging from Several security modes are defined for CoAP in Section 9 ranging from
no security to certificate-based security. This document specifies a no security to certificate-based security. This document specifies a
binding to DTLS for securing the protocol; the use of IPsec with CoAP binding to DTLS for securing the protocol; the use of IPsec with CoAP
is discussed in [I-D.bormann-core-ipsec-for-coap]. is discussed in [IPsec-CoAP].
2.2. Request/Response Model 2.2. Request/Response Model
CoAP request and response semantics are carried in CoAP messages, CoAP request and response semantics are carried in CoAP messages,
which include either a Method code or Response code, respectively. which include either a Method Code or Response Code, respectively.
Optional (or default) request and response information, such as the Optional (or default) request and response information, such as the
URI and payload media type are carried as CoAP options. A Token is URI and payload media type are carried as CoAP options. A Token is
used to match responses to requests independently from the underlying used to match responses to requests independently from the underlying
messages (Section 5.3). (Note that the Token is a concept separate messages (Section 5.3). (Note that the Token is a concept separate
from the Message ID.) from the Message ID.)
A request is carried in a Confirmable (CON) or Non-confirmable (NON) A request is carried in a Confirmable (CON) or Non-confirmable (NON)
message, and if immediately available, the response to a request message, and, if immediately available, the response to a request
carried in a Confirmable message is carried in the resulting carried in a Confirmable message is carried in the resulting
Acknowledgement (ACK) message. This is called a piggy-backed Acknowledgement (ACK) message. This is called a piggybacked
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 piggybacked 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 piggybacked response is lost.) Two examples for a basic GET request
with piggy-backed response are shown in Figure 4, one successful, one with piggybacked 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 Piggybacked 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 Request and a Response Carried in Non-confirmable
Messages
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 [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 status codes with a few CoAP-specific codes
codes added, as defined in Section 5.9. added, as defined in Section 5.9.
2.3. Intermediaries and Caching 2.3. Intermediaries and Caching
The protocol supports the caching of responses in order to The protocol supports the caching of responses in order to
efficiently fulfill requests. Simple caching is enabled using efficiently fulfill requests. Simple caching is enabled using
freshness and validity information carried with CoAP responses. A freshness and validity information carried with CoAP responses. A
cache could be located in an endpoint or an intermediary. Caching cache could be located in an endpoint or an intermediary. Caching
functionality is specified in Section 5.6. functionality is specified in Section 5.6.
Proxying is useful in constrained networks for several reasons, Proxying is useful in constrained networks for several reasons,
including network traffic limiting, to improve performance, to access including to limit network traffic, to improve performance, to access
resources of sleeping devices or for security reasons. The proxying resources of sleeping devices, and for security reasons. The
of requests on behalf of another CoAP endpoint is supported in the proxying of requests on behalf of another CoAP endpoint is supported
protocol. When using a proxy, the URI of the resource to request is in the protocol. When using a proxy, the URI of the resource to
included in the request, while the destination IP address is set to request is included in the request, while the destination IP address
the address of the proxy. See Section 5.7 for more information on is set to the address of the proxy. See Section 5.7 for more
proxy functionality. information on proxy functionality.
As CoAP was designed according to the REST architecture [REST] and As CoAP was designed according to the REST architecture [REST], and
thus exhibits functionality similar to that of the HTTP protocol, it thus exhibits functionality similar to that of the HTTP protocol, it
is quite straightforward to map from CoAP to HTTP and from HTTP to is quite straightforward to map from CoAP to HTTP and from HTTP to
CoAP. Such a mapping may be used to realize an HTTP REST interface CoAP. Such a mapping may be used to realize an HTTP REST interface
using CoAP, or for converting between HTTP and CoAP. This conversion using CoAP or to convert between HTTP and CoAP. This conversion can
can be carried out by a cross-protocol proxy ("cross-proxy"), which be carried out by a cross-protocol proxy ("cross-proxy"), which
converts the method or response code, media type, and options to the converts the Method or Response Code, media type, and options to the
corresponding HTTP feature. Section 10 provides more detail about corresponding HTTP feature. Section 10 provides more detail about
HTTP mapping. HTTP mapping.
2.4. Resource Discovery 2.4. Resource Discovery
Resource discovery is important for machine-to-machine interactions, Resource discovery is important for machine-to-machine interactions
and is supported using the CoRE Link Format [RFC6690] as discussed in and is supported using the CoRE Link Format [RFC6690] as discussed in
Section 7. Section 7.
3. Message Format 3. Message Format
CoAP is based on the exchange of compact messages which, by default, CoAP is based on the exchange of compact messages that, 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
Options in Type-Length-Value (TLV) format, optionally followed by a Options in Type-Length-Value (TLV) format, optionally followed by a
payload which takes up the rest of the datagram. payload that takes up the rest of the datagram.
0 1 2 3 0 1 2 3
0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|Ver| T | TKL | Code | Message ID | |Ver| T | TKL | Code | Message ID |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Token (if any, TKL bytes) ... | Token (if any, TKL bytes) ...
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Options (if any) ... | Options (if any) ...
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|1 1 1 1 1 1 1 1| Payload (if any) ... |1 1 1 1 1 1 1 1| Payload (if any) ...
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
skipping to change at page 16, line 14 skipping to change at page 16, line 31
Figure 7: Message Format Figure 7: Message Format
The fields in the header are defined as follows: The fields in the header are defined as follows:
Version (Ver): 2-bit unsigned integer. Indicates the CoAP version Version (Ver): 2-bit unsigned integer. Indicates the CoAP version
number. Implementations of this specification MUST set this field number. Implementations of this specification MUST set this field
to 1 (01 binary). Other values are reserved for future versions. to 1 (01 binary). Other values are reserved for future versions.
Messages with unknown version numbers MUST be silently ignored. Messages with unknown version numbers MUST be silently ignored.
Type (T): 2-bit unsigned integer. Indicates if this message is of Type (T): 2-bit unsigned integer. Indicates if this message is of
type Confirmable (0), Non-confirmable (1), Acknowledgement (2) or type Confirmable (0), Non-confirmable (1), Acknowledgement (2), or
Reset (3). The semantics of these message types are defined in Reset (3). The semantics of these message types are defined in
Section 4. Section 4.
Token Length (TKL): 4-bit unsigned integer. Indicates the length of Token Length (TKL): 4-bit unsigned integer. Indicates the length of
the variable-length Token field (0-8 bytes). Lengths 9-15 are the variable-length Token field (0-8 bytes). Lengths 9-15 are
reserved, MUST NOT be sent, and MUST be processed as a message reserved, MUST NOT be sent, and MUST be processed as a message
format error. format error.
Code: 8-bit unsigned integer, 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
subfield and dd are two digits from 00 to 31 for the 5-bit 3-bit subfield and "dd" are two digits from 00 to 31 for the 5-bit
subfield. The class can indicate a request (0), a success subfield. The class can indicate a request (0), a success
response (2), a client error response (4), or a server error response (2), a client error response (4), or a server error
response (5). (All other class values are reserved.) As a response (5). (All other class values are reserved.) As a
special case, Code 0.00 indicates an Empty message. In case of a special case, Code 0.00 indicates an Empty message. In case of a
request, the Code field indicates the Request Method; in case of a request, the Code field indicates the Request Method; in case of a
response a Response Code. Possible values are maintained in the response, a Response Code. Possible values are maintained in the
CoAP Code Registries (Section 12.1). The semantics of requests CoAP Code Registries (Section 12.1). The semantics of requests
and responses are defined in Section 5. 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 to
the detection of message duplication, and to match messages of detect message duplication and to match messages of type
type Acknowledgement/Reset to messages of type Confirmable/Non- Acknowledgement/Reset to messages of type Confirmable/Non-
confirmable. The rules for generating a Message ID and matching confirmable. The rules for generating a Message ID and 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.
Following the header, token, and options, if any, comes the optional Following the header, token, and options, if any, comes the optional
payload. If present and of non-zero length, it is prefixed by a payload. If present and of non-zero length, it is prefixed by a
fixed, one-byte Payload Marker (0xFF) which indicates the end of fixed, one-byte Payload Marker (0xFF), which indicates the end of
options and the start of the payload. The payload data extends from options and the start of the payload. The payload data extends from
after the marker to the end of the UDP datagram, i.e., the Payload after the marker to the end of the UDP datagram, i.e., the Payload
Length is calculated from the datagram size. The absence of the Length is calculated from the datagram size. The absence of the
Payload Marker denotes a zero-length payload. The presence of a Payload Marker denotes a zero-length payload. The presence of a
marker followed by a zero-length payload MUST be processed as a marker followed by a zero-length payload MUST be processed as a
message format error. message format error.
Implementation Note: The byte value 0xFF may also occur within an Implementation Note: The byte value 0xFF may also occur within an
option length or value, so simple byte-wise scanning for 0xFF is option length or value, so simple byte-wise scanning for 0xFF is
not a viable technique for finding the payload marker. The byte not a viable technique for finding the payload marker. The byte
0xFF has the meaning of a payload marker only where the beginning 0xFF has the meaning of a payload marker only where the beginning
of another option could occur. of another option could occur.
3.1. Option Format 3.1. Option Format
CoAP defines a number of options which can be included in a message. CoAP defines a number of options that can be included in a message.
Each option instance in a message specifies the Option Number of the Each option instance in a message specifies the Option Number of the
defined CoAP option, the length of the Option Value and the Option defined CoAP option, the length of the Option Value, and the Option
Value itself. Value itself.
Instead of specifying the Option Number directly, the instances MUST Instead of specifying the Option Number directly, the instances MUST
appear in order of their Option Numbers and a delta encoding is used appear in order of their Option Numbers and a delta encoding is used
between them: The Option Number for each instance is calculated as between them: the Option Number for each instance is calculated as
the sum of its delta and the Option Number of the preceding instance the sum of its delta and the Option Number of the preceding instance
in the message. For the first instance in a message, a preceding in the message. For the first instance in a message, a preceding
option instance with Option Number zero is assumed. Multiple option instance with Option Number zero is assumed. Multiple
instances of the same option can be included by using a delta of instances of the same option can be included by using a delta of
zero. zero.
Option Numbers are maintained in the CoAP Option Number Registry Option Numbers are maintained in the "CoAP Option Numbers" registry
(Section 12.2). See Section 5.4 for the semantics of the options (Section 12.2). See Section 5.4 for the semantics of the options
defined in this document. defined in this document.
0 1 2 3 4 5 6 7 0 1 2 3 4 5 6 7
+---------------+---------------+ +---------------+---------------+
| | | | | |
| Option Delta | Option Length | 1 byte | Option Delta | Option Length | 1 byte
| | | | | |
+---------------+---------------+ +---------------+---------------+
\ \ \ \
skipping to change at page 18, line 23 skipping to change at page 18, line 40
+-------------------------------+ +-------------------------------+
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 15: Reserved for the Payload Marker. If the field is set to this
this value but the entire byte is not the payload marker, value but the entire byte is not the payload marker, this MUST
this MUST be processed as a message format error. 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
value formats. value formats.
empty: A zero-length sequence of bytes. empty: A zero-length sequence of bytes.
opaque: An opaque sequence of bytes. opaque: An opaque sequence of bytes.
uint: A non-negative integer which is represented in network byte uint: A non-negative integer that is represented in network byte
order using the number of bytes given by the Option Length order using the number of bytes given by the Option Length
field. field.
An option definition may specify a range of permissible An option definition may specify a range of permissible
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 constrained, for the sender is intended for highly constrained,
templated implementations (e.g., hardware templated implementations (e.g., hardware
implementations) that use fixed size options in the implementations) that use fixed-size options in the
templates. templates.
string: A Unicode string which is encoded using UTF-8 [RFC3629] in string: A Unicode string that 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
is used in the CoAP protocol, the intention is that the encoding is used in the CoAP protocol, the intention is
encoded strings can be directly used and compared as opaque that the encoded strings can be directly used and compared
byte strings by CoAP protocol implementations. There is no as opaque byte strings by CoAP protocol implementations.
expectation and no need to perform normalization within a There is no expectation and no need to perform
CoAP implementation (except where Unicode strings that are normalization within a CoAP implementation (except where
not known to be normalized are imported from sources Unicode strings that are not known to be normalized are
outside the CoAP protocol). Note also that ASCII strings imported from sources outside the CoAP protocol). Note
(that do not make use of special control characters) are also that ASCII strings (that do not make use of special
always valid UTF-8 Net-Unicode strings. control characters) are always valid UTF-8 Net-Unicode
strings.
4. Message Transmission 4. Message Transmission
CoAP messages are exchanged asynchronously between CoAP endpoints. CoAP messages are exchanged asynchronously between CoAP endpoints.
They are used to transport CoAP requests and responses, the semantics They are used to transport CoAP requests and responses, the semantics
of which are defined in Section 5. of which are defined in Section 5.
As CoAP is bound to non-reliable transports such as UDP, CoAP As CoAP is bound to unreliable transports such as UDP, CoAP messages
messages may arrive out of order, appear duplicated, or go missing may arrive out of order, appear duplicated, or go missing without
without notice. For this reason, CoAP implements a lightweight notice. For this reason, CoAP implements a lightweight reliability
reliability mechanism, without trying to re-create the full feature mechanism, without trying to re-create the full feature set of a
set of a transport like TCP. It has the following features: transport like TCP. It has the following features:
o Simple stop-and-wait retransmission reliability with exponential o Simple stop-and-wait retransmission reliability with exponential
back-off for Confirmable messages. back-off for Confirmable messages.
o Duplicate detection for both Confirmable and Non-confirmable o Duplicate detection for both Confirmable and Non-confirmable
messages. messages.
4.1. Messages and Endpoints 4.1. Messages and Endpoints
A CoAP endpoint is the source or destination of a CoAP message. The A CoAP endpoint is the source or destination of a CoAP message. The
skipping to change at page 20, line 52 skipping to change at page 21, line 24
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 either (a) acknowledge a Confirmable message with an
message or, if it lacks context to process the message properly Acknowledgement message or (b) reject the message if the recipient
(including the case where the message is Empty, uses a code with a lacks context to process the message properly, including situations
reserved class (1, 6 or 7), or has a message format error), MUST where the message is Empty, uses a code with a reserved class (1, 6,
reject it; rejecting a Confirmable message is effected by sending a or 7), or has a message format error. Rejecting a Confirmable
matching Reset message and otherwise ignoring it. The message is effected by sending a matching Reset message and otherwise
Acknowledgement message MUST echo the Message ID of the Confirmable ignoring it. The Acknowledgement message MUST echo the Message ID of
message, and MUST carry a response or be Empty (see Section 5.2.1 and the Confirmable message and MUST carry a response or be Empty (see
Section 5.2.2). The Reset message MUST echo the Message ID of the Sections 5.2.1 and 5.2.2). The Reset message MUST echo the Message
Confirmable message, and MUST be Empty. Rejecting an Acknowledgement ID of the Confirmable message and MUST be Empty. Rejecting an
or Reset message (including the case where the Acknowledgement Acknowledgement or Reset message (including the case where the
carries a request or a code with a reserved class, or the Reset Acknowledgement carries a request or a code with a reserved class, or
message is not Empty) is effected by silently ignoring it. More the Reset message is not Empty) is effected by silently ignoring it.
generally, recipients of Acknowledgement and Reset messages MUST NOT More generally, recipients of Acknowledgement and Reset messages MUST
respond with either Acknowledgement or Reset messages. NOT respond with either Acknowledgement or Reset messages.
The sender retransmits the Confirmable message at exponentially The sender retransmits the Confirmable message at exponentially
increasing intervals, until it receives an acknowledgement (or Reset increasing intervals, until it receives an acknowledgement (or Reset
message), or runs out of attempts. message) or runs out of attempts.
Retransmission is controlled by two things that a CoAP endpoint MUST Retransmission is controlled by two things that a CoAP endpoint MUST
keep track of for each Confirmable message it sends while waiting for keep track of for each Confirmable message it sends while waiting for
an acknowledgement (or reset): a timeout and a retransmission an acknowledgement (or reset): a timeout and a retransmission
counter. For a new Confirmable message, the initial timeout is set counter. For a new Confirmable message, the initial timeout is set
to a random 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 back-off
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 may catch up on the next
next one. However, the minimum spacing before another retransmission one. However, the minimum spacing before another retransmission is
is ACK_TIMEOUT, and the entire sequence of (re-)transmissions MUST ACK_TIMEOUT, and the entire sequence of (re-)transmissions MUST stay
stay in the envelope of MAX_TRANSMIT_SPAN (see Section 4.8.2), even in the envelope of MAX_TRANSMIT_SPAN (see Section 4.8.2), even if
if that means a sender may miss an opportunity to transmit. 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. For example, the application has canceled the
it no longer needs a response, or there is some other indication that request as it no longer needs a response, or there is some other
the CON message did arrive. In particular, a CoAP request message indication that the CON message did arrive. In particular, a CoAP
may have elicited a separate response, in which case it is clear to request message may have elicited a separate response, in which case
the requester that only the ACK was lost and a retransmission of the it is clear to the requester that only the ACK was lost and a
request would serve no purpose. However, a responder MUST NOT in retransmission of the request would serve no purpose. However, a
turn rely on this cross-layer behavior from a requester, i.e. it responder MUST NOT in turn rely on this cross-layer behavior from a
MUST retain the state to create the ACK for the request, if needed, requester, i.e., it MUST retain the state to create the ACK for the
even if a Confirmable response was already acknowledged by the request, if needed, even if a Confirmable response was already
requester. 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
ignored if the implementation note in Section 4.6 is followed; ignored if the implementation note in Section 4.6 is followed;
otherwise, they SHOULD feed into a path MTU discovery algorithm otherwise, they SHOULD feed into a path MTU discovery algorithm
[RFC4821]. Source Quench and Time Exceeded ICMP messages SHOULD be [RFC4821]. Source Quench and Time Exceeded ICMP messages SHOULD be
ignored. Host, network, port or protocol unreachable errors, or ignored. Host, network, port, or protocol unreachable errors or
parameter problem errors MAY, after appropriate vetting, be used to parameter problem errors MAY, after appropriate vetting, be used to
inform the application of a failure in sending. inform the application of a failure in sending.
4.3. Messages Transmitted Without Reliability 4.3. Messages Transmitted without Reliability
Some messages do not require an acknowledgement. This is Some messages do not require an acknowledgement. This is
particularly true for messages that are repeated regularly for particularly true for messages that are repeated regularly for
application requirements, such as repeated readings from a sensor application requirements, such as repeated readings from a sensor
where eventual success is sufficient. where eventual success is sufficient.
As a more lightweight alternative, a message can be transmitted less As a more lightweight alternative, a message can be transmitted less
reliably by marking the message as Non-confirmable. A Non- reliably by marking the message as Non-confirmable. A Non-
confirmable message always carries either a request or response and confirmable message always carries either a request or response and
MUST NOT be Empty. A Non-confirmable message MUST NOT be MUST NOT be Empty. A Non-confirmable message MUST NOT be
acknowledged by the recipient. If a recipient lacks context to acknowledged by the recipient. A recipient MUST reject the message
process the message properly (including the case where the message is if it lacks context to process the message properly, including the
Empty, uses a code with a reserved class (1, 6 or 7), or has a case where the message is Empty, uses a code with a reserved class
message format error), it MUST reject the message; rejecting a Non- (1, 6, or 7), or has a message format error. 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 Sections 4.2 and 4.3, the four message types can be used
be used as in Table 1. "*" means that the combination is not used in as in Table 1. "*" means that the combination is not used in normal
normal operation, but only to elicit a Reset message ("CoAP ping"). 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 |
+----------+-----+-----+-----+-----+ +----------+-----+-----+-----+-----+
Table 1: Usage of message types Table 1: Usage of Message Types
4.4. Message Correlation 4.4. Message Correlation
An Acknowledgement or Reset message is related to a Confirmable An Acknowledgement or Reset message is related to a Confirmable
message or Non-confirmable message by means of a Message ID along message or Non-confirmable message by means of a Message ID along
with additional address information of the corresponding endpoint. with additional address information of the corresponding endpoint.
The Message ID is a 16-bit unsigned integer that is generated by the The Message ID is a 16-bit unsigned integer that is generated by the
sender of a Confirmable or Non-confirmable message and included in sender of a Confirmable or Non-confirmable message and included in
the CoAP header. The Message ID MUST be echoed in the the CoAP header. The Message ID MUST be echoed in the
Acknowledgement or Reset message by the recipient. Acknowledgement or Reset message by the recipient.
The same Message ID MUST NOT be re-used (in communicating with the The same Message ID MUST NOT be reused (in communicating with the
same endpoint) within the EXCHANGE_LIFETIME (Section 4.8.2). same endpoint) within the EXCHANGE_LIFETIME (Section 4.8.2).
Implementation Note: Several implementation strategies can be Implementation Note: Several implementation strategies can be
employed for generating Message IDs. In the simplest case a CoAP employed for generating Message IDs. In the simplest case, a CoAP
endpoint generates Message IDs by keeping a single Message ID endpoint generates Message IDs by keeping a single Message ID
variable, which is changed each time a new Confirmable or Non- variable, which is changed each time a new Confirmable or Non-
confirmable message is sent regardless of the destination address confirmable message is sent, regardless of the destination address
or port. Endpoints dealing with large numbers of transactions or port. Endpoints dealing with large numbers of transactions
could keep multiple Message ID variables, for example per prefix could keep multiple Message ID variables, for example, per prefix
or destination address (note that some receiving endpoints may not or destination address. (Note that some receiving endpoints may
be able to distinguish unicast and multicast packets addressed to not be able to distinguish unicast and multicast packets addressed
it, so endpoints generating Message IDs need to make sure these do to it, so endpoints generating Message IDs need to make sure these
not overlap). It is strongly recommended that the initial value do not overlap.) It is strongly recommended that the initial
of the variable (e.g., on startup) be randomized, in order to make value of the variable (e.g., on startup) be randomized, in order
successful off-path attacks on the protocol less likely. to make successful off-path attacks on the protocol less likely.
For an Acknowledgement or Reset message to match a Confirmable or For an Acknowledgement or Reset message to match a Confirmable or
Non-confirmable message, the Message ID and source endpoint of the Non-confirmable message, the Message ID and source endpoint of the
Acknowledgement or Reset message MUST match the Message ID and Acknowledgement or Reset message MUST match the Message ID and
destination endpoint of the Confirmable or Non-confirmable message. destination endpoint of the Confirmable or Non-confirmable message.
4.5. Message Deduplication 4.5. Message Deduplication
A recipient might receive the same Confirmable message (as indicated A recipient might receive the same Confirmable message (as indicated
by the Message ID and source endpoint) multiple times within the by the Message ID and source endpoint) multiple times within the
EXCHANGE_LIFETIME (Section 4.8.2), for example, when its EXCHANGE_LIFETIME (Section 4.8.2), for example, when its
Acknowledgement went missing or didn't reach the original sender Acknowledgement went missing or didn't reach the original sender
before the first timeout. The recipient SHOULD acknowledge each before the first timeout. The recipient SHOULD acknowledge each
duplicate copy of a Confirmable message using the same duplicate copy of a Confirmable message using the same
Acknowledgement or Reset message, but SHOULD process any request or Acknowledgement or Reset message but SHOULD process any request or
response in the message only once. This rule MAY be relaxed in case response in the message only once. This rule MAY be relaxed in case
the Confirmable message transports a request that is idempotent (see the Confirmable message transports a request that is idempotent (see
Section 5.1) or can be handled in an idempotent fashion. Examples Section 5.1) or can be handled in an idempotent fashion. Examples
for relaxed message deduplication: for relaxed message deduplication:
o A server might relax the requirement to answer all retransmissions o A server might relax the requirement to answer all retransmissions
of an idempotent request with the same response (Section 4.2), so of an idempotent request with the same response (Section 4.2), so
that it does not have to maintain state for Message IDs. For that it does not have to maintain state for Message IDs. For
example, an implementation might want to process duplicate example, an implementation might want to process duplicate
transmissions of a GET, PUT or DELETE request as separate requests transmissions of a GET, PUT, or DELETE request as separate
if the effort incurred by duplicate processing is less expensive requests if the effort incurred by duplicate processing is less
than keeping track of previous responses would be. expensive than keeping track of previous responses would be.
o A constrained server might even want to relax this requirement for o A constrained server might even want to relax this requirement for
certain non-idempotent requests if the application semantics make certain non-idempotent requests if the application semantics make
this trade-off favorable. For example, if the result of a POST this trade-off favorable. For example, if the result of a POST
request is just the creation of some short-lived state at the request is just the creation of some short-lived state at the
server, it may be less expensive to incur this effort multiple server, it may be less expensive to incur this effort multiple
times for a request than keeping track of whether a previous times for a request than keeping track of whether a previous
transmission of the same request already was processed. transmission of the same request already was processed.
A recipient might receive the same Non-confirmable message (as A recipient might receive the same Non-confirmable message (as
indicated by the Message ID and source endpoint) multiple times indicated by the Message ID and source endpoint) multiple times
within NON_LIFETIME (Section 4.8.2). As a general rule that MAY be within NON_LIFETIME (Section 4.8.2). As a general rule that MAY be
relaxed based on the specific semantics of a message, the recipient relaxed based on the specific semantics of a message, the recipient
SHOULD silently ignore any duplicated Non-confirmable message, and SHOULD silently ignore any duplicated Non-confirmable message and
SHOULD process any request or response in the message only once. SHOULD process any request or response in the message only once.
4.6. Message Size 4.6. Message Size
While specific link layers make it beneficial to keep CoAP messages While specific link layers make it beneficial to keep CoAP messages
small enough to fit into their link layer packets (see Section 1), small enough to fit into their link-layer packets (see Section 1),
this is a matter of implementation quality. The CoAP specification this is a matter of implementation quality. The CoAP specification
itself provides only an upper bound to the message size. Messages itself provides only an upper bound to the message size. Messages
larger than an IP packet result in undesirable packet fragmentation. larger than an IP packet result in undesirable packet fragmentation.
A CoAP message, appropriately encapsulated, SHOULD fit within a A CoAP message, appropriately encapsulated, SHOULD fit within a
single IP packet (i.e., avoid IP fragmentation) and (by fitting into single IP packet (i.e., avoid IP fragmentation) and (by fitting into
one UDP payload) obviously needs to fit within a single IP datagram. one UDP payload) obviously needs to fit within a single IP datagram.
If the Path MTU is not known for a destination, an IP MTU of 1280 If the Path MTU is not known for a destination, an IP MTU of 1280
bytes SHOULD be assumed; if nothing is known about the size of the bytes SHOULD be assumed; if nothing is known about the size of the
headers, good upper bounds are 1152 bytes for the message size and headers, good upper bounds are 1152 bytes for the message size and
1024 bytes for the payload size. 1024 bytes for the payload size.
Implementation Note: CoAP's choice of message size parameters works Implementation Note: CoAP's choice of message size parameters works
well with IPv6 and with most of today's IPv4 paths. (However, well with IPv6 and with most of today's IPv4 paths. (However,
with IPv4, it is harder to absolutely ensure that there is no IP with IPv4, it is harder to absolutely ensure that there is no IP
fragmentation. If IPv4 support on unusual networks is a fragmentation. If IPv4 support on unusual networks is a
consideration, implementations may want to limit themselves to consideration, implementations may want to limit themselves to
more conservative IPv4 datagram sizes such as 576 bytes; worse, more conservative IPv4 datagram sizes such as 576 bytes; per
the absolute minimum value of the IP MTU for IPv4 is as low as 68 [RFC0791], the absolute minimum value of the IP MTU for IPv4 is as
bytes, which would leave only 40 bytes minus security overhead for low as 68 bytes, which would leave only 40 bytes minus security
a UDP payload. Implementations extremely focused on this problem overhead for a UDP payload. Implementations extremely focused on
set might also set the IPv4 DF bit and perform some form of path this problem set might also set the IPv4 DF bit and perform some
MTU discovery [RFC4821]; this should generally be unnecessary in form of path MTU discovery [RFC4821]; this should generally be
most realistic use cases for CoAP, however.) A more important unnecessary in realistic use cases for CoAP, however.) A more
kind of fragmentation in many constrained networks is that on the important kind of fragmentation in many constrained networks is
adaptation layer (e.g., 6LoWPAN L2 packets are limited to 127 that on the adaptation layer (e.g., 6LoWPAN L2 packets are limited
bytes including various overheads); this may motivate to 127 bytes including various overheads); this may motivate
implementations to be frugal in their packet sizes and to move to implementations to be frugal in their packet sizes and to move to
block-wise transfers [I-D.ietf-core-block] when approaching three- block-wise transfers [BLOCK] when approaching three-digit message
digit message sizes. sizes.
Message sizes are also of considerable importance to Message sizes are also of considerable importance to
implementations on constrained nodes. Many implementations will implementations on constrained nodes. Many implementations will
need to allocate a buffer for incoming messages. If an need to allocate a buffer for incoming messages. If an
implementation is too constrained to allow for allocating the implementation is too constrained to allow for allocating the
above-mentioned upper bound, it could apply the following above-mentioned upper bound, it could apply the following
implementation strategy for messages not using DTLS security: implementation strategy for messages not using DTLS security:
Implementations receiving a datagram into a buffer that is too Implementations receiving a datagram into a buffer that is too
small are usually able to determine if the trailing portion of a small are usually able to determine if the trailing portion of a
datagram was discarded and to retrieve the initial portion. So, datagram was discarded and to retrieve the initial portion. So,
if not all of the payload, at least the CoAP header and options at least the CoAP header and options, if not all of the payload,
are likely to fit within the buffer. A server can thus fully are likely to fit within the buffer. A server can thus fully
interpret a request and return a 4.13 (Request Entity Too Large, interpret a request and return a 4.13 (Request Entity Too Large;
see Section 5.9.2.9) response code if the payload was truncated. see Section 5.9.2.9) Response Code if the payload was truncated.
A client sending an idempotent request and receiving a response A client sending an idempotent request and receiving a response
larger than would fit in the buffer can repeat the request with a larger than would fit in the buffer can repeat the request with a
suitable value for the Block Option [I-D.ietf-core-block]. suitable value for the Block Option [BLOCK].
4.7. Congestion Control 4.7. Congestion Control
Basic congestion control for CoAP is provided by the exponential Basic congestion control for CoAP is provided by the exponential
back-off mechanism in Section 4.2. back-off mechanism in Section 4.2.
In order not to cause congestion, Clients (including proxies) MUST In order not to cause congestion, clients (including proxies) MUST
strictly limit the number of simultaneous outstanding interactions strictly limit the number of simultaneous outstanding interactions
that they maintain to a given server (including proxies) to NSTART. that they maintain to a given server (including proxies) to NSTART.
An outstanding interaction is either a CON for which an ACK has not An outstanding interaction is either a CON for which an ACK has not
yet been received but is still expected (message layer) or a request yet been received but is still expected (message layer) or a request
for which neither a response nor an Acknowledgment message has yet for which neither a response nor an Acknowledgment message has yet
been received but is still expected (which may both occur at the same been received but is still expected (which may both occur at the same
time, counting as one outstanding interaction). The default value of time, counting as one outstanding interaction). The default value of
NSTART for this specification is 1. NSTART for this specification is 1.
Further congestion control optimizations and considerations are Further congestion control optimizations and considerations are
expected in the future, which may for example provide automatic expected in the future, may for example provide automatic
initialization of the CoAP transmission parameters defined in initialization of the CoAP transmission parameters defined in
Section 4.8, and thus may allow a value for NSTART greater than one. Section 4.8, and thus may allow a value for NSTART greater than one.
A client stops expecting a response to a Confirmable request for After EXCHANGE_LIFETIME, a client stops expecting a response to a
which no acknowledgment message was received, after Confirmable request for which no acknowledgment message was received.
EXCHANGE_LIFETIME. The specific algorithm by which a client stops to
"expect" a response to a Confirmable request that was acknowledged, The specific algorithm by which a client stops to "expect" a response
or to a Non-confirmable request, is not defined. Unless this is to a Confirmable request that was acknowledged, or to a Non-
modified by additional congestion control optimizations, it MUST be confirmable request, is not defined. Unless this is modified by
chosen in such a way that an endpoint does not exceed an average data additional congestion control optimizations, it MUST be chosen in
rate of PROBING_RATE in sending to another endpoint that does not such a way that an endpoint does not exceed an average data rate of
respond. PROBING_RATE in sending to another endpoint that does not 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:
+-------------------+---------------+ +-------------------+---------------+
| name | default value | | name | default value |
+-------------------+---------------+ +-------------------+---------------+
| ACK_TIMEOUT | 2 seconds | | ACK_TIMEOUT | 2 seconds |
| ACK_RANDOM_FACTOR | 1.5 | | ACK_RANDOM_FACTOR | 1.5 |
| MAX_RETRANSMIT | 4 | | MAX_RETRANSMIT | 4 |
| NSTART | 1 | | NSTART | 1 |
| DEFAULT_LEISURE | 5 seconds | | DEFAULT_LEISURE | 5 seconds |
| PROBING_RATE | 1 Byte/second | | PROBING_RATE | 1 byte/second |
+-------------------+---------------+ +-------------------+---------------+
Table 2: CoAP Protocol Parameters Table 2: CoAP Protocol Parameters
4.8.1. Changing The Parameters 4.8.1. Changing the Parameters
The values for ACK_TIMEOUT, ACK_RANDOM_FACTOR, MAX_RETRANSMIT, The values for ACK_TIMEOUT, ACK_RANDOM_FACTOR, MAX_RETRANSMIT,
NSTART, DEFAULT_LEISURE (Section 8.2), and PROBING_RATE may be NSTART, DEFAULT_LEISURE (Section 8.2), and PROBING_RATE may be
configured to values specific to the application environment configured to values specific to the application environment
(including dynamically adjusted values), however the configuration (including dynamically adjusted values); however, the configuration
method is out of scope of this document. It is RECOMMENDED that an method is out of scope of this document. It is RECOMMENDED that an
application environment use consistent values for these parameters; application environment use consistent values for these parameters;
the specific effects of operating with inconsistent values in an the specific effects of operating with inconsistent values in an
application environment are outside the scope of the present application environment are outside the scope of the present
specification. specification.
The transmission parameters have been chosen to achieve a behavior in The transmission parameters have been chosen to achieve a behavior in
the presence of congestion that is safe in the Internet. If a the presence of congestion that is safe in the Internet. If a
configuration desires to use different values, the onus is on the configuration desires to use different values, the onus is on the
configuration to ensure these congestion control properties are not configuration to ensure these congestion control properties are not
violated. In particular, a decrease of ACK_TIMEOUT below 1 second violated. In particular, a decrease of ACK_TIMEOUT below 1 second
would violate the guidelines of [RFC5405]. would violate the guidelines of [RFC5405]. ([RTO-CONSIDER] provides
([I-D.allman-tcpm-rto-consider] provides some additional background.) some additional background.) CoAP was designed to enable
CoAP was designed to enable implementations that do not maintain implementations that do not maintain round-trip-time (RTT)
round-trip-time (RTT) measurements. However, where it is desired to measurements. However, where it is desired to decrease the
decrease the ACK_TIMEOUT significantly or increase NSTART, this can ACK_TIMEOUT significantly or increase NSTART, this can only be done
only be done safely when maintaining such measurements. safely when maintaining such measurements. Configurations MUST NOT
Configurations MUST NOT decrease ACK_TIMEOUT or increase NSTART decrease ACK_TIMEOUT or increase NSTART without using mechanisms that
without using mechanisms that ensure congestion control safety, ensure congestion control safety, either defined in the configuration
either defined in the configuration or in future standards documents. or in future standards documents.
ACK_RANDOM_FACTOR MUST NOT be decreased below 1.0, and it SHOULD have ACK_RANDOM_FACTOR MUST NOT be decreased below 1.0, and it SHOULD have
a value that is sufficiently different from 1.0 to provide some a value that is sufficiently different from 1.0 to provide some
protection from synchronization effects. protection from synchronization effects.
MAX_RETRANSMIT can be freely adjusted, but a too small value will MAX_RETRANSMIT can be freely adjusted, but a value that is too small
reduce the probability that a Confirmable message is actually will reduce the probability that a Confirmable message is actually
received, while a larger value than given here will require further received, while a larger value than given here will require further
adjustments in the time values (see Section 4.8.2). adjustments in the time values (see Section 4.8.2).
If the choice of transmission parameters leads to an increase of If the choice of transmission parameters leads to an increase of
derived time values (see Section 4.8.2), the configuration mechanism derived time values (see Section 4.8.2), the configuration mechanism
MUST ensure the adjusted value is also available to all the endpoints MUST ensure the adjusted value is also available to all the endpoints
that these adjusted values are to be used to communicate with. with which these adjusted values are to be used to communicate.
4.8.2. Time Values derived from Transmission Parameters 4.8.2. Time Values Derived from Transmission Parameters
The combination of ACK_TIMEOUT, ACK_RANDOM_FACTOR and MAX_RETRANSMIT The combination of ACK_TIMEOUT, ACK_RANDOM_FACTOR, and MAX_RETRANSMIT
influences the timing of retransmissions, which in turn influences influences the timing of retransmissions, which in turn influences
how long certain information items need to be kept by an how long certain information items need to be kept by an
implementation. To be able to unambiguously reference these derived implementation. To be able to unambiguously reference these derived
time values, we give them names as follows: time values, we give them names as follows:
o MAX_TRANSMIT_SPAN is the maximum time from the first transmission o MAX_TRANSMIT_SPAN is the maximum time from the first transmission
of a Confirmable message to its last retransmission. For the of a Confirmable message to its last retransmission. For the
default transmission parameters, the value is (2+4+8+16)*1.5 = 45 default transmission parameters, the value is (2+4+8+16)*1.5 = 45
seconds, or more generally: seconds, or more generally:
skipping to change at page 28, line 39 skipping to change at page 29, line 24
In addition, some assumptions need to be made on the characteristics In addition, some assumptions need to be made on the characteristics
of the network and the nodes. of the network and the nodes.
o MAX_LATENCY is the maximum time a datagram is expected to take o MAX_LATENCY is the maximum time a datagram is expected to take
from the start of its transmission to the completion of its from the start of its transmission to the completion of its
reception. This constant is related to the MSL (Maximum Segment reception. This constant is related to the MSL (Maximum Segment
Lifetime) of [RFC0793], which is "arbitrarily defined to be 2 Lifetime) of [RFC0793], which is "arbitrarily defined to be 2
minutes" ([RFC0793] glossary, page 81). Note that this is not minutes" ([RFC0793] glossary, page 81). Note that this is not
necessarily smaller than MAX_TRANSMIT_WAIT, as MAX_LATENCY is not necessarily smaller than MAX_TRANSMIT_WAIT, as MAX_LATENCY is not
intended to describe a situation when the protocol works well, but intended to describe a situation when the protocol works well, but
the worst case situation against which the protocol has to guard. the worst-case situation against which the protocol has to guard.
We, also arbitrarily, define MAX_LATENCY to be 100 seconds. Apart We, also arbitrarily, define MAX_LATENCY to be 100 seconds. Apart
from being reasonably realistic for the bulk of configurations as from being reasonably realistic for the bulk of configurations as
well as close to the historic choice for TCP, this value also well as close to the historic choice for TCP, this value also
allows Message ID lifetime timers to be represented in 8 bits allows Message ID lifetime timers to be represented in 8 bits
(when measured in seconds). In these calculations, there is no (when measured in seconds). In these calculations, there is no
assumption that the direction of the transmission is irrelevant assumption that the direction of the transmission is irrelevant
(i.e. that the network is symmetric), just that the same value (i.e., that the network is symmetric); there is just the
can reasonably be used as a maximum value for both directions. If assumption that the same value can reasonably be used as a maximum
that is not the case, the following calculations become only value for both directions. If that is not the case, the following
slightly more complex. calculations become only 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:
MAX_TRANSMIT_SPAN + (2 * MAX_LATENCY) + PROCESSING_DELAY MAX_TRANSMIT_SPAN + (2 * MAX_LATENCY) + PROCESSING_DELAY
or 247 seconds with the default transmission parameters. or 247 seconds with the default transmission parameters.
o NON_LIFETIME is the time from sending a Non-confirmable message to o NON_LIFETIME is the time from sending a Non-confirmable message to
the time its Message ID can be safely reused. If multiple the time its Message ID can be safely reused. If multiple
transmission of a NON message is not used, its value is transmission of a NON message is not used, its value is
MAX_LATENCY, or 100 seconds. However, a CoAP sender might send a MAX_LATENCY, or 100 seconds. However, a CoAP sender might send a
NON message multiple times, in particular for multicast NON message multiple times, in particular for multicast
applications. While the period of re-use is not bounded by the applications. While the period of reuse is not bounded by the
specification, an expectation of reliable detection of duplication specification, an expectation of reliable detection of duplication
at the receiver is in the timescales of MAX_TRANSMIT_SPAN. at the receiver is on the timescales of MAX_TRANSMIT_SPAN.
Therefore, for this purpose, it is safer to use the value: Therefore, for this purpose, it is safer to use the value:
MAX_TRANSMIT_SPAN + MAX_LATENCY MAX_TRANSMIT_SPAN + MAX_LATENCY
or 145 seconds with the default transmission parameters; however, or 145 seconds with the default transmission parameters; however,
an implementation that just wants to use a single timeout value an implementation that just wants to use a single timeout value
for retiring Message IDs can safely use the larger value for for retiring Message IDs can safely use the larger value for
EXCHANGE_LIFETIME. EXCHANGE_LIFETIME.
Table 3 summarizes the derived parameters introduced in this Table 3 lists the derived parameters introduced in this subsection
subsection with their default values. with their default values.
+-------------------+---------------+ +-------------------+---------------+
| name | default value | | name | default value |
+-------------------+---------------+ +-------------------+---------------+
| MAX_TRANSMIT_SPAN | 45 s | | MAX_TRANSMIT_SPAN | 45 s |
| MAX_TRANSMIT_WAIT | 93 s | | MAX_TRANSMIT_WAIT | 93 s |
| MAX_LATENCY | 100 s | | MAX_LATENCY | 100 s |
| PROCESSING_DELAY | 2 s | | PROCESSING_DELAY | 2 s |
| MAX_RTT | 202 s | | MAX_RTT | 202 s |
| EXCHANGE_LIFETIME | 247 s | | EXCHANGE_LIFETIME | 247 s |
skipping to change at page 30, line 25 skipping to change at page 31, line 11
+-------------------+---------------+ +-------------------+---------------+
Table 3: Derived Protocol Parameters Table 3: Derived Protocol Parameters
5. Request/Response Semantics 5. Request/Response Semantics
CoAP operates under a similar request/response model as HTTP: a CoAP CoAP operates under a similar request/response model as HTTP: a CoAP
endpoint in the role of a "client" sends one or more CoAP requests to endpoint in the role of a "client" sends one or more CoAP requests to
a "server", which services the requests by sending CoAP responses. a "server", which services the requests by sending CoAP responses.
Unlike HTTP, requests and responses are not sent over a previously Unlike HTTP, requests and responses are not sent over a previously
established connection, but exchanged asynchronously over CoAP established connection but are exchanged asynchronously over CoAP
messages. messages.
5.1. Requests 5.1. Requests
A CoAP request consists of the method to be applied to the resource, A CoAP request consists of the method to be applied to the resource,
the identifier of the resource, a payload and Internet media type (if the identifier of the resource, a payload and Internet media type (if
any), and optional meta-data about the request. any), and optional metadata about the request.
CoAP supports the basic methods of GET, POST, PUT, DELETE, which are CoAP supports the basic methods of GET, POST, PUT, and DELETE, which
easily mapped to HTTP. They have the same properties of safe (only are easily mapped to HTTP. They have the same properties of safe
retrieval) and idempotent (you can invoke it multiple times with the (only retrieval) and idempotent (you can invoke it multiple times
same effects) as HTTP (see Section 9.1 of [RFC2616]). The GET method with the same effects) as HTTP (see Section 9.1 of [RFC2616]). The
is safe, therefore it MUST NOT take any other action on a resource GET method is safe; therefore, it MUST NOT take any other action on a
other than retrieval. The GET, PUT and DELETE methods MUST be resource other than retrieval. The GET, PUT, and DELETE methods MUST
performed in such a way that they are idempotent. POST is not be performed in such a way that they are idempotent. POST is not
idempotent, because its effect is determined by the origin server and idempotent, because its effect is determined by the origin server and
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.
skipping to change at page 31, line 4 skipping to change at page 31, line 38
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 that 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
documented in the format "c.dd", where "c" is the class in decimal, documented in the format "c.dd", where "c" is the class in decimal,
and "dd" is the detail as a two-digit decimal. For example, and "dd" is the detail as a two-digit decimal. For example,
"Forbidden" is written as 4.03 -- indicating an 8-bit code value of "Forbidden" is written as 4.03 -- indicating an 8-bit code value of
hexadecimal 0x83 (4*0x20+3) or decimal 131 (4*32+3). hexadecimal 0x83 (4*0x20+3) or decimal 131 (4*32+3).
There are 3 classes of response codes: There are 3 classes of Response Codes:
2 - Success: The request was successfully received, understood, and 2 - Success: The request was successfully received, understood, and
accepted. accepted.
4 - Client Error: The request contains bad syntax or cannot be 4 - Client Error: The request contains bad syntax or cannot be
fulfilled. fulfilled.
5 - Server Error: The server failed to fulfill an apparently valid 5 - Server Error: The server failed to fulfill an apparently valid
request. request.
The response codes are designed to be extensible: Response Codes in The Response Codes are designed to be extensible: Response Codes in
the Client Error and Server Error class that are unrecognized by an the Client Error or Server Error class that are unrecognized by an
endpoint are treated as being equivalent to the generic Response Code endpoint are treated as being equivalent to the generic Response Code
of that class (4.00 and 5.00, respectively). However, there is no of that class (4.00 and 5.00, respectively). However, there is no
generic Response Code indicating success, so a Response Code in the generic Response Code indicating success, so a Response Code in the
Success class that is unrecognized by an endpoint can only be used to Success class that is unrecognized by an endpoint can only be used to
determine that the request was successful without any further determine that the request was successful without any further
details. details.
The possible response codes are described in detail in Section 5.9. The possible Response Codes are described in detail in Section 5.9.
Responses can be sent in multiple ways, which are defined in the Responses can be sent in multiple ways, which are defined in the
following subsections. following subsections.
5.2.1. Piggy-backed 5.2.1. Piggybacked
In the most basic case, the response is carried directly in the In the most basic case, the response is carried directly in the
Acknowledgement message that acknowledges the request (which requires Acknowledgement message that acknowledges the request (which requires
that the request was carried in a Confirmable message). This is that the request was carried in a Confirmable message). This is
called a "Piggy-backed" Response. called a "Piggybacked Response".
The response is returned in the Acknowledgement message independent The response is returned in the Acknowledgement message, independent
of whether the response indicates success or failure. In effect, the of whether the response indicates success or failure. In effect, the
response is piggy-backed on the Acknowledgement message, and no response is piggybacked on the Acknowledgement message, and no
separate message is required to return the response. separate message is required to return the response.
Implementation Note: The protocol leaves the decision whether to Implementation Note: The protocol leaves the decision whether to
piggy-back a response or not (i.e., send a separate response) to piggyback a response or not (i.e., send a separate response) to
the server. The client MUST be prepared to receive either. On the server. The client MUST be prepared to receive either. On
the quality of implementation level, there is a strong expectation the quality-of-implementation level, there is a strong expectation
that servers will implement code to piggy-back whenever possible that servers will implement code to piggyback whenever possible --
-- saving resources in the network and both at the client and at saving resources in the network and both at the client and at the
the server. server.
5.2.2. Separate 5.2.2. Separate
It may not be possible to return a piggy-backed response in all It may not be possible to return a piggybacked response in all cases.
cases. For example, a server might need longer to obtain the For example, a server might need longer to obtain the representation
representation of the resource requested than it can wait sending of the resource requested than it can wait to send back the
back the Acknowledgement message, without risking the client to Acknowledgement message, without risking the client repeatedly
repeatedly retransmit the request message (see also the discussion of retransmitting the request message (see also the discussion of
PROCESSING_DELAY in Section 4.8.2). The Response to a request PROCESSING_DELAY in Section 4.8.2). The response to a request
carried in a Non-confirmable message is always sent separately (as carried in a Non-confirmable message is always sent separately (as
there is no Acknowledgement message). there is no Acknowledgement message).
One way to implement this in a server is to initiate the attempt to One way to implement this in a server is to initiate the attempt to
obtain the resource representation and, while that is in progress, obtain the resource representation and, while that is in progress,
time out an acknowledgement timer. A server may also immediately time out an acknowledgement timer. A server may also immediately
send an acknowledgement knowing in advance that there will be no send an acknowledgement if it knows in advance that there will be no
piggy-backed response. In both cases, the acknowledgement piggybacked response. In both cases, the acknowledgement effectively
effectively is a promise that the request will be acted upon later. 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
does not make any specific demands here, there is an expectation does not make any specific demands here, there is an expectation
that the response will come within a time frame that is reasonable that the response will come within a time frame that is reasonable
from an application point of view; as there is no underlying from an application point of view. As there is no underlying
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.
skipping to change at page 34, line 4 skipping to change at page 34, line 40
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 that the server MUST echo (without
resulting response without modification. modification) in any resulting response.
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 piggybacked 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 nontrivial, 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 the
opaque and make no assumptions about its content or structure. token as opaque and make no assumptions about its content or
structure.
5.3.2. Request/Response Matching Rules 5.3.2. Request/Response Matching Rules
The exact rules for matching a response to a request are as follows: The exact rules for matching a response to a request are as follows:
1. The source endpoint of the response MUST be the same as the 1. The source endpoint of the response MUST be the same as the
destination endpoint of the original request. destination endpoint of the original request.
2. In a piggy-backed response, both the Message ID of the 2. In a piggybacked response, the Message ID of the Confirmable
Confirmable request and the Acknowledgement, and the token of the request and the Acknowledgement MUST match, and the tokens of the
response and original request MUST match. In a separate response and original request MUST match. In a separate
response, just the token of the response and original request response, just the tokens of the response and original request
MUST match. MUST match.
In case a message carrying a response is unexpected (the client is In case a message carrying a response is unexpected (the client is
not waiting for a response from the identified endpoint, at the not waiting for a response from the identified endpoint, at the
endpoint addressed, and/or with the given token), the response is endpoint addressed, and/or with the given token), the response is
rejected (Section 4.2, Section 4.3). rejected (Sections 4.2 and 4.3).
Implementation Note: A client that receives a response in a CON Implementation Note: A client that receives a response in a CON
message may want to clean up the message state right after sending message may want to clean up the message state right after sending
the ACK. If that ACK is lost and the server retransmits the CON, the ACK. If that ACK is lost and the server retransmits the CON,
the client may no longer have any state to correlate this response the client may no longer have any state to which to correlate this
to, making the retransmission an unexpected message; the client response, making the retransmission an unexpected message; the
will likely send a Reset message so it does not receive any more client will likely send a Reset message so it does not receive any
retransmissions. This behavior is normal and not an indication of more retransmissions. This behavior is normal and not an
an error. (Clients that are not aggressively optimized in their indication of an error. (Clients that are not aggressively
state memory usage will still have message state that will optimized in their state memory usage will still have message
identify the second CON as a retransmission. Clients that state that will identify the second CON as a retransmission.
actually expect more messages from the server Clients that actually expect more messages from the server
[I-D.ietf-core-observe] will have to keep state in any case.) [OBSERVE] will have to keep state in any case.)
5.4. Options 5.4. Options
Both requests and responses may include a list of one or more Both requests and responses may include a list of one or more
options. For example, the URI in a request is transported in several options. For example, the URI in a request is transported in several
options, and meta-data that would be carried in an HTTP header in options, and metadata that would be carried in an HTTP header in HTTP
HTTP is supplied as options as well. is supplied as options as well.
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
skipping to change at page 36, line 29 skipping to change at page 37, line 17
o If-Match o If-Match
o If-None-Match o If-None-Match
o Size1 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 Sections 5.8 and 5.9, respectively. In case an option is
option is not defined for a method or response code, it MUST NOT be not defined for a Method or Response Code, it MUST NOT be included by
included by a sender and MUST be treated like an unrecognized option a sender and MUST be treated like an unrecognized option by a
by a recipient. recipient.
5.4.1. Critical/Elective 5.4.1. Critical/Elective
Options fall into one of two classes: "critical" or "elective". The Options fall into one of two classes: "critical" or "elective". The
difference between these is how an option unrecognized by an endpoint difference between these is how an option unrecognized by an endpoint
is handled: is handled:
o Upon reception, unrecognized options of class "elective" MUST be o Upon reception, unrecognized options of class "elective" MUST be
silently ignored. silently ignored.
o Unrecognized options of class "critical" that occur in a o Unrecognized options of class "critical" that occur in a
Confirmable request MUST cause the return of a 4.02 (Bad Option) Confirmable request MUST cause the return of a 4.02 (Bad Option)
response. This response SHOULD include a diagnostic payload response. This response SHOULD include a diagnostic payload
describing the unrecognized option(s) (see Section 5.5.2). describing the unrecognized option(s) (see Section 5.5.2).
o Unrecognized options of class "critical" that occur in a o Unrecognized options of class "critical" that occur in a
Confirmable response, or piggy-backed in an Acknowledgement, MUST Confirmable response, or piggybacked in an Acknowledgement, MUST
cause the response to be rejected (Section 4.2). cause the response to be rejected (Section 4.2).
o Unrecognized options of class "critical" that occur in a Non- o Unrecognized options of class "critical" that occur in a Non-
confirmable message MUST cause the message to be rejected confirmable message MUST cause the message to be rejected
(Section 4.3). (Section 4.3).
Note that, whether critical or elective, an option is never Note that, whether critical or elective, an option is never
"mandatory" (it is always optional): These rules are defined in order "mandatory" (it is always optional): these rules are defined in order
to enable implementations to stop processing options they do not to enable implementations to stop processing options they do not
understand or implement. understand or implement.
Critical/Elective rules apply to non-proxying endpoints. A proxy Critical/elective rules apply to non-proxying endpoints. A proxy
processes options based on Unsafe/Safe-to-Forward classes as defined processes options based on Unsafe/Safe-to-Forward classes as defined
in Section 5.7. in Section 5.7.
5.4.2. Proxy Unsafe/Safe-to-Forward and NoCacheKey 5.4.2. Proxy Unsafe or Safe-to-Forward and NoCacheKey
In addition to an option being marked as Critical or Elective, In addition to an option being marked as critical or elective,
options are also classified based on how a proxy is to deal with the options are also classified based on how a proxy is to deal with the
option if it does not recognize it. For this purpose, an option can option if it does not recognize it. For this purpose, an option can
either be considered Unsafe to Forward (UnSafe is set) or Safe-to- either be considered Unsafe to forward (UnSafe is set) or Safe-to-
Forward (UnSafe is clear). Forward (UnSafe is clear).
In addition, for an option that is marked Safe-to-Forward, the option In addition, for an option that is marked Safe-to-Forward, the option
number indicates whether it is intended to be part of the Cache-Key number indicates whether or not it is intended to be part of the
(Section 5.6) in a request or not; if some of the NoCacheKey bits are Cache-Key (Section 5.6) in a request. If some of the NoCacheKey bits
0, it is, if all NoCacheKey bits are 1, it is not (see are 0, it is; if all NoCacheKey bits are 1, it is not (see
Section 5.4.6). Section 5.4.6).
Note: The Cache-Key indication is relevant only for proxies that do Note: The Cache-Key indication is relevant only for proxies that do
not implement the given option as a request option and instead not implement the given option as a request option and instead
rely on the Unsafe/Safe-to-Forward indication only. E.g., for rely on the Unsafe/Safe-to-Forward indication only. For example,
ETag, actually using the request option as a part of the Cache-Key for ETag, actually using the request option as a part of the
is grossly inefficient, but it is the best thing one can do if Cache-Key is grossly inefficient, but it is the best thing one can
ETag is not implemented by a proxy, as the response is going to do if ETag is not implemented by a proxy, as the response is going
differ based on the presence of the request option. A more useful to differ based on the presence of the request option. A more
proxy that does implement the ETag request option is not using useful proxy that does implement the ETag request option is not
ETag as a part of the Cache-Key. using ETag as a part of the Cache-Key.
NoCacheKey is indicated in three bits so that only one out of NoCacheKey is indicated in three bits so that only one out of
eight codepoints is qualified as NoCacheKey, assuming this is the eight codepoints is qualified as NoCacheKey, leaving seven out of
less likely case. eight codepoints for what appears to be the more likely case.
Proxy behavior with regard to these classes is defined in Proxy behavior with regard to these classes is defined in
Section 5.7. Section 5.7.
5.4.3. Length 5.4.3. Length
Option values are defined to have a specific length, often in the Option values are defined to have a specific length, often in the
form of an upper and lower bound. If the length of an option value form of an upper and lower bound. If the length of an option value
in a request is outside the defined range, that option MUST be in a request is outside the defined range, that option MUST be
treated like an unrecognized option (see Section 5.4.1). treated like an unrecognized option (see Section 5.4.1).
5.4.4. Default Values 5.4.4. Default Values
Options may be defined to have a default value. If the value of Options may be defined to have a default value. If the value of an
option is intended to be this default value, the option SHOULD NOT be option is intended to be this default value, the option SHOULD NOT be
included in the message. If the option is not present, the default included in the message. If the option is not present, the default
value MUST be assumed. value MUST be assumed.
Where a critical option has a default value, this is chosen in such a Where a critical option has a default value, this is chosen in such a
way that the absence of the option in a message can be processed way that the absence of the option in a message can be processed
properly both by implementations unaware of the critical option and properly both by implementations unaware of the critical option and
by implementations that interpret this absence as the presence of the by implementations that interpret this absence as the presence of the
default value for the option. default value for the option.
skipping to change at page 38, line 40 skipping to change at page 39, line 26
included more than once in a message. included more than once in a message.
If a message includes an option with more occurrences than the option If a message includes an option with more occurrences than the option
is defined for, each supernumerary option occurrence that appears is defined for, each supernumerary option occurrence that appears
subsequently in the message MUST be treated like an unrecognized subsequently in the message MUST be treated like an unrecognized
option (see Section 5.4.1). option (see Section 5.4.1).
5.4.6. Option Numbers 5.4.6. Option Numbers
An Option is identified by an option number, which also provides some An Option is identified by an option number, which also provides some
additional semantics information: e.g., odd numbers indicate a additional semantics information, e.g., odd numbers indicate a
critical option, while even numbers indicate an elective option. critical option, while even numbers indicate an elective option.
Note that this is not just a convention, it is a feature of the Note that this is not just a convention, it is a feature of the
protocol: Whether an option is elective or critical is entirely protocol: Whether an option is elective or critical is entirely
determined by whether its option number is even or odd. determined by whether its option number is even or odd.
More generally speaking, an Option number is constructed with a bit More generally speaking, an Option number is constructed with a bit
mask to indicate if an option is Critical/Elective, Unsafe/Safe-to- mask to indicate if an option is Critical or Elective, Unsafe or
Forward and in the case of Safe-to-Forward, also a Cache-Key Safe-to-Forward, and, in the case of Safe-to-Forward, to provide a
indication as shown by the following figure. In the following text, Cache-Key indication as shown by the following figure. In the
the bit mask is expressed as a single byte that is applied to the following text, the bit mask is expressed as a single byte that is
least significant byte of the option number in unsigned integer applied to the least significant byte of the option number in
representation. When bit 7 (the least significant bit) is 1, an unsigned integer representation. When bit 7 (the least significant
option is Critical (and likewise Elective when 0). When bit 6 is 1, bit) is 1, an option is Critical (and likewise Elective when 0).
an option is Unsafe (and likewise Safe-to-Forward when 0). When bit When bit 6 is 1, an option is Unsafe (and likewise Safe-to-Forward
6 is 0, i.e., the option is not Unsafe, it is not a Cache-Key when 0). When bit 6 is 0, i.e., the option is not Unsafe, it is not
(NoCacheKey) if and only if bits 3-5 are all set to 1; all other bit a Cache-Key (NoCacheKey) if and only if bits 3-5 are all set to 1;
combinations mean that it indeed is a Cache-Key. These classes of all other bit combinations mean that it indeed is a Cache-Key. These
options are explained in the next sections. classes of 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);
Figure 11: Determining Characteristics from an Option Number Figure 11: Determining Characteristics from an Option Number
The option numbers for the options defined in this document are The option numbers for the options defined in this document are
listed in the CoAP Option Number Registry (Section 12.2). listed in the "CoAP Option Numbers" registry (Section 12.2).
5.5. Payloads and Representations 5.5. Payloads and Representations
Both requests and responses may include a payload, depending on the Both requests and responses may include a payload, depending on the
method or response code respectively. If a method or response code Method or Response Code, respectively. If a Method or Response Code
is not defined to have a payload, then a sender MUST NOT include one, is not defined to have a payload, then a sender MUST NOT include one,
and a recipient MUST ignore it. and a recipient MUST ignore it.
5.5.1. Representation 5.5.1. Representation
The payload of requests or of responses indicating success is The payload of requests or of responses indicating success is
typically a representation of a resource ("resource representation") typically a representation of a resource ("resource representation")
or the result of the requested action ("action result"). Its format or the result of the requested action ("action result"). Its format
is specified by the Internet media type and content coding given by is specified by the Internet media type and content coding given by
the Content-Format Option. In the absence of this option, no default the Content-Format Option. In the absence of this option, no default
value is assumed and the format will need to be inferred by the value is assumed, and the format will need to be inferred by the
application (e.g., from the application context). Payload "sniffing" application (e.g., from the application context). Payload "sniffing"
SHOULD only be attempted if no content type is given. SHOULD only be attempted if no content type is given.
Implementation Note: On a quality of implementation level, there is Implementation Note: On a quality-of-implementation level, there is
a strong expectation that a Content-Format indication will be a strong expectation that a Content-Format indication will be
provided with resource representations whenever possible. This is provided with resource representations whenever possible. This is
not a "SHOULD"-level requirement solely because it is not a not a "SHOULD" level requirement solely because it is not a
protocol requirement, and it also would be difficult to outline protocol requirement, and it also would be difficult to outline
exactly in what cases this expectation can be violated. exactly in what cases this expectation can be violated.
For responses indicating a client or server error, the payload is For responses indicating a client or server error, the payload is
considered a representation of the result of the requested action considered a representation of the result of the requested action
only if a Content-Format Option is given. In the absence of this only if a Content-Format Option is given. In the absence of this
option, the payload is a Diagnostic Payload (Section 5.5.2). option, the payload is a Diagnostic Payload (Section 5.5.2).
5.5.2. Diagnostic Payload 5.5.2. Diagnostic Payload
If no Content-Format option is given, the payload of responses If no Content-Format option is given, the payload of responses
indicating a client or server error is a brief human-readable indicating a client or server error is a brief human-readable
diagnostic message, explaining the error situation. This diagnostic diagnostic message, explaining the error situation. This diagnostic
message MUST be encoded using UTF-8 [RFC3629], more specifically message MUST be encoded using UTF-8 [RFC3629], more specifically
using Net-Unicode form [RFC5198]. using Net-Unicode form [RFC5198].
The message is similar to the Reason-Phrase on an HTTP status line. The message is similar to the Reason-Phrase on an HTTP status line.
It is not intended for end-users but for software engineers that It is not intended for end users but for software engineers that
during debugging need to interpret it in the context of the present, during debugging need to interpret it in the context of the present,
English-language specification; therefore no mechanism for language English-language specification; therefore, no mechanism for language
tagging is needed or provided. In contrast to what is usual in HTTP, tagging is needed or provided. In contrast to what is usual in HTTP,
the payload SHOULD be empty if there is no additional information the payload SHOULD be empty if there is no additional information
beyond the response code. beyond the Response Code.
5.5.3. Selected Representation 5.5.3. Selected Representation
Not all responses carry a payload that provides a representation of Not all responses carry a payload that provides a representation of
the resource addressed by the request. It is, however, sometimes the resource addressed by the request. It is, however, sometimes
useful to be able to refer to such a representation in relation to a useful to be able to refer to such a representation in relation to a
response, independent of whether it actually was enclosed. response, independent of whether it actually was enclosed.
We use the term "selected representation" to refer to the current We use the term "selected representation" to refer to the current
representation of a target resource that would have been selected in representation of a target resource that would have been selected in
a successful response if the corresponding request had used the a successful response if the corresponding request had used the
method GET and excluded any conditional request options method GET and excluded any conditional request options
(Section 5.10.8). (Section 5.10.8).
Certain response options provide metadata about the selected Certain response options provide metadata about the selected
representation, which might differ from the representation included representation, which might differ from the representation included
in the message for responses to some state-changing methods. Of the in the message for responses to some state-changing methods. Of the
response options defined in this specification, only the ETag response options defined in this specification, only the ETag
response option (Section 5.10.6) is defined as selected response option (Section 5.10.6) is defined as metadata about the
representation metadata. selected representation.
5.5.4. Content Negotiation 5.5.4. Content Negotiation
A server may be able to supply a representation for a resource in one A server may be able to supply a representation for a resource in one
of multiple representation formats. Without further information from of multiple representation formats. Without further information from
the client, it will provide the representation in the format it the client, it will provide the representation in the format it
prefers. prefers.
By using the Accept Option (Section 5.10.4) in a request, the client By using the Accept Option (Section 5.10.4) in a request, the client
can indicate which content-format it prefers to receive. can indicate which content-format it prefers to receive.
skipping to change at page 41, line 26 skipping to change at page 42, line 21
The goal of caching in CoAP is to reuse a prior response message to The goal of caching in CoAP is to reuse a prior response message to
satisfy a current request. In some cases, a stored response can be satisfy a current request. In some cases, a stored response can be
reused without the need for a network request, reducing latency and reused without the need for a network request, reducing latency and
network round-trips; a "freshness" mechanism is used for this purpose network round-trips; a "freshness" mechanism is used for this purpose
(see Section 5.6.1). Even when a new request is required, it is (see Section 5.6.1). Even when a new request is required, it is
often possible to reuse the payload of a prior response to satisfy often possible to reuse the payload of a prior response to satisfy
the request, thereby reducing network bandwidth usage; a "validation" the request, thereby reducing network bandwidth usage; a "validation"
mechanism is used for this purpose (see Section 5.6.2). mechanism is used for this purpose (see Section 5.6.2).
Unlike HTTP, the cacheability of CoAP responses does not depend on Unlike HTTP, the cacheability of CoAP responses does not depend on
the request method, but the Response Code. The cacheability of each the request method, but it depends on the Response Code. The
Response Code is defined along the Response Code definitions in cacheability of each Response Code is defined along the Response Code
Section 5.9. Response Codes that indicate success and are definitions in Section 5.9. Response Codes that indicate success and
unrecognized by an endpoint MUST NOT be cached. are unrecognized by an endpoint MUST NOT be cached.
For a presented request, a CoAP endpoint MUST NOT use a stored For a presented request, a CoAP endpoint MUST NOT use a stored
response, unless: response, unless:
o the presented request method and that used to obtain the stored o the presented request method and that used to obtain the stored
response match, response match,
o all options match between those in the presented request and those o all options match between those in the presented request and those
of the request used to obtain the stored response (which includes of the request used to obtain the stored response (which includes
the request URI), except that there is no need for a match of any the request URI), except that there is no need for a match of any
request options marked as NoCacheKey (Section 5.4) or recognized request options marked as NoCacheKey (Section 5.4) or recognized
by the Cache and fully interpreted with respect to its specified by the Cache and fully interpreted with respect to its specified
cache behavior (such as the ETag request option, Section 5.10.6, cache behavior (such as the ETag request option described in
see also Section 5.4.2), and Section 5.10.6; see also Section 5.4.2), and
o the stored response is either fresh or successfully validated as o the stored response is either fresh or successfully validated as
defined below. defined below.
The set of request options that is used for matching the cache entry The set of request options that is used for matching the cache entry
is also collectively referred to as the "Cache-Key". For URI schemes is also collectively referred to as the "Cache-Key". For URI schemes
other than coap and coaps, matching of those options that constitute other than coap and coaps, matching of those options that constitute
the request URI may be performed under rules specific to the URI the request URI may be performed under rules specific to the URI
scheme. scheme.
skipping to change at page 42, line 38 skipping to change at page 43, line 32
If a client has a fresh stored response and makes a new request If a client has a fresh stored response and makes a new request
matching the request for that stored response, the new response matching the request for that stored response, the new response
invalidates the old response. invalidates the old response.
5.6.2. Validation Model 5.6.2. Validation Model
When an endpoint has one or more stored responses for a GET request, When an endpoint has one or more stored responses for a GET request,
but cannot use any of them (e.g., because they are not fresh), it can but cannot use any of them (e.g., because they are not fresh), it can
use the ETag Option (Section 5.10.6) in the GET request to give the use the ETag Option (Section 5.10.6) in the GET request to give the
origin server an opportunity to both select a stored response to be origin server an opportunity both to select a stored response to be
used, and to update its freshness. This process is known as used, and to update its freshness. This process is known as
"validating" or "revalidating" the stored response. "validating" or "revalidating" the stored response.
When sending such a request, the endpoint SHOULD add an ETag Option When sending such a request, the endpoint SHOULD add an ETag Option
specifying the entity-tag of each stored response that is applicable. specifying the entity-tag of each stored response that is applicable.
A 2.03 (Valid) response indicates the stored response identified by A 2.03 (Valid) response indicates the stored response identified by
the entity-tag given in the response's ETag Option can be reused, the entity-tag given in the response's ETag Option can be reused
after updating it as described in Section 5.9.1.3. after updating it as described in Section 5.9.1.3.
Any other response code indicates that none of the stored responses Any other Response Code indicates that none of the stored responses
nominated in the request is suitable. Instead, the response SHOULD nominated in the request is suitable. Instead, the response SHOULD
be used to satisfy the request and MAY replace the stored response. be used to satisfy the request and MAY replace the stored response.
5.7. Proxying 5.7. Proxying
A proxy is a CoAP endpoint that can be tasked by CoAP clients to A proxy is a CoAP endpoint that can be tasked by CoAP clients to
perform requests on their behalf. This may be useful, for example, perform requests on their behalf. This may be useful, for example,
when the request could otherwise not be made, or to service the when the request could otherwise not be made, or to service the
response from a cache in order to reduce response time and network response from a cache in order to reduce response time and network
bandwidth or energy consumption. bandwidth or energy consumption.
skipping to change at page 43, line 23 skipping to change at page 44, line 23
In an overall architecture for a Constrained RESTful Environment, In an overall architecture for a Constrained RESTful Environment,
proxies can serve quite different purposes. Proxies can be proxies can serve quite different purposes. Proxies can be
explicitly selected by clients, a role that we term "forward-proxy". explicitly selected by clients, a role that we term "forward-proxy".
Proxies can also be inserted to stand in for origin servers, a role Proxies can also be inserted to stand in for origin servers, a role
that we term "reverse-proxy". Orthogonal to this distinction, a that we term "reverse-proxy". Orthogonal to this distinction, a
proxy can map from a CoAP request to a CoAP request (CoAP-to-CoAP proxy can map from a CoAP request to a CoAP request (CoAP-to-CoAP
proxy) or translate from or to a different protocol ("cross-proxy"). proxy) or translate from or to a different protocol ("cross-proxy").
Full definitions of these terms are provided in Section 1.2. Full definitions of these terms are provided in Section 1.2.
Notes: The terminology in this specification has been selected to be Notes: The terminology in this specification has been selected to be
culturally compatible with the terminology used in the wider Web culturally compatible with the terminology used in the wider web
application environments, without necessarily matching it in every application environments, without necessarily matching it in every
detail (which may not even be relevant to Constrained RESTful detail (which may not even be relevant to Constrained RESTful
Environments). Not too much semantics should be ascribed to the Environments). Not too much semantics should be ascribed to the
components of the terms (such as "forward", "reverse", or components of the terms (such as "forward", "reverse", or
"cross"). "cross").
HTTP proxies, besides acting as HTTP proxies, often offer a HTTP proxies, besides acting as HTTP proxies, often offer a
transport protocol proxying function ("CONNECT") to enable end-to- transport-protocol proxying function ("CONNECT") to enable end-to-
end transport layer security through the proxy. No such function end transport layer security through the proxy. No such function
is defined for CoAP-to-CoAP proxies in this specification, as is defined for CoAP-to-CoAP proxies in this specification, as
forwarding of UDP packets is unlikely to be of much value in forwarding of UDP packets is unlikely to be of much value in
Constrained RESTful environments. See also Section 10.2.7 for the Constrained RESTful Environments. See also Section 10.2.7 for the
cross-proxy case. cross-proxy case.
When a client uses a proxy to make a request that will use a secure When a client uses a proxy to make a request that will use a secure
URI scheme (e.g., coaps or https), the request towards the proxy URI scheme (e.g., "coaps" or "https"), the request towards the proxy
SHOULD be sent using DTLS security except where equivalent lower SHOULD be sent using DTLS except where equivalent lower-layer
layer security is used for the leg between the client and the proxy. security is used for the leg between the client and the proxy.
5.7.1. Proxy Operation 5.7.1. Proxy Operation
A proxy generally needs a way to determine potential request A proxy generally needs a way to determine potential request
parameters for a request to a destination based on the request it parameters for a request it places to a destination, based on the
received. This way is fully specified for a forward-proxy, but may request it received from its client. This way is fully specified for
depend on the specific configuration for a reverse-proxy. In a forward-proxy but may depend on the specific configuration for a
particular, the client of a reverse-proxy generally does not indicate reverse-proxy. In particular, the client of a reverse-proxy
a locator for the destination, necessitating some form of namespace generally does not indicate a locator for the destination,
translation in the reverse-proxy. However, some aspects of the necessitating some form of namespace translation in the reverse-
operation of proxies are common to all its forms. proxy. However, some aspects of the operation of proxies are common
to all its forms.
If a proxy does not employ a cache, then it simply forwards the If a proxy does not employ a cache, then it simply forwards the
translated request to the determined destination. Otherwise, if it translated request to the determined destination. Otherwise, if it
does employ a cache but does not have a stored response that matches does employ a cache but does not have a stored response that matches
the translated request and is considered fresh, then it needs to the translated request and is considered fresh, then it needs to
refresh its cache according to Section 5.6. For options in the refresh its cache according to Section 5.6. For options in the
request that the proxy recognizes, it knows whether the option is request that the proxy recognizes, it knows whether the option is
intended to act as part of the key used in looking up the cached intended to act as part of the key used in looking up the cached
value or not. E.g., since requests for different Uri-Path values value or not. For example, since requests for different Uri-Path
address different resources, Uri-Path values are always part of the values address different resources, Uri-Path values are always part
Cache-Key, while, e.g., Token values are never part of the Cache-Key. of the Cache-Key, while, e.g., Token values are never part of the
For options that the proxy does not recognize but that are marked Cache-Key. For options that the proxy does not recognize but that
Safe-to-Forward in the option number, the option also indicates are marked Safe-to-Forward in the option number, the option also
whether it is to be included in the Cache-Key (NoCacheKey is not all indicates whether it is to be included in the Cache-Key (NoCacheKey
set) or not (NoCacheKey is all set). (Options that are unrecognized is not all set) or not (NoCacheKey is all set). (Options that are
and marked Unsafe lead to 4.02 Bad Option.) unrecognized and marked Unsafe lead to 4.02 Bad Option.)
If the request to the destination times out, then a 5.04 (Gateway If the request to the destination times out, then a 5.04 (Gateway
Timeout) response MUST be returned. If the request to the Timeout) response MUST be returned. If the request to the
destination returns a response that cannot be processed by the proxy destination returns a response that cannot be processed by the proxy
(e.g, due to unrecognized critical options, message format errors), (e.g, due to unrecognized critical options or message format errors),
then a 5.02 (Bad Gateway) response MUST be returned. Otherwise, the then a 5.02 (Bad Gateway) response MUST be returned. Otherwise, the
proxy returns the response to the client. proxy returns the response to the client.
If a response is generated out of a cache, the generated (or implied) If a response is generated out of a cache, the generated (or implied)
Max-Age Option MUST NOT extend the max-age originally set by the Max-Age Option MUST NOT extend the max-age originally set by the
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. For example, the Max-Age Option could be adjusted by the
each response using the formula: proxy for 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.
Additional considerations for cross-protocol proxying between CoAP Additional considerations for cross-protocol proxying between CoAP
and HTTP are discussed in Section 10. and HTTP are discussed in Section 10.
5.7.2. Forward-Proxies 5.7.2. Forward-Proxies
CoAP distinguishes between requests made (as if) to an origin server CoAP distinguishes between requests made (as if) to an origin server
and a request made through a forward-proxy. CoAP requests to a and requests made through a forward-proxy. CoAP requests to a
forward-proxy are made as normal Confirmable or Non-confirmable forward-proxy are made as normal Confirmable or Non-confirmable
requests to the forward-proxy endpoint, but specify the request URI requests to the forward-proxy endpoint, but they specify the request
in a different way: The request URI in a proxy request is specified URI in a different way: The request URI in a proxy request is
as a string in the Proxy-Uri Option (see Section 5.10.2), while the specified as a string in the Proxy-Uri Option (see Section 5.10.2),
request URI in a request to an origin server is split into the Uri- while the request URI in a request to an origin server is split into
Host, Uri-Port, Uri-Path and Uri-Query Options (see Section 5.10.1); the Uri-Host, Uri-Port, Uri-Path, and Uri-Query Options (see
alternatively the URI in a proxy request can be assembled from a Section 5.10.1). Alternatively, the URI in a proxy request can be
Proxy-Scheme option and the split options mentioned. assembled from a Proxy-Scheme option and the split options mentioned.
When a proxy request is made to an endpoint and the endpoint is When a proxy request is made to an endpoint and the endpoint is
unwilling or unable to act as proxy for the request URI, it MUST unwilling or unable to act as proxy for the request URI, it MUST
return a 5.05 (Proxying Not Supported) response. If the authority return a 5.05 (Proxying Not Supported) response. If the authority
(host and port) is recognized as identifying the proxy endpoint (host and port) is recognized as identifying the proxy endpoint
itself (see Section 5.10.2), then the request MUST be treated as a itself (see Section 5.10.2), then the request MUST be treated as a
local (non-proxied) request. local (non-proxied) request.
Unless a proxy is configured to forward the proxy request to another Unless a proxy is configured to forward the proxy request to another
proxy, it MUST translate the request as follows: The scheme of the proxy, it MUST translate the request as follows: the scheme of the
request URI defines the outgoing protocol and its details (e.g., CoAP request URI defines the outgoing protocol and its details (e.g., CoAP
is used over UDP for the "coap" scheme and over DTLS for the "coaps" is used over UDP for the "coap" scheme and over DTLS for the "coaps"
scheme.) For a CoAP-to-CoAP proxy, the origin server's IP address scheme.) For a CoAP-to-CoAP proxy, the origin server's IP address
and port are determined by the authority component of the request and port are determined by the authority component of the request
URI, and the request URI is decoded and split into the Uri-Host, Uri- URI, and the request URI is decoded and split into the Uri-Host, Uri-
Port, Uri-Path and Uri-Query Options. This consumes the Proxy-Uri or Port, Uri-Path and Uri-Query Options. This consumes the Proxy-Uri or
Proxy-Scheme option, which is therefore not forwarded to the origin Proxy-Scheme option, which is therefore not forwarded to the origin
server. server.
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
request from information in the request and information in their from information in the request and information in their
configuration. E.g., a reverse-proxy might offer various resources configuration. For example, a reverse-proxy might offer various
the existence of which it has learned through resource discovery as resources as if they were its own resources, after having learned of
if they were its own resources. The reverse-proxy is free to build a their existence through resource discovery. The reverse-proxy is
namespace for the URIs that identify these resources. A reverse- free to build a namespace for the URIs that identify these resources.
proxy may also build a namespace that gives the client more control A reverse-proxy may also build a namespace that gives the client more
over where the request goes, e.g. by embedding host identifiers and control over where the request goes, e.g., by embedding host
port numbers into the URI path of the resources offered. identifiers and 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.
5.8. Method Definitions 5.8. Method Definitions
In this section each method is defined along with its behavior. A In this section, each method is defined along with its behavior. A
request with an unrecognized or unsupported Method Code MUST generate request with an unrecognized or unsupported Method Code MUST generate
a 4.05 (Method Not Allowed) piggy-backed response. a 4.05 (Method Not Allowed) piggybacked response.
5.8.1. GET 5.8.1. GET
The GET method retrieves a representation for the information that The GET method retrieves a representation for the information that
currently corresponds to the resource identified by the request URI. currently corresponds to the resource identified by the request URI.
If the request includes an Accept Option, that indicates the If the request includes an Accept Option, that indicates the
preferred content-format of a response. If the request includes an preferred content-format of a response. If the request includes an
ETag Option, the GET method requests that ETag be validated and that ETag Option, the GET method requests that ETag be validated and that
the representation be transferred only if validation failed. Upon the representation be transferred only if validation failed. Upon
success a 2.05 (Content) or 2.03 (Valid) response code SHOULD be success, a 2.05 (Content) or 2.03 (Valid) Response Code SHOULD be
present in the response. present in the response.
The GET method is safe and idempotent. The GET method is safe and idempotent.
5.8.2. POST 5.8.2. POST
The POST method requests that the representation enclosed in the The POST method requests that the representation enclosed in the
request be processed. The actual function performed by the POST request be processed. The actual function performed by the POST
method is determined by the origin server and dependent on the target method is determined by the origin server and dependent on the target
resource. It usually results in a new resource being created or the resource. It usually results in a new resource being created or the
target resource being updated. target resource being updated.
If a resource has been created on the server, the response returned If a resource has been created on the server, the response returned
by the server SHOULD have a 2.01 (Created) response code and SHOULD by the server SHOULD have a 2.01 (Created) Response Code and SHOULD
include the URI of the new resource in a sequence of one or more include the URI of the new resource in a sequence of one or more
Location-Path and/or Location-Query Options (Section 5.10.7). If the Location-Path and/or Location-Query Options (Section 5.10.7). If the
POST succeeds but does not result in a new resource being created on POST succeeds but does not result in a new resource being created on
the server, the response SHOULD have a 2.04 (Changed) response code. the server, the response SHOULD have a 2.04 (Changed) Response Code.
If the POST succeeds and results in the target resource being If the POST succeeds and results in the target resource being
deleted, the response SHOULD have a 2.02 (Deleted) response code. deleted, the response SHOULD have a 2.02 (Deleted) Response Code.
POST is neither safe nor idempotent. POST is neither safe nor idempotent.
5.8.3. PUT 5.8.3. PUT
The PUT method requests that the resource identified by the request The PUT method requests that the resource identified by the request
URI be updated or created with the enclosed representation. The URI be updated or created with the enclosed representation. The
representation format is specified by the media type and content representation format is specified by the media type and content
coding given in the Content-Format Option, if provided. coding given in the Content-Format Option, if provided.
If a resource exists at the request URI the enclosed representation If a resource exists at the request URI, the enclosed representation
SHOULD be considered a modified version of that resource, and a 2.04 SHOULD be considered a modified version of that resource, and a 2.04
(Changed) response code SHOULD be returned. If no resource exists (Changed) Response Code SHOULD be returned. If no resource exists,
then the server MAY create a new resource with that URI, resulting in then the server MAY create a new resource with that URI, resulting in
a 2.01 (Created) response code. If the resource could not be created a 2.01 (Created) Response Code. If the resource could not be created
or modified, then an appropriate error response code SHOULD be sent. or modified, then an appropriate error Response Code SHOULD be sent.
Further restrictions to a PUT can be made by including the If-Match Further restrictions to a PUT can be made by including the If-Match
(see Section 5.10.8.1) or If-None-Match (see Section 5.10.8.2) (see Section 5.10.8.1) or If-None-Match (see Section 5.10.8.2)
options in the request. options in the request.
PUT is not safe, but is idempotent. PUT is not safe but is idempotent.
5.8.4. DELETE 5.8.4. DELETE
The DELETE method requests that the resource identified by the The DELETE method requests that the resource identified by the
request URI be deleted. A 2.02 (Deleted) response code SHOULD be request URI be deleted. A 2.02 (Deleted) Response Code SHOULD be
used on success or in case the resource did not exist before the used on success or in case the resource did not exist before the
request. request.
DELETE is not safe, but is idempotent. DELETE is not safe but is idempotent.
5.9. Response Code Definitions 5.9. Response Code Definitions
Each response code is described below, including any options required Each Response Code is described below, including any options required
in the response. Where appropriate, some of the codes will be in the response. Where appropriate, some of the codes will be
specified in regards to related response codes in HTTP [RFC2616]; specified in regards to related Response Codes in HTTP [RFC2616];
this does not mean that any such relationship modifies the HTTP this does not mean that any such relationship modifies the HTTP
mapping specified in Section 10. mapping specified in Section 10.
5.9.1. Success 2.xx 5.9.1. Success 2.xx
This class of status code indicates that the clients request was This class of Response Code indicates that the clients request was
successfully received, understood, and accepted. successfully received, understood, and accepted.
5.9.1.1. 2.01 Created 5.9.1.1. 2.01 Created
Like HTTP 201 "Created", but only used in response to POST and PUT Like HTTP 201 "Created", but only used in response to POST and PUT
requests. The payload returned with the response, if any, is a requests. The payload returned with the response, if any, is a
representation of the action result. representation of the action result.
If the response includes one or more Location-Path and/or Location- If the response includes one or more Location-Path and/or Location-
Query Options, the values of these options specify the location at Query Options, the values of these options specify the location at
which the resource was created. Otherwise, the resource was created which the resource was created. Otherwise, the resource was created
at the request URI. A cache receiving this response MUST mark any at the request URI. A cache receiving this response MUST mark any
stored response for the created resource as not fresh. stored response for the created resource as not fresh.
This response is not cacheable. This response is not cacheable.
5.9.1.2. 2.02 Deleted 5.9.1.2. 2.02 Deleted
Like HTTP 204 "No Content", but only used in response to requests This Response Code is like HTTP 204 "No Content" but only used in
that cause the resource to cease being available, such as DELETE and response to requests that cause the resource to cease being
in certain circumstances POST. The payload returned with the available, such as DELETE and, in certain circumstances, POST. The
response, if any, is a representation of the action result. payload returned with the response, if any, is a representation of
the action result.
This response is not cacheable. However, a cache MUST mark any This response is not cacheable. However, a cache MUST mark any
stored response for the deleted resource as not fresh. stored response for the deleted resource as not fresh.
5.9.1.3. 2.03 Valid 5.9.1.3. 2.03 Valid
Related to HTTP 304 "Not Modified", but only used to indicate that This Response Code is related to HTTP 304 "Not Modified" but only
the response identified by the entity-tag identified by the included used to indicate that the response identified by the entity-tag
ETag Option is valid. Accordingly, the response MUST include an ETag identified by the included ETag Option is valid. Accordingly, the
Option, and MUST NOT include a payload. response MUST include an ETag Option and MUST NOT include a payload.
When a cache that recognizes and processes the ETag response option When a cache that recognizes and processes the ETag response option
receives a 2.03 (Valid) response, it MUST update the stored response receives a 2.03 (Valid) response, it MUST update the stored response
with the value of the Max-Age Option included in the response with the value of the Max-Age Option included in the response
(explicitly, or implicitly as a default value; see also (explicitly, or implicitly as a default value; see also
Section 5.6.2). For each type of Safe-to-Forward option present in Section 5.6.2). For each type of Safe-to-Forward option present in
the response, the (possibly empty) set of options of this type that the response, the (possibly empty) set of options of this type that
are present in the stored response MUST be replaced with the set of are present in the stored response MUST be replaced with the set of
options of this type in the response received. (Unsafe options may options of this type in the response received. (Unsafe options may
trigger similar option specific processing as defined by the option.) trigger similar option-specific processing as defined by the option.)
5.9.1.4. 2.04 Changed 5.9.1.4. 2.04 Changed
Like HTTP 204 "No Content", but only used in response to POST and PUT This Response Code is like HTTP 204 "No Content" but only used in
requests. The payload returned with the response, if any, is a response to POST and PUT requests. The payload returned with the
representation of the action result. response, if any, is a representation of the action result.
This response is not cacheable. However, a cache MUST mark any This response is not cacheable. However, a cache MUST mark any
stored response for the changed resource as not fresh. stored response for the changed resource as not fresh.
5.9.1.5. 2.05 Content 5.9.1.5. 2.05 Content
Like HTTP 200 "OK", but only used in response to GET requests. This Response Code is like HTTP 200 "OK" but only used in response to
GET requests.
The payload returned with the response is a representation of the The payload returned with the response is a representation of the
target resource. target resource.
This response is cacheable: Caches can use the Max-Age Option to This response is cacheable: Caches can use the Max-Age Option to
determine freshness (see Section 5.6.1) and (if present) the ETag determine freshness (see Section 5.6.1) and (if present) the ETag
Option for validation (see Section 5.6.2). Option for validation (see Section 5.6.2).
5.9.2. Client Error 4.xx 5.9.2. Client Error 4.xx
This class of response code is intended for cases in which the client This class of Response Code is intended for cases in which the client
seems to have erred. These response codes are applicable to any seems to have erred. These Response Codes are applicable to any
request method. request method.
The server SHOULD include a diagnostic payload under the conditions The server SHOULD include a diagnostic payload under the conditions
detailed in Section 5.5.2. detailed in Section 5.5.2.
Responses of this class are cacheable: Caches can use the Max-Age Responses of this class are cacheable: Caches can use the Max-Age
Option to determine freshness (see Section 5.6.1). They cannot be Option to determine freshness (see Section 5.6.1). They cannot be
validated. validated.
5.9.2.1. 4.00 Bad Request 5.9.2.1. 4.00 Bad Request
Like HTTP 400 "Bad Request". This Response Code is Like HTTP 400 "Bad Request".
5.9.2.2. 4.01 Unauthorized 5.9.2.2. 4.01 Unauthorized
The client is not authorized to perform the requested action. The The client is not authorized to perform the requested action. The
client SHOULD NOT repeat the request without first improving its client SHOULD NOT repeat the request without first improving its
authentication status to the server. Which specific mechanism can be authentication status to the server. Which specific mechanism can be
used for this is outside this document's scope; see also Section 9. used for this is outside this document's scope; see also Section 9.
5.9.2.3. 4.02 Bad Option 5.9.2.3. 4.02 Bad Option
The request could not be understood by the server due to one or more The request could not be understood by the server due to one or more
unrecognized or malformed options. The client SHOULD NOT repeat the unrecognized or malformed options. The client SHOULD NOT repeat the
request without modification. request without modification.
5.9.2.4. 4.03 Forbidden 5.9.2.4. 4.03 Forbidden
Like HTTP 403 "Forbidden". This Response Code is like HTTP 403 "Forbidden".
5.9.2.5. 4.04 Not Found 5.9.2.5. 4.04 Not Found
Like HTTP 404 "Not Found". This Response Code is like HTTP 404 "Not Found".
5.9.2.6. 4.05 Method Not Allowed 5.9.2.6. 4.05 Method Not Allowed
Like HTTP 405 "Method Not Allowed", but with no parallel to the This Response Code is like HTTP 405 "Method Not Allowed" but with no
"Allow" header field. parallel to the "Allow" header field.
5.9.2.7. 4.06 Not Acceptable 5.9.2.7. 4.06 Not Acceptable
Like HTTP 406 "Not Acceptable", but with no response entity. This Response Code is 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". This Response Code is 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". This Response Code is like HTTP 413 "Request Entity Too Large".
The response SHOULD include a Size1 Option (Section 5.10.9) to The response SHOULD include a Size1 Option (Section 5.10.9) to
indicate the maximum size of request entity the server is able and 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 willing to handle, unless the server is not in a position to make
this information available. 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". This Response Code is 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.
The server SHOULD include a diagnostic payload under the conditions The server SHOULD include a diagnostic payload under the conditions
detailed in Section 5.5.2. detailed in Section 5.5.2.
Responses of this class are cacheable: Caches can use the Max-Age Responses of this class are cacheable: Caches can use the Max-Age
Option to determine freshness (see Section 5.6.1). They cannot be Option to determine freshness (see Section 5.6.1). They cannot be
validated. validated.
5.9.3.1. 5.00 Internal Server Error 5.9.3.1. 5.00 Internal Server Error
Like HTTP 500 "Internal Server Error". This Response Code is like HTTP 500 "Internal Server Error".
5.9.3.2. 5.01 Not Implemented 5.9.3.2. 5.01 Not Implemented
Like HTTP 501 "Not Implemented". This Response Code is like HTTP 501 "Not Implemented".
5.9.3.3. 5.02 Bad Gateway 5.9.3.3. 5.02 Bad Gateway
Like HTTP 502 "Bad Gateway". This Response Code is like HTTP 502 "Bad Gateway".
5.9.3.4. 5.03 Service Unavailable 5.9.3.4. 5.03 Service Unavailable
Like HTTP 503 "Service Unavailable", but using the Max-Age Option in
place of the "Retry-After" header field to indicate the number of This Response Code is like HTTP 503 "Service Unavailable" but uses
seconds after which to retry. the Max-Age Option in place of the "Retry-After" header field to
indicate the number of seconds after which to retry.
5.9.3.5. 5.04 Gateway Timeout 5.9.3.5. 5.04 Gateway Timeout
Like HTTP 504 "Gateway Timeout". This Response Code is like HTTP 504 "Gateway Timeout".
5.9.3.6. 5.05 Proxying Not Supported 5.9.3.6. 5.05 Proxying Not Supported
The server is unable or unwilling to act as a forward-proxy for the The server is unable or unwilling to act as a forward-proxy for the
URI specified in the Proxy-Uri Option or using Proxy-Scheme (see URI specified in the Proxy-Uri Option or using Proxy-Scheme (see
Section 5.10.2). Section 5.10.2).
5.10. Option Definitions 5.10. Option Definitions
The individual CoAP options are summarized in Table 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.
present specification does not define any NoCacheKey options, but the
format of the table is intended to be useful for additional +-----+---+---+---+---+----------------+--------+--------+----------+
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) |
| 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) |
+-----+---+---+---+---+----------------+--------+--------+----------+
+-----+----+---+---+---+----------------+--------+--------+---------+
| 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
the full URI can be reconstructed at any involved endpoint. The the full URI can be reconstructed at any involved endpoint. The
syntax of CoAP URIs is defined in Section 6. syntax of CoAP URIs is defined in Section 6.
The steps for parsing URIs into options is defined in Section 6.4. The steps for parsing URIs into options is defined in Section 6.4.
These steps result in zero or more Uri-Host, Uri-Port, Uri-Path and These steps result in zero or more Uri-Host, Uri-Port, Uri-Path, and
Uri-Query Options being included in a request, where each option Uri-Query Options being included in a request, where each option
holds the following values: holds the following values:
o the Uri-Host Option specifies the Internet host of the resource o the Uri-Host Option specifies the Internet host of the resource
being requested, being requested,
o the Uri-Port Option specifies the transport layer port number of o the Uri-Port Option specifies the transport-layer port number of
the resource, the resource,
o each Uri-Path Option specifies one segment of the absolute path to o each Uri-Path Option specifies one segment of the absolute path to
the resource, and the resource, and
o each Uri-Query Option specifies one argument parameterizing the o each Uri-Query Option specifies one argument parameterizing the
resource. resource.
Note: Fragments ([RFC3986], Section 3.5) are not part of the request Note: Fragments ([RFC3986], Section 3.5) are not part of the request
URI and thus will not be transmitted in a CoAP request. URI and thus will not be transmitted in a CoAP request.
skipping to change at page 52, line 47 skipping to change at page 54, line 21
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 examining 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
The Proxy-Uri Option is used to make a request to a forward-proxy The Proxy-Uri Option is used to make a request to a forward-proxy
(see Section 5.7). The forward-proxy is requested to forward the (see Section 5.7). The forward-proxy is requested to forward the
request or service it from a valid cache, and return the response. request or service it from a valid cache and return the response.
The option value is an absolute-URI ([RFC3986], Section 4.3). The option value is an absolute-URI ([RFC3986], Section 4.3).
Note that the forward-proxy MAY forward the request on to another Note that the forward-proxy MAY forward the request on to another
proxy or directly to the server specified by the absolute-URI. In proxy or directly to the server specified by the absolute-URI. In
order to avoid request loops, a proxy MUST be able to recognize all order to avoid request loops, a proxy MUST be able to recognize all
of its server names, including any aliases, local variations, and the of its server names, including any aliases, local variations, and the
numeric IP addresses. numeric IP addresses.
An endpoint receiving a request with a Proxy-Uri Option that is An endpoint receiving a request with a Proxy-Uri Option that is
unable or unwilling to act as a forward-proxy for the request MUST unable or unwilling to act as a forward-proxy for the request MUST
cause the return of a 5.05 (Proxying Not Supported) response. cause the return of a 5.05 (Proxying Not Supported) response.
The Proxy-Uri Option MUST take precedence over any of the Uri-Host, The Proxy-Uri Option MUST take precedence over any of the Uri-Host,
Uri-Port, Uri-Path or Uri-Query options (which MUST NOT be included Uri-Port, Uri-Path or Uri-Query options (each of which MUST NOT be
at the same time in a request containing the Proxy-Uri Option). included in a request containing the Proxy-Uri Option).
As a special case to simplify many proxy clients, the absolute-URI As a special case to simplify many proxy clients, the absolute-URI
can be constructed from the Uri-* options. When a Proxy-Scheme can be constructed from the Uri-* options. When a Proxy-Scheme
Option is present, the absolute-URI is constructed as follows: A CoAP Option is present, the absolute-URI is constructed as follows: a CoAP
URI is constructed from the Uri-* options as defined in Section 6.5. URI is constructed from the Uri-* options as defined in Section 6.5.
In the resulting URI, the initial scheme up to, but not including the In the resulting URI, the initial scheme up to, but not including,
following colon is then replaced by the content of the Proxy-Scheme the following colon is then replaced by the content of the Proxy-
Option. Note that this case is only applicable if the components of Scheme Option. Note that this case is only applicable if the
the desired URI other than the scheme component actually can be components of the desired URI other than the scheme component
expressed using Uri-* options; e.g., to represent a URI with a actually can be expressed using Uri-* options; for example, to
userinfo component in the authority, only Proxy-Uri can be used. represent a URI with a userinfo component in the authority, only
Proxy-Uri can be used.
5.10.3. Content-Format 5.10.3. Content-Format
The Content-Format Option indicates the representation format of the The Content-Format Option indicates the representation format of the
message payload. The representation format is given as a numeric message payload. The representation format is given as a numeric
content format identifier that is defined in the CoAP Content Format Content-Format identifier that is defined in the "CoAP Content-
Registry (Section 12.3). In the absence of the option, no default Formats" registry (Section 12.3). In the absence of the option, no
value is assumed, i.e. the representation format of any default 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-Formats" 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 returns the server to be in the Content-Format indicated. The server returns
the preferred Content-Format if available. If the preferred Content- the preferred Content-Format if available. If the preferred Content-
Format cannot be returned, then a 4.06 "Not Acceptable" MUST be sent Format cannot be returned, then a 4.06 "Not Acceptable" MUST be sent
as a response, unless another error code takes precedence for this as a response, unless another error code takes precedence for this
response. response.
5.10.5. Max-Age 5.10.5. Max-Age
skipping to change at page 54, line 39 skipping to change at page 56, line 11
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
version, checksum, hash or time. An endpoint receiving an entity-tag version, checksum, hash, or time. An endpoint receiving an entity-
MUST treat it as opaque and make no assumptions about its content or tag MUST treat it as opaque and make no assumptions about its content
structure. (Endpoints that generate an entity-tag are encouraged to or structure. (Endpoints that generate an entity-tag are encouraged
use the most compact representation possible, in particular in to use the most compact representation possible, in particular in
regards to clients and intermediaries that may want to store multiple regards to clients and intermediaries that may want to store multiple
ETag values.) ETag values.)
5.10.6.1. ETag as a Response Option 5.10.6.1. ETag as a Response Option
The ETag Option in a response provides the current value (i.e., after The ETag Option in a response provides the current value (i.e., after
the request was processed) of the entity-tag for the "tagged the request was processed) of the entity-tag for the "tagged
representation". If no Location-* options are present, the tagged representation". If no Location-* options are present, the tagged
representation is the selected representation (Section 5.5.3) of the representation is the selected representation (Section 5.5.3) of the
target resource. If one or more Location-* options are present and target resource. If one or more Location-* options are present and
skipping to change at page 55, line 26 skipping to change at page 56, line 47
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 multiple times in a request.
5.10.7. Location-Path and Location-Query 5.10.7. Location-Path and Location-Query
The Location-Path and Location-Query Options together indicate a The Location-Path and Location-Query Options together indicate a
relative URI that consists either of an absolute path, a query string relative URI that consists either of an absolute path, a query
or both. A combination of these options is included in a 2.01 string, or both. A combination of these options is included in a
(Created) response to indicate the location of the resource created 2.01 (Created) response to indicate the location of the resource
as the result of a POST request (see Section 5.8.2). The location is created as the result of a POST request (see Section 5.8.2). The
resolved relative to the request URI. location is resolved relative to the request URI.
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
collectively called Location-* options. Beyond Location-Path and collectively called Location-* options. Beyond Location-Path and
Location-Query, more Location-* options may be defined in the future, Location-Query, more Location-* options may be defined in the future
and have been reserved option numbers 128, 132, 136, and 140. If any and have been reserved option numbers 128, 132, 136, and 140. If any
of these reserved option numbers occurs in addition to Location-Path of these reserved option numbers occurs in addition to Location-Path
and/or Location-Query and are not supported, then a 4.02 (Bad Option) and/or Location-Query and are not supported, then a 4.02 (Bad Option)
error MUST be returned. error MUST be returned.
5.10.8. Conditional Request Options 5.10.8. Conditional Request Options
Conditional request options enable a client to ask the server to Conditional request options enable a client to ask the server to
perform the request only if certain conditions specified by the perform the request only if certain conditions specified by the
option are fulfilled. option are fulfilled.
For each of these options, if the condition given is not fulfilled, For each of these options, if the condition given is not fulfilled,
then the server MUST NOT perform the requested method. Instead, the then the server MUST NOT perform the requested method. Instead, the
server MUST respond with the 4.12 (Precondition Failed) response server MUST respond with the 4.12 (Precondition Failed) Response
code. Code.
If the condition is fulfilled, the server performs the request method If the condition is fulfilled, the server performs the request method
as if the conditional request options were not present. as if the conditional request options were not present.
If the request would, without the conditional request options, result If the request would, without the conditional request options, result
in anything other than a 2.xx or 4.12 response code, then any in anything other than a 2.xx or 4.12 Response Code, then any
conditional request options MAY be ignored. conditional request options MAY be ignored.
5.10.8.1. If-Match 5.10.8.1. If-Match
The If-Match Option MAY be used to make a request conditional on the The If-Match Option MAY be used to make a request conditional on the
current existence or value of an ETag for one or more representations current existence or value of an ETag for one or more representations
of the target resource. If-Match is generally useful for resource of the target resource. If-Match is generally useful for resource
update requests, such as PUT requests, as a means for protecting update requests, such as PUT requests, as a means for protecting
against accidental overwrites when multiple clients are acting in against accidental overwrites when multiple clients are acting in
parallel on the same resource (i.e., the "lost update" problem). parallel on the same resource (i.e., the "lost update" problem).
The value of an If-Match option is either an ETag or the empty The value of an If-Match option is either an ETag or the empty
string. An If-Match option with an ETag matches a representation string. An If-Match option with an ETag matches a representation
with that exact ETag. An If-Match option with an empty value matches with that exact ETag. An If-Match option with an empty value matches
any existing representation (i.e., it places the precondition on the any existing representation (i.e., it places the precondition on the
existence of any current representation for the target resource). existence of any current representation for the target resource).
The If-Match Option can occur multiple times. If any of the options The If-Match Option can occur multiple times. If any of the options
match, then the condition is fulfilled. match, then the condition is fulfilled.
If there is one or more If-Match Option, but none of the options If there is one or more If-Match Options, but none of the options
match, then the condition is not fulfilled. match, then the condition is not fulfilled.
5.10.8.2. If-None-Match 5.10.8.2. If-None-Match
The If-None-Match Option MAY be used to make a request conditional on The If-None-Match Option MAY be used to make a request conditional on
the non-existence of the target resource. If-None-Match is useful the nonexistence of the target resource. If-None-Match is useful for
for resource creation requests, such as PUT requests, as a means for resource creation requests, such as PUT requests, as a means for
protecting against accidental overwrites when multiple clients are protecting against accidental overwrites when multiple clients are
acting in parallel on the same resource. The If-None-Match Option acting in parallel on the same resource. The If-None-Match Option
carries no value. carries no value.
If the target resource does exist, then the condition is not If the target resource does exist, then the condition is not
fulfilled. fulfilled.
(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.)
5.10.9. Size1 Option 5.10.9. Size1 Option
The Size1 option provides size information about the resource The Size1 option provides size information about the resource
representation in a request. The option value is an integer number representation in a request. The option value is an integer number
of bytes. Its main use is with block-wise transfers of bytes. Its main use is with block-wise transfers [BLOCK]. In the
[I-D.ietf-core-block]. In the present specification, it is used in present specification, it is used in 4.13 responses (Section 5.9.2.9)
4.13 responses (Section 5.9.2.9) to indicate the maximum size of to indicate the maximum size of request entity that the server is
request entity that the server is able and willing to handle. able and willing to handle.
6. CoAP URIs 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 that
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
"https" URI schemes respectively. "https" URI schemes, respectively.
The syntax of the "coap" and "coaps" URI schemes is specified in this The syntax of the "coap" and "coaps" URI schemes is specified in this
section in Augmented Backus-Naur Form (ABNF) [RFC5234]. The section in Augmented Backus-Naur Form (ABNF) [RFC5234]. The
definitions of "host", "port", "path-abempty", "query", "segment", definitions of "host", "port", "path-abempty", "query", "segment",
"IP-literal", "IPv4address" and "reg-name" are adopted from "IP-literal", "IPv4address", and "reg-name" are adopted from
[RFC3986]. [RFC3986].
Implementation Note: Unfortunately, over time the URI format has Implementation Note: Unfortunately, over time, the URI format has
acquired significant complexity. Implementers are encouraged to acquired significant complexity. Implementers are encouraged to
examine [RFC3986] closely. E.g., the ABNF for IPv6 addresses is examine [RFC3986] closely. For example, the ABNF for IPv6
more complicated than maybe expected. Also, implementers should addresses is more complicated than maybe expected. Also,
take care to perform the processing of percent decoding/encoding implementers should take care to perform the processing of
exactly once on the way from a URI to its decoded components or percent-decoding or percent-encoding exactly once on the way from
back. Percent encoding is crucial for data transparency, but may a URI to its decoded components or back. Percent-encoding is
lead to unusual results such as a slash in a path component. crucial for data transparency but may lead to unusual results such
as a slash character in a path component.
6.1. coap URI Scheme 6.1. coap URI Scheme
coap-URI = "coap:" "//" host [ ":" port ] path-abempty [ "?" query ] coap-URI = "coap:" "//" host [ ":" port ] path-abempty [ "?" query ]
If the host component is provided as an IP-literal or IPv4address, If the host component is provided as an IP-literal or IPv4address,
then the CoAP server can be reached at that IP address. If host is a then the CoAP server can be reached at that IP address. If host is a
registered name, then that name is considered an indirect identifier registered name, then that name is considered an indirect identifier
and the endpoint might use a name resolution service, such as DNS, to and the endpoint might use a name resolution service, such as DNS, to
find the address of that host. The host MUST NOT be empty; if a URI find the address of that host. The host MUST NOT be empty; if a URI
skipping to change at page 59, line 8 skipping to change at page 60, line 19
The path identifies a resource within the scope of the host and port. The path identifies a resource within the scope of the host and port.
It consists of a sequence of path segments separated by a slash It consists of a sequence of path segments separated by a slash
character (U+002F SOLIDUS "/"). character (U+002F SOLIDUS "/").
The query serves to further parameterize the resource. It consists The query serves to further parameterize the resource. It consists
of a sequence of arguments separated by an ampersand character of a sequence of arguments separated by an ampersand character
(U+0026 AMPERSAND "&"). An argument is often in the form of a (U+0026 AMPERSAND "&"). An argument is often in the form of a
"key=value" pair. "key=value" pair.
The "coap" URI scheme supports the path prefix "/.well-known/" The "coap" URI scheme supports the path prefix "/.well-known/"
defined by [RFC5785] for "well-known locations" in the name-space of defined by [RFC5785] for "well-known locations" in the namespace of a
a host. This enables discovery of policy or other information about host. This enables discovery of policy or other information about a
a host ("site-wide metadata"), such as hosted resources (see host ("site-wide metadata"), such as hosted resources (see
Section 7). Section 7).
Application designers are encouraged to make use of short, but Application designers are encouraged to make use of short but
descriptive URIs. As the environments that CoAP is used in are descriptive URIs. As the environments that CoAP is used in are
usually constrained for bandwidth and energy, the trade-off between usually constrained for bandwidth and energy, the trade-off between
these two qualities should lean towards the shortness, without these two qualities should lean towards the shortness, without
ignoring descriptiveness. ignoring descriptiveness.
6.2. coaps URI Scheme 6.2. coaps URI Scheme
coaps-URI = "coaps:" "//" host [ ":" port ] path-abempty coaps-URI = "coaps:" "//" host [ ":" port ] path-abempty
[ "?" query ] [ "?" query ]
All of the requirements listed above for the "coap" scheme are also All of the requirements listed above for the "coap" scheme are also
requirements for the "coaps" scheme, except that a default UDP port requirements for the "coaps" scheme, except that a default UDP port
of [IANA_TBD_PORT] is assumed if the port subcomponent is empty or of 5684 is assumed if the port subcomponent is empty or not given,
not given, and the UDP datagrams MUST be secured through the use of and the UDP datagrams MUST be secured through the use of DTLS as
DTLS as described in Section 9.1. described in Section 9.1.
Considerations for caching of responses to "coaps" identified Considerations for caching of responses to "coaps" identified
requests are discussed in Section 11.2. requests are discussed in Section 11.2.
Resources made available via the "coaps" scheme have no shared Resources made available via the "coaps" scheme have no shared
identity with the "coap" scheme even if their resource identifiers identity with the "coap" scheme even if their resource identifiers
indicate the same authority (the same host listening to the same UDP indicate the same authority (the same host listening to the same UDP
port). They are distinct name spaces and are considered to be port). They are distinct namespaces and are considered to be
distinct origin servers. distinct origin servers.
6.3. Normalization and Comparison Rules 6.3. Normalization and Comparison Rules
Since the "coap" and "coaps" schemes conform to the URI generic Since the "coap" and "coaps" schemes conform to the URI generic
syntax, such URIs are normalized and compared according to the syntax, such URIs are normalized and compared according to the
algorithm defined in [RFC3986], Section 6, using the defaults algorithm defined in [RFC3986], Section 6, using the defaults
described above for each scheme. described above for each scheme.
If the port is equal to the default port for a scheme, the normal If the port is equal to the default port for a scheme, the normal
form is to elide the port subcomponent. Likewise, an empty path form is to elide the port subcomponent. Likewise, an empty path
component is equivalent to an absolute path of "/", so the normal component is equivalent to an absolute path of "/", so the normal
form is to provide a path of "/" instead. The scheme and host are form is to provide a path of "/" instead. The scheme and host are
case-insensitive and normally provided in lowercase; IP-literals are case insensitive and normally provided in lowercase; IP-literals are
in recommended form [RFC5952]; all other components are compared in a in recommended form [RFC5952]; all other components are compared in a
case-sensitive manner. Characters other than those in the "reserved" case-sensitive manner. Characters other than those in the "reserved"
set are equivalent to their percent-encoded bytes (see [RFC3986], set are equivalent to their percent-encoded bytes (see [RFC3986],
Section 2.1): the normal form is to not encode them. Section 2.1): the normal form is to not encode them.
For example, the following three URIs are equivalent, and cause the For example, the following three URIs are equivalent and cause the
same options and option values to appear in the CoAP messages: same options and option values to appear in the CoAP messages:
coap://example.com:5683/~sensors/temp.xml coap://example.com:5683/~sensors/temp.xml
coap://EXAMPLE.com/%7Esensors/temp.xml coap://EXAMPLE.com/%7Esensors/temp.xml
coap://EXAMPLE.com:/%7esensors/temp.xml coap://EXAMPLE.com:/%7esensors/temp.xml
6.4. Decomposing URIs into Options 6.4. Decomposing URIs into Options
The steps to parse a request's options from a string |url| are as The steps to parse a request's options from a string |url| are as
follows. These steps either result in zero or more of the Uri-Host, follows. These steps either result in zero or more of the Uri-Host,
Uri-Port, Uri-Path and Uri-Query Options being included in the Uri-Port, Uri-Path, and Uri-Query Options being included in the
request, or they fail. request or they fail.
1. If the |url| string is not an absolute URI ([RFC3986]), then fail 1. If the |url| string is not an absolute URI ([RFC3986]), then fail
this algorithm. this algorithm.
2. Resolve the |url| string using the process of reference 2. Resolve the |url| string using the process of reference
resolution defined by [RFC3986]. At this stage the URL is in resolution defined by [RFC3986]. At this stage, the URL is in
ASCII encoding [RFC0020], even though the decoded components will ASCII encoding [RFC0020], even though the decoded components will
be interpreted in UTF-8 [RFC3629] after step 5, 8 and 9. be interpreted in UTF-8 [RFC3629] after steps 5, 8, and 9.
NOTE: It doesn't matter what it is resolved relative to, since we NOTE: It doesn't matter what it is resolved relative to, since we
already know it is an absolute URL at this point. already know it is an absolute URL at this point.
3. If |url| does not have a <scheme> component whose value, when 3. If |url| does not have a <scheme> component whose value, when
converted to ASCII lowercase, is "coap" or "coaps", then fail converted to ASCII lowercase, is "coap" or "coaps", then fail
this algorithm. this algorithm.
4. If |url| has a <fragment> component, then fail this algorithm. 4. If |url| has a <fragment> component, then fail this algorithm.
5. If the <host> component of |url| does not represent the request's 5. If the <host> component of |url| does not represent the request's
destination IP address as an IP-literal or IPv4address, include a destination IP address as an IP-literal or IPv4address, include a
Uri-Host Option and let that option's value be the value of the Uri-Host Option and let that option's value be the value of the
<host> component of |url|, converted to ASCII lowercase, and then <host> component of |url|, converted to ASCII lowercase, and then
converting all percent-encodings ("%" followed by two hexadecimal convert all percent-encodings ("%" followed by two hexadecimal
digits) to the corresponding characters. digits) to the corresponding characters.
NOTE: In the usual case where the request's destination IP NOTE: In the usual case where the request's destination IP
address is derived from the host part, this ensures that a Uri- address is derived from the host part, this ensures that a Uri-
Host Option is only used for a <host> component of the form reg- Host Option is only used for a <host> component of the form reg-
name. name.
6. If |url| has a <port> component, then let |port| be that 6. If |url| has a <port> component, then let |port| be that
component's value interpreted as a decimal integer; otherwise, component's value interpreted as a decimal integer; otherwise,
let |port| be the default port for the scheme. let |port| be the default port for the scheme.
skipping to change at page 61, line 33 skipping to change at page 62, line 45
<query> component, include a Uri-Query Option and let that <query> component, include a Uri-Query Option and let that
option's value be the argument (not including the question mark option's value be the argument (not including the question mark
and the delimiting ampersand characters) after converting each and the delimiting ampersand characters) after converting each
percent-encoding to the corresponding byte. percent-encoding to the corresponding byte.
Note that these rules completely resolve any percent-encoding. Note that these rules completely resolve any percent-encoding.
6.5. Composing URIs from Options 6.5. Composing URIs from Options
The steps to construct a URI from a request's options are as follows. The steps to construct a URI from a request's options are as follows.
These steps either result in a URI, or they fail. In these steps, These steps either result in a URI or they fail. In these steps,
percent-encoding a character means replacing each of its (UTF-8 percent-encoding a character means replacing each of its
encoded) bytes by a "%" character followed by two hexadecimal digits (UTF-8-encoded) bytes by a "%" character followed by two hexadecimal
representing the byte, where the digits A-F are in upper case (as digits representing the byte, where the digits A-F are in uppercase
defined in [RFC3986] Section 2.1; to reduce variability, the (as defined in Section 2.1 of [RFC3986]; to reduce variability, the
hexadecimal notation for percent-encoding in CoAP URIs MUST use hexadecimal notation for percent-encoding in CoAP URIs MUST use
uppercase letters). The definitions of "unreserved" and "sub-delims" uppercase letters). The definitions of "unreserved" and "sub-delims"
are adopted from [RFC3986]. are adopted from [RFC3986].
1. If the request is secured using DTLS, let |url| be the string 1. If the request is secured using DTLS, let |url| be the string
"coaps://". Otherwise, let |url| be the string "coap://". "coaps://". Otherwise, let |url| be the string "coap://".
2. If the request includes a Uri-Host Option, let |host| be that 2. If the request includes a Uri-Host Option, let |host| be that
option's value, where any non-ASCII characters are replaced by option's value, where any non-ASCII characters are replaced by
their corresponding percent-encoding. If |host| is not a valid their corresponding percent-encoding. If |host| is not a valid
skipping to change at page 62, line 19 skipping to change at page 63, line 30
destination UDP port. destination UDP port.
5. If |port| is not the default port for the scheme, then append a 5. If |port| is not the default port for the scheme, then append a
single U+003A COLON character (:) followed by the decimal single U+003A COLON character (:) followed by the decimal
representation of |port| to |url|. representation of |port| to |url|.
6. Let |resource name| be the empty string. For each Uri-Path 6. Let |resource name| be the empty string. For each Uri-Path
Option in the request, append a single character U+002F SOLIDUS Option in the request, append a single character U+002F SOLIDUS
(/) followed by the option's value to |resource name|, after (/) followed by the option's value to |resource name|, after
converting any character that is not either in the "unreserved" converting any character that is not either in the "unreserved"
set, "sub-delims" set, a U+003A COLON (:) or U+0040 COMMERCIAL set, in the "sub-delims" set, a U+003A COLON (:) character, or a
AT (@) character, to its percent-encoded form. U+0040 COMMERCIAL AT (@) character to its percent-encoded form.
7. If |resource name| is the empty string, set it to a single 7. If |resource name| is the empty string, set it to a single
character U+002F SOLIDUS (/). character U+002F SOLIDUS (/).
8. For each Uri-Query Option in the request, append a single 8. For each Uri-Query Option in the request, append a single
character U+003F QUESTION MARK (?) (first option) or U+0026 character U+003F QUESTION MARK (?) (first option) or U+0026
AMPERSAND (&) (subsequent options) followed by the option's AMPERSAND (&) (subsequent options) followed by the option's
value to |resource name|, after converting any character that is value to |resource name|, after converting any character that is
not either in the "unreserved" set, "sub-delims" set (except not either in the "unreserved" set, in the "sub-delims" set
U+0026 AMPERSAND (&)), a U+003A COLON (:), U+0040 COMMERCIAL AT (except U+0026 AMPERSAND (&)), a U+003A COLON (:), a U+0040
(@), U+002F SOLIDUS (/) or U+003F QUESTION MARK (?) character, COMMERCIAL AT (@), a U+002F SOLIDUS (/), or a U+003F QUESTION
to its percent-encoded form. MARK (?) character to its percent-encoded form.
9. Append |resource name| to |url|. 9. Append |resource name| to |url|.
10. Return |url|. 10. Return |url|.
Note that these steps have been designed to lead to a URI in normal Note that these steps have been designed to lead to a URI in normal
form (see Section 6.3). form (see Section 6.3).
7. Discovery 7. Discovery
7.1. Service Discovery 7.1. Service Discovery
As a part of discovering the services offered by a CoAP server, a As a part of discovering the services offered by a CoAP server, a
client has to learn about the endpoint used by a server. client has to learn about the endpoint used by a server.
A server is discovered by a client by the client (knowing or) A server is discovered by a client (knowing or) learning a URI that
learning a URI that references a resource in the namespace of the references a resource in the namespace of the server. Alternatively,
server. Alternatively, clients can use Multicast CoAP (see clients can use multicast CoAP (see Section 8) and the "All CoAP
Section 8) and the "All CoAP Nodes" multicast address to find CoAP Nodes" multicast address to find CoAP servers.
servers.
Unless the port subcomponent in a "coap" or "coaps" URI indicates the Unless the port subcomponent in a "coap" or "coaps" URI indicates the
UDP port at which the CoAP server is located, the server is assumed UDP port at which the CoAP server is located, the server is assumed
to be reachable at the default port. to be reachable at the default port.
The CoAP default port number 5683 MUST be supported by a server that The CoAP default port number 5683 MUST be supported by a server that
offers resources for resource discovery (see Section 7.2 below) and offers resources for resource discovery (see Section 7.2 below) and
SHOULD be supported for providing access to other resources. The SHOULD be supported for providing access to other resources. The
default port number [IANA_TBD_PORT] for DTLS-secured CoAP MAY be default port number 5684 for DTLS-secured CoAP MAY be supported by a
supported by a server for resource discovery and for providing access server for resource discovery and for providing access to other
to other resources. In addition other endpoints may be hosted at resources. In addition, other endpoints may be hosted at other
other ports, e.g. in the dynamic port space. 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] and [RFC6282]. (Note that, as its UDP port differs
port, it is a different endpoint from the server at the default from the default port, it is a different endpoint from the server
port). at the default port.)
7.2. Resource Discovery 7.2. Resource Discovery
The discovery of resources offered by a CoAP endpoint is extremely The discovery of resources offered by a CoAP endpoint is extremely
important in machine-to-machine applications where there are no important in machine-to-machine applications where there are no
humans in the loop and static interfaces result in fragility. To humans in the loop and static interfaces result in fragility. To
maximize interoperability in a CoRE environment, a CoAP endpoint maximize interoperability in a CoRE environment, a CoAP endpoint
SHOULD support the CoRE Link Format of discoverable resources as SHOULD support the CoRE Link Format of discoverable resources as
described in [RFC6690], except where fully manual configuration is described in [RFC6690], except where fully manual configuration is
desired. It is up to the server which resources are made desired. It is up to the server which resources are made
discoverable (if any). discoverable (if any).
7.2.1. 'ct' Attribute 7.2.1. 'ct' Attribute
This section defines a new Web Linking [RFC5988] attribute for use This section defines a new Web Linking [RFC5988] attribute for use
with [RFC6690]. The Content-Format code "ct" attribute provides a with [RFC6690]. The Content-Format code "ct" attribute provides a
hint about the Content-Formats this resource returns. Note that this hint about the Content-Formats this resource returns. Note that this
is only a hint, and does not override the Content-Format Option of a is only a hint, and it does not override the Content-Format Option of
CoAP response obtained by actually requesting the representation of a CoAP response obtained by actually requesting the representation of
the resource. The value is in the CoAP identifier code format as a the resource. The value is in the CoAP identifier code format as a
decimal ASCII integer and MUST be in the range of 0-65535 (16-bit decimal ASCII integer and MUST be in the range of 0-65535 (16-bit
unsigned integer). For example application/xml would be indicated as unsigned integer). For example, "application/xml" would be indicated
"ct=41". If no Content-Format code attribute is present then nothing as "ct=41". If no Content-Format code attribute is present, then
about the type can be assumed. The Content-Format code attribute MAY nothing about the type can be assumed. The Content-Format code
include a space-separated sequence of Content-Format codes, attribute MAY include a space-separated sequence of Content-Format
indicating that multiple content-formats are available. The syntax codes, indicating that multiple content-formats are available. The
of the attribute value is summarized in the production ct-value in syntax of the attribute value is summarized in the production "ct-
Figure 12, where cardinal, SP and DQUOTE are defined as in [RFC6690]. value" in 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 an 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 [GROUPCOMM].
[I-D.ietf-core-groupcomm].
CoAP endpoints that offer services that they want other endpoints to CoAP endpoints that offer services that they want other endpoints to
be able to find using multicast service discovery, join one or more be able to find using multicast service discovery join one or more of
of the appropriate all-CoAP-nodes multicast addresses (Section 12.8) the appropriate all-CoAP-node multicast addresses (Section 12.8) and
and listen on the default CoAP port. Note that an endpoint might listen on the default CoAP port. Note that an endpoint might receive
receive multicast requests on other multicast addresses, including multicast requests on other multicast addresses, including the all-
the all-nodes IPv6 address (or via broadcast on IPv4); an endpoint nodes IPv6 address (or via broadcast on IPv4); an endpoint MUST
MUST therefore be prepared to receive such messages but MAY ignore therefore be prepared to receive such messages but MAY ignore them if
them if multicast service discovery is not desired. multicast service discovery is not desired.
8.1. Messaging Layer 8.1. Messaging Layer
A multicast request is characterized by being transported in a CoAP A multicast request is characterized by being transported in a CoAP
message that is addressed to an IP multicast address instead of a message that is addressed to an IP multicast address instead of a
CoAP endpoint. Such multicast requests MUST be Non-confirmable. CoAP endpoint. Such multicast requests MUST be Non-confirmable.
A server SHOULD be aware that a request arrived via multicast, e.g. A server SHOULD be aware that a request arrived via multicast, e.g.,
by making use of modern APIs such as IPV6_RECVPKTINFO [RFC3542], if by making use of modern APIs such as IPV6_RECVPKTINFO [RFC3542], if
available. available.
To avoid an implosion of error responses, when a server is aware that To avoid an implosion of error responses, when a server is aware that
a request arrived via multicast, it MUST NOT return a RST in reply to a request arrived via multicast, it MUST NOT return a Reset message
NON. If it is not aware, it MAY return a RST in reply to NON as in reply to a Non-confirmable message. If it is not aware, it MAY
usual. Because such a Reset message will look identical to an RST return a Reset message in reply to a Non-confirmable message as
for a unicast message from the sender, the sender MUST avoid using a usual. Because such a Reset message will look identical to one for a
unicast message from the sender, the sender MUST avoid using a
Message ID that is also still active from this endpoint with any Message ID that is also still active from this endpoint with any
unicast endpoint that might receive the multicast message. unicast endpoint that might receive the multicast message.
At the time of writing, multicast messages can only be carried in At the time of writing, multicast messages can only be carried in UDP
UDP, not in DTLS. This means that the security modes defined for not in DTLS. This means that the security modes defined for CoAP in
CoAP in this document are not applicable to multicast. this document are not applicable to multicast.
8.2. Request/Response Layer 8.2. Request/Response Layer
When a server is aware that a request arrived via multicast, the When a server is aware that a request arrived via multicast, the
server MAY always ignore the request, in particular if it doesn't server MAY always ignore the request, in particular if it doesn't
have anything useful to respond (e.g., if it only has an empty have anything useful to respond (e.g., if it only has an empty
payload or an error response). The decision for this may depend on payload or an error response). The decision for this may depend on
the application. (For example, in [RFC6690] query filtering, a the application. (For example, in query filtering as described in
server should not respond to a multicast request if the filter does [RFC6690], a server should not respond to a multicast request if the
not match. More examples are in [I-D.ietf-core-groupcomm].) filter does not match. More examples are in [GROUPCOMM].)
If a server does decide to respond to a multicast request, it should If a server does decide to respond to a multicast request, it should
not respond immediately. Instead, it should pick a duration for the not respond immediately. Instead, it should pick a duration for the
period of time during which it intends to respond. For purposes of period of time during which it intends to respond. For the purposes
this exposition, we call the length of this period the Leisure. The of this exposition, we call the length of this period the Leisure.
specific value of this Leisure may depend on the application, or MAY The specific value of this Leisure may depend on the application or
be derived as described below. The server SHOULD then pick a random MAY be derived as described below. The server SHOULD then pick a
point of time within the chosen Leisure period to send back the random point of time within the chosen leisure period to send back
unicast response to the multicast request. If further responses need the unicast response to the multicast request. If further responses
to be sent based on the same multicast address membership, a new need 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 For example, for a multicast request with link-local scope on a 2.4
IEEE 802.15.4 (6LoWPAN) network, G could be (relatively GHz 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.
When matching a response to a multicast request, only the token MUST When matching a response to a multicast request, only the token MUST
match; the source endpoint of the response does not need to (and will match; the source endpoint of the response does not need to (and will
not) be the same as the destination endpoint of the original request. not) be the same as the destination endpoint of the original request.
For the purposes of interpreting the Location-* options and any links For the purposes of interpreting the Location-* options and any links
embedded in the representation and, the request URI (base URI) embedded in the representation, the request URI (i.e., the base URI
relative to which the response is interpreted, is formed by replacing relative to which the response is interpreted) is formed by replacing
the multicast address in the Host component of the original request the multicast address in the Host component of the original request
URI by the literal IP address of the endpoint actually responding. URI by the literal IP address of the endpoint actually responding.
8.2.1. Caching 8.2.1. Caching
When a client makes a multicast request, it always makes a new When a client makes a multicast request, it always makes a new
request to the multicast group (since there may be new group members request to the multicast group (since there may be new group members
that joined meanwhile or ones that did not get the previous request). that joined meanwhile or ones that did not get the previous request).
It MAY update a cache with the received responses. Then it uses both It MAY update a cache with the received responses. Then, it uses
cached-still-fresh and 'new' responses as the result of the request. both cached-still-fresh and new responses as the result of the
request.
A response received in reply to a GET request to a multicast group A response received in reply to a GET request to a multicast group
MAY be used to satisfy a subsequent request on the related unicast MAY be used to satisfy a subsequent request on the related unicast
request URI. The unicast request URI is obtained by replacing the request URI. The unicast request URI is obtained by replacing the
authority part of the request URI with the transport layer source authority part of the request URI with the transport-layer source
address of the response message. address of the response message.
A cache MAY revalidate a response by making a GET request on the A cache MAY revalidate a response by making a GET request on the
related unicast request URI. related unicast request URI.
A GET request to a multicast group MUST NOT contain an ETag option. A GET request to a multicast group MUST NOT contain an ETag option.
A mechanism to suppress responses the client already has is left for A mechanism to suppress responses the client already has is left for
further study. further study.
8.2.2. Proxying 8.2.2. Proxying
When a forward-proxy receives a request with a Proxy-Uri or URI When a forward-proxy receives a request with a Proxy-Uri or URI
constructed from Proxy-Scheme that indicates a multicast address, the constructed from Proxy-Scheme that indicates a multicast address, the
proxy obtains a set of responses as described above and sends all proxy obtains a set of responses as described above and sends all
responses (both cached-still-fresh and new) back to the original responses (both cached-still-fresh and new) back to the original
client. client.
This specification does not provide a way to indicate the unicast- This specification does not provide a way to indicate the unicast-
modified request URI (base URI) in responses thus forwarded. modified request URI (base URI) in responses thus forwarded.
Proxying multicast requests is discussed in more detail in Proxying multicast requests is discussed in more detail in
[I-D.ietf-core-groupcomm]; one proposal to address the base URI issue [GROUPCOMM]; one proposal to address the base URI issue can be found
can be found in section 3 of [I-D.bormann-coap-misc]. in Section 3 of [CoAP-MISC].
9. Securing CoAP 9. Securing CoAP
This section defines the DTLS binding for CoAP. This section defines the DTLS binding for CoAP.
During the provisioning phase, a CoAP device is provided with the During the provisioning phase, a CoAP device is provided with the
security information that it needs, including keying materials and security information that it needs, including keying materials and
access control lists. This specification defines provisioning for access control lists. This specification defines provisioning for
the RawPublicKey mode in Section 9.1.3.2.1. At the end of the the RawPublicKey mode in Section 9.1.3.2.1. At the end of the
provisioning phase, the device will be in one of four security modes provisioning phase, the device will be in one of four security modes
with the following information for the given mode. The NoSec and with the following information for the given mode. The NoSec and
RawPublicKey modes are mandatory to implement for this specification. RawPublicKey modes are mandatory to implement for this specification.
NoSec: There is no protocol level security (DTLS is disabled). NoSec: There is no protocol-level security (DTLS is disabled).
Alternative techniques to provide lower layer security SHOULD be Alternative techniques to provide lower-layer security SHOULD be
used when appropriate. The use of IPsec is discussed in used when appropriate. The use of IPsec is discussed in
[I-D.bormann-core-ipsec-for-coap]. Certain link layers in use [IPsec-CoAP]. Certain link layers in use with constrained nodes
with constrained nodes also provide link layer security, which may also provide link-layer security, which may be appropriate with
be appropriate with proper key management. proper key management.
PreSharedKey: DTLS is enabled and there is a list of pre-shared keys PreSharedKey: DTLS is enabled, there is a list of pre-shared keys
[RFC4279] and each key includes a list of which nodes it can be [RFC4279], and each key includes a list of which nodes it can be
used to communicate with as described in Section 9.1.3.1. At the used to communicate with as described in Section 9.1.3.1. At the
extreme there may be one key for each node this CoAP node needs to extreme, there may be one key for each node this CoAP node needs
communicate with (1:1 node/key ratio). Conversely, if more than to communicate with (1:1 node/key ratio). Conversely, if more
two entities share a specific pre-shared key, this key only than two entities share a specific pre-shared key, this key only
enables the entities to authenticate as a member of that group and enables the entities to authenticate as a member of that group and
not as a specific peer. not as a specific peer.
RawPublicKey: DTLS is enabled and the device has an asymmetric key RawPublicKey: DTLS is enabled and the device has an asymmetric key
pair without a certificate (a raw public key) that is validated pair without a certificate (a raw public key) that is validated
using an out-of-band mechanism [I-D.ietf-tls-oob-pubkey] as using an out-of-band mechanism [RFC7250] as described in
described in Section 9.1.3.2. The device also has an identity Section 9.1.3.2. The device also has an identity calculated from
calculated from the public key and a list of identities of the the public key and a list of identities of the nodes it can
nodes it can communicate with. communicate with.
Certificate: DTLS is enabled and the device has an asymmetric key Certificate: DTLS is enabled and the device has an asymmetric key
pair with an X.509 certificate [RFC5280] that binds it to its pair with an X.509 certificate [RFC5280] that binds it to its
Authority Name and is signed by some common trust root as subject and is signed by some common trust root as described in
described in Section 9.1.3.3. The device also has a list of root Section 9.1.3.3. The device also has a list of root trust anchors
trust anchors that can be used for validating a certificate. that can be used for validating a certificate.
In the "NoSec" mode, the system simply sends the packets over normal In the "NoSec" mode, the system simply sends the packets over normal
UDP over IP and is indicated by the "coap" scheme and the CoAP UDP over IP and is indicated by the "coap" scheme and the CoAP
default port. The system is secured only by keeping attackers from default port. The system is secured only by keeping attackers from
being able to send or receive packets from the network with the CoAP being able to send or receive packets from the network with the CoAP
nodes; see Section 11.5 for an additional complication with this nodes; see Section 11.5 for an additional complication with this
approach. approach.
The other three security modes are achieved using DTLS and are The other three security modes are achieved using DTLS and are
indicated by the "coaps" scheme and DTLS-secured CoAP default port. indicated by the "coaps" scheme and DTLS-secured CoAP default port.
The result is a security association that can be used to authenticate The result is a security association that can be used to authenticate
(within the limits of the security model) and, based on this (within the limits of the security model) and, based on this
authentication, authorize the communication partner. CoAP itself authentication, authorize the communication partner. CoAP itself
does not provide protocol primitives for authentication or does not provide protocol primitives for authentication or
authorization; where this is required, it can either be provided by authorization; where this is required, it can either be provided by
communication security (i.e., IPsec or DTLS) or by object security communication security (i.e., IPsec or DTLS) or by object security
(within the payload). Devices that require authorization for certain (within the payload). Devices that require authorization for certain
operations are expected to require one of these two forms of operations are expected to require one of these two forms of
security. Necessarily, where an intermediary is involved, security. Necessarily, where an intermediary is involved,
communication security only works when that intermediary is part of communication security only works when that intermediary is part of
the trust relationships; CoAP does not provide a way to forward the trust relationships. CoAP does not provide a way to forward
different levels of authorization that clients may have with an different levels of authorization that clients may have with an
intermediary to further intermediaries or origin servers -- it intermediary to further intermediaries or origin servers -- it
therefore may be required to perform all authorization at the first therefore may be required to perform all authorization at the first
intermediary. intermediary.
9.1. DTLS-secured CoAP 9.1. DTLS-Secured CoAP
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. In practice, DTLS is 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
approximately 13 bytes, not including any initialization vectors/ approximately 13 bytes, not including any initialization vectors/
nonces (e.g., 8 bytes with TLS_PSK_WITH_AES_128_CCM_8 [RFC6655]), nonces (e.g., 8 bytes with TLS_PSK_WITH_AES_128_CCM_8 [RFC6655]),
integrity check values (e.g., 8 bytes with TLS_PSK_WITH_AES_128_CCM_8 integrity check values (e.g., 8 bytes with TLS_PSK_WITH_AES_128_CCM_8
[RFC6655]) and padding required by the cipher suite. Whether and [RFC6655]), and padding required by the cipher suite. Whether the
which mode of using DTLS is applicable for a CoAP-based application use of a given mode of DTLS is applicable for a CoAP-based
should be carefully weighed considering the specific cipher suites application should be carefully weighed considering the specific
that may be applicable, and whether the session maintenance makes it cipher suites that may be applicable, whether the session maintenance
compatible with application flows and sufficient resources are makes it compatible with application flows, and whether sufficient
available on the constrained nodes and for the added network resources are available on the constrained nodes and for the added
overhead. (For some modes of using DTLS, this specification network overhead. (For some modes of using DTLS, this specification
identifies a mandatory to implement cipher suite. This is an identifies a mandatory-to-implement cipher suite. This is an
implementation requirement to maximize interoperability in those implementation requirement to maximize interoperability in those
cases where these cipher suites are indeed appropriate. The specific cases where these cipher suites are indeed appropriate. The specific
security policies of an application may determine the actual (set of) security policies of an application may determine the actual set of
cipher suites that can be used.) DTLS is not applicable to group cipher suites that can be used.) DTLS is not applicable to group
keying (multicast communication); however, it may be a component in a keying (multicast communication); however, it may be a component in a
future group key management protocol. future group key management protocol.
9.1.1. Messaging Layer 9.1.1. Messaging Layer
The endpoint acting as the CoAP client should also act as the DTLS The endpoint acting as the CoAP client should also act as the DTLS
client. It should initiate a session to the server on the client. It should initiate a session to the server on the
appropriate port. When the DTLS handshake has finished, the client appropriate port. When the DTLS handshake has finished, the client
may initiate the first CoAP request. All CoAP messages MUST be sent may initiate the first CoAP request. All CoAP messages MUST be sent
as DTLS "application data". as DTLS "application data".
The following rules are added for matching an ACK or RST to a CON The following rules are added for matching an Acknowledgement message
message or a RST to a NON message: The DTLS session MUST be the same or Reset message to a Confirmable message, or a Reset message to a
and the epoch MUST be the same. Non-confirmable message: The DTLS session MUST be the same, and the
epoch MUST be the same.
A message is the same when it is sent within the same DTLS session A message is the same when it is sent within the same DTLS session
and same epoch and has the same Message ID. and same epoch and has the same Message ID.
Note: When a Confirmable message is retransmitted, a new DTLS Note: When a Confirmable message is retransmitted, a new DTLS
sequence_number is used for each attempt, even though the CoAP sequence_number is used for each attempt, even though the CoAP
Message ID stays the same. So a recipient still has to perform Message ID stays the same. So a recipient still has to perform
deduplication as described in Section 4.5. Retransmissions MUST NOT deduplication as described in Section 4.5. Retransmissions MUST NOT
be performed across epochs. be performed across epochs.
DTLS connections in RawPublicKey and Certificate mode are set up DTLS connections in RawPublicKey and Certificate mode are set up
using mutual authentication so they can remain up and be reused for using mutual authentication so they can remain up and be reused for
future message exchanges in either direction. Devices can close a future message exchanges in either direction. Devices can close a
DTLS connection when they need to recover resources but in general DTLS connection when they need to recover resources, but in general
they should keep the connection up for as long as possible. Closing they should keep the connection up for as long as possible. Closing
the DTLS connection after every CoAP message exchange is very the DTLS connection after every CoAP message exchange is very
inefficient. inefficient.
9.1.2. Request/Response Layer 9.1.2. Request/Response Layer
The following rules are added for matching a response to a request: The following rules are added for matching a response to a request:
The DTLS session MUST be the same and the epoch MUST be the same. The DTLS session MUST be the same, and the epoch MUST be the same.
This means the response to a DTLS secured request MUST always be DTLS 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 therefore MUST be rejected (unless it does match an
therefore MUST be rejected. unrelated NoSec request).
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 their authority in the SNI HostName field as defined in Section 3 of
Section 3 of [RFC6066]. This is needed so that when a host that acts [RFC6066]. This is needed so that when a host that acts as a virtual
as a virtual server for multiple Authorities receives a new DTLS server for multiple Authorities receives a new DTLS connection, it
connection, it knows which keys to use for the DTLS session. knows which keys to use for the DTLS session.
9.1.3.1. Pre-Shared Keys 9.1.3.1. Pre-Shared Keys
When forming a connection to a new node, the system selects an When forming a connection to a new node, the system selects an
appropriate key based on which nodes it is trying to reach and then appropriate key based on which nodes it is trying to reach and then
forms a DTLS session using a PSK (Pre-Shared Key) mode of DTLS. forms a DTLS session using a PSK (Pre-Shared Key) mode of DTLS.
Implementations in these modes MUST support the mandatory to Implementations in these modes MUST support the mandatory-to-
implement cipher suite TLS_PSK_WITH_AES_128_CCM_8 as specified in implement cipher suite TLS_PSK_WITH_AES_128_CCM_8 as specified in
[RFC6655]. [RFC6655].
Depending on the commissioning model, applications may need to define Depending on the commissioning model, applications may need to define
an application profile for identity hints as required and detailed in an application profile for identity hints (as required and detailed
[RFC4279] (Section 5.2) to enable the use of PSK identity hints. in Section 5.2 of [RFC4279]) to enable the use of PSK identity hints.
The security considerations of [RFC4279] (Section 7) apply. In The security considerations of Section 7 of [RFC4279] apply. In
particular, applications should carefully weigh whether they need particular, applications should carefully weigh whether or not they
Perfect Forward Secrecy (PFS) or not and select an appropriate cipher need Perfect Forward Secrecy (PFS) and select an appropriate cipher
suite (7.1). The entropy of the PSK must be sufficient to mitigate suite (Section 7.1 of [RFC4279]). The entropy of the PSK must be
against brute-force and (where the PSK is not chosen randomly but by sufficient to mitigate against brute-force and (where the PSK is not
a human) dictionary attacks (7.2). The cleartext communication of chosen randomly but by a human) dictionary attacks (Section 7.2 of
client identities may leak data or compromise privacy (7.3). [RFC4279]). The cleartext communication of client identities may
leak data or compromise privacy (Section 7.3 of [RFC4279]).
9.1.3.2. Raw Public Key Certificates 9.1.3.2. Raw Public Key Certificates
In this mode the device has an asymmetric key pair but without an In this mode, the device has an asymmetric key pair but without an
X.509 certificate (called a raw public key); e.g., the asymmetric key X.509 certificate (called a raw public key); for example, the
pair is generated by the manufacturer and installed on the device asymmetric key pair is generated by the manufacturer and installed on
(see also Section 11.6). A device MAY be configured with multiple the device (see also Section 11.6). A device MAY be configured with
raw public keys. The type and length of the raw public key depends multiple raw public keys. The type and length of the raw public key
on the cipher suite used. Implementations in RawPublicKey mode MUST depends on the cipher suite used. Implementations in RawPublicKey
support the mandatory to implement cipher suite mode MUST support the mandatory-to-implement cipher suite
TLS_ECDHE_ECDSA_WITH_AES_128_CCM_8 as specified in TLS_ECDHE_ECDSA_WITH_AES_128_CCM_8 as specified in [RFC7251],
[I-D.mcgrew-tls-aes-ccm-ecc], [RFC5246], [RFC4492]. The key used [RFC5246], and [RFC4492]. The key used MUST be ECDSA capable. The
MUST be ECDSA-capable. The curve secp256r1 MUST be supported curve secp256r1 MUST be supported [RFC4492]; this curve is equivalent
[RFC4492]; this curve is equivalent to the NIST P-256 curve. The to the NIST P-256 curve. The hash algorithm is SHA-256.
hash algorithm is SHA-256. Implementations MUST use the Supported Implementations MUST use the Supported Elliptic Curves and Supported
Elliptic Curves Extension and Supported Point Format extensions Point Formats Extensions [RFC4492]; the uncompressed point format
[RFC4492]; the uncompressed point format MUST be supported; [RFC6090] MUST be supported; [RFC6090] can be used as an implementation method.
can be used as an implementation method. Some guidance relevant to Some guidance relevant to the implementation of this cipher suite can
the implementation of this cipher suite can be found in [W3CXMLSEC]. be found in [W3CXMLSEC]. The mechanism for using raw public keys
The mechanism for using raw public keys with TLS is specified in with TLS is specified in [RFC7250].
[I-D.ietf-tls-oob-pubkey].
Implementation Note: Specifically, this means the extensions listed Implementation Note: Specifically, this means the extensions listed
in Figure 14 with at least the values listed will be present in in Figure 14 with at least the values listed will be present in
the DTLS handshake. the DTLS handshake.
Extension: elliptic_curves Extension: elliptic_curves
Type: elliptic_curves (0x000a) Type: elliptic_curves (0x000a)
Length: 4 Length: 4
Elliptic Curves Length: 2 Elliptic Curves Length: 2
Elliptic curves (1 curve) Elliptic curves (1 curve)
skipping to change at page 71, line 34 skipping to change at page 72, line 50
Elliptic curves point formats (1) Elliptic curves point formats (1)
EC point format: uncompressed (0) EC point format: uncompressed (0)
Extension: signature_algorithms Extension: signature_algorithms
Type: signature_algorithms (0x000d) Type: signature_algorithms (0x000d)
Length: 4 Length: 4
Data (4 bytes): 00 02 04 03 Data (4 bytes): 00 02 04 03
HashAlgorithm: sha256 (4) HashAlgorithm: sha256 (4)
SignatureAlgorithm: ecdsa (3) SignatureAlgorithm: ecdsa (3)
Figure 14: DTLS extensions present for Figure 14: DTLS Extensions Present for
TLS_ECDHE_ECDSA_WITH_AES_128_CCM_8 TLS_ECDHE_ECDSA_WITH_AES_128_CCM_8
9.1.3.2.1. Provisioning 9.1.3.2.1. Provisioning
The RawPublicKey mode was designed to be easily provisioned in M2M The RawPublicKey mode was designed to be easily provisioned in M2M
deployments. It is assumed that each device has an appropriate deployments. It is assumed that each device has an appropriate
asymmetric public key pair installed. An identifier is calculated by asymmetric public key pair installed. An identifier is calculated by
the endpoint from the public key as described in Section 2 of the endpoint from the public key as described in Section 2 of
[RFC6920]. All implementations that support checking RawPublicKey [RFC6920]. All implementations that support checking RawPublicKey
identities MUST support at least the sha-256-120 mode (SHA-256 identities MUST support at least the sha-256-120 mode (SHA-256
truncated to 120 bits). Implementations SHOULD support also longer truncated to 120 bits). Implementations SHOULD also support longer
length identifiers and MAY support shorter lengths. Note that the length identifiers and MAY support shorter lengths. Note that the
shorter lengths provide less security against attacks and their use shorter lengths provide less security against attacks, and their use
is NOT RECOMMENDED. is NOT RECOMMENDED.
Depending on how identifiers are given to the system that verifies Depending on how identifiers are given to the system that verifies
them, support for URI, binary, and/or human-speakable format them, support for URI, binary, and/or human-speakable format
[RFC6920] needs to be implemented. All implementations SHOULD [RFC6920] needs to be implemented. All implementations SHOULD
support the binary mode and implementations that have a user support the binary mode, and implementations that have a user
interface SHOULD also support the human-speakable format. interface SHOULD also support the human-speakable format.
During provisioning, the identifier of each node is collected, for During provisioning, the identifier of each node is collected, for
example by reading a barcode on the outside of the device or by example, by reading a barcode on the outside of the device or by
obtaining a pre-compiled list of the identifiers. These identifiers obtaining a pre-compiled list of the identifiers. These identifiers
are then installed in the corresponding endpoint, for example an M2M are then installed in the corresponding endpoint, for example, an M2M
data collection server. The identifier is used for two purposes, to data collection server. The identifier is used for two purposes, to
associate the endpoint with further device information and to perform associate the endpoint with further device information and to perform
access control. During (initial and ongoing) provisioning, an access access control. During (initial and ongoing) provisioning, an access
control list of identifiers the device may start DTLS sessions with control list of identifiers with which the device may start DTLS
SHOULD also be installed and maintained. sessions SHOULD also be installed and maintained.
9.1.3.3. X.509 Certificates 9.1.3.3. X.509 Certificates
Implementations in Certificate Mode MUST support the mandatory to Implementations in Certificate Mode MUST support the mandatory-to-
implement cipher suite TLS_ECDHE_ECDSA_WITH_AES_128_CCM_8 as implement cipher suite TLS_ECDHE_ECDSA_WITH_AES_128_CCM_8 as
specified in [I-D.mcgrew-tls-aes-ccm-ecc], [RFC5246], [RFC4492]. specified in [RFC7251], [RFC5246], and [RFC4492]. Namely, the
Namely, the certificate includes a SubjectPublicKeyInfo that certificate includes a SubjectPublicKeyInfo that indicates an
indicates an algorithm of id-ecPublicKey with namedCurves secp256r1 algorithm of id-ecPublicKey with namedCurves secp256r1 [RFC5480]; the
[RFC5480]; the public key format is uncompressed [RFC5480]; the hash public key format is uncompressed [RFC5480]; the hash algorithm is
algorithm is SHA-256; if included the key usage extension indicates SHA-256; if included, the key usage extension indicates
digitalSignature. Certificates MUST be signed with ECDSA using digitalSignature. Certificates MUST be signed with ECDSA using
secp256r1, and the signature MUST use SHA-256. The key used MUST be secp256r1, and the signature MUST use SHA-256. The key used MUST be
ECDSA-capable. The curve secp256r1 MUST be supported [RFC4492]; this ECDSA capable. The curve secp256r1 MUST be supported [RFC4492]; this
curve is equivalent to the NIST P-256 curve. The hash algorithm is curve is equivalent to the NIST P-256 curve. The hash algorithm is
SHA-256. Implementations MUST use the Supported Elliptic Curves SHA-256. Implementations MUST use the Supported Elliptic Curves and
Extension and Supported Point Format extensions [RFC4492]; the Supported Point Formats Extensions [RFC4492]; the uncompressed point
uncompressed point format MUST be supported; [RFC6090] can be used as format MUST be supported; [RFC6090] can be used as an implementation
an implementation method. method.
The Authority Name in the certificate would be built out of a long The subject in the certificate would be built out of a long-term
term unique identifier for the device such as the EUI-64 [EUI64]. unique identifier for the device such as the EUI-64 [EUI64]. The
The Authority Name could also be based on the FQDN that was used as subject could also be based on the Fully Qualified Domain Name (FQDN)
the Host part of the CoAP URI. However, the device's IP address that was used as the Host part of the CoAP URI. However, the
should not typically be used as the Authority name as it would change device's IP address should not typically be used as the subject, as
over time. The discovery process used in the system would build up it would change over time. The discovery process used in the system
the mapping between IP addresses of the given devices and the would build up the mapping between IP addresses of the given devices
Authority Name for each device. Some devices could have more than and the subject for each device. Some devices could have more than
one Authority and would need more than a single certificate. one subject and would need more than a single certificate.
When a new connection is formed, the certificate from the remote When a new connection is formed, the certificate from the remote
device needs to be verified. If the CoAP node has a source of device needs to be verified. If the CoAP node has a source of
absolute time, then the node SHOULD check that the validity dates of absolute time, then the node SHOULD check that the validity dates of
the certificate are within range. The certificate MUST be validated the certificate are within range. The certificate MUST be validated
as appropriate for the security requirements, using functionality as appropriate for the security requirements, using functionality
equivalent to the algorithm specified in [RFC5280] section 6. If the equivalent to the algorithm specified in Section 6 of [RFC5280]. If
certificate contains a SubjectAltName, then the Authority Name MUST the certificate contains a SubjectAltName, then the authority of the
match at least one of the authority names of any CoAP URI found in a request URI MUST match at least one of the authorities of any CoAP
field of URI type in the SubjectAltName set. If there is no URI found in a field of URI type in the SubjectAltName set. If there
SubjectAltName in the certificate, then the Authoritative Name MUST is no SubjectAltName in the certificate, then the authority of the
match the CN found in the certificate using the matching rules request URI MUST match the Common Name (CN) found in the certificate
defined in [RFC2818] with the exception that certificates with using the matching rules defined in [RFC3280] with the exception that
wildcards are not allowed. certificates with wildcards are not allowed.
CoRE support for certificate status checking requires further study. CoRE support for certificate status checking requires further study.
As a mapping of OCSP [RFC2560] onto CoAP is not currently defined and As a mapping of the Online Certificate Status Protocol (OCSP)
OCSP may also not be easily applicable in all environments, an [RFC6960] onto CoAP is not currently defined and OCSP may also not be
alternative approach may be using the TLS Certificate Status Request easily applicable in all environments, an alternative approach may be
extension ([RFC6066] section 8, also known as "OCSP stapling") or using the TLS Certificate Status Request extension (Section 8 of
preferably the Multiple Certificate Status Extension [RFC6066]; also known as "OCSP stapling") or preferably the Multiple
([I-D.ietf-tls-multiple-cert-status-extension]), if available. Certificate Status Extension ([RFC6961]), if available.
If the system has a shared key in addition to the certificate, then a If the system has a shared key in addition to the certificate, then a
cipher suite that includes the shared key such as cipher suite that includes the shared key such as
TLS_ECDHE_PSK_WITH_AES_128_CBC_SHA [RFC5489] SHOULD be used. TLS_ECDHE_PSK_WITH_AES_128_CBC_SHA [RFC5489] SHOULD be used.
10. Cross-Protocol Proxying between CoAP and HTTP 10. Cross-Protocol Proxying between CoAP and HTTP
CoAP supports a limited subset of HTTP functionality, and thus cross- CoAP supports a limited subset of HTTP functionality, and thus cross-
protocol proxying to HTTP is straightforward. There might be several protocol proxying to HTTP is straightforward. There might be several
reasons for proxying between CoAP and HTTP, for example when reasons for proxying between CoAP and HTTP, for example, when
designing a web interface for use over either protocol or when designing a web interface for use over either protocol or when
realizing a CoAP-HTTP proxy. Likewise, CoAP could equally be proxied realizing a CoAP-HTTP proxy. Likewise, CoAP could equally be proxied
to other protocols such as XMPP [RFC6120] or SIP [RFC3264]; the to other protocols such as XMPP [RFC6120] or SIP [RFC3264]; the
definition of these mechanisms is out of scope of this specification. definition of these mechanisms is out of scope for this
specification.
There are two possible directions to access a resource via a forward- There are two possible directions to access a resource via a forward-
proxy: proxy:
CoAP-HTTP Proxying: Enables CoAP clients to access resources on HTTP CoAP-HTTP Proxying: Enables CoAP clients to access resources on HTTP
servers through an intermediary. This is initiated by including servers through an intermediary. This is initiated by including
the Proxy-Uri or Proxy-Scheme Option with an "http" or "https" URI the Proxy-Uri or Proxy-Scheme Option with an "http" or "https" URI
in a CoAP request to a CoAP-HTTP proxy. in a CoAP request to a CoAP-HTTP proxy.
HTTP-CoAP Proxying: Enables HTTP clients to access resources on CoAP HTTP-CoAP Proxying: Enables HTTP clients to access resources on CoAP
servers through an intermediary. This is initiated by specifying servers through an intermediary. This is initiated by specifying
a "coap" or "coaps" URI in the Request-Line of an HTTP request to a "coap" or "coaps" URI in the Request-Line of an HTTP request to
an HTTP-CoAP proxy. an HTTP-CoAP proxy.
Either way, only the Request/Response model of CoAP is mapped to Either way, only the request/response model of CoAP is mapped to
HTTP. The underlying model of Confirmable or Non-confirmable HTTP. The underlying model of Confirmable or Non-confirmable
messages, etc., is invisible and MUST have no effect on a proxy messages, etc., is invisible and MUST have no effect on a proxy
function. The following sections describe the handling of requests function. The following sections describe the handling of requests
to a forward-proxy. Reverse proxies are not specified as the proxy to a forward-proxy. Reverse-proxies are not specified, as the proxy
function is transparent to the client with the proxy acting as if it function is transparent to the client with the proxy acting as if it
was the origin server. However, similar considerations apply to were the origin server. However, similar considerations apply to
reverse-proxies as to forward-proxies, and there generally will be an reverse-proxies as to forward-proxies, and there generally will be an
expectation that reverse-proxies operate in a similar way forward- expectation that reverse-proxies operate in a similar way forward-
proxies would. As an implementation note, HTTP client libraries may proxies would. As an implementation note, HTTP client libraries may
make it hard to operate an HTTP-CoAP forward proxy by not providing a make it hard to operate an HTTP-CoAP forward-proxy by not providing a
way to put a CoAP URI on the HTTP Request-Line; reverse-proxying may way to put a CoAP URI on the HTTP Request-Line; reverse-proxying may
therefore lead to wider applicability of a proxy. A separate therefore lead to wider applicability of a proxy. A separate
specification may define a convention for URIs operating such a HTTP- specification may define a convention for URIs operating such an
CoAP reverse proxy [I-D.castellani-core-http-mapping]. HTTP-CoAP reverse-proxy [MAPPING].
10.1. CoAP-HTTP Proxying 10.1. CoAP-HTTP Proxying
If a request contains a Proxy-Uri or Proxy-Scheme Option with an If a request contains a Proxy-Uri or Proxy-Scheme Option with an
'http' or 'https' URI [RFC2616], then the receiving CoAP endpoint 'http' or 'https' URI [RFC2616], then the receiving CoAP endpoint
(called "the proxy" henceforth) is requested to perform the operation (called "the proxy" henceforth) is requested to perform the operation
specified by the request method on the indicated HTTP resource and specified by the request method on the indicated HTTP resource and
return the result to the client. (See also Section 5.7 for how the return the result to the client. (See also Section 5.7 for how the
request to the proxy is formulated, including security requirements.) request to the proxy is formulated, including security requirements.)
This section specifies for any CoAP request the CoAP response that This section specifies for any CoAP request the CoAP response that
the proxy should return to the client. How the proxy actually the proxy should return to the client. How the proxy actually
satisfies the request is an implementation detail, although the satisfies the request is an implementation detail, although the
typical case is expected to be the proxy translating and forwarding typical case is expected to be that the proxy translates and forwards
the request to an HTTP origin server. the request to an HTTP origin server.
Since HTTP and CoAP share the basic set of request methods, Since HTTP and CoAP share the basic set of request methods,
performing a CoAP request on an HTTP resource is not so different performing a CoAP request on an HTTP resource is not so different
from performing it on a CoAP resource. The meanings of the from performing it on a CoAP resource. The meanings of the
individual CoAP methods when performed on HTTP resources are individual CoAP methods when performed on HTTP resources are
explained in the subsections of this section. explained in the subsections of this section.
If the proxy is unable or unwilling to service a request with an HTTP If the proxy is unable or unwilling to service a request with an HTTP
URI, a 5.05 (Proxying Not Supported) response is returned to the URI, a 5.05 (Proxying Not Supported) response is returned to the
skipping to change at page 74, line 49 skipping to change at page 76, line 24
third party (such as the HTTP origin server) and is unable to obtain third party (such as the HTTP origin server) and is unable to obtain
a result within a reasonable time frame, a 5.04 (Gateway Timeout) a result within a reasonable time frame, a 5.04 (Gateway Timeout)
response is returned; if a result can be obtained but is not response is returned; if a result can be obtained but is not
understood, a 5.02 (Bad Gateway) response is returned. understood, a 5.02 (Bad Gateway) response is returned.
10.1.1. GET 10.1.1. GET
The GET method requests the proxy to return a representation of the The GET method requests the proxy to return a representation of the
HTTP resource identified by the request URI. HTTP resource identified by the request URI.
Upon success, a 2.05 (Content) response code SHOULD be returned. The Upon success, a 2.05 (Content) Response Code SHOULD be returned. The
payload of the response MUST be a representation of the target HTTP payload of the response MUST be a representation of the target HTTP
resource, and the Content-Format Option be set accordingly. The resource, and the Content-Format Option MUST be set accordingly. The
response MUST indicate a Max-Age value that is no greater than the response MUST indicate a Max-Age value that is no greater than the
remaining time the representation can be considered fresh. If the remaining time the representation can be considered fresh. If the
HTTP entity has an entity tag, the proxy SHOULD include an ETag HTTP entity has an entity-tag, the proxy SHOULD include an ETag
Option in the response and process ETag Options in requests as Option in the response and process ETag Options in requests as
described below. described below.
A client can influence the processing of a GET request by including A client can influence the processing of a GET request by including
the following option: the following option:
Accept: The request MAY include an Accept Option, identifying the Accept: The request MAY include an Accept Option, identifying the
preferred response content-format. preferred response content-format.
ETag: The request MAY include one or more ETag Options, identifying ETag: The request MAY include one or more ETag Options, identifying
responses that the client has stored. This requests the proxy to responses that the client has stored. This requests the proxy to
send a 2.03 (Valid) response whenever it would send a 2.05 send a 2.03 (Valid) response whenever it would send a 2.05
(Content) response with an entity tag in the requested set (Content) response with an entity-tag in the requested set
otherwise. Note that CoAP ETags are always strong ETags in the otherwise. Note that CoAP ETags are always strong ETags in the
HTTP sense; CoAP does not have the equivalent of HTTP weak ETags, HTTP sense; CoAP does not have the equivalent of HTTP weak ETags,
and there is no good way to make use of these in a cross-proxy. and there is no good way to make use of these in a cross-proxy.
10.1.2. PUT 10.1.2. PUT
The PUT method requests the proxy to update or create the HTTP The PUT method requests the proxy to update or create the HTTP
resource identified by the request URI with the enclosed resource identified by the request URI with the enclosed
representation. representation.
If a new resource is created at the request URI, a 2.01 (Created) If a new resource is created at the request URI, a 2.01 (Created)
response MUST be returned to the client. If an existing resource is response MUST be returned to the client. If an existing resource is
modified, a 2.04 (Changed) response MUST be returned to indicate modified, a 2.04 (Changed) response MUST be returned to indicate
successful completion of the request. successful completion of the request.
10.1.3. DELETE 10.1.3. DELETE
The DELETE method requests the proxy to delete the HTTP resource The DELETE method requests the proxy to delete the HTTP resource
identified by the request URI at the HTTP origin server. identified by the request URI at the HTTP origin server.
A 2.02 (Deleted) response MUST be returned to client upon success or A 2.02 (Deleted) response MUST be returned to the client upon success
if the resource does not exist at the time of the request. or if the resource does not exist at the time of the request.
10.1.4. POST 10.1.4. POST
The POST method requests the proxy to have the representation The POST method requests the proxy to have the representation
enclosed in the request be processed by the HTTP origin server. The enclosed in the request be processed by the HTTP origin server. The
actual function performed by the POST method is determined by the actual function performed by the POST method is determined by the
origin server and dependent on the resource identified by the request origin server and dependent on the resource identified by the request
URI. URI.
If the action performed by the POST method does not result in a If the action performed by the POST method does not result in a
resource that can be identified by a URI, a 2.04 (Changed) response resource that can be identified by a URI, a 2.04 (Changed) response
MUST be returned to the client. If a resource has been created on MUST be returned to the client. If a resource has been created on
the origin server, a 2.01 (Created) response MUST be returned. the origin server, a 2.01 (Created) response MUST be returned.
10.2. HTTP-CoAP Proxying 10.2. HTTP-CoAP Proxying
If an HTTP request contains a Request-URI with a 'coap' or 'coaps' If an HTTP request contains a Request-URI with a "coap" or "coaps"
URI, then the receiving HTTP endpoint (called "the proxy" henceforth) URI, then the receiving HTTP endpoint (called "the proxy" henceforth)
is requested to perform the operation specified by the request method is requested to perform the operation specified by the request method
on the indicated CoAP resource and return the result to the client. on the indicated CoAP resource and return the result to the client.
This section specifies for any HTTP request the HTTP response that This section specifies for any HTTP request the HTTP response that
the proxy should return to the client. Unless otherwise specified the proxy should return to the client. Unless otherwise specified,
all the statements made are RECOMMENDED behavior; some highly all the statements made are RECOMMENDED behavior; some highly
constrained implementations may need to resort to shortcuts. How the constrained implementations may need to resort to shortcuts. How the
proxy actually satisfies the request is an implementation detail, proxy actually satisfies the request is an implementation detail,
although the typical case is expected to be the proxy translating and although the typical case is expected to be that the proxy translates
forwarding the request to a CoAP origin server. The meanings of the and forwards the request to a CoAP origin server. The meanings of
individual HTTP methods when performed on CoAP resources are the individual HTTP methods when performed on CoAP resources are
explained in the subsections of this section. explained in the subsections of this section.
If the proxy is unable or unwilling to service a request with a CoAP If the proxy is unable or unwilling to service a request with a CoAP
URI, a 501 (Not Implemented) response is returned to the client. If URI, a 501 (Not Implemented) response is returned to the client. If
the proxy services the request by interacting with a third party the proxy services the request by interacting with a third party
(such as the CoAP origin server) and is unable to obtain a result (such as the CoAP origin server) and is unable to obtain a result
within a reasonable time frame, a 504 (Gateway Timeout) response is within a reasonable time frame, a 504 (Gateway Timeout) response is
returned; if a result can be obtained but is not understood, a 502 returned; if a result can be obtained but is not understood, a 502
(Bad Gateway) response is returned. (Bad Gateway) response is returned.
10.2.1. OPTIONS and TRACE 10.2.1. OPTIONS and TRACE
As the OPTIONS and TRACE methods are not supported in CoAP a 501 (Not As the OPTIONS and TRACE methods are not supported in CoAP, a 501
Implemented) error MUST be returned to the client. (Not Implemented) error MUST be returned to the client.
10.2.2. GET 10.2.2. GET
The GET method requests the proxy to return a representation of the The GET method requests the proxy to return a representation of the
CoAP resource identified by the Request-URI. CoAP resource identified by the Request-URI.
Upon success, a 200 (OK) response is returned. The payload of the Upon success, a 200 (OK) response is returned. The payload of the
response MUST be a representation of the target CoAP resource, and response MUST be a representation of the target CoAP resource, and
the Content-Type and Content-Encoding header fields be set the Content-Type and Content-Encoding header fields MUST be set
accordingly. The response MUST indicate a max-age directive that accordingly. The response MUST indicate a max-age directive that
indicates a value no greater than the remaining time the indicates a value no greater than the remaining time the
representation can be considered fresh. If the CoAP response has an representation can be considered fresh. If the CoAP response has an
ETag option, the proxy should include an ETag header field in the ETag option, the proxy should include an ETag header field in the
response. response.
A client can influence the processing of a GET request by including A client can influence the processing of a GET request by including
the following options: the following options:
Accept: The most preferred Media-type of the HTTP Accept header Accept: The most-preferred media type of the HTTP Accept header
field in a request is mapped to a CoAP Accept option. HTTP Accept field in a request is mapped to a CoAP Accept option. HTTP Accept
Media-type ranges, parameters and extensions are not supported by media-type ranges, parameters, and extensions are not supported by
the CoAP Accept option. If the proxy cannot send a response which the CoAP Accept option. If the proxy cannot send a response that
is acceptable according to the combined Accept field value, then is acceptable according to the combined Accept field value, then
the proxy sends a 406 (not acceptable) response. The proxy MAY the proxy sends a 406 (Not Acceptable) response. The proxy MAY
then retry the request with further Media-types from the HTTP then retry the request with further media types from the HTTP
Accept header field. Accept header field.
Conditional GETs: Conditional HTTP GET requests that include an "If- Conditional GETs: Conditional HTTP GET requests that include an "If-
Match" or "If-None-Match" request-header field can be mapped to a Match" or "If-None-Match" request-header field can be mapped to a
corresponding CoAP request. The "If-Modified-Since" and "If- corresponding CoAP request. The "If-Modified-Since" and "If-
Unmodified-Since" request-header fields are not directly supported Unmodified-Since" request-header fields are not directly supported
by CoAP, but are implemented locally by a caching proxy. by CoAP but are implemented locally by a caching proxy.
10.2.3. HEAD 10.2.3. HEAD
The HEAD method is identical to GET except that the server MUST NOT The HEAD method is identical to GET except that the server MUST NOT
return a message-body in the response. return a message-body in the response.
Although there is no direct equivalent of HTTP's HEAD method in CoAP, Although there is no direct equivalent of HTTP's HEAD method in CoAP,
an HTTP-CoAP proxy responds to HEAD requests for CoAP resources, and an HTTP-CoAP proxy responds to HEAD requests for CoAP resources, and
the HTTP headers are returned without a message-body. the HTTP headers are returned without a message-body.
Implementation Note: An HTTP-CoAP proxy may want to try using a Implementation Note: An HTTP-CoAP proxy may want to try using a
block-wise transfer [I-D.ietf-core-block] option to minimize the block-wise transfer option [BLOCK] to minimize the amount of data
amount of data actually transferred, but needs to be prepared for actually transferred, but it needs to be prepared for the case
the case that the origin server does not support block-wise that the origin server does not support block-wise transfers.
transfers.
10.2.4. POST 10.2.4. POST
The POST method requests the proxy to have the representation The POST method requests the proxy to have the representation
enclosed in the request be processed by the CoAP origin server. The enclosed in the request be processed by the CoAP origin server. The
actual function performed by the POST method is determined by the actual function performed by the POST method is determined by the
origin server and dependent on the resource identified by the request origin server and dependent on the resource identified by the request
URI. URI.
If the action performed by the POST method does not result in a If the action performed by the POST method does not result in a
skipping to change at page 78, line 17 skipping to change at page 79, line 45
returned. returned.
10.2.5. PUT 10.2.5. PUT
The PUT method requests the proxy to update or create the CoAP The PUT method requests the proxy to update or create the CoAP
resource identified by the Request-URI with the enclosed resource identified by the Request-URI with the enclosed
representation. representation.
If a new resource is created at the Request-URI, a 201 (Created) If a new resource is created at the Request-URI, a 201 (Created)
response is returned to the client. If an existing resource is response is returned to the client. If an existing resource is
modified, either the 200 (OK) or 204 (No Content) response codes is modified, either the 200 (OK) or 204 (No Content) Response Codes is
sent to indicate successful completion of the request. sent to indicate successful completion of the request.
10.2.6. DELETE 10.2.6. DELETE
The DELETE method requests the proxy to delete the CoAP resource The DELETE method requests the proxy to delete the CoAP resource
identified by the Request-URI at the CoAP origin server. identified by the Request-URI at the CoAP origin server.
A successful response is 200 (OK) if the response includes an entity A successful response is 200 (OK) if the response includes an entity
describing the status or 204 (No Content) if the action has been describing the status or 204 (No Content) if the action has been
enacted but the response does not include an entity. enacted but the response does not include an entity.
10.2.7. CONNECT 10.2.7. CONNECT
This method can not currently be satisfied by an HTTP-CoAP proxy This method cannot currently be satisfied by an HTTP-CoAP proxy
function as TLS to DTLS tunneling has not yet been specified. For function, as TLS to DTLS tunneling has not yet been specified. For
now, a 501 (Not Implemented) error is returned to the client. now, a 501 (Not Implemented) error is returned to the client.
11. Security Considerations 11. Security Considerations
This section analyzes the possible threats to the protocol. It is This section analyzes the possible threats to the protocol. It is
meant to inform protocol and application developers about the meant to inform protocol and application developers about the
security limitations of CoAP as described in this document. As CoAP security limitations of CoAP as described in this document. As CoAP
realizes a subset of the features in HTTP/1.1, the security realizes a subset of the features in HTTP/1.1, the security
considerations in Section 15 of [RFC2616] are also pertinent to CoAP. considerations in Section 15 of [RFC2616] are also pertinent to CoAP.
This section concentrates on describing limitations specific to CoAP. This section concentrates on describing limitations specific to CoAP.
11.1. Protocol Parsing, Processing URIs 11.1. Parsing the Protocol and Processing URIs
A network-facing application can exhibit vulnerabilities in its A network-facing application can exhibit vulnerabilities in its
processing logic for incoming packets. Complex parsers are well- processing logic for incoming packets. Complex parsers are well-
known as a likely source of such vulnerabilities, such as the ability known as a likely source of such vulnerabilities, such as the ability
to remotely crash a node, or even remotely execute arbitrary code on to remotely crash a node, or even remotely execute arbitrary code on
it. CoAP attempts to narrow the opportunities for introducing such it. CoAP attempts to narrow the opportunities for introducing such
vulnerabilities by reducing parser complexity, by giving the entire vulnerabilities by reducing parser complexity, by giving the entire
range of encodable values a meaning where possible, and by range of encodable values a meaning where possible, and by
aggressively reducing complexity that is often caused by unnecessary aggressively reducing complexity that is often caused by unnecessary
choice between multiple representations that mean the same thing. choice between multiple representations that mean the same thing.
skipping to change at page 79, line 17 skipping to change at page 80, line 51
reducing the opportunities for introducing vulnerabilities into the reducing the opportunities for introducing vulnerabilities into the
servers. Even so, the URI processing code in CoAP implementations is servers. Even so, the URI processing code in CoAP implementations is
likely to be a large source of remaining vulnerabilities and should likely to be a large source of remaining vulnerabilities and should
be implemented with special care. CoAP access control be implemented with special care. CoAP access control
implementations need to ensure they don't introduce vulnerabilities implementations need to ensure they don't introduce vulnerabilities
through discrepancies between the code deriving access control through discrepancies between the code deriving access control
decisions from a URI and the code finally serving up the resource decisions from a URI and the code finally serving up the resource
addressed by the URI. The most complex parser remaining could be the addressed by the URI. The most complex parser remaining could be the
one for the CoRE Link Format, although this also has been designed one for the CoRE Link Format, although this also has been designed
with a goal of reduced implementation complexity [RFC6690]. (See with a goal of reduced implementation complexity [RFC6690]. (See
also section 15.2 of [RFC2616].) also Section 15.2 of [RFC2616].)
11.2. Proxying and Caching 11.2. Proxying and Caching
As mentioned in 15.7 of [RFC2616], proxies are by their very nature As mentioned in Section 15.7 of [RFC2616], proxies are by their very
men-in-the-middle, breaking any IPsec or DTLS protection that a nature men-in-the-middle, breaking any IPsec or DTLS protection that
direct CoAP message exchange might have. They are therefore a 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 HTTP/ define any of the cache-suppressing Cache-Control options that
1.1 provides to better protect sensitive data. HTTP/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 those the proxy would require to
the process of forwarding the request in the first place. perform request forwarding in the first place.
Unlike the "coap" scheme, responses to "coaps" identified requests Unlike the "coap" scheme, responses to "coaps" identified requests
are never "public" and thus MUST NOT be reused for shared caching are never "public" and thus MUST NOT be reused for shared caching,
unless the cache is able to make equivalent access control decisions unless the cache is able to make equivalent access control decisions
to the ones that led to the cached entry. They can, however, be to the ones that led to the cached entry. They can, however, be
reused in a private cache if the message is cacheable by default in reused in a private cache if the message is cacheable by default in
CoAP. CoAP.
Finally, a proxy that fans out Separate Responses (as opposed to Finally, a proxy that fans out Separate Responses (as opposed to
Piggy-backed Responses) to multiple original requesters may provide piggybacked Responses) to multiple original requesters may provide
additional amplification (see Section 11.3). additional amplification (see Section 11.3).
11.3. Risk of amplification 11.3. Risk of Amplification
CoAP servers generally reply to a request packet with a response CoAP servers generally reply to a request packet with a response
packet. This response packet may be significantly larger than the packet. This response packet may be significantly larger than the
request packet. An attacker might use CoAP nodes to turn a small request packet. An attacker might use CoAP nodes to turn a small
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, are
that are accessible from an attacker and can access potential victims accessible from an attacker, and can access potential victims (e.g.,
(e.g. on the general Internet), as the UDP protocol provides no way on the general Internet), as the UDP protocol provides no way to
to verify the source address given in the request packet. An verify the source address given in the request packet. An attacker
attacker need only place the IP address of the victim in the source need only place the IP address of the victim in the source address of
address of a suitable request packet to generate a larger packet a suitable request packet to generate a larger packet directed at the
directed at the victim. 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.
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 [BLOCK] and offering large
offering large resource representations only in relatively small resource representations only in relatively small slices. For
slices. E.g., for a 1000 byte resource, a 10-byte request might example, for a 1000-byte resource, a 10-byte request might result in
result in an 80-byte response (with a 64-byte block) instead of a an 80-byte response (with a 64-byte block) instead of a 1016-byte
1016-byte response, considerably reducing the amplification provided. 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 DoS attacks, especially over
especially over constrained networks. This specification attempts to constrained networks. This specification attempts to reduce the
reduce the amplification effects of multicast requests by limiting amplification effects of multicast requests by limiting when a
when a response is returned. To limit the possibility of malicious response is returned. To limit the possibility of malicious use,
use, CoAP servers SHOULD NOT accept multicast requests that can not CoAP servers SHOULD NOT accept multicast requests that can not be
be authenticated in some way, cryptographically or by some multicast 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.
On some general purpose operating systems providing a Posix-style On some general-purpose operating systems providing a POSIX-style API
API, it is not straightforward to find out whether a packet received [IEEE1003.1], it is not straightforward to find out whether a packet
was addressed to a multicast address. While many implementations received was addressed to a multicast address. While many
will know whether they have joined a multicast group, this creates a implementations will know whether they have joined a multicast group,
problem for packets addressed to multicast addresses of the form this creates a problem for packets addressed to multicast addresses
FF0x::1, which are received by every IPv6 node. Implementations of the form FF0x::1, which are received by every IPv6 node.
SHOULD make use of modern APIs such as IPV6_RECVPKTINFO [RFC3542], if Implementations SHOULD make use of modern APIs such as
available, to make this determination. IPV6_RECVPKTINFO [RFC3542], if 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 that 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 a 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 a Reset message in response to a Confirmable message or
endpoint "deaf"; or Non-confirmable message, thus making an 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,
to much bolder attacks on the supporting infrastructure, e.g. to much bolder attacks on the supporting infrastructure, e.g.,
poisoning proxy caches, or tricking validation / lookup poisoning proxy caches, or tricking validation/lookup interfaces
interfaces in resource directories and, more generally, any in resource directories and, more generally, any component that
component that stores global network state and uses CoAP as the stores global network state and uses CoAP as the messaging
messaging facility to handle state set/update's is a potential facility to handle setting or updating state is a potential
target.); or target.); or
4. spoofing a multicast request for a target node which may result 4. spoofing a multicast request for a target node; this may result
in both network congestion/collapse and victim DoS'ing / forced in network congestion/collapse, a DoS attack on the victim, or
wakeup from sleeping; or forced wake-up from sleeping; or
5. spoofing observe messages, etc. 5. spoofing observe messages, etc.
Response spoofing by off-path attackers can be detected and mitigated Response spoofing by off-path attackers can be detected and mitigated
even without transport layer security by choosing a non-trivial, even without transport layer security by choosing a nontrivial,
randomized token in the request (Section 5.3.1). [RFC4086] discusses randomized token in the request (Section 5.3.1). [RFC4086] discusses
randomness requirements for security. randomness requirements for security.
In principle, other kinds of spoofing can be detected by CoAP only in In principle, other kinds of spoofing can be detected by CoAP only in
case CON semantics is used, because of unexpected ACK/RSTs coming case Confirmable message semantics is used, because of unexpected
from the deceived endpoint. But this imposes keeping track of the Acknowledgement or Reset messages coming from the deceived endpoint.
used Message IDs which is not always possible, and moreover detection But this imposes keeping track of the used Message IDs, which is not
becomes available usually after the damage is already done. This always possible, and moreover detection becomes available usually
kind of attack can be prevented using security modes other than after the damage is already done. This kind of attack can be
NoSec. prevented using security modes other than NoSec.
With or without source address spoofing, a client can attempt to With or without source address spoofing, a client can attempt to
overload a server by sending requests, preferably complex ones, to a overload a server by sending requests, preferably complex ones, to a
server; address spoofing makes tracing back, and blocking, this server; address spoofing makes tracing back, and blocking, this
attack harder. Given that the cost of a CON request is small, this attack harder. Given that the cost of a CON request is small, this
attack can easily be executed. Under this attack, a constrained node attack can easily be executed. Under this attack, a constrained node
with limited total energy available may exhaust that energy much more with limited total energy available may exhaust that energy much more
quickly than planned (battery depletion attack). Also, if the client quickly than planned (battery depletion attack). Also, if the client
uses a Confirmable message and the server responds with a Confirmable uses a Confirmable message and the server responds with a Confirmable
separate response to a (possibly spoofed) address that does not separate response to a (possibly spoofed) address that does not
respond, the server will have to allocate buffer and retransmission respond, the server will have to allocate buffer and retransmission
logic for each response up to the exhaustion of MAX_TRANSMIT_SPAN, logic for each response up to the exhaustion of MAX_TRANSMIT_SPAN,
making it more likely that it runs out of resources for processing making it more likely that it runs out of resources for processing
legitimate traffic. The latter problem can be mitigated somewhat by legitimate traffic. The latter problem can be mitigated somewhat by
limiting the rate of responses as discussed in Section 4.7. An limiting the rate of responses as discussed in Section 4.7. An
attacker could also spoof the address of a legitimate client, which, attacker could also spoof the address of a legitimate client; this
if the server uses separate responses, might block legitimate might cause the server, if it uses separate responses, to block
responses to that client because of NSTART=1. All these attacks can legitimate responses to that client because of NSTART=1. All these
be prevented using a security mode other than NoSec, leaving only attacks can be prevented using a security mode other than NoSec, thus
attacks on the security protocol. leaving only attacks on the security protocol.
11.5. Cross-Protocol Attacks 11.5. Cross-Protocol Attacks
The ability to incite a CoAP endpoint to send packets to a fake The ability to incite a CoAP endpoint to send packets to a fake
source address can be used not only for amplification, but also for source address can be used not only for amplification, but also for
cross-protocol attacks against a victim listening to UDP packets at a cross-protocol attacks against a victim listening to UDP packets at a
given address (IP address and port): given address (IP address and port). This would occur as follows:
o the attacker sends a message to a CoAP endpoint with the given o The attacker sends a message to a CoAP endpoint with the given
address as the fake source address, address as the fake source address.
o the CoAP endpoint replies with a message to the given source o The CoAP endpoint replies with a message to the given source
address, address.
o the victim at the given address receives a UDP packet that it o The victim at the given address receives a UDP packet that it
interprets according to the rules of a different protocol. interprets according to the rules of a different protocol.
This may be used to circumvent firewall rules that prevent direct This may be used to circumvent firewall rules that prevent direct
communication from the attacker to the victim, but happen to allow communication from the attacker to the victim but happen to allow
communication from the CoAP endpoint (which may also host a valid communication from the CoAP endpoint (which may also host a valid
role in the other protocol) to the victim. role in the other protocol) to the victim.
Also, CoAP endpoints may be the victim of a cross-protocol attack Also, CoAP endpoints may be the victim of a cross-protocol attack
generated through an endpoint of another UDP-based protocol such as generated through an endpoint of another UDP-based protocol such as
DNS. In both cases, attacks are possible if the security properties DNS. In both cases, attacks are possible if the security properties
of the endpoints rely on checking IP addresses (and firewalling off of the endpoints rely on checking IP addresses (and firewalling off
direct attacks sent from outside using fake IP addresses). In direct attacks sent from outside using fake IP addresses). In
general, because of their lack of context, UDP-based protocols are general, because of their lack of context, UDP-based protocols are
relatively easy targets for cross-protocol attacks. relatively easy targets for cross-protocol attacks.
Finally, CoAP URIs transported by other means could be used to incite Finally, CoAP URIs transported by other means could be used to incite
clients to send messages to endpoints of other protocols. clients to send messages to endpoints of other protocols.
One mitigation against cross-protocol attacks is strict checking of One mitigation against cross-protocol attacks is strict checking of
the syntax of packets received, combined with sufficient difference the syntax of packets received, combined with sufficient difference
in syntax. As an example, it might help if it were difficult to in syntax. As an example, it might help if it were difficult to
incite a DNS server to send a DNS response that would pass the checks incite a DNS server to send a DNS response that would pass the checks
of a CoAP endpoint. Unfortunately, the first two bytes of a DNS of a CoAP endpoint. Unfortunately, the first two bytes of a DNS
reply are an ID that can be chosen by the attacker, which map into reply are an ID that can be chosen by the attacker and that map into
the interesting part of the CoAP header, and the next two bytes are the interesting part of the CoAP header, and the next two bytes are
then interpreted as CoAP's Message ID (i.e., any value is then interpreted as CoAP's Message ID (i.e., any value is
acceptable). The DNS count words may be interpreted as multiple acceptable). The DNS count words may be interpreted as multiple
instances of a (non-existent, but elective) CoAP option 0, or instances of a (nonexistent but elective) CoAP option 0, or possibly
possibly as a Token. The echoed query finally may be manufactured by as a Token. The echoed query finally may be manufactured by the
the attacker to achieve a desired effect on the CoAP endpoint; the attacker to achieve a desired effect on the CoAP endpoint; the
response added by the server (if any) might then just be interpreted response added by the server (if any) might then just be interpreted
as added payload. as added payload.
1 1 1 1 1 1 1 1 1 1 1 1
0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5
+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+ +--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
| ID | T, TKL, code | ID | T, TKL, code
+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+ +--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
|QR| Opcode |AA|TC|RD|RA| Z | RCODE | Message ID |QR| Opcode |AA|TC|RD|RA| Z | RCODE | Message ID
+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+ +--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
| 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 ([RFC1035], Section 4.1.1) 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.
Conversely, a NoSec environment that completely relies on a firewall Conversely, a NoSec environment that completely relies on a firewall
for CoAP security not only needs to firewall off the CoAP endpoints for CoAP security not only needs to firewall off the CoAP endpoints
but also all other endpoints that might be incited to send UDP but also all other endpoints that might be incited to send UDP
messages to CoAP endpoints using some other UDP-based protocol. messages to CoAP endpoints using some other UDP-based protocol.
In addition to the considerations above, the security considerations In addition to the considerations above, the security considerations
for DTLS with respect to cross-protocol attacks apply. E.g., if the for DTLS with respect to cross-protocol attacks apply. For example,
same DTLS security association ("connection") is used to carry data if the same DTLS security association ("connection") is used to carry
of multiple protocols, DTLS no longer provides protection against data of multiple protocols, DTLS no longer provides protection
cross-protocol attacks between these protocols. against cross-protocol attacks between these protocols.
11.6. Constrained node considerations 11.6. Constrained-Node Considerations
Implementers on constrained nodes often find themselves without a Implementers on constrained nodes often find themselves without a
good source of entropy [RFC4086]. If that is the case, the node MUST good source of entropy [RFC4086]. If that is the case, the node MUST
NOT be used for processes that require good entropy, such as key NOT be used for processes that require good entropy, such as key
generation. Instead, keys should be generated externally and added generation. Instead, keys should be generated externally and added
to the device during manufacturing or commissioning. to the device during manufacturing or commissioning.
Due to their low processing power, constrained nodes are particularly Due to their low processing power, constrained nodes are particularly
susceptible to timing attacks. Special care must be taken in susceptible to timing attacks. Special care must be taken in
implementation of cryptographic primitives. implementation of cryptographic primitives.
skipping to change at page 84, line 41 skipping to change at page 86, line 35
recovery of keying materials. This needs to be considered when recovery of keying materials. This needs to be considered when
defining the scope of credentials assigned to them. In particular, defining the scope of credentials assigned to them. In particular,
assigning a shared key to a group of nodes may make any single assigning a shared key to a group of nodes may make any single
constrained node a target for subverting the entire group. constrained node a target for subverting the entire group.
12. IANA Considerations 12. IANA Considerations
12.1. CoAP Code Registries 12.1. CoAP Code Registries
This document defines two sub-registries for the values of the Code This document defines two sub-registries for the values of the Code
field in the CoAP header within the Constrained RESTful Environments field in the CoAP header within the "Constrained RESTful Environments
(CoRE) Parameters ("CoRE Parameters") registry. (CoRE) Parameters" registry, hereafter referred to as the "CoRE
Parameters" registry.
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 digits dd denote a decimal
between 00 and 31 for the detail. number 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
skipping to change at page 85, line 31 skipping to change at page 87, line 34
Each entry in the sub-registry must include the Method Code in the Each entry in the sub-registry must include the Method Code in the
range 0.01-0.31, the name of the method, and a reference to the range 0.01-0.31, the name of the method, and a reference to the
method's documentation. method's documentation.
Initial entries in this sub-registry are as follows: Initial entries in this sub-registry are as follows:
+------+--------+-----------+ +------+--------+-----------+
| Code | Name | Reference | | Code | Name | Reference |
+------+--------+-----------+ +------+--------+-----------+
| 0.01 | GET | [RFCXXXX] | | 0.01 | GET | [RFC7252] |
| 0.02 | POST | [RFCXXXX] | | 0.02 | POST | [RFC7252] |
| 0.03 | PUT | [RFCXXXX] | | 0.03 | PUT | [RFC7252] |
| 0.04 | DELETE | [RFCXXXX] | | 0.04 | DELETE | [RFC7252] |
+------+--------+-----------+ +------+--------+-----------+
Table 5: CoAP Method Codes Table 5: CoAP Method Codes
All other Method Codes are Unassigned. All other Method Codes are Unassigned.
The IANA policy for future additions to this 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 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 |
skipping to change at page 86, line 15 skipping to change at page 88, line 18
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 | [RFC7252] |
| 2.02 | Deleted | [RFCXXXX] | | 2.02 | Deleted | [RFC7252] |
| 2.03 | Valid | [RFCXXXX] | | 2.03 | Valid | [RFC7252] |
| 2.04 | Changed | [RFCXXXX] | | 2.04 | Changed | [RFC7252] |
| 2.05 | Content | [RFCXXXX] | | 2.05 | Content | [RFC7252] |
| 4.00 | Bad Request | [RFCXXXX] | | 4.00 | Bad Request | [RFC7252] |
| 4.01 | Unauthorized | [RFCXXXX] | | 4.01 | Unauthorized | [RFC7252] |
| 4.02 | Bad Option | [RFCXXXX] | | 4.02 | Bad Option | [RFC7252] |
| 4.03 | Forbidden | [RFCXXXX] | | 4.03 | Forbidden | [RFC7252] |
| 4.04 | Not Found | [RFCXXXX] | | 4.04 | Not Found | [RFC7252] |
| 4.05 | Method Not Allowed | [RFCXXXX] | | 4.05 | Method Not Allowed | [RFC7252] |
| 4.06 | Not Acceptable | [RFCXXXX] | | 4.06 | Not Acceptable | [RFC7252] |
| 4.12 | Precondition Failed | [RFCXXXX] | | 4.12 | Precondition Failed | [RFC7252] |
| 4.13 | Request Entity Too Large | [RFCXXXX] | | 4.13 | Request Entity Too Large | [RFC7252] |
| 4.15 | Unsupported Content-Format | [RFCXXXX] | | 4.15 | Unsupported Content-Format | [RFC7252] |
| 5.00 | Internal Server Error | [RFCXXXX] | | 5.00 | Internal Server Error | [RFC7252] |
| 5.01 | Not Implemented | [RFCXXXX] | | 5.01 | Not Implemented | [RFC7252] |
| 5.02 | Bad Gateway | [RFCXXXX] | | 5.02 | Bad Gateway | [RFC7252] |
| 5.03 | Service Unavailable | [RFCXXXX] | | 5.03 | Service Unavailable | [RFC7252] |
| 5.04 | Gateway Timeout | [RFCXXXX] | | 5.04 | Gateway Timeout | [RFC7252] |
| 5.05 | Proxying Not Supported | [RFCXXXX] | | 5.05 | Proxying Not Supported | [RFC7252] |
+------+------------------------------+-----------+ +------+------------------------------+-----------+
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
a response with that code, including the following properties: a response with that code, including the following properties:
o The methods the response code applies to. o The methods the Response Code applies to.
o Whether payload is required, optional or not allowed. o Whether payload is required, optional, or not allowed.
o The semantics of the payload. For example, the payload of a 2.05 o The semantics of the payload. For example, the payload of a 2.05
(Content) response is a representation of the target resource; the (Content) response is a representation of the target resource; the
payload in an error response is a human-readable diagnostic payload in an error response is a human-readable diagnostic
payload. payload.
o The format of the payload. For example, the format in a 2.05 o The format of the payload. For example, the format in a 2.05
(Content) response is indicated by the Content-Format Option; the (Content) response is indicated by the Content-Format Option; the
format of the payload in an error response is always Net-Unicode format of the payload in an error response is always Net-Unicode
text. text.
o Whether the response is cacheable according to the freshness o Whether the response is cacheable according to the freshness
model. model.
o Whether the response is validatable according to the validation o Whether the response is validatable according to the validation
model. model.
o Whether the response causes a cache to mark responses stored for o Whether the response causes a cache to mark responses stored for
the request URI as not fresh. the request URI as not fresh.
12.2. Option Number Registry 12.2. CoAP Option Numbers Registry
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) | [RFC7252] |
| 1 | If-Match | [RFCXXXX] | | 1 | If-Match | [RFC7252] |
| 3 | Uri-Host | [RFCXXXX] | | 3 | Uri-Host | [RFC7252] |
| 4 | ETag | [RFCXXXX] | | 4 | ETag | [RFC7252] |
| 5 | If-None-Match | [RFCXXXX] | | 5 | If-None-Match | [RFC7252] |
| 7 | Uri-Port | [RFCXXXX] | | 7 | Uri-Port | [RFC7252] |
| 8 | Location-Path | [RFCXXXX] | | 8 | Location-Path | [RFC7252] |
| 11 | Uri-Path | [RFCXXXX] | | 11 | Uri-Path | [RFC7252] |
| 12 | Content-Format | [RFCXXXX] | | 12 | Content-Format | [RFC7252] |
| 14 | Max-Age | [RFCXXXX] | | 14 | Max-Age | [RFC7252] |
| 15 | Uri-Query | [RFCXXXX] | | 15 | Uri-Query | [RFC7252] |
| 17 | Accept | [RFCXXXX] | | 17 | Accept | [RFC7252] |
| 20 | Location-Query | [RFCXXXX] | | 20 | Location-Query | [RFC7252] |
| 35 | Proxy-Uri | [RFCXXXX] | | 35 | Proxy-Uri | [RFC7252] |
| 39 | Proxy-Scheme | [RFCXXXX] | | 39 | Proxy-Scheme | [RFC7252] |
| 60 | Size1 | [RFCXXXX] | | 60 | Size1 | [RFC7252] |
| 128 | (Reserved) | [RFCXXXX] | | 128 | (Reserved) | [RFC7252] |
| 132 | (Reserved) | [RFCXXXX] | | 132 | (Reserved) | [RFC7252] |
| 136 | (Reserved) | [RFCXXXX] | | 136 | (Reserved) | [RFC7252] |
| 140 | (Reserved) | [RFCXXXX] | | 140 | (Reserved) | [RFC7252] |
+--------+------------------+-----------+ +--------+------------------+-----------+
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
option semantics are defined correctly. The option numbers between option semantics are defined correctly. The option numbers between
65000 and 65535 inclusive are reserved for experiments. They are not 65000 and 65535 inclusive are reserved for experiments. They are not
meant for vendor specific use of any kind and MUST NOT be used in meant for vendor-specific use of any kind and MUST NOT be used in
operational deployments. operational deployments.
+---------------+------------------------------+ +-------------+---------------------------------------+
| Option Number | Policy [RFC5226] | | Range | Registration Procedures |
+---------------+------------------------------+ +-------------+---------------------------------------+
| 0..255 | IETF Review or IESG approval | | 0-255 | IETF Review or IESG Approval |
| 256..2047 | Specification Required | | 256-2047 | Specification Required |
| 2048..64999 | Designated Expert | | 2048-64999 | Expert Review |
| 65000..65535 | Reserved for experiments | | 65000-65535 | Experimental use (no operational use) |
+---------------+------------------------------+ +-------------+---------------------------------------+
Table 8: CoAP Option Number Registry Policy Table 8: CoAP Option Numbers: Registration Procedures
The documentation of an Option Number should specify the semantics of The documentation of an Option Number should specify the semantics of
an option with that number, including the following properties: an option with that number, including the following properties:
o The meaning of the option in a request. o The meaning of the option in a request.
o The meaning of the option in a response. o The meaning of the option in a response.
o Whether the option is critical or elective, as determined by the o Whether the option is critical or elective, as determined by the
Option Number. Option Number.
skipping to change at page 89, line 10 skipping to change at page 91, line 37
part of the Cache-Key, as determined by the Option Number (see part of the Cache-Key, as determined by the Option Number (see
Section 5.4.2). Section 5.4.2).
o The format and length of the option's value. o The format and length of the option's value.
o Whether the option must occur at most once or whether it can occur o Whether the option must occur at most once or whether it can occur
multiple times. multiple times.
o The default value, if any. For a critical option with a default o The default value, if any. For a critical option with a default
value, a discussion on how the default value enables processing by value, a discussion on how the default value enables processing by
implementations not implementing the critical option implementations that do not support the critical option
(Section 5.4.4). (Section 5.4.4).
12.3. Content-Format Registry 12.3. CoAP Content-Formats Registry
Internet media types are identified by a string, such as "application Internet media types are identified by a string, such as
/xml" [RFC2046]. In order to minimize the overhead of using these "application/xml" [RFC2046]. In order to minimize the overhead of
media types to indicate the format of payloads, this document defines using these media types to indicate the format of payloads, this
a sub-registry for a subset of Internet media types to be used in document defines a sub-registry for a subset of Internet media types
CoAP and assigns each, in combination with a content-coding, a to be used in CoAP and assigns each, in combination with a content-
numeric identifier. The name of the sub-registry is "CoAP Content- coding, a numeric identifier. The name of the sub-registry is "CoAP
Formats", within the "CoRE Parameters" registry. Content-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] |
| charset=utf-8 | | | | | charset=utf-8 | | | [RFC5147] |
| application/ | - | 40 | [RFC6690] | | application/link-format | - | 40 | [RFC6690] |
| link-format | | | | | application/xml | - | 41 | [RFC3023] |
| application/xml | - | 41 | [RFC3023] | | application/octet-stream | - | 42 | [RFC2045] [RFC2046] |
| application/ | - | 42 | [RFC2045][RFC2046] | | application/exi | - | 47 | [REC-exi-20140211] |
| octet-stream | | | | | application/json | - | 50 | [RFC7159] |
| application/exi | - | 47 | [EXIMIME] | +--------------------------+----------+----+------------------------+
| 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.
Because the name space of single-byte identifiers is so small, the Because the namespace of single-byte identifiers is so small, the
IANA policy for future additions in the range 0-255 inclusive to the IANA policy for future additions in the range 0-255 inclusive to the
sub-registry is "Expert Review" as described in [RFC5226]. The IANA sub-registry is "Expert Review" as described in [RFC5226]. The IANA
policy for additions in the range 10000-64999 inclusive is "First policy for additions in the range 10000-64999 inclusive is "First
Come First Served" as described in [RFC5226]. Come First Served" as described in [RFC5226]. This is summarized in
the following table.
In machine to machine applications, it is not expected that generic +-------------+---------------------------------------+
| Range | Registration Procedures |
+-------------+---------------------------------------+
| 0-255 | Expert Review |
| 256-9999 | IETF Review or IESG Approval |
| 10000-64999 | First Come First Served |
| 65000-65535 | Experimental use (no operational use) |
+-------------+---------------------------------------+
Table 10: CoAP Content-Formats: Registration Procedures
In machine-to-machine applications, it is not expected that generic
Internet media types such as text/plain, application/xml or Internet media types such as text/plain, application/xml or
application/octet-stream are useful for real applications in the long application/octet-stream are useful for real applications in the long
term. It is recommended that M2M applications making use of CoAP term. It is recommended that M2M applications making use of CoAP
will request new Internet media types from IANA indicating semantic request new Internet media types from IANA indicating semantic
information about how to create or parse a payload. For example, a information about how to create or parse a payload. For example, a
Smart Energy application payload carried as XML might request a more Smart Energy application payload carried as XML might request a more
specific type like application/se+xml or application/se-exi. specific type like application/se+xml or application/se-exi.
12.4. URI Scheme Registration 12.4. URI Scheme Registration
This document requests the registration of the Uniform Resource This document contains the request for the registration of the
Identifier (URI) scheme "coap". The registration request complies Uniform Resource Identifier (URI) scheme "coap". The registration
with [RFC4395]. request complies 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 [RFC7252].
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 [RFC7252] 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 [RFC7252].
Contact. Contact.
IETF Chair <chair@ietf.org> IETF Chair <chair@ietf.org>
Author/Change controller. Author/Change controller.
IESG <iesg@ietf.org> IESG <iesg@ietf.org>
References. References.
[RFCXXXX] [RFC7252]
12.5. Secure URI Scheme Registration 12.5. Secure URI Scheme Registration
This document requests the registration of the Uniform Resource This document contains the request for the registration of the
Identifier (URI) scheme "coaps". The registration request complies Uniform Resource Identifier (URI) scheme "coaps". The registration
with [RFC4395]. request complies with [RFC4395].
URI scheme name. URI scheme name.
coaps coaps
Status. Status.
Permanent. Permanent.
URI scheme syntax. URI scheme syntax.
Defined in Section 6.2 of [RFCXXXX]. Defined in Section 6.2 of [RFC7252].
URI scheme semantics. URI scheme semantics.
The "coaps" URI scheme provides a way to identify resources that The "coaps" 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) 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 [RFC7252] 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.
See Section 11.1 of [RFCXXXX]. See Section 11.1 of [RFC7252].
Contact. Contact.
IETF Chair <chair@ietf.org> IETF Chair <chair@ietf.org>
Author/Change controller. Author/Change controller.
IESG <iesg@ietf.org> IESG <iesg@ietf.org>
References. References.
[RFCXXXX] [RFC7252]
12.6. Service Name and Port Number Registration 12.6. Service Name and Port Number Registration
One of the functions of CoAP is resource discovery: a CoAP client can One of the functions of CoAP is resource discovery: a CoAP client can
ask a CoAP server about the resources offered by it (see Section 7). ask a CoAP server about the resources offered by it (see Section 7).
To enable resource discovery just based on the knowledge of an IP To enable resource discovery just based on the knowledge of an IP
address, the CoAP port for resource discovery needs to be address, the CoAP port for resource discovery needs to be
standardized. standardized.
IANA has assigned the port number 5683 and the service name "coap", IANA has assigned the port number 5683 and the service name "coap",
in accordance with [RFC6335]. in accordance with [RFC6335].
Besides unicast, CoAP can be used with both multicast and anycast. Besides unicast, CoAP can be used with both multicast and anycast.
Service Name. Service Name.
coap coap
Transport Protocol. Transport Protocol.
UDP udp
Assignee. Assignee.
IESG <iesg@ietf.org> IESG <iesg@ietf.org>
Contact. Contact.
IETF Chair <chair@ietf.org> IETF Chair <chair@ietf.org>
Description. Description.
Constrained Application Protocol (CoAP) Constrained Application Protocol (CoAP)
Reference. Reference.
[RFCXXXX] [RFC7252]
Port Number. Port Number.
5683 5683
12.7. Secure Service Name and Port Number Registration 12.7. Secure Service Name and Port Number Registration
CoAP resource discovery may also be provided using the DTLS-secured CoAP resource discovery may also be provided using the DTLS-secured
CoAP "coaps" scheme. Thus the CoAP port for secure resource CoAP "coaps" scheme. Thus, the CoAP port for secure resource
discovery needs to be standardized. discovery needs to be standardized.
This document requests the assignment of the port number IANA has assigned the port number 5684 and the service name "coaps",
[IANA_TBD_PORT] and the service name "coaps", in accordance with in accordance with [RFC6335].
[RFC6335].
Besides unicast, DTLS-secured CoAP can be used with anycast. Besides unicast, DTLS-secured CoAP can be used with anycast.
Service Name. Service Name.
coaps coaps
Transport Protocol. Transport Protocol.
UDP udp
Assignee. Assignee.
IESG <iesg@ietf.org> IESG <iesg@ietf.org>
Contact. Contact.
IETF Chair <chair@ietf.org> IETF Chair <chair@ietf.org>
Description. Description.
DTLS-secured CoAP DTLS-secured CoAP
Reference. Reference.
[RFCXXXX] [RFC7252]
Port Number. Port Number.
[IANA_TBD_PORT] 5684
12.8. Multicast Address Registration 12.8. Multicast Address Registration
Section 8, "Multicast CoAP", defines the use of multicast. This Section 8, "Multicast CoAP", defines the use of multicast. IANA has
document requests the assignment of the following multicast addresses assigned the following multicast addresses for use by CoAP nodes:
for use by CoAP nodes:
IPv4 -- "All CoAP Nodes" address [TBD1], from the IPv4 Multicast
Address Space Registry. As the address is used for discovery that
may span beyond a single network, it should come from the
Internetwork Control Block (224.0.1.x, RFC 5771).
IPv6 -- "All CoAP Nodes" address [TBD2], from the IPv6 Multicast IPv4 -- "All CoAP Nodes" address 224.0.1.187, from the "IPv4
Address Space Registry, in the Variable Scope Multicast Addresses Multicast Address Space Registry". As the address is used for
space (RFC3307). Note that there is a distinct multicast address discovery that may span beyond a single network, it has come from
for each scope that interested CoAP nodes should listen to; CoAP the Internetwork Control Block (224.0.1.x, RFC 5771).
needs the Link-Local and Site-Local scopes only. The address
should be of the form FF0x::nn, where nn is a single byte, to
ensure good compression of the local-scope address with [RFC6282].
[The explanatory text to be removed upon allocation of the addresses, IPv6 -- "All CoAP Nodes" address FF0X::FD, from the "IPv6 Multicast
except for the note about the distinct multicast addresses.] Address Space Registry", in the "Variable Scope Multicast
Addresses" space (RFC 3307). Note that there is a distinct
multicast address for each scope that interested CoAP nodes should
listen to; CoAP needs the Link-Local and Site-Local scopes only.
13. Acknowledgements 13. Acknowledgements
Brian Frank was a contributor to and co-author of previous drafts of Brian Frank was a contributor to and coauthor of early versions 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 Floris Van den Abeele, Anthony Baire, Ed Beroset, Berta
Cragie, Esko Dijk, Lisa Dusseault, Mehmet Ersue, Thomas Fossati, Tom Carballido, Angelo P. Castellani, Gilbert Clark, Robert Cragie,
Herbst, Richard Kelsey, Ari Keranen, Matthias Kovatsch, Salvatore Pierre David, Esko Dijk, Lisa Dusseault, Mehmet Ersue, Thomas
Loreto, Kerry Lynn, Alexey Melnikov, Guido Moritz, Petri Mutka, Colin Fossati, Tobias Gondrom, Bert Greevenbosch, Tom Herbst, Jeroen
O'Flynn, Charles Palmer, Adriano Pezzuto, Robert Quattlebaum, Akbar Hoebeke, Richard Kelsey, Sye Loong Keoh, Ari Keranen, Matthias
Rahman, Eric Rescorla, Dan Romascanu, David Ryan, Szymon Sasin, Kovatsch, Avi Lior, Stephan Lohse, Salvatore Loreto, Kerry Lynn,
Michael Scharf, Dale Seed, Robby Simpson, Peter van der Stok, Michael Andrew McGregor, Alexey Melnikov, Guido Moritz, Petri Mutka, Colin
Stuber, Linyi Tian, Gilman Tolle, Matthieu Vial and Alper Yegin for O'Flynn, Charles Palmer, Adriano Pezzuto, Thomas Poetsch, Robert
helpful comments and discussions that have shaped the document. Quattlebaum, Akbar Rahman, Eric Rescorla, Dan Romascanu, David Ryan,
Peter Saint-Andre, Szymon Sasin, Michael Scharf, Dale Seed, Robby
Special thanks also to the IESG reviewers, Adrian Farrel, Martin Simpson, Peter van der Stok, Michael Stuber, Linyi Tian, Gilman
Stiemerling, Pete Resnick, Richard Barnes, Sean Turner, Spencer Tolle, Matthieu Vial, Maciej Wasilak, Fan Xianyou, and Alper Yegin
Dawkins, Stephen Farrell, and Ted Lemon, who contributed in-depth for helpful comments and discussions that have shaped the document.
reviews. Special thanks also to the responsible IETF area director at the time
of completion, Barry Leiba, and the IESG reviewers, Adrian Farrel,
Martin Stiemerling, Pete Resnick, Richard Barnes, Sean Turner,
Spencer Dawkins, Stephen Farrell, and Ted Lemon, who contributed in-
depth reviews.
Some of the text has been borrowed from the working documents of the Some of the text has been borrowed from the working documents of the
IETF httpbis working group. IETF HTTPBIS working group.
14. References 14. References
14.1. Normative References 14.1. Normative References
[I-D.ietf-tls-oob-pubkey]
Wouters, P., Tschofenig, H., Gilmore, J., Weiler, S., and
T. Kivinen, "Out-of-Band Public Key Validation for
Transport Layer Security (TLS)", draft-ietf-tls-oob-
pubkey-07 (work in progress), February 2013.
[I-D.mcgrew-tls-aes-ccm-ecc]
McGrew, D., Bailey, D., Campagna, M., and R. Dugal, "AES-
CCM ECC Cipher Suites for TLS", draft-mcgrew-tls-aes-ccm-
ecc-06 (work in progress), 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.S. Borenstein, "Multipurpose Internet Mail [RFC2045] Freed, N. and N. 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 97, line 18 skipping to change at page 99, line 46
[RFC6347] Rescorla, E. and N. Modadugu, "Datagram Transport Layer [RFC6347] Rescorla, E. and N. Modadugu, "Datagram Transport Layer
Security Version 1.2", RFC 6347, January 2012. Security Version 1.2", RFC 6347, January 2012.
[RFC6690] Shelby, Z., "Constrained RESTful Environments (CoRE) Link [RFC6690] Shelby, Z., "Constrained RESTful Environments (CoRE) Link
Format", RFC 6690, August 2012. Format", RFC 6690, August 2012.
[RFC6920] Farrell, S., Kutscher, D., Dannewitz, C., Ohlman, B., [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 [RFC7250] Wouters, P., Tschofenig, H., Gilmore, J., Weiler, S., and
T. Kivinen, "Using Raw Public Keys in Transport Layer
[EUI64] , "GUIDELINES FOR 64-BIT GLOBAL IDENTIFIER (EUI-64) Security (TLS) and Datagram Transport Layer Security
REGISTRATION AUTHORITY", April 2010, <http:// (DTLS)", RFC 7250, June 2014.
standards.ieee.org/regauth/oui/tutorials/EUI64.html>.
[EXIMIME] , "Efficient XML Interchange (EXI) Format 1.0", December [RFC7251] McGrew, D., Bailey, D., Campagna, M., and R. Dugal, "AES-
2009, <http://www.w3.org/TR/2009/CR-exi-20091208/ CCM Elliptic Curve Cryptography (ECC) Cipher Suites for
#mediaTypeRegistration>. Transport Layer Security (TLS)", RFC 7251, June 2014.
[HHGTTG] Adams, D., "The Hitchhiker's Guide to the Galaxy", October 14.2. Informative References
1979.
[I-D.allman-tcpm-rto-consider] [BLOCK] Bormann, C. and Z. Shelby, "Blockwise transfers in CoAP",
Allman, M., "Retransmission Timeout Considerations", Work in Progress, October 2013.
draft-allman-tcpm-rto-consider-01 (work in progress), May
2012.
[I-D.bormann-coap-misc] [CoAP-MISC]
Bormann, C. and K. Hartke, "Miscellaneous additions to Bormann, C. and K. Hartke, "Miscellaneous additions to
CoAP", draft-bormann-coap-misc-22 (work in progress), CoAP", Work in Progress, December 2013.
December 2012.
[I-D.bormann-core-ipsec-for-coap] [EUI64] IEEE Standards Association, "Guidelines for 64-bit Global
Bormann, C., "Using CoAP with IPsec", draft-bormann-core- Identifier (EUI-64 (TM))", Registration Authority
ipsec-for-coap-00 (work in progress), December 2012. Tutorials, April 2010, <http://standards.ieee.org/regauth/
oui/tutorials/EUI64.html>.
[I-D.castellani-core-http-mapping] [GROUPCOMM]
Castellani, A., Loreto, S., Rahman, A., Fossati, T., and Rahman, A. and E. Dijk, "Group Communication for CoAP",
E. Dijk, "Best Practices for HTTP-CoAP Mapping Work in Progress, December 2013.
Implementation", draft-castellani-core-http-mapping-07
(work in progress), February 2013.
[I-D.ietf-core-block] [HHGTTG] Adams, D., "The Hitchhiker's Guide to the Galaxy", Pan
Bormann, C. and Z. Shelby, "Blockwise transfers in CoAP", Books ISBN 3320258648, 1979.
draft-ietf-core-block-10 (work in progress), October 2012.
[I-D.ietf-core-groupcomm] [IEEE1003.1]
Rahman, A. and E. Dijk, "Group Communication for CoAP", IEEE and The Open Group, "Portable Operating System
draft-ietf-core-groupcomm-06 (work in progress), April Interface (POSIX)", The Open Group Base Specifications
2013. Issue 7, IEEE 1003.1, 2013 Edition,
<http://pubs.opengroup.org/onlinepubs/9699919799/>.
[I-D.ietf-core-observe] [IPsec-CoAP]
Hartke, K., "Observing Resources in CoAP", draft-ietf- Bormann, C., "Using CoAP with IPsec", Work in Progress,
core-observe-08 (work in progress), February 2013. December 2012.
[I-D.ietf-lwig-terminology] [MAPPING] Castellani, A., Loreto, S., Rahman, A., Fossati, T., and
Bormann, C., Ersue, M., and A. Keraenen, "Terminology for E. Dijk, "Guidelines for HTTP-CoAP Mapping
Constrained Node Networks", draft-ietf-lwig-terminology-04 Implementations", Work in Progress, February 2014.
(work in progress), April 2013.
[I-D.ietf-tls-multiple-cert-status-extension] [OBSERVE] Hartke, K., "Observing Resources in CoAP", Work in
Pettersen, Y., "The TLS Multiple Certificate Status Progress, April 2014.
Request Extension", draft-ietf-tls-multiple-cert-status-
extension-08 (work in progress), April 2013. [REC-exi-20140211]
Schneider, J., Kamiya, T., Peintner, D., and R. Kyusakov,
"Efficient XML Interchange (EXI) Format 1.0 (Second
Edition)", W3C Recommendation REC-exi-20140211, February
2014, <http://www.w3.org/TR/2014/REC-exi-20140211/>.
[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,
www.ics.uci.edu/~fielding/pubs/dissertation/ <http://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.
[RFC0791] Postel, J., "Internet Protocol", STD 5, RFC 791, September
1981.
[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, RFC [RFC0793] Postel, J., "Transmission Control Protocol", STD 7, RFC
793, September 1981. 793, September 1981.
[RFC2560] Myers, M., Ankney, R., Malpani, A., Galperin, S., and C. [RFC1035] Mockapetris, P., "Domain names - implementation and
Adams, "X.509 Internet Public Key Infrastructure Online specification", STD 13, RFC 1035, November 1987.
Certificate Status Protocol - OCSP", RFC 2560, June 1999.
[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, June with Session Description Protocol (SDP)", RFC 3264, June
2002. 2002.
[RFC3280] Housley, R., Polk, W., Ford, W., and D. Solo, "Internet
X.509 Public Key Infrastructure Certificate and
Certificate Revocation List (CRL) Profile", RFC 3280,
April 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
Requirements for Security", BCP 106, RFC 4086, June 2005. Requirements for Security", BCP 106, RFC 4086, June 2005.
[RFC4443] Conta, A., Deering, S., and M. Gupta, "Internet Control [RFC4443] Conta, A., Deering, S., and M. Gupta, "Internet Control
Message Protocol (ICMPv6) for the Internet Protocol Message Protocol (ICMPv6) for the Internet Protocol
Version 6 (IPv6) Specification", RFC 4443, March 2006. Version 6 (IPv6) Specification", RFC 4443, March 2006.
[RFC4492] Blake-Wilson, S., Bolyard, N., Gupta, V., Hawk, C., and B. [RFC4492] Blake-Wilson, S., Bolyard, N., Gupta, V., Hawk, C., and B.
Moeller, "Elliptic Curve Cryptography (ECC) Cipher Suites Moeller, "Elliptic Curve Cryptography (ECC) Cipher Suites
for Transport Layer Security (TLS)", RFC 4492, May 2006. for Transport Layer Security (TLS)", RFC 4492, May 2006.
[RFC4627] Crockford, D., "The application/json Media Type for
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, November for Application Designers", BCP 145, RFC 5405, November
2008. 2008.
skipping to change at page 100, line 15 skipping to change at page 102, line 42
Transport Protocol Port Number Registry", BCP 165, RFC Transport Protocol Port Number Registry", BCP 165, 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.
[RFC6960] Santesson, S., Myers, M., Ankney, R., Malpani, A.,
Galperin, S., and C. Adams, "X.509 Internet Public Key
Infrastructure Online Certificate Status Protocol - OCSP",
RFC 6960, June 2013.
[RFC6961] Pettersen, Y., "The Transport Layer Security (TLS)
Multiple Certificate Status Request Extension", RFC 6961,
June 2013.
[RFC7159] Bray, T., "The JavaScript Object Notation (JSON) Data
Interchange Format", RFC 7159, March 2014.
[RFC7228] Bormann, C., Ersue, M., and A. Keranen, "Terminology for
Constrained-Node Networks", RFC 7228, May 2014.
[RTO-CONSIDER]
Allman, M., "Retransmission Timeout Considerations", Work
in Progress, May 2012.
[W3CXMLSEC] [W3CXMLSEC]
Wenning, R., "Report of the XML Security PAG", October Wenning, R., "Report of the XML Security PAG", W3C XML
2012, <http://www.w3.org/2011/xmlsec-pag/pagreport.html>. Security PAG, October 2012,
<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 piggybacked response:
The client sends a Confirmable GET request for the resource coap:// The client sends a Confirmable GET request for the resource
server/temperature to the server with a Message ID of 0x7d34. The coap://server/temperature to the server with a Message ID of 0x7d34.
request includes one Uri-Path Option (Delta 0 + 11 = 11, Length 11, The request includes one Uri-Path Option (Delta 0 + 11 = 11, Length
Value "temperature"); the Token is left empty. This request is a 11, 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 101, line 15 skipping to change at page 104, line 48
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
0 1 2 3 0 1 2 3
0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| 1 | 2 | 0 | 2.05=69 | MID=0x7d34 | | 1 | 2 | 0 | 2.05=69 | MID=0x7d34 |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|1 1 1 1 1 1 1 1| "22.3 C" (6 B) ... |1 1 1 1 1 1 1 1| "22.3 C" (6 B) ...
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
Figure 16: Confirmable request; piggy-backed response Figure 16: Confirmable Request; Piggybacked Response
Figure 17 shows a similar example, but with the inclusion of an non- Figure 17 shows a similar example, but with the inclusion of an non-
empty Token (Value 0x20) in the request and the response, increasing empty Token (Value 0x20) in the request and the response, increasing
the sizes to 17 and 12 bytes, respectively. the sizes to 17 and 12 bytes, respectively.
Client Server Client Server
| | | |
| | | |
+----->| Header: GET (T=CON, Code=0.01, MID=0x7d35) +----->| Header: GET (T=CON, Code=0.01, MID=0x7d35)
| GET | Token: 0x20 | GET | Token: 0x20
skipping to change at page 102, line 10 skipping to change at page 105, line 42
0 1 2 3 0 1 2 3
0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| 1 | 2 | 1 | 2.05=69 | MID=0x7d35 | | 1 | 2 | 1 | 2.05=69 | MID=0x7d35 |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| 0x20 | | 0x20 |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|1 1 1 1 1 1 1 1| "22.3 C" (6 B) ... |1 1 1 1 1 1 1 1| "22.3 C" (6 B) ...
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
Figure 17: Confirmable request; piggy-backed response Figure 17: Confirmable Request; Piggybacked Response
In Figure 18, the Confirmable GET request is lost. After ACK_TIMEOUT In Figure 18, the Confirmable GET request is lost. After ACK_TIMEOUT
seconds, the client retransmits the request, resulting in a piggy- seconds, the client retransmits the request, resulting in a
backed response as in the previous example. piggybacked response as in the previous example.
Client Server Client Server
| | | |
| | | |
+----X | Header: GET (T=CON, Code=0.01, MID=0x7d36) +----X | Header: GET (T=CON, Code=0.01, MID=0x7d36)
| GET | Token: 0x31 | GET | Token: 0x31
| | Uri-Path: "temperature" | | Uri-Path: "temperature"
TIMEOUT | TIMEOUT |
| | | |
+----->| Header: GET (T=CON, Code=0.01, MID=0x7d36) +----->| Header: GET (T=CON, Code=0.01, MID=0x7d36)
| GET | Token: 0x31 | GET | Token: 0x31
| | Uri-Path: "temperature" | | Uri-Path: "temperature"
| | | |
| | | |
|<-----+ Header: 2.05 Content (T=ACK, Code=2.05, MID=0x7d36) |<-----+ Header: 2.05 Content (T=ACK, Code=2.05, MID=0x7d36)
| 2.05 | Token: 0x31 | 2.05 | Token: 0x31
| | Payload: "22.3 C" | | Payload: "22.3 C"
| | | |
Figure 18: Confirmable request (retransmitted); piggy-backed response Figure 18: Confirmable Request (Retransmitted); Piggybacked Response
In Figure 19, the first Acknowledgement message from the server to In Figure 19, the first Acknowledgement message from the server to
the client is lost. After ACK_TIMEOUT seconds, the client the client is lost. After ACK_TIMEOUT seconds, the client
retransmits the request. retransmits the request.
Client Server Client Server
| | | |
| | | |
+----->| Header: GET (T=CON, Code=0.01, MID=0x7d37) +----->| Header: GET (T=CON, Code=0.01, MID=0x7d37)
| GET | Token: 0x42 | GET | Token: 0x42
| | Uri-Path: "temperature" | | Uri-Path: "temperature"
skipping to change at page 103, line 17 skipping to change at page 107, line 31
+----->| Header: GET (T=CON, Code=0.01, MID=0x7d37) +----->| Header: GET (T=CON, Code=0.01, MID=0x7d37)
| GET | Token: 0x42 | GET | Token: 0x42
| | Uri-Path: "temperature" | | Uri-Path: "temperature"
| | | |
| | | |
|<-----+ Header: 2.05 Content (T=ACK, Code=2.05, MID=0x7d37) |<-----+ Header: 2.05 Content (T=ACK, Code=2.05, MID=0x7d37)
| 2.05 | Token: 0x42 | 2.05 | Token: 0x42
| | Payload: "22.3 C" | | Payload: "22.3 C"
| | | |
Figure 19: Confirmable request; piggy-backed response (retransmitted) Figure 19: Confirmable Request; Piggybacked Response (Retransmitted)
In Figure 20, the server acknowledges the Confirmable request and In Figure 20, the server acknowledges the Confirmable request and
sends a 2.05 (Content) response separately in a Confirmable message. sends a 2.05 (Content) response separately in a Confirmable message.
Note that the Acknowledgement message and the Confirmable response do Note that the Acknowledgement message and the Confirmable response do
not necessarily arrive in the same order as they were sent. The not necessarily arrive in the same order as they were sent. The
client acknowledges the Confirmable response. client acknowledges the Confirmable response.
Client Server Client Server
| | | |
| | | |
+----->| Header: GET (T=CON, Code=0.01, MID=0x7d38) +----->| Header: GET (T=CON, Code=0.01, MID=0x7d38)
skipping to change at page 103, line 44 skipping to change at page 108, line 29
| | | |
| | | |
|<-----+ Header: 2.05 Content (T=CON, Code=2.05, MID=0xad7b) |<-----+ Header: 2.05 Content (T=CON, Code=2.05, MID=0xad7b)
| 2.05 | Token: 0x53 | 2.05 | Token: 0x53
| | Payload: "22.3 C" | | Payload: "22.3 C"
| | | |
| | | |
+- - ->| Header: (T=ACK, Code=0.00, MID=0xad7b) +- - ->| Header: (T=ACK, Code=0.00, MID=0xad7b)
| | | |
Figure 20: Confirmable request; separate response Figure 20: Confirmable Request; Separate Response
Figure 21 shows an example where the client loses its state (e.g., Figure 21 shows an example where the client loses its state (e.g.,
crashes and is rebooted) right after sending a Confirmable request, crashes and is rebooted) right after sending a Confirmable request,
so the separate response arriving some time later comes unexpected. so the separate response arriving some time later comes unexpected.
In this case, the client rejects the Confirmable response with a In this case, the client rejects the Confirmable response with a
Reset message. Note that the unexpected ACK is silently ignored. Reset message. Note that the unexpected ACK is silently ignored.
Client Server Client Server
| | | |
| | | |
skipping to change at page 104, line 24 skipping to change at page 109, line 30
| | | |
| | | |
|<-----+ Header: 2.05 Content (T=CON, Code=2.05, MID=0xad7c) |<-----+ Header: 2.05 Content (T=CON, Code=2.05, MID=0xad7c)
| 2.05 | Token: 0x64 | 2.05 | Token: 0x64
| | Payload: "22.3 C" | | Payload: "22.3 C"
| | | |
| | | |
+- - ->| Header: (T=RST, Code=0.00, MID=0xad7c) +- - ->| Header: (T=RST, Code=0.00, MID=0xad7c)
| | | |
Figure 21: Confirmable request; separate response (unexpected) Figure 21: Confirmable Request; Separate Response (Unexpected)
Figure 22 shows a basic GET request where the request and the Figure 22 shows a basic GET request where the request and the
response are Non-confirmable, so both may be lost without notice. response are Non-confirmable, so both may be lost without notice.
Client Server Client Server
| | | |
| | | |
+----->| Header: GET (T=NON, Code=0.01, MID=0x7d40) +----->| Header: GET (T=NON, Code=0.01, MID=0x7d40)
| GET | Token: 0x75 | GET | Token: 0x75
| | Uri-Path: "temperature" | | Uri-Path: "temperature"
| | | |
| | | |
|<-----+ Header: 2.05 Content (T=NON, Code=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
skipping to change at page 105, line 27 skipping to change at page 110, line 35
| | | | | | | |
| X------------+ | Header: 2.05 (T=NON, Code=2.05, MID=0x01a0) | X------------+ | Header: 2.05 (T=NON, Code=2.05, MID=0x01a0)
| 2.05 | | | Token: 0x86 | 2.05 | | | Token: 0x86
| | | | Payload: "20.9 C" | | | | Payload: "20.9 C"
| | | | | | | |
| | | | | | | |
|<------------------+ Header: 4.04 (T=NON, Code=4.04, MID=0x952a) |<------------------+ Header: 4.04 (T=NON, Code=4.04, MID=0x952a)
| 4.04 | | | Token: 0x86 | 4.04 | | | Token: 0x86
| | | | | | | |
Figure 23: Non-confirmable request (multicast); Non-confirmable Figure 23: Non-confirmable Request (Multicast); Non-confirmable
response Response
Appendix B. URI Examples Appendix B. URI Examples
The following examples demonstrate different sets of Uri options, and The following examples demonstrate different sets of Uri options, and
the result after constructing an URI from them. In addition to the the result after constructing an URI from them. In addition to the
options, Section 6.5 refers to the destination IP address and port, options, Section 6.5 refers to the destination IP address and port,
but not all paths of the algorithm cause the destination IP address but not all paths of the algorithm cause the destination IP address
and port to be included in the URI. and port to be included in the URI.
o Input: o Input:
skipping to change at page 107, line 5 skipping to change at page 112, line 20
Uri-Path = "/" Uri-Path = "/"
Uri-Path = "" Uri-Path = ""
Uri-Path = "" Uri-Path = ""
Uri-Query = "//" Uri-Query = "//"
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
(To be removed by RFC editor before publication.)
Changes from ietf-17 to ietf-18: Address comments from the IESG
reviews.
o Accept is now critical.
o Add Size1 option for 4.13 responses.
Changes from ietf-15 to ietf-16: Address comments from the IESG
reviews. These should not impact interoperability.
o Clarify that once there has been an empty ACK, all further ACKs to
the same message also must be empty (#301).
o Define Cache-key properly (#302).
o Clarify that ACKs don't get retransmitted, the CONs do (#303).
o Clarify: NON is like separate for CON (#304).
o Don't use decimal response codes, keep the 3+5 structure
throughout (#305).
o RFC 2119 usage in 4.5 (#306) and 8.2 (#307).
o Ensure all protocol reactions to reserved or prohibited values are
defined (#308).
o URI matching rules may be scheme specific (#309).
o Don't dally beyond MAX_TRANSMIT_SPAN during retransmission (#310).
o More about selecting a token length for anti-spoofing (#311).
o Discuss spoofing ACKs (#312).
o Qualify partial discard strategy implementation note as UDP only
(#313).
o Explicitly point out that UDP and DTLS don't mix (#314).
o Point out security consideration re URIs and access control
(#315).
o Point to RFC5280 section 6 (#316).
o Add a paragraph about cert status checking (#317).
o RSA is out, ECDHE is in for cert-with-PSK, too (#318).
o Point out that requests and responses don't always come in pairs
(#319).
o Clarify when there is a need for Unicode normalization (#320).
o Point out that Uri-Host doesn't handle user-part (#321).
o Clarify the use of non-FQDN Authority Names in certificates.
o Numerous editorial improvements and clarifications.
Changes from ietf-14 to ietf-15: Address comments from IETF last-
call, mostly implementation notes and editorial improvements. These
should not impact interoperability.
o Clarify bytes/characters and UTF-8/ASCII in "Decomposing URIs into
Options" (#282).
o Make reference to ECC/CCM DTLS ciphersuite normative (#286).
o Add a quick warning that bytewise scanning for a payload marker is
not a good idea (#287).
o Make reference to PROBING_RATE explicit for saturation discussion
(#288).
o Mention PROCESSING_DELAY when discussion piggy-backing (#290).
o Various editorial nits: Clarify use of noun "service" (#283),
Reference terminology from lwig-terminology (#284), make reference
to HTTP terms more explicit (#285), add a forward reference to
5.9.2.9 (#289), 8 kbit/s is not "conservative" (#291).
o Add description of resource depletion attack (#292).
o Add description of DoS attack on congestion control (#293).
o Add discussion of using non-trivial token for protecting against
hijacking (#294).
o Clarify implementation note about per-destination Message ID
generation.
Changed from ietf-13 to ietf-14:
o Made Accept option non-repeatable.
o Clarified that Safe options in a 2.03 Valid response update the
cache.
o Clarified that payload sniffing is acceptable only if no Content-
Format was supplied.
o Clarified URI examples (Appendix B).
o Numerous editorial improvements and clarifications.
Changed from ietf-12 to ietf-13:
o Simplified message format.
* Removed the OC (Option Count) field in the CoAP Header.
* Changed the End-of-Options Marker into the Payload Marker.
* Changed the format of Options: use 4 bits for option length and
delta; insert one or two additional bytes after the option
header if necessary.
* Promoted the Token Option to a field following the CoAP Header.
o Clarified when a payload is a diagnostic payload (#264).
o Moved IPsec discussion to separate draft (#262).
o Added a reference to a separate draft on reverse-proxy URI
embedding (#259).
o Clarified the use of ETags and of 2.03 responses (#265, #254,
#256).
o Added reserved Location-* numbers and clarified Location-*.
o Added Proxy-Scheme proposal.
o Clarified terms such as content negotiation, selected
representation, representation-format, message format error.
o Numerous clarifications and a few bugfixes.
Changed from ietf-11 to ietf-12:
o Extended options to support lengths of up to 1034 bytes (#202).
o Added new Jump mechanism for options and removed Fenceposting
(#214).
o Added new IANA option number registration policy (#214).
o Added Proxy Unsafe/Safe and Cache-Key masking to option numbers
(#241).
o Re-numbered option numbers to use Unsafe/Safe and Cache-Key
compliant numbers (#241).
o Defined NSTART and restricted the value to 1 with a MUST (#215).
o Defined PROBING_RATE and set it to 1 Byte/second (#215).
o Defined DEFAULT_LEISURE (#246).
o Renamed Content-Type into Content-Format, and Media Type registry
into Content-Format registry.
o A large number of small editorial changes, clarifications and
improvements have been made.
Changed from ietf-10 to ietf-11:
o Expanded section 4.8 on Transmission Parameters, and used the
derived values defined there (#201). Changed parameter names to
be shorter and more to the point.
o Several more small editorial changes, clarifications and
improvements have been made.
Changed from ietf-09 to ietf-10:
o Option deltas are restricted to 0 to 14; the option delta 15 is
used exclusively for the end-of-options marker (#239).
o Option numbers that are a multiple of 14 are not reserved, but are
required to have an empty default value (#212).
o Fixed misleading language that was introduced in 5.10.2 in coap-07
re Uri-Host and Uri-Port (#208).
o Segments and arguments can have a length of zero characters
(#213).
o The Location-* options describe together describe one location.
The location is a relative URI, not an "absolute path URI" (#218).
o The value of the Location-Path Option must not be '.' or '..'
(#218).
o Added a sentence on constructing URIs from Location-* options
(#231).
o Reserved option numbers for future Location-* options (#230).
o Fixed response codes with payload inconsistency (#233).
o Added advice on default values for critical options (#207).
o Clarified use of identifiers in RawPublicKey Mode Provisioning
(#222).
o Moved "Securing CoAP" out of the "Security Considerations" (#229).
o Added "All CoAP Nodes" multicast addresses to "IANA
Considerations" (#216).
o Over 100 small editorial changes, clarifications and improvements
have been made.
Changed from ietf-08 to ietf-09:
o Improved consistency of statements about RST on NON: RST is a
valid response to a NON message (#183).
o Clarified that the protocol constants can be configured for
specific application environments.
o Added implementation note recommending piggy-backing whenever
possible (#182).
o Added a content-encoding column to the media type registry (#181).
o Minor improvements to Appendix D.
o Added text about multicast response suppression (#177).
o Included the new End-of-options Marker (#176).
o Added a reference to draft-ietf-tls-oob-pubkey and updated the RPK
text accordingly.
Changed from ietf-07 to ietf-08:
o Clarified matching rules for messages (#175)
o Fixed a bug in Section 8.2.2 on Etags (#168)
o Added an IP address spoofing threat analysis contribution (#167)
o Re-focused the security section on raw public keys (#166)
o Added an 4.06 error to Accept (#165)
Changed from ietf-06 to ietf-07:
o application/link-format added to Media types registration (#160)
o Moved content-type attribute to the document from link-format.
o Added coaps scheme and DTLS-secured CoAP default port (#154)
o Allowed 0-length Content-type options (#150)
o Added congestion control recommendations (#153)
o Improved text on PUT/POST response payloads (#149)
o Added an Accept option for content-negotiation (#163)
o Added If-Match and If-None-Match options (#155)
o Improved Token Option explanation (#147)
o Clarified mandatory to implement security (#156)
o Added first come first server policy for 2-byte Media type codes
(#161)
o Clarify matching rules for messages and tokens (#151)
o Changed OPTIONS and TRACE to always return 501 in HTTP-CoAP
mapping (#164)
Changed from ietf-05 to ietf-06:
o HTTP mapping section improved with the minimal protocol standard
text for CoAP-HTTP and HTTP-CoAP forward proxying (#137).
o Eradicated percent-encoding by including one Uri-Query Option per
&-delimited argument in a query.
o Allowed RST message in reply to a NON message with unexpected
token (#135).
o Cache Invalidation only happens upon successful responses (#134).
o 50% jitter added to the initial retransmit timer (#142).
o DTLS cipher suites aligned with ZigBee IP, DTLS clarified as
default CoAP security mechanism (#138, #139)
o Added a minimal reference to draft-kivinen-ipsecme-ikev2-minimal
(#140).
o Clarified the comparison of UTF-8s (#136).
o Minimized the initial media type registry (#101).
Changed from ietf-04 to ietf-05:
o Renamed Immediate into Piggy-backed and Deferred into Separate --
should finally end the confusion on what this is about.
o GET requests now return a 2.05 (Content) response instead of 2.00
(OK) response (#104).
o Added text to allow 2.02 (Deleted) responses in reply to POST
requests (#105).
o Improved message deduplication rules (#106).
o Section added on message size implementation considerations
(#103).
o Clarification made on human readable error payloads (#109).
o Definition of CoAP methods improved (#108).
o Max-Age removed from requests (#107).
o Clarified uniqueness of tokens (#112).
o Location-Query Option added (#113).
o ETag length set to 1-8 bytes (#123).
o Clarified relation between elective/critical and option numbers
(#110).
o Defined when to update Version header field (#111).
o URI scheme registration improved (#102).
o Added review guidelines for new CoAP codes and numbers.
Changes from ietf-03 to ietf-04:
o Major document reorganization (#51, #63, #71, #81).
o Max-age length set to 0-4 bytes (#30).
o Added variable unsigned integer definition (#31).
o Clarification made on human readable error payloads (#50).
o Definition of POST improved (#52).
o Token length changed to 0-8 bytes (#53).
o Section added on multiplexing CoAP, DTLS and STUN (#56).
o Added cross-protocol attack considerations (#61).
o Used new Immediate/Deferred response definitions (#73).
o Improved request/response matching rules (#74).
o Removed unnecessary media types and added recommendations for
their use in M2M (#76).
o Response codes changed to base 32 coding, new Y.XX naming (#77).
o References updated as per AD review (#79).
o IANA section completed (#80).
o Proxy-Uri Option added to disambiguate between proxy and non-proxy
requests (#82).
o Added text on critical options in cached states (#83).
o HTTP mapping sections improved (#88).
o Added text on reverse proxies (#72).
o Some security text on multicast added (#54).
o Trust model text added to introduction (#58, #60).
o AES-CCM vs. AES-CCB text added (#55).
o Text added about device capabilities (#59).
o DTLS section improvements (#87).
o Caching semantics aligned with RFC2616 (#78).
o Uri-Path Option split into multiple path segments.
o MAX_RETRANSMIT changed to 4 to adjust for RESPONSE_TIME = 2.
Changes from ietf-02 to ietf-03:
o Token Option and related use in asynchronous requests added (#25).
o CoAP specific error codes added (#26).
o Erroring out on unknown critical options changed to a MUST (#27).
o Uri-Query Option added.
o Terminology and definitions of URIs improved.
o Security section completed (#22).
Changes from ietf-01 to ietf-02:
o Sending an error on a critical option clarified (#18).
o Clarification on behavior of PUT and idempotent operations (#19).
o Use of Uri-Authority clarified along with server processing rules;
Uri-Scheme Option removed (#20, #23).
o Resource discovery section removed to a separate CoRE Link Format
draft (#21).
o Initial security section outline added.
Changes from ietf-00 to ietf-01:
o New cleaner transaction message model and header (#5).
o Removed subscription while being designed (#1).
o Section 2 re-written (#3).
o Text added about use of short URIs (#4).
o Improved header option scheme (#5, #14).
o Date option removed whiled being designed (#6).
o New text for CoAP default port (#7).
o Completed proxying section (#8).
o Completed resource discovery section (#9).
o Completed HTTP mapping section (#10).
o Several new examples added (#11).
o URI split into 3 options (#12).
o MIME type defined for link-format (#13, #16).
o New text on maximum message size (#15).
o Location Option added.
Changes from shelby-01 to ietf-00:
o Removed the TCP binding section, left open for the future.
o Fixed a bug in the example.
o Marked current Sub/Notify as (Experimental) while under WG
discussion.
o Fixed maximum datagram size to 1280 for both IPv4 and IPv6 (for
CoAP-CoAP proxying to work).
o Temporarily removed the Magic Byte header as TCP is no longer
included as a binding.
o Removed the Uri-code Option as different URI encoding schemes are
being discussed.
o Changed the rel= field to desc= for resource discovery.
o Changed the maximum message size to 1024 bytes to allow for IP/UDP
headers.
o Made the URI slash optimization and method idempotence MUSTs
o Minor editing and bug fixing.
Changes from shelby-00 to shelby-01:
o Unified the message header and added a notify message type.
o Renamed methods with HTTP names and removed the NOTIFY method.
o Added a number of options field to the header.
o Combines the Option Type and Length into an 8-bit field.
o Added the magic byte header.
o Added new ETag Option.
o Added new Date Option.
o Added new Subscription Option.
o Completed the HTTP Code - CoAP Code mapping table appendix.
o Completed the Content-type Identifier appendix and tables.
o Added more simplifications for URI support.
o Initial subscription and discovery sections.
o A Flag requirements simplified.
Authors' Addresses Authors' Addresses
Zach Shelby Zach Shelby
Sensinode ARM
Kidekuja 2 150 Rose Orchard
Vuokatti 88600 San Jose, CA 95134
Finland USA
Phone: +358407796297 Phone: +1-408-203-9434
Email: zach@sensinode.com EMail: zach.shelby@arm.com
Klaus Hartke Klaus Hartke
Universitaet Bremen TZI Universitaet Bremen TZI
Postfach 330440 Postfach 330440
Bremen D-28359 Bremen D-28359
Germany Germany
Phone: +49-421-218-63905 Phone: +49-421-218-63905
Email: hartke@tzi.org EMail: hartke@tzi.org
Carsten Bormann Carsten Bormann
Universitaet Bremen TZI Universitaet Bremen TZI
Postfach 330440 Postfach 330440
Bremen D-28359 Bremen D-28359
Germany Germany
Phone: +49-421-218-63921 Phone: +49-421-218-63921
Email: cabo@tzi.org EMail: cabo@tzi.org
 End of changes. 510 change blocks. 
1882 lines changed or deleted 1391 lines changed or added

This html diff was produced by rfcdiff 1.45. The latest version is available from http://tools.ietf.org/tools/rfcdiff/