draft-ietf-ace-oauth-authz-00.txt   draft-ietf-ace-oauth-authz-01.txt 
ACE Working Group L. Seitz ACE Working Group L. Seitz
Internet-Draft SICS Internet-Draft SICS
Intended status: Standards Track G. Selander Intended status: Standards Track G. Selander
Expires: June 23, 2016 Ericsson Expires: August 28, 2016 Ericsson
E. Wahlstroem E. Wahlstroem
S. Erdtman S. Erdtman
Nexus Technology Nexus Technology
H. Tschofenig H. Tschofenig
ARM Ltd. ARM Ltd.
December 21, 2015 February 25, 2016
Authorization for the Internet of Things using OAuth 2.0 Authorization for the Internet of Things using OAuth 2.0
draft-ietf-ace-oauth-authz-00 draft-ietf-ace-oauth-authz-01
Abstract Abstract
This memo defines how to use OAuth 2.0 as an authorization framework This memo defines how to use OAuth 2.0 as an authorization framework
with Internet of Things (IoT) deployments, thus bringing a well-known with Internet of Things (IoT) deployments, thus bringing a well-known
and widely used security solution to IoT devices. Where possible and widely used security solution to IoT devices. Where possible
vanilla OAuth 2.0 is used, but where the limitations of IoT devices vanilla OAuth 2.0 is used, but where the limitations of IoT devices
require it, profiles and extensions are provided. require it, profiles and extensions are provided.
Status of This Memo Status of This Memo
skipping to change at page 1, line 40 skipping to change at page 1, line 40
Internet-Drafts are working documents of the Internet Engineering Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF). Note that other groups may also distribute Task Force (IETF). Note that other groups may also distribute
working documents as Internet-Drafts. The list of current Internet- working documents as Internet-Drafts. The list of current Internet-
Drafts is at http://datatracker.ietf.org/drafts/current/. Drafts is at http://datatracker.ietf.org/drafts/current/.
Internet-Drafts are draft documents valid for a maximum of six months Internet-Drafts are draft documents valid for a maximum of six months
and may be updated, replaced, or obsoleted by other documents at any and may be updated, replaced, or obsoleted by other documents at any
time. It is inappropriate to use Internet-Drafts as reference time. It is inappropriate to use Internet-Drafts as reference
material or to cite them other than as "work in progress." material or to cite them other than as "work in progress."
This Internet-Draft will expire on June 23, 2016. This Internet-Draft will expire on August 28, 2016.
Copyright Notice Copyright Notice
Copyright (c) 2015 IETF Trust and the persons identified as the Copyright (c) 2016 IETF Trust and the persons identified as the
document authors. All rights reserved. document authors. All rights reserved.
This document is subject to BCP 78 and the IETF Trust's Legal This document is subject to BCP 78 and the IETF Trust's Legal
Provisions Relating to IETF Documents Provisions Relating to IETF Documents
(http://trustee.ietf.org/license-info) in effect on the date of (http://trustee.ietf.org/license-info) in effect on the date of
publication of this document. Please review these documents publication of this document. Please review these documents
carefully, as they describe your rights and restrictions with respect carefully, as they describe your rights and restrictions with respect
to this document. Code Components extracted from this document must to this document. Code Components extracted from this document must
include Simplified BSD License text as described in Section 4.e of include Simplified BSD License text as described in Section 4.e of
the Trust Legal Provisions and are provided without warranty as the Trust Legal Provisions and are provided without warranty as
described in the Simplified BSD License. described in the Simplified BSD License.
Table of Contents Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3
2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 3 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 4
3. Overview . . . . . . . . . . . . . . . . . . . . . . . . . . 4 3. Overview . . . . . . . . . . . . . . . . . . . . . . . . . . 4
3.1. OAuth 2.0 . . . . . . . . . . . . . . . . . . . . . . . . 5 3.1. OAuth 2.0 . . . . . . . . . . . . . . . . . . . . . . . . 5
3.2. CoAP . . . . . . . . . . . . . . . . . . . . . . . . . . 7 3.2. CoAP . . . . . . . . . . . . . . . . . . . . . . . . . . 7
3.3. Object Security . . . . . . . . . . . . . . . . . . . . . 8 3.3. Object Security . . . . . . . . . . . . . . . . . . . . . 8
4. Protocol Interactions . . . . . . . . . . . . . . . . . . . . 8 4. Protocol Interactions . . . . . . . . . . . . . . . . . . . . 9
5. OAuth 2.0 Profiling . . . . . . . . . . . . . . . . . . . . . 12 5. OAuth 2.0 Profiling . . . . . . . . . . . . . . . . . . . . . 12
5.1. Communication Security Protocol . . . . . . . . . . . . . 12 5.1. Client Information . . . . . . . . . . . . . . . . . . . 12
5.2. Authorization Information Resource at the Resource Server 13 5.2. CoAP Access-Token Option . . . . . . . . . . . . . . . . 15
5.3. Authorization Information Format . . . . . . . . . . . . 13 5.3. Authorization Information Resource at the Resource Server 15
5.4. CBOR Data Formats . . . . . . . . . . . . . . . . . . . . 13 5.3.1. Authorization Information Request . . . . . . . . . . 16
6. Deployment Scenarios . . . . . . . . . . . . . . . . . . . . 13 5.3.2. Authorization Information Response . . . . . . . . . 16
6.1. Client and Resource Server are Offline . . . . . . . . . 14 5.3.2.1. Success Response . . . . . . . . . . . . . . . . 16
6.2. Resource Server Offline . . . . . . . . . . . . . . . . . 17 5.3.2.2. Error Response . . . . . . . . . . . . . . . . . 16
6.3. Token Introspection with an Offline Client . . . . . . . 21 5.4. Authorization Information Format . . . . . . . . . . . . 17
6.4. Always-On Connectivity . . . . . . . . . . . . . . . . . 25 5.5. CBOR Data Formats . . . . . . . . . . . . . . . . . . . . 17
6.5. Token-less Authorization . . . . . . . . . . . . . . . . 26 5.6. Token Expiration . . . . . . . . . . . . . . . . . . . . 17
6.6. Securing Group Communication . . . . . . . . . . . . . . 29 6. Deployment Scenarios . . . . . . . . . . . . . . . . . . . . 18
7. Security Considerations . . . . . . . . . . . . . . . . . . . 30 6.1. Client and Resource Server are Offline . . . . . . . . . 19
8. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 30 6.2. Resource Server Offline . . . . . . . . . . . . . . . . . 22
9. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 30 6.3. Token Introspection with an Offline Client . . . . . . . 26
10. References . . . . . . . . . . . . . . . . . . . . . . . . . 30 6.4. Always-On Connectivity . . . . . . . . . . . . . . . . . 30
10.1. Normative References . . . . . . . . . . . . . . . . . . 30 6.5. Token-less Authorization . . . . . . . . . . . . . . . . 31
10.2. Informative References . . . . . . . . . . . . . . . . . 32 6.6. Securing Group Communication . . . . . . . . . . . . . . 34
Appendix A. Design Justification . . . . . . . . . . . . . . . . 33 7. Security Considerations . . . . . . . . . . . . . . . . . . . 35
Appendix B. Optimizations . . . . . . . . . . . . . . . . . . . 35 8. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 35
Appendix C. CoAP and CBOR profiles for OAuth 2.0 . . . . . . . . 36 8.1. CoAP Option Number Registration . . . . . . . . . . . . . 35
C.1. Profile for Token resource . . . . . . . . . . . . . . . 36 9. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 36
C.1.1. Token Request . . . . . . . . . . . . . . . . . . . . 36 10. References . . . . . . . . . . . . . . . . . . . . . . . . . 36
C.1.2. Token Response . . . . . . . . . . . . . . . . . . . 38 10.1. Normative References . . . . . . . . . . . . . . . . . . 36
C.2. CoAP Profile for OAuth Introspection . . . . . . . . . . 39 10.2. Informative References . . . . . . . . . . . . . . . . . 38
C.2.1. Introspection Request . . . . . . . . . . . . . . . . 39 Appendix A. Design Justification . . . . . . . . . . . . . . . . 40
C.2.2. Introspection Response . . . . . . . . . . . . . . . 40 Appendix B. Roles and Responsibilites -- a Checklist . . . 41
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 42 Appendix C. Optimizations . . . . . . . . . . . . . . . . . . . 44
Appendix D. CoAP and CBOR profiles for OAuth 2.0 . . . . . . . . 45
D.1. Profile for Token resource . . . . . . . . . . . . . . . 45
D.1.1. Token Request . . . . . . . . . . . . . . . . . . . . 46
D.1.2. Token Response . . . . . . . . . . . . . . . . . . . 47
D.2. CoAP Profile for OAuth Introspection . . . . . . . . . . 48
D.2.1. Introspection Request . . . . . . . . . . . . . . . . 48
D.2.2. Introspection Response . . . . . . . . . . . . . . . 49
Appendix E. Document Updates . . . . . . . . . . . . . . . . . . 51
E.1. Version -00 to -01 . . . . . . . . . . . . . . . . . . . 51
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 52
1. Introduction 1. Introduction
Authorization is the process for granting approval to an entity to Authorization is the process for granting approval to an entity to
access a resource [RFC4949]. Managing authorization information for access a resource [RFC4949]. Managing authorization information for
a large number of devices and users is often a complex task where a large number of devices and users is often a complex task where
dedicated servers are used. dedicated servers are used.
Managing authorization of users, services and their devices with the Managing authorization of users, services and their devices with the
help of dedicated authorization servers (AS) is a common task, found help of dedicated authorization servers (AS) is a common task, found
in enterprise networks as well as on the Web. In its simplest form in enterprise networks as well as on the Web. In its simplest form
the authorization task can be described as granting access to a the authorization task can be described as granting access to a
resource hosted on a device, the resource server (RS). This exchange requesting client, for a resource hosted on a device, the resource
is mediated by one or multiple authorization servers. server (RS). This exchange is mediated by one or multiple
authorization servers.
We envision that end consumers and enterprises will want to manage We envision that end consumers and enterprises will want to manage
their Internet of Things (IoT) devices in the same style and this access-control and authorization for their Internet of Things (IoT)
desire will increase with the number of exposed services and devices in the same style and this desire will increase with the
capabilities provided by applications hosted on the IoT devices. The number of exposed services and capabilities provided by applications
IoT devices may be constrained in various ways including processing, hosted on the IoT devices. The IoT devices may be constrained in
memory, code, energy, etc., as defined in [RFC7228], and the various ways including processing, memory, code-size, energy, etc.,
different IoT deployments present a continuous range of device and as defined in [RFC7228], and the different IoT deployments present a
network capabilities. Taking energy consumption as an example: At continuous range of device and network capabilities. Taking energy
one end there are energy-harvesting or battery powered devices which consumption as an example: At one end there are energy-harvesting or
have a tight power budget, on the other end there are devices battery powered devices which have a tight power budget, on the other
connected to a continuous power supply which are not constrained in end there are devices connected to a continuous power supply which
terms of power, and all levels in between. Thus IoT devices are very are not constrained in terms of power, and all levels in between.
different in terms of available processing and message exchange Thus IoT devices are very different in terms of available processing
capabilities. and message exchange capabilities.
This memo describes how to re-use OAuth 2.0 [RFC6749] to extend This memo describes how to re-use OAuth 2.0 [RFC6749] to extend
authorization to Internet of Things devices with different kinds of authorization to Internet of Things devices with different kinds of
constrainedness. At the time of writing, OAuth 2.0 is already used constraints. At the time of writing, OAuth 2.0 is already used with
with certain types of IoT devices and this document will provide certain types of IoT devices and this document will provide
implementers additional guidance for using it in a secure and implementers additional guidance for using it in a secure and
privacy-friendly way. Where possible the basic OAuth 2.0 mechanisms privacy-friendly way. Where possible the basic OAuth 2.0 mechanisms
are used; in some circumstances profiles are defined, for example to are used; in some circumstances profiles are defined, for example to
support lower the over-the-wire message size and smaller code size. support smaller the over-the-wire message size and smaller code size.
2. Terminology 2. Terminology
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
"SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
document are to be interpreted as described in [RFC2119]. document are to be interpreted as described in [RFC2119].
Certain security-related terms such as "authentication", Certain security-related terms such as "authentication",
"authorization", "confidentiality", "(data) integrity", "message "authorization", "confidentiality", "(data) integrity", "message
authentication code", and "verify" are taken from [RFC4949]. authentication code", and "verify" are taken from [RFC4949].
skipping to change at page 6, line 50 skipping to change at page 7, line 10
protection of the token. More information about PoP tokens can be protection of the token. More information about PoP tokens can be
found in [I-D.ietf-oauth-pop-architecture]. found in [I-D.ietf-oauth-pop-architecture].
Scopes and Permissions: Scopes and Permissions:
In OAuth 2.0, the client specifies the type of permissions it is In OAuth 2.0, the client specifies the type of permissions it is
seeking to obtain (via the scope parameter) in the access request. seeking to obtain (via the scope parameter) in the access request.
In turn, the AS may use the "scope" response parameter to inform In turn, the AS may use the "scope" response parameter to inform
the client of the scope of the access token issued. As the client the client of the scope of the access token issued. As the client
could be a constrained device as well, this memo uses CBOR encoded could be a constrained device as well, this memo uses CBOR encoded
messages defined in Appendix C to request scopes and to be messages defined in Appendix D to request scopes and to be
informed what scopes the access token was actually authorized for informed what scopes the access token was actually authorized for
by the AS. by the AS.
The values of the scope parameter are expressed as a list of The values of the scope parameter are expressed as a list of
space- delimited, case-sensitive strings, with a semantic that is space- delimited, case-sensitive strings, with a semantic that is
well-known to the AS and the RS. More details about the concept well-known to the AS and the RS. More details about the concept
of scopes is found under Section 3.3 in [RFC6749]. of scopes is found under Section 3.3 in [RFC6749].
Claims: Claims:
skipping to change at page 7, line 45 skipping to change at page 8, line 5
OAuth 2.0 can be found in [I-D.ietf-oauth-introspection]. OAuth 2.0 can be found in [I-D.ietf-oauth-introspection].
3.2. CoAP 3.2. CoAP
CoAP is an application layer protocol similar to HTTP, but CoAP is an application layer protocol similar to HTTP, but
specifically designed for constrained environments. CoAP typically specifically designed for constrained environments. CoAP typically
uses datagram-oriented transport, such as UDP, where reordering and uses datagram-oriented transport, such as UDP, where reordering and
loss of packets can occur. A security solution need to take the loss of packets can occur. A security solution need to take the
latter aspects into account. latter aspects into account.
Where HTTP uses headers and query-strings to convey additional While HTTP uses headers and query-strings to convey additional
information about a request, CoAP encodes such information in so- information about a request, CoAP encodes such information in so-
called 'options'. called 'options'.
CoAP supports application-layer fragmentation of the CoAP payloads CoAP supports application-layer fragmentation of the CoAP payloads
through blockwise transfers [I-D.ietf-core-block]. However, this through blockwise transfers [I-D.ietf-core-block]. However, this
method does not allow the fragmentation of large CoAP options, method does not allow the fragmentation of large CoAP options,
therefore data encoded in options has to be kept small. therefore data encoded in options has to be kept small.
3.3. Object Security 3.3. Object Security
skipping to change at page 8, line 38 skipping to change at page 8, line 47
For the case of wrapping of application layer payload data For the case of wrapping of application layer payload data
("content") only, such as resource representations or claims of ("content") only, such as resource representations or claims of
access tokens, the same COSE profile can be applied to obtain end- access tokens, the same COSE profile can be applied to obtain end-
to-end confidentiality, integrity and replay protection. to-end confidentiality, integrity and replay protection.
[I-D.selander-ace-object-security] defines this functionality as [I-D.selander-ace-object-security] defines this functionality as
Object Security of Content (OSCON). Object Security of Content (OSCON).
In this case, the message is not bound to the underlying In this case, the message is not bound to the underlying
application layer protocol and can therefore be used with HTTP, application layer protocol and can therefore be used with HTTP,
CoAP, Bluetooth Smart, etc. Whereas OSCOAP integrity protects CoAP, Bluetooth Smart, etc. While OSCOAP integrity protects
specific CoAP message meta-data like request/response code, and specific CoAP message meta-data like request/response code, and
binds a response to a specific request, OSCON protects only binds a response to a specific request, OSCON protects only
payload/content, therefore those security features are lost. The payload/content, therefore those security features are lost. The
advantages are that an OSCON message can be passed across advantages are that an OSCON message can be passed across
different protocols, from request to response, and used to secure different protocols, from request to response, and used to secure
group communications. group communications.
4. Protocol Interactions 4. Protocol Interactions
This framework is based on the same protocol interactions as OAuth This framework is based on the same protocol interactions as OAuth
skipping to change at page 10, line 42 skipping to change at page 10, line 42
Access Token Response (B): Access Token Response (B):
If the AS successfully processes the request from the client, it If the AS successfully processes the request from the client, it
returns an access token. It also includes various parameters, returns an access token. It also includes various parameters,
which we call "Client Information". In addition to the response which we call "Client Information". In addition to the response
parameters defined by OAuth 2.0 and the PoP token extension, we parameters defined by OAuth 2.0 and the PoP token extension, we
consider new kinds of response parameters in Section 5, including consider new kinds of response parameters in Section 5, including
information on which security protocol the client should use with information on which security protocol the client should use with
the resource server(s) that it has just been authorized to access. the resource server(s) that it has just been authorized to access.
Communication security between client and RS may be based on pre- Communication security between client and RS may be based on pre-
provisioned keys/security contexts or dynamically established to provisioned keys/security contexts or dynamically established.
the RS via the PoP token; and to the client via the client The RS authenticates the client via the PoP token; and the client
information as described in Section 5.1. authenticates the RS via the client information as described in
Section 5.1.
Resource Request (C): Resource Request (C):
The client interacts with the RS to request access to the The client interacts with the RS to request access to the
protected resource and provides the access token. The protocol to protected resource and provides the access token. The protocol to
use between the client and the RS is not restricted to CoAP; HTTP, use between the client and the RS is not restricted to CoAP; HTTP,
HTTP/2, Bluetooth Smart etc., are also possible candidates. HTTP/2, Bluetooth Smart etc., are also possible candidates.
Depending on the device limitations and the selected protocol this Depending on the device limitations and the selected protocol this
exchange may be split up into two phases: exchange may be split up into two phases:
(1) the client sends the access token to a newly defined (1) the client sends the access token to a newly defined
authorization endpoint at the RS (see Section 5.2) , which authorization endpoint at the RS (see Section 5.3) , which
conveys authorization information to the RS that may be used conveys authorization information to the RS that may be used by
for subsequent resource requests, and the client for subsequent resource requests, and
(2) the client makes the resource access request, using the (2) the client makes the resource access request, using the
communication security protocol and other client information communication security protocol and other client information
obtained from the AS. obtained from the AS.
The RS verifies that the token is integrity protected by the AS The RS verifies that the token is integrity protected by the AS
and compares the claims contained in the access token with the and compares the claims contained in the access token with the
resource request. If the RS is online, validation can be handed resource request. If the RS is online, validation can be handed
over to the AS using token introspection (see messages D and E) over to the AS using token introspection (see messages D and E)
over HTTP or CoAP, in which case the different parts of step C may over HTTP or CoAP, in which case the different parts of step C may
skipping to change at page 12, line 12 skipping to change at page 12, line 12
The RS uses the dynamically established keys to protect the The RS uses the dynamically established keys to protect the
response, according to used communication security protocol. response, according to used communication security protocol.
5. OAuth 2.0 Profiling 5. OAuth 2.0 Profiling
This section describes profiles of OAuth 2.0 adjusting it to This section describes profiles of OAuth 2.0 adjusting it to
constrained environments for use cases where this is necessary. constrained environments for use cases where this is necessary.
Profiling for JSON Web Tokens (JWT) is provided in Profiling for JSON Web Tokens (JWT) is provided in
[I-D.wahlstroem-ace-cbor-web-token]. [I-D.wahlstroem-ace-cbor-web-token].
5.1. Communication Security Protocol 5.1. Client Information
OAuth 2.0 using bearer tokens, as described in RFC 6749 and in RFC OAuth 2.0 using bearer tokens, as described in [RFC6749] and in
6750, requires TLS for all communication interactions between client, [RFC6750], requires TLS for all communication interactions between
authorization server, and resource server. This is possible in the client, authorization server, and resource server. This is possible
scope where OAuth 2.0 was originally developed, web and mobile in the scope where OAuth 2.0 was originally developed: web and mobile
applications. In these environments resources like computational applications. In these environments resources like computational
power and bandwidth are not scarce and operating systems as well as power and bandwidth are not scarce and operating systems as well as
browser platforms are pre-provisioned with trust anchors that enable browser platforms are pre-provisioned with trust anchors that enable
clients to authenticate servers based on the Web PKI. In a more clients to authenticate servers based on the Web PKI. In a more
heterogeneous IoT environment a wider range of use cases needs to be heterogeneous IoT environment a wider range of use cases needs to be
supported. Therefore, this document suggests extensions to OAuth 2.0 supported. Therefore, this document suggests extensions to OAuth 2.0
that enable the AS to inform the client on how to communicate that enables the AS to inform the client on how to communicate
securely with a RS. securely with a RS and that allows the client to indicate
communication security preferences to the AS.
In the OAuth memo defining the key distribution for proof-of-
possession (PoP) tokens [I-D.ietf-oauth-pop-key-distribution], the
authors suggest to use Uri-query parameters in order to submit the
parameters of the client's token request. To avoid large headers if
the client uses CoAP to communicate with the AS, this memo specifies
the following alternative for submitting client request parameters to
the AS: The client encodes the parameters of it's request as a CBOR
map and submits that map as the payload of the client request. The
Content-format MUST be application/cbor in that case.
The OAuth memo further specifies that the AS SHALL use a JSON
structure in the payload of the response to encode the response
parameters. These parameters include the access token, destined for
the RS and additional information for the client, such as e.g. the
PoP key. We call this information "client information". If the
client is using CoAP to communicate with the AS the AS SHOULD use
CBOR instead of JSON for encoding it's response. The client can
explicitly request this encoding by using the CoAP Accept option.
If the channel between client and AS is not secure, the whole
messages from client to AS and vice-versa MUST be wrapped in JWEs
[RFC7516] or COSE_Encrypted structures [I-D.ietf-cose-msg].
The client may be a constrained device and could therefore be limited
in the communication security protocols it supports. It can
therefore signal to the AS which protocols it can support for
securing their mutual communication. This is done by using the "csp"
parameter defined below in the Token Request message sent to the AS.
Note that The OAuth key distribution specification
[I-D.ietf-oauth-pop-key-distribution] describes in section 6 how the
client can request specific types of keys (symmetric vs. asymmetric)
and proof-of-possession algorithms in the PoP token request.
The client and the RS might not have any prior knowledge about each The client and the RS might not have any prior knowledge about each
other, therefore the AS needs to help them to establish a security other, therefore the AS needs to help them to establish a security
context or at least a key. The AS does this by indicating context or at least a key. The AS does this by indicating
communication security protocol ("csp") and additional key parameters communication security protocol ("csp") and additional key parameters
in the client information. in the client information.
The "csp" parameter specifies how client and RS communication is The "csp" parameter specifies how client and RS communication is
going to be secured based on returned keys. Currently defined values going to be secured based on returned keys. Currently defined values
are "TLS", "DTLS", "OSCOAP" and "OSCON". Depending on the value are "TLS", "DTLS", "ObjectSecurity" with the encodings specified in
different additional parameters become mandatory. Figure 2. Depending on the value different additional parameters
become mandatory.
TLS with certificates may make use of pre-established trust anchors /-----------+--------------+-----------------------\
or configured more tightly with additional client information | Value | Major Type | Key |
parameters, like x5c, x5t or x5t#S256. |-----------+--------------+-----------------------|
| 0 | 0 | TLS |
| 1 | 0 | DTLS |
| 2 | 0 | ObjectSecurity |
\-----------+--------------+-----------------------/
CoAP specifies three security "modes" of DTLS: PreSharedKey, Figure 2: Table of 'csp' parameter value encodings for Client
RawPublicKey and Certificate. In case of PreSharedKey and Information.
RawPublicKey DTLS is based on the use keys distributed in the PoP
token and via the client information. Additional certificate
information may also be added, for example using the parameter x5c,
x5t or x5t#S256.
To use OSCOAP and OSCON requires security context to be established, CoAP specifies three security modes of DTLS: PreSharedKey,
which can be provisioned with PoP token and client information, or RawPublicKey and Certificate. The same modes may be used with TLS.
derived from that information. The client is to infer from the type of key provided, which (D)TLS
mode the RS supports as follows.
5.2. Authorization Information Resource at the Resource Server If PreSharedKey mode is used, the AS MUST provide the client with the
pre-shared key to be used with the RS. This key MUST be the same as
the PoP key (i.e. a symmetric key as in section 4 of
[I-D.ietf-oauth-pop-key-distribution]).
The client MUST use the PoP key as DTLS pre-shared key. The client
MUST furthermore use the "kid" parameter provided as part of the JWK/
COSE_Key as the psk_identity in the DTLS handshake [RFC4279].
If RawPublicKey mode is used, the AS MUST provide the client with the
RS's raw public key using the "rpk" parameter defined in the
following. This parameter MUST contain a JWK or a COSE_Key. The
client MUST provide a raw public key to the AS, and the AS MUST use
this key as PoP key in the token. The token MUST thus use asymmetric
keys for the proof-of-possession.
In order to get the proof-of-possession a RS configured to use this
mode together with PoP tokens MUST require client authentication in
the DTLS handshake. The client MUST use the raw public key bound to
the PoP token for client authentication in DTLS.
TLS or DTLS with certificates MAY make use of pre-established trust
anchors or MAY be configured more tightly with additional client
information parameters, such as x5c, x5t, or x5t#S256. An overview
of these parameters is given below.
For when communication security is based on certificates this
attribute can be used to define the server certificate or CA
certificate. Semantics for this attribute is defined by [RFC7517] or
COSE_Key [I-D.ietf-cose-msg].
For when communication security is based on certificates this
attribute can be used to define the specific server certificate to
expect or the CA certificate. Semantics for this attribute is
defined by JWK/COSE_Key.
To use object security (such as OSCOAP and OSCON) requires security
context to be established, which can be provisioned with PoP token
and client information, or derived from that information. Object
security specifications designed to be used with this protocol MUST
specify the parameters that an AS has to provide to the client in
order to set up the necessary security context.
The RS may support different ways of receiving the access token from
the client (see Section 5.3 and Appendix C). The AS MAY signal the
required method for access token transfer in the client information
by using the "tktr" (token transport) parameter using the values
defined in table Figure 3. If no "tktn" parameter is present, the
client MUST use the default Authorization Information resource as
specified in Section 5.3.
/-----------+--------------+-------------------------\
| Value | Major Type | Key |
|-----------+--------------+-------------------------|
| 0 | 0 | POST to /authz-info |
| 1 | 0 | RFC 4680 |
| 2 | 0 | CoAP option "Ref-Token" |
\-----------+--------------+-------------------------/
Figure 3: Table of 'tktn' parameter value encodings for Client
Information.
Table Figure 4 summarizes the additional parameters defined here for
use by the client or the AS in the PoP token request protocol.
/-----------+--------------+----------------------------------\
| Parameter | Used by | Description |
|-----------+--------------+----------------------------------|
| csp | client or AS | Communication security protocol |
| rpk | AS | RS's raw public key |
| x5c | AS | RS's X.509 certificate chain |
| x5t | AS | RS's SHA-1 cert thumb print |
| x5t#S256 | AS | RS's SHA-256 cert thumb print |
| tktn | AS | Mode of token transfer C -> RS |
\-----------+--------------+----------------------------------/
Figure 4: Table of additional parameters defined for the PoP
protocol.
5.2. CoAP Access-Token Option
OAuth 2.0 access tokens are usually transferred as authorization
header. CoAP has no authorization header equivalence. This document
therefor register the option Access-Token. The Access-Token option
is an alternative for transferring the access token when it is
smaller then 255 bytes. If token is larger the 255 bytes lager
authorization information resources MUST at the RS be user when CoAP.
5.3. Authorization Information Resource at the Resource Server
A consequence of allowing the use of CoAP as web transfer protocol is A consequence of allowing the use of CoAP as web transfer protocol is
that we cannot rely on HTTP specific mechanisms, such as transferring that we cannot rely on HTTP specific mechanisms, such as transferring
information elements in HTTP headers since those are not necessarily information elements in HTTP headers since those are not necessarily
gracefully mapped to CoAP. In case the access token is larger than gracefully mapped to CoAP. In case the access token is larger than
255 bytes it should not be sent as a CoAP option. 255 bytes it should not be sent as a CoAP option.
For conveying authorization information to the RS we therefore For conveying authorization information to the RS a new resource is
introduce a new resource to which the PoP tokens can be sent to introduced to which the PoP tokens can be sent to convey
convey authorization information before the first resource request is authorization information before the first resource request is made
made by the client. This specification calls this resource "/authz- by the client. This specification calls this resource "/authz-info";
info"; the URI may, however, vary in deployments. the URI may, however, vary in deployments.
5.3. Authorization Information Format The RS needs to store the PoP token for when later authorizing
requests from the client. The RS is not mandated to be able to
manage multiple client at once. how the RS manages clients is out of
scope for this specification.
5.3.1. Authorization Information Request
The client makes a POST request to the authorization information
resource by sending its PoP token as request data.
Client MUST send the Content-Format option indicate token format
5.3.2. Authorization Information Response
The RS MUST resonde to a requests to the authorization information
resource. The response MUST match CoAP response codes according to
success or error response section
5.3.2.1. Success Response
Successful requests MUST be answered with 2.01 Created to indicate
that a "session" for the PoP Token has been created. No location
path is required to be returned.
Resource
Client Server
| |
| |
A: +-------->| Header: POST (Code=0.02)
| POST | Uri-Path: "/authz-info"
| | Content-Format: "application/cwt"
| | Payload: <PoP Token>
| |
B: |<--------+ Header: 2.01 Created
| 2.01 |
| |
Figure 5: Authorization Information Resource Success Response
5.3.2.2. Error Response
The resource server MUST user appropriate CoAP response code to
convey the error to the Client. For request that are not valid, e.g.
unknown Content-Format, 4.00 Bad Request MUST be returned. If token
is not valid, e.g. wrong audience, the RS MUST return 4.01
Unauthorized.
Resource
Client Server
| |
| |
A: +-------->| Header: POST (Code=0.02)
| POST | Uri-Path: "/authz-info"
| | Content-Format: "application/cwt"
| | Payload: <PoP Token>
| |
B: |<--------+ Header: 4.01 Unauthorized
| 2.01 |
| |
Figure 6: Authorization Information Resource Error Response
5.4. Authorization Information Format
We introduce a new claim for describing access rights with a specific We introduce a new claim for describing access rights with a specific
format, the "aif" claim. In this memo we propose to use the compact format, the "aif" claim. In this memo we propose to use the compact
format provided by AIF [I-D.bormann-core-ace-aif]. Access rights may format provided by AIF [I-D.bormann-core-ace-aif]. Access rights may
be specified as a list of URIs of resources together with allowed be specified as a list of URIs of resources together with allowed
actions (GET, POST, PUT, PATCH, or DELETE). Other formats may be actions (GET, POST, PUT, PATCH, or DELETE). Other formats may be
mandated by specific applications or requirements (e.g. specifying mandated by specific applications or requirements (e.g. specifying
local conditions on access). local conditions on access).
5.4. CBOR Data Formats 5.5. CBOR Data Formats
The /token resource (called "endpoint" in OAuth 2.0), defined in The /token resource (called "endpoint" in OAuth 2.0), defined in
Section 3.2 of [RFC6749], is used by the client to obtain an access Section 3.2 of [RFC6749], is used by the client to obtain an access
token. Requests sent to the /token resource use the HTTP POST method token. Requests sent to the /token resource use the HTTP POST method
and the payload includes a query component, which is formatted as and the payload includes a query component, which is formatted as
application/x-www-form-urlencoded. CoAP payloads cannot be formatted application/x-www-form-urlencoded. CoAP payloads cannot be formatted
in the same way which requires the /token resource on the AS to be in the same way which requires the /token resource on the AS to be
profiled. Appendix C defines a CBOR-based format for sending profiled. Appendix D defines a CBOR-based format for sending
parameters to the /token resource. parameters to the /token resource.
5.6. Token Expiration
Depending on the capabilities of the RS, there are various ways in
which it can verify the validity of a received access token. We list
the possibilities here including what functionality they require of
the RS.
o The token is a CWT/JWT and includes a 'exp' claim and possibly the
'nbf' claim. The RS verifies these by comparing them to values
from its internal clock as defined in [RFC7519]. In this case the
RS must have a real time chip (RTC) or some other way of reliably
measuring time.
o The RS verifies the validity of the token by performing an
introspection request as specified in Appendix D.2. This requires
the RS to have a reliable network connection to the AS and to be
able to handle two secure sessions in parallel (C to RS and AS to
RS).
o The RS and the AS both store a sequence number linked to their
common security association. The AS increments this number for
each access token it issues and includes it in the access token,
which is a CWT/JWT. The RS keeps track of the most recently
received sequence number, and only accepts tokens as valid, that
are in a certain range around this number. This method does only
require the RS to keep track of the sequence number. The method
does not provide timely expiration, but it makes sure that older
tokens cease to be valid after a specified number of newer ones
got issued. For a constrained RS with no network connectivity and
no means of reliably measuring time, this is the best that can be
achieved.
6. Deployment Scenarios 6. Deployment Scenarios
There is a large variety of IoT deployments, as is indicated in There is a large variety of IoT deployments, as is indicated in
Appendix A, and this section highlights common variants. This Appendix A, and this section highlights common variants. This
section is not normative but illustrates how the framework can be section is not normative but illustrates how the framework can be
applied. applied.
For each of the deployment variants there are a number of possible For each of the deployment variants there are a number of possible
security setups between clients, resource servers and authorization security setups between clients, resource servers and authorization
servers. The main focus in the following subsections is on how servers. The main focus in the following subsections is on how
skipping to change at page 14, line 27 skipping to change at page 19, line 19
the time of the resource request. This access procedure involves the time of the resource request. This access procedure involves
steps A, B, C, and F of Figure 1, but assumes that step A and B have steps A, B, C, and F of Figure 1, but assumes that step A and B have
been carried out during a phase when the client had connectivity to been carried out during a phase when the client had connectivity to
AS. AS.
Since the resource server must be able to verify the access token Since the resource server must be able to verify the access token
locally, self-contained access tokens must be used. locally, self-contained access tokens must be used.
This example shows the interactions between a client, the This example shows the interactions between a client, the
authorization server and a temperature sensor acting as a resource authorization server and a temperature sensor acting as a resource
server. Message exchanges A and B are shown in Figure 2. server. Message exchanges A and B are shown in Figure 7.
A: The client first generates a public-private key pair used for A: The client first generates a public-private key pair used for
communication security with the RS. communication security with the RS.
The client sends the POST request to /token at AS. The request The client sends the POST request to /token at AS. The request
contains the public key of the client and the Audience parameter contains the public key of the client and the Audience parameter
set to "tempSensorInLivingRoom", a value the that the temperature set to "tempSensorInLivingRoom", a value that the temperature
sensor identifies itself with. The AS evaluates the request and sensor identifies itself with. The AS evaluates the request and
authorizes the client to access the resource. authorizes the client to access the resource.
B: The AS responds with a PoP token and client information. The B: The AS responds with a PoP token and client information. The
PoP token contains the public key of the client, while the client PoP token contains the public key of the client, while the client
information contains the public key of the RS. For communication information contains the public key of the RS. For communication
security this example uses DTLS with raw public keys between the security this example uses DTLS with raw public keys between the
client and the RS. client and the RS.
Note: In this example we assume that the client knows what Note: In this example we assume that the client knows what
skipping to change at page 15, line 18 skipping to change at page 20, line 18
| | | |
A: +-------->| Header: POST (Code=0.02) A: +-------->| Header: POST (Code=0.02)
| POST | Uri-Path:"token" | POST | Uri-Path:"token"
| | Payload: <Request-Payload> | | Payload: <Request-Payload>
| | | |
B: |<--------+ Header: 2.05 Content B: |<--------+ Header: 2.05 Content
| | Content-Type: application/cbor | | Content-Type: application/cbor
| 2.05 | Payload: <Response-Payload> | 2.05 | Payload: <Response-Payload>
| | | |
Figure 2: Token Request and Response Using Client Credentials. Figure 7: Token Request and Response Using Client Credentials.
The information contained in the Request-Payload and the Response- The information contained in the Request-Payload and the Response-
Payload is shown in Figure 3. Payload is shown in Figure 8.
Request-Payload : Request-Payload :
{ {
"grant_type" : "client_credentials", "grant_type" : "client_credentials",
"aud" : "tempSensorInLivingRoom", "aud" : "tempSensorInLivingRoom",
"client_id" : "myclient", "client_id" : "myclient",
"client_secret" : "qwerty" "client_secret" : "qwerty"
} }
Response-Payload : Response-Payload :
{ {
"access_token" : b64'SlAV32hkKG ...', "access_token" : b64'SlAV32hkKG ...',
"token_type" : "pop", "token_type" : "pop",
"csp" : "DTLS", "csp" : "DTLS",
"key" : b64'eyJhbGciOiJSU0ExXzUi ...' "key" : b64'eyJhbGciOiJSU0ExXzUi ...'
} }
Figure 3: Request and Response Payload Details. Figure 8: Request and Response Payload Details.
The content of the "key" parameter and the access token are shown in The content of the "key" parameter and the access token are shown in
Figure 4 and Figure 5. Figure 9 and Figure 10.
{ {
"kid" : b64'c29tZSBwdWJsaWMga2V5IGlk', "kid" : b64'c29tZSBwdWJsaWMga2V5IGlk',
"kty" : "EC", "kty" : "EC",
"crv" : "P-256", "crv" : "P-256",
"x" : b64'MKBCTNIcKUSDii11ySs3526iDZ8AiTo7Tu6KPAqv7D4', "x" : b64'MKBCTNIcKUSDii11ySs3526iDZ8AiTo7Tu6KPAqv7D4',
"y" : b64'4Etl6SRW2YiLUrN5vfvVHuhp7x8PxltmWWlbbM4IFyM' "y" : b64'4Etl6SRW2YiLUrN5vfvVHuhp7x8PxltmWWlbbM4IFyM'
} }
Figure 4: Public Key of the RS. Figure 9: Public Key of the RS.
{ {
"aud" : "tempSensorInLivingRoom", "aud" : "tempSensorInLivingRoom",
"iat" : "1360189224", "iat" : "1360189224",
"cnf" : { "cnf" : {
"jwk" : { "jwk" : {
"kid" : b64'1Bg8vub9tLe1gHMzV76e8', "kid" : b64'1Bg8vub9tLe1gHMzV76e8',
"kty" : "EC", "kty" : "EC",
"crv" : "P-256", "crv" : "P-256",
"x" : b64'f83OJ3D2xF1Bg8vub9tLe1gHMzV76e8Tus9uPHvRVEU', "x" : b64'f83OJ3D2xF1Bg8vub9tLe1gHMzV76e8Tus9uPHvRVEU',
"y" : b64'x_FEzRu9m36HLN_tue659LNpXW6pCyStikYjKIWI5a0' "y" : b64'x_FEzRu9m36HLN_tue659LNpXW6pCyStikYjKIWI5a0'
} }
} }
} }
Figure 5: Access Token including Public Key of the Client. Figure 10: Access Token including Public Key of the Client.
Messages C and F are shown in Figure 6 - Figure 7. Messages C and F are shown in Figure 11 - Figure 12.
C: The client then sends the PoP token to the /authz-info resource C: The client then sends the PoP token to the /authz-info resource
at the RS. This is a plain CoAP request, i.e. no DTLS/OSCOAP at the RS. This is a plain CoAP request, i.e. no DTLS/OSCOAP
between client and RS, since the token is integrity protected between client and RS, since the token is integrity protected
between AS and RS. The RS verifies that the PoP token was created between AS and RS. The RS verifies that the PoP token was created
by a known and trusted AS, is valid, and responds to the client. by a known and trusted AS, is valid, and responds to the client.
The RS caches the security context together with authorization The RS caches the security context together with authorization
information about this client contained in the PoP token. information about this client contained in the PoP token.
The client and resource server run the DTLS handshake using the The client and resource server run the DTLS handshake using the
skipping to change at page 16, line 51 skipping to change at page 21, line 51
| | | |
C: +-------->| Header: POST (Code=0.02) C: +-------->| Header: POST (Code=0.02)
| POST | Uri-Path:"authz-info" | POST | Uri-Path:"authz-info"
| | Payload: SlAV32hkKG ... | | Payload: SlAV32hkKG ...
| | (access token) | | (access token)
| | | |
|<--------+ Header: 2.04 Changed |<--------+ Header: 2.04 Changed
| 2.04 | | 2.04 |
| | | |
Figure 6: Access Token provisioning to RS Figure 11: Access Token provisioning to RS
Resource Resource
Client Server Client Server
| | | |
|<=======>| DTLS Connection Establishment |<=======>| DTLS Connection Establishment
| | using Raw Public Keys | | using Raw Public Keys
| | | |
| | | |
+-------->| Header: GET (Code=0.01) +-------->| Header: GET (Code=0.01)
| GET | Uri-Path: "temperature" | GET | Uri-Path: "temperature"
| | | |
| | | |
| | | |
F: |<--------+ Header: 2.05 Content F: |<--------+ Header: 2.05 Content
| 2.05 | Payload: {"t":"22.7"} | 2.05 | Payload: {"t":"22.7"}
| | | |
Figure 7: Resource Request and Response protected by DTLS. Figure 12: Resource Request and Response protected by DTLS.
6.2. Resource Server Offline 6.2. Resource Server Offline
In this deployment scenario we consider the case of an RS that may In this deployment scenario we consider the case of an RS that may
not be able to access the AS at the time it receives an access not be able to access the AS at the time it receives an access
request from a client. We denote this case "RS offline", it involves request from a client. We denote this case "RS offline", it involves
steps A, B, C and F of Figure 1. steps A, B, C and F of Figure 1.
If the RS is offline, then it must be possible for the RS to locally If the RS is offline, then it must be possible for the RS to locally
validate the access token. This requires self-contained tokens to be validate the access token. This requires self-contained tokens to be
used. used.
The validity time for the token should always be chosen as short as The validity time for the token should always be chosen as short as
possible to reduce the possibility that a token contains out-of-date possible to reduce the possibility that a token contains out-of-date
authorization information. Therefore the value for the Expiration authorization information. Therefore the value for the Expiration
Time claim ("exp") should be set only slightly larger than the value Time claim ("exp") should be set only slightly larger than the value
for the Issuing Time claim ("iss"). A constrained RS with means to for the Issuing Time claim ("iss"). A constrained RS with means to
reliably measure time must validate the expiration time of the access reliably measure time must validate the expiration time of the access
token. token.
The following example shows interactions between a client (AC control The following example shows interactions between a client (air-
unit), an offline resource server (temperature sensor) and an conditioning control unit), an offline resource server (temperature
authorization server. The message exchanges A and B are shown in sensor)and an authorization server. The message exchanges A and B
Figure 8. are shown in Figure 13.
A: The client sends the request POST to /token at AS. The request A: The client sends the request POST to /token at AS. The request
contains the Audience parameter set to "tempSensor109797", a value contains the Audience parameter set to "tempSensor109797", a value
that the temperature sensor identifies itself with. The scope the that the temperature sensor identifies itself with. The scope the
client want's the AS to authorize the access token for is "owner", client wants the AS to authorize the access token for is "owner",
which means that the token can be used to both read temperature which means that the token can be used to both read temperature
data and upgrade the firmware on the RS. The AS evaluates the data and upgrade the firmware on the RS. The AS evaluates the
request and authorizes the client to access the resource. request and authorizes the client to access the resource.
B: The AS responds with a PoP token and client information. The B: The AS responds with a PoP token and client information. The
PoP token is wrapped in a COSE message, object secured content PoP token is wrapped in a COSE message, object secured content
from AS to RS. The client information contains a symmetric key. from AS to RS. The client information contains a symmetric key.
In this case communication security between C and RS is OSCOAP In this case communication security between C and RS is OSCOAP
with an authenticated encryption algorithm. The client derives with an authenticated encryption algorithm. The client derives
two unidirectional security contexts to use with the resource two unidirectional security contexts to use with the resource
skipping to change at page 18, line 35 skipping to change at page 23, line 35
A: +-------->| Header: POST (Code=0.02) A: +-------->| Header: POST (Code=0.02)
| POST | Uri-Path: "token" | POST | Uri-Path: "token"
| | Payload: <Request-Payload> | | Payload: <Request-Payload>
| | | |
B: |<--------+ Header: 2.05 Content B: |<--------+ Header: 2.05 Content
| | Content-Type: application/cbor | | Content-Type: application/cbor
| 2.05 | Payload: <Response-Payload> | 2.05 | Payload: <Response-Payload>
| | | |
| | | |
Figure 8: Token Request and Response Figure 13: Token Request and Response
The information contained in the Request-Payload and the Response- The information contained in the Request-Payload and the Response-
Payload is shown in Figure 9. Payload is shown in Figure 14.
Request-Payload: Request-Payload:
{ {
"grant_type" : "client_credentials", "grant_type" : "client_credentials",
"client_id" : "myclient", "client_id" : "myclient",
"client_secret" : "qwerty", "client_secret" : "qwerty",
"aud" : "tempSensor109797", "aud" : "tempSensor109797",
"scope" : "owner" "scope" : "owner"
} }
Response-Payload: Response-Payload:
{ {
"access_token": b64'SlAV32hkKG ...', "access_token": b64'SlAV32hkKG ...',
"token_type" : "pop", "token_type" : "pop",
"csp" : "OSCOAP", "csp" : "OSCOAP",
"key" : b64'eyJhbGciOiJSU0ExXzUi ...' "key" : b64'eyJhbGciOiJSU0ExXzUi ...'
} }
Figure 9: Request and Response Payload for RS offline Figure 14: Request and Response Payload for RS offline
Figure 10 shows examples of the key and the access_token parameters Figure 15 shows examples of the key and the access_token parameters
of the Response-Payload, decoded to CBOR. of the Response-Payload, decoded to CBOR.
access_token: access_token:
{ {
"aud" : "tempSensor109797", "aud" : "tempSensor109797",
"exp" : 1311281970, "exp" : 1311281970,
"iat" : 1311280970, "iat" : 1311280970,
"aif" : [["/tempC", 0], ["/firmware", 2]], "aif" : [["/tempC", 0], ["/firmware", 2]],
"cnf" : { "cnf" : {
"ck":b64'JDLUhTMjU2IiwiY3R5Ijoi ...' "ck":b64'JDLUhTMjU2IiwiY3R5Ijoi ...'
} }
} }
key: key:
{ {
"alg" : "AES_128_CCM_8", "alg" : "AES_128_CCM_8",
"kid" : b64'U29tZSBLZXkgSWQ', "kid" : b64'U29tZSBLZXkgSWQ',
"k" : b64'ZoRSOrFzN_FzUA5XKMYoVHyzff5oRJxl-IXRtztJ6uE' "k" : b64'ZoRSOrFzN_FzUA5XKMYoVHyzff5oRJxl-IXRtztJ6uE'
} }
Figure 10: Access Token and symmetric key from the Response-Payload Figure 15: Access Token and symmetric key from the Response-Payload
Message exchanges C and F are shown in Figure 11 and Figure 12. Message exchanges C and F are shown in Figure 16 and Figure 17.
C: The client then sends the PoP token to the /authz-info resource C: The client then sends the PoP token to the /authz-info resource
in the RS. This is a plain CoAP request, i.e. no DTLS/OSCOAP in the RS. This is a plain CoAP request, i.e. no DTLS/OSCOAP
between client and RS, since the token is integrity protected between client and RS, since the token is integrity protected
between AS and RS. The RS verifies that the PoP token was created between AS and RS. The RS verifies that the PoP token was created
by a known and trusted AS, is valid, and responds to the client. by a known and trusted AS, is valid, and responds to the client.
The RS derives and caches the security contexts together with The RS derives and caches the security contexts together with
authorization information about this client contained in the PoP authorization information about this client contained in the PoP
token. token.
skipping to change at page 20, line 28 skipping to change at page 25, line 28
C: +-------->| Header: POST (Code=0.02) C: +-------->| Header: POST (Code=0.02)
| POST | Uri-Path:"authz-info" | POST | Uri-Path:"authz-info"
| | Payload: <Access Token> | | Payload: <Access Token>
| | | |
| | | |
|<--------+ Header: 2.04 Changed |<--------+ Header: 2.04 Changed
| 2.04 | | 2.04 |
| | | |
| | | |
Figure 11: Access Token provisioning to RS Figure 16: Access Token provisioning to RS
Resource Resource
Client Server Client Server
| | | |
+-------->| Header: GET (Code=0.01) +-------->| Header: GET (Code=0.01)
| GET | Object-Security: | GET | Object-Security:
| | (<seq>,<cid>,[Uri-Path:"tempC"],<tag>) | | (<seq>,<cid>,[Uri-Path:"tempC"],<tag>)
| | | |
F: |<--------+ Header: 2.05 Content F: |<--------+ Header: 2.05 Content
| 2.05 | Object-Security: | 2.05 | Object-Security:
| | (<seq>,<cid>,[22.7 C],<tag>) | | (<seq>,<cid>,[22.7 C],<tag>)
| | | |
Figure 12: Resource request and response protected by OSCOAP Figure 17: Resource request and response protected by OSCOAP
In Figure 12 the GET request contains an Object-Security option and In Figure 17 the GET request contains an Object-Security option and
an indication of the content of the COSE object: a sequence number an indication of the content of the COSE object: a sequence number
("seq", starting from 0), a context identifier ("cid") indicating the ("seq", starting from 0), a context identifier ("cid") indicating the
security context, the ciphertext containing the encrypted CoAP option security context, the ciphertext containing the encrypted CoAP option
identifying the resource, and the Message Authentication Code ("tag") identifying the resource, and the Message Authentication Code ("tag")
which also covers the Code in the CoAP header. which also covers the Code in the CoAP header.
The Object-Security ciphertext in the response [22.7 C] represents an The Object-Security ciphertext in the response [22.7 C] represents an
encrypted temperature reading. (The COSE object is actually carried encrypted temperature reading. (The COSE object is actually carried
in the CoAP payload when possible but that is omitted to simplify in the CoAP payload when possible but that is omitted to simplify
notation.) notation.)
skipping to change at page 21, line 29 skipping to change at page 26, line 29
Since the client is assumed to be offline, at least for a certain Since the client is assumed to be offline, at least for a certain
period of time, a pre-provisioned access token has to be long-lived. period of time, a pre-provisioned access token has to be long-lived.
The resource server may use its online connectivity to validate the The resource server may use its online connectivity to validate the
access token with the authorization server, which is shown in the access token with the authorization server, which is shown in the
example below. example below.
In the example we show the interactions between an offline client In the example we show the interactions between an offline client
(key fob), a resource server (online lock), and an authorization (key fob), a resource server (online lock), and an authorization
server. We assume that there is a provisioning step where the client server. We assume that there is a provisioning step where the client
has access to the AS. This corresponds to message exchanges A and B has access to the AS. This corresponds to message exchanges A and B
which are shown in Figure 13. which are shown in Figure 18.
A: The client sends the request using POST to /token at AS. The A: The client sends the request using POST to /token at AS. The
request contains the Audience parameter set to "lockOfDoor4711", a request contains the Audience parameter set to "lockOfDoor4711", a
value the that the online door in question identifies itself with. value the that the online door in question identifies itself with.
The AS generates an access token as on opaque string, which it can The AS generates an access token as on opaque string, which it can
match to the specific client, a targeted audience and a symmetric match to the specific client, a targeted audience and a symmetric
key security context. key security context.
B: The AS responds with the an access token and client B: The AS responds with the an access token and client
information, the latter containing a symmetric key. Communication information, the latter containing a symmetric key. Communication
skipping to change at page 22, line 18 skipping to change at page 27, line 18
| | | |
A: +-------->| Header: POST (Code=0.02) A: +-------->| Header: POST (Code=0.02)
| POST | Uri-Path:"token" | POST | Uri-Path:"token"
| | Payload: <Request-Payload> | | Payload: <Request-Payload>
| | | |
B: |<--------+ Header: 2.05 Content B: |<--------+ Header: 2.05 Content
| | Content-Type: application/cbor | | Content-Type: application/cbor
| 2.05 | Payload: <Response-Payload> | 2.05 | Payload: <Response-Payload>
| | | |
Figure 13: Token Request and Response using Client Credentials. Figure 18: Token Request and Response using Client Credentials.
Authorization consent from the resource owner can be pre-configured, Authorization consent from the resource owner can be pre-configured,
but it can also be provided via an interactive flow with the resource but it can also be provided via an interactive flow with the resource
owner. An example of this for the key fob case could be that the owner. An example of this for the key fob case could be that the
resource owner has a connected car, he buys a generic key that he resource owner has a connected car, he buys a generic key that he
wants to use with the car. To authorize the key fob he connects it wants to use with the car. To authorize the key fob he connects it
to his computer that then provides the UI for the device. After that to his computer that then provides the UI for the device. After that
OAuth 2.0 implicit flow is used to authorize the key for his car at OAuth 2.0 implicit flow is used to authorize the key for his car at
the the car manufacturers AS. the the car manufacturers AS.
The information contained in the Request-Payload and the Response- The information contained in the Request-Payload and the Response-
Payload is shown in Figure 14. Payload is shown in Figure 19.
Request-Payload: Request-Payload:
{ {
"grant_type" : "token", "grant_type" : "token",
"aud" : "lockOfDoor4711", "aud" : "lockOfDoor4711",
"client_id" : "myclient", "client_id" : "myclient",
} }
Response-Payload: Response-Payload:
{ {
"access_token" : b64'SlAV32hkKG ...' "access_token" : b64'SlAV32hkKG ...'
"token_type" : "pop", "token_type" : "pop",
"csp" : "OSCOAP", "csp" : "OSCOAP",
"key" : b64'eyJhbGciOiJSU0ExXzUi ...' "key" : b64'eyJhbGciOiJSU0ExXzUi ...'
} }
Figure 14: Request and Response Payload for C offline Figure 19: Request and Response Payload for C offline
The access token in this case is just an opaque string referencing The access token in this case is just an opaque string referencing
the authorization information at the AS. the authorization information at the AS.
C: Next, the client POSTs the access token to the /authz-info C: Next, the client POSTs the access token to the /authz-info
resource in the RS. This is a plain CoAP request, i.e. no DTLS/ resource in the RS. This is a plain CoAP request, i.e. no DTLS/
OSCOAP between client and RS. Since the token is an opaque OSCOAP between client and RS. Since the token is an opaque
string, the RS cannot verify it on its own, and thus defers to string, the RS cannot verify it on its own, and thus defers to
respond the client with a status code until step E and only respond the client with a status code until step E and only
acknowledges on the CoAP message layer (indicated with a dashed acknowledges on the CoAP message layer (indicated with a dashed
skipping to change at page 23, line 25 skipping to change at page 28, line 25
| | | |
C: +-------->| Header: POST (T=CON, Code=0.02 C: +-------->| Header: POST (T=CON, Code=0.02
| POST | Token 0x2a12) | POST | Token 0x2a12)
| | Uri-Path:"authz-info" | | Uri-Path:"authz-info"
| | Payload: SlAV32hkKG ... | | Payload: SlAV32hkKG ...
| | (access token) | | (access token)
| | | |
|<- - - - + Header: T=ACK |<- - - - + Header: T=ACK
| | | |
Figure 15: Access Token provisioning to RS Figure 20: Access Token provisioning to RS
D: The RS forwards the token to the /introspect resource on the D: The RS forwards the token to the /introspect resource on the
AS. Introspection assumes a secure connection between the AS and AS. Introspection assumes a secure connection between the AS and
the RS, e.g. using DTLS or OSCOAP, which is not detailed in this the RS, e.g. using DTLS or OSCOAP, which is not detailed in this
example. example.
E: The AS provides the introspection response containing claims E: The AS provides the introspection response containing claims
about the token. This includes the confirmation key (cnf) claim about the token. This includes the confirmation key (cnf) claim
that allows the RS to verify the client's proof of possession in that allows the RS to verify the client's proof of possession in
step F. step F.
skipping to change at page 24, line 17 skipping to change at page 29, line 17
| | | |
D: +--------->| Header: POST (Code=0.02) D: +--------->| Header: POST (Code=0.02)
| POST | Uri-Path: "introspect" | POST | Uri-Path: "introspect"
| | Payload: <Request-Payload> | | Payload: <Request-Payload>
| | | |
E: |<---------+ Header: 2.05 Content E: |<---------+ Header: 2.05 Content
| 2.05 | Content-Type: application/cbor) | 2.05 | Content-Type: application/cbor)
| | Payload: <Response-Payload> | | Payload: <Response-Payload>
| | | |
Figure 16: Token Introspection for C offline Figure 21: Token Introspection for C offline
The information contained in the Request-Payload and the Response- The information contained in the Request-Payload and the Response-
Payload is shown in Figure 17. Payload is shown in Figure 22.
Request-Payload: Request-Payload:
{ {
"token" : b64'SlAV32hkKG...', "token" : b64'SlAV32hkKG...',
"client_id" : "myRS", "client_id" : "myRS",
"client_secret" : "ytrewq" "client_secret" : "ytrewq"
} }
Response-Payload: Response-Payload:
{ {
"active" : true, "active" : true,
"aud" : "lockOfDoor4711", "aud" : "lockOfDoor4711",
"scope" : "open, close", "scope" : "open, close",
"iat" : 1311280970, "iat" : 1311280970,
"cnf" : { "cnf" : {
"ck" : b64'JDLUhTMjU2IiwiY3R5Ijoi ...' "ck" : b64'JDLUhTMjU2IiwiY3R5Ijoi ...'
} }
} }
Figure 17: Request and Response Payload for Introspection Figure 22: Request and Response Payload for Introspection
The client sends the CoAP requests PUT 1 (= "close the lock") to The client sends the CoAP requests PUT 1 (= "close the lock") to
/lock on RS using OSCOAP with a security context derived from the /lock on RS using OSCOAP with a security context derived from the
key supplied in step B. The RS verifies the request with the key key supplied in step B. The RS verifies the request with the key
supplied in step E and that it is authorized by the token supplied supplied in step E and that it is authorized by the token supplied
in step C. in step C.
F: The RS responds with a protected status code using OSCOAP. The F: The RS responds with a protected status code using OSCOAP. The
client verifies the response. client verifies the response.
skipping to change at page 25, line 17 skipping to change at page 30, line 17
| | | |
+-------->| Header: PUT (Code=0.03) +-------->| Header: PUT (Code=0.03)
| PUT | Object-Security: | PUT | Object-Security:
| | (<seq>,<cid>,[Uri-Path:"lock", 1],<tag>) | | (<seq>,<cid>,[Uri-Path:"lock", 1],<tag>)
| | | |
F: |<--------+ Header: 2.04 Changed F: |<--------+ Header: 2.04 Changed
| 2.04 | Object-Security: | 2.04 | Object-Security:
| | (<seq>,<cid>,,<tag>) | | (<seq>,<cid>,,<tag>)
| | | |
Figure 18: Resource request and response protected by OSCOAP Figure 23: Resource request and response protected by OSCOAP
The Object-Security ciphertext [...] of the PUT request contains CoAP The Object-Security ciphertext [...] of the PUT request contains CoAP
options that are encrypted, as well as the payload value '1' which is options that are encrypted, as well as the payload value '1' which is
the value of PUT to the door lock. the value of PUT to the door lock.
In this example there is no ciphertext of the PUT response, but "tag" In this example there is no ciphertext of the PUT response, but "tag"
contains a MAC which covers the request sequence number and context contains a MAC which covers the request sequence number and context
identifier as well as the Code which allows the Client to verify that identifier as well as the Code which allows the Client to verify that
this actuator command was well received (door is locked). this actuator command was well received (door is locked).
skipping to change at page 26, line 38 skipping to change at page 31, line 38
the protected resource. the protected resource.
In case 2., the RS does not need to receive any message from the In case 2., the RS does not need to receive any message from the
client, and therefore enables offloading recurring resource request client, and therefore enables offloading recurring resource request
and response processing to a third party, such as a Message Broker and response processing to a third party, such as a Message Broker
(MB) in a publish-subscribe setting. (MB) in a publish-subscribe setting.
This scenario involves steps A, B, C and F of Figure 1 and four This scenario involves steps A, B, C and F of Figure 1 and four
parties: a client (subscriber), an offline RS (publisher), a trusted parties: a client (subscriber), an offline RS (publisher), a trusted
AS, and a MB, not necessarily trusted with access to the plain text AS, and a MB, not necessarily trusted with access to the plain text
publications. Message exchange A, B is shown in Figure 19. publications. Message exchange A, B is shown in Figure 24.
A: The client sends the request POST to /token at AS. The request A: The client sends the request POST to /token at AS. The request
contains the Audience parameter set to "birchPollenSensor301", a contains the Audience parameter set to "birchPollenSensor301", a
value that characterizes a certain pollen sensor resource. The AS value that characterizes a certain pollen sensor resource. The AS
evaluates the request and authorizes the client to access the evaluates the request and authorizes the client to access the
resource. resource.
B: The AS responds with an empty token and client information with B: The AS responds with an empty token and client information with
a security context to be used by the client. The empty token a security context to be used by the client. The empty token
signifies that authorization is performed by means of signifies that authorization is performed by means of
skipping to change at page 27, line 21 skipping to change at page 32, line 21
A: +-------->| Header: POST (Code=0.02) A: +-------->| Header: POST (Code=0.02)
| POST | Uri-Path:"token" | POST | Uri-Path:"token"
| | Payload: <Request-Payload> | | Payload: <Request-Payload>
| | | |
B: |<--------+ Header: 2.05 Content B: |<--------+ Header: 2.05 Content
| | Content-Type: application/cbor | | Content-Type: application/cbor
| 2.05 | Payload: <Response-Payload> | 2.05 | Payload: <Response-Payload>
| | | |
| | | |
Figure 19: Token Request and Response Figure 24: Token Request and Response
The information contained in the Request-Payload and the Response- The information contained in the Request-Payload and the Response-
Payload is shown in Figure 20. Payload is shown in Figure 25.
Request-Payload : Request-Payload :
{ {
"grant_type" : "client_credentials", "grant_type" : "client_credentials",
"aud" : "birchPollenSensor301", "aud" : "birchPollenSensor301",
"client_id" : "myclient", "client_id" : "myclient",
"client_secret" : "qwerty" "client_secret" : "qwerty"
} }
Response-Payload : Response-Payload :
{ {
"access_token" : NULL, "access_token" : NULL,
"token_type" : "none", "token_type" : "none",
"csp" : "OSCON", "csp" : "OSCON",
"key" : b64'eyJhbGciOiJSU0ExXzUi ...' "key" : b64'eyJhbGciOiJSU0ExXzUi ...'
} }
Figure 20: Request and Response Payload for RS severely constrained Figure 25: Request and Response Payload for RS severely constrained
The content of the "key" parameter is shown in Figure 21. The content of the "key" parameter is shown in Figure 26.
key : key :
{ {
"alg" : "AES_128_CTR_ECDSA", "alg" : "AES_128_CTR_ECDSA",
"kid" : b64'c29tZSBvdGhlciBrZXkgaWQ'; "kid" : b64'c29tZSBvdGhlciBrZXkgaWQ';
"k" : b64'ZoRSOrFzN_FzUA5XKMYoVHyzff5oRJxl-IXRtztJ6uE', "k" : b64'ZoRSOrFzN_FzUA5XKMYoVHyzff5oRJxl-IXRtztJ6uE',
"crv" : "P-256", "crv" : "P-256",
"x" : b64'MKBCTNIcKUSDii11ySs3526iDZ8AiTo7Tu6KPAqv7D4', "x" : b64'MKBCTNIcKUSDii11ySs3526iDZ8AiTo7Tu6KPAqv7D4',
"y" : b64'4Etl6SRW2YiLUrN5vfvVHuhp7x8PxltmWWlbbM4IFyM' "y" : b64'4Etl6SRW2YiLUrN5vfvVHuhp7x8PxltmWWlbbM4IFyM'
} }
Figure 21: The 'key' Parameter Figure 26: The 'key' Parameter
The RS, which sleeps most of the time, occasionally wakes up, The RS, which sleeps most of the time, occasionally wakes up,
measures the number birch pollens per cubic meters, publishes the measures the number birch pollens per cubic meters, publishes the
measurements to the MB, and then returns to sleep. See Figure 22. measurements to the MB, and then returns to sleep. See Figure 27.
In this case the birch pollen count stopped at 270, which is In this case the birch pollen count stopped at 270, which is
encrypted with the symmetric key and signed with the private key of encrypted with the symmetric key and signed with the private key of
the RS. The MB verifies that the message originates from RS using the RS. The MB verifies that the message originates from RS using
the public key of RS, that it is not a replay of an old measurement the public key of RS, that it is not a replay of an old measurement
using the sequence number of the OSCON COSE profile, and caches the using the sequence number of the OSCON COSE profile, and caches the
object secured content. The MB does not have the secret key so is object secured content. The MB does not have the secret key so is
unable to read the plain text measurement. unable to read the plain text measurement.
Message exchanges C and F are shown in Figure 22. Message exchanges C and F are shown in Figure 27.
C: Since there is no access token, the client does not address the C: Since there is no access token, the client does not address the
/authz-info resource in the RS. The client sends the CoAP request /authz-info resource in the RS. The client sends the CoAP request
GET to /birchPollen on MB which is a plain CoAP request. GET to /birchPollen on MB which is a plain CoAP request.
F: The MB responds with the cached object secured content. F: The MB responds with the cached object secured content.
Message Resource Message Resource
Client Broker Server Client Broker Server
| | | | | |
skipping to change at page 29, line 24 skipping to change at page 34, line 24
| | | |
| | | |
C: +-------->| Header: GET (Code=0.01) C: +-------->| Header: GET (Code=0.01)
| GET | Uri-Path: "birchPollen" | GET | Uri-Path: "birchPollen"
| | | |
| | | |
F: |<--------+ Header: 2.05 Content F: |<--------+ Header: 2.05 Content
| 2.05 | Payload: (<seq>,<cid>,["270"],<tag>) | 2.05 | Payload: (<seq>,<cid>,["270"],<tag>)
| | | |
Figure 22: Sensor measurement protected by COSE Figure 27: Sensor measurement protected by COSE
The payload is a COSE message consisting of sequence number 'seq' The payload is a COSE message consisting of sequence number 'seq'
stepped by the RS for each publication, the context identifier 'cid' stepped by the RS for each publication, the context identifier 'cid'
in this case coinciding with the key identifier 'kid' of Figure 21, in this case coinciding with the key identifier 'kid' of Figure 26,
the encrypted measurement and the signature by the RS. the encrypted measurement and the signature by the RS.
Note that the same COSE message format may be used as in OSCOAP but Note that the same COSE message format may be used as in OSCOAP but
that only CoAP payload is protected in this case. that only CoAP payload is protected in this case.
The authorization step is implicit, so while any client could request The authorization step is implicit, so while any client could request
access the COSE object, only authorized clients have access to the access the COSE object, only authorized clients have access to the
symmetric key needed to decrypt the content. symmetric key needed to decrypt the content.
Note that in this case the order of the message exchanges A,B and C,F Note that in this case the order of the message exchanges A,B and C,F
skipping to change at page 30, line 33 skipping to change at page 35, line 33
Furthermore [RFC6819] provides additional security considerations for Furthermore [RFC6819] provides additional security considerations for
OAuth which apply to IoT deployments as well. Finally OAuth which apply to IoT deployments as well. Finally
[I-D.ietf-oauth-pop-architecture] discusses security and privacy [I-D.ietf-oauth-pop-architecture] discusses security and privacy
threats as well as mitigation measures for Proof-of-Possession threats as well as mitigation measures for Proof-of-Possession
tokens. tokens.
8. IANA Considerations 8. IANA Considerations
TBD TBD
FIXME: Add registry over 'csp' values from Figure 2
FIXME: Add registry of 'rpk' parameter from section 5.1
FIXME: Add registry of 'tktn' values from Figure 3
8.1. CoAP Option Number Registration
This section registers the "Access-Token" CoAP Option Number
[RFC2046] in "CoRE Parameters" sub-registry "CoAP Option Numbers" in
the manner described in [RFC7252].
Name
Access-Token
Number
TBD
Reference
[draft-ietf-ace-oauth-authz]
Meaning in Request
Contains an Access Token according to [draft-ietf-ace-oauth-authz]
containing access permissions of the client.
Meaning in Response
Not used in response
Safe-to-Forward
TBD
Format
Based on the observer the format is perseved differently. Opaque
data to the client and CWT or reference token to the RS.
Length
Less then 255 bytes
9. Acknowledgments 9. Acknowledgments
We would like to thank Eve Maler for her contributions to the use of We would like to thank Eve Maler for her contributions to the use of
OAuth 2.0 and UMA in IoT scenarios, Robert Taylor for his discussion OAuth 2.0 and UMA in IoT scenarios, Robert Taylor for his discussion
input, and Malisa Vucinic for his input on the ACRE proposal input, and Malisa Vucinic for his input on the ACRE proposal
[I-D.seitz-ace-core-authz] which was one source of inspiration for [I-D.seitz-ace-core-authz] which was one source of inspiration for
this work. Finally, we would like to thank the ACE working group in this work. Finally, we would like to thank the ACE working group in
general for their feedback. general for their feedback.
10. References 10. References
10.1. Normative References 10.1. Normative References
[I-D.bormann-core-ace-aif] [I-D.bormann-core-ace-aif]
Bormann, C., "An Authorization Information Format (AIF) Bormann, C., "An Authorization Information Format (AIF)
for ACE", draft-bormann-core-ace-aif-03 (work in for ACE", draft-bormann-core-ace-aif-03 (work in
progress), July 2015. progress), July 2015.
[I-D.ietf-cose-msg] [I-D.ietf-cose-msg]
Schaad, J., "CBOR Encoded Message Syntax", draft-ietf- Schaad, J., "CBOR Encoded Message Syntax", draft-ietf-
cose-msg-09 (work in progress), December 2015. cose-msg-10 (work in progress), February 2016.
[I-D.ietf-oauth-introspection] [I-D.ietf-oauth-introspection]
Richer, J., "OAuth 2.0 Token Introspection", draft-ietf- Richer, J., "OAuth 2.0 Token Introspection", draft-ietf-
oauth-introspection-11 (work in progress), July 2015. oauth-introspection-11 (work in progress), July 2015.
[I-D.ietf-oauth-pop-architecture] [I-D.ietf-oauth-pop-architecture]
Hunt, P., Richer, J., Mills, W., Mishra, P., and H. Hunt, P., Richer, J., Mills, W., Mishra, P., and H.
Tschofenig, "OAuth 2.0 Proof-of-Possession (PoP) Security Tschofenig, "OAuth 2.0 Proof-of-Possession (PoP) Security
Architecture", draft-ietf-oauth-pop-architecture-07 (work Architecture", draft-ietf-oauth-pop-architecture-07 (work
in progress), December 2015. in progress), December 2015.
skipping to change at page 31, line 46 skipping to change at page 37, line 42
Wahlstroem, E., "OAuth 2.0 Introspection over the Wahlstroem, E., "OAuth 2.0 Introspection over the
Constrained Application Protocol (CoAP)", draft- Constrained Application Protocol (CoAP)", draft-
wahlstroem-ace-oauth-introspection-01 (work in progress), wahlstroem-ace-oauth-introspection-01 (work in progress),
March 2015. March 2015.
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
Requirement Levels", BCP 14, RFC 2119, Requirement Levels", BCP 14, RFC 2119,
DOI 10.17487/RFC2119, March 1997, DOI 10.17487/RFC2119, March 1997,
<http://www.rfc-editor.org/info/rfc2119>. <http://www.rfc-editor.org/info/rfc2119>.
[RFC4279] Eronen, P., Ed. and H. Tschofenig, Ed., "Pre-Shared Key
Ciphersuites for Transport Layer Security (TLS)",
RFC 4279, DOI 10.17487/RFC4279, December 2005,
<http://www.rfc-editor.org/info/rfc4279>.
[RFC6347] Rescorla, E. and N. Modadugu, "Datagram Transport Layer [RFC6347] Rescorla, E. and N. Modadugu, "Datagram Transport Layer
Security Version 1.2", RFC 6347, DOI 10.17487/RFC6347, Security Version 1.2", RFC 6347, DOI 10.17487/RFC6347,
January 2012, <http://www.rfc-editor.org/info/rfc6347>. January 2012, <http://www.rfc-editor.org/info/rfc6347>.
[RFC7252] Shelby, Z., Hartke, K., and C. Bormann, "The Constrained [RFC7252] Shelby, Z., Hartke, K., and C. Bormann, "The Constrained
Application Protocol (CoAP)", RFC 7252, Application Protocol (CoAP)", RFC 7252,
DOI 10.17487/RFC7252, June 2014, DOI 10.17487/RFC7252, June 2014,
<http://www.rfc-editor.org/info/rfc7252>. <http://www.rfc-editor.org/info/rfc7252>.
[RFC7516] Jones, M. and J. Hildebrand, "JSON Web Encryption (JWE)",
RFC 7516, DOI 10.17487/RFC7516, May 2015,
<http://www.rfc-editor.org/info/rfc7516>.
[RFC7517] Jones, M., "JSON Web Key (JWK)", RFC 7517,
DOI 10.17487/RFC7517, May 2015,
<http://www.rfc-editor.org/info/rfc7517>.
10.2. Informative References 10.2. Informative References
[I-D.ietf-ace-actors] [I-D.ietf-ace-actors]
Gerdes, S., Seitz, L., Selander, G., and C. Bormann, "An Gerdes, S., Seitz, L., Selander, G., and C. Bormann, "An
architecture for authorization in constrained architecture for authorization in constrained
environments", draft-ietf-ace-actors-02 (work in environments", draft-ietf-ace-actors-02 (work in
progress), October 2015. progress), October 2015.
[I-D.ietf-core-block] [I-D.ietf-core-block]
Bormann, C. and Z. Shelby, "Block-wise transfers in CoAP", Bormann, C. and Z. Shelby, "Block-wise transfers in CoAP",
draft-ietf-core-block-18 (work in progress), September draft-ietf-core-block-18 (work in progress), September
2015. 2015.
[I-D.seitz-ace-core-authz] [I-D.seitz-ace-core-authz]
Seitz, L., Selander, G., and M. Vucinic, "Authorization Seitz, L., Selander, G., and M. Vucinic, "Authorization
for Constrained RESTful Environments", draft-seitz-ace- for Constrained RESTful Environments", draft-seitz-ace-
core-authz-00 (work in progress), June 2015. core-authz-00 (work in progress), June 2015.
[I-D.somaraju-ace-multicast] [I-D.somaraju-ace-multicast]
Somaraju, A., Kumar, S., and H. Tschofenig, "Multicast Somaraju, A., Kumar, S., Tschofenig, H., and W. Werner,
Security for the Lighting Domain", draft-somaraju-ace- "Security for Low-Latency Group Communication", draft-
multicast-00 (work in progress), July 2015. somaraju-ace-multicast-01 (work in progress), January
2016.
[RFC4680] Santesson, S., "TLS Handshake Message for Supplemental [RFC4680] Santesson, S., "TLS Handshake Message for Supplemental
Data", RFC 4680, DOI 10.17487/RFC4680, October 2006, Data", RFC 4680, DOI 10.17487/RFC4680, October 2006,
<http://www.rfc-editor.org/info/rfc4680>. <http://www.rfc-editor.org/info/rfc4680>.
[RFC4949] Shirey, R., "Internet Security Glossary, Version 2", [RFC4949] Shirey, R., "Internet Security Glossary, Version 2",
FYI 36, RFC 4949, DOI 10.17487/RFC4949, August 2007, FYI 36, RFC 4949, DOI 10.17487/RFC4949, August 2007,
<http://www.rfc-editor.org/info/rfc4949>. <http://www.rfc-editor.org/info/rfc4949>.
[RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security
skipping to change at page 33, line 5 skipping to change at page 39, line 18
<http://www.rfc-editor.org/info/rfc5246>. <http://www.rfc-editor.org/info/rfc5246>.
[RFC6690] Shelby, Z., "Constrained RESTful Environments (CoRE) Link [RFC6690] Shelby, Z., "Constrained RESTful Environments (CoRE) Link
Format", RFC 6690, DOI 10.17487/RFC6690, August 2012, Format", RFC 6690, DOI 10.17487/RFC6690, August 2012,
<http://www.rfc-editor.org/info/rfc6690>. <http://www.rfc-editor.org/info/rfc6690>.
[RFC6749] Hardt, D., Ed., "The OAuth 2.0 Authorization Framework", [RFC6749] Hardt, D., Ed., "The OAuth 2.0 Authorization Framework",
RFC 6749, DOI 10.17487/RFC6749, October 2012, RFC 6749, DOI 10.17487/RFC6749, October 2012,
<http://www.rfc-editor.org/info/rfc6749>. <http://www.rfc-editor.org/info/rfc6749>.
[RFC6750] Jones, M. and D. Hardt, "The OAuth 2.0 Authorization
Framework: Bearer Token Usage", RFC 6750,
DOI 10.17487/RFC6750, October 2012,
<http://www.rfc-editor.org/info/rfc6750>.
[RFC6819] Lodderstedt, T., Ed., McGloin, M., and P. Hunt, "OAuth 2.0 [RFC6819] Lodderstedt, T., Ed., McGloin, M., and P. Hunt, "OAuth 2.0
Threat Model and Security Considerations", RFC 6819, Threat Model and Security Considerations", RFC 6819,
DOI 10.17487/RFC6819, January 2013, DOI 10.17487/RFC6819, January 2013,
<http://www.rfc-editor.org/info/rfc6819>. <http://www.rfc-editor.org/info/rfc6819>.
[RFC7049] Bormann, C. and P. Hoffman, "Concise Binary Object [RFC7049] Bormann, C. and P. Hoffman, "Concise Binary Object
Representation (CBOR)", RFC 7049, DOI 10.17487/RFC7049, Representation (CBOR)", RFC 7049, DOI 10.17487/RFC7049,
October 2013, <http://www.rfc-editor.org/info/rfc7049>. October 2013, <http://www.rfc-editor.org/info/rfc7049>.
[RFC7159] Bray, T., Ed., "The JavaScript Object Notation (JSON) Data [RFC7159] Bray, T., Ed., "The JavaScript Object Notation (JSON) Data
skipping to change at page 33, line 50 skipping to change at page 40, line 23
Common IoT constraints are: Common IoT constraints are:
Low Power Radio: Low Power Radio:
Many IoT devices are equipped with a small battery which needs to Many IoT devices are equipped with a small battery which needs to
last for a long time. For many constrained wireless devices the last for a long time. For many constrained wireless devices the
highest energy cost is associated to transmitting or receiving highest energy cost is associated to transmitting or receiving
messages. It is therefore important to keep the total messages. It is therefore important to keep the total
communication overhead low, including minimizing the number and communication overhead low, including minimizing the number and
size of messages sent and received, which has an impact of choice size of messages sent and received, which has an impact of choice
of message format and protocol. By using CoAP over UDP, and CBOR on the message format and protocol. By using CoAP over UDP, and
encoded messages some of these aspects are addressed. Security CBOR encoded messages some of these aspects are addressed.
protocols contribute to the communication overhead and can in some Security protocols contribute to the communication overhead and
cases can be optimized. For example authentication and key can in some cases be optimized. For example authentication and
establishment may in certain cases where security requirements so key establishment may in certain cases where security requirements
allows be replaced by provisioning of security context by a so allows be replaced by provisioning of security context by a
trusted third party, using transport or application layer trusted third party, using transport or application layer
security. security.
Low CPU Speed: Low CPU Speed:
Some IoT devices are equipped with processors that are Some IoT devices are equipped with processors that are
significantly slower than those found in most current devices on significantly slower than those found in most current devices on
the Internet. This typically has implications on what timely the Internet. This typically has implications on what timely
cryptographic operations a device is capable to perform, which in cryptographic operations a device is capable to perform, which in
turn impacts e.g. protocol latency. Symmetric key cryptography turn impacts e.g. protocol latency. Symmetric key cryptography
skipping to change at page 35, line 19 skipping to change at page 41, line 40
The communication interactions this framework builds upon (as The communication interactions this framework builds upon (as
shown graphically in Figure 1) may be accomplished using a variety shown graphically in Figure 1) may be accomplished using a variety
of different protocols, and not all parts of the message flow are of different protocols, and not all parts of the message flow are
used in all applications due to the communication constraints. used in all applications due to the communication constraints.
While we envision deployments to make use of CoAP we explicitly While we envision deployments to make use of CoAP we explicitly
want to support HTTP, HTTP/2 or specific protocols, such as want to support HTTP, HTTP/2 or specific protocols, such as
Bluetooth Smart communication, which does not necessarily use IP. Bluetooth Smart communication, which does not necessarily use IP.
The latter raises the need for application layer security over the The latter raises the need for application layer security over the
various interfaces. various interfaces.
Appendix B. Optimizations Appendix B. Roles and Responsibilites -- a Checklist
Resource Owner
* Make sure that the RS is registered at the AS.
* Make sure that clients can discover the AS which is in charge
of the RS.
* Make sure that the AS has the necessary, up-to-date, access
control policies for the RS.
Requesting Party
* Make sure that the client is provisioned the necessary
credentials to authenticate to the AS.
* Make sure that the client is configured to follow the security
requirements of the Requesting Party, when issuing requests
(e.g. minimum communication security requirements, trust
anchors).
* Register the client at the AS.
Authorization Server
* Register RS and manage corresponding security contexts.
* Register clients and including authentication credentials.
* Allow Resource Onwers to configure and update access control
policies related to their registered RS'
* Expose a service that allows clients to request tokens.
* Authenticate clients that wishes to request a token.
* Process a token requests against the authorization policies
configured for the RS.
* Expose a service that allows RS's to submit token introspection
requests.
* Authenticate RS's that wishes to get an introspection response.
* Process token introspection requests.
* Optionally: Handle token revocation.
Client
* Discover the AS in charge of the RS that is to be targeted with
a request.
* Submit the token request (A).
+ Authenticate towards the AS.
+ Specify which RS, which resource(s), and which action(s) the
request(s) will target.
+ Specify preferences for communication security
+ If raw public key (rpk) or certificate is used, make sure
the AS has the right rpk or certificate for this client.
* Process the access token and client information (B)
+ Check that the token has the right format (e.g. CWT).
+ Check that the client information provides the necessary
security parameters (e.g. PoP key, information on
communication security protocols supported by the RS).
* Send the token and request to the RS (C)
+ Authenticate towards the RS (this could coincide with the
proof of possession process).
+ Transmit the token as specified by the AS (default is to an
authorization information resource, alternative options are
as a CoAP option or in the DTLS handshake).
+ Perform the proof-of-possession procedure as specified for
the type of used token (this may already have been taken
care of through the authentication procedure).
* Process the RS response (F) requirements of the Requesting
Party, when issuing requests (e.g. minimum communication
security requirements, trust anchors).
* Register the client at the AS.
Resource Server
* Expose a way to submit access tokens.
* Process an access token.
+ Verify the token is from the right AS.
+ Verify that the token applies to this RS.
+ Check that the token has not expired (if the token provides
expiration information).
+ Check the token's integrity.
+ Store the token so that it can be retrieved in the context
of a matching request.
* Process a request.
+ Set up communication security with the client.
+ Authenticate the client.
+ Match the client against existing tokens.
+ Check that tokens belonging to the client actually authorize
the requested action.
+ Optionally: Check that the matching tokens are still valid
(if this is possible.
* Send a response following the agreed upon communication
security.
Appendix C. Optimizations
This section sketches some potential optimizations to the presented This section sketches some potential optimizations to the presented
solution. solution.
Access token in DTLS handshake Access token in DTLS handshake
In the case of CSP=DTLS/TLS, the access token provisoning exchange In the case of CSP=DTLS/TLS, the access token provisioning
in step C of the protocol may be embedded in the security exchange in step C of the protocol may be embedded in the security
handshake. Different solutions are possible, where one handshake. Different solutions are possible, where one
standardized method would be the use of the TLS supplemental data standardized method would be the use of the TLS supplemental data
extension [RFC4680] for transferring the access token. extension [RFC4680] for transferring the access token.
Reference token and introspection Reference token and introspection
In case of introspection it may be useful with access tokens which In case of introspection it may be beneficial to utilize access
are not self-contained (also known as "reference tokens") that are tokens which are not self-contained (also known as "reference
used to lookup detailed information about the authorization. The tokens") that are used to lookup detailed information about the
RS uses the introspection message exchange not only for validating authorization. The RS uses the introspection message exchange not
token claims, but also for obtaining claims that potentially were only for validating token claims, but also for obtaining claims
not known at the time when the access token was issued. that potentially were not known at the time when the access token
was issued.
A reference token can be made much more compact than a self- A reference token can be made much more compact than a self-
contained token, since it does not need to contain any of claims contained token, since it does not need to contain any of claims
that it represents. This could be very useful in particular if that it represents. This could be very useful in particular if
the client is constrained and offline most of the time. the client is constrained and offline most of the time.
Reference token in CoAP option Reference token in CoAP option
While large access tokens must be sent in CoAP payload, if the While large access tokens must be sent in CoAP payload, if the
access token is known to be of a certain limited size, for example access token is known to be of a certain limited size, for example
in the case of a reference token, then it would be favorable to in the case of a reference token, then it would be favorable to
combine the access token provisioning request with the resource combine the access token provisioning request with the resource
request to the RS. request to the RS.
One way to achieve this is to define a new CoAP option for One way to achieve this is to define a new CoAP option for
carrying reference tokens, called "Ref-Token" as shown in the carrying reference tokens, called "Ref-Token" as shown in the
example in Figure 23. example in Figure 28.
Resource Resource
Client Server Client Server
| | | |
C: +-------->| Header: PUT (Code=0.02) C: +-------->| Header: PUT (Code=0.02)
| PUT | Ref-Token:SlAV32hkKG | PUT | Ref-Token:SlAV32hkKG
| | Object-Security: | | Object-Security:
| | <seq>,<cid>,[Uri-Path:"lock", 1],<tag>) | | <seq>,<cid>,[Uri-Path:"lock", 1],<tag>)
| | | |
. . . .
. . . .
. . . .
| | | |
F: |<--------+ Header: 2.04 Changed F: |<--------+ Header: 2.04 Changed
| 2.04 | Object-Security: | 2.04 | Object-Security:
| | (<seq>,<cid>,,<tag>) | | (<seq>,<cid>,,<tag>)
| | | |
Figure 23: Reference Token in CoAP Option Figure 28: Reference Token in CoAP Option
Appendix C. CoAP and CBOR profiles for OAuth 2.0 Appendix D. CoAP and CBOR profiles for OAuth 2.0
Many IoT devices can support OAuth 2.0 without any additional Many IoT devices can support OAuth 2.0 without any additional
extensions, but for certain constrained settings additional profiling extensions, but for certain constrained settings additional profiling
is needed. In this appendix we define CoAP resources for the HTTP is needed. In this appendix we define CoAP resources for the HTTP
based token and introspection endpoints used in vanilla OAuth 2.0. based token and introspection endpoints used in vanilla OAuth 2.0.
We also define a CBOR alternative to the JSON and form based POST We also define a CBOR alternative to the JSON and form based POST
structures used in HTTP. structures used in HTTP.
C.1. Profile for Token resource D.1. Profile for Token resource
The token resource is used by the client to obtain an access token by The token resource is used by the client to obtain an access token by
presenting its authorization grant or client credentials to the presenting its authorization grant or client credentials to the
/token resource the AS. /token resource the AS.
C.1.1. Token Request D.1.1. Token Request
The client makes a request to the token resource by sending a CBOR The client makes a request to the token resource by sending a CBOR
structure with the following attributes. structure with the following attributes.
grant_type: grant_type:
REQUIRED. The grant type, "code", "client_credentials", REQUIRED. The grant type, "code", "client_credentials",
"password" or others. "password" or others.
client_id: client_id:
skipping to change at page 38, line 17 skipping to change at page 47, line 17
|-----------+--------------+-----------------------| |-----------+--------------+-----------------------|
| 0 | 0 | grant_type | | 0 | 0 | grant_type |
| 1 | 0 | client_id | | 1 | 0 | client_id |
| 2 | 0 | client_secret | | 2 | 0 | client_secret |
| 3 | 0 | scope | | 3 | 0 | scope |
| 4 | 0 | aud | | 4 | 0 | aud |
| 5 | 0 | alg | | 5 | 0 | alg |
| 6 | 0 | key | | 6 | 0 | key |
\-----------+--------------+-----------------------/ \-----------+--------------+-----------------------/
Figure 24: CBOR mappings used in token requests Figure 29: CBOR mappings used in token requests
C.1.2. Token Response D.1.2. Token Response
The AS responds by sending a CBOR structure with the following The AS responds by sending a CBOR structure with the following
attributes. attributes.
access_token: access_token:
REQUIRED. The access token issued by the authorization server. REQUIRED. The access token issued by the authorization server.
token_type: token_type:
skipping to change at page 39, line 22 skipping to change at page 48, line 22
| Value | Major Type | Key | | Value | Major Type | Key |
|-----------+--------------+-----------------------| |-----------+--------------+-----------------------|
| 0 | 0 | access_token | | 0 | 0 | access_token |
| 1 | 0 | token_type | | 1 | 0 | token_type |
| 2 | 0 | key | | 2 | 0 | key |
| 3 | 0 | csp | | 3 | 0 | csp |
| 4 | 0 | scope | | 4 | 0 | scope |
| 5 | 0 | alg | | 5 | 0 | alg |
\-----------+--------------+-----------------------/ \-----------+--------------+-----------------------/
Figure 25: CBOR mappings used in token responses Figure 30: CBOR mappings used in token responses
C.2. CoAP Profile for OAuth Introspection D.2. CoAP Profile for OAuth Introspection
This section defines a way for a holder of access tokens, mainly This section defines a way for a holder of access tokens, mainly
clients and RS's, to get metadata like validity status, claims and clients and RS's, to get metadata like validity status, claims and
scopes found in access token. The OAuth Token Introspection scopes found in access token. The OAuth Token Introspection
specification [I-D.ietf-oauth-introspection] defines a way to specification [I-D.ietf-oauth-introspection] defines a way to
validate the token using HTTP POST or HTTP GET. This document reuses validate the token using HTTP POST or HTTP GET. This document reuses
the work done in the OAuth Token Introspection and defines a mapping the work done in the OAuth Token Introspection and defines a mapping
of the request and response to CoAP [RFC7252] to be used by of the request and response to CoAP [RFC7252] to be used by
constrained devices. constrained devices.
C.2.1. Introspection Request D.2.1. Introspection Request
The token holder makes a request to the Introspection CoAP resource The token holder makes a request to the Introspection CoAP resource
by sending a CBOR structure with the following attributes. by sending a CBOR structure with the following attributes.
token: token:
REQUIRED. The string value of the token. REQUIRED. The string value of the token.
resource_id: resource_id:
skipping to change at page 40, line 20 skipping to change at page 49, line 20
/-----------+--------------+-----------------------\ /-----------+--------------+-----------------------\
| Value | Major Type | Key | | Value | Major Type | Key |
|-----------+--------------+-----------------------| |-----------+--------------+-----------------------|
| 0 | 0 | token | | 0 | 0 | token |
| 1 | 0 | resource_id | | 1 | 0 | resource_id |
| 2 | 0 | client_id | | 2 | 0 | client_id |
| 3 | 0 | client_secret | | 3 | 0 | client_secret |
\-----------+--------------+-----------------------/ \-----------+--------------+-----------------------/
Figure 26: CBOR Mappings to Token Introspection Request Parameters. Figure 31: CBOR Mappings to Token Introspection Request Parameters.
C.2.2. Introspection Response D.2.2. Introspection Response
If the introspection request is valid and authorized, the If the introspection request is valid and authorized, the
authorization server returns a CoAP message with the response encoded authorization server returns a CoAP message with the response encoded
as a CBOR structure in the payload of the message. If the request as a CBOR structure in the payload of the message. If the request
failed client authentication or is invalid, the authorization server failed client authentication or is invalid, the authorization server
returns an error response using the CoAP 4.00 'Bad Request' response returns an error response using the CoAP 4.00 'Bad Request' response
code. code.
The JSON structure in the payload response includes the top-level The JSON structure in the payload response includes the top-level
members defined in Section 2.2 in the OAuth Token Introspection members defined in Section 2.2 in the OAuth Token Introspection
skipping to change at page 42, line 34 skipping to change at page 51, line 34
| 4 | 0 | token_type | | 4 | 0 | token_type |
| 5 | 0 | exp | | 5 | 0 | exp |
| 6 | 0 | iat | | 6 | 0 | iat |
| 7 | 0 | nbf | | 7 | 0 | nbf |
| 8 | 0 | sub | | 8 | 0 | sub |
| 9 | 0 | aud | | 9 | 0 | aud |
| 10 | 0 | iss | | 10 | 0 | iss |
| 11 | 0 | cti | | 11 | 0 | cti |
\-----------+--------------+-----------------------/ \-----------+--------------+-----------------------/
Figure 27: CBOR Mappings to Token Introspection Response Parameters. Figure 32: CBOR Mappings to Token Introspection Response Parameters.
Appendix E. Document Updates
E.1. Version -00 to -01
o Changed 5.1. from "Communication Security Protocol" to "Client
Information".
o Major rewrite of 5.1 to clarify the information exchanged between
C and AS in the PoP token request profile for IoT.
* Allow the client to indicate preferences for the communication
security protocol.
* Defined the term "Client Information" for the additional
information returned to the client in addition to the access
token.
* Require that the messages between AS and client are secured,
either with (D)TLS or with COSE_Encrypted wrappers.
* Removed dependency on OSCoAP and added generic text about
object security instead.
* Defined the "rpk" parameter in the client information to
transmit the raw public key of the RS from AS to client.
* (D)TLS MUST use the PoP key in the handshake (either as PSK or
as client RPK with client authentication).
* Defined the use of x5c, x5t and x5tS256 parameters when a
client certificate is used for proof of possession.
* Defined "tktn" parameter for signaling for how to tranfer the
access token.
o Added 5.2. the CoAP Access-Token option for transfering access
tokens in messages that do not have payload.
o 5.3.2. Defined success and error responses from the RS when
receiving an access token.
o 5.6.:Added section giving guidance on how to handle token
expiration in the absence of reliable time.
o Appendix B Added list of roles and responsibilities for C, AS and
RS.
Authors' Addresses Authors' Addresses
Ludwig Seitz Ludwig Seitz
SICS SICS
Scheelevaegen 17 Scheelevaegen 17
Lund 223 70 Lund 223 70
SWEDEN SWEDEN
Email: ludwig@sics.se Email: ludwig@sics.se
 End of changes. 94 change blocks. 
167 lines changed or deleted 640 lines changed or added

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