One document matched: draft-bergmann-ace-dcaf-cose-00.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 comments="yes"?>
<rfc ipr="trust200902" docName="draft-bergmann-ace-dcaf-cose-00" category="std">
<front>
<title abbrev="DCAF-COSE">Using The Delegated CoAP Authentication and Authorization Framework (DCAF) With CBOR Encoded Message Syntax</title>
<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="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>
<date year="2015" month="October" day="19"/>
<area>Security</area>
<workgroup>ACE Working Group</workgroup>
<keyword>Internet-Draft</keyword>
<abstract>
<t>This specification defines a profile for the Delegated CoAP
Authentication and Authorization Framework (DCAF) that facilitates
client authentication and authorization in a constrained environment
using the CBOR Encoded Message Syntax.</t>
</abstract>
</front>
<middle>
<section anchor="introduction" title="Introduction">
<t>The Delegated CoAP Authentication and Authorization Framework (DCAF)
is designed to be agnostic of the actual mechanism being used to secure the
communication between the ACE actors. While the original specification
<xref target="I-D.gerdes-ace-dcaf-authorize"/> defines how to use DCAF messaging
for establishing a Datagram Transport Layer Security (DTLS)
<xref target="RFC6347"/> channel between actors on the constrained level
(cf. <xref target="I-D.ietf-ace-actors"/>), this document specifies a binding of
DCAF to the CBOR Encoded Message Syntax, COSE <xref target="I-D.ietf-cose-msg"/>.</t>
<t>To reduce confusion, we use “DTLS DCAF” to refer to DCAF based on DTLS
security, and “COSE DCAF” to refer to DCAF as defined in the present
document.</t>
<t>DCAF defines authorized access to a resource hosted on a resource
Server (S) based on a security context that is established between the
requesting Client (C) and S. In DTLS DCAF, this security context is tied to a DTLS
channel which allows for end-to-end integrity protection and
confidentiality of communication. In the presence of intermediaries
such as, e.g., CoAP proxies, channel security may not be applicable
for all configurations. If this is the case, the exchanged
information must be protected at the application level
to help achieving the principals’ security requirements.
The IETF
working group CBOR Object Signing and Encryption (COSE) has defined a
Concise Binary Object Representation (CBOR) <xref target="RFC7049"/> representation
for signed and encrypted objects as well as message authentication
codes.</t>
<t>This specification uses this CBOR Encoded Message Syntax
<xref target="I-D.ietf-cose-msg"/> to protect the DCAF protocol flow on the
application level. The features of this DCAF profile are:</t>
<t><list style="symbols">
<t>Authenticated exchange of authorization information.</t>
<t>Simplified authentication on constrained nodes by handing the more
sophisticated authentication work 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>Can be made to work just using symmetric encryption on the
constrained nodes.</t>
<t>Enable delivery of piggybacked protected content as discussed in
<xref target="I-D.gerdes-ace-dcaf-authorize"/>.</t>
</list></t>
<section anchor="terminology" title="Terminology">
<t>The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”,
“SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “NOT RECOMMENDED”, “MAY”, and “OPTIONAL” in this
document are to be interpreted as described in 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-dcaf-authorize"/>.</t>
</section>
</section>
<section anchor="overview" title="Overview">
<t>This specification retains the most important features of DCAF by
utilizing the same basic messaging mechanism. DCAF ensures that protected
information is accessible only by authorized entities, i.e. access must
be authenticated and the principal that oversees the particular piece
of information must permit the requested action. The DCAF
specification cryptographically ties this authorization to a DTLS
session setup between the communicating Client and Server. The DTLS
key material used for creating this session hence defines the security
context between the communicating parties. By supplementing DCAF with
the notion of a context identifier, the same mechanism can be used
with application level security as well.</t>
<section anchor="authorized-requests" title="Sending Authorized Requests">
<t>In general, every request that C sends to S must be treated by S
within a particular security context with C.
<cref anchor="_1" source="Editor's note">As a consequence, if no such security context is found, the
request will be rejected as Unauthorized Request.</cref> If S is not able to
otherwise identify the security context from the message context, the context
identifier must be transferred within the respective message. An
example of a request containing an explicit context identifier is
shown in <xref target="ex-request01"/> using the CBOR diagnostic notation as
defined in Section 6 of <xref target="RFC7049"/>
to describe the actual data represented in CBOR.</t>
<figure title="Example for CoAP Request with Explicit Context Identifier" anchor="ex-request01"><artwork><![CDATA[
PUT /r
Content-Format: application/cose+cbor
[ h'a10300', # protected { content_type: text/plain }
{ alg: HMAC 256/256, # unprotected
kid: h'3233386473613239' # context identifier: "238dsa29"
},
h'48656c6c6f20576f726c6421', # payload: "Hello World!\n"
h'....', # tag: HMAC(options+protected+payload, secret)
[ [ h'', {}, h'' ] ] # recipients
]
]]></artwork></figure>
<t><xref target="ex-request01"/> shows a PUT request from C to S for resource r
containing a payload of type ‘application/cose+cbor’ that carries a
COSE_Mac structure to integrity-protect the request using the MAC key
from a previously established security context with identifier
‘238dsa29’. As the security context can be determined from the context
identifier, an empty COSE_recipient structure is used. Note that the
integrity protection not only covers the message payload but also the
content type and various sensitive CoAP options such as Uri-Path that
will be passed to the MAC creation functions as canonicalized
external_aad as described in <xref target="c14n"/>.</t>
<t><list style="hanging">
<t hangText='Note1:'>
Where confidentiality is required, a COSE_encryptData structure will
be used instead of the COSE_Mac structure.</t>
<t hangText='Note2:'>
COSE_enveloped may be used instead of COSE_encryptData when
dynamically generated session keys should be used, e.g. with
protected piggybacked content.</t>
<t hangText='Note3:'>
As transferring COSE objects as the CoAP message payload is not
always possible (e.g. in GET requests), this specification defines
two new CoAP options ‘Authorization’ and ‘Authorization-Format’ that
can be used to convey the authorization information.</t>
</list></t>
<t>To retrieve a resource representation using the request method GET,
the authorization information is conveyed in an Authorization
attribute as shown in <xref target="ex-auth-attr"/>.</t>
<figure title="Example for CoAP Request with Authorization Option" anchor="ex-auth-attr"><artwork><![CDATA[
GET /r
Authorization: [ h'', # protected (empty)
{ alg: HMAC 256/256, # unprotected
kid: h'3233386473613239' # context identifier: "238dsa29"
},
nil, # payload (empty)
h'....', # tag: HMAC(options+protected, secret)
[ [ h'', {}, h'' ] ] # recipients
]
]]></artwork></figure>
<t>The request in <xref target="ex-auth-attr"/> uses the default Authorization-Format
‘application-cose’ for the contents of the Authorization option which
is a COSE_Mac structure. As in <xref target="ex-request01"/> the MAC key from a
previously established security context with identifier ‘238dsa29’ is
used and an empty COSE_recipient structure is used. The integrity
protection for this request not only covers the message payload but
also the content type and various sensitive CoAP options such as
Uri-Path that will be passed to the MAC creation functions as
external_aad. The external_aad MUST be constructed as CBOR bytes
containing a canonicalized CoAP message as specified in <xref target="c14n"/>.</t>
</section>
<section anchor="responding-to-an-authorized-request" title="Responding to an Authorized Request">
<t>A response to an Authorized Request that uses this DCAF profile MUST
be protected according to the principals’ security objectives covered by
the existing security context between C and S. Usually, this means
that a resource representation returned by S in the response is
wrapped into a COSE_encryptData or COSE_enveloped structure. A
protected response to an authorized GET request is depicted in
<xref target="ex-get-response"/>.</t>
<t><list style="hanging">
<t hangText='Note:'>
For AEAD ciphers, confidentiality and integrity can be achieved in
one encryption step. For other cipher suites, it may be more
convenient to use a COSE_Mac structure when only message integrity
is required.</t>
</list></t>
<figure title="Example for a Protected Response Containing a Resource Representation" anchor="ex-get-response"><artwork><![CDATA[
2.05 Content
Content-Format: application/cose+cbor
[ h'a10300', # protected { content_type: text/plain }
{ alg: AES-CCM-16-64-128, # unprotected
nonce: h'77cd8a8047b7af7113bb074bcc', # nonce
},
h'TBD:encrypted payload w/ tag', # ciphertext
# recipients:
[ [ h'', # protected (absent for AE alg.)
{ alg: A128KW, # unprotected
kid: h'3233386473613239' # context identifier: "238dsa29"
},
h'fec31142bc...' # encrypted session key
] ]
]
]]></artwork></figure>
</section>
</section>
<section anchor="establishing-a-security-context" title="Establishing a Security Context">
<t><xref target="authorized-requests"/> illustrates the use of CBOR Encoded Message
Syntax for sending Authorized Requests and Responses. Before this
communication can take place the security context must be established
using the COSE DCAF message types as described in this section. This
section describes
the basic message flow as outlined in <xref target="I-D.gerdes-ace-dcaf-authorize"/>, but using the CBOR Encoded
Message Syntax to convey the DCAF information instead of DTLS.</t>
<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 has been
granted so far.
S MUST treat any CoAP request as an Unauthorized Resource Request message
when any of the following holds:</t>
<t><list style="symbols">
<t>The request has been received unprotected.</t>
<t>The security context for the received request is unknown.</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 has been granted and a security context 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"/>. S MAY include
a protected piggybacked response with the SAM Information Message in the
Unauthorized Resource Request message, as discussed in <xref target="piggyback"/>.</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 naive 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 a URI
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 a SAM Information message
payload using stylized CBOR diagnostic notation. (Refer to <xref target="I-D.gerdes-ace-dcaf-authorize"/> 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: [ 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 {{face}} for more details concerning the usage of time stamps to
ensure freshness of access tickets.--></t>
<t>The content format accepted by S is ‘application/cose+cbor’ defined in
<xref target="I-D.ietf-cose-msg"/> to indicate DCAF over CBOR Encoded Message
Syntax as defined in this document.</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)
81 # array(2)
19 03e7 # unsigned(999) (=cose+cbor)
]]></artwork></figure>
</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 COSE_encryptData or COSE_enveloped
structure with content-type application/dcaf+cbor 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="I-D.gerdes-ace-dcaf-authorize"/>.</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 as described in <xref target="I-D.gerdes-ace-dcaf-authorize"/>. An example Access Request from C
to CAM is depicted in <xref target="authorization-message-example"/>. (Refer to
<xref target="I-D.gerdes-ace-dcaf-authorize"/> 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/cose+cbor
[ h'a1031862', # protected { content_type: application/dcaf+cbor }
{ alg: AES-CCM-16-64-128 # unprotected
nonce: h'd6150b90e6f0eb5be42164062c', # nonce
},
h'TBD:encrypted payload w/ tag', # encrypted DCAF payload
# recipients:
[ [ h'', # protected (absent for AE algorithm)
{ alg: A128KW, # unprotected
kid: h'383261622e6161733432' # context identifier: "82ab.aas42"
},
h'52ff9ed52d...' # encrypted session key
] ]
]
]]></artwork></figure>
<t>The example shows an Access Request message with COSE payload that
contains the encrypted and integrity protected DCAF object shown in
<xref target="ex-access-request-payload"/>. To integrity-protect the CoAP message
header fields the canonicalized CoAP message MUST be included in the
external_aad structure. The recipient structure of this message
contains a wrapped key that is encrypted with the key material for the
common security context of C and CAM that is identified by the kid
parameter. If the client cannot create a random session key, it could
send a COSE_encryptData structure instead using the
direct encryption method. The benefit of
wrapping the content encryption key is that CAM can pass the encrypted
content on to SAM needing to wrap the content encryption key with the
key material used in the common security context with SAM.</t>
<figure title="Access Request Payload Example" anchor="ex-access-request-payload"><artwork><![CDATA[
{
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 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>CAM processes any Access Request message received from C as defined in
<xref target="I-D.gerdes-ace-dcaf-authorize"/>. If CAM decides to send a Ticket Request message to the SAM
provided in the Access Request, it has to establish a security context
with SAM. 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”), or a COSE_enveloped structure using SAM’s public key to encrypt
the content encryption key.</t>
</section>
<section anchor="ticket-grant-message" title="Ticket Grant Message">
<t>A Ticket Request Message is processed and responded to as specified in
<xref target="I-D.gerdes-ace-dcaf-authorize"/>. SAM MUST use the same security context that has been used
by CAM to transfer the Ticket Request message, i.e., if the Ticket
Request message was received over DTLS, the response MUST be sent over
the same DTLS session. This restriction is alleviated slightly when
using COSE where the only requirement is that
the CoAP response can be mapped to the respective request.</t>
</section>
<section anchor="ticket-transfer" title="Ticket Transfer Message">
<t>A Ticket Transfer message is sent by CAM to deliver the authorization
information from SAM in a Ticket Grant message to the requesting
client C. Processing of the Ticket Grant message and construction of
the Ticket Transfer message is done as specified in <xref target="I-D.gerdes-ace-dcaf-authorize"/>. An
example for a Ticket Transfer message in response to the Ticket Access
Request described in <xref target="access-request"/> is depicted in
<xref target="fig:ticket-transfer"/>.</t>
<figure title="Example Ticket Transfer Message Encoded as COSE Message" anchor="fig:ticket-transfer"><artwork><![CDATA[
2.05 Content
Content-Format: application/cose+cbor
[ h'a1031862', # protected { content_type: application/dcaf+cbor }
{ alg: AES-CCM-16-64-128 # unprotected
nonce: h'd259f53783993e757ec9d1d957', # nonce
kid: h'383261622e6161733432' # context identifier: "82ab.aas42"
},
h'TBD:encrypted payload w/ tag', # encrypted DCAF payload
]
]]></artwork></figure>
<t>In this example, a COSE_encryptData structure is used to avoid
including a recipients structure. The kid parameter referring to the
same security context that has been used for the Access Request
message is included with the unprotected header of the
COSE_encryptData structure. The encrypted DCAF payload contains the
required ticket Face and Verifier as defined in <xref target="I-D.gerdes-ace-dcaf-authorize"/>. In this
example, the ticket shown in <xref target="ex:ticket-transfer-payload"/> is passed
in the payload field of the COSE_encryptData structure shown in
<xref target="fig:ticket-transfer"/>.</t>
<figure title="Example Ticket Transfer Message" anchor="ex:ticket-transfer-payload"><artwork><![CDATA[
{ 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="security-association-between-c-and-s" title="Security Association between C and S">
<t>The information contained in a Ticket Transfer message (i.e. a ticket
a Face and Client Information) can be used by C to establish a
security context with S. While <xref target="I-D.gerdes-ace-dcaf-authorize"/> defines how to infer a DTLS
pre-shared key, this specification uses the verifier as MAC key in a COSE_MAC
structure as described below. This structure comprises the payload of
a POST request to the authorization resource hosted by S as described
in <xref target="auth-info"/>.</t>
<t><list style="numbers">
<t>The CoAP request is protected as external_aad as
described in <xref target="c14n"/>.</t>
<t>The protected header contains the parameter content_type with
the value ‘application/dcaf+cbor’.</t>
<t>The unprotected header contains the alg parameter that denotes the
MAC algorithm that is used at the content level.</t>
<t>The payload field of the COSE_MAC structure
contains the ticket Face encoded as canonicalized CBOR structure,
and the tag field is constructed using the verifier from the Ticket
Transfer message as secret, and the recipients structure is filled
with empty values.</t>
</list></t>
<t>The authorization for uploading authorization tickets is tied to a key
that is associated to the particular ticket Face and MUST be generated
by the authorized SAM. When receiving a POST request to the auth-info
resource, S generates its own version of the verifier using the
information contained in Face.</t>
<t>The distributed key derivation method is defined as follows:</t>
<t><list style="symbols">
<t>SAM and S both generate the verifier 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 content encryption key. 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).</t>
<t>SAM MUST include a representation of the session key in the Verifier.</t>
<t>As SAM and C do not have a shared secret, the Verifier MUST
be transmitted to C using protected channels.</t>
<t>SAM MUST NOT include a representation of the Verifier in Face.</t>
<t>SAM MUST NOT encrypt Face.</t>
</list></t>
<t>Once S has validated the contents of the POST request using the
locally generated verifier, it creates a new resource that represents
this authorization and returns the Location-Path of this new
resource. This path then can be used by C to update the authorization
information and MUST be used by C in the kid parameter to identify
this security context as described in <xref target="authorized-requests"/>.</t>
<t>An example for the POST request and corresponding 2.01 response is
given in <xref target="authorization-creation"/>. The Location-Path returned by S
is subsequently used by C as identifier for the security context tied
to this authorization.</t>
<figure title="Example POST to S's auth-info Resource and Response" anchor="authorization-creation"><artwork><![CDATA[
C --> S
POST /authorize
Content-Format: application/cose+cbor
[ h'a1031862', # protected { content_type: application/dcaf+cbor }
{ alg: HMAC 256/256 }, # unprotected
h'{ SAI: [ "/s/tempC" ... }', # DCAF payload wrapped in CBOR binary
h'....', # tag: HMAC(options+protected+payload, secret)
[ [ h'', {}, h'' ] ] # recipients
]
S --> C
2.01 Created
Content-Format: application/cose+cbor
Location-Path: 238dsa29
Authorization: [ h'a1031862', # protected
{ alg: HMAC 256/256 }, # unprotected
h'', # empty payload
h'....', # tag: HMAC(options+protected, secret)
[ [ h'', {}, h'' ] ] # recipients
]
]]></artwork></figure>
<!-- FIXME: describe how to get update authorization -->
</section>
</section>
<section anchor="piggyback" title="Piggybacked Protected Content">
<t>Piggybacked protected content was introduced in <xref target="I-D.gerdes-ace-dcaf-authorize"/> as a
possibility to deliver an encrypted resource representation without
having to maintain authorization information for the respective
resource. Once a requesting client has received the 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>
</section>
<section anchor="coap-options-authorization-and-authorization-format" title="CoAP Options Authorization and Authorization-Format">
<t>The options Authorization and Authorization-Format have the
properties shown in <xref target="tbl-options"/>.</t>
<!-- C=Critical, U=Unsafe, N=No-Cache-Key, R=Repeatable-->
<texttable title="The Options Authorization and Authorization-Format" anchor="tbl-options">
<ttcol align='center'>No.</ttcol>
<ttcol align='center'>C</ttcol>
<ttcol align='center'>U</ttcol>
<ttcol align='center'>N</ttcol>
<ttcol align='center'>R</ttcol>
<ttcol align='left'>Name</ttcol>
<ttcol align='left'>Format</ttcol>
<ttcol align='left'>Length</ttcol>
<ttcol align='left'>Default</ttcol>
<c>64</c>
<c> </c>
<c> </c>
<c> </c>
<c> </c>
<c>Authorization</c>
<c>opaque</c>
<c>1-1034</c>
<c>(none)</c>
<c>65</c>
<c>x</c>
<c> </c>
<c> </c>
<c> </c>
<c>Authorization-Format</c>
<c>uint</c>
<c>0-2</c>
<c>application/cose+cbor</c>
</texttable>
</section>
<section anchor="c14n" title="Canonicalization of the CoAP Message Header">
<t>This section describes the canonicalization of parts from the CoAP
message for integrity protection. As intermediaries such as caching
proxies may change certain fields in a CoAP message, only those fields
are considered that must not be changed by intermediaries. The
canonicalized CoAP message then serves as external_aad to the COSE
MAC_structure and Enc_structure as used in this specification. The
canonicalized CoAP message is constructed as follows:</t>
<figure title="Canonicalized CoAP Message Header" anchor="c14n-header"><artwork><![CDATA[
0 1 2 3
0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|Ver| 0 | 0 | Code | Options to protect (if any) ...
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
]]></artwork></figure>
<t>As shown in <xref target="c14n-header"/>, only the version bits and the message
code from the CoAP base header are relevant for integrity
protection.
<cref anchor="_3">Editor’s note: message type, token and id can change on the way.</cref> From the list of options that a message might have,
only the following options are to be included with the canonicalized
message.
<cref anchor="_4">TBD</cref></t>
<t><list style="symbols">
<t>If-Match</t>
<t>Uri-Host</t>
<t>ETag</t>
<t>If-None-Match</t>
<t>Observe</t>
<t>Uri-Port</t>
<t>Location-Path</t>
<t>Uri-Path</t>
<t>Uri-Query</t>
<t>Accept</t>
<t>Location-Query</t>
<t>Proxy-Uri <!-- probably not --></t>
<t>Proxy-Scheme <!-- probably not --></t>
<t>Size1</t>
</list></t>
<!-- TODO: add No-Response, Block1, Block2 -->
<t><list style="hanging">
<t hangText='Note:'>
The Content-Format must be contained in the protected header of the
MAC_structure or Enc_structure and hence is not required here.</t>
</list></t>
<t>An application that requires integrity protection of new options that
are not listed here must add a critical-options header field to the
MAC_structure or Enc_structure containing a CBOR array with the
additional options to protect in ascending numerical order.</t>
<t><xref target="ex-c14n-custom-opt"/> shows an example for a POST request to upload
SenML <xref target="I-D.jennings-core-senml"/> sensor readings to a remote
server. The protected header in the COSE_Mac structure contains a
‘required options’ entry that lists the custom option X-Something,
hence the external_aad would contain a canonicalized message header
that consists of the CoAP version number, the method POST, Uri-Path
‘measurements’, Uri-Path ‘current’, and X-Something 1234 as
delta-encoded options in ascending order as specified in Section 3.1
of <xref target="RFC7252"/>.</t>
<figure title="Example Message with Protected Custom Option" anchor="ex-c14n-custom-opt"><artwork><![CDATA[
POST /measurements/current
Content-Format: application/senml+cbor
X-Something: 1234
Authorization: [
# protected { content_type: application/senml+cbor,
# "required options": [ X-Something ] }
h'a203766170706c69636174696f6e2f73656e6d6...',
{ alg: HMAC 256/256, # unprotected
kid: h'3233386473613239' # context identifier: "238dsa29"
},
h'a2231a4eaecc5d....', # payload: "{ -4: 1320078..."
h'....', # tag: HMAC(options+protected+payload, secret)
[ [ nil, {}, h'' ] ] # recipients
]
{ -4: 1320078429,
-2: [{0: "temperature", 2: 272, 1: "Cel"},
{0: "humidity", 2: 80, 1: "%RH"}]
}
]]></artwork></figure>
</section>
<section anchor="auth-info" title="The “auth-info” Link Relation">
<t>This section defines a resource type “auth-info” that can be used by
clients to establish a new security context with S using the
authorization information retrieved from SAM. When used with the
parameter rt in a web link, “auth-info” indicates that the
corresponding target URI can be used in a POST message to upload
the authorization information contained in the request payload.</t>
<t>The following example shows the web link used by S in this
document to accept authorization information created by SAM.</t>
<figure><artwork><![CDATA[
<authorize>;rt="auth-info";ct=TBD1,ct_cose_msg
;title="Upload Authorization Information"
]]></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-info";ct=TBD1,ct_cose_msg
;ep="node138"
;title="Upload Authorization Information"
;anchor="coaps://s.example.com/"
]]></artwork></figure>
</section>
<section anchor="security-considerations" title="Security Considerations">
<t>The SAM Information message cannot be protected as no security context
between S and C is present at the time the message is sent. An
attacker thus can inject a SAM Information message listing a different
SAM URI to trick C into disclosing the intended action. Where this is
an issue, C could retrieve the SAM URI from a resource directory as
described in <xref target="I-D.gerdes-ace-dcaf-authorize"/>.</t>
</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="coap-option-registration" title="CoAP Option Registration">
<t>IANA is requested to add the following entries to the CoAP Option Numbers
registry:</t>
<texttable>
<ttcol align='center'>Number</ttcol>
<ttcol align='left'>Name</ttcol>
<ttcol align='left'>Reference</ttcol>
<c>64</c>
<c>Authorization</c>
<c>&SELF;</c>
<c>65</c>
<c>Authorization-Format</c>
<c>&SELF;</c>
</texttable>
</section>
</section>
<section anchor="acknowledgements" title="Acknowledgements">
<t>The authors would like to thank Carsten Bormann for his valuable input and
feedback.</t>
<!-- LocalWords: Datagram CoAP CoRE DTLS DCAF DCAF's introducer URI
-->
<!-- LocalWords: namespace Verifier JSON timestamp timestamps PSK
-->
<!-- LocalWords: decrypt UTC decrypted whitespace preshared HMAC
-->
<!-- Local Variables: -->
<!-- coding: utf-8 -->
<!-- End: -->
</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='I-D.gerdes-ace-dcaf-authorize'>
<front>
<title>Delegated CoAP Authentication and Authorization Framework (DCAF)</title>
<author initials='S' surname='Gerdes' fullname='Stefanie Gerdes'>
<organization />
</author>
<author initials='O' surname='Bergmann' fullname='Olaf Bergmann'>
<organization />
</author>
<author initials='C' surname='Bormann' fullname='Carsten Bormann'>
<organization />
</author>
<date month='September' day='10' year='2015' />
<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>
<seriesInfo name='Internet-Draft' value='draft-gerdes-ace-dcaf-authorize-03' />
<format type='TXT'
target='http://www.ietf.org/internet-drafts/draft-gerdes-ace-dcaf-authorize-03.txt' />
</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>
</references>
<references title='Informative References'>
<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='I-D.ietf-cose-msg'>
<front>
<title>CBOR Encoded Message Syntax</title>
<author initials='J' surname='Schaad' fullname='Jim Schaad'>
<organization />
</author>
<date month='October' day='17' 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-06' />
<format type='TXT'
target='http://www.ietf.org/internet-drafts/draft-ietf-cose-msg-06.txt' />
</reference>
<reference anchor='I-D.ietf-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='October' day='19' 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 identifies the elements that an architecture needs to address, providing a problem statement, for authentication and authorization in these networks.</t></abstract>
</front>
<seriesInfo name='Internet-Draft' value='draft-ietf-ace-actors-02' />
<format type='TXT'
target='http://www.ietf.org/internet-drafts/draft-ietf-ace-actors-02.txt' />
</reference>
<reference anchor='I-D.jennings-core-senml'>
<front>
<title>Media Types for Sensor Markup Language (SENML)</title>
<author initials='C' surname='Jennings' fullname='Cullen Jennings'>
<organization />
</author>
<author initials='Z' surname='Shelby' fullname='Zach Shelby'>
<organization />
</author>
<author initials='J' surname='Arkko' fullname='Jari Arkko'>
<organization />
</author>
<author initials='A' surname='Keranen' fullname='Ari Keranen'>
<organization />
</author>
<date month='October' day='19' year='2015' />
<abstract><t>This specification defines media types for representing simple sensor measurements and device parameters in the Sensor Markup Language (SenML). Representations are defined in JavaScript Object Notation (JSON), Concise Binary Object Representation (CBOR), eXtensible Markup Language (XML), and Efficient XML Interchange (EXI), which share the common SenML data model. A simple sensor, such as a temperature sensor, could use this media type in protocols such as HTTP or CoAP to transport the measurements of the sensor or to be configured.</t></abstract>
</front>
<seriesInfo name='Internet-Draft' value='draft-jennings-core-senml-02' />
<format type='TXT'
target='http://www.ietf.org/internet-drafts/draft-jennings-core-senml-02.txt' />
</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>
</references>
</back>
</rfc>
| PAFTECH AB 2003-2026 | 2026-04-23 09:27:04 |