3. Message Format

CoAP is based on the exchange of compact messages that, by default, are transported over UDP (i.e., each CoAP message occupies the data section of one UDP datagram). CoAP may also be used over Datagram Transport Layer Security (DTLS) (see Section 9.1). It could also be used over other transports such as SMS, TCP, or SCTP, the 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 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.

Following the Token value comes a sequence of zero or more CoAP Options in Type-Length-Value (TLV) format, optionally followed by a payload that takes up the rest of the datagram.

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

+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ |Ver| T | TKL | Code | Message ID | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | Token (if any, TKL bytes) ... +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | Options (if any) ... +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ |1 1 1 1 1 1 1 1| Payload (if any) ... +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+

                     Figure 7: Message Format

The fields in the header are defined as follows:

Version (Ver): 2-bit unsigned integer. Indicates the CoAP version number. Implementations of this specification MUST set this field to 1 (01 binary). Other values are reserved for future versions. Messages with unknown version numbers MUST be silently ignored.

Type (T): 2-bit unsigned integer. Indicates if this message is of type Confirmable (0), Non-confirmable (1), Acknowledgement (2), or Reset (3). The semantics of these message types are defined in Section 4.

Token Length (TKL): 4-bit unsigned integer. Indicates the length of the variable-length Token field (0-8 bytes). Lengths 9-15 are reserved, MUST NOT be sent, and MUST be processed as a message format error.

Code: 8-bit unsigned integer, split into a 3-bit class (most 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 subfield and "dd" are two digits from 00 to 31 for the 5-bit subfield. The class can indicate a request (0), a success response (2), a client error response (4), or a server error response (5). (All other class values are reserved.) As a special case, Code 0.00 indicates an Empty message. In case of a request, the Code field indicates the Request Method; in case of a response, a Response Code. Possible values are maintained in the CoAP Code Registries (Section 12.1). The semantics of requests and responses are defined in Section 5.

Message ID: 16-bit unsigned integer in network byte order. Used to detect message duplication and to match messages of type Acknowledgement/Reset to messages of type Confirmable/Non- confirmable. The rules for generating a Message ID and matching messages are defined in Section 4.

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 correlate requests and responses. The rules for generating a Token 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). An Option can be followed by the end of the message, by another Option, or by the Payload Marker and the payload.

Following the header, token, and options, if any, comes the optional payload. If present and of non-zero length, it is prefixed by a fixed, one-byte Payload Marker (0xFF), which indicates the end of options and the start of the payload. The payload data extends from after the marker to the end of the UDP datagram, i.e., the Payload Length is calculated from the datagram size. The absence of the Payload Marker denotes a zero-length payload. The presence of a marker followed by a zero-length payload MUST be processed as a message format error.

Implementation Note: The byte value 0xFF may also occur within an option length or value, so simple byte-wise scanning for 0xFF is not a viable technique for finding the payload marker. The byte 0xFF has the meaning of a payload marker only where the beginning of another option could occur.

3.1. Option Format

CoAP defines a number of options that can be included in a message. Each option instance in a message specifies the Option Number of the defined CoAP option, the length of the Option Value, and the Option Value itself.

Instead of specifying the Option Number directly, the instances MUST appear in order of their Option Numbers and a delta encoding is used between them: the Option Number for each instance is calculated as the sum of its delta and the Option Number of the preceding instance in the message. For the first instance in a message, a preceding option instance with Option Number zero is assumed. Multiple instances of the same option can be included by using a delta of zero.

Option Numbers are maintained in the "CoAP Option Numbers" registry (Section 12.2). See Section 5.4 for the semantics of the options defined in this document.

 0   1   2   3   4   5   6   7

+---------------+---------------+ | | | | Option Delta | Option Length | 1 byte | | | +---------------+---------------+ \
/ Option Delta / 0-2 bytes \ (extended)
+-------------------------------+ \
/ Option Length / 0-2 bytes \ (extended)
+-------------------------------+ \
/ / \
/ Option Value / 0 or more bytes \
/ / \
+-------------------------------+

                      Figure 8: Option Format

The fields in an option are defined as follows:

Option Delta: 4-bit unsigned integer. A value between 0 and 12 indicates the Option Delta. Three values are reserved for special constructs:

  13:  An 8-bit unsigned integer follows the initial byte and
     indicates the Option Delta minus 13.

  14:  A 16-bit unsigned integer in network byte order follows the
     initial byte and indicates the Option Delta minus 269.

  15:  Reserved for the Payload Marker.  If the field is set to this
     value but the entire byte is not the payload marker, this MUST
     be processed as a message format error.










  The resulting Option Delta is used as the difference between the
  Option Number of this option and that of the previous option (or
  zero for the first option).  In other words, the Option Number is
  calculated by simply summing the Option Delta values of this and
  all previous options before it.

Option Length: 4-bit unsigned integer. A value between 0 and 12 indicates the length of the Option Value, in bytes. Three values are reserved for special constructs:

  13:  An 8-bit unsigned integer precedes the Option Value and
     indicates the Option Length minus 13.

  14:  A 16-bit unsigned integer in network byte order precedes the
     Option Value and indicates the Option Length minus 269.

  15:  Reserved for future use.  If the field is set to this value,
     it MUST be processed as a message format error.

Value: A sequence of exactly Option Length bytes. The length and format of the Option Value depend on the respective option, which MAY define variable-length values. See Section 3.2 for the formats used in this document; options defined in other documents MAY make use of other option value formats.

3.2. Option Value Formats

The options defined in this document make use of the following option value formats.

empty: A zero-length sequence of bytes.

opaque: An opaque sequence of bytes.

uint: A non-negative integer that is represented in network byte order using the number of bytes given by the Option Length field.

         An option definition may specify a range of permissible
         numbers of bytes; if it has a choice, a sender SHOULD
         represent the integer with as few bytes as possible, i.e.,
         without leading zero bytes.  For example, the number 0 is
         represented with an empty option value (a zero-length
         sequence of bytes) and the number 1 by a single byte with
         the numerical value of 1 (bit combination 00000001 in most
         significant bit first notation).  A recipient MUST be
         prepared to process values with leading zero bytes.







         Implementation Note:  The exceptional behavior permitted
            for the sender is intended for highly constrained,
            templated implementations (e.g., hardware
            implementations) that use fixed-size options in the
            templates.

string: A Unicode string that is encoded using UTF-8 [RFC3629] in Net-Unicode form [RFC5198].

         Note that here, and in all other places where UTF-8
         encoding is used in the CoAP protocol, the intention is
         that the encoded strings can be directly used and compared
         as opaque byte strings by CoAP protocol implementations.
         There is no expectation and no need to perform
         normalization within a CoAP implementation (except where
         Unicode strings that are not known to be normalized are
         imported from sources outside the CoAP protocol).  Note
         also that ASCII strings (that do not make use of special
         control characters) are always valid UTF-8 Net-Unicode
         strings.