One document matched: draft-gerdes-ace-dcaf-authorize-03.xml
<?xml version="1.0" encoding="utf-8"?>
<?xml-stylesheet type="text/xsl" href="rfc2629.xslt" ?>
<!-- generated by https://github.com/cabo/kramdown-rfc2629 version 1.0.28 -->
<!DOCTYPE rfc SYSTEM "rfc2629.dtd" [
<!ENTITY SELF "[RFC-XXXX]">
]>
<?rfc toc="yes"?>
<?rfc sortrefs="yes"?>
<?rfc symrefs="yes"?>
<rfc ipr="trust200902" docName="draft-gerdes-ace-dcaf-authorize-03" category="std">
<front>
<title abbrev="DCAF">Delegated CoAP Authentication and Authorization Framework (DCAF)</title>
<author initials="S." surname="Gerdes" fullname="Stefanie Gerdes">
<organization>Universität Bremen TZI</organization>
<address>
<postal>
<street>Postfach 330440</street>
<city>Bremen</city>
<code>D-28359</code>
<country>Germany</country>
</postal>
<phone>+49-421-218-63906</phone>
<email>gerdes@tzi.org</email>
</address>
</author>
<author initials="O." surname="Bergmann" fullname="Olaf Bergmann">
<organization>Universität Bremen TZI</organization>
<address>
<postal>
<street>Postfach 330440</street>
<city>Bremen</city>
<code>D-28359</code>
<country>Germany</country>
</postal>
<phone>+49-421-218-63904</phone>
<email>bergmann@tzi.org</email>
</address>
</author>
<author initials="C." surname="Bormann" fullname="Carsten Bormann">
<organization>Universität Bremen TZI</organization>
<address>
<postal>
<street>Postfach 330440</street>
<city>Bremen</city>
<code>D-28359</code>
<country>Germany</country>
</postal>
<phone>+49-421-218-63921</phone>
<email>cabo@tzi.org</email>
</address>
</author>
<date year="2015" month="September" day="10"/>
<area>Applications</area>
<workgroup>ACE Working Group</workgroup>
<keyword>Internet-Draft</keyword>
<abstract>
<t>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 severe limitations regarding
processing power and memory.</t>
</abstract>
</front>
<middle>
<section anchor="introduction" title="Introduction">
<t>The Constrained Application Protocol (CoAP) <xref target="RFC7252"/> 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 system resources such as memory, stable storage (such as 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 stable storage severely limits
the number of keys the system can store. Moreover, CoAP has no mechanism
for authorization.</t>
<t><xref target="I-D.gerdes-ace-actors"/> describes an architecture that is
designed to help constrained nodes with authorization-related tasks by
introducing less-constrained nodes. These Authorization Managers
perform complex security tasks for their nodes such as managing keys
for numerous devices, and enable the constrained nodes to enforce the
authorization policies of their principals.</t>
<t>DCAF uses access tokens to implement this architecture.
A device that
wants to access an item of interest on a constrained node first has to gain
permission in the form of a token from the node’s Authorization
Manager.</t>
<t>As fine-grained authorization is not always needed on constrained
devices, DCAF supports an implicit authorization mode where no
authorization information is exchanged.</t>
<!-- Note: DCAF's goal is to provide access control to a resource of a
constrained device. If the access to a resource is restricted somehow,
either by granting access rights to all authenticated clients or by a
more sophisticated authorization approach, it is necessary to be able
to doubtlessly verify the client's claim. To ensure the security of the
authorization information it is beneficial to intertwine
authentication and authorization mechanism. -->
<t>The main goals of DCAF are the setup of a Datagram Transport Layer
Security (DTLS) <xref target="RFC6347"/> channel with symmetric pre-shared
keys (PSK) <xref target="RFC4279"/> between two nodes and to
securely transmit authorization tickets.</t>
<section anchor="features" title="Features">
<t><list style="symbols">
<t>Utilize DTLS communication with pre-shared keys.</t>
<t>Authenticated exchange of authorization information.</t>
<t>Simplified authentication on constrained nodes by handing the more
sophisticated authentication over to less-constrained devices.</t>
<t>Support of secure constrained device to constrained device communication.</t>
<t>Authorization policies of the principals of both participating
parties are ensured.</t>
<t>Simplified authorization mechanism for cases where implicit
authorization is sufficient.</t>
<t>Using only symmetric encryption on constrained nodes.</t>
</list></t>
<!-- Kerberos: RFC4120: -->
</section>
<section anchor="terminology" title="Terminology">
<t>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 <xref target="RFC2119"/>.</t>
<t>Readers are expected to be familiar with the terms and concepts defined in
<xref target="I-D.gerdes-ace-actors"/>.</t>
<section anchor="actors" title="Actors">
<t><list style="hanging">
<t hangText='Server (S):'>
An endpoint that hosts and represents a CoAP resource.</t>
<t hangText='Client (C):'>
An endpoint that attempts to access a CoAP resource on the Server.</t>
<t hangText='Server Authorization Manager (SAM):'>
An entity that prepares and endorses authentication and
authorization data for a Server.</t>
<t hangText='Client Authorization Manager (CAM):'>
An entity that prepares and endorses authentication and
authorization data for a Client.</t>
<t hangText='Authorization Manager (AM):'>
An entity that is either a SAM or a CAM.</t>
<t hangText='Client Overseeing Principal (COP):'>
The principal that is in charge of the Client and controls permissions
concerning authorized representations of a CoAP resource.</t>
<t hangText='Resource Overseeing Principal (ROP):'>
The principal that is in charge of the CoAP resource and controls
its access permissions.</t>
</list></t>
</section>
<section anchor="other-terms" title="Other Terms">
<t><list style="hanging">
<t hangText='Resource:'>
A CoAP resource.</t>
<t hangText='Authorization information:'>
Contains all information needed by S to
decide if C is privileged to access a resource in a specific way.</t>
<t hangText='Authentication information:'>
Contains all information needed by S to
decide if the entity in possession of a certain key is verified by SAM.</t>
<t hangText='Access information:'>
Contains authentication information and, if
necessary, authorization information.</t>
<t hangText='Access ticket:'>
Contains the authentication and, if necessary, the
authorization information needed to access a resource. A Ticket consists
of the Ticket Face and the Client Information. The access ticket is a
representation of the access information.</t>
<t hangText='Ticket Face:'>
The part of the ticket which is generated for the
Server. It contains the authorization information and all
information needed by the Server to verify that it was
granted by SAM.</t>
<t hangText='Client Information (CI):'>
The part of the ticket which is generated for the Client. It
contains the Verifier and optionally may contain authorization
information that represent COP’s authorization policies for C.</t>
<t hangText='Verifier:'>
It enables the client to verify that it is communicating with
an appropriate S.</t>
<t hangText='Explicit authorization:'>
SAM informs the S in detail which privileges are granted to the
Client.</t>
<t hangText='Implicit authorization:'>
SAM authenticates the Client for the Server without
specifying the privileges in detail. This can be used for binary or
unrestricted authorization (cf section 4 of <xref target="I-D.gerdes-ace-actors"/>).</t>
</list></t>
<!-- TODO: It might be useful if S can have own authorization
information. Maybe a simple set of fallback-information when no AS is
available or more sophisticated ai if S is not quite so
constrained. -->
</section>
</section>
</section>
<section anchor="system-overview" title="System Overview">
<t>Within the DCAF Architecture each Server (S) has a Server
Authorization Manger (SAM) which conducts the authentication and
authorization for S. S and SAM 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.</t>
<t>To gain access to a specific resource on a S, a
Client (C) has to request an access ticket from the
SAM serving S either directly or, if it is a constrained
device, using its Client Authorization Manager (CAM).
In the following, we always discuss the CAM role separately, even if that is
co-located within a (more powerful) C (see section <xref target="combined"/> for
details about co-located actors).</t>
<t>CAM decides if S is an authorized source for R according to the
policies set by COP and in this case transmits the request to SAM. If
SAM decides that C is allowed to access the resource according to the
policies set by ROP, it generates a
DTLS pre-shared key (PSK) for the communication between C and S and
wraps it into an access ticket. For explicit access control,
SAM adds the detailed access permissions to the ticket in a way that CAM and S
can interpret. CAM checks if the permissions in the access ticket
comply with COP’s authorization policies for C, and if this is the case
sends it to C.
After C
presented the ticket to S, C and S can communicate securely.</t>
<t>To be able to provide for the authentication and authorization
services, an Authorization Manager has to fulfill several
requirements:</t>
<t><list style="symbols">
<t>AM must have enough stable storage (such as disk space) to store
the necessary number of credentials (matching the number of Clients
and Servers).</t>
<t>AM must possess means for user interaction, for example directly
or indirectly connected input/output devices such as keyboard and
display, to allow for configuration of authorization information by
the respective Principal.</t>
<t>AM must have enough processing power to handle the authorization
requests for all constrained devices it is responsible for.</t>
</list></t>
</section>
<section anchor="protocol" title="Protocol">
<t>The DCAF protocol comprises three parts:</t>
<t><list style="numbers">
<t>transfer of authentication and, if necessary, authorization
information between C and S;</t>
<t>transfer of access requests and the
respective ticket grants between C and CAM; and</t>
<t>transfer of access requests and the
respective ticket grants between SAM and CAM.</t>
</list></t>
<!-- In most network topologies, at least two of the three sub-protocols -->
<!-- will be present, depending on the actual roles that each device -->
<!-- impersonates. In simple scenarios, AS(C) and AS(RS) might be -->
<!-- identical, i.e. C and RS use the same authorization server. In this -->
<!-- case, no AS-to-AS communication is required. Moreover, if C is capable -->
<!-- of mutual authentication with AS(RS), it could act as AS(C). -->
<section anchor="overview" title="Overview">
<t>In <xref target="protocol-overview"/>, a DCAF protocol flow is depicted (messages
in square brackets are optional):</t>
<figure title="Protocol Overview" anchor="protocol-overview"><artwork><![CDATA[
CAM C S SAM
| <== DTLS chan. ==> | | <== DTLS chan. ==> |
| | [Resource Req.-->] | |
| | | |
| | [<-- SAM Info.] | |
| | | |
| <-- Access Req. | | |
| | | |
| <==== TLS/DTLS channel (CAM/SAM Mutual Authentication) ====> |
| | | |
| Ticket Request ------------------------------------------> |
| | | |
| <------------------------------------------ Ticket Grant |
| | | |
| Ticket Transf. --> | | |
| | | |
| | <== DTLS chan. ==> | |
| | Auth. Res. Req. -> | |
]]></artwork></figure>
<t>To determine the SAM in charge of a resource hosted at the S, C MAY
send an initial Unauthorized Resource Request message to S. S then
denies the request and sends the address of its SAM back to C.</t>
<t>Instead of the initial Unauthorized Resource Request message, C MAY
look up the desired resource in a
resource directory (cf. <xref target="I-D.ietf-core-resource-directory"/>) that
lists S’s resources as discussed in <xref target="rd"/>.</t>
<t>Once C knows SAM’s address, it can send a request for authorization to
SAM using its own CAM. CAM and SAM authenticate each other and each
determine if the request is to be authorized. If it is, SAM
generates an access ticket for C. The ticket contains keying material
for the establishment of a secure channel and, if necessary, a
representation of the permissions C has for the resource.
C keeps one part of the access ticket and presents the other part
to S to prove its right to access. With their respective
parts of the ticket, C and S are able to establish
a secure channel.</t>
<t>The following sections specify how CoAP is used to interchange
access-related data between S and SAM so that SAM can
provide C and S with sufficient information to establish a secure
channel, and simultaneously convey
authorization information specific for this communication relationship
to S.</t>
<t><list style="hanging">
<t hangText='Note:'>
Special implementation considerations apply when one single entity
takes the role of more than one actors. <xref target="combined"/> gives
additional advice on some of these usage scenarios.</t>
</list></t>
<t>This document uses Concise Binary Object Representation (CBOR, <xref target="RFC7049"/>) to
express authorization information as set of attributes passed in CoAP
payloads. Notation and encoding options are discussed in
<xref target="payload-format"/>. A formal specification of the DCAF message format
is given in <xref target="cddl"/>.</t>
</section>
<section anchor="rreq" title="Unauthorized Resource Request Message">
<t>The optional Unauthorized Resource Request message is a request for a resource
hosted by S for which no proper authorization is granted. S MUST
treat any CoAP request as Unauthorized Resource Request message when any of the
following holds:</t>
<t><list style="symbols">
<t>The request has been received on an insecure channel.</t>
<t>S has no valid access ticket for the sender of the
request regarding the requested action on that resource.</t>
<t>S has a valid access ticket for the sender of the
request, but this does not allow the requested action on the requested
resource.</t>
</list></t>
<t>Note: These conditions ensure that S can handle requests autonomously
once access was granted and a secure channel has been established
between C and S.</t>
<t>Unauthorized Resource Request messages MUST be denied with a client error
response. In this response, the Server MUST provide
proper SAM Information to enable the Client to request an
access ticket from S’s SAM as described in <xref target="sam-info"/>.</t>
<t>The response code MUST be 4.01 (Unauthorized) in case the sender of
the Unauthorized Resource Request message is not authenticated, or if
S has no valid access ticket for C. If S has an access ticket for C
but not for the resource that C has requested, S
MUST reject the request with a 4.03 (Forbidden). If S has
an access ticket for C but it does not cover the action C
requested on the resource, S MUST reject the request with a 4.05
(Method Not Allowed).</t>
<t><list style="hanging">
<t hangText='Note:'>
The use of the response codes 4.03 and 4.05 is intended to prevent
infinite loops where a dumb Client optimistically tries to access
a requested resource with any access token received from the SAM.
As malicious clients could pretend to be C to determine C’s
privileges, these detailed response codes must be used only when a
certain level of security is already available which can be achieved
only when the Client is authenticated.</t>
</list></t>
</section>
<section anchor="sam-info" title="SAM Information Message">
<t>The SAM Information Message is sent by S as a response to an
Unauthorized Resource Request message (see <xref target="rreq"/>) to point the sender of the
Unauthorized Resource Request message to S’s SAM. The SAM
information is a set of attributes containing an absolute URI (see
Section 4.3 of <xref target="RFC3986"/>) that specifies the SAM in charge of S.</t>
<t>An optional field A lists the different content formats that are
supported by S.</t>
<t>The message MAY also contain a timestamp generated by S. <!-- (RS wants either his own timestamp or a timestamp generated by AS(RS) back in the end to make sure the information it gets is fresh)--></t>
<t><xref target="sam-info-payload"/> shows an example for an SAM Information message
payload using CBOR diagnostic notation. (Refer to <xref target="payload-format"/> for a detailed
description of the available attributes and their semantics.)</t>
<figure title="SAM Information Payload Example" anchor="sam-info-payload"><artwork><![CDATA[
4.01 Unauthorized
Content-Format: application/dcaf+cbor
{SAM: "coaps://sam.example.com/authorize", TS: 168537,
A: [ TBD1, ct_cose_msg ] }
]]></artwork></figure>
<t>In this example, the attribute SAM points the receiver of this message
to the URI “coaps://sam.example.com/authorize” to request access
permissions. The originator of the SAM Information payload
(i.e. S) uses a local clock that is loosely synchronized with a time
scale common between S and SAM (e.g., 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 <xref target="face"/> for more details concerning the usage of time stamps to
ensure freshness of access tickets.</t>
<t>The content formats accepted by S are TBD1 (identifying
‘application/dcaf+cbor’ as defined in this document), and
‘application/cose+cbor’ defined in <xref target="I-D.ietf-cose-msg"/>.</t>
<t><list style="hanging">
<t hangText='Editorial note:'>
ct_cose_msg is to be replaced with the numeric value assigned for
‘application/cose+cbor’.</t>
</list></t>
<t>The examples in this document are written in CBOR diagnostic notation
to improve readability. <xref target="sam-info-cbor"/> illustrates the binary
encoding of the message payload shown in <xref target="sam-info-payload"/>.</t>
<figure title="SAM Information Payload Example encoded in CBOR" anchor="sam-info-cbor"><artwork><![CDATA[
a2 # map(2)
00 # unsigned(0) (=SAM)
78 21 # text(33)
636f6170733a2f2f73616d2e6578
616d706c652e636f6d2f617574686f72
697a65 # "coaps://sam.example.com/authorize"
05 # unsigned(5) (=TS)
1a 00029259 # unsigned(168537)
0a # unsigned(10) (=A)
82 # array(2)
19 03e6 # unsigned(998) (=dcaf+cbor)
19 03e7 # unsigned(999) (=cose+cbor)
]]></artwork></figure>
<section anchor="piggyback" title="Piggybacked Protected Content">
<t>For some use cases (such as sleepy nodes) it might be necessary to
store sensor data on a server that might not belong to the same
security domain. A client can retrieve the data from that server. To
be able to achieve the security objectives of the principles the data
must be protected properly.</t>
<t>The server that hosts the stored data may respond to GET requests for
this particular resource with a SAM Information message that contains
the protected data as piggybacked content in addition to the URI of the
authorization manager that is responsible for the protected data.
<!-- SAM URI could be retrieved from RD --></t>
<t>Once a requesting client has received the SAM Information Message with
piggybacked content, it needs to request authorization for accessing
the protected data. To do so, it constructs an Access Request as
defined in <xref target="access-request"/>. If access to the protected data
is granted, the requesting client will be provided with cryptographic
material to verify the integrity and authenticity of the piggybacked content and
decrypt the protected data in case it is encrypted.</t>
<!-- FIXME: key derivation?
S can derive a key for C and return an encrypted object.
When C is authorized, SAM derives the same key using
crypto material that it shares with S.
-->
</section>
</section>
<section anchor="access-request" title="Access Request">
<!-- FIXME: if the client gets SAM information messages repeatedly, it
should not resend Access Requests -->
<t>To retrieve an access ticket for the resource that C wants to
access, C sends an Access Request to its CAM. The Access Request is
constructed as follows:</t>
<t><list style="numbers">
<t>The request method is POST.</t>
<t>The request URI is set as described below.</t>
<t>The message payload contains a data structure that describes the
action and resource for which C requests an access ticket.</t>
</list></t>
<t>The request URI identifies a resource at CAM for handling
authorization requests from C. The URI SHOULD be announced by CAM in
its resource directory as described in <xref target="rd"/>.</t>
<t><list style="hanging">
<t hangText='Note:'>
Where capacity limitations of C do not allow for resource directory
lookups, the request URI in Access Requests could be
hard-coded during provisioning or set in a specific device
configuration profile.</t>
</list></t>
<t>The message payload is constructed from the SAM information
that S has returned in its SAM Information message (see
<xref target="sam-info"/>) and information that C provides to describe its intended
request(s). The
Access Request MUST contain the following attributes:</t>
<t><list style="numbers">
<t>Contact information for the SAM to use.
<!-- 1. An identifier of C that can be used by AS to distinguish Access Requests from different Clients. --></t>
<t>An absolute URI of the resource that C wants to access.</t>
<t>The actions that C wants to perform on the resource.
<!-- Can we omit the actions if they are not needed? Maybe
not, C cannot know if S needs them or not. They would have to
negotiate that --></t>
<t>Any time stamp generated by S.</t>
</list></t>
<t>An example Access Request from C to CAM is depicted in
<xref target="authorization-message-example"/>. (Refer to <xref target="payload-format"/> for a detailed
description of the available attributes and their semantics.)</t>
<figure title="Access Request Message Example" anchor="authorization-message-example"><artwork><![CDATA[
POST client-authorize
Content-Format: application/dcaf+cbor
{
SAM: "coaps://sam.example.com/authorize",
SAI: ["coaps://temp451.example.com/s/tempC", 5],
TS: 168537
}
]]></artwork></figure>
<t>The example shows an Access Request message payload for the resource
“/s/tempC” on the Server “temp451.example.com”. Requested operations in
attribute SAI are GET and PUT.</t>
<t>The attributes SAM (that denotes the Server Authorization Manager to use) and
TS (a nonce generated by S) are taken from the SAM Information
message from S.</t>
<t>The response to an Authorization Request is delivered by CAM back to
C in a Ticket Transfer message.</t>
</section>
<section anchor="ticket-req" title="Ticket Request Message">
<!-- FIXME: CAM should check that C does not request the same
authorization policies repeatedly in short intervals. Since CAM is
responsible for C and C should not be bothered to store a lot of
state, CAM should watch over C's resources -->
<t>When CAM receives an Access Request message from C and COP specified
authorization policies for C, CAM MUST check if the requested actions
are allowed according to these policies. If this is not the case, CAM
MUST send a 4.03 response.</t>
<t>If no authorization policies were specified or the requested action is
allowed according to the authorization policies, CAM either returns a
cached response or attempts to create a Ticket Request message.</t>
<t>CAM MAY return a cached response if it is known to be fresh according
to Max-Age. CAM SHOULD NOT return a cached response if it expires in
less than a minute.</t>
<t>If CAM does not send a cached response, it
checks whether the request payload is of type “application/dcaf+cbor
and contains at least the fields SAM and SAI. CAM MUST respond
with 4.00 (Bad Request) if the type is “application/dcaf+cbor and any
of these fields is missing or does not conform to the format described
in <xref target="payload-format"/>. Content formats other than
application/dcaf+cbor are out of scope of this specification.</t>
<t>If the payload is correct, CAM creates a Ticket Request message
from the Access Request received from C as follows:</t>
<t><list style="numbers">
<t>The destination of the Ticket Request message is derived from the
authority information in the URI contained in field “SAM” of the
Access Request message payload.</t>
<t>The request method is POST.</t>
<t>The request URI is constructed from the SAM field received in the
Access Request message payload.</t>
<t>The payload is copied from the Access Request sent by C.</t>
<t>A label that describes the Client is added to the payload</t>
</list></t>
<t>To send the Ticket Request message to SAM
a secure channel between CAM
and SAM MUST be used. Depending on the URI scheme used in the
SAM field of the Access Request message payload (the less-constrained
devices CAM and SAM do not necessarily use CoAP to communicate with each
other), this could be,
e.g., a DTLS channel (for “coaps”) or a TLS connection (for
“https”). CAM and SAM MUST be able to mutually authenticate each other,
e.g. based on a public key infrastructure. (Refer to <xref target="trust"/> for a detailed
discussion of the trust relationship between Client Authorization
Managers and Server Authorization Managers.)</t>
</section>
<section anchor="ticket-grant-message" title="Ticket Grant Message">
<t>When SAM has received a Ticket Request message it has to evaluate
the access request information contained therein. First, it
checks whether the request payload is of type “application/dcaf+cbor”
and contains at least the fields SAM and SAI. SAM MUST respond
with 4.00 (Bad Request) for CoAP (or 400 for HTTP) if the type is “application/dcaf+cbor” and any
of these fields is missing or does not conform to the format described
in <xref target="payload-format"/>.
<!--
FIXME: Don't we need a more general description here? We want to be able to
support other methods beside json. AS must check if the request
message contains all mandatory information depicted in {{ticket-req}}
(i.e. the contact information for AS (is it even meant for this AS?,
an identifier of C, the absolute URI of the resource and the actions C
wants to perform on the resource.
--></t>
<t>SAM decides whether or not access is granted to the requested
resource and then creates a Ticket Grant message that reflects the
result.
To grant access to the requested resource, SAM creates an
access ticket comprised of a Face and the Client Information as described in
<xref target="face"/>.</t>
<t>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 contains the
Ticket Face, the Client Information, which at this point only consists
of the Verifier and the Session Key Generation Method.</t>
<t>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 <xref target="RFC7252"/> to facilitate
ticket retrieval when C has crashed and wants to recover the DTLS
session with S.
<!-- Check that this stuff actually is cache-able. --></t>
<t>SAM SHOULD set Max-Age according to the ticket lifetime in its response
(Ticket Grant Message).</t>
<t><xref target="ticket-grant"/> shows an example Ticket Grant message using CoAP. The
Face/Verifier information is transferred as a CBOR data structure as
specified in <xref target="payload-format"/>. The Max-Age option tells the
receiving CAM how long this ticket will be valid.</t>
<!-- msg1 -->
<figure title="Example Ticket Grant Message" anchor="ticket-grant"><artwork><![CDATA[
2.05 Content
Content-Format: application/dcaf+cbor
Max-Age: 86400
{ F: {
SAI: [ "/s/tempC", 7 ],
TS: 0("2013-07-10T10:04:12.391"),
L: 86400,
G: hmac_sha256
},
V: h'f89947160c73601c7a65cb5e08812026
6d0f0565160e3ff7d3907441cdf44cc9'
}
]]></artwork></figure>
<t>A Ticket Grant message that declines any operation on the requested
resource is illustrated in <xref target="ticket-reject"/>. As no ticket needs
to be issued, an empty payload is included with the response.</t>
<figure title="Example Ticket Grant Message With Reject" anchor="ticket-reject"><artwork><![CDATA[
2.05 Content
Content-Format: application/dcaf+cbor
]]></artwork></figure>
</section>
<section anchor="ticket-transfer" title="Ticket Transfer Message">
<t>A Ticket Transfer message delivers the access information
sent by SAM in a Ticket Grant message to the requesting client C.
The Ticket Transfer message is the response to
the Access Request message sent from C to CAM
and includes any access information from SAM contained in the
Ticket Grant message.</t>
<t>The Authorization Information provided by SAM in the Ticket Grant
Message may grant more permissions than C has requested. The
authorization policies of COP and ROP may differ: COP might want restrict
the resources C is allowed to access, and the actions that C is allowed
to perform on the resource.</t>
<t>If CAM must ensure
authorization policies COP configured , CAM MUST add Authorization
Information for C (CAI) to the CI. Since C and CAM use a DTLS
channel for communication, the autorization information does not need
to be encrypted.</t>
<t>CAM includes the Face and Verifier sent by SAM in the Ticket Transfer
message. CAM MUST NOT include any other information SAM provided. In
particular, CAM MUST NOT include any CAI information provided by SAM.</t>
<t><xref target="fig:ticket-transfer"/> shows an example Ticket Transfer message that
conveys the permissions
for actions GET, POST, PUT (but not DELETE) on the resource “/s/tempC”
in field SAI. As CAM only wants to permit outbound GET requests, it
restricts C’s permissions in the field CAI accordingly.</t>
<figure title="Example Ticket Transfer Message" anchor="fig:ticket-transfer"><artwork><![CDATA[
2.05 Content
Content-Format: application/dcaf+cbor
Max-Age: 86400
{ F: {
SAI: [ "/s/tempC", 7 ],
TS: 0("2013-07-10T10:04:12.391"),
L: 86400,
G: hmac_sha256
},
V: h'f89947160c73601c7a65cb5e08812026
6d0f0565160e3ff7d3907441cdf44cc9'
CAI: [ "/s/tempC", 1 ],
TS: 0("2013-07-10T10:04:12.855"),
L: 86400
}
]]></artwork></figure>
</section>
<section anchor="dtls-channel" title="DTLS Channel Setup Between C and S">
<t>Using the information contained in a positive response to its
Access Request (i.e. a Ticket Transfer message that contains
a Face and a Client Information), C can initiate establishment of a new DTLS
channel with S. To use DTLS with pre-shared keys, C follows the PSK
key exchange algorithm specified in Section 2 of <xref target="RFC4279"/>, with the
following additional requirements:</t>
<t><list style="numbers">
<t>C sets the psk_identity field of the ClientKeyExchange message
to the ticket Face received in the Ticket Transfer message.</t>
<t>C uses the ticket Verifier as PSK when constructing the premaster
secret.</t>
</list></t>
<t>Note1: As S cannot provide C with a meaningful PSK identity hint in
response to C’s ClientHello message, S SHOULD NOT send a
ServerKeyExchange message.</t>
<t>Note2: According to <xref target="RFC7252"/>, CoAP implementations MUST
support the ciphersuite TLS_PSK_WITH_AES_128_CCM_8
<xref target="RFC6655"/>. C is therefore expected to offer at least this
ciphersuite to S.</t>
<t>Note3: The ticket is constructed by SAM such that S can derive the
authorization information as well as the PSK (refer to
<xref target="key-generation"/> for details).</t>
</section>
<section anchor="authorized-rreq" title="Authorized Resource Request Message">
<t>If the Client Information in the Ticket Transfer message contains CAI,
C MUST ensure that it only sends requests that according to them are
allowed. C therefore MUST check CAI, L and T before every request. If
CAI is no longer valid according to L, C MUST terminate the DTLS
connection with S and re-request the CAI from CAM using an Access
Request Message.</t>
<!-- FIXME: C MAY re-request the CAI from CAM earlier using a Ticket
Request Message. CAM can than use a cached ticket and add new CAI. We
could also use observe for that -->
<t>On the Server side, successful establishment of the DTLS
channel between C and S ties the
SAM authorization information contained in the psk_identity field to this
channel. Any request that S receives on this channel is checked
against these authorization rules. Incoming CoAP requests that are not
Authorized Resource Requests MUST be rejected by S with 4.01
response as described in <xref target="rreq"/>.</t>
<t>S SHOULD treat an incoming CoAP request as Authorized Resource
Request if the following holds:</t>
<t><list style="numbers">
<t>The message was received on a secure channel that has been
established using the procedure defined in <xref target="dtls-channel"/>.</t>
<t>The authorization information tied to the secure channel is valid.</t>
<t>The request is destined for S.</t>
<t>The resource URI specified in the request is covered by the
authorization information.</t>
<t>The request method is an authorized action on the resource with
respect to the authorization information.</t>
</list></t>
<t>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. Implicit authorization also provides access rights
to authenticated clients for all actions on all resources that S
offers. 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 <xref target="I-D.ietf-core-block"/> or refreshing
observe-relationships <xref target="I-D.ietf-core-observe"/>) but also for requests
to distinct resources.</t>
<t>Incoming CoAP requests received on a secure channel according to the
procedure defined in <xref target="dtls-channel"/> MUST be rejected</t>
<t><list style="numbers">
<t>with response code 4.03 (Forbidden) when the resource URI specified
in the request is not covered by the authorization information, and</t>
<t>with response code 4.05 (Method Not Allowed) when the resource URI
specified in the request covered by the authorization information but
not the requested action.</t>
</list></t>
<t>Since SAM may limit the set of requested actions in its Ticket Grant
message, C cannot know a priori if an Authorized Resource Request
will succeed.</t>
</section>
<section anchor="update" title="Dynamic Update of Authorization Information">
<t>Once a security association exists between a Client and a Resource
Server, the Client can update the Authorization Information stored at
the Server at any time. To do so, the Client creates a new
Access Request for the intended action on the respective resource and
sends this request to its CAM which checks and relays this
request to the Server’s SAM as described in
<xref target="access-request"/>.</t>
<t><list style="hanging">
<t hangText='Note:'>
Requesting a new Access Ticket also can be a Client’s reaction on a
4.03 or 4.05 error that it has received in response to an Authorized
Resource Request.</t>
</list></t>
<t><xref target="update-overview"/> depicts the message flow where C requests a new
Access Tickets after a security association between C and S has been
established using this protocol.</t>
<figure title="Overview of Dynamic Update Operation" anchor="update-overview"><artwork><![CDATA[
CAM C S SAM
| <== DTLS chan. ==> | <== DTLS chan. ==> | <== DTLS chan. ==> |
| | | |
| | [Unauth. R. Req->] | |
| |[<- 4.0x+SAM Info.] | |
| | | |
| <-- Access Req. | | |
| | | |
| <==== TLS/DTLS channel (CAM/SAM Mutual Authentication) ====> |
| | | |
| Ticket Request ------------------------------------------> |
| | | |
| <------------------------------------------ Ticket Grant |
| | | |
| Ticket Transf. --> | | |
| | | |
| | <== Update SAI ==> | |
]]></artwork></figure>
<t>Processing the Ticket Request is done at the SAM as
specified in <xref target="ticket-grant-message"/>, i.e. the SAM checks
whether or not the requested operation is permitted by the Resource
Principal’s policy, and then return a Ticket Grant message with the result
of this check. If access is granted, the Ticket Grant message contains
an Access Ticket comprised of a public Ticket Face and a private
Ticket Verifier. This authorization payload is relayed by
CAM to the Client in a Ticket Transfer Message
as defined in <xref target="ticket-transfer"/>.</t>
<t>The major difference between dynamic update of Authorization
Information and the initial handshake is the handling of a Ticket
Transfer message by the Client that is described in <xref target="ticket-handle"/>.</t>
<section anchor="ticket-handle" title="Handling of Ticket Transfer Messages">
<t>If the security association with S still exists and S
has indicated support for session renegotiation according to
<xref target="RFC5746"/>, the ticket Face SHOULD be used to renegotiate the
existing DTLS session. In this case, the ticket Face is used as
psk_identity as defined in <xref target="dtls-channel"/>. Otherwise, the Client
MUST perform a new DTLS handshake according to <xref target="dtls-channel"/> that
replaces the existing DTLS session.</t>
<t>After successful completion of the DTLS handshake S updates the
existing SAM Authorization Information for C according to the
contents of the ticket Face.</t>
<t><list style="hanging">
<t hangText='Note:'>
No mutual authentication between C and S is required for dynamic
updates when a DTLS channel exists that has been established as
defined in <xref target="dtls-channel"/>. S only needs to verify the
authenticity and integrity of the ticket Face issued by SAM which is
achieved by having performed a successful DTLS handshake with the
ticket Face as psk_identity. This could even be done within the
existing DTLS session by tunneling a CoDTLS
<xref target="I-D.schmertmann-dice-codtls"/> handshake.</t>
</list></t>
</section>
</section>
</section>
<section anchor="ticket" title="Ticket">
<t>Access tokens in DCAF are tickets that
consist of two parts, namely the Face and the Client Information.
The Face goes to S, the CI goes to the Client. The Face and the
CI are parts of the same ticket.</t>
<t>S only needs the information contained in the Ticket Face to authorize the
client and make sure that SAM generated the Ticket Face (S cannot
make authorization decisions by itself and hence needs SAM to do it). No
additional information about the Client is needed. S keeps the Ticket
Face as long as it is valid.</t>
<section anchor="face" title="Face">
<t>Face is the part of the ticket generated for S. Face MUST contain all
information needed for authorized access to a resource:</t>
<t><list style="symbols">
<t>SAM Authorization Information</t>
<t>A timestamp generated by SAM</t>
</list></t>
<t>Optionally, Face MAY also contain:</t>
<t><list style="symbols">
<t>A lifetime (optional)</t>
<t>A DTLS pre-shared key (optional)
<!-- end of list --></t>
</list></t>
<t>S MUST verify the integrity of Face, i.e. the information contained
in Face stems from SAM and was not manipulated by anyone else.</t>
<t>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
S and included in the first SAM Information
message. Alternatively, SAM MAY generate the timestamp. In this
case, SAM and S MUST use a time synchronization mechanism to make
sure that S interprets the timestamp correctly.</t>
<t>Face MAY be encrypted. If Face contains a DTLS PSK, the whole content
of Face MUST be encrypted.</t>
<t>The integrity of Face can be ensured by various means. Face may be
encrypted by SAM with a key it shares with S. Alternatively, S
can use a mechanism to generate the DTLS PSK which includes Face.
S generates the key from the Face it received. The correct key can
only be calculated with the correct Face (refer to <xref target="key-generation"/>
for details).</t>
</section>
<section anchor="client-information" title="Client Information">
<t>The CI part of the ticket is generated for C. It contains the Verifier, i.e. the
DTLS PSK for C and MAY contain Client Authorization Information
generated by CAM to provide the COP’s authorization policies to C. The
Verifier MUST NOT be transmitted over
insecure channels.</t>
</section>
<section anchor="revocation" title="Revocation">
<t>The existence of access tickets SHOULD be limited in time to avoid
stale tickets that waste resources on S and C.
This can be achieved either by explicit Revocation Messages
to invalidate a ticket or implicitly by attaching a lifetime
to the ticket.</t>
<section anchor="time" title="Lifetime">
<t>Tickets MAY have a lifetime. SAM is responsible for defining the
ticket lifetime. If SAM sets a lifetime for a ticket, SAM and S
MUST use a time synchronization method to ensure that S is able to
interpret the lifetime correctly. S SHOULD end the DTLS connection to
C if the lifetime of a ticket has run out and it MUST NOT accept new
requests. S MUST NOT accept tickets with an invalid lifetime.</t>
<t>If CAM provides CAI in the CI part of the ticket, CAM MAY add a
lifetime for this CAI. If CI contains a lifetime, CAM and C MUST use a
time synchronization method to ensure that C is able to interpret the
lifetime correctly. C SHOULD end the DTLS connection to S and MUST
NOT send new requests if the CAI in the ticket is no longer valid. C
MUST NOT accept tickets with an invalid lifetime.</t>
<t>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
SAM.</t>
</section>
<section anchor="revocation-messages" title="Revocation Messages">
<t>SAM MAY revoke tickets by sending a ticket revocation message to
S. If S receives a ticket revocation message, it MUST end the DTLS
connection to C and MUST NOT accept any further requests from C.</t>
<t>If ticket revocation messages are used, S MUST check regularly if
SAM is still available. If S cannot contact SAM, it MUST end
all DTLS connections and reject any further requests from C.</t>
<t>Note: The loss of the connection between S and SAM prevents all
access to S. This might especially be a severe problem if SAM is
responsible for several Servers or even a whole network.</t>
</section>
</section>
</section>
<section anchor="payload-format" title="Payload Format and Encoding (application/dcaf+cbor)">
<t>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 S. In this section, a representation in
Concise Binary Object Representation (CBOR, <xref target="RFC7049"/>) is defined.</t>
<t>DCAF data structures are defined as CBOR maps that contain key value
pairs. For efficient encoding, the keys defined in this document are
represented as unsigned integers in CBOR, i. e. major type 0. For
improved reading, we use symbolic identifiers to represent the
corresponding encoded values as defined in <xref target="cbor-keys"/>.</t>
<texttable title="DCAF field identifiers encoded in CBOR" anchor="cbor-keys">
<ttcol align='left'>Encoded Value</ttcol>
<ttcol align='left'>Key</ttcol>
<c>0</c>
<c>SAM</c>
<c>1</c>
<c>SAI</c>
<c>2</c>
<c>CAI</c>
<c>3</c>
<c>E</c>
<c>4</c>
<c>K</c>
<c>5</c>
<c>TS</c>
<c>6</c>
<c>L</c>
<c>7</c>
<c>G</c>
<c>8</c>
<c>F</c>
<c>9</c>
<c>V</c>
<c>10</c>
<c>A</c>
<c>11</c>
<c>D</c>
<c>12</c>
<c>N</c>
</texttable>
<t>The following list describes the semantics of the keys defined
in DCAF.</t>
<t><list style="hanging">
<t hangText='SAM:'>
Server Authorization Manager. This attribute denotes the Server Authorization
Manager 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 <xref target="RFC3986"/>.</t>
<t hangText='SAI:'>
SAM Authorization Information. A data structure used to convey
authorization information from SAM to S. It describes C’s
permissions for S according to SAM, e.g., which actions
C is allowed to perform on an R of S. The SAI attribute
contains an AIF object as defined in <xref target="I-D.bormann-core-ace-aif"/>.
C uses SAI for its Access Request messages.</t>
<t hangText='CAI:'>
CAM Authorization Information. A data structure used to convey
authorization information from CAM to C. It describes the C’s
permissions for S according to CAM, e.g., which actions C is allowed
to perform on an R of S. The CAI attribute
contains an AIF object as defined in <xref target="I-D.bormann-core-ace-aif"/>.</t>
<t hangText='A:'>
Accepted content formats. An array of numeric content formats from
the CoAP Content-Formats registry (c.f. Section 12.3 of <xref target="RFC7252"/>.</t>
<t hangText='D:'>
Protected Data. A binary string containing data that may be encrypted.</t>
<t hangText='E:'>
Encrypted Ticket Face. A binary string containing an encrypted ticket Face.</t>
<t hangText='K:'>
Key. A string that identifies the shared key between S and SAM
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 S
and SAM.</t>
<t hangText='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 Server in an SAM 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 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 S.</t>
<t hangText='L:'>
Lifetime. When in included in a ticket face, the contents of the
L parameter denote the lifetime of the ticket. In combination with
the protected data field D, this parameter denotes the lifetime
of the protected data. 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.</t>
<t hangText='N:'>
Nonce. An initialization vector used in combination with piggybacked
protected content.</t>
<t hangText='G:'>
DTLS PSK Generation Method. A numeric identifier for the method that
S 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. This specification uses symbolic identifiers for
improved readability. The corresponding numeric values encoded in
CBOR are defined in <xref target="cbor-g"/>. A registry for these codes is
defined in <xref target="cbor-g-iana"/>.</t>
<t hangText='F:'>
Ticket Face. An object containing the fields SAI, TS, and optionally
G, L and V.</t>
<t hangText='V:'>
Ticket Verifier. A binary string containing the shared secret between C and
S.</t>
</list></t>
<texttable title="CBOR encoding for DTLS PSK Key Generation Methods" anchor="cbor-g">
<ttcol align='left'>Encoded Value</ttcol>
<ttcol align='left'>Mnemonic</ttcol>
<ttcol align='left'>Support</ttcol>
<c>0</c>
<c>hmac_sha256</c>
<c>mandatory</c>
<c>1</c>
<c>hmac_sha384</c>
<c>optional</c>
<c>2</c>
<c>hmac_sha512</c>
<c>optional</c>
</texttable>
<section anchor="examples" title="Examples">
<t>The following example specifies a SAM 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.</t>
<figure><artwork><![CDATA[
POST /a?ep=%5B2001:DB8::dcaf:1234%5D HTTP/1.1
Host: sam.example.com
Content-Type: application/dcaf+cbor
{SAM: "https://sam.example.com/a?ep=%5B2001:DB8::dcaf:1234%5D",
SAI: ["coaps://temp451.example.com/s/tempC", 1],
TS: 0("2013-07-14T11:58:22.923")}
]]></artwork></figure>
<t>The following example shows a ticket for the distributed key
generation method (cf. <xref target="key-derivation"/>), comprised of a Face (F)
and a Verifier (V). The Face data structure contains authorization
information SAI, a client
descriptor, a timestamp using the local time scale of S, and a
lifetime relative to S’s time scale.</t>
<t>The DTLS PSK Generation Method is set to hmac_sha256 denoting
that the distributed key derivation is used as defined in
<xref target="key-derivation"/> with SHA-256 as HMAC function.</t>
<t>The Verifier V contains a shared secret to be used as DTLS PSK
between C and S.</t>
<!-- msg2.txt -->
<figure><artwork><![CDATA[
HTTP/1.1 200 OK
Content-Type: application/dcaf+cbor
{
F: {
SAI: [ "/s/tempC", 1 ],
TS: 2938749,
L: 3600,
G: hmac_sha256
},
V: h'48ae5a81b87241d81618f56cab0b65ec
441202f81faabbe10075b20cb57fa939'
}
]]></artwork></figure>
<t>The Face may be encrypted as illustrated in the following example.
Here, the field E carries an encrypted Face data structure that
contains the same information as the previous example, and an
additional Verifier. Encryption was done with a secret shared by
SAM and S. (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 S’s timestamp { 0x00, 0x2C, 0xD7, 0x7D
} as nonce.) Line breaks have been inserted to improve readability.</t>
<t>The attribute K describes the identity of the key to be used by S to
decrypt the contents of attribute E. Here, The value “key0” in this
example is used to indicate that the shared session key between S and
SAM was used for encrypting E.</t>
<!-- msg3.enc -->
<figure><artwork><![CDATA[
{
E: h'2e75eeae01b831e0b65c2976e06d90f4
82135bec5efef3be3d31520b2fa8c6fb
f572f817203bf7a0940bb6183697567c
e291b03e9fca5e9cbdfa7e560322d4ed
3a659f44a542e55331a1a9f43d7f',
K: "key0",
V: h'48ae5a81b87241d81618f56cab0b65ec
441202f81faabbe10075b20cb57fa939'
}
]]></artwork></figure>
<t>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. <xref target="key-transfer"/>).</t>
<figure><artwork><![CDATA[
{
F: {
SAI: [ "/s/tempC", 1 ],
TS: 2938749,
L: 3600,
G: hmac_sha256
},
V: h'48ae5a81b87241d81618f56cab0b65ec
441202f81faabbe10075b20cb57fa939'
}
]]></artwork></figure>
</section>
</section>
<section anchor="key-generation" title="DTLS PSK Generation Methods">
<t>One goal of the DCAF protocol is to provide for a DTLS PSK shared between C and S. SAM and S MUST negotiate the method for the DTLS PSK generation.</t>
<section anchor="key-transfer" title="DTLS PSK Transfer">
<t>The DTLS PSK is generated by AS and transmitted to C and S using a secure channel.</t>
<t>The DTLS PSK transfer method is defined as follows:</t>
<t><list style="symbols">
<t>SAM generates the DTLS PSK using an algorithm of its choice</t>
<t>SAM MUST include a representation of the DTLS PSK in Face and
encrypt it together with all other information in Face with a key
K(SAM,S) it shares with S. How SAM and S exchange
K(SAM,S) is not in the scope of this document. SAM and S
MAY use their preshared key as K(SAM,S).</t>
<t>SAM MUST include a representation of the DTLS PSK in the Verifier.</t>
<t>As SAM and C do not have a shared secret, the Verifier MUST
be transmitted to C using encrypted channels.</t>
<t>S MUST decrypt Face using K(SAM,S)</t>
</list></t>
</section>
<section anchor="key-derivation" title="Distributed Key Derivation">
<t>SAM generates a DTLS PSK for C which is transmitted using a secure channel. S generates its own version of the DTLS PSK using the information contained in Face (see also <xref target="face"/>).</t>
<t>The distributed key derivation method is defined as follows:</t>
<t><list style="symbols">
<t>SAM and S both generate the DTLS PSK using the information
included in Face. They use an HMAC algorithm on Face with a shared
key K(SAM,S). The result serves as the DTLS PSK. How SAM and S
exchange K(SAM,S) is not in the scope of this document. They MAY
use their preshared key as K(SAM,S). How SAM and S negotiate the
used HMAC algorithm is also not in the scope of this
document. They MAY however use the HMAC algorithm they use for their
DTLS connection.</t>
<t>SAM MUST include a representation of the DTLS PSK in the Verifier.</t>
<t>As SAM and C do not have a shared secret, the Verifier MUST
be transmitted to C using encrypted channels.</t>
<t>SAM MUST NOT include a representation of the DTLS PSK in Face.</t>
<t>SAM MUST NOT encrypt Face.</t>
</list></t>
</section>
</section>
<section anchor="authorization-configuration" title="Authorization Configuration">
<t>For the protocol defined in this document, proper configuration of CAM
and SAM is crucial. The principals that are in charge of the resource,
S and SAM, and the principals that are in charge of C and CAM need to
define the respective permissions. The data representation of these
permissions are not in the scope of this document.</t>
</section>
<section anchor="trust" title="Trust Relationships">
<t>C has a trust relationship with CAM: C trusts CAM to act in behalf of
C’s principal. S has a trust relationship with SAM: S trusts SAM to act
in behalf of S’s principal.</t>
<t>Obviously, CAM trusts C with the specific permissions it hands over to
it.
How this trust is established, is not in the scope of this document. It may be achieved by using a bootstrapping mechanism similar to <xref target="bergmann12"/>.</t>
<t>Additionally, SAM and CAM need to have a trust relationship
established. Its establishment is also not in the scope of this
document. It fulfills the following conditions:</t>
<t><list style="numbers">
<t>SAM has means to authenticate CAM (e.g. it has a certificate of CAM or a PKI in which CAM is included) and vice versa</t>
<t>As far as SAM needs to rely on the different clients of CAM to
receive different permissions, it can be sure that CAM correctly
identifies these clients towards SAM and does not leak tickets that have
been generated for a specific client C to another client.</t>
</list></t>
<!-- end of list -->
<!--
* to authorize individual devices, AS MUST be able to identify the devices (resource owner Must name them)
otherwise, AS may rely on AM that the request is allowed
-->
<t>SAM trusts C indirectly because it trusts CAM and CAM vouches for C. The DCAF Protocol does not provide any means for SAM to validate that a resource request stems from C.</t>
<t>C indirectly trusts SAM with some potentially confidential information, and that SAM
correctly represents S, because CAM trusts SAM.</t>
<t>CAM trusts S indirectly because it trusts SAM and SAM vouches for S.</t>
<t>C implicitly trusts S with some potentially confidential information
because it trusts CAM and because S can prove that it shares a key with SAM.</t>
<figure><artwork><![CDATA[
CAM <------------------> SAM
/|\ /|\
| |
\|/ \|/
C ..................... S
]]></artwork></figure>
</section>
<section anchor="rd" title="Listing Authorization Manager Information in a Resource Directory">
<t>CoAP utilizes the Web Linking format <xref target="RFC5988"/> to facilitate
discovery of services in an M2M environment. <xref target="RFC6690"/> defines
specific link parameters that can be used to describe resources to be
listed in a resource directory <xref target="I-D.ietf-core-resource-directory"/>.</t>
<section anchor="rt-auth-request" title="The “auth-request” Link Relation">
<t>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.</t>
<t>The Content-Format “application/dcaf+cbor with numeric identifier
TBD1 defined in this specification MAY be used to express
access requests and their responses.</t>
<t>The following example shows the web link used by CAM in this
document to relay incoming Authorization Request messages to SAM.
(Whitespace is included only for readability.)</t>
<figure><artwork><![CDATA[
<client-authorize>;rt="auth-request";ct=TBD1
;title="Contact Remote Authorization Manager"
]]></artwork></figure>
<t>The resource directory that hosts the resource descriptions of S
could list the following description. In this example, the URI
“ep/node138/a/switch2941” is relative to the resource context
“coaps://sam.example.com/”, i.e. the Server Authorization Manager SAM.</t>
<figure><artwork><![CDATA[
<ep/node138/a/switch2941>;rt="auth-request";ct=TBD1;ep="node138"
;title="Request Client Authorization"
;anchor="coaps://sam.example.com/"
]]></artwork></figure>
</section>
</section>
<section anchor="examples-1" title="Examples">
<t>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 SAM. The notation here follows the actors conventions defined in
<xref target="actors"/>. The payload format is encoded as proposed in
<xref target="payload-format"/>. The IP address of SAM is 2001:DB8::1, the IP address
of S is 2001:DB8::dcaf:1234, and C’s IP address is 2001:DB8::c.</t>
<section anchor="access-granted" title="Access Granted">
<t>This example shows an Unauthorized PUT request from C to S that is
answered with a SAM Information message. C then sends a POST
request to CAM with a description of its intended request. CAM
forwards this request to SAM using CoAP over a DTLS-secured
channel. The response from SAM contains an access ticket that is
relayed back to CAM.</t>
<figure><artwork><![CDATA[
C --> S
PUT a/switch2941 [Mid=1234]
Content-Format: application/senml+json
{"e": [{"bv": "1"}]}
C <-- S
4.01 Unauthorized [Mid=1234]
Content-Format: application/dcaf+cbor
{SAM: "coaps://[2001:DB8::1]/ep/node138/a/switch2941"}
C --> CAM
POST client-authorize [Mid=1235,Token="tok"]
Content-Format: application/dcaf+cbor
{
SAM: "coaps://[2001:DB8::1]/ep/node138/a/switch2941",
SAI: ["coaps://[2001:DB8::dcaf:1234]/a/switch2941", 4]
}
CAM --> SAM [Mid=23146]
POST ep/node138/a/switch2941
Content-Format: application/dcaf+cbor
{
SAM: "coaps://[2001:DB8::1]/ep/node138/a/switch2941",
SAI: ["coaps://[2001:DB8::dcaf:1234]/a/switch2941", 4]
}
CAM <-- SAM
2.05 Content [Mid=23146]
Content-Format: application/dcaf+cbor
{ F: {
SAI: ["a/switch2941", 5],
TS: 0("2013-07-04T20:17:38.002"),
G: hmac_sha256
},
V: h'7ba4d9e287c8b69dd52fd3498fb8d26d
9503611917b014ee6ec2a570d857987a'
}
C <-- CAM
2.05 Content [Mid=1235,Token="tok"]
Content-Format: application/dcaf+cbor
{ F: {
SAI: ["a/switch2941", 5],
TS: 0("2013-07-04T20:17:38.002"),
G: hmac_sha256
},
V: h'7ba4d9e287c8b69dd52fd3498fb8d26d
9503611917b014ee6ec2a570d857987a'
}
C --> S
ClientHello (TLS_PSK_WITH_AES_128_CCM_8)
C <-- S
ServerHello (TLS_PSK_WITH_AES_128_CCM_8)
ServerHelloDone
C --> S
ClientKeyExchange
psk_identity=0xa301826c612f73776974636832393431
0x0505c077323031332d30372d30345432
0x303a31373a33382e3030320700
(C decodes the contents of V and uses the result as PSK)
ChangeCipherSpec
Finished
(S calculates PSK from SAI, TS and its session key
HMAC_sha256(0xa301826c612f73776974636832393431
0x0505c077323031332d30372d30345432
0x303a31373a33382e3030320700,
0x736563726574)
= 0x7ba4d9e287c8...
)
C <-- S
ChangeCipherSpec
Finished
]]></artwork></figure>
<!-- openssl dgst -sha256 -hmac "secret" -binary <msg >hmac1.txt -->
</section>
<section anchor="access-denied" title="Access Denied">
<t>This example shows a denied Authorization request for the DELETE
operation.</t>
<figure><artwork><![CDATA[
C --> S
DELETE a/switch2941
C <-- S
4.01 Unauthorized
Content-Format: application/dcaf+cbor
{SAM: "coaps://[2001:DB8::1]/ep/node138/a/switch2941"}
C --> CAM
POST client-authorize
Content-Format: application/dcaf+cbor
{
SAM: "coaps://[2001:DB8::1]/ep/node138/a/switch2941",
SAI: ["coaps://[2001:DB8::dcaf:1234]/a/switch2941", 8]
}
CAM --> SAM
POST ep/node138/a/switch2941
Content-Format: application/dcaf+cbor
{
SAM: "coaps://[2001:DB8::1]/ep/node138/a/switch2941",
SAI: ["coaps://[2001:DB8::dcaf:1234]/a/switch2941", 8]
}
CAM <-- SAM
2.05 Content
Content-Format: application/dcaf+cbor
C <-- CAM
2.05 Content
Content-Format: application/dcaf+cbor
]]></artwork></figure>
</section>
<section anchor="access-restricted" title="Access Restricted">
<t>This example shows a denied Authorization request for the operations
GET, PUT, and DELETE. SAM grants access for PUT only.</t>
<figure><artwork><![CDATA[
CAM --> SAM
POST ep/node138/a/switch2941
Content-Format: application/dcaf+cbor
{
SAM: "coaps://[2001:DB8::1]/ep/node138/a/switch2941",
SAI: ["coaps://[2001:DB8::dcaf:1234]/a/switch2941", 13]
}
CAM <-- SAM
2.05 Content
Content-Format: application/dcaf+cbor
{ F: {
SAI: ["a/switch2941", 5],
TS: 0("2013-07-04T21:33:11.930"),
G: hmac_sha256
},
V: h'c7b5774f2ddcbd548f4ad74b30a1b2e5
b6b04e66a9995edd2545e5a06216c53d'
}
]]></artwork></figure>
</section>
<section anchor="implicit-authorization" title="Implicit Authorization">
<t>This example shows an Authorization request using implicit
authorization. CAM initially requests the actions GET and POST
on the resource “coaps://[2001:DB8::dcaf:1234]/a/switch2941”.
SAM returns a ticket that has no SAI field in its ticket Face,
hence implicitly authorizing C.</t>
<figure><artwork><![CDATA[
CAM --> SAM
POST ep/node138/a/switch2941
Content-Format: application/dcaf+cbor
{
SAM: "coaps://[2001:DB8::1]/ep/node138/a/switch2941",
SAI: ["coaps://[2001:DB8::dcaf:1234]/a/switch2941", 3]
}
CAM <-- SAM
2.05 Content
Content-Format: application/dcaf+cbor
{ F: {
TS: 0("2013-07-16T10:15:43.663"),
G: hmac_sha256
},
V: h'4f7b0e7fdcc498fb2ece648bf6bdf736
61a6067e51278a0078e5b8217147ea06'
}
]]></artwork></figure>
</section>
</section>
<section anchor="combined" title="Specific Usage Scenarios">
<t>The general DCAF architure outlined in <xref target="overview"/> illustrates the
various actors who participate in the message exchange for
authenticated authorization. The message types defined in this
document cover the most general case where all four actors are
separate entities that may or may not reside on the same device.</t>
<t>Special implementation considerations apply when one single entity
takes the role of more than one actor. This section gives advice on
the most common usage scenarios where the Client Authorization
Manager and Client, the Server Authorization Manager and Server or
both Authorization Managers
reside on the same (less-constrained) device and have a means of
secure communication outside the scope of this document.</t>
<section anchor="combined-authorization-manager-and-client" title="Combined Authorization Manager and Client">
<t>When CAM and C reside on the same (less-constrained) device, the Access
Request and Ticket Transfer messages can be substituted by other
means of secure communication. <xref target="cam-c-combined"/> shows a simplified
message exchange for a combined CAM+C device.</t>
<figure title="Combined Client Authorization Manager and Client" anchor="cam-c-combined"><artwork><![CDATA[
CAM+C S SAM
| | <== DTLS chan. ==> |
| [Resource Req.-->] | |
| | |
| [<-- SAM Info.] | |
| | |
| <==== TLS/DTLS chan. (Mutual Auth) ===> |
| | |
| Ticket Request ---------------------> |
| | |
| <--------------------- Ticket Grant |
| | |
| <== DTLS chan. ==> | |
| Auth. Res. Req. -> | |
]]></artwork></figure>
<section anchor="creating-the-ticket-request-message" title="Creating the Ticket Request Message">
<t>When CAM+C receives an SAM Information message as a reaction to an
Unauthorized Request message, it creates a Ticket Request message as
follows:</t>
<t><list style="numbers">
<t>The destination of the Ticket Request message is derived from the
authority information in the URI contained in field “SAM” of the
SAM Information message payload.</t>
<t>The request method is POST.</t>
<t>The request URI is constructed from the SAM field received in the
SAM Information message payload.</t>
<t>The payload contains the SAM field from the SAM Information message,
an absolute URI of the resource that CAM+C wants to access, the
actions that CAM+C wants to perform on the resource, and any time
stamp generated by S that was transferred with the SAM Information
message.</t>
<t>A label that describes CAM+C is added to the payload.</t>
</list></t>
</section>
<section anchor="processing-the-ticket-grant-message" title="Processing the Ticket Grant Message">
<t>Based on the Ticket Grant message, CAM+C is able to establish a DTLS
channel with S. To do so, CAM+C sets the psk_identity field of the
DTLS ClientKeyExchange message to the ticket Face received in the
Ticket Grant message and uses the ticket Verifier as PSK when
constructing the premaster secret.</t>
</section>
</section>
<section anchor="combined-client-authorization-manager-and-server-authorization-manager" title="Combined Client Authorization Manager and Server Authorization Manager">
<t>In certain scenarios, CAM and SAM may be combined to a single entity
that knows both, C and S, and decides if their actions are
authorized. Therefore, no explicit communication between CAM and SAM is
necessary, resulting in omission of the Ticket Request and Ticket
Grant messages. <xref target="cam-sam-combined"/> depicts the resulting message
sequence in this simplified architecture.</t>
<figure title="Combined Client Authorization Manager and Server Authorization Manager" anchor="cam-sam-combined"><artwork><![CDATA[
C CAM+SAM S
| <== DTLS chan. ==> | <== DTLS chan. ==> |
| | |
| [Resource Req.----------------------->] |
| | |
| [<-------------------- SAM Information] |
| | |
| Access Request --> | |
| | |
| <-- Ticket Transf. | |
| | |
| <=========== DTLS channel ===========> |
| | |
| Authorized Resource Request ----------> |
]]></artwork></figure>
<section anchor="processing-the-access-request-message" title="Processing the Access Request Message">
<t>When receiving an Access Request message, CAM+SAM performs the checks
specified in <xref target="ticket-req"/> and returns a 4.00 (Bad Request) response
in case of failure. Otherwise, if the checks have succeeded, CAM+SAM
evaluates the contents of Access Request message as described in
<xref target="ticket-grant-message"/>.</t>
<t>The decision on the access request is performed by CAM+SAM with respect
to the stored policies. When the requested action is permitted on the
respective resource, CAM+SAM generates an access ticket as outlined in
<xref target="face"/> and creates a Ticket Transfer message to convey the access
ticket to the Client.</t>
</section>
<section anchor="creating-the-ticket-transfer-message" title="Creating the Ticket Transfer Message">
<t>A Ticket Transfer message is constructed as a 2.05 response with the
access ticket contained in its payload. The response MAY contain a
Max-Age option to indicate the ticket’s lifetime to the receiving
Client.</t>
<t>This specification defines a CBOR data representation for the access
ticket as illustrated in <xref target="ticket-grant-message"/>.</t>
</section>
</section>
<section anchor="combined-server-authorization-manager-and-server" title="Combined Server Authorization Manager and Server">
<t>If SAM and S are colocated in one entity (SAM+S), the main objective is to
allow CAM to delegate access to C. Accordingly, the authorization
information could be replaced by a nonce internal to SAM+S. (TBD.)</t>
<figure title="Combined Server Authorization Manager and Server" anchor="sam-rs-combined"><artwork><![CDATA[
CAM C SAM+S
| <== DTLS chan. ==> | |
| | [Resource Req.-->] |
| | |
| | [<-- SAM Info.] |
| | |
| <-- Access Req. | |
| | |
| <========= TLS/DTLS channel =========> |
| | |
| Ticket Request ---------------------> |
| | |
| <--------------------- Ticket Grant |
| | |
| Ticket Transf. --> | |
| | |
| | <== DTLS chan. ==> |
| | Auth. Res. Req. -> |
]]></artwork></figure>
</section>
</section>
<section anchor="security-considerations" title="Security Considerations">
<t>As this protocol builds on transitive trust between Authorization
Managers as mentioned in <xref target="trust"/>, SAM has no direct means to validate
that a resource request originates from C. It has to trust CAM that it
correctly vouches for C and that it does not give authorization tickets meant for C to another client nor disclose the contained session key.</t>
<t>The Authorization Managers also could constitute a single point of
failure. If the Server Authorization Manager fails, the resources on
all Servers it is responsible for cannot be accessed any
more. If a Client Authorization Manager fails, all clients it is
responsible are not able to access resources on a Server.
Thus, it is crucial for large networks to use Authorization Managers
in a redundant setup.</t>
<!-- As already mentioned in {{trust}}, AS(RS) has no means to validate that a resource request really stems from C. It has to trust AS(C) that it really is responsible for C and that it does not give authorization tickets meant for C to another client. -->
</section>
<section anchor="iana-considerations" title="IANA Considerations">
<t>The following registrations are done following the procedure specified
in <xref target="RFC6838"/>.</t>
<t>Note to RFC Editor: Please replace all occurrences of “&SELF;” with
the RFC number of this specification.</t>
<section anchor="cbor-g-iana" title="DTLS PSK Key Generation Methods">
<t>A sub-registry for the values indicating the PSK key generation method
as contents of the field G in a payload of type application/dcaf+cbor
is defined. Values in this sub-registry are numeric integers encoded
in Concise Binary Object Notation (CBOR, <xref target="RFC7049"/>). This document
follows the notation of <xref target="RFC7049"/> for binary values, i.e. a number
starts with the prefix “0b”. The major type is separated from the actual
numeric value by an underscore to emphasize the value’s internal
structure.</t>
<t>Initial entries in this sub-registry are as follows:</t>
<texttable title="DTLS PSK Key Generation Methods" anchor="iana-g">
<ttcol align='left'>Encoded Value</ttcol>
<ttcol align='left'>Name</ttcol>
<ttcol align='left'>Reference</ttcol>
<c>0b000_00000</c>
<c>hmac_sha256</c>
<c>&SELF;</c>
<c>0b000_00001</c>
<c>hmac_sha384</c>
<c>&SELF;</c>
<c>0b000_00010</c>
<c>hmac_sha512</c>
<c>&SELF;</c>
</texttable>
<t>New methods can be added to this
registry based on designated expert review according to <xref target="RFC5226"/>.</t>
<t>(TBD: criteria for expert review.)</t>
</section>
<section anchor="mt" title="dcaf+cbor Media Type Registration">
<t>Type name: application</t>
<t>Subtype name: dcaf+cbor</t>
<t>Required parameters: none</t>
<t>Optional parameters: none</t>
<t>Encoding considerations: Must be encoded as using a subset of the
encoding allowed in <xref target="RFC7049"/>. Specifically, only the primitive data
types String and Number are allowed. The type Number is restricted to
unsigned integers (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.</t>
<t>Security considerations: TBD</t>
<t>Interoperability considerations: TBD</t>
<t>Published specification: &SELF;</t>
<t>Applications that use this media type: TBD</t>
<t>Additional information:</t>
<t>Magic number(s): none</t>
<t>File extension(s): dcaf</t>
<t>Macintosh file type code(s): none</t>
<t>Person & email address to contact for further information: TBD</t>
<t>Intended usage: COMMON</t>
<t>Restrictions on usage: None</t>
<t>Author: TBD</t>
<t>Change controller: IESG</t>
</section>
<section anchor="coap-content-format-registration" title="CoAP Content Format Registration">
<t>This document specifies a new media type application/dcaf+cbor
(cf. <xref target="mt"/>). 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.</t>
<t>Note to RFC Editor: Please replace all occurrences of “RFC-XXXX” with
the RFC number of this specification.</t>
<texttable>
<ttcol align='right'>Media type</ttcol>
<ttcol align='left'>Encoding</ttcol>
<ttcol align='left'>Id.</ttcol>
<ttcol align='left'>Reference</ttcol>
<c>application/dcaf+cbor</c>
<c>-</c>
<c>TBD1</c>
<c>&SELF;</c>
</texttable>
</section>
</section>
</middle>
<back>
<references title='Normative References'>
<reference anchor='RFC2119' target='http://www.rfc-editor.org/info/rfc2119'>
<front>
<title>Key words for use in RFCs to Indicate Requirement Levels</title>
<author initials='S.' surname='Bradner' fullname='S. Bradner'><organization /></author>
<date year='1997' month='March' />
<abstract><t>In many standards track documents several words are used to signify the requirements in the specification. These words are often capitalized. This document defines these words as they should be interpreted in IETF documents. This document specifies an Internet Best Current Practices for the Internet Community, and requests discussion and suggestions for improvements.</t></abstract>
</front>
<seriesInfo name='BCP' value='14'/>
<seriesInfo name='RFC' value='2119'/>
<seriesInfo name='DOI' value='10.17487/RFC2119'/>
</reference>
<reference anchor='RFC3986' target='http://www.rfc-editor.org/info/rfc3986'>
<front>
<title>Uniform Resource Identifier (URI): Generic Syntax</title>
<author initials='T.' surname='Berners-Lee' fullname='T. Berners-Lee'><organization /></author>
<author initials='R.' surname='Fielding' fullname='R. Fielding'><organization /></author>
<author initials='L.' surname='Masinter' fullname='L. Masinter'><organization /></author>
<date year='2005' month='January' />
<abstract><t>A Uniform Resource Identifier (URI) is a compact sequence of characters that identifies an abstract or physical resource. This specification defines the generic URI syntax and a process for resolving URI references that might be in relative form, along with guidelines and security considerations for the use of URIs on the Internet. The URI syntax defines a grammar that is a superset of all valid URIs, allowing an implementation to parse the common components of a URI reference without knowing the scheme-specific requirements of every possible identifier. This specification does not define a generative grammar for URIs; that task is performed by the individual specifications of each URI scheme. [STANDARDS-TRACK]</t></abstract>
</front>
<seriesInfo name='STD' value='66'/>
<seriesInfo name='RFC' value='3986'/>
<seriesInfo name='DOI' value='10.17487/RFC3986'/>
</reference>
<reference anchor='RFC4279' target='http://www.rfc-editor.org/info/rfc4279'>
<front>
<title>Pre-Shared Key Ciphersuites for Transport Layer Security (TLS)</title>
<author initials='P.' surname='Eronen' fullname='P. Eronen' role='editor'><organization /></author>
<author initials='H.' surname='Tschofenig' fullname='H. Tschofenig' role='editor'><organization /></author>
<date year='2005' month='December' />
<abstract><t>This document specifies three sets of new ciphersuites for the Transport Layer Security (TLS) protocol to support authentication based on pre-shared keys (PSKs). These pre-shared keys are symmetric keys, shared in advance among the communicating parties. The first set of ciphersuites uses only symmetric key operations for authentication. The second set uses a Diffie-Hellman exchange authenticated with a pre-shared key, and the third set combines public key authentication of the server with pre-shared key authentication of the client. [STANDARDS-TRACK]</t></abstract>
</front>
<seriesInfo name='RFC' value='4279'/>
<seriesInfo name='DOI' value='10.17487/RFC4279'/>
</reference>
<reference anchor='RFC6838' target='http://www.rfc-editor.org/info/rfc6838'>
<front>
<title>Media Type Specifications and Registration Procedures</title>
<author initials='N.' surname='Freed' fullname='N. Freed'><organization /></author>
<author initials='J.' surname='Klensin' fullname='J. Klensin'><organization /></author>
<author initials='T.' surname='Hansen' fullname='T. Hansen'><organization /></author>
<date year='2013' month='January' />
<abstract><t>This document defines procedures for the specification and registration of media types for use in HTTP, MIME, and other Internet protocols. This memo documents an Internet Best Current Practice.</t></abstract>
</front>
<seriesInfo name='BCP' value='13'/>
<seriesInfo name='RFC' value='6838'/>
<seriesInfo name='DOI' value='10.17487/RFC6838'/>
</reference>
<reference anchor='RFC5746' target='http://www.rfc-editor.org/info/rfc5746'>
<front>
<title>Transport Layer Security (TLS) Renegotiation Indication Extension</title>
<author initials='E.' surname='Rescorla' fullname='E. Rescorla'><organization /></author>
<author initials='M.' surname='Ray' fullname='M. Ray'><organization /></author>
<author initials='S.' surname='Dispensa' fullname='S. Dispensa'><organization /></author>
<author initials='N.' surname='Oskov' fullname='N. Oskov'><organization /></author>
<date year='2010' month='February' />
<abstract><t>Secure Socket Layer (SSL) and Transport Layer Security (TLS) renegotiation are vulnerable to an attack in which the attacker forms a TLS connection with the target server, injects content of his choice, and then splices in a new TLS connection from a client. The server treats the client's initial TLS handshake as a renegotiation and thus believes that the initial data transmitted by the attacker is from the same entity as the subsequent client data. This specification defines a TLS extension to cryptographically tie renegotiations to the TLS connections they are being performed over, thus preventing this attack. [STANDARDS-TRACK]</t></abstract>
</front>
<seriesInfo name='RFC' value='5746'/>
<seriesInfo name='DOI' value='10.17487/RFC5746'/>
</reference>
<reference anchor='RFC6347' target='http://www.rfc-editor.org/info/rfc6347'>
<front>
<title>Datagram Transport Layer Security Version 1.2</title>
<author initials='E.' surname='Rescorla' fullname='E. Rescorla'><organization /></author>
<author initials='N.' surname='Modadugu' fullname='N. Modadugu'><organization /></author>
<date year='2012' month='January' />
<abstract><t>This document specifies version 1.2 of the Datagram Transport Layer Security (DTLS) protocol. The DTLS protocol provides communications privacy for datagram protocols. The protocol allows client/server applications to communicate in a way that is designed to prevent eavesdropping, tampering, or message forgery. The DTLS protocol is based on the Transport Layer Security (TLS) protocol and provides equivalent security guarantees. Datagram semantics of the underlying transport are preserved by the DTLS protocol. This document updates DTLS 1.0 to work with TLS version 1.2. [STANDARDS-TRACK]</t></abstract>
</front>
<seriesInfo name='RFC' value='6347'/>
<seriesInfo name='DOI' value='10.17487/RFC6347'/>
</reference>
<reference anchor='RFC7049' target='http://www.rfc-editor.org/info/rfc7049'>
<front>
<title>Concise Binary Object Representation (CBOR)</title>
<author initials='C.' surname='Bormann' fullname='C. Bormann'><organization /></author>
<author initials='P.' surname='Hoffman' fullname='P. Hoffman'><organization /></author>
<date year='2013' month='October' />
<abstract><t>The Concise Binary Object Representation (CBOR) is a data format whose design goals include the possibility of extremely small code size, fairly small message size, and extensibility without the need for version negotiation. These design goals make it different from earlier binary serializations such as ASN.1 and MessagePack.</t></abstract>
</front>
<seriesInfo name='RFC' value='7049'/>
<seriesInfo name='DOI' value='10.17487/RFC7049'/>
</reference>
<reference anchor='RFC7252' target='http://www.rfc-editor.org/info/rfc7252'>
<front>
<title>The Constrained Application Protocol (CoAP)</title>
<author initials='Z.' surname='Shelby' fullname='Z. Shelby'><organization /></author>
<author initials='K.' surname='Hartke' fullname='K. Hartke'><organization /></author>
<author initials='C.' surname='Bormann' fullname='C. Bormann'><organization /></author>
<date year='2014' month='June' />
<abstract><t>The Constrained Application Protocol (CoAP) is a specialized web transfer protocol for use with constrained nodes and constrained (e.g., low-power, lossy) networks. The nodes often have 8-bit microcontrollers with small amounts of ROM and RAM, while constrained networks such as IPv6 over Low-Power Wireless Personal Area Networks (6LoWPANs) often have high packet error rates and a typical throughput of 10s of kbit/s. The protocol is designed for machine- to-machine (M2M) applications such as smart energy and building automation.</t><t>CoAP provides a request/response interaction model between application endpoints, supports built-in discovery of services and resources, and includes key concepts of the Web such as URIs and Internet media types. CoAP is designed to easily interface with HTTP for integration with the Web while meeting specialized requirements such as multicast support, very low overhead, and simplicity for constrained environments.</t></abstract>
</front>
<seriesInfo name='RFC' value='7252'/>
<seriesInfo name='DOI' value='10.17487/RFC7252'/>
</reference>
<reference anchor='RFC5226' target='http://www.rfc-editor.org/info/rfc5226'>
<front>
<title>Guidelines for Writing an IANA Considerations Section in RFCs</title>
<author initials='T.' surname='Narten' fullname='T. Narten'><organization /></author>
<author initials='H.' surname='Alvestrand' fullname='H. Alvestrand'><organization /></author>
<date year='2008' month='May' />
<abstract><t>Many protocols make use of identifiers consisting of constants and other well-known values. Even after a protocol has been defined and deployment has begun, new values may need to be assigned (e.g., for a new option type in DHCP, or a new encryption or authentication transform for IPsec). To ensure that such quantities have consistent values and interpretations across all implementations, their assignment must be administered by a central authority. For IETF protocols, that role is provided by the Internet Assigned Numbers Authority (IANA).</t><t>In order for IANA to manage a given namespace prudently, it needs guidelines describing the conditions under which new values can be assigned or when modifications to existing values can be made. If IANA is expected to play a role in the management of a namespace, IANA must be given clear and concise instructions describing that role. This document discusses issues that should be considered in formulating a policy for assigning values to a namespace and provides guidelines for authors on the specific text that must be included in documents that place demands on IANA.</t><t>This document obsoletes RFC 2434. This document specifies an Internet Best Current Practices for the Internet Community, and requests discussion and suggestions for improvements.</t></abstract>
</front>
<seriesInfo name='BCP' value='26'/>
<seriesInfo name='RFC' value='5226'/>
<seriesInfo name='DOI' value='10.17487/RFC5226'/>
</reference>
</references>
<references title='Informative References'>
<reference anchor='RFC5988' target='http://www.rfc-editor.org/info/rfc5988'>
<front>
<title>Web Linking</title>
<author initials='M.' surname='Nottingham' fullname='M. Nottingham'><organization /></author>
<date year='2010' month='October' />
<abstract><t>This document specifies relation types for Web links, and defines a registry for them. It also defines the use of such links in HTTP headers with the Link header field. [STANDARDS-TRACK]</t></abstract>
</front>
<seriesInfo name='RFC' value='5988'/>
<seriesInfo name='DOI' value='10.17487/RFC5988'/>
</reference>
<reference anchor='RFC6655' target='http://www.rfc-editor.org/info/rfc6655'>
<front>
<title>AES-CCM Cipher Suites for Transport Layer Security (TLS)</title>
<author initials='D.' surname='McGrew' fullname='D. McGrew'><organization /></author>
<author initials='D.' surname='Bailey' fullname='D. Bailey'><organization /></author>
<date year='2012' month='July' />
<abstract><t>This memo describes the use of the Advanced Encryption Standard (AES) in the Counter with Cipher Block Chaining - Message Authentication Code (CBC-MAC) Mode (CCM) of operation within Transport Layer Security (TLS) and Datagram TLS (DTLS) to provide confidentiality and data origin authentication. The AES-CCM algorithm is amenable to compact implementations, making it suitable for constrained environments. [STANDARDS-TRACK]</t></abstract>
</front>
<seriesInfo name='RFC' value='6655'/>
<seriesInfo name='DOI' value='10.17487/RFC6655'/>
</reference>
<reference anchor='RFC6690' target='http://www.rfc-editor.org/info/rfc6690'>
<front>
<title>Constrained RESTful Environments (CoRE) Link Format</title>
<author initials='Z.' surname='Shelby' fullname='Z. Shelby'><organization /></author>
<date year='2012' month='August' />
<abstract><t>This specification defines Web Linking using a link format for use by constrained web servers to describe hosted resources, their attributes, and other relationships between links. Based on the HTTP Link Header field defined in RFC 5988, the Constrained RESTful Environments (CoRE) Link Format is carried as a payload and is assigned an Internet media type. "RESTful" refers to the Representational State Transfer (REST) architecture. A well-known URI is defined as a default entry point for requesting the links hosted by a server. [STANDARDS-TRACK]</t></abstract>
</front>
<seriesInfo name='RFC' value='6690'/>
<seriesInfo name='DOI' value='10.17487/RFC6690'/>
</reference>
<reference anchor="bergmann12" >
<front>
<title>Secure Bootstrapping of Nodes in a CoAP Network</title>
<author initials="O." surname="Bergmann" fullname="Olaf Bergmann">
<organization></organization>
</author>
<author initials="S." surname="Gerdes" fullname="Stefanie Gerdes">
<organization></organization>
</author>
<author initials="S." surname="Schaefer" fullname="Silke Schaefer">
<organization></organization>
</author>
<author initials="F." surname="Junge" fullname="Florian Junge">
<organization></organization>
</author>
<author initials="C." surname="Bormann" fullname="Carsten Bormann">
<organization></organization>
</author>
<date year="2012" month="April"/>
</front>
<seriesInfo name="IEEE" value="Wireless Communications and Networking Conference Workshops (WCNCW)"/>
</reference>
<reference anchor='I-D.ietf-core-block'>
<front>
<title>Block-wise transfers in CoAP</title>
<author initials='C' surname='Bormann' fullname='Carsten Bormann'>
<organization />
</author>
<author initials='Z' surname='Shelby' fullname='Zach Shelby'>
<organization />
</author>
<date month='March' day='9' year='2015' />
<abstract><t>CoAP is a RESTful transfer protocol for constrained nodes and networks. Basic CoAP messages work well for the small payloads we expect from temperature sensors, light switches, and similar building-automation devices. Occasionally, however, applications will need to transfer larger payloads -- for instance, for firmware updates. With HTTP, TCP does the grunt work of slicing large payloads up into multiple packets and ensuring that they all arrive and are handled in the right order. CoAP is based on datagram transports such as UDP or DTLS, which limits the maximum size of resource representations that can be transferred without too much fragmentation. Although UDP supports larger payloads through IP fragmentation, it is limited to 64 KiB and, more importantly, doesn't really work well for constrained applications and networks. Instead of relying on IP fragmentation, this specification extends basic CoAP with a pair of "Block" options, for transferring multiple blocks of information from a resource representation in multiple request-response pairs. In many important cases, the Block options enable a server to be truly stateless: the server can handle each block transfer separately, with no need for a connection setup or other server-side memory of previous block transfers. In summary, the Block options provide a minimal way to transfer larger representations in a block-wise fashion.</t></abstract>
</front>
<seriesInfo name='Internet-Draft' value='draft-ietf-core-block-17' />
<format type='TXT'
target='http://www.ietf.org/internet-drafts/draft-ietf-core-block-17.txt' />
</reference>
<reference anchor='I-D.ietf-core-observe'>
<front>
<title>Observing Resources in CoAP</title>
<author initials='K' surname='Hartke' fullname='Klaus Hartke'>
<organization />
</author>
<date month='December' day='30' year='2014' />
<abstract><t>The Constrained Application Protocol (CoAP) is a RESTful application protocol for constrained nodes and networks. The state of a resource on a CoAP server can change over time. This document specifies a simple protocol extension for CoAP that enables CoAP clients to "observe" resources, i.e., to retrieve a representation of a resource and keep this representation updated by the server over a period of time. The protocol follows a best-effort approach for sending new representations to clients and provides eventual consistency between the state observed by each client and the actual resource state at the server.</t></abstract>
</front>
<seriesInfo name='Internet-Draft' value='draft-ietf-core-observe-16' />
<format type='TXT'
target='http://www.ietf.org/internet-drafts/draft-ietf-core-observe-16.txt' />
</reference>
<reference anchor='I-D.ietf-core-resource-directory'>
<front>
<title>CoRE Resource Directory</title>
<author initials='Z' surname='Shelby' fullname='Zach Shelby'>
<organization />
</author>
<author initials='M' surname='Koster' fullname='Michael Koster'>
<organization />
</author>
<author initials='C' surname='Bormann' fullname='Carsten Bormann'>
<organization />
</author>
<author initials='P' surname='Stok' fullname='Peter Van der Stok'>
<organization />
</author>
<date month='July' day='6' year='2015' />
<abstract><t>In many M2M applications, direct discovery of resources is not practical due to sleeping nodes, disperse networks, or networks where multicast traffic is inefficient. These problems can be solved by employing an entity called a Resource Directory (RD), which hosts descriptions of resources held on other servers, allowing lookups to be performed for those resources. This document specifies the web interfaces that a Resource Directory supports in order for web servers to discover the RD and to register, maintain, lookup and remove resources descriptions. Furthermore, new link attributes useful in conjunction with an RD are defined.</t></abstract>
</front>
<seriesInfo name='Internet-Draft' value='draft-ietf-core-resource-directory-04' />
<format type='TXT'
target='http://www.ietf.org/internet-drafts/draft-ietf-core-resource-directory-04.txt' />
<format type='PDF'
target='http://www.ietf.org/internet-drafts/draft-ietf-core-resource-directory-04.pdf' />
</reference>
<reference anchor='I-D.ietf-cose-msg'>
<front>
<title>CBOR Encoded Message Syntax</title>
<author initials='J' surname='Schaad' fullname='Jim Schaad'>
<organization />
</author>
<author initials='B' surname='Campbell' fullname='Brian Campbell'>
<organization />
</author>
<date month='August' day='28' year='2015' />
<abstract><t>Concise Binary Object Representation (CBOR) is data format designed for small code size and small message size. There is a need for the ability to have the basic security services defined for this data format. This document specifies how to do signatures, message authentication codes and encryption using this data format.</t></abstract>
</front>
<seriesInfo name='Internet-Draft' value='draft-ietf-cose-msg-04' />
<format type='TXT'
target='http://www.ietf.org/internet-drafts/draft-ietf-cose-msg-04.txt' />
</reference>
<reference anchor='I-D.schmertmann-dice-codtls'>
<front>
<title>CoDTLS: DTLS handshakes over CoAP</title>
<author initials='L' surname='Schmertmann' fullname='Lars Schmertmann'>
<organization />
</author>
<author initials='K' surname='Hartke' fullname='Klaus Hartke'>
<organization />
</author>
<author initials='C' surname='Bormann' fullname='Carsten Bormann'>
<organization />
</author>
<date month='August' day='15' year='2014' />
<abstract><t>The Datagram Transport Layer Security protocol, DTLS, is usually transported over UDP. In Constrained Node Networks, there may be considerable limitations on the packet delivery rates and on practically usable packet sizes. Applications often can control the size and retransmission requirements of their data packets, but the DTLS handshake is out of scope for such application optimizations. This specification defines how to perform a DTLS handshake on top of the CoAP protocol. The resulting DTLS connection may then be used for instance for transporting CoAP, or as a source of keying material. The latter case is particularly interesting if the CoAP exchanges transporting the DTLS handshake messages traverse CoAP proxies.</t></abstract>
</front>
<seriesInfo name='Internet-Draft' value='draft-schmertmann-dice-codtls-01' />
<format type='TXT'
target='http://www.ietf.org/internet-drafts/draft-schmertmann-dice-codtls-01.txt' />
</reference>
<reference anchor='I-D.bormann-core-ace-aif'>
<front>
<title>An Authorization Information Format (AIF) for ACE</title>
<author initials='C' surname='Bormann' fullname='Carsten Bormann'>
<organization />
</author>
<date month='July' day='6' year='2015' />
<abstract><t>Constrained Devices as they are used in the "Internet of Things" need security. One important element of this security is that devices in the Internet of Things need to be able to decide which operations requested of them should be considered authorized, need to ascertain that the authorization to request the operation does apply to the actual requester, and need to ascertain that other devices they place requests on are the ones they intended. On the ACE mailing list, an activity to create specifications for such authenticated authorization for constrained devices is contemplated, leading to protocol proposals such as [I-D.gerdes-ace-dcaf-authorize]. One potential work item complementing this protocol work is an Authorization Information Format (AIF). This document provides a strawman for such a format that should enable further discussion of the objectives for its development.</t></abstract>
</front>
<seriesInfo name='Internet-Draft' value='draft-bormann-core-ace-aif-03' />
<format type='TXT'
target='http://www.ietf.org/internet-drafts/draft-bormann-core-ace-aif-03.txt' />
</reference>
<reference anchor='I-D.gerdes-ace-actors'>
<front>
<title>An architecture for authorization in constrained environments</title>
<author initials='S' surname='Gerdes' fullname='Stefanie Gerdes'>
<organization />
</author>
<author initials='L' surname='Seitz' fullname='Ludwig Seitz'>
<organization />
</author>
<author initials='G' surname='Selander' fullname='Goran Selander'>
<organization />
</author>
<author initials='C' surname='Bormann' fullname='Carsten Bormann'>
<organization />
</author>
<date month='April' day='29' year='2015' />
<abstract><t>Constrained-node networks are networks where some nodes have severe constraints on code size, state memory, processing capabilities, user interface, power and communication bandwidth (RFC 7228). This document provides terminology, and elements of an architecture / a problem statement, for authentication and authorization in these networks.</t></abstract>
</front>
<seriesInfo name='Internet-Draft' value='draft-gerdes-ace-actors-05' />
<format type='TXT'
target='http://www.ietf.org/internet-drafts/draft-gerdes-ace-actors-05.txt' />
</reference>
<reference anchor='I-D.greevenbosch-appsawg-cbor-cddl'>
<front>
<title>CBOR data definition language: a notational convention to express CBOR data structures.</title>
<author initials='C' surname='Vigano' fullname='Christoph Vigano'>
<organization />
</author>
<author initials='H' surname='Birkholz' fullname='Henk Birkholz'>
<organization />
</author>
<date month='July' day='6' year='2015' />
<abstract><t>This document proposes a notational convention to express CBOR data structures (RFC 7049). Its main goal is to provide an easy and unambiguous way to express structures for protocol messages and data formats that use CBOR.</t></abstract>
</front>
<seriesInfo name='Internet-Draft' value='draft-greevenbosch-appsawg-cbor-cddl-06' />
<format type='TXT'
target='http://www.ietf.org/internet-drafts/draft-greevenbosch-appsawg-cbor-cddl-06.txt' />
</reference>
</references>
<section anchor="cddl" title="CDDL Specification">
<t>This appendix shows a formal specification of the DCAF messaging
format using the CBOR data definition language (CDDL)
<xref target="I-D.greevenbosch-appsawg-cbor-cddl"/>:</t>
<figure><artwork><![CDATA[
dcaf-msg = sam-information-msg
/ access-request-msg
/ ticket-transfer-msg
/ ticket-grant-msg
sam-information-msg = { sam, ? full-timestamp, ? accepted-formats,
? piggybacked }
access-request-msg = { sam, sam-ai, full-timestamp }
ticket-transfer-msg = { face-or-encrypted, verifier }
face-or-encrypted = ( face | encrypted-face )
face = ( F => { sam-ai, limited-timestamp, lifetime, psk-gen } )
verifier = ( V => shared-secret )
shared-secret = bstr
F = 8
V = 9
encrypted-face = ( E => bstr, K => tstr )
E = 3
K = 4
ticket-grant-msg = { face-or-encrypted, verifier, ? client-info }
client-info = ( cam-ai, full-timestamp, lifetime)
sam = (SAM => abs-uri)
SAM = 0
abs-uri = tstr ; .regexp "______"
sam-ai = ( SAI => [* auth-info])
SAI = 1
auth-info = ( uri : tstr, mask : 0..15 )
cam-ai = ( CAI => [* auth-info])
CAI = 2
full-timestamp = ( TS => date)
TS = 5
date = tdate / localdate
localdate = uint
limited-timestamp = ( TS => localdate)
accepted-formats = ( A => [+ content-format] )
content-format = uint ; valid entry from CoAP content format registry
A=10
piggybacked = ( data, lifetime, nonce )
data = ( D => bstr )
none = ( N => bstr )
lifetime = ( L => period)
period = uint ; in seconds
L = 6
D = 11
N = 12
psk-gen = ( G => mac-algorithm)
G = 7
mac-algorithm = &( hmac-sha256: 0, hmac-sha384: 1, hmac-sha512: 2 )
]]></artwork></figure>
<!-- LocalWords: Datagram CoAP CoRE DTLS DCAF DCAF's introducer URI
-->
<!-- LocalWords: namespace Verifier JSON timestamp timestamps PSK
-->
<!-- LocalWords: decrypt UTC decrypted whitespace preshared HMAC
-->
</section>
</back>
</rfc>
| PAFTECH AB 2003-2026 | 2026-04-23 02:58:20 |