CORE C. Bormann, Ed.
Internet-Draft K. Hartke
Intended status: Standards Track Universitaet Bremen TZI
Expires: December 12, 2016 June 10, 2016
CoAP Signaling Messages
draft-bormann-core-coap-sig-00
Abstract
draft-ietf-core-coap-tcp-tls defines how to transport CoAP messages
on reliable transports such as TCP, TLS, or WebSockets.
All these underlying protocols have ways to set up connection
properties and manage the connection. In many cases, these ways
cannot be used very well for managing CoAP's use of the connection.
Signaling messages are a way to signal information that is about the
connection. They form a third basic kind of messages in CoAP, beyond
requests and responses. Message class 7 is used for signaling
messages.
Signaling messages are only relevant for the connection they appear
in. The present draft assumes reliable, sequence-preserving
connections. It is for further study whether signaling messages are
needed or useful for DTLS connections.
Status of This Memo
This Internet-Draft is submitted in full conformance with the
provisions of BCP 78 and BCP 79.
Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF). Note that other groups may also distribute
working documents as Internet-Drafts. The list of current Internet-
Drafts is at http://datatracker.ietf.org/drafts/current/.
Internet-Drafts are draft documents valid for a maximum of six months
and may be updated, replaced, or obsoleted by other documents at any
time. It is inappropriate to use Internet-Drafts as reference
material or to cite them other than as "work in progress."
This Internet-Draft will expire on December 12, 2016.
Bormann & Hartke Expires December 12, 2016 [Page 1]
Internet-Draft CoAP Signaling Messages June 2016
Copyright Notice
Copyright (c) 2016 IETF Trust and the persons identified as the
document authors. All rights reserved.
This document is subject to BCP 78 and the IETF Trust's Legal
Provisions Relating to IETF Documents
(http://trustee.ietf.org/license-info) in effect on the date of
publication of this document. Please review these documents
carefully, as they describe your rights and restrictions with respect
to this document. Code Components extracted from this document must
include Simplified BSD License text as described in Section 4.e of
the Trust Legal Provisions and are provided without warranty as
described in the Simplified BSD License.
Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2
2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 2
3. Signaling messages . . . . . . . . . . . . . . . . . . . . . 3
4. Capability and Settings Messages . . . . . . . . . . . . . . 3
4.1. ServerName Setting Option . . . . . . . . . . . . . . . . 4
4.2. Using the Capability and Settings message for version
negotiation . . . . . . . . . . . . . . . . . . . . . . . 4
5. Ping and Pong Messages . . . . . . . . . . . . . . . . . . . 5
6. Release Messages . . . . . . . . . . . . . . . . . . . . . . 5
7. Abort Messages . . . . . . . . . . . . . . . . . . . . . . . 6
8. Security Considerations . . . . . . . . . . . . . . . . . . . 7
9. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 7
9.1. Message Codes . . . . . . . . . . . . . . . . . . . . . . 7
9.2. Signaling Options . . . . . . . . . . . . . . . . . . . . 8
10. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 8
11. References . . . . . . . . . . . . . . . . . . . . . . . . . 9
11.1. Normative References . . . . . . . . . . . . . . . . . . 9
11.2. Informative References . . . . . . . . . . . . . . . . . 9
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 9
1. Introduction
(Please see abstract for now.)
2. Terminology
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
"SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and
"OPTIONAL" in this document are to be interpreted as described in
[RFC2119].
Bormann & Hartke Expires December 12, 2016 [Page 2]
Internet-Draft CoAP Signaling Messages June 2016
The definitions of [RFC7252] apply.
In this document, the term "byte" is used in its now customary sense
as a synonym for "octet".
Where bit arithmetic is explained, this document uses the notation
familiar from the programming language C, except that the operator
"**" stands for exponentiation.
3. Signaling messages
Signaling messages are structured like any other CoAP message; they
have a code, a token, options, and optionally a payload. The code
for a signaling message comes from the 7.xx space.
Option numbers for signaling messages are specific to the message
code, i.e., they do not share the number space with CoAP options for
request/response messages or with signaling messages using other
codes.
Signaling options can be elective or critical (see Section 5.4.1 of
[RFC7252]); if a signaling message option is critical and not
understood by the receiver, it MUST abort the connection (see
Section 7. (If the option is understood but somehow cannot be
carried out, the option defines how to handle the situation.)
Payloads in signaling messages are diagnostic payloads (see
Section 5.5.2 of [RFC7252]), unless otherwise determined by a
signaling message option.
This specification lays out five kinds of signaling messages, without
necessarily defining an instance of each of the kinds.
For each message, there is an emitter (that sends the message) and a
peer receiving the message.
4. Capability and Settings Messages
Capability and Settings messages are used for two purposes:
o Capability indication options indicate a capability of the emitter
to the peer. Capability options are generally elective options.
o Setting options indicate a setting that will be applied by the
emitter. Setting options are generally mandatory options.
Both capability indication options and setting options are
cumulative, i.e., a capability message without any option is a no-
Bormann & Hartke Expires December 12, 2016 [Page 3]
Internet-Draft CoAP Signaling Messages June 2016
operation (and can be used as such). (An option that is given might
override a previous value for the same option; the option defines how
to handle this, if needed.) Most CSM options are useful mainly as
initial messages in the connection.
Capability and Settings messages carry the code 7.CSM (CSM to be
defined).
+-------+------+-----------+
| Code | Name | Reference |
+-------+------+-----------+
| 7.CSM | CSM | [RFCthis] |
+-------+------+-----------+
A number of options for Capability and Settings messages are defined
in the following subsections.
4.1. ServerName Setting Option
A client can indicate a default value that it wants to set for the
Uri-Host options in the messages it sends to the server:
The ServerName option is defined as follows:
+---------------+------------+-------------+-----------+
| Option Number | Applies to | Option Name | Reference |
+---------------+------------+-------------+-----------+
| TBD1 | 7.CSM | ServerName | [RFCthis] |
+---------------+------------+-------------+-----------+
The ServerName option is a mandatory option (TBD1 is odd) and carries
a "string" value, with the same restrictions as for Uri-Host
(Section 5.10 of RFC 7252: length is between 1 and 255).
For TLS, the initial value for the ServerName option is given by the
SNI value. SECURITY CONSIDERATIONS. For Websockets, the initial
value for the ServerName is given by the HTTP Host header field.
4.2. Using the Capability and Settings message for version negotiation
CoAP is defined in RFC 7252 with a version number of 1. In contrast
to the message layer for UDP and DTLS, the CoAP over TCP message
layer does not send the version number in each single message.
Instead, options for the Capability and Settings message can be used
to perform a version negotiation.
At the time of writing, there is no known reason for supporting
version numbers different from 1. The details of a version
Bormann & Hartke Expires December 12, 2016 [Page 4]
Internet-Draft CoAP Signaling Messages June 2016
negotiation, once it is actually needed, will depend on the specifics
of the new version(s), so the present specification makes no attempt
to specify these details. However, Capability and Settings messages
have been specifically designed with a view to supporting such a
potential future need.
5. Ping and Pong Messages
(NOTE: The present specification assumes that the CoAP over TCP
specification specifies that empty messages can always be sent and
will be ignored. This provides for a keepalive function that appears
to be needed for some applications. Ping and Pong messages are a
bidirectional exchange, a need for which has not yet been clearly
identified.)
(NOT NOW: This specification does not actually define Ping and Pong.
The following text just shows what _could_ be done if it appears
there is a need.)
Ping, pong: A ping message is responded to by a pong message with the
same token. No options are defined for Ping messages in this
specification, but options might be defined later. As with all
signaling messages, the receiver of a ping or pong message MUST
ignore elective options it does not understand.
+--------+------+-----------+
| Code | Name | Reference |
+--------+------+-----------+
| 7.PING | PING | [RFCthis] |
| | | |
| 7.PONG | PONG | [RFCthis] |
+--------+------+-----------+
6. Release Messages
A release message indicates that the emitter does not want to
continue maintaining the connection and opts for an orderly shutdown;
the details are in the options. A diagnostic payload MAY be
included. A release message will normally be replied to by the peer
by closing the TCP/TLS connection. Messages may be in flight when
the emitter decides to send a Release message; the general
expectation is that these will still be processed.
+-----------+---------+-----------+
| Code | Name | Reference |
+-----------+---------+-----------+
| 7.RELEASE | RELEASE | [RFCthis] |
+-----------+---------+-----------+
Bormann & Hartke Expires December 12, 2016 [Page 5]
Internet-Draft CoAP Signaling Messages June 2016
Release messages can indicate one or more reasons using elective
options; the following options are defined:
+---------------+------------+--------------------+-----------+
| Option Number | Applies to | Option Name | Reference |
+---------------+------------+--------------------+-----------+
| TBD2 | 7.RELEASE | BadServerName | [RFCthis] |
| | | | |
| TBD3 | 7.RELEASE | AlternativeAddress | [RFCthis] |
| | | | |
| TBD4 | 7.RELEASE | HoldOff | [RFCthis] |
+---------------+------------+--------------------+-----------+
The BadServerName option indicates that the default as set by the CSM
option ServerName is unlikely to be useful for this server. The
value is empty. (TBD2 is even, i.e., the option is elective.)
The AlternativeAddress option requests the peer to instead open a
connection of the same kind as the present connection to the
alternative transport address given. The value is a string, of the
form "authority" defined in Section 3.2 of RFC 3986. (TBD3 is even,
i.e., the option is elective.) SECURITY CONSIDERATIONS.
The HoldOff option indicates that the server is requesting that the
peer not reconnect to it for the number of seconds given as the
value. The value is a uint. (TBD4 is even, i.e., the option is
elective.) (Do we need a "go away forever"?)
7. Abort Messages
An abort message indicates that the emitter is unable to continue
maintaining the connection and cannot even wait for an orderly
release; the emitter shuts down the connection immediately after the
abort (and may or may not wait for a release or abort message or
connection shutdown in the inverse direction). A diagnostic payload
SHOULD be included in the Abort message. Messages may be in flight
when the emitter decides to send an abort message; the general
expectation is that these will NOT be processed.
+---------+-------+-----------+
| Code | Name | Reference |
+---------+-------+-----------+
| 7.ABORT | ABORT | [RFCthis] |
+---------+-------+-----------+
Abort messages can indicate one or more reasons using elective
options; the following options are defined:
Bormann & Hartke Expires December 12, 2016 [Page 6]
Internet-Draft CoAP Signaling Messages June 2016
+---------------+------------+--------------+-----------+
| Option Number | Applies to | Option Name | Reference |
+---------------+------------+--------------+-----------+
| TBD5 | 7.ABORT | BadCSMOption | [RFCthis] |
+---------------+------------+--------------+-----------+
The BadCSMOption indicates that the emitter is unable to process the
CSM option identified by its option number, e.g. when it is mandatory
and the option number is unknown by the emitter, or when there is
parameter problem with the value of an elective option. The value is
a uint. (TBD5 is even, i.e., the option is elective.) (More
detailed information SHOULD be given as a diagnostic payload.)
One reason for an emitter to generate an abort message is a general
syntax error in the byte stream received; no specific option has been
defined for this, as the details of that syntax error are best left
to a diagnostic payload.
8. Security Considerations
The security considerations of [RFC7252] apply.
o Alternative Address cannot be followed blindly.
o SNI vs. ServerName: The security is for the SNI name.
9. IANA Considerations
9.1. Message Codes
IANA is requested to create a third sub-registry for values of the
Code field in the CoAP header (cf. Section 12.1 of [RFC7252]).
(IANA policy TBD.)
(remember to copy down values from above)
Bormann & Hartke Expires December 12, 2016 [Page 7]
Internet-Draft CoAP Signaling Messages June 2016
+-----------+---------+-----------+
| Code | Name | Reference |
+-----------+---------+-----------+
| 7.CSM | CSM | [RFCthis] |
| | | |
| 7.PING | PING | [RFCthis] |
| | | |
| 7.PONG | PONG | [RFCthis] |
| | | |
| 7.RELEASE | RELEASE | [RFCthis] |
| | | |
| 7.ABORT | ABORT | [RFCthis] |
+-----------+---------+-----------+
9.2. Signaling Options
IANA is requested to create a sub-registry for signaling options
similar to the CoAP Option Numbers Registry (Section 12.2 of
[RFC7252]), with the single change that a fourth column is added to
the sub-registry that is one of the message codes in the message code
subregistry (Section 9.1).
(IANA policy TBD.)
(remember to copy down values from above)
+---------------+------------+--------------------+-----------+
| Option Number | Applies to | Option Name | Reference |
+---------------+------------+--------------------+-----------+
| TBD1 | 7.CSM | ServerName | [RFCthis] |
| | | | |
| TBD2 | 7.RELEASE | BadServerName | [RFCthis] |
| | | | |
| TBD3 | 7.RELEASE | AlternativeAddress | [RFCthis] |
| | | | |
| TBD4 | 7.RELEASE | HoldOff | [RFCthis] |
| | | | |
| TBD5 | 7.ABORT | BadCSMOption | [RFCthis] |
+---------------+------------+--------------------+-----------+
10. Acknowledgements
Significant parts of the present text have been contributed by Hannes
Tschofenig. Matthias Kovatsch reviewed an early version of this
draft.
Bormann & Hartke Expires December 12, 2016 [Page 8]
Internet-Draft CoAP Signaling Messages June 2016
11. References
11.1. Normative References
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
Requirement Levels", BCP 14, RFC 2119,
DOI 10.17487/RFC2119, March 1997,
<http://www.rfc-editor.org/info/rfc2119>.
[RFC7252] Shelby, Z., Hartke, K., and C. Bormann, "The Constrained
Application Protocol (CoAP)", RFC 7252,
DOI 10.17487/RFC7252, June 2014,
<http://www.rfc-editor.org/info/rfc7252>.
11.2. Informative References
[I-D.ietf-core-coap-tcp-tls]
Bormann, C., Lemay, S., Technologies, Z., and H.
Tschofenig, "A TCP and TLS Transport for the Constrained
Application Protocol (CoAP)", draft-ietf-core-coap-tcp-
tls-02 (work in progress), April 2016.
Authors' Addresses
Carsten Bormann (editor)
Universitaet Bremen TZI
Postfach 330440
Bremen D-28359
Germany
Phone: +49-421-218-63921
Email: cabo@tzi.org
Klaus Hartke
Universitaet Bremen TZI
Postfach 330440
Bremen D-28359
Germany
Phone: +49-421-218-63905
Email: hartke@tzi.org
Bormann & Hartke Expires December 12, 2016 [Page 9]