Delegated CoAP Authorization Function (DCAF)
draft-gerdes-core-dcaf-authorize-00
The information below is for an old version of the document.
| Document | Type |
This is an older version of an Internet-Draft whose latest revision state is "Replaced".
|
|
|---|---|---|---|
| Authors | Stefanie Gerdes , Olaf Bergmann , Carsten Bormann | ||
| Last updated | 2013-07-15 | ||
| Replaced by | draft-gerdes-ace-dcaf-authorize | ||
| RFC stream | (None) | ||
| Formats | |||
| Stream | Stream state | (No stream defined) | |
| Consensus boilerplate | Unknown | ||
| RFC Editor Note | (None) | ||
| IESG | IESG state | I-D Exists | |
| Telechat date | (None) | ||
| Responsible AD | (None) | ||
| Send notices to | (None) |
draft-gerdes-core-dcaf-authorize-00
CoRE Working Group S. Gerdes
Internet-Draft O. Bergmann
Intended status: Standards Track C. Bormann
Expires: January 16, 2014 Universitaet Bremen TZI
July 15, 2013
Delegated CoAP Authorization Function (DCAF)
draft-gerdes-core-dcaf-authorize-00
Abstract
This specification defines a protocol for delegating client
authentication and authorization in a constrained environment for
establishing a Datagram Transport Layer Security (DTLS) channel
between resource-constrained nodes. The protocol relies on DTLS to
transfer authorization information and shared secrets for symmetric
cryptography between entities in a constrained network. A resource-
constrained node can use this protocol to delegate authentication of
communication peers and management of authorization information to a
trusted host with less limitations regarding processing power and
memory.
Status of this Memo
This Internet-Draft is submitted in full conformance with the
provisions of BCP 78 and BCP 79.
Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF). Note that other groups may also distribute
working documents as Internet-Drafts. The list of current Internet-
Drafts is at http://datatracker.ietf.org/drafts/current/.
Internet-Drafts are draft documents valid for a maximum of six months
and may be updated, replaced, or obsoleted by other documents at any
time. It is inappropriate to use Internet-Drafts as reference
material or to cite them other than as "work in progress."
This Internet-Draft will expire on January 16, 2014.
Copyright Notice
Copyright (c) 2013 IETF Trust and the persons identified as the
document authors. All rights reserved.
This document is subject to BCP 78 and the IETF Trust's Legal
Provisions Relating to IETF Documents
(http://trustee.ietf.org/license-info) in effect on the date of
Gerdes, et al. Expires January 16, 2014 [Page 1]
Internet-Draft DCAF July 2013
publication of this document. Please review these documents
carefully, as they describe your rights and restrictions with respect
to this document. Code Components extracted from this document must
include Simplified BSD License text as described in Section 4.e of
the Trust Legal Provisions and are provided without warranty as
described in the Simplified BSD License.
Gerdes, et al. Expires January 16, 2014 [Page 2]
Internet-Draft DCAF July 2013
Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 4
1.1. Features . . . . . . . . . . . . . . . . . . . . . . . . . 4
1.2. Terminology . . . . . . . . . . . . . . . . . . . . . . . 4
1.2.1. Roles . . . . . . . . . . . . . . . . . . . . . . . . 4
2. System Overview . . . . . . . . . . . . . . . . . . . . . . . 6
3. Protocol . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
3.1. Overview . . . . . . . . . . . . . . . . . . . . . . . . . 7
3.2. Unauthorized Resource Request Message . . . . . . . . . . 8
3.3. AS(RS) Information Message . . . . . . . . . . . . . . . . 9
3.4. Authorization Request . . . . . . . . . . . . . . . . . . 9
3.5. Ticket Request Message . . . . . . . . . . . . . . . . . . 11
3.6. Ticket Grant Message . . . . . . . . . . . . . . . . . . . 11
3.7. Ticket Transmission Message . . . . . . . . . . . . . . . 13
3.8. DTLS Channel Setup Between C and RS . . . . . . . . . . . 13
3.9. Authorized Resource Request Message . . . . . . . . . . . 13
4. Ticket . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
4.1. Face . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
4.2. Verifier . . . . . . . . . . . . . . . . . . . . . . . . . 15
4.3. Revocation . . . . . . . . . . . . . . . . . . . . . . . . 16
4.3.1. Lifetime . . . . . . . . . . . . . . . . . . . . . . . 16
4.3.2. Revocation Messages . . . . . . . . . . . . . . . . . 16
5. Payload Format and Encoding (application/dcaf+json) . . . . . 17
5.1. Examples . . . . . . . . . . . . . . . . . . . . . . . . . 18
6. DTLS PSK Generation Methods . . . . . . . . . . . . . . . . . 21
6.1. DTLS PSK Transfer . . . . . . . . . . . . . . . . . . . . 21
6.2. Distributed Key Derivation . . . . . . . . . . . . . . . . 21
7. Authorization Configuration . . . . . . . . . . . . . . . . . 23
8. Trust Relationships . . . . . . . . . . . . . . . . . . . . . 24
9. Listing Authorization Server Information in a Resource
Directory . . . . . . . . . . . . . . . . . . . . . . . . . . 25
10. Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . 26
10.1. Access Granted . . . . . . . . . . . . . . . . . . . . . . 26
10.2. Access Denied . . . . . . . . . . . . . . . . . . . . . . 28
10.3. Access Restricted . . . . . . . . . . . . . . . . . . . . 28
11. Security Considerations . . . . . . . . . . . . . . . . . . . 30
12. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 31
12.1. dcaf+json Media Type Registration . . . . . . . . . . . . 31
12.2. CoAP Content Format Registration . . . . . . . . . . . . . 32
13. References . . . . . . . . . . . . . . . . . . . . . . . . . . 33
13.1. Normative References . . . . . . . . . . . . . . . . . . . 33
13.2. Informative References . . . . . . . . . . . . . . . . . . 33
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 35
Gerdes, et al. Expires January 16, 2014 [Page 3]
Internet-Draft DCAF July 2013
1. Introduction
The Constrained Application Protocol (CoAP) [I-D.ietf-core-coap] is a
transfer protocol similar to HTTP which is designed for the special
requirements of constrained environments. A serious problem with
constrained devices is the realization of secure communication. The
devices only have limited resources such as memory, disk space and
transmission capacity and often lack input/output devices such as
keyboards or displays. Therefore, they are not readily capable of
using common protocols. Especially authentication mechanisms are
difficult to realize, because the lack of disk space severely limits
the number of keys the system can store. Moverover, although CoAP
provides for a simple authorization mechanism, it has no means to
distinguish access rights for different clients.
The DCAF architecture is designed to relieve the constrained nodes
from managing keys for numerous devices by introducing authorization
servers which conduct the authentication and authorization for their
nodes. To achieve this, authorization tickets are used. A device
which wants to access a constrained node's resource first has to gain
permission in the form of a ticket from the node's authorization
server.
The main goals of DCAF are the setup of a Datagram Transport Layer
Security (DTLS) [RFC6347] channel with symmetric pre-shared keys
(PSK) [RFC4279] and to securely transmit authorization tickets.
1.1. Features
o Providing means for DTLS communication with pre-shared keys.
o Authenticated exchange of authorization information.
o Using only symmetric encryption on constrained nodes.
1.2. Terminology
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
"SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
document are to be interpreted as described in RFC 2119 [RFC2119].
1.2.1. Roles
Authorization Server (AS): The device which conducts authentication
and authorization for a constrained device. An Authorization Server
can be responsible for a single or multiple devices or even for a
whole network. A constrained device can have multiple Authorization
Servers.
Gerdes, et al. Expires January 16, 2014 [Page 4]
Internet-Draft DCAF July 2013
Resource Server (RS): The constrained device which hosts resources
the Client wants to access.
Client (C): A device which wants to access a resource on the Resource
Server.
Resource Owner: The subject who owns the resource and controls its
access permissions.
Gerdes, et al. Expires January 16, 2014 [Page 5]
Internet-Draft DCAF July 2013
2. System Overview
Within the DCAF Architecture each constrained device has one or more
Authorization servers (AS) which conduct the authentication and
authorization for the device. The constrained device and the AS
share a symmetric key which has to be exchanged initially to provide
for a secure channel. The mechanism used for this is not in the
scope of this document.
To gain access to a specific resource on a Resource Server (RS), a
client (C) has to request an authorization ticket from RS'
Authorization Server (AS(RS)) either directly or, if it is a
constrained device using its own Authorization Server (AS(C)).
If AS(RS) decides that C is allowed to access the resource, it
generates a DTLS pre-shared key (PSK) for the communication between C
and RS and wraps it together with the access permissions into an
authorization ticket. After presenting the ticket to the RS, C and
RS can communicate securely.
To be able to provide for the authentication and authorization
services, the Authorization Servers have to fulfill several
requirements. They MUST have enough disk space to store a sufficient
number of credentials (matching the number of clients and Resource
Servers) and MUST possess means for user interaction, for example
input/output devices like keyboard and display to allow for
configuration of authorization information by the Resource Owner.
Additionally they MUST have enough processing power to handle the
authorization requests for all devices they are responsible for.
Gerdes, et al. Expires January 16, 2014 [Page 6]
Internet-Draft DCAF July 2013
3. Protocol
The DCAF protocol comprises three parts:
1. Transmission of authorization information between C and RS,
2. transmission of authorization requests and access grants between
C and AS(C), and
3. transmission of authorization requests and access grants between
AS(C) and AS(RS).
3.1. Overview
In Figure 1, a protocol flow with an Authentication Server for RS is
depicted (messages in square brackets are optional):
AS(C) C RS AS(RS)
| <== DTLS chan. ==> | | <== DTLS chan. ==> |
| | [Resource Req.-->] | |
| | | |
| | [<-- AS(RS) Info.] | |
| | | |
| <-- Author. Req. | | |
| | | |
| <====== TLS/DTLS channel (AS Mutual Authentication) =======> |
| | | |
| Ticket Request ------------------------------------------> |
| | | |
| <------------------------------------------ Ticket Grant |
| | | |
| Ticket Transm. --> | | |
| | | |
| | <== DTLS chan. ==> | |
| | Auth. Res. Req. -> | |
Figure 1: Protocol Overview
To determine the Authorization Server that is in charge of a resource
hosted at the Resource Server (RS), the client (C) MAY send an
initial Unauthorized Resource Request message to RS. RS then rejects
the request and sends the address of its authorization server
(AS(RS)) back to the client.
Instead of the initial Unauthorized Resource Request message, C MAY
lookup the desired resource in a resource directory (cf.
[I-D.ietf-core-resource-directory]) that lists RS's resources as
Gerdes, et al. Expires January 16, 2014 [Page 7]
Internet-Draft DCAF July 2013
discussed in Section 9.
Once C knows AS(RS)'s address, it can send a request for
authorization to AS(RS) using its own Authorization Server (AS(C)).
After authenticating AS(C), AS(RS) decides if C is allowed to access
the requested resource and in this case generates an access ticket
for C. The ticket contains a representation of the permissions C has
for the resource as well as keying material for the establishment of
a secure channel. C keeps one part of the access ticket and presents
the other part to RS to prove its right to access the resource. With
their respective parts of the ticket, C and RS are able to establish
a secure channel.
The following sections specify how CoAP is used to interchange
authorization-related data between RS and AS(RS) so that AS(RS) can
provide C and RS with sufficient information to establish a secure
channel using symmetric cryptography, and simultaneously convey
authorization information specific for this communication
relationship to RS.
This document uses JavaScript Object Notation (JSON, [RFC4627]) to
express authorization information as set of attributes passed in CoAP
payloads. Notation and encoding options are discussed in Section 5.
3.2. Unauthorized Resource Request Message
The optional Unauthorized Resource Request message is a request for a
resource hosted by RS for which no proper authorization is granted.
RS MUST treat any CoAP request as Unauthorized Resource Request
message when any of the following holds:
o The request has been received on an insecure channel.
o RS has no valid authorization information for the sender of the
request regarding the requested action on that resource.
o RS has valid authorization information for the sender of the
request that does not allow the requested action on the requested
resource.
Note: These conditions ensure that RS can handle requests
autonomously once access was granted and a secure channel has been
established between C and RS.
Unauthorized Resource Request messages MUST be rejected with a 4.01
(Unauthorized) response. In this response, the Resource Server MUST
provide proper AS(RS) Information to enable the Client to request an
access ticket from RS's Authorization Server as described in
Gerdes, et al. Expires January 16, 2014 [Page 8]
Internet-Draft DCAF July 2013
Section 3.3.
3.3. AS(RS) Information Message
The AS(RS) Information Message is sent by RS as a response to an
Unauthorized Resource Request message (see Section 3.2) to point the
sender of the Unauthorized Resource Request message to RS's
Authorization Server. The AS(RS) Information is a set of attributes
containing an absolute URI (see Section 4.3 of [RFC3986]) that
specifies the Authorization Server in charge of RS.
The message MAY also contain a timestamp generated by RS.
Figure 2 shows an example for an AS(RS) Information message payload
using JSON. (Refer to Section 5 for a detailed description of the
available attributes and their semantics.)
4.01 Unauthorized
Content-Format: application/dcaf+json
{
"AS": "coaps://as-rs.example.com/authorize",
"TS": 168537
}
Figure 2: AS(RS) Information Payload Example
In this example, the attribute AS points the receiver of this message
to the URI "coaps://as-rs.example.com/authorize" to request access
permissions. The originator of the AS(RS) Information payload (i.e.
RS) uses a local clock that is loosely synchronized with wall clock
time. Therefore, it has included a time stamp on its own time scale
that is used as a nonce for replay attack prevention. Refer to
Section 4.1 for more details concerning the usage of time stamps to
ensure freshness of authorization tickets.
3.4. Authorization Request
To retrieve an authorization ticket for the resource that C wants to
access, C sends an Authorization Request to its authorization server
AS(C). The Authorization Request is constructed as follows:
1. The request method is POST.
2. The request URI is set as described below.
3. The message payload contains a data structure that describes the
action and resource for which C requests an authorization ticket.
Gerdes, et al. Expires January 16, 2014 [Page 9]
Internet-Draft DCAF July 2013
The request URI identifies a resource at AS(C) for handling
authorization requests from C. The URI SHOULD be announced by AS(C)
in its resource directory as described in Section 9.
Note: Where capacity limitations of C do not allow for resource
directory lookups, the request URI in authorization requests could
be hard-coded during provisioning or set in a specific device
configuration profile.
The message payload is constructed from the authorization information
that RS has returned in its AS(RS) Information message (see
Section 3.3) and information that C provides to describe its intended
request(s). The Authorization Request MUST contain the following
attributes:
1. Contact information for the AS(RS) to use.
2. An identifier of C that is recognized by AS(RS).
3. An absolute URI of the resource that C wants to access.
4. The actions that C wants to perform on the resource.
5. Any time stamp generated by RS.
An example Authorization Request from C to AS(C) is depicted in
Figure 3. (Refer to Section 5 for a detailed description of the
available attributes and their semantics.)
POST client-authorize
Content-Format: application/dcaf+json
{
"AS": coaps://as-rs.example.com/authorize",
"CI": "node-588",
"M": [ "GET", "PUT" ],
"R": "coaps://temp451.example.com/s/tempC",
"TS": 168537
}
Figure 3: Authorization Message Example
The example shows an Authorization Request message payload for the
resource "/s/tempC" on the Resource Server "temp451.example.com".
Requested operations in attribute M are GET and PUT. The requesting
client is identified as "node-588".
The attributes AS (that denotes the Authorization Server to use) and
TS (a nonce generated by RS) are taken from the AS(RS) Information
Gerdes, et al. Expires January 16, 2014 [Page 10]
Internet-Draft DCAF July 2013
message from RS.
The response to an Authorization Request is delivered by AS(C) back
to C in a Ticket Transmission message.
3.5. Ticket Request Message
When AS(C) receives an Authorization Request message from C it MAY
return a cached response if it is known to be fresh. Otherwise, it
checks whether the request payload is of type "application/dcaf+json"
and contains at least the fields AS, CI, M, and R. AS(C) MUST respond
with 4.00 (Bad Request) if the type is "application/dcaf+json" and
any of these fields is missing or does not conform to the format
described in Section 5. Content formats other than application/
dcaf+json are out of scope of this specification.
When the payload is correct AS(C) MUST create a Ticket Request
message from the Authorization Request received from C as follows:
1. The destination of the Ticket Request message is derived from the
authority information in the URI contained in field "AS" of the
Authorization Request message payload.
2. The request method is POST.
3. The request URI is constructed from the AS field received in the
Authorization Request message payload.
4. The payload is copied from the Authorization Request sent by C.
To sent the Ticket Request message to AS(RS) a secure channel between
AS(C) and AS(RS) MUST be used. Depending on the URI scheme used in
the AS field of the Authorization Request message payload, this could
be, e.g., a DTLS channel (for "coaps") or a TLS connection (for
"https"). AS(C) and AS(RS) MUST be able to mutually authenticate
each other, e.g. based on a public key infrastructure. (Refer to
Section 8 for a detailed discussion of the trust relationship between
authorization servers.)
3.6. Ticket Grant Message
When AS(RS) has received a Ticket Request message it has to evaluate
the authorization request information contained therein. First, it
checks whether the request payload is of type "application/dcaf+json"
and contains at least the fields AS, CI, M, and R. AS(RS) MUST
respond with 4.00 (Bad Request) for CoAP (or 400 for HTTP) if the
type is "application/dcaf+json" and any of these fields is missing or
does not conform to the format described in Section 5.
Gerdes, et al. Expires January 16, 2014 [Page 11]
Internet-Draft DCAF July 2013
AS(RS) decides whether or not access is granted to the requested
resource and then creates a Ticket Grant message that reflects the
result. If AS(RS) grants access to the requested resource it has to
create an access ticket comprised of a Face and a Verifier as
described in Section 4.1.
The Ticket Grant message then is constructed as a success response
indicating attached content, i.e. 2.05 for CoAP, or 200 for HTTP,
respectively. The payload of the Ticket Grant message is a data
structure that contains the result of the access request. When
access is granted the data structure MUST contain the ticket's Face,
the Verifier and the Session Key Generation Method.
The Ticket Grant message MAY provide cache-control options to enable
intermediaries to cache the response. The message MAY be cached
according to the rules defined in [I-D.ietf-core-coap] to facilitate
ticket retrieval when C has crashed and wants to recover the DTLS
session with RS.
AS(RS) sets Max-Age according to the ticket lifetime in its response
(Ticket Grant Message).
Figure 4 shows an example Ticket Grant message using CoAP. The Face/
Verifier information is transferred as JSON data structure as
specified in Section 5. The Max-Age option tells the receiving AS(C)
how long this ticket will be valid.
2.05 Content
Content-Format: application/dcaf+json
Max-Age: 86400
{ "F": {
"AI": { "Role" : 3 },
"CI": "2001:db8:ab9:1234:7920:3133:ae5f:87",
"TS": "2013-07-10T10:04:12.391",
"L": 86400,
"G": "hmac_sha256"
},
"V": "w+ZeJx5MxIEkt7yBMWjX6ztSYcIBTz+sv4z98m+PUEY="
}
Figure 4: Example Ticket Grant Message
A Ticket Grant message that declines any operation on the requested
resource is illustrated in Figure 5. As no ticket needs to be
issued, an empty payload is included with the response.
Gerdes, et al. Expires January 16, 2014 [Page 12]
Internet-Draft DCAF July 2013
2.05 Content
Content-Format: application/dcaf+json
Figure 5: Example Ticket Grant Message With Reject
3.7. Ticket Transmission Message
A Ticket Transmission message delivers the authorization information
sent by AS(RS) in a Ticket Grant message to the requesting client C.
The Ticket Transmission message MUST be the first and only response
to the corresponding Authorization Request message sent from C to
AS(C) and include any authorization information from AS(RS) contained
in the Ticket Grant message.
3.8. DTLS Channel Setup Between C and RS
Using the information contained in a positive response to its
Authorization Request (i.e. a Ticket Transmission message that
contains a Face and a Verifier), C can initiate establishment of a
new DTLS channel with RS. To use DTLS with pre-shared keys, C
follows the PSK key exchange algorithm specified in Section 2 of
[RFC4279], with the following additional requirements:
1. C MUST set the psk_identity field of the ClientKeyExchange
message to the ticket Face received in the Ticket Transmission
message.
2. C MUST use the ticket Verifier as PSK when constructing the
premaster secret.
Note1: As RS cannot provide C with a meaningful PSK identity hint in
response to C's ClientHello message, RS SHOULD NOT send a
ServerKeyExchange message.
Note2: According to [I-D.ietf-core-coap], CoAP implementations MUST
support the ciphersuite TLS_PSK_WITH_AES_128_CCM_8 [RFC6655]. C is
therefore expected to offer at least this ciphersuite to RS.
Note3: The ticket is constructed by AS(RS) such that RS can derive
the authorization information as well as the PSK (refer to Section 6
for details).
3.9. Authorized Resource Request Message
Successful establishment of the DTLS channel between C and RS ties
the authorization information contained in the psk_identity field to
this channel. Any request that RS receives on this channel is
checked against these authorization rules. Incoming CoAP requests
Gerdes, et al. Expires January 16, 2014 [Page 13]
Internet-Draft DCAF July 2013
that are not Authorized Resource Requests MUST be rejected by RS with
4.01 response as described in Section 3.2.
RS SHOULD treat an incoming CoAP request as Authorized Resource
Request if the following holds:
1. The message was received on a secure channel that has been
established using the procedure defined in Section 3.8.
2. The authorization information tied to the secure channel is
valid.
3. The request is destined for RS.
4. The resource URI specified in the request is covered by the
authorization information.
5. The request method is an authorized action on the resource with
respect to the authorization information.
Note that the authorization information is not restricted to a single
resource URI. For example, role-based authorization can be used to
authorize a collection of semantically connected resources
simultaneously. As a result, C can use the same DTLS channel not
only for subsequent requests for the same resource (e.g. for block-
wise transfer as defined in [I-D.ietf-core-block] or refreshing
observe-relationships [I-D.ietf-core-observe]) but also for requests
to distinct resources.
Gerdes, et al. Expires January 16, 2014 [Page 14]
Internet-Draft DCAF July 2013
4. Ticket
A DCAF ticket consists of two parts, the Face and the Verifier.
4.1. Face
Face is the part of the ticket generated for RS. Face MUST contain
all information needed for authorized access to a resource:
o Authorization Information
o Client Identifier
o A timestamp generated by AS(RS)
Optionally, Face MAY also contain:
o A lifetime (optional)
o A DTLS pre-shared key (optional)
RS MUST verify the integrity of Face, i.e. the information contained
in Face stems from AS(RS) and was not manipulated by anyone else.
Face MUST contain a timestamp to verify that the contained
information is fresh. As constrained devices may not have a clock,
timestamps MAY be generated using the clock ticks since the last
reboot. To circumvent synchronization problems the timestamp MAY be
generated by RS and included in the first AS(RS) Information message.
Alternatively, AS(RS) MAY generate the timestamp. In this case,
AS(RS) and RS MUST use a time synchronisation mechanism to make sure
that RS interprets the timestamp correctly.
Face MAY be encrypted. If Face contains a DTLS PSK, the whole
content of Face MUST be encrypted.
Note: The integrity of Face can be ensured by various means. Face
may be encrypted by AS(RS) with a key it shares with RS.
Alternatively, RS can use a mechanism to generate the DTLS PSK which
includes Face and is only able to calculate the correct key with the
correct Face (refer to Section 6 for details).
4.2. Verifier
The Verifier part of the ticket is generated for C. It contains the
DTLS PSK for C. The Verifier MUST NOT be transmitted over insecure
channels.
Gerdes, et al. Expires January 16, 2014 [Page 15]
Internet-Draft DCAF July 2013
4.3. Revocation
4.3.1. Lifetime
Tickets MAY have a lifetime. AS(RS) is responsible for defining the
ticket lifetime. If AS(RS) sets a lifetime for a ticket, AS(RS) and
RS MUST use a time synchronisation method to ensure that RS is able
to interpret the lifetime correctly. RS SHOULD end the DTLS
connection to C if the lifetime of a ticket has run out and it MUST
NOT accept new requests. RS MUST NOT accept tickets with an invalid
lifetime.
Note: Defining reasonable ticket lifetimes is difficult to
accomplish. How long a client needs to access a resource depends
heavily on the application scenario and may be difficult to decide
for AS(RS).
4.3.2. Revocation Messages
AS(RS) MAY revoke tickets by sending a ticket revocation message to
RS. If RS receives a ticket revocation message, it MUST end the DTLS
connection to C and MUST NOT accept any further requests from C.
If ticket revocation messages are used, RS MUST check regularly if
AS(RS) is still available. If RS cannot contact AS(RS), it MUST end
all DTLS connections and reject any further requests from C.
Note: The loss of the connection between RS and AS(RS) prevents all
access to RS. This might especially be a severe problem if AS(RS) is
responsible for several Resource Servers or even a whole network.
Gerdes, et al. Expires January 16, 2014 [Page 16]
Internet-Draft DCAF July 2013
5. Payload Format and Encoding (application/dcaf+json)
Various messages types of the DCAF protocol carry payloads to express
authorization information and parameters for generating the DTLS PSK
to be used by C and RS. In this section, a representation in
JavaScript Object Notation (JSON, [RFC4627]) is defined.
The following attributes are defined:
AS: Authentication Server. This attribute denotes the authorization
server that is in charge of the resource specified in attribute R.
The attribute's value is a string that contains an absolute URI
according to Section 4.3 of [RFC3986].
AI: Authorization Information. A data structure used to convey
authorization information from AS(RS) to RS (see below).
CI: Client Identity. A string that identifies the initiator of the
authorization request. This label MAY be a fully qualified domain
name, an IP address, or any other character literal that is used
by the Authorization Server to decide whether or not access is
granted to the requesting entity.
E: Encrypted Ticket Face. A string containing an encrypted ticket
Face encoded as base64 according to Section 4 of [RFC4648].
K: Key. A string that identifies the shared key between RS and AS(RS)
that can be used to decrypt the contents of E. If the attribute E
is present and no attribute K has been specified, the default is
to use the current session key for the secured channel between RS
and AS(RS).
M: Methods. The list of actions to be performed on the resource R,
encoded as an array of strings. In an authorization request, this
list contains the actions that the initiator of the request wants
to perform. In an authorization ticket, this attribute denotes
the actions that are permitted.
R: Resource. A string that denotes the absolute URI of the resource
to be accessed. As the access ticket is requested in order to
establish a DTLS connection with the server that hosts this
resource, the URI scheme typically is "coaps".
TS: Time Stamp. An optional time stamp that indicates the instant
when the access ticket request was formed. This attribute can be
used by the resource server in an AS(RS) Information message to
convey a time stamp in its local time scale (e.g. when it does not
have a real time clock with synchronized global time). When the
Gerdes, et al. Expires January 16, 2014 [Page 17]
Internet-Draft DCAF July 2013
attribute's value is encoded as a string, it MUST contain a valid
UTC timestamp without time zone information. When encoded as
integer, TS contains a system timestamp relative to the local time
scale of its generator, usually RS.
L: Lifetime. A lifetime of the ticket. When encoded as a string, L
MUST denote the ticket's expiry time as a valid UTC timestamp
without time zone information. When encoded as an integer, L MUST
denote the ticket's validity period in seconds relative to TS.
G: DTLS PSK Generation Method. A string that identifies the method
that RS MUST use to derive the DTLS PSK from the ticket Face.
This attribute MUST NOT be used when attribute V is present within
the contents of F.
F: Ticket Face. An object containing the fields AI, CI, TS, and
optionally G, L and V.
V: Ticket Verifier. A string containing the shared secret between C
and RS, encoded as base64 according to Section 4 of [RFC4648].
The exact specification of AI is out of scope for this document. AI
may, e.g., contain a single role identifier known by RS, or an array
of pairs (M, R) with M and R defined as above.
As AI is used to authorize resource access as defined in Section 3.9,
RS MUST be able to interpret the contained information.
5.1. Examples
The following example specifies an Authorization Server that will be
accessed using HTTP over TLS. The request URI is set to "/a?ep=%
5B2001:DB8::dcaf:1234%5D" (hence denoting the endpoint address to
authorize). TS denotes a local timestamp in UTC.
POST /a?ep=%5B2001:DB8::dcaf:1234%5D HTTP/1.1
Host: as-rs.example.com
Content-Type: application/dcaf+json
{
"AS": "https://as-rs.example.com/a?ep=%5B2001:DB8::dcaf:1234%5D",
"CI": "2001:DB8::dcaf:1234",
"M": [ "GET" ],
"R": "coaps://temp451.example.com/s/tempC",
"TS": "2013-07-14T11:58:22.923"
}
The following example shows a ticket for the distributed key
Gerdes, et al. Expires January 16, 2014 [Page 18]
Internet-Draft DCAF July 2013
generation method (cf. Section 6.2), comprised of a Face (F) and a
Verifier (V). The Face data structure contains authorization
information AI with an application-specific role identifier, a client
identifier, a timestamp using the local time scale of RS, and a
lifetime relative to RS's time scale.
The DTLS PSK Generation Method is set to "hmac_sha256" denoting that
the distributed key derivation is used as defined in Section 6.2 with
SHA-256 as HMAC function.
The Verifier V contains a shared secret to be used as DTLS PSK
between C and RS.
HTTP/1.1 200 OK
Content-Type: application/dcaf+json
{
"F": {
"AI": { "Role" : 3 },
"CI": "2001:db8:ab9:1234:7920:3133:ae5f:87",
"TS": 2938749,
"L": 3600,
"G": "hmac_sha256"
},
"V": "zrPOuc6xzr/Pjc+Bz4TOuSDOvM61IM68zq3Ou865Cg=="
}
The Face may be encrypted as illustrated in the following example.
Here, the field E carries an encrypted and base64-encoded Face data
structure that contains the same information as the previous example,
and an additional Verifier. Encryption was done with a secret shared
by AS(RS) and RS. (This example uses AES128_CCM with the secret {
0x00, 0x01, 0x02, 0x03, 0x04, 0x05, 0x06, 0x07, 0x08, 0x09, 0x0a,
0x0b, 0x0c, 0x0d, 0x0e, 0x0f } and RS's timestamp { 0x00, 0x2C, 0xD7,
0x7D } as nonce.) Line breaks have been inserted to improve
readability.
The attribute K describes the identity of the key to be used by RS to
decrypt the contents of attribute E. Here, The value "key0" in this
example is used to indicate that the shared session key between RS
and AS(RS) was used for encrypting E.
Gerdes, et al. Expires January 16, 2014 [Page 19]
Internet-Draft DCAF July 2013
{
"E": "rjtolfjyX9q7Emxgsnz+nf0xTQhe1MjzZBRoIEW4vmSVlyJdW4KDgVtW
LyBnQSVX0lmVpxUYbdNuk/5PkCOJBeex0obiEBC1UmKoJfJfjy7bLQhq
k9HuJD7cvjHNOVZtNZf5qrxt7xJSoZFe6j/SJuxGNH/72SPDrdMQeXJI
pX6vCJB698FcRDOXh/ipi9KT8YWeo/ljUMgJc+LI",
"K": "key0",
"V": "zrPOuc6xzr/Pjc+Bz4TOuSDOvM61IM68zq3Ou865Cg=="
}
The decrypted contents of E are depicted below (whitespace has been
added to improve readability). The presence of the attribute V
indicates that the DTLS PSK Transfer is used to convey the session
key (cf. Section 6.1).
"F":{"AI":{"Role":3},
"CI":"2001:db8:ab9:1234:7920:3133:ae5f:87",
"TS":2938749,
"L":3600,
"V":"zrPOuc6xzr/Pjc+Bz4TOuSDOvM61IM68zq3Ou865Cg=="}
Gerdes, et al. Expires January 16, 2014 [Page 20]
Internet-Draft DCAF July 2013
6. DTLS PSK Generation Methods
One goal of the DCAF protocol is to provide for a DTLS PSK shared
between C and RS. AS(RS) and RS MUST negotiate the method for the
DTLS PSK generation.
6.1. DTLS PSK Transfer
The DTLS PSK is generated by AS(RS) and transmitted to C and RS using
a secure channel.
The DTLS PSK transfer method is defined as follows:
o AS(RS) generates the DTLS PSK using an algorithm of its choice
o AS(RS) MUST include a representation of the DTLS PSK in Face and
encrypt it together with all other information in Face with a key
K(AS(RS),RS) it shares with RS. How AS(RS) and RS exchange
K(AS(RS),RS) is not in the scope of this document. AS(RS) and RS
MAY use their preshared key as K(AS(RS),RS).
o AS(RS) MUST include a representation of the DTLS PSK in the
Verifier.
o As AS(RS) and C do not have a shared secret, the Verifier MUST be
transmitted to C using encrypted channels.
o RS MUST decrypt Face using K(AS(RS),RS)
6.2. Distributed Key Derivation
AS(RS) generates a DTLS PSK for C which is transmitted using a secure
channel. RS generates its own version of the DTLS PSK using the
information contained in Face (see also Section 4.1).
The distributed key derivation method is defined as follows:
o AS(RS) and RS both generate the DTLS PSK using the information.
included in Face. They use an HMAC algorithm on Face with a
shared key. The result serves as the DTLS PSK. How AS(RS) and RS
negotiate the used HMAC algorithm is not in the scope of this
document. They MAY however use the HMAC algorithm they use for
their DTLS connection.
o AS(RS) MUST include a representation of the DTLS PSK in the
Verifier.
Gerdes, et al. Expires January 16, 2014 [Page 21]
Internet-Draft DCAF July 2013
o As AS(RS) and C do not have a shared secret, the Verifier MUST be
transmitted to C using encrypted channels.
o AS(RS) MUST NOT include a representation of the DTLS PSK in Face.
o AS(RS) MUST NOT encrypt Face.
Gerdes, et al. Expires January 16, 2014 [Page 22]
Internet-Draft DCAF July 2013
7. Authorization Configuration
For the protocol defined in this document, proper configuration of
AS(RS) is crucial. The principal who owns the resources hosted by RS
(i.e. the Resource Owner) needs to define permissions for the
resources. The data representation of these permissions are not in
the scope of this document.
Gerdes, et al. Expires January 16, 2014 [Page 23]
Internet-Draft DCAF July 2013
8. Trust Relationships
C and RS trust their respective Authorization Servers and vice versa.
How this trust is established, is not in the scope of this document.
It may be achieved by using a bootstrapping mechanism similar to
[bergmann12].
Additionally, AS(RS) and AS(C) already have a trust relationship.
Its establishment is also not in the scope of this document. It
fulfills the following conditions:
1. AS(RS) has means to identify AS(C) (e.g. it has a certificate of
AS(C) or a PKI in which AS(C) is included) and vice versa
2. AS(RS) knows that AS(C) is responsible for C
3. AS(RS) can be sure that AS(C) does not transmit tickets that have
been generated for C to another client
AS(RS) trusts C implicitly because it trusts AS(C). The DCAF
Protocol does not provide any means for AS(RS) to validate that a
resource requests stems from C.
C trusts AS(RS) because AS(C) trusts AS(RS).
AS(C) trusts RS implicitely because it trusts AS(RS)
C implicitely trusts RS because it trusts AS(C) and because RS can
proof that it shares a key with AS(RS).
AS(C) <----------------> AS(RS)
/|\ /|\
| |
\|/ \|/
C ..................... RS
Gerdes, et al. Expires January 16, 2014 [Page 24]
Internet-Draft DCAF July 2013
9. Listing Authorization Server Information in a Resource Directory
CoAP utilizes the Web Linking format [RFC5988] to facilitate
discovery of services in an M2M environment.[RFC6690] defines
specific link parameters that can be used to describe resources to be
listed in a resource directory [I-D.ietf-core-resource-directory].
This section defines a resource type "auth-request" that can be used
by clients to retrieve the request URI for a server's authorization
service. When used with the parameter rt in a web link, "auth-
request" indicates that the corresponding target URI can be used in a
POST message to request authorization for the resource and action
that are described in the request payload.
The Content-Format "application/dcaf+json" with numeric identifier
TBD1 defined in this specification MAY be used to express
authorization requests and their responses.
The following example shows the web link used by AS(C) in this
document to relay incoming Authorization Request messages to AS(RS).
(Whitespace is included only for readability.)
<client-authorize>;rt="auth-request";ct=TBD1
;title="Contact Remote Authorization Server"
The resource directory that hosts the resource descriptions of RS
could list the following description. In this example, the URI "ep/
node138/a/switch2941" is relative to the resource context
"coaps://as-rs.example.com/", i.e. the authorization server AS(RS).
<ep/node138/a/switch2941>;rt="auth-request";ct=TBD1;ep="node138"
;title="Request Client Authorization"
;anchor="coaps://as-rs.example.com/"
Gerdes, et al. Expires January 16, 2014 [Page 25]
Internet-Draft DCAF July 2013
10. Examples
This section gives a number of short examples with message flows for
the initial Unauthorized Resource Request and the subsequent
retrieval of a ticket from AS(RS). The notation here follows the
role conventions defined in Section 1.2.1. The payload format is
encoded as proposed in Section 5. The IP address of AS(RS) is 2001:
DB8::1, the IP address of RS is 2001:DB8::dcaf:1234, and C's IP
address is 2001:DB8::c.
10.1. Access Granted
This example shows an Unauthorized PUT request from C to RS that is
answered with an AS(RS) Information message. C then sends a POST
request to AS(C) with a description of its intended request. AS(C)
forwards this request to AS(RS) using CoAP over a DTLS-secured
channel. The response from AS(RS) contains an access ticket that is
relayed back to AS(C).
C --> RS
PUT a/switch2941 [Mid=1234]
Content-Format: application/senml+json
{e: [{"bv": "1"}]}
C <-- RS
4.01 Unauthorized [Mid=1234]
Content-Format: application/dcaf+json
{"AS": "coaps://[2001:DB8::1]/ep/node138/a/switch2941"}
C --> AS(C)
POST client-authorize [Mid=1235,Token="tok"]
Content-Format: application/dcaf+json
{"AS": "coaps://[2001:DB8::1]/ep/node138/a/switch2941",
"CI": "2001:DB8::c",
"M": [ "PUT" ],
"R": "coaps://[2001:DB8::dcaf:1234]/a/switch2941"
}
AS(C) --> AS(RS) [Mid=23146]
POST ep/node138/a/switch2941
Content-Format: application/dcaf+json
{"AS": "coaps://[2001:DB8::1]/ep/node138/a/switch2941",
"CI": "2001:DB8::c",
"M": [ "PUT" ],
"R": "coaps://[2001:DB8::dcaf:1234]/a/switch2941"
}
AS(C) <-- AS(RS)
Gerdes, et al. Expires January 16, 2014 [Page 26]
Internet-Draft DCAF July 2013
2.05 Content [Mid=23146]
Content-Format: application/dcaf+json
{ "F": { "AI": { "R" : "a/switch2941", "M" : [ "GET", "PUT" ] },
"CI": "2001:DB8::c",
"TS": "2013-07-04T20:17:38.002,
"G": "hmac_sha256"
},
"V": "yYVLYZZ5Nssbn0by3fqel9WK6jHdoYyNej2d/kSuBLw="
}
C <-- AS(C)
2.05 Content [Mid=1235,Token="tok"]
Content-Format: application/dcaf+json
{ "F": { "AI": { "R" : "a/switch2941", "M" : [ "GET", "PUT" ] },
"CI": "2001:DB8::c",
"TS": "2013-07-04T20:17:38.002",
"G": "hmac_sha256"
},
"V": "MR5TMrNngbSEAkFl0akmsdbmzF0gqxGI/d3KjwT8GxI="
}
C --> RS
ClientHello (TLS_PSK_WITH_AES_128_CCM_8)
C <-- RS
ServerHello (TLS_PSK_WITH_AES_128_CCM_8)
ServerHelloDone
C --> RS
ClientKeyExchange
psk_identity='"F":{"AI":{"R":"a/switch2941","M":["GET","PUT"]},
"CI": "2001:DB8::c",
"TS": "2013-07-04T20:17:38.002",
"G": "hmac_sha256"')
(C decodes the contents of V and uses the result as PSK)
ChangeCipherSpec
Finished
(RS calculates PSK from AI, CI, TS and its session key
HMAC_sha256("{\"R\":\"a/switch2941\",\"M\":[\"GET\",\"PUT\"]}"+
"2001:DB8::c"+"2013-07-04T20:17:38.002",
"secret")
= 311e5332b36781b484024165d1a926b1d6e6cc5d20ab1188fdddca8f04fc1b12
)
C <-- RS
ChangeCipherSpec
Gerdes, et al. Expires January 16, 2014 [Page 27]
Internet-Draft DCAF July 2013
Finished
10.2. Access Denied
This example shows a denied Authorization request for the DELETE
operation.
C --> RS
DELETE a/switch2941
C <-- RS
4.01 Unauthorized
Content-Format: application/dcaf+json
{"AS": "coaps://[2001:DB8::1]/ep/node138/a/switch2941"}
C --> AS(C)
POST client-authorize
Content-Format: application/dcaf+json
{"AS": "coaps://[2001:DB8::1]/ep/node138/a/switch2941",
"CI": "2001:DB8::c",
"M": [ "DELETE" ],
"R": "coaps://[2001:DB8::dcaf:1234]/a/switch2941"
}
AS(C) --> AS(RS)
POST ep/node138/a/switch2941
Content-Format: application/dcaf+json
{"AS": "coaps://[2001:DB8::1]/ep/node138/a/switch2941",
"CI": "2001:DB8::c",
"M": [ "DELETE" ],
"R": "coaps://[2001:DB8::dcaf:1234]/a/switch2941"
}
AS(C) <-- AS(RS)
2.05 Content
Content-Format: application/dcaf+json
C <-- AS(C)
2.05 Content
Content-Format: application/dcaf+json
10.3. Access Restricted
This example shows a denied Authorization request for the operations
GET, PUT, and DELETE. AS(RS) grants access for PUT only.
Gerdes, et al. Expires January 16, 2014 [Page 28]
Internet-Draft DCAF July 2013
AS(C) --> AS(RS)
POST ep/node138/a/switch2941
Content-Format: application/dcaf+json
{"AS": "coaps://[2001:DB8::1]/ep/node138/a/switch2941",
"CI": "2001:DB8::c",
"M": [ "GET", "PUT", "DELETE" ],
"R": "coaps://[2001:DB8::dcaf:1234]/a/switch2941"
}
AS(C) <-- AS(RS)
2.05 Content
Content-Format: application/dcaf+json
{ "F": { "AI": { "R" : "a/switch2941", "M" : [ "GET", "PUT" ] },
"CI": "2001:DB8::c",
"TS": "2013-07-04T21:33:11.930",
"G": "hmac_sha256"
},
"V": "NZ8Q3o8P4eHOzkoscaUpoRvrn5d74Cscw/aXAiNmC/k="
}
Gerdes, et al. Expires January 16, 2014 [Page 29]
Internet-Draft DCAF July 2013
11. Security Considerations
As this protocol builds on transitive trust between authorization
servers as mentioned in Section 8, AS(RS) has no means to validate
that a resource request originates from C. It has to trust AS(C) that
it is responsible for C and that it does not give authorization
tickets meant for C to another client nor disclose the contained
session key.
The Authentication Server also constitutes a single point of failure.
If the Authentication Server fails, the resources on all Resource
Servers it is responsible for cannot be accessed any more. Thus, it
is crucial for large networks to use Authorization Servers in a
failsafe setup.
Gerdes, et al. Expires January 16, 2014 [Page 30]
Internet-Draft DCAF July 2013
12. IANA Considerations
The following registrations are done following the procedure
specified in [RFC6838].
Note to RFC Editor: Please replace all occurrences of "[RFC-XXXX]"
with the RFC number of this specification.
12.1. dcaf+json Media Type Registration
Type name: application
Subtype name: dcaf+json
Required parameters: none
Optional parameters: none
Encoding considerations: Must be encoded as using a subset of the
encoding allowed in [RFC4627]. Specifically, only the primitive data
types String and Number are allowed. The type Number is restricted
to int (i.e., no negative numbers, fractions or exponents are
allowed). Encoding MUST be UTF-8. These restrictions simplify
implementations on devices that have very limited memory capacity.
Security considerations: TBD
Interoperability considerations: TBD
Published specification: [RFC-XXXX]
Applications that use this media type: TBD
Additional information:
Magic number(s): none
File extension(s): dcaf
Macintosh file type code(s): none
Person & email address to contact for further information: TBD
Intended usage: COMMON
Restrictions on usage: None
Author: TBD
Gerdes, et al. Expires January 16, 2014 [Page 31]
Internet-Draft DCAF July 2013
Change controller: IESG
12.2. CoAP Content Format Registration
This document specifies a new media type application/dcaf+json (cf.
Section 12.1). For use with CoAP, a numeric Content-Format
identifier is to be registered in the "CoAP Content-Formats" sub-
registry within the "CoRE Parameters" registry.
Note to RFC Editor: Please replace all occurrences of "RFC-XXXX" with
the RFC number of this specification.
+-----------------------+----------+------+------------+
| Media type | Encoding | Id. | Reference |
+-----------------------+----------+------+------------+
| application/dcaf+json | utf-8 | TBD1 | [RFC-XXXX] |
+-----------------------+----------+------+------------+
Gerdes, et al. Expires January 16, 2014 [Page 32]
Internet-Draft DCAF July 2013
13. References
13.1. Normative References
[I-D.ietf-core-coap]
Shelby, Z., Hartke, K., and C. Bormann, "Constrained
Application Protocol (CoAP)", draft-ietf-core-coap-18
(work in progress), June 2013.
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
Requirement Levels", BCP 14, RFC 2119, March 1997.
[RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform
Resource Identifier (URI): Generic Syntax", STD 66,
RFC 3986, January 2005.
[RFC4279] Eronen, P. and H. Tschofenig, "Pre-Shared Key Ciphersuites
for Transport Layer Security (TLS)", RFC 4279,
December 2005.
[RFC4648] Josefsson, S., "The Base16, Base32, and Base64 Data
Encodings", RFC 4648, October 2006.
[RFC6347] Rescorla, E. and N. Modadugu, "Datagram Transport Layer
Security Version 1.2", RFC 6347, January 2012.
[RFC6838] Freed, N., Klensin, J., and T. Hansen, "Media Type
Specifications and Registration Procedures", BCP 13,
RFC 6838, January 2013.
13.2. Informative References
[I-D.ietf-core-block]
Bormann, C. and Z. Shelby, "Blockwise transfers in CoAP",
draft-ietf-core-block-12 (work in progress), June 2013.
[I-D.ietf-core-observe]
Hartke, K., "Observing Resources in CoAP",
draft-ietf-core-observe-09 (work in progress), July 2013.
[I-D.ietf-core-resource-directory]
Shelby, Z., Krco, S., and C. Bormann, "CoRE Resource
Directory", draft-ietf-core-resource-directory-00 (work in
progress), June 2013.
[RFC4627] Crockford, D., "The application/json Media Type for
JavaScript Object Notation (JSON)", RFC 4627, July 2006.
Gerdes, et al. Expires January 16, 2014 [Page 33]
Internet-Draft DCAF July 2013
[RFC5988] Nottingham, M., "Web Linking", RFC 5988, October 2010.
[RFC6655] McGrew, D. and D. Bailey, "AES-CCM Cipher Suites for
Transport Layer Security (TLS)", RFC 6655, July 2012.
[RFC6690] Shelby, Z., "Constrained RESTful Environments (CoRE) Link
Format", RFC 6690, August 2012.
[bergmann12]
Bergmann, O., Gerdes, S., Schaefer, S., Junge, F., and C.
Bormann, "Secure Bootstrapping of Nodes in a CoAP
Network", IEEE Wireless Communications and Networking
Conference Workshops (WCNCW), April 2012.
Gerdes, et al. Expires January 16, 2014 [Page 34]
Internet-Draft DCAF July 2013
Authors' Addresses
Stefanie Gerdes
Universitaet Bremen TZI
Postfach 330440
Bremen D-28359
Germany
Phone: +49-421-218-63906
Email: gerdes@tzi.org
Olaf Bergmann
Universitaet Bremen TZI
Postfach 330440
Bremen D-28359
Germany
Phone: +49-421-218-63904
Email: bergmann@tzi.org
Carsten Bormann
Universitaet Bremen TZI
Postfach 330440
Bremen D-28359
Germany
Phone: +49-421-218-63921
Email: cabo@tzi.org
Gerdes, et al. Expires January 16, 2014 [Page 35]