CoAP over WebSockets
draft-savolainen-core-coap-websockets-01
The information below is for an old version of the document.
| Document | Type |
This is an older version of an Internet-Draft whose latest revision state is "Replaced".
|
|
|---|---|---|---|
| Authors | Teemu Savolainen , Klaus Hartke , Bill Silverajan | ||
| Last updated | 2013-10-18 | ||
| Replaced by | RFC 8323, draft-ietf-core-coap-tcp-tls | ||
| RFC stream | (None) | ||
| Formats | |||
| Additional resources | |||
| Stream | Stream state | (No stream defined) | |
| Consensus boilerplate | Unknown | ||
| RFC Editor Note | (None) | ||
| IESG | IESG state | I-D Exists | |
| Telechat date | (None) | ||
| Responsible AD | (None) | ||
| Send notices to | (None) |
draft-savolainen-core-coap-websockets-01
CoRE Working Group T. Savolainen
Internet-Draft K. Hartke
Intended status: Standards Track Nokia
Expires: April 21, 2014 B. Silverajan
Tampere University of Technology
October 18, 2013
CoAP over WebSockets
draft-savolainen-core-coap-websockets-01
Abstract
This document specifies how to retrieve and update CoAP resources
using CoAP requests and responses over the WebSocket Protocol.
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 April 21, 2014.
Copyright Notice
Copyright (c) 2013 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.
Savolainen, et al. Expires April 21, 2014 [Page 1]
Internet-Draft CoAP over WebSockets October 2013
Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3
1.1. Overview . . . . . . . . . . . . . . . . . . . . . . . . . 4
1.2. Terminology . . . . . . . . . . . . . . . . . . . . . . . 6
2. CoAP over WebSockets . . . . . . . . . . . . . . . . . . . . . 6
2.1. Opening Handshake . . . . . . . . . . . . . . . . . . . . 6
2.2. Message Format . . . . . . . . . . . . . . . . . . . . . . 7
2.3. Message Transmission . . . . . . . . . . . . . . . . . . . 8
2.4. Request Cancellation . . . . . . . . . . . . . . . . . . . 8
2.5. Connection Health . . . . . . . . . . . . . . . . . . . . 9
2.6. Closing the Connection . . . . . . . . . . . . . . . . . . 9
3. CoAP over WebSockets URIs . . . . . . . . . . . . . . . . . . 9
4. Security Considerations . . . . . . . . . . . . . . . . . . . 10
5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 10
5.1. URI Scheme Registrations . . . . . . . . . . . . . . . . . 10
5.2. WebSocket Subprotocol Registration . . . . . . . . . . . . 12
6. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . 12
7. References . . . . . . . . . . . . . . . . . . . . . . . . . . 12
7.1. Normative References . . . . . . . . . . . . . . . . . . . 12
7.2. Informative References . . . . . . . . . . . . . . . . . . 13
Appendix A. Examples . . . . . . . . . . . . . . . . . . . . . . 14
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 17
Savolainen, et al. Expires April 21, 2014 [Page 2]
Internet-Draft CoAP over WebSockets October 2013
1. Introduction
The Constrained Application Protocol (CoAP) [I-D.ietf-core-coap] is a
web protocol designed for communications between resource constrained
nodes. By default, CoAP operates on top of UDP or DTLS, but there is
interest in using CoAP also over other types of transports, such as
SMS [I-D.becker-core-coap-sms-gprs].
An interesting transport for CoAP could be the WebSocket Protocol
[RFC6455]. The WebSocket protocol provides two-way communication
between a client and a server after upgrading an HTTP [RFC2616]
connection, and may be available in an environment that does not
allow transportation of CoAP over UDP. This environment can be, for
example, a corporate network with Internet access only via an HTTP
proxy, or a CoAP application running in a web browser without access
to connectivity means other than HTTP and WebSockets.
This document specifies how to access resources using CoAP requests
and responses over the WebSocket Protocol. This allows connectivity-
limited applications to obtain end-to-end CoAP connectivity either by
communicating CoAP directly with a CoAP server that is accessible
over a WebSocket Connection, or via an intermediary that proxies CoAP
requests and responses between different transports, such as between
WebSockets and UDP.
+---------------------------------------+
| |
| Application |
| |
+---------------------------------------+
| |
| CoAP |
| Requests and Responses |
| |
+ - - - - - - - - - +-------------------+
| | |
| CoAP | CoAP over |
| Messaging | WebSockets |
| | |
+---------+---------+-------------------+
| | | |
| UDP | DTLS | WebSockets |
| | | |
+---------+---------+-------------------+
Figure 1: Abstract layering of CoAP extended by WebSockets
Savolainen, et al. Expires April 21, 2014 [Page 3]
Internet-Draft CoAP over WebSockets October 2013
1.1. Overview
CoAP over WebSockets can be used in a number of configurations. The
most basic configuration is a CoAP client seeking to retrieve or
update a CoAP resource located at a CoAP server that exposes a
WebSocket endpoint (Figure 2). The CoAP client takes the role of the
WebSocket client, establishes a WebSocket Connection and sends a CoAP
request, to which the CoAP server returns a CoAP response. The
WebSocket Connection can be used for any number of requests.
___________ ___________
| | | |
| _|___ requests ___|_ |
| CoAP / \ \ -------------> / / \ CoAP |
| Client \__/__/ <------------- \__\__/ Server |
| | responses | |
|___________| |___________|
WebSocket =============> WebSocket
Client Connection Server
Figure 2: CoAP client (WebSocket client)
accesses CoAP server (WebSocket server)
The challenge in this configuration is to identify resource in the
namespace of the CoAP server: When the WebSocket Protocol is used by
a dedicated client directly (i.e., not from a web page through a web
browser), the client can connect to any WebSocket endpoint. This
means it is necessary that the client is able to determine both the
endpoint (identified by a "ws" or "wss" URI) and the path and query
of the resource within that endpoint from the same URI. When the
WebSocket Protocol is used from a web page, the choices are more
limited [RFC6454], but the challenge persists.
Section 3 proposes a new "coap+ws" URI scheme that identifies both a
WebSocket endpoint and a resource within that endpoint as follows:
coap+ws://example.org/path/to/endpoint?/sensors/temperature?u=degC
\_______________ ______________/ \____________ ___________/
\/ \/
Uri-Path: "sensors"
ws://example.org/path/to/endpoint Uri-Path: "temperature"
Uri-Query: "u=degC"
Figure 3: The "coap+ws" URI Scheme
Savolainen, et al. Expires April 21, 2014 [Page 4]
Internet-Draft CoAP over WebSockets October 2013
Another possible configuration is to set up a CoAP forward proxy at
the WebSocket endpoint. Depending on what transports are available
to the proxy, it could forward the request to a CoAP server with a
CoAP UDP endpoint (Figure 4), an SMS endpoint (a.k.a. mobile phone),
or even another WebSocket endpoint. The client specifies the
resource to be updated or retrieved in the Proxy-URI Option.
___________ ___________ ___________
| | | | | |
| _|___ ___|_ _|___ ___|_ |
| CoAP / \ \ ---> / / \ CoAP / \ \ ---> / / \ CoAP |
| Client \__/__/ <--- \__\__/ Proxy \__/__/ <--- \__\__/ Server |
| | | | | |
|___________| |___________| |___________|
WebSocket ===> WebSocket UDP UDP
Client Server Client Server
Figure 4: CoAP Client (WebSocket client) accesses CoAP Server
(UDP server) via a CoAP proxy (WebSocket server/UDP client)
In a completely different direction, another possible configuration
is a CoAP server running inside a web browser (Figure 5). The web
browser initially connects to a WebSocket endpoint and is then
reachable through the WebSocket server. When no connection exists,
the CoAP server is not reachable; it therefore can be considered a
sleepy endpoint (SEP) [I-D.dijk-core-sleepy-reqs].
___________ ___________ ___________
| | | | | |
| _|___ ___|_ _|___ ___|_ |
| CoAP / \ \ ---> / / \ CoAP / / \ ---> / \ \ CoAP |
| Client \__/__/ <--- \__\__/ Proxy \__\__/ <--- \__/__/ Server |
| | | | | |
|___________| |___________| |___________|
UDP UDP WebSocket <=== WebSocket
Client Server Server Client
Figure 5: CoAP Client (UDP client) accesses sleepy CoAP Server
(WebSocket client) via a CoAP proxy (UDP server/WebSocket server)
The challenge, again, is to identify the resource. Since the CoAP
server is running inside the web browser, this requires not only to
identify the WebSocket client and the path and query, but also the
intermediary, which is the only path to reach the server. The
Savolainen, et al. Expires April 21, 2014 [Page 5]
Internet-Draft CoAP over WebSockets October 2013
problem can be avoided if the intermediary is turned into a reverse
proxy or a mirror server [I-D.vial-core-mirror-server].
Further configurations are possible, including those where a
WebSocket Connection is established through an HTTP proxy.
1.2. Terminology
This document assumes that readers are familiar with the terms and
concepts that are used in [RFC6455] and [I-D.ietf-core-coap].
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
"SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
document are to be interpreted as described in [RFC2119].
2. CoAP over WebSockets
CoAP over WebSockets is intentionally very similar to CoAP as defined
over UDP. Therefore, instead of presenting CoAP over WebSockets as a
new protocol, this document specifies it as a series of deltas from
[I-D.ietf-core-coap].
2.1. Opening Handshake
Before CoAP requests and responses can be exchanged, a WebSocket
Connection needs to be established as defined in Section 4 of
[RFC6455]. The WebSocket client MUST include the subprotocol name
"coap.v1" in the list of protocols, which indicates support for the
protocol defined in this document. Figure 6 shows an example.
GET /path/to/endpoint HTTP/1.1
Host: example.org
Upgrade: websocket
Connection: Upgrade
Sec-WebSocket-Key: dGhlIHNhbXBsZSBub25jZQ==
Sec-WebSocket-Protocol: coap.v1
Sec-WebSocket-Version: 13
HTTP/1.1 101 Switching Protocols
Upgrade: websocket
Connection: Upgrade
Sec-WebSocket-Accept: s3pPLMBiTxaQ9kYGzzhZRbK+xOo=
Sec-WebSocket-Protocol: coap.v1
Figure 6: Example of an Opening Handshake
Savolainen, et al. Expires April 21, 2014 [Page 6]
Internet-Draft CoAP over WebSockets October 2013
2.2. Message Format
Once a WebSocket Connection has been established, CoAP requests and
responses can be exchanged as WebSocket messages. Since CoAP uses a
binary message format, the messages are transmitted in binary data
frames as specified in Sections 5 and 6 of [RFC6455].
The message format is very similar to the format specified for CoAP
over UDP [I-D.ietf-core-coap]. The differences are as follows:
o Since the underlying TCP connection provides retransmissions and
deduplication, there is no need for the reliability mechanisms
provided by CoAP. This means the "T" and "Message ID" fields in
the CoAP message header can be elided.
o Furthermore, since the CoAP version is already negotiated during
the opening handshake, the "Ver" field can be elided as well.
The resulting message format is shown in Figure 7. The four most-
significant bits of the first byte are reserved (R). The remaining
fields and structure are the same as defined in [I-D.ietf-core-coap].
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
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| R | TKL | Code | Token (TKL bytes) ...
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Options (if any) ...
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|1 1 1 1 1 1 1 1| Payload (if any) ...
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
Figure 7: CoAP Message Format over WebSockets
Requests and response messages can be fragmented as specified in
Section 5.4 of [RFC6455], though typically they are sent unfragmented
as they tend to be small and fully buffered before transmission. The
WebSocket protocol does not provide means for multiplexing; if it is
not desirable for a large message to monopolize the connection, a
multiplexing extension such as [I-D.ietf-hybi-websocket-multiplexing]
can be used. Alternatively, requests and responses can be
transferred in a blockwise fashion as defined in
[I-D.ietf-core-block].
Messages MUST NOT be Empty (Code 0.00), i.e., they always carry
either a request or a response.
Savolainen, et al. Expires April 21, 2014 [Page 7]
Internet-Draft CoAP over WebSockets October 2013
2.3. Message Transmission
CoAP requests and responses are exchanged asynchronously over the
WebSocket Connection, i.e., a CoAP client can send multiple requests
without waiting for a response, and the CoAP server can return
responses in any order. Responses MUST be returned over the same
connection as the originating request. Concurrent requests are
differentiated by the Token, which is local to the connection.
The connection is bi-directional, so requests can be sent both by the
entity that established the connection and the remote host.
Retransmission and deduplication of messages is provided by the
WebSocket Protocol. CoAP over WebSockets therefore does not make a
distinction between Confirmable or Non-Confirmable messages, and does
not provide Acknowledgement or Reset messages.
Since the WebSocket Protocol provides ordered delivery of messages,
the mechanism for reordering detection when observing resources
[I-D.ietf-core-observe] is not needed. The value of the Observe
Option in notifications therefore MAY be empty on transmission and
MUST be ignored on reception.
2.4. Request Cancellation
[I-D.ietf-core-coap] defines that a CoAP client that is no longer
interest in receiving a separate response or further notifications
while observing a resource [I-D.ietf-core-observe], can simply
"forget" the pending request. When the server then sends the
response or the next notification, the client will not recognize the
Token in the message and return a Reset message.
Since the "T" field in the CoAP message header is elided when sent
over the WebSocket Protocol, a client cannot send Reset messages.
Instead, a client MAY request the cancellation of a pending request
at any time by sending a CoAP message with the Code field set to 7.31
and the Token field set to the token of the request to be cancelled
[I-D.hartke-core-coap-liveliness].
A server SHOULD NOT send any response or further notification in
reply to the specified request after receiving such a message, and
MUST remove any matching entry from the list of observers of the
target resource of the request.
The server SHOULD abort any ongoing tasks related to the request.
However, if it is not possible to abort the tasks without leaving the
system in an inconsistent state, it MAY continue to execute the tasks
and just suppress the return of the resulting response.
Savolainen, et al. Expires April 21, 2014 [Page 8]
Internet-Draft CoAP over WebSockets October 2013
"LSB(fn)" is not set, then right-shift both "fn" and "sn"
equally until either "LSB(fn)" is set or "fn" is "0".
Laurie, et al. Expires March 4, 2017 [Page 42]
Internet-Draft Certificate Transparency August 2016
Otherwise:
1. Set "sr" to "HASH(0x01 || sr || c)"
Finally, right-shift both "fn" and "sn" one time.
6. After completing iterating through the "consistency_path" array
as described above, verify that the "fr" calculated is equal to
the "first_hash" supplied, that the "sr" calculated is equal to
the "second_hash" supplied and that "sn" is 0.
10.4.3. Verifying root hash given entries
When a client has a complete list of leaf input "entries" from "0" up
to "tree_size - 1" and wishes to verify this list against an STH
"root_hash" returned by the log for the same "tree_size", the
following algorithm may be used:
1. Set "stack" to an empty stack.
2. For each "i" from "0" up to "tree_size - 1":
1. Push "HASH(0x00 || entries[i])" to "stack".
2. Set "merge_count" to the lowest value ("0" included) such
that "LSB(i >> merge_count)" is not set. In other words, set
"merge_count" to the number of consecutive "1"s found
starting at the least significant bit of "i".
3. Repeat "merge_count" times:
1. Pop "right" from "stack".
2. Pop "left" from "stack".
3. Push "HASH(0x01 || left || right)" to "stack".
3. If there is more than one element in the "stack", repeat the same
merge procedure (Step 2.3 above) until only a single element
remains.
4. The remaining element in "stack" is the Merkle Tree hash for the
given "tree_size" and should be compared by equality against the
supplied "root_hash".
Laurie, et al. Expires March 4, 2017 [Page 43]
Internet-Draft Certificate Transparency August 2016
11. Algorithm Agility
It is not possible for a log to change any of its algorithms part way
through its lifetime:
Signature algorithm: SCT signatures must remain valid so signature
algorithms can only be added, not removed.
Hash algorithm: A log would have to support the old and new hash
algorithms to allow backwards-compatibility with clients that are
not aware of a hash algorithm change.
Allowing multiple signature or hash algorithms for a log would
require that all data structures support it and would significantly
complicate client implementation, which is why it is not supported by
this document.
If it should become necessary to deprecate an algorithm used by a
live log, then the log should be frozen as specified in Section 10.1
and a new log should be started. Certificates in the frozen log that
have not yet expired and require new SCTs SHOULD be submitted to the
new log and the SCTs from that log used instead.
12. IANA Considerations
12.1. TLS Extension Type
IANA is asked to allocate an RFC 5246 ExtensionType value for the
"transparency_info" TLS extension. IANA should update this extension
type to point at this document.
12.2. New Entry to the TLS CachedInformationType registry
IANA is asked to add an entry for "ct_compliant(TBD)" to the "TLS
CachedInformationType Values" registry that was defined in [RFC7924].
12.3. Hash Algorithms
IANA is asked to establish a registry of hash algorithm values,
initially consisting of:
+-------+---------------------+
| Index | Hash |
+-------+---------------------+
| 0 | SHA-256 [FIPS180-4] |
| | |
| 255 | reserved |
+-------+---------------------+
Laurie, et al. Expires March 4, 2017 [Page 44]
Internet-Draft Certificate Transparency August 2016
2.5. Connection Health
If a client does not receive any response for some time after sending
a CoAP request, the connection between the WebSocket client and the
WebSocket server may be lost or temporarily disrupted without the
client being aware of it. In this case, the client can send an
unsolicited Pong frame to check the health of the WebSocket
Connection, as specified in Section 5.5.3 of [RFC6455].
2.6. Closing the Connection
The WebSocket Connection is closed as specified in Section 7 of
[RFC6455].
If there are any requests for which the CoAP client has not received
a response yet, each request is cancelled when the connection is
closed. If the CoAP client observes one or more resource over a
WebSocket Connection, the CoAP server (or intermediary in the role of
the CoAP server) MUST remove all associated entries from the list of
observers when the connection is closed.
3. CoAP over WebSockets URIs
For the first configuration discussed in Section 1.1, this document
defines two new URIs schemes that can be used for identifying CoAP
resources and providing a means of locating these resources:
"coap+ws" and "coap+wss".
Similar to the "coap" and "coaps" schemes, the "coap+ws" and "coap+
wss" schemes organize resources hierarchically under a CoAP origin
server. The key difference is that the server is potentially
reachable on a WebSocket endpoint instead of a UDP endpoint. The
endpoint is identified by an embedded "ws" or "wss" URI respectively.
The remainder of the URI identifies a resource which can be operated
on by the methods defined by the CoAP protocol.
The syntax of the "coap+ws" and "coap+wss" URI schemes is specified
below in Augmented Backus-Naur Form (ABNF) [RFC5234]. The
definitions of "host", "port", "path-abempty" and "query" are the
same as in [RFC3986].
coap-ws-URI = "coap+" ws-URI-nq [ "?" path-abempty [ "?" query ] ]
coap-wss-URI = "coap+" wss-URI-nq [ "?" path-abempty [ "?" query ] ]
ws-URI-nq = "ws:" "//" host [ ":" port ] path-abempty
wss-URI-nq = "wss:" "//" host [ ":" port ] path-abempty
Savolainen, et al. Expires April 21, 2014 [Page 9]
Internet-Draft CoAP over WebSockets October 2013
The port component is OPTIONAL; the default for "coap+ws" is port 80,
while the default for "coap+wss" is port 443.
Fragment identifiers are not part of the request URI and thus MUST
NOT be transmitted in a WebSocket handshake or a CoAP request.
4. Security Considerations
CoAP over WebSockets and CoAP over TLS-secured WebSockets do not
introduce additional security issues beyond CoAP and DTLS-secured
CoAP respectively [I-D.ietf-core-coap]. The security considerations
of [RFC6455] apply.
5. IANA Considerations
5.1. URI Scheme Registrations
5.1.1. "coap+ws"
This document requests the registration of the Uniform Resource
Identifier (URI) scheme "coap+ws".
URI scheme name.
coap+ws
Status.
Permanent.
URI scheme syntax.
Defined in Section 3.
URI scheme semantics.
The "coap+ws" URI scheme provides a way to identify resources that
are potentially accessible over the Constrained Application
Protocol (CoAP) using the WebSocket Protocol.
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 the WebSocket protocol.
Savolainen, et al. Expires April 21, 2014 [Page 10]
Internet-Draft CoAP over WebSockets October 2013
Interoperability considerations.
None.
Security considerations.
See Section 4.
Contact.
IETF Chair <chair@ietf.org>
Author/Change controller.
IESG <iesg@ietf.org>
References.
This document.
5.1.2. "coap+wss"
This document requests the registration of the Uniform Resource
Identifier (URI) scheme "coap+wss".
URI scheme name.
coap+wss
Status.
Permanent.
URI scheme syntax.
Defined in Section 3.
URI scheme semantics.
The "coap+wss" URI scheme provides a way to identify resources
that are potentially accessible over the Constrained Application
Protocol (CoAP) using the WebSocket Protocol secured with
Transport Layer Security (TLS).
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 the WebSocket protocol secured with TLS.
Interoperability considerations.
None.
Savolainen, et al. Expires April 21, 2014 [Page 11]
Internet-Draft CoAP over WebSockets October 2013
Security considerations.
See Section 4.
Contact.
IETF Chair <chair@ietf.org>
Author/Change controller.
IESG <iesg@ietf.org>
References.
This document.
5.2. WebSocket Subprotocol Registration
This document requests the registration of the subprotocol name
"coap.v1" in the WebSocket Subprotocol Name Registry.
Subprotocol Identifier.
coap.v1
Subprotocol Common Name.
Constrained Application Protocol (CoAP).
Subprotocol Definition.
This document.
6. Acknowledgements
Thanks to Nadir Javed for helpful comments and discussions that have
shaped the document.
7. References
7.1. Normative References
[I-D.ietf-core-coap]
Shelby, Z., Hartke, K., and C. Bormann, "Constrained
Application Protocol (CoAP)", draft-ietf-core-coap-18
(work in progress), June 2013.
[I-D.ietf-core-observe]
Hartke, K., "Observing Resources in CoAP",
draft-ietf-core-observe-11 (work in progress),
October 2013.
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
Savolainen, et al. Expires April 21, 2014 [Page 12]
Internet-Draft CoAP over WebSockets October 2013
Requirement Levels", BCP 14, RFC 2119, March 1997.
[RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform
Resource Identifier (URI): Generic Syntax", STD 66,
RFC 3986, January 2005.
[RFC6455] Fette, I. and A. Melnikov, "The WebSocket Protocol",
RFC 6455, December 2011.
7.2. Informative References
[I-D.becker-core-coap-sms-gprs]
Becker, M., Li, K., Poetsch, T., and K. Kuladinithi,
"Transport of CoAP over SMS",
draft-becker-core-coap-sms-gprs-04 (work in progress),
August 2013.
[I-D.dijk-core-sleepy-reqs]
Dijk, E., "Sleepy Devices using CoAP - Requirements",
draft-dijk-core-sleepy-reqs-00 (work in progress),
June 2013.
[I-D.hartke-core-coap-liveliness]
Hartke, K., "Liveliness and Cancellation of Separate
Responses and Observations",
draft-hartke-core-coap-liveliness-00 (work in progress),
July 2013.
[I-D.ietf-core-block]
Bormann, C. and Z. Shelby, "Blockwise transfers in CoAP",
draft-ietf-core-block-12 (work in progress), June 2013.
[I-D.ietf-hybi-websocket-multiplexing]
Tamplin, J. and T. Yoshino, "A Multiplexing Extension for
WebSockets", draft-ietf-hybi-websocket-multiplexing-11
(work in progress), July 2013.
[I-D.vial-core-mirror-server]
Vial, M., "CoRE Mirror Server",
draft-vial-core-mirror-server-01 (work in progress),
April 2013.
[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.
[RFC5234] Crocker, D. and P. Overell, "Augmented BNF for Syntax
Specifications: ABNF", STD 68, RFC 5234, January 2008.
Savolainen, et al. Expires April 21, 2014 [Page 13]
Internet-Draft CoAP over WebSockets October 2013
[RFC6454] Barth, A., "The Web Origin Concept", RFC 6454,
December 2011.
Appendix A. Examples
This section gives examples for the first two configurations
discussed in Section 1.1.
An example of the process followed by a CoAP client to retrieve the
representation of a resource identified by a "coap+ws" URI might be
as follows. Figure 8 below illustrates the WebSocket and CoAP
messages exchanged in detail.
1. The CoAP client obtains the URI <coap+ws://example.org/path/to/
endpoint?/sensors/temperature?u=degC>, for example, from a
resource representation that it retrieved previously.
2. It establishes a WebSocket Connection to the endpoint identified
by the embedded "ws" URI, <ws://example.org/path/to/endpoint>.
3. It sends a single-frame, masked, binary message containing a CoAP
request. The request indicates the target resource with the Uri-
Path ("sensors", "temperature") and Uri-Query ("u=degC") options.
4. It waits for server to return a response.
5. The CoAP client uses the connection for further requests, or the
connection is closed.
Savolainen, et al. Expires April 21, 2014 [Page 14]
Internet-Draft CoAP over WebSockets October 2013
CoAP CoAP
Client Server
(WebSocket (WebSocket
Client) Server)
| |
| |
+=========>| GET /path/to/endpoint HTTP/1.1
| | Host: example.org
| | Upgrade: websocket
| | Connection: Upgrade
| | Sec-WebSocket-Key: dGhlIHNhbXBsZSBub25jZQ==
| | Sec-WebSocket-Protocol: coap.v1
| | Sec-WebSocket-Version: 13
| |
|<=========+ HTTP/1.1 101 Switching Protocols
| | Upgrade: websocket
| | Connection: Upgrade
| | Sec-WebSocket-Accept: s3pPLMBiTxaQ9kYGzzhZRbK+xOo=
| | Sec-WebSocket-Protocol: coap.v1
| |
| |
+--------->| Binary frame (opcode=%x2, FIN=1, MASK=1)
| | +-------------------------+
| | | GET |
| | | Token: 0x53 |
| | | Uri-Path: "sensors" |
| | | Uri-Path: "temperature" |
| | | Uri-Query: "u=degC" |
| | +-------------------------+
| |
|<---------+ Binary frame (opcode=%x2, FIN=1, MASK=0)
| | +-------------------------+
| | | 2.05 Content |
| | | Token: 0x53 |
| | | Payload: "22.3 C" |
| | +-------------------------+
: :
: :
| |
+--------->| Close frame (opcode=%x8, FIN=1, MASK=1)
| |
|<---------+ Close frame (opcode=%x8, FIN=1, MASK=0)
| |
Figure 8: A CoAP client retrieves the representation of a resource
identified by a "coap+ws" URI
Savolainen, et al. Expires April 21, 2014 [Page 15]
Internet-Draft CoAP over WebSockets October 2013
Figure 9 shows how a CoAP client uses a CoAP forward proxy with a
WebSocket endpoint to retrieve the representation of the resource
<coap://[2001:DB8::1]/>. The use of the forward proxy and the
address of the WebSocket endpoint are determined by the client from
local configuration rules. The request URI is specified in the
Proxy-Uri Option. Since the request URI uses the "coap" URI scheme,
the proxy fulfills the request by issuing a Confirmable GET request
over UDP to the CoAP server and returning the response to the client.
CoAP CoAP CoAP
Client Proxy Server
(WebSocket (WebSocket (UDP
Client) Server) Endpoint)
| | |
+--------->| | Binary frame (opcode=%x2, FIN=1, MASK=1)
| | | +------------------------------------+
| | | | GET |
| | | | Token: 0x7d |
| | | | Proxy-Uri: "coap://[2001:DB8::1]/" |
| | | +------------------------------------+
| | |
| +--------->| CoAP message (Ver=1, T=Con, MID=0x8f54)
| | | +------------------------------------+
| | | | GET |
| | | | Token: 0x0a15 |
| | | +------------------------------------+
| | |
| |<---------+ CoAP message (Ver=1, T=Ack, MID=0x8f54)
| | | +------------------------------------+
| | | | 2.05 Content |
| | | | Token: 0x0a15 |
| | | | Payload: "ready" |
| | | +------------------------------------+
| | |
|<---------+ | Binary frame (opcode=%x2, FIN=1, MASK=0)
| | | +------------------------------------+
| | | | 2.05 Content |
| | | | Token: 0x7d |
| | | | Payload: "ready" |
| | | +------------------------------------+
| | |
Figure 9: A CoAP client retrieves the representation of a resource
identified by a "coap" URI via a WebSockets-enabled CoAP proxy
Savolainen, et al. Expires April 21, 2014 [Page 16]12.4. Signature Algorithms
IANA is asked to establish a registry of signature algorithm values,
initially consisting of:
+-------+-----------------------------------------------------------+
| Index | Signature Algorithm |
+-------+-----------------------------------------------------------+
| 0 | deterministic ECDSA [RFC6979] using the NIST P-256 curve |
| | (Section D.1.2.3 of the Digital Signature Standard [DSS]) |
| | and HMAC-SHA256. |
| | |
| 1 | RSA signatures (RSASSA-PKCS1-v1_5 with SHA-256, Section |
| | 8.2 of [RFC3447]) using a key of at least 2048 bits. |
+-------+-----------------------------------------------------------+
12.5. SCT Extensions
IANA is asked to establish a registry of SCT extensions, initially
consisting of:
+-------+-----------+
| Type | Extension |
+-------+-----------+
| 65535 | reserved |
+-------+-----------+
TBD: policy for adding to the registry
12.6. STH Extensions
IANA is asked to establish a registry of STH extensions, initially
consisting of:
+-------+-----------+
| Type | Extension |
+-------+-----------+
| 65535 | reserved |
+-------+-----------+
TBD: policy for adding to the registry
12.7. Object Identifiers
This document uses object identifiers (OIDs) to identify Log IDs (see
Section 5.3), the precertificate CMS "eContentType" (see
Section 3.2), and X.509v3 extensions in certificates (see Section 4.2
Laurie, et al. Expires March 4, 2017 [Page 45]
Internet-Draft Certificate Transparency August 2016
and Section 9.1.2) and OCSP responses (see Section 9.1.1). The OIDs
are defined in an arc that was selected due to its short encoding.
12.7.1. Log ID Registry 1
All OIDs in the range from 1.3.101.8192 to 1.3.101.16383 have been
reserved. This is a limited resource of 8,192 OIDs, each of which
has an encoded length of 4 octets.
IANA is requested to establish a registry that will allocate Log IDs
from this range.
TBD: policy for adding to the registry. Perhaps "Expert Review"?
12.7.2. Log ID Registry 2
The 1.3.101.80 arc has been delegated. This is an unlimited
resource, but only the 128 OIDs from 1.3.101.80.0 to 1.3.101.80.127
have an encoded length of only 4 octets.
IANA is requested to establish a registry that will allocate Log IDs
from this arc.
TBD: policy for adding to the registry. Perhaps "Expert Review"?
13. Security Considerations
With CAs, logs, and servers performing the actions described here,
TLS clients can use logs and signed timestamps to reduce the
likelihood that they will accept misissued certificates. If a server
presents a valid signed timestamp for a certificate, then the client
knows that a log has committed to publishing the certificate. From
this, the client knows that monitors acting for the subject of the
certificate have had some time to notice the misissue and take some
action, such as asking a CA to revoke a misissued certificate, or
that the log has misbehaved, which will be discovered when the SCT is
audited. A signed timestamp is not a guarantee that the certificate
is not misissued, since appropriate monitors might not have checked
the logs or the CA might have refused to revoke the certificate.
In addition, if TLS clients will not accept unlogged certificates,
then site owners will have a greater incentive to submit certificates
to logs, possibly with the assistance of their CA, increasing the
overall transparency of the system.
[I-D.ietf-trans-threat-analysis] provides a more detailed threat
analysis of the Certificate Transparency architecture.
Laurie, et al. Expires March 4, 2017 [Page 46]
Internet-Draft Certificate Transparency August 2016
13.1. Misissued Certificates
Misissued certificates that have not been publicly logged, and thus
do not have a valid SCT, are not considered compliant. Misissued
certificates that do have an SCT from a log will appear in that
public log within the Maximum Merge Delay, assuming the log is
operating correctly. Thus, the maximum period of time during which a
misissued certificate can be used without being available for audit
is the MMD.
13.2. Detection of Misissue
The logs do not themselves detect misissued certificates; they rely
instead on interested parties, such as domain owners, to monitor them
and take corrective action when a misissue is detected.
13.3. Misbehaving Logs
A log can misbehave in several ways. Examples include failing to
incorporate a certificate with an SCT in the Merkle Tree within the
MMD, presenting different, conflicting views of the Merkle Tree at
different times and/or to different parties and issuing STHs too
frequently. Such misbehavior is detectable and the
[I-D.ietf-trans-threat-analysis] provides more details on how this
can be done.
Violation of the MMD contract is detected by log clients requesting a
Merkle inclusion proof (Section 6.5) for each observed SCT. These
checks can be asynchronous and need only be done once per each
certificate. In order to protect the clients' privacy, these checks
need not reveal the exact certificate to the log. Instead, clients
can request the proof from a trusted auditor (since anyone can
compute the proofs from the log) or communicate with the log via
proxies.
Violation of the append-only property or the STH issuance rate limit
can be detected by clients comparing their instances of the Signed
Tree Heads. There are various ways this could be done, for example
via gossip (see [I-D.ietf-trans-gossip]) or peer-to-peer
communications or by sending STHs to monitors (who could then
directly check against their own copy of the relevant log). A proof
of misbehavior in such cases would be a series of STHs that were
issued too closely together, proving violation of the STH issuance
rate limit, or an STH with a root hash that does not match the one
calculated from a copy of the log, proving violation of the append-
only property.
Laurie, et al. Expires March 4, 2017 [Page 47]
Internet-Draft Certificate Transparency August 2016
13.4. Deterministic Signatures
Logs are required to use deterministic signatures for the following
reasons:
o Using non-deterministic ECDSA with a predictable source of
randomness means that each signature can potentially expose the
secret material of the signing key.
o Clients that gossip STHs or report back SCTs can be tracked or
traced if a log was to produce multiple STHs or SCTs with the same
timestamp and data but different signatures.
13.5. Multiple SCTs
By offering multiple SCTs, each from a different log, TLS servers
reduce the effectiveness of an attack where a CA and a log collude
(see Section 8.1).
14. Acknowledgements
The authors would like to thank Erwann Abelea, Robin Alden, Andrew
Ayer, Al Cutter, David Drysdale, Francis Dupont, Adam Eijdenberg,
Stephen Farrell, Daniel Kahn Gillmor, Paul Hadfield, Brad Hill, Jeff
Hodges, Paul Hoffman, Jeffrey Hutzelman, Kat Joyce, Stephen Kent, SM,
Alexey Melnikov, Linus Nordberg, Chris Palmer, Trevor Perrin, Pierre
Phaneuf, Melinda Shore, Ryan Sleevi, Martin Smith, Carl Wallace and
Paul Wouters for their valuable contributions.
A big thank you to Symantec for kindly donating the OIDs from the
1.3.101 arc that are used in this document.
15. References
15.1. Normative References
[DSS] National Institute of Standards and Technology, "Digital
Signature Standard (DSS)", FIPS 186-3, June 2009,
<http://csrc.nist.gov/publications/fips/fips186-3/
fips_186-3.pdf>.
[FIPS180-4]
National Institute of Standards and Technology, "Secure
Hash Standard", FIPS 180-4, March 2012,
<http://csrc.nist.gov/publications/fips/fips180-4/
fips-180-4.pdf>.
Laurie, et al. Expires March 4, 2017 [Page 48]
Internet-Draft Certificate Transparency August 2016
[HTML401] Raggett, D., Le Hors, A., and I. Jacobs, "HTML 4.01
Specification", World Wide Web Consortium Recommendation
REC-html401-19991224, December 1999,
<http://www.w3.org/TR/1999/REC-html401-19991224>.
[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>.
[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,
DOI 10.17487/RFC2616, June 1999,
<http://www.rfc-editor.org/info/rfc2616>.
[RFC3447] Jonsson, J. and B. Kaliski, "Public-Key Cryptography
Standards (PKCS) #1: RSA Cryptography Specifications
Version 2.1", RFC 3447, DOI 10.17487/RFC3447, February
2003, <http://www.rfc-editor.org/info/rfc3447>.
[RFC4627] Crockford, D., "The application/json Media Type for
JavaScript Object Notation (JSON)", RFC 4627,
DOI 10.17487/RFC4627, July 2006,
<http://www.rfc-editor.org/info/rfc4627>.
[RFC4648] Josefsson, S., "The Base16, Base32, and Base64 Data
Encodings", RFC 4648, DOI 10.17487/RFC4648, October 2006,
<http://www.rfc-editor.org/info/rfc4648>.
[RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security
(TLS) Protocol Version 1.2", RFC 5246,
DOI 10.17487/RFC5246, August 2008,
<http://www.rfc-editor.org/info/rfc5246>.
[RFC5280] Cooper, D., Santesson, S., Farrell, S., Boeyen, S.,
Housley, R., and W. Polk, &
Internet-Draft CoAP over WebSockets October 2013
Authors' Addresses
Teemu Savolainen
Nokia
Hermiankatu 12 D
Tampere FI-33720
Finland
Email: teemu.savolainen@nokia.com
Klaus Hartke
Nokia
Hermiankatu 12 D
Tampere FI-33720
Finland
Email: klaus.hartke@nokia.com
Bilhanan Silverajan
Tampere University of Technology
Korkeakoulunkatu 10
Tampere FI-33720
Finland
Email: bilhanan.silverajan@tut.fi
Savolainen, et al. Expires April 21, 2014 [Page 17]