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

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