RFC 7252
The Constrained Application Protocol (CoAP)
12. IANA Considerations
12.1. CoAP Code Registries
This document defines two sub-registries for the values of the Code field in the CoAP header within the "Constrained RESTful Environments (CoRE) Parameters" registry, hereafter referred to as the "CoRE Parameters" registry. Values in the two sub-registries are eight-bit values notated as three decimal digits c.dd separated by a period between the first and the second digit; the first digit c is between 0 and 7 and denotes the code class; the second and third digits dd denote a decimal number between 00 and 31 for the detail.
All Code values are assigned by sub-registries according to the following ranges: 0.00 Indicates an Empty message (see Section 4.1). 0.01-0.31 Indicates a request. Values in this range are assigned by the "CoAP Method Codes" sub-registry (see Section 12.1.1). 1.00-1.31 Reserved 2.00-5.31 Indicates a response. Values in this range are assigned by the "CoAP Response Codes" sub-registry (see Section 12.1.2). 6.00-7.31 Reserved12.1.1. Method Codes
The name of the sub-registry is "CoAP Method Codes". Each entry in the sub-registry must include the Method Code in the range 0.01-0.31, the name of the method, and a reference to the method's documentation. Initial entries in this sub-registry are as follows: +------+--------+-----------+ | Code | Name | Reference | +------+--------+-----------+ | 0.01 | GET | [RFC7252] | | 0.02 | POST | [RFC7252] | | 0.03 | PUT | [RFC7252] | | 0.04 | DELETE | [RFC7252] | +------+--------+-----------+ Table 5: CoAP Method Codes All other Method Codes are Unassigned. The IANA policy for future additions to this sub-registry is "IETF Review or IESG Approval" as described in [RFC5226]. The documentation of a Method Code should specify the semantics of a request with that code, including the following properties: o The Response Codes the method returns in the success case. o Whether the method is idempotent, safe, or both.
12.1.2. 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 range 2.00-5.31, a description of the Response Code, and a reference to the Response Code's documentation. Initial entries in this sub-registry are as follows: +------+------------------------------+-----------+ | Code | Description | Reference | +------+------------------------------+-----------+ | 2.01 | Created | [RFC7252] | | 2.02 | Deleted | [RFC7252] | | 2.03 | Valid | [RFC7252] | | 2.04 | Changed | [RFC7252] | | 2.05 | Content | [RFC7252] | | 4.00 | Bad Request | [RFC7252] | | 4.01 | Unauthorized | [RFC7252] | | 4.02 | Bad Option | [RFC7252] | | 4.03 | Forbidden | [RFC7252] | | 4.04 | Not Found | [RFC7252] | | 4.05 | Method Not Allowed | [RFC7252] | | 4.06 | Not Acceptable | [RFC7252] | | 4.12 | Precondition Failed | [RFC7252] | | 4.13 | Request Entity Too Large | [RFC7252] | | 4.15 | Unsupported Content-Format | [RFC7252] | | 5.00 | Internal Server Error | [RFC7252] | | 5.01 | Not Implemented | [RFC7252] | | 5.02 | Bad Gateway | [RFC7252] | | 5.03 | Service Unavailable | [RFC7252] | | 5.04 | Gateway Timeout | [RFC7252] | | 5.05 | Proxying Not Supported | [RFC7252] | +------+------------------------------+-----------+ Table 6: CoAP Response Codes The Response Codes 3.00-3.31 are Reserved for future use. All other Response Codes are Unassigned. The IANA policy for future additions to this sub-registry is "IETF Review or IESG Approval" as described in [RFC5226].
The documentation of a Response Code should specify the semantics of
a response with that code, including the following properties:
o The methods the Response Code applies to.
o Whether payload is required, optional, or not allowed.
o The semantics of the payload. For example, the payload of a 2.05
(Content) response is a representation of the target resource; the
payload in an error response is a human-readable diagnostic
payload.
o The format of the payload. For example, the format in a 2.05
(Content) response is indicated by the Content-Format Option; the
format of the payload in an error response is always Net-Unicode
text.
o Whether the response is cacheable according to the freshness
model.
o Whether the response is validatable according to the validation
model.
o Whether the response causes a cache to mark responses stored for
the request URI as not fresh.
12.2. CoAP Option Numbers Registry
This document defines a sub-registry for the Option Numbers used in
CoAP options within the "CoRE Parameters" registry. The name of the
sub-registry is "CoAP Option Numbers".
Each entry in the sub-registry must include the Option Number, the
name of the option, and a reference to the option's documentation.
Initial entries in this sub-registry are as follows: +--------+------------------+-----------+ | Number | Name | Reference | +--------+------------------+-----------+ | 0 | (Reserved) | [RFC7252] | | 1 | If-Match | [RFC7252] | | 3 | Uri-Host | [RFC7252] | | 4 | ETag | [RFC7252] | | 5 | If-None-Match | [RFC7252] | | 7 | Uri-Port | [RFC7252] | | 8 | Location-Path | [RFC7252] | | 11 | Uri-Path | [RFC7252] | | 12 | Content-Format | [RFC7252] | | 14 | Max-Age | [RFC7252] | | 15 | Uri-Query | [RFC7252] | | 17 | Accept | [RFC7252] | | 20 | Location-Query | [RFC7252] | | 35 | Proxy-Uri | [RFC7252] | | 39 | Proxy-Scheme | [RFC7252] | | 60 | Size1 | [RFC7252] | | 128 | (Reserved) | [RFC7252] | | 132 | (Reserved) | [RFC7252] | | 136 | (Reserved) | [RFC7252] | | 140 | (Reserved) | [RFC7252] | +--------+------------------+-----------+ Table 7: CoAP Option Numbers The IANA policy for future additions to this sub-registry is split into three tiers as follows. The range of 0..255 is reserved for options defined by the IETF (IETF Review or IESG Approval). The range of 256..2047 is reserved for commonly used options with public specifications (Specification Required). The range of 2048..64999 is for all other options including private or vendor-specific ones, which undergo a Designated Expert review to help ensure that the option semantics are defined correctly. The option numbers between 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 operational deployments.
+-------------+---------------------------------------+ | Range | Registration Procedures | +-------------+---------------------------------------+ | 0-255 | IETF Review or IESG Approval | | 256-2047 | Specification Required | | 2048-64999 | Expert Review | | 65000-65535 | Experimental use (no operational use) | +-------------+---------------------------------------+ Table 8: CoAP Option Numbers: Registration Procedures The documentation of an Option Number should specify the semantics of an option with that number, including the following properties: o The meaning of the option in a request. o The meaning of the option in a response. o Whether the option is critical or elective, as determined by the Option Number. o Whether the option is Safe-to-Forward, and, if yes, whether it is part of the Cache-Key, as determined by the Option Number (see Section 5.4.2). o The format and length of the option's value. o Whether the option must occur at most once or whether it can occur multiple times. o The default value, if any. For a critical option with a default value, a discussion on how the default value enables processing by implementations that do not support the critical option (Section 5.4.4).12.3. CoAP Content-Formats Registry
Internet media types are identified by a string, such as "application/xml" [RFC2046]. In order to minimize the overhead of using these media types to indicate the format of payloads, this document defines a sub-registry for a subset of Internet media types to be used in CoAP and assigns each, in combination with a content- coding, a numeric identifier. The name of the sub-registry is "CoAP Content-Formats", within the "CoRE Parameters" registry.
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 that media type in CoAP, the content-coding associated with this identifier, and a reference to a document describing what a payload with that media type means semantically. CoAP does not include a separate way to convey content-encoding information with a request or response, and for that reason the content-encoding is also specified for each identifier (if any). If multiple content-encodings will be used with a media type, then a separate Content-Format identifier for each is to be registered. Similarly, other parameters related to an Internet media type, such as level, can be defined for a CoAP Content-Format entry. Initial entries in this sub-registry are as follows: +--------------------------+----------+----+------------------------+ | Media type | Encoding | ID | Reference | +--------------------------+----------+----+------------------------+ | text/plain; | - | 0 | [RFC2046] [RFC3676] | | charset=utf-8 | | | [RFC5147] | | application/link-format | - | 40 | [RFC6690] | | application/xml | - | 41 | [RFC3023] | | application/octet-stream | - | 42 | [RFC2045] [RFC2046] | | application/exi | - | 47 | [REC-exi-20140211] | | application/json | - | 50 | [RFC7159] | +--------------------------+----------+----+------------------------+ Table 9: CoAP Content-Formats The identifiers between 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 operational deployments. The identifiers between 256 and 9999 are reserved for future use in IETF specifications (IETF Review or IESG Approval). All other identifiers are Unassigned. Because the namespace of single-byte identifiers is so small, the IANA policy for future additions in the range 0-255 inclusive to the sub-registry is "Expert Review" as described in [RFC5226]. The IANA policy for additions in the range 10000-64999 inclusive is "First Come First Served" as described in [RFC5226]. This is summarized in the following table.
+-------------+---------------------------------------+ | Range | Registration Procedures | +-------------+---------------------------------------+ | 0-255 | Expert Review | | 256-9999 | IETF Review or IESG Approval | | 10000-64999 | First Come First Served | | 65000-65535 | Experimental use (no operational use) | +-------------+---------------------------------------+ Table 10: CoAP Content-Formats: Registration Procedures In machine-to-machine applications, it is not expected that generic Internet media types such as text/plain, application/xml or application/octet-stream are useful for real applications in the long term. It is recommended that M2M applications making use of CoAP request new Internet media types from IANA indicating semantic information about how to create or parse a payload. For example, a Smart Energy application payload carried as XML might request a more specific type like application/se+xml or application/se-exi.12.4. URI Scheme Registration
This document contains the request for the registration of the Uniform Resource Identifier (URI) scheme "coap". The registration request complies with [RFC4395]. URI scheme name. coap Status. Permanent. URI scheme syntax. Defined in Section 6.1 of [RFC7252]. URI scheme semantics. The "coap" URI scheme provides a way to identify resources that are potentially accessible over the Constrained Application Protocol (CoAP). The resources can be located by contacting the governing CoAP server and operated on by sending CoAP requests to the server. This scheme can thus be compared to the "http" URI scheme [RFC2616]. See Section 6 of [RFC7252] for the details of operation. Encoding considerations. The scheme encoding conforms to the encoding rules established for URIs in [RFC3986], i.e., internationalized and reserved characters are expressed using UTF-8-based percent-encoding.
Applications/protocols that use this URI scheme name.
The scheme is used by CoAP endpoints to access CoAP resources.
Interoperability considerations.
None.
Security considerations.
See Section 11.1 of [RFC7252].
Contact.
IETF Chair <chair@ietf.org>
Author/Change controller.
IESG <iesg@ietf.org>
References.
[RFC7252]
12.5. Secure URI Scheme Registration
This document contains the request for the registration of the
Uniform Resource Identifier (URI) scheme "coaps". The registration
request complies with [RFC4395].
URI scheme name.
coaps
Status.
Permanent.
URI scheme syntax.
Defined in Section 6.2 of [RFC7252].
URI scheme semantics.
The "coaps" URI scheme provides a way to identify resources that
are potentially accessible over the Constrained Application
Protocol (CoAP) using Datagram Transport Layer Security (DTLS) for
transport security. The resources can be located by contacting
the governing CoAP server and operated on by sending CoAP requests
to the server. This scheme can thus be compared to the "https"
URI scheme [RFC2616]. See Section 6 of [RFC7252] for the details
of operation.
Encoding considerations.
The scheme encoding conforms to the encoding rules established for
URIs in [RFC3986], i.e., internationalized and reserved characters
are expressed using UTF-8-based percent-encoding.
Applications/protocols that use this URI scheme name.
The scheme is used by CoAP endpoints to access CoAP resources
using DTLS.
Interoperability considerations.
None.
Security considerations.
See Section 11.1 of [RFC7252].
Contact.
IETF Chair <chair@ietf.org>
Author/Change controller.
IESG <iesg@ietf.org>
References.
[RFC7252]
12.6. Service Name and Port Number Registration
One of the functions of CoAP is resource discovery: a CoAP client can
ask a CoAP server about the resources offered by it (see Section 7).
To enable resource discovery just based on the knowledge of an IP
address, the CoAP port for resource discovery needs to be
standardized.
IANA has assigned the port number 5683 and the service name "coap",
in accordance with [RFC6335].
Besides unicast, CoAP can be used with both multicast and anycast.
Service Name.
coap
Transport Protocol.
udp
Assignee.
IESG <iesg@ietf.org>
Contact.
IETF Chair <chair@ietf.org>
Description.
Constrained Application Protocol (CoAP)
Reference.
[RFC7252]
Port Number.
5683
12.7. Secure Service Name and Port Number Registration
CoAP resource discovery may also be provided using the DTLS-secured
CoAP "coaps" scheme. Thus, the CoAP port for secure resource
discovery needs to be standardized.
IANA has assigned the port number 5684 and the service name "coaps",
in accordance with [RFC6335].
Besides unicast, DTLS-secured CoAP can be used with anycast.
Service Name.
coaps
Transport Protocol.
udp
Assignee.
IESG <iesg@ietf.org>
Contact.
IETF Chair <chair@ietf.org>
Description.
DTLS-secured CoAP
Reference.
[RFC7252]
Port Number.
5684
12.8. Multicast Address Registration
Section 8, "Multicast CoAP", defines the use of multicast. IANA has assigned the following multicast addresses for use by CoAP nodes: IPv4 -- "All CoAP Nodes" address 224.0.1.187, from the "IPv4 Multicast Address Space Registry". As the address is used for discovery that may span beyond a single network, it has come from the Internetwork Control Block (224.0.1.x, RFC 5771). IPv6 -- "All CoAP Nodes" address FF0X::FD, from the "IPv6 Multicast Address Space Registry", in the "Variable Scope Multicast Addresses" space (RFC 3307). Note that there is a distinct multicast address for each scope that interested CoAP nodes should listen to; CoAP needs the Link-Local and Site-Local scopes only.13. Acknowledgements
Brian Frank was a contributor to and coauthor of early versions of this specification. Special thanks to Peter Bigot, Esko Dijk, and Cullen Jennings for substantial contributions to the ideas and text in the document, along with countless detailed reviews and discussions. Thanks to Floris Van den Abeele, Anthony Baire, Ed Beroset, Berta Carballido, Angelo P. Castellani, Gilbert Clark, Robert Cragie, Pierre David, Esko Dijk, Lisa Dusseault, Mehmet Ersue, Thomas Fossati, Tobias Gondrom, Bert Greevenbosch, Tom Herbst, Jeroen Hoebeke, Richard Kelsey, Sye Loong Keoh, Ari Keranen, Matthias Kovatsch, Avi Lior, Stephan Lohse, Salvatore Loreto, Kerry Lynn, Andrew McGregor, Alexey Melnikov, Guido Moritz, Petri Mutka, Colin O'Flynn, Charles Palmer, Adriano Pezzuto, Thomas Poetsch, Robert Quattlebaum, Akbar Rahman, Eric Rescorla, Dan Romascanu, David Ryan, Peter Saint-Andre, Szymon Sasin, Michael Scharf, Dale Seed, Robby Simpson, Peter van der Stok, Michael Stuber, Linyi Tian, Gilman Tolle, Matthieu Vial, Maciej Wasilak, Fan Xianyou, and Alper Yegin for helpful comments and discussions that have shaped the document. Special thanks also to the responsible IETF area director at the time of completion, Barry Leiba, and the IESG reviewers, Adrian Farrel, Martin Stiemerling, Pete Resnick, Richard Barnes, Sean Turner, Spencer Dawkins, Stephen Farrell, and Ted Lemon, who contributed in- depth reviews. Some of the text has been borrowed from the working documents of the IETF HTTPBIS working group.
14. References
14.1. Normative References
[RFC0768] Postel, J., "User Datagram Protocol", STD 6, RFC 768, August 1980. [RFC2045] Freed, N. and N. Borenstein, "Multipurpose Internet Mail Extensions (MIME) Part One: Format of Internet Message Bodies", RFC 2045, November 1996. [RFC2046] Freed, N. and N. Borenstein, "Multipurpose Internet Mail Extensions (MIME) Part Two: Media Types", RFC 2046, November 1996. [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, March 1997. [RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999. [RFC3023] Murata, M., St. Laurent, S., and D. Kohn, "XML Media Types", RFC 3023, January 2001. [RFC3629] Yergeau, F., "UTF-8, a transformation format of ISO 10646", STD 63, RFC 3629, November 2003. [RFC3676] Gellens, R., "The Text/Plain Format and DelSp Parameters", RFC 3676, February 2004. [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform Resource Identifier (URI): Generic Syntax", STD 66, RFC 3986, January 2005. [RFC4279] Eronen, P. and H. Tschofenig, "Pre-Shared Key Ciphersuites for Transport Layer Security (TLS)", RFC 4279, December 2005. [RFC4395] Hansen, T., Hardie, T., and L. Masinter, "Guidelines and Registration Procedures for New URI Schemes", BCP 35, RFC 4395, February 2006. [RFC5147] Wilde, E. and M. Duerst, "URI Fragment Identifiers for the text/plain Media Type", RFC 5147, April 2008. [RFC5198] Klensin, J. and M. Padlipsky, "Unicode Format for Network Interchange", RFC 5198, March 2008.
[RFC5226] Narten, T. and H. Alvestrand, "Guidelines for Writing an IANA Considerations Section in RFCs", BCP 26, RFC 5226, May 2008. [RFC5234] Crocker, D. and P. Overell, "Augmented BNF for Syntax Specifications: ABNF", STD 68, RFC 5234, January 2008. [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security (TLS) Protocol Version 1.2", RFC 5246, August 2008. [RFC5280] Cooper, D., Santesson, S., Farrell, S., Boeyen, S., Housley, R., and W. Polk, "Internet X.509 Public Key Infrastructure Certificate and Certificate Revocation List (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 Uniform Resource Identifiers (URIs)", RFC 5785, April 2010. [RFC5952] Kawamura, S. and M. Kawashima, "A Recommendation for IPv6 Address Text Representation", RFC 5952, August 2010. [RFC5988] Nottingham, M., "Web Linking", RFC 5988, October 2010. [RFC6066] Eastlake, D., "Transport Layer Security (TLS) Extensions: Extension Definitions", RFC 6066, January 2011. [RFC6347] Rescorla, E. and N. Modadugu, "Datagram Transport Layer Security Version 1.2", RFC 6347, January 2012. [RFC6690] Shelby, Z., "Constrained RESTful Environments (CoRE) Link Format", RFC 6690, August 2012. [RFC6920] Farrell, S., Kutscher, D., Dannewitz, C., Ohlman, B., Keranen, A., and P. Hallam-Baker, "Naming Things with Hashes", RFC 6920, April 2013. [RFC7250] Wouters, P., Tschofenig, H., Gilmore, J., Weiler, S., and T. Kivinen, "Using Raw Public Keys in Transport Layer Security (TLS) and Datagram Transport Layer Security (DTLS)", RFC 7250, June 2014.
[RFC7251] McGrew, D., Bailey, D., Campagna, M., and R. Dugal, "AES- CCM Elliptic Curve Cryptography (ECC) Cipher Suites for Transport Layer Security (TLS)", RFC 7251, June 2014.14.2. Informative References
[BLOCK] Bormann, C. and Z. Shelby, "Blockwise transfers in CoAP", Work in Progress, October 2013. [CoAP-MISC] Bormann, C. and K. Hartke, "Miscellaneous additions to CoAP", Work in Progress, December 2013. [EUI64] IEEE Standards Association, "Guidelines for 64-bit Global Identifier (EUI-64 (TM))", Registration Authority Tutorials, April 2010, <http://standards.ieee.org/regauth/ oui/tutorials/EUI64.html>. [GROUPCOMM] Rahman, A. and E. Dijk, "Group Communication for CoAP", Work in Progress, December 2013. [HHGTTG] Adams, D., "The Hitchhiker's Guide to the Galaxy", Pan Books ISBN 3320258648, 1979. [IEEE1003.1] IEEE and The Open Group, "Portable Operating System Interface (POSIX)", The Open Group Base Specifications Issue 7, IEEE 1003.1, 2013 Edition, <http://pubs.opengroup.org/onlinepubs/9699919799/>. [IPsec-CoAP] Bormann, C., "Using CoAP with IPsec", Work in Progress, December 2012. [MAPPING] Castellani, A., Loreto, S., Rahman, A., Fossati, T., and E. Dijk, "Guidelines for HTTP-CoAP Mapping Implementations", Work in Progress, February 2014. [OBSERVE] Hartke, K., "Observing Resources in CoAP", Work in Progress, April 2014. [REC-exi-20140211] Schneider, J., Kamiya, T., Peintner, D., and R. Kyusakov, "Efficient XML Interchange (EXI) Format 1.0 (Second Edition)", W3C Recommendation REC-exi-20140211, February 2014, <http://www.w3.org/TR/2014/REC-exi-20140211/>.
[REST] Fielding, R., "Architectural Styles and the Design of Network-based Software Architectures", Ph.D. Dissertation, University of California, Irvine, 2000, <http://www.ics.uci.edu/~fielding/pubs/dissertation/ fielding_dissertation.pdf>. [RFC0020] Cerf, V., "ASCII format for network interchange", RFC 20, October 1969. [RFC0791] Postel, J., "Internet Protocol", STD 5, RFC 791, September 1981. [RFC0792] Postel, J., "Internet Control Message Protocol", STD 5, RFC 792, September 1981. [RFC0793] Postel, J., "Transmission Control Protocol", STD 7, RFC 793, September 1981. [RFC1035] Mockapetris, P., "Domain names - implementation and specification", STD 13, RFC 1035, November 1987. [RFC3264] Rosenberg, J. and H. Schulzrinne, "An Offer/Answer Model with Session Description Protocol (SDP)", RFC 3264, June 2002. [RFC3280] Housley, R., Polk, W., Ford, W., and D. Solo, "Internet X.509 Public Key Infrastructure Certificate and Certificate Revocation List (CRL) Profile", RFC 3280, April 2002. [RFC3542] Stevens, W., Thomas, M., Nordmark, E., and T. Jinmei, "Advanced Sockets Application Program Interface (API) for 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 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. Moeller, "Elliptic Curve Cryptography (ECC) Cipher Suites for Transport Layer Security (TLS)", RFC 4492, May 2006.
[RFC4821] Mathis, M. and J. Heffner, "Packetization Layer Path MTU Discovery", RFC 4821, March 2007. [RFC4944] Montenegro, G., Kushalnagar, N., Hui, J., and D. Culler, "Transmission of IPv6 Packets over IEEE 802.15.4 Networks", RFC 4944, September 2007. [RFC5405] Eggert, L. and G. Fairhurst, "Unicast UDP Usage Guidelines for Application Designers", BCP 145, RFC 5405, November 2008. [RFC5489] Badra, M. and I. Hajjeh, "ECDHE_PSK Cipher Suites for Transport Layer Security (TLS)", RFC 5489, March 2009. [RFC6090] McGrew, D., Igoe, K., and M. Salter, "Fundamental Elliptic Curve Cryptography Algorithms", RFC 6090, February 2011. [RFC6120] Saint-Andre, P., "Extensible Messaging and Presence Protocol (XMPP): Core", RFC 6120, March 2011. [RFC6282] Hui, J. and P. Thubert, "Compression Format for IPv6 Datagrams over IEEE 802.15.4-Based Networks", RFC 6282, September 2011. [RFC6335] Cotton, M., Eggert, L., Touch, J., Westerlund, M., and S. Cheshire, "Internet Assigned Numbers Authority (IANA) Procedures for the Management of the Service Name and Transport Protocol Port Number Registry", BCP 165, RFC 6335, August 2011. [RFC6655] McGrew, D. and D. Bailey, "AES-CCM Cipher Suites for 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. [RFC6960] Santesson, S., Myers, M., Ankney, R., Malpani, A., Galperin, S., and C. Adams, "X.509 Internet Public Key Infrastructure Online Certificate Status Protocol - OCSP", RFC 6960, June 2013. [RFC6961] Pettersen, Y., "The Transport Layer Security (TLS) Multiple Certificate Status Request Extension", RFC 6961, June 2013. [RFC7159] Bray, T., "The JavaScript Object Notation (JSON) Data Interchange Format", RFC 7159, March 2014.
[RFC7228] Bormann, C., Ersue, M., and A. Keranen, "Terminology for Constrained-Node Networks", RFC 7228, May 2014. [RTO-CONSIDER] Allman, M., "Retransmission Timeout Considerations", Work in Progress, May 2012. [W3CXMLSEC] Wenning, R., "Report of the XML Security PAG", W3C XML Security PAG, October 2012, <http://www.w3.org/2011/xmlsec-pag/pagreport.html>.
Appendix A. Examples
This section gives a number of short examples with message flows for GET requests. These examples demonstrate the basic operation, the operation in the presence of retransmissions, and multicast. Figure 16 shows a basic GET request causing a piggybacked response: The client sends a Confirmable GET request for the resource coap://server/temperature to the server with a Message ID of 0x7d34. The request includes one Uri-Path Option (Delta 0 + 11 = 11, Length 11, Value "temperature"); the Token is left empty. This request is a total of 16 bytes long. A 2.05 (Content) response is returned in the Acknowledgement message that acknowledges the Confirmable request, 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. Client Server | | | | +----->| Header: GET (T=CON, Code=0.01, MID=0x7d34) | GET | Uri-Path: "temperature" | | | | |<-----+ Header: 2.05 Content (T=ACK, Code=2.05, MID=0x7d34) | 2.05 | Payload: "22.3 C" | | 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 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | 1 | 0 | 0 | GET=1 | MID=0x7d34 | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | 11 | 11 | "temperature" (11 B) ... +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 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 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | 1 | 2 | 0 | 2.05=69 | MID=0x7d34 | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ |1 1 1 1 1 1 1 1| "22.3 C" (6 B) ... +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ Figure 16: Confirmable Request; Piggybacked Response
Figure 17 shows a similar example, but with the inclusion of an non- empty Token (Value 0x20) in the request and the response, increasing the sizes to 17 and 12 bytes, respectively. Client Server | | | | +----->| Header: GET (T=CON, Code=0.01, MID=0x7d35) | GET | Token: 0x20 | | Uri-Path: "temperature" | | | | |<-----+ Header: 2.05 Content (T=ACK, Code=2.05, MID=0x7d35) | 2.05 | Token: 0x20 | | Payload: "22.3 C" | | 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 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | 1 | 0 | 1 | GET=1 | MID=0x7d35 | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | 0x20 | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | 11 | 11 | "temperature" (11 B) ... +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 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 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | 1 | 2 | 1 | 2.05=69 | MID=0x7d35 | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | 0x20 | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ |1 1 1 1 1 1 1 1| "22.3 C" (6 B) ... +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ Figure 17: Confirmable Request; Piggybacked Response
In Figure 18, the Confirmable GET request is lost. After ACK_TIMEOUT seconds, the client retransmits the request, resulting in a piggybacked response as in the previous example. Client Server | | | | +----X | Header: GET (T=CON, Code=0.01, MID=0x7d36) | GET | Token: 0x31 | | Uri-Path: "temperature" TIMEOUT | | | +----->| Header: GET (T=CON, Code=0.01, MID=0x7d36) | GET | Token: 0x31 | | Uri-Path: "temperature" | | | | |<-----+ Header: 2.05 Content (T=ACK, Code=2.05, MID=0x7d36) | 2.05 | Token: 0x31 | | Payload: "22.3 C" | | Figure 18: Confirmable Request (Retransmitted); Piggybacked Response
In Figure 19, the first Acknowledgement message from the server to the client is lost. After ACK_TIMEOUT seconds, the client retransmits the request. Client Server | | | | +----->| Header: GET (T=CON, Code=0.01, MID=0x7d37) | GET | Token: 0x42 | | Uri-Path: "temperature" | | | | | X----+ Header: 2.05 Content (T=ACK, Code=2.05, MID=0x7d37) | 2.05 | Token: 0x42 | | Payload: "22.3 C" TIMEOUT | | | +----->| Header: GET (T=CON, Code=0.01, MID=0x7d37) | GET | Token: 0x42 | | Uri-Path: "temperature" | | | | |<-----+ Header: 2.05 Content (T=ACK, Code=2.05, MID=0x7d37) | 2.05 | Token: 0x42 | | Payload: "22.3 C" | | Figure 19: Confirmable Request; Piggybacked Response (Retransmitted)
In Figure 20, the server acknowledges the Confirmable request and sends a 2.05 (Content) response separately in a Confirmable message. Note that the Acknowledgement message and the Confirmable response do not necessarily arrive in the same order as they were sent. The client acknowledges the Confirmable response. Client Server | | | | +----->| Header: GET (T=CON, Code=0.01, MID=0x7d38) | GET | Token: 0x53 | | Uri-Path: "temperature" | | | | |<- - -+ Header: (T=ACK, Code=0.00, MID=0x7d38) | | | | |<-----+ Header: 2.05 Content (T=CON, Code=2.05, MID=0xad7b) | 2.05 | Token: 0x53 | | Payload: "22.3 C" | | | | +- - ->| Header: (T=ACK, Code=0.00, MID=0xad7b) | | Figure 20: Confirmable Request; Separate Response
Figure 21 shows an example where the client loses its state (e.g., crashes and is rebooted) right after sending a Confirmable request, so the separate response arriving some time later comes unexpected. In this case, the client rejects the Confirmable response with a Reset message. Note that the unexpected ACK is silently ignored. Client Server | | | | +----->| Header: GET (T=CON, Code=0.01, MID=0x7d39) | GET | Token: 0x64 | | Uri-Path: "temperature" CRASH | | | |<- - -+ Header: (T=ACK, Code=0.00, MID=0x7d39) | | | | |<-----+ Header: 2.05 Content (T=CON, Code=2.05, MID=0xad7c) | 2.05 | Token: 0x64 | | Payload: "22.3 C" | | | | +- - ->| Header: (T=RST, Code=0.00, MID=0xad7c) | | Figure 21: Confirmable Request; Separate Response (Unexpected) Figure 22 shows a basic GET request where the request and the response are Non-confirmable, so both may be lost without notice. Client Server | | | | +----->| Header: GET (T=NON, Code=0.01, MID=0x7d40) | GET | Token: 0x75 | | Uri-Path: "temperature" | | | | |<-----+ Header: 2.05 Content (T=NON, Code=2.05, MID=0xad7d) | 2.05 | Token: 0x75 | | Payload: "22.3 C" | | Figure 22: Non-confirmable Request; Non-confirmable Response
In Figure 23, the client sends a Non-confirmable GET request to a 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 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, therefore it sends a Non-confirmable 4.04 (Not Found) response. Client ff02::1 A B C | | | | | | | | | | +------>| | | | Header: GET (T=NON, Code=0.01, MID=0x7d41) | GET | | | | Token: 0x86 | | | | Uri-Path: "temperature" | | | | | | | | |<------------+ | | Header: 2.05 (T=NON, Code=2.05, MID=0x60b1) | 2.05 | | | Token: 0x86 | | | | Payload: "22.3 C" | | | | | | | | | X------------+ | Header: 2.05 (T=NON, Code=2.05, MID=0x01a0) | 2.05 | | | Token: 0x86 | | | | Payload: "20.9 C" | | | | | | | | |<------------------+ Header: 4.04 (T=NON, Code=4.04, MID=0x952a) | 4.04 | | | Token: 0x86 | | | | Figure 23: Non-confirmable Request (Multicast); Non-confirmable ResponseAppendix B. URI Examples
The following examples demonstrate different sets of Uri options, and the result after constructing an URI from them. In addition to the options, Section 6.5 refers to the destination IP address and port, but not all paths of the algorithm cause the destination IP address and port to be included in the URI. o Input: Destination IP Address = [2001:db8::2:1] Destination UDP Port = 5683
Output:
coap://[2001:db8::2:1]/
o Input:
Destination IP Address = [2001:db8::2:1]
Destination UDP Port = 5683
Uri-Host = "example.net"
Output:
coap://example.net/
o Input:
Destination IP Address = [2001:db8::2:1]
Destination UDP Port = 5683
Uri-Host = "example.net"
Uri-Path = ".well-known"
Uri-Path = "core"
Output:
coap://example.net/.well-known/core
o Input:
Destination IP Address = [2001:db8::2:1]
Destination UDP Port = 5683
Uri-Host = "xn--18j4d.example"
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
E38193E38293E381ABE381A1E381AF hexadecimal
Output:
coap://xn--18j4d.example/
%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
part of the URI.)
o Input:
Destination IP Address = 198.51.100.1
Destination UDP Port = 61616
Uri-Path = ""
Uri-Path = "/"
Uri-Path = ""
Uri-Path = ""
Uri-Query = "//"
Uri-Query = "?&"
Output:
coap://198.51.100.1:61616//%2F//?%2F%2F&?%26
Authors' Addresses
Zach Shelby
ARM
150 Rose Orchard
San Jose, CA 95134
USA
Phone: +1-408-203-9434
EMail: zach.shelby@arm.com
Klaus Hartke
Universitaet Bremen TZI
Postfach 330440
Bremen D-28359
Germany
Phone: +49-421-218-63905
EMail: hartke@tzi.org
Carsten Bormann
Universitaet Bremen TZI
Postfach 330440
Bremen D-28359
Germany
Phone: +49-421-218-63921
EMail: cabo@tzi.org