< draft-ietf-ace-oauth-authz-16.txt   draft-ietf-ace-oauth-authz-17.txt >
ACE Working Group L. Seitz ACE Working Group L. Seitz
Internet-Draft RISE Internet-Draft RISE
Intended status: Standards Track G. Selander Intended status: Standards Track G. Selander
Expires: April 5, 2019 Ericsson Expires: May 30, 2019 Ericsson
E. Wahlstroem E. Wahlstroem
S. Erdtman S. Erdtman
Spotify AB Spotify AB
H. Tschofenig H. Tschofenig
Arm Ltd. Arm Ltd.
October 2, 2018 November 26, 2018
Authentication and Authorization for Constrained Environments (ACE) Authentication and Authorization for Constrained Environments (ACE)
using the OAuth 2.0 Framework (ACE-OAuth) using the OAuth 2.0 Framework (ACE-OAuth)
draft-ietf-ace-oauth-authz-16 draft-ietf-ace-oauth-authz-17
Abstract Abstract
This specification defines a framework for authentication and This specification defines a framework for authentication and
authorization in Internet of Things (IoT) environments called ACE- authorization in Internet of Things (IoT) environments called ACE-
OAuth. The framework is based on a set of building blocks including OAuth. The framework is based on a set of building blocks including
OAuth 2.0 and CoAP, thus making a well-known and widely used OAuth 2.0 and CoAP, thus making a well-known and widely used
authorization solution suitable for IoT devices. Existing authorization solution suitable for IoT devices. Existing
specifications are used where possible, but where the constraints of specifications are used where possible, but where the constraints of
IoT devices require it, extensions are added and profiles are IoT devices require it, extensions are added and profiles are
skipping to change at page 1, line 45 skipping to change at page 1, line 45
Internet-Drafts are working documents of the Internet Engineering Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF). Note that other groups may also distribute Task Force (IETF). Note that other groups may also distribute
working documents as Internet-Drafts. The list of current Internet- working documents as Internet-Drafts. The list of current Internet-
Drafts is at http://datatracker.ietf.org/drafts/current/. Drafts is at http://datatracker.ietf.org/drafts/current/.
Internet-Drafts are draft documents valid for a maximum of six months Internet-Drafts are draft documents valid for a maximum of six months
and may be updated, replaced, or obsoleted by other documents at any and may be updated, replaced, or obsoleted by other documents at any
time. It is inappropriate to use Internet-Drafts as reference time. It is inappropriate to use Internet-Drafts as reference
material or to cite them other than as "work in progress." material or to cite them other than as "work in progress."
This Internet-Draft will expire on April 5, 2019. This Internet-Draft will expire on May 30, 2019.
Copyright Notice Copyright Notice
Copyright (c) 2018 IETF Trust and the persons identified as the Copyright (c) 2018 IETF Trust and the persons identified as the
document authors. All rights reserved. document authors. All rights reserved.
This document is subject to BCP 78 and the IETF Trust's Legal This document is subject to BCP 78 and the IETF Trust's Legal
Provisions Relating to IETF Documents Provisions Relating to IETF Documents
(http://trustee.ietf.org/license-info) in effect on the date of (http://trustee.ietf.org/license-info) in effect on the date of
publication of this document. Please review these documents publication of this document. Please review these documents
skipping to change at page 2, line 26 skipping to change at page 2, line 26
include Simplified BSD License text as described in Section 4.e of include Simplified BSD License text as described in Section 4.e of
the Trust Legal Provisions and are provided without warranty as the Trust Legal Provisions and are provided without warranty as
described in the Simplified BSD License. described in the Simplified BSD License.
Table of Contents Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 4 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 4
2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 5 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 5
3. Overview . . . . . . . . . . . . . . . . . . . . . . . . . . 5 3. Overview . . . . . . . . . . . . . . . . . . . . . . . . . . 5
3.1. OAuth 2.0 . . . . . . . . . . . . . . . . . . . . . . . . 6 3.1. OAuth 2.0 . . . . . . . . . . . . . . . . . . . . . . . . 6
3.2. CoAP . . . . . . . . . . . . . . . . . . . . . . . . . . 9 3.2. CoAP . . . . . . . . . . . . . . . . . . . . . . . . . . 10
4. Protocol Interactions . . . . . . . . . . . . . . . . . . . . 10 4. Protocol Interactions . . . . . . . . . . . . . . . . . . . . 10
5. Framework . . . . . . . . . . . . . . . . . . . . . . . . . . 14 5. Framework . . . . . . . . . . . . . . . . . . . . . . . . . . 14
5.1. Discovering Authorization Servers . . . . . . . . . . . . 15 5.1. Discovering Authorization Servers . . . . . . . . . . . . 15
5.1.1. Unauthorized Resource Request Message . . . . . . . . 15 5.1.1. Unauthorized Resource Request Message . . . . . . . . 15
5.1.2. AS Information . . . . . . . . . . . . . . . . . . . 16 5.1.2. AS Information . . . . . . . . . . . . . . . . . . . 16
5.2. Authorization Grants . . . . . . . . . . . . . . . . . . 17 5.2. Authorization Grants . . . . . . . . . . . . . . . . . . 17
5.3. Client Credentials . . . . . . . . . . . . . . . . . . . 18 5.3. Client Credentials . . . . . . . . . . . . . . . . . . . 18
5.4. AS Authentication . . . . . . . . . . . . . . . . . . . . 18 5.4. AS Authentication . . . . . . . . . . . . . . . . . . . . 18
5.5. The Authorization Endpoint . . . . . . . . . . . . . . . 18 5.5. The Authorization Endpoint . . . . . . . . . . . . . . . 19
5.6. The Token Endpoint . . . . . . . . . . . . . . . . . . . 19 5.6. The Token Endpoint . . . . . . . . . . . . . . . . . . . 19
5.6.1. Client-to-AS Request . . . . . . . . . . . . . . . . 19 5.6.1. Client-to-AS Request . . . . . . . . . . . . . . . . 20
5.6.2. AS-to-Client Response . . . . . . . . . . . . . . . . 22 5.6.2. AS-to-Client Response . . . . . . . . . . . . . . . . 22
5.6.3. Error Response . . . . . . . . . . . . . . . . . . . 24 5.6.3. Error Response . . . . . . . . . . . . . . . . . . . 24
5.6.4. Request and Response Parameters . . . . . . . . . . . 25 5.6.4. Request and Response Parameters . . . . . . . . . . . 25
5.6.4.1. Grant Type . . . . . . . . . . . . . . . . . . . 25 5.6.4.1. Grant Type . . . . . . . . . . . . . . . . . . . 25
5.6.4.2. Token Type . . . . . . . . . . . . . . . . . . . 26 5.6.4.2. Token Type . . . . . . . . . . . . . . . . . . . 26
5.6.4.3. Profile . . . . . . . . . . . . . . . . . . . . . 26 5.6.4.3. Profile . . . . . . . . . . . . . . . . . . . . . 26
5.6.5. Mapping Parameters to CBOR . . . . . . . . . . . . . 27 5.6.5. Mapping Parameters to CBOR . . . . . . . . . . . . . 27
5.7. The Introspection Endpoint . . . . . . . . . . . . . . . 27 5.7. The Introspection Endpoint . . . . . . . . . . . . . . . 27
5.7.1. Introspection Request . . . . . . . . . . . . . . . . 28 5.7.1. Introspection Request . . . . . . . . . . . . . . . . 28
5.7.2. Introspection Response . . . . . . . . . . . . . . . 29 5.7.2. Introspection Response . . . . . . . . . . . . . . . 29
5.7.3. Error Response . . . . . . . . . . . . . . . . . . . 30 5.7.3. Error Response . . . . . . . . . . . . . . . . . . . 30
5.7.4. Mapping Introspection parameters to CBOR . . . . . . 30 5.7.4. Mapping Introspection parameters to CBOR . . . . . . 31
5.8. The Access Token . . . . . . . . . . . . . . . . . . . . 31 5.8. The Access Token . . . . . . . . . . . . . . . . . . . . 31
5.8.1. The Authorization Information Endpoint . . . . . . . 32 5.8.1. The Authorization Information Endpoint . . . . . . . 32
5.8.2. Client Requests to the RS . . . . . . . . . . . . . . 33 5.8.1.1. Verifying an Access Token . . . . . . . . . . . . 33
5.8.3. Token Expiration . . . . . . . . . . . . . . . . . . 33 5.8.1.2. Protecting the Authzorization Information
6. Security Considerations . . . . . . . . . . . . . . . . . . . 34 Endpoint . . . . . . . . . . . . . . . . . . . . 34
6.1. Unprotected AS Information . . . . . . . . . . . . . . . 35 5.8.2. Client Requests to the RS . . . . . . . . . . . . . . 34
6.2. Use of Nonces for Replay Protection . . . . . . . . . . . 36 5.8.3. Token Expiration . . . . . . . . . . . . . . . . . . 35
6.3. Combining profiles . . . . . . . . . . . . . . . . . . . 36 6. Security Considerations . . . . . . . . . . . . . . . . . . . 36
6.4. Error responses . . . . . . . . . . . . . . . . . . . . . 36 6.1. Unprotected AS Information . . . . . . . . . . . . . . . 37
7. Privacy Considerations . . . . . . . . . . . . . . . . . . . 36 6.2. Minimal security requirements for communication . 37
8. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 37 6.3. Use of Nonces for Replay Protection . . . . . . . . . . . 38
8.1. Authorization Server Information . . . . . . . . . . . . 37 6.4. Combining profiles . . . . . . . . . . . . . . . . . . . 39
8.2. OAuth Extensions Error Registration . . . . . . . . . . . 38 6.5. Unprotected Information . . . . . . . . . . . . . . . . . 39
8.3. OAuth Error Code CBOR Mappings Registry . . . . . . . . . 38 6.6. Denial of service against or with Introspection . . 39
8.4. OAuth Grant Type CBOR Mappings . . . . . . . . . . . . . 39 7. Privacy Considerations . . . . . . . . . . . . . . . . . . . 40
8.5. OAuth Access Token Types . . . . . . . . . . . . . . . . 39 8. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 41
8.6. OAuth Token Type CBOR Mappings . . . . . . . . . . . . . 39 8.1. Authorization Server Information . . . . . . . . . . . . 41
8.6.1. Initial Registry Contents . . . . . . . . . . . . . . 40 8.2. OAuth Extensions Error Registration . . . . . . . . . . . 41
8.7. ACE Profile Registry . . . . . . . . . . . . . . . . . . 40 8.3. OAuth Error Code CBOR Mappings Registry . . . . . . . . . 42
8.8. OAuth Parameter Registration . . . . . . . . . . . . . . 41 8.4. OAuth Grant Type CBOR Mappings . . . . . . . . . . . . . 42
8.9. OAuth CBOR Parameter Mappings Registry . . . . . . . . . 41 8.5. OAuth Access Token Types . . . . . . . . . . . . . . . . 43
8.10. OAuth Introspection Response Parameter Registration . . . 42 8.6. OAuth Token Type CBOR Mappings . . . . . . . . . . . . . 43
8.11. Introspection Endpoint CBOR Mappings Registry . . . . . . 42 8.6.1. Initial Registry Contents . . . . . . . . . . . . . . 43
8.12. JSON Web Token Claims . . . . . . . . . . . . . . . . . . 42 8.7. ACE Profile Registry . . . . . . . . . . . . . . . . . . 44
8.13. CBOR Web Token Claims . . . . . . . . . . . . . . . . . . 43 8.8. OAuth Parameter Registration . . . . . . . . . . . . . . 44
8.14. Media Type Registrations . . . . . . . . . . . . . . . . 44 8.9. Token Endpoint CBOR Mappings Registry . . . . . . . . . . 44
8.15. CoAP Content-Format Registry . . . . . . . . . . . . . . 45 8.10. OAuth Introspection Response Parameter Registration . . . 45
9. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 45 8.11. Introspection Endpoint CBOR Mappings Registry . . . . . . 45
10. References . . . . . . . . . . . . . . . . . . . . . . . . . 45 8.12. JSON Web Token Claims . . . . . . . . . . . . . . . . . . 46
10.1. Normative References . . . . . . . . . . . . . . . . . . 45 8.13. CBOR Web Token Claims . . . . . . . . . . . . . . . . . . 47
10.2. Informative References . . . . . . . . . . . . . . . . . 47 8.14. Media Type Registrations . . . . . . . . . . . . . . . . 47
Appendix A. Design Justification . . . . . . . . . . . . . . . . 50 8.15. CoAP Content-Format Registry . . . . . . . . . . . . . . 48
Appendix B. Roles and Responsibilities . . . . . . . . . . . . . 53 9. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 48
Appendix C. Requirements on Profiles . . . . . . . . . . . . . . 55 10. References . . . . . . . . . . . . . . . . . . . . . . . . . 49
Appendix D. Assumptions on AS knowledge about C and RS . . . . . 56 10.1. Normative References . . . . . . . . . . . . . . . . . . 49
Appendix E. Deployment Examples . . . . . . . . . . . . . . . . 56 10.2. Informative References . . . . . . . . . . . . . . . . . 51
E.1. Local Token Validation . . . . . . . . . . . . . . . . . 57 Appendix A. Design Justification . . . . . . . . . . . . . . . . 53
E.2. Introspection Aided Token Validation . . . . . . . . . . 61 Appendix B. Roles and Responsibilities . . . . . . . . . . . . . 57
Appendix F. Document Updates . . . . . . . . . . . . . . . . . . 65 Appendix C. Requirements on Profiles . . . . . . . . . . . . . . 59
F.1. Version -15 to -16 . . . . . . . . . . . . . . . . . . . 65 Appendix D. Assumptions on AS knowledge about C and RS . . . . . 60
F.2. Version -14 to -15 . . . . . . . . . . . . . . . . . . . 65 Appendix E. Deployment Examples . . . . . . . . . . . . . . . . 60
F.3. Version -13 to -14 . . . . . . . . . . . . . . . . . . . 65 E.1. Local Token Validation . . . . . . . . . . . . . . . . . 61
F.4. Version -12 to -13 . . . . . . . . . . . . . . . . . . . 66 E.2. Introspection Aided Token Validation . . . . . . . . . . 65
F.5. Version -11 to -12 . . . . . . . . . . . . . . . . . . . 66 Appendix F. Document Updates . . . . . . . . . . . . . . . . . . 69
F.6. Version -10 to -11 . . . . . . . . . . . . . . . . . . . 66 F.1. Version -15 to -16 . . . . . . . . . . . . . . . . . . . 69
F.7. Version -09 to -10 . . . . . . . . . . . . . . . . . . . 66 F.2. Version -14 to -15 . . . . . . . . . . . . . . . . . . . 69
F.8. Version -08 to -09 . . . . . . . . . . . . . . . . . . . 66 F.3. Version -13 to -14 . . . . . . . . . . . . . . . . . . . 69
F.9. Version -07 to -08 . . . . . . . . . . . . . . . . . . . 67 F.4. Version -12 to -13 . . . . . . . . . . . . . . . . . . . 70
F.10. Version -06 to -07 . . . . . . . . . . . . . . . . . . . 67 F.5. Version -11 to -12 . . . . . . . . . . . . . . . . . . . 70
F.11. Version -05 to -06 . . . . . . . . . . . . . . . . . . . 67 F.6. Version -10 to -11 . . . . . . . . . . . . . . . . . . . 70
F.12. Version -04 to -05 . . . . . . . . . . . . . . . . . . . 67 F.7. Version -09 to -10 . . . . . . . . . . . . . . . . . . . 70
F.13. Version -03 to -04 . . . . . . . . . . . . . . . . . . . 68 F.8. Version -08 to -09 . . . . . . . . . . . . . . . . . . . 70
F.14. Version -02 to -03 . . . . . . . . . . . . . . . . . . . 68 F.9. Version -07 to -08 . . . . . . . . . . . . . . . . . . . 71
F.15. Version -01 to -02 . . . . . . . . . . . . . . . . . . . 68 F.10. Version -06 to -07 . . . . . . . . . . . . . . . . . . . 71
F.16. Version -00 to -01 . . . . . . . . . . . . . . . . . . . 69 F.11. Version -05 to -06 . . . . . . . . . . . . . . . . . . . 71
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 69 F.12. Version -04 to -05 . . . . . . . . . . . . . . . . . . . 71
F.13. Version -03 to -04 . . . . . . . . . . . . . . . . . . . 72
F.14. Version -02 to -03 . . . . . . . . . . . . . . . . . . . 72
F.15. Version -01 to -02 . . . . . . . . . . . . . . . . . . . 72
F.16. Version -00 to -01 . . . . . . . . . . . . . . . . . . . 73
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 73
1. Introduction 1. Introduction
Authorization is the process for granting approval to an entity to Authorization is the process for granting approval to an entity to
access a resource [RFC4949]. The authorization task itself can best access a resource [RFC4949]. The authorization task itself can best
be described as granting access to a requesting client, for a be described as granting access to a requesting client, for a
resource hosted on a device, the resource server (RS). This exchange resource hosted on a device, the resource server (RS). This exchange
is mediated by one or multiple authorization servers (AS). Managing is mediated by one or multiple authorization servers (AS). Managing
authorization for a large number of devices and users can be a authorization for a large number of devices and users can be a
complex task. complex task.
skipping to change at page 7, line 45 skipping to change at page 7, line 46
Refresh tokens are issued to the client by the authorization Refresh tokens are issued to the client by the authorization
server and are used to obtain a new access token when the current server and are used to obtain a new access token when the current
access token becomes invalid or expires, or to obtain additional access token becomes invalid or expires, or to obtain additional
access tokens with identical or narrower scope (access tokens may access tokens with identical or narrower scope (access tokens may
have a shorter lifetime and fewer permissions than authorized by have a shorter lifetime and fewer permissions than authorized by
the resource owner). Issuing a refresh token is optional at the the resource owner). Issuing a refresh token is optional at the
discretion of the authorization server. If the authorization discretion of the authorization server. If the authorization
server issues a refresh token, it is included when issuing an server issues a refresh token, it is included when issuing an
access token (i.e., step (B) in Figure 1). access token (i.e., step (B) in Figure 1).
A refresh token is a string representing the authorization granted A refresh token in OAuth 2.0 is a string representing the
to the client by the resource owner. The string is usually opaque authorization granted to the client by the resource owner. The
to the client. The token denotes an identifier used to retrieve string is usually opaque to the client. The token denotes an
the authorization information. Unlike access tokens, refresh identifier used to retrieve the authorization information. Unlike
tokens are intended for use only with authorization servers and access tokens, refresh tokens are intended for use only with
are never sent to resource servers. authorization servers and are never sent to resource servers.
Proof of Possession Tokens: Proof of Possession Tokens:
An access token may be bound to a cryptographic key, which is then An access token may be bound to a cryptographic key, which is then
used by an RS to authenticate requests from a client. Such tokens used by an RS to authenticate requests from a client. Such tokens
are called proof-of-possession access tokens (or PoP access are called proof-of-possession access tokens (or PoP access
tokens). tokens).
The proof-of-possession (PoP) security concept assumes that the AS The proof-of-possession (PoP) security concept assumes that the AS
acts as a trusted third party that binds keys to access tokens. acts as a trusted third party that binds keys to access tokens.
These so called PoP keys are then used by the client to These so called PoP keys are then used by the client to
demonstrate the possession of the secret to the RS when accessing demonstrate the possession of the secret to the RS when accessing
skipping to change at page 10, line 16 skipping to change at page 10, line 22
While HTTP uses headers and query strings to convey additional While HTTP uses headers and query strings to convey additional
information about a request, CoAP encodes such information into information about a request, CoAP encodes such information into
header parameters called 'options'. header parameters called 'options'.
CoAP supports application-layer fragmentation of the CoAP payloads CoAP supports application-layer fragmentation of the CoAP payloads
through blockwise transfers [RFC7959]. However, blockwise transfer through blockwise transfers [RFC7959]. However, blockwise transfer
does not increase the size limits of CoAP options, therefore data does not increase the size limits of CoAP options, therefore data
encoded in options has to be kept small. encoded in options has to be kept small.
Transport layer security for CoAP can be provided by DTLS 1.2 Transport layer security for CoAP can be provided by DTLS or TLS
[RFC6347] or TLS 1.2 [RFC5246]. CoAP defines a number of proxy [RFC6347][RFC5246][RFC8446] [I-D.ietf-tls-dtls13]. CoAP defines a
operations that require transport layer security to be terminated at number of proxy operations that require transport layer security to
the proxy. One approach for protecting CoAP communication end-to-end be terminated at the proxy. One approach for protecting CoAP
through proxies, and also to support security for CoAP over a communication end-to-end through proxies, and also to support
different transport in a uniform way, is to provide security at the security for CoAP over a different transport in a uniform way, is to
application layer using an object-based security mechanism such as provide security at the application layer using an object-based
COSE [RFC8152]. security mechanism such as COSE [RFC8152].
One application of COSE is OSCORE [I-D.ietf-core-object-security], One application of COSE is OSCORE [I-D.ietf-core-object-security],
which provides end-to-end confidentiality, integrity and replay which provides end-to-end confidentiality, integrity and replay
protection, and a secure binding between CoAP request and response protection, and a secure binding between CoAP request and response
messages. In OSCORE, the CoAP messages are wrapped in COSE objects messages. In OSCORE, the CoAP messages are wrapped in COSE objects
and sent using CoAP. and sent using CoAP.
This framework RECOMMENDS the use of CoAP as replacement for HTTP for This framework RECOMMENDS the use of CoAP as replacement for HTTP for
use in constrained environments. use in constrained environments.
skipping to change at page 14, line 49 skipping to change at page 15, line 6
profile. In ACE framework the AS is expected to manage the profile. In ACE framework the AS is expected to manage the
matching of compatible profile choices between a client and an RS. matching of compatible profile choices between a client and an RS.
The AS informs the client of the selected profile using the The AS informs the client of the selected profile using the
"profile" parameter in the token response. "profile" parameter in the token response.
OAuth 2.0 requires the use of TLS both to protect the communication OAuth 2.0 requires the use of TLS both to protect the communication
between AS and client when requesting an access token; between client between AS and client when requesting an access token; between client
and RS when accessing a resource and between AS and RS if and RS when accessing a resource and between AS and RS if
introspection is used. In constrained settings TLS is not always introspection is used. In constrained settings TLS is not always
feasible, or desirable. Nevertheless it is REQUIRED that the data feasible, or desirable. Nevertheless it is REQUIRED that the data
exchanged with the AS is encrypted and integrity protected. It is exchanged with the AS is encrypted, integrity protected and protected
furthermore REQUIRED that the AS and the endpoint communicating with against message replay. It is also REQUIRED that the AS and the
it (client or RS) perform mutual authentication. endpoint communicating with it (client or RS) perform mutual
authentication. Furthermore it MUST be assured that responses are
bound to the requests in the sense that the receiver of a response
can be certain that the response actually belongs to a certain
request.
Profiles MUST specify how mutual authentication is done, depending Profiles MUST specify a communication security protocol that provides
e.g. on the communication protocol and the credentials used by the the features required above.
client or the RS.
In OAuth 2.0 the communication with the Token and the Introspection In OAuth 2.0 the communication with the Token and the Introspection
endpoints at the AS is assumed to be via HTTP and may use Uri-query endpoints at the AS is assumed to be via HTTP and may use Uri-query
parameters. When profiles of this framework use CoAP instead, this parameters. When profiles of this framework use CoAP instead, this
framework REQUIRES the use of the following alternative instead of framework REQUIRES the use of the following alternative instead of
Uri-query parameters: The sender (client or RS) encodes the Uri-query parameters: The sender (client or RS) encodes the
parameters of its request as a CBOR map and submits that map as the parameters of its request as a CBOR map and submits that map as the
payload of the POST request. Profiles that use CBOR encoding of payload of the POST request. Profiles that use CBOR encoding of
protocol message parameters MUST use the media format 'application/ protocol message parameters MUST use the media format 'application/
ace+cbor', unless the protocol message is wrapped in another Content- ace+cbor', unless the protocol message is wrapped in another Content-
skipping to change at page 19, line 46 skipping to change at page 20, line 10
integer abbreviations for the parameters or their values for integer abbreviations for the parameters or their values for
illustrative purposes. Note that implementations MUST use the illustrative purposes. Note that implementations MUST use the
integer abbreviations and the binary CBOR encoding, if the CBOR integer abbreviations and the binary CBOR encoding, if the CBOR
encoding is used. encoding is used.
5.6.1. Client-to-AS Request 5.6.1. Client-to-AS Request
The client sends a POST request to the token endpoint at the AS. The The client sends a POST request to the token endpoint at the AS. The
profile MUST specify how the communication is protected. The content profile MUST specify how the communication is protected. The content
of the request consists of the parameters specified in Section 4 of of the request consists of the parameters specified in Section 4 of
the OAuth 2.0 specification [RFC6749]. the OAuth 2.0 specification [RFC6749] with the exception of the
"grant_type" parameter, which is OPTIONAL in the context of this
framework (as opposed to REQUIRED in RFC6749). If that parameter is
missing, the default value "client_credentials" is implied.
In addition to these parameters, a client MUST be able to use the In addition to these parameters, a client MUST be able to use the
parameters from [I-D.ietf-ace-oauth-params] in an access token parameters from [I-D.ietf-ace-oauth-params] in an access token
request to the token endpoint and the AS MUST be able to process request to the token endpoint and the AS MUST be able to process
these additional parameters. these additional parameters.
If CBOR is used then this parameter MUST be encoded as a CBOR map. If CBOR is used then this parameter MUST be encoded as a CBOR map.
The "scope" parameter can be formatted as specified in [RFC6749] and The "scope" parameter can be formatted as specified in [RFC6749] and
additionally as a byte array, in order to allow compact encoding of additionally as a byte string, in order to allow compact encoding of
complex scopes. complex scopes.
When HTTP is used as a transport then the client makes a request to When HTTP is used as a transport then the client makes a request to
the token endpoint by sending the parameters using the "application/ the token endpoint by sending the parameters using the "application/
x-www-form-urlencoded" format with a character encoding of UTF-8 in x-www-form-urlencoded" format with a character encoding of UTF-8 in
the HTTP request entity-body, as defined in RFC 6749. the HTTP request entity-body, as defined in RFC 6749.
The following examples illustrate different types of requests for The following examples illustrate different types of requests for
proof-of-possession tokens. proof-of-possession tokens.
Figure 5 shows a request for a token with a symmetric proof-of- Figure 5 shows a request for a token with a symmetric proof-of-
possession key. The content is displayed in CBOR diagnostic possession key. The content is displayed in CBOR diagnostic
notation, without abbreviations for better readability. notation, without abbreviations for better readability. Note that
this example uses the "req_aud" parameter from
[I-D.ietf-ace-oauth-params].
Header: POST (Code=0.02) Header: POST (Code=0.02)
Uri-Host: "as.example.com" Uri-Host: "as.example.com"
Uri-Path: "token" Uri-Path: "token"
Content-Format: "application/ace+cbor" Content-Format: "application/ace+cbor"
Payload: Payload:
{ {
"grant_type" : "client_credentials", "grant_type" : "client_credentials",
"client_id" : "myclient", "client_id" : "myclient",
"req_aud" : "tempSensor4711" "req_aud" : "tempSensor4711"
} }
Figure 5: Example request for an access token bound to a symmetric Figure 5: Example request for an access token bound to a symmetric
key. key.
Figure 6 shows a request for a token with an asymmetric proof-of- Figure 6 shows a request for a token with an asymmetric proof-of-
possession key. Note that in this example COSE is used to provide possession key. Note that in this example OSCORE
object-security, therefore the Content-Format is "application/cose" [I-D.ietf-core-object-security] is used to provide object-security,
wrapping the "application/ace+cbor" type content. Also note that in therefore the Content-Format is "application/oscore" wrapping the
this example the audience is implicitly known by both client and AS. "application/ace+cbor" type content. Also note that in this example
the audience is implicitly known by both client and AS. Furthermore
note that this example uses the "req_cnf" parameter from
[I-D.ietf-ace-oauth-params].
Header: POST (Code=0.02) Header: POST (Code=0.02)
Uri-Host: "as.example.com" Uri-Host: "as.example.com"
Uri-Path: "token" Uri-Path: "token"
Content-Format: "application/cose" Content-Format: "application/oscore"
Payload: Payload:
16( # COSE_ENCRYPTED 0x44025d1 ... (full payload ommitted for brevity) ... 68b3825e
[ h'a1010a', # protected header: {"alg" : "AES-CCM-16-64-128"}
{5 : b64'ifUvZaHFgJM7UmGnjA'}, # unprotected header, IV
b64'WXThuZo6TMCaZZqi6ef/8WHTjOdGk8kNzaIhIQ' # ciphertext
]
) )
Decrypted payload: Decrypted payload:
{ {
"grant_type" : "client_credentials", "grant_type" : "client_credentials",
"client_id" : "myclient", "client_id" : "myclient",
"req_cnf" : { "req_cnf" : {
"COSE_Key" : { "COSE_Key" : {
"kty" : "EC", "kty" : "EC",
"kid" : h'11', "kid" : h'11',
skipping to change at page 21, line 37 skipping to change at page 21, line 42
"y" : b64'IBOL+C3BttVivg+lSreASjpkttcsz+1rb7btKLv8EX4' "y" : b64'IBOL+C3BttVivg+lSreASjpkttcsz+1rb7btKLv8EX4'
} }
} }
} }
Figure 6: Example token request bound to an asymmetric key. Figure 6: Example token request bound to an asymmetric key.
Figure 7 shows a request for a token where a previously communicated Figure 7 shows a request for a token where a previously communicated
proof-of-possession key is only referenced. Note that the client proof-of-possession key is only referenced. Note that the client
performs a password based authentication in this example by performs a password based authentication in this example by
submitting its client_secret (see Section 2.3.1 of [RFC6749]). submitting its client_secret (see Section 2.3.1 of [RFC6749]). Note
that this example uses the "req_aud" and "req_cnf" parameters from
[I-D.ietf-ace-oauth-params].
Header: POST (Code=0.02) Header: POST (Code=0.02)
Uri-Host: "as.example.com" Uri-Host: "as.example.com"
Uri-Path: "token" Uri-Path: "token"
Content-Format: "application/ace+cbor" Content-Format: "application/ace+cbor"
Payload: Payload:
{ {
"grant_type" : "client_credentials", "grant_type" : "client_credentials",
"client_id" : "myclient", "client_id" : "myclient",
"client_secret" : "mysecret234", "client_secret" : "mysecret234",
skipping to change at page 23, line 42 skipping to change at page 23, line 42
| state | RFC 6749 | | state | RFC 6749 |
| error | RFC 6749 | | error | RFC 6749 |
| error_description | RFC 6749 | | error_description | RFC 6749 |
| error_uri | RFC 6749 | | error_uri | RFC 6749 |
| profile | [this document] | | profile | [this document] |
\-------------------+-------------------------------/ \-------------------+-------------------------------/
Figure 8: Access Information parameters Figure 8: Access Information parameters
Figure 9 shows a response containing a token and a "cnf" parameter Figure 9 shows a response containing a token and a "cnf" parameter
with a symmetric proof-of-possession key. with a symmetric proof-of-possession key, which is defined in
[I-D.ietf-ace-oauth-params].
Header: Created (Code=2.01) Header: Created (Code=2.01)
Content-Format: "application/ace+cbor" Content-Format: "application/ace+cbor"
Payload: Payload:
{ {
"access_token" : b64'SlAV32hkKG ... "access_token" : b64'SlAV32hkKG ...
(remainder of CWT omitted for brevity; (remainder of CWT omitted for brevity;
CWT contains COSE_Key in the "cnf" claim)', CWT contains COSE_Key in the "cnf" claim)',
"profile" : "coap_dtls", "profile" : "coap_dtls",
"expires_in" : "3600", "expires_in" : "3600",
skipping to change at page 24, line 39 skipping to change at page 24, line 39
equivalent to the ones for HTTP-based interactions as defined in equivalent to the ones for HTTP-based interactions as defined in
Section 5.2 of [RFC6749], with the following differences: Section 5.2 of [RFC6749], with the following differences:
o When using CBOR the raw payload before being processed by the o When using CBOR the raw payload before being processed by the
communication security protocol MUST be encoded as a CBOR map. communication security protocol MUST be encoded as a CBOR map.
o A response code equivalent to the CoAP code 4.00 (Bad Request) o A response code equivalent to the CoAP code 4.00 (Bad Request)
MUST be used for all error responses, except for invalid_client MUST be used for all error responses, except for invalid_client
where a response code equivalent to the CoAP code 4.01 where a response code equivalent to the CoAP code 4.01
(Unauthorized) MAY be used under the same conditions as specified (Unauthorized) MAY be used under the same conditions as specified
in Section 5.2 of [RFC6749]. in Section 5.2 of [RFC6749].
o The content type (for CoAP-based interactions) or media type (for
HTTP-based interactions) "application/ace+cbor" MUST be used for
the error response.
o The parameters "error", "error_description" and "error_uri" MUST o The parameters "error", "error_description" and "error_uri" MUST
be abbreviated using the codes specified in Figure 12, when a CBOR be abbreviated using the codes specified in Figure 12, when a CBOR
encoding is used. encoding is used.
o The error code (i.e., value of the "error" parameter) MUST be o The error code (i.e., value of the "error" parameter) MUST be
abbreviated as specified in Figure 10, when a CBOR encoding is abbreviated as specified in Figure 10, when a CBOR encoding is
used. used.
/------------------------+-------------\ /------------------------+-------------\
| Name | CBOR Values | | Name | CBOR Values |
|------------------------+-------------| |------------------------+-------------|
skipping to change at page 26, line 38 skipping to change at page 26, line 38
if a CBOR encoding is used. if a CBOR encoding is used.
In this framework the "pop" value for the "token_type" parameter is In this framework the "pop" value for the "token_type" parameter is
the default. The AS may, however, provide a different value. the default. The AS may, however, provide a different value.
5.6.4.3. Profile 5.6.4.3. Profile
Profiles of this framework MUST define the communication protocol and Profiles of this framework MUST define the communication protocol and
the communication security protocol between the client and the RS. the communication security protocol between the client and the RS.
The security protocol MUST provide encryption, integrity and replay The security protocol MUST provide encryption, integrity and replay
protection. Furthermore profiles MUST define proof-of-possession protection. It MUST also provide a binding between requests and
responses. Furthermore profiles MUST define proof-of-possession
methods, if they support proof-of-possession tokens. methods, if they support proof-of-possession tokens.
A profile MUST specify an identifier that MUST be used to uniquely A profile MUST specify an identifier that MUST be used to uniquely
identify itself in the "profile" parameter. The textual identify itself in the "profile" parameter. The textual
representation of the profile identifier is just intended for human representation of the profile identifier is just intended for human
readability and MUST NOT be used in parameters and claims. readability and MUST NOT be used in parameters and claims.
Profiles MAY define additional parameters for both the token request Profiles MAY define additional parameters for both the token request
and the Access Information in the access token response in order to and the Access Information in the access token response in order to
support negotiation or signaling of profile specific parameters. support negotiation or signaling of profile specific parameters.
5.6.5. Mapping Parameters to CBOR 5.6.5. Mapping Parameters to CBOR
If CBOR encoding is used, all OAuth parameters in access token If CBOR encoding is used, all OAuth parameters in access token
requests and responses MUST be mapped to CBOR types as specified in requests and responses MUST be mapped to CBOR types as specified in
Figure 12, using the given integer abbreviation for the map keys. Figure 12, using the given integer abbreviation for the map keys.
Note that we have aligned these abbreviations with the claim Note that we have aligned the abbreviations corresponding to claims
abbreviations defined in [RFC8392]. with the abbreviations defined in [RFC8392].
Note also that abbreviations from -24 to 23 have a 1 byte encoding Note also that abbreviations from -24 to 23 have a 1 byte encoding
size in CBOR. We have thus choosen to assign abbreviations in that size in CBOR. We have thus chosen to assign abbreviations in that
range to parameters we expect to be used most frequently in range to parameters we expect to be used most frequently in
constrained scenarios. constrained scenarios.
/-------------------+----------+---------------------\ /-------------------+----------+---------------------\
| Name | CBOR Key | Value Type | | Name | CBOR Key | Value Type |
|-------------------+----------+---------------------| |-------------------+----------+---------------------|
| access_token | 1 | byte string |
| scope | 9 | text or byte string | | scope | 9 | text or byte string |
| profile | 10 | unsigned integer |
| error | 11 | unsigned integer |
| grant_type | 12 | unsigned integer |
| access_token | 13 | byte string |
| token_type | 14 | unsigned integer |
| client_id | 24 | text string | | client_id | 24 | text string |
| client_secret | 25 | byte string | | client_secret | 25 | byte string |
| response_type | 26 | text string | | response_type | 26 | text string |
| state | 27 | text string | | redirect_uri | 27 | text string |
| redirect_uri | 28 | text string | | state | 28 | text string |
| error_description | 29 | text string | | code | 29 | byte string |
| error_uri | 30 | text string | | error | 30 | unsigned integer |
| code | 31 | byte string | | error_description | 31 | text string |
| expires_in | 32 | unsigned integer | | error_uri | 32 | text string |
| username | 33 | text string | | grant_type | 33 | unsigned integer |
| password | 34 | text string | | token_type | 34 | unsigned integer |
| refresh_token | 35 | byte string | | expires_in | 35 | unsigned integer |
| username | 36 | text string |
| password | 37 | text string |
| refresh_token | 38 | byte string |
| profile | 39 | unsigned integer |
\-------------------+----------+---------------------/ \-------------------+----------+---------------------/
Figure 12: CBOR mappings used in token requests Figure 12: CBOR mappings used in token requests
5.7. The Introspection Endpoint 5.7. The Introspection Endpoint
Token introspection [RFC7662] can be OPTIONALLY provided by the AS, Token introspection [RFC7662] can be OPTIONALLY provided by the AS,
and is then used by the RS and potentially the client to query the AS and is then used by the RS and potentially the client to query the AS
for metadata about a given token, e.g., validity or scope. Analogous for metadata about a given token, e.g., validity or scope. Analogous
to the protocol defined in RFC 7662 [RFC7662] for HTTP and JSON, this to the protocol defined in RFC 7662 [RFC7662] for HTTP and JSON, this
section defines adaptations to more constrained environments using section defines adaptations to more constrained environments using
CBOR and leaving the choice of the application protocol to the CBOR and leaving the choice of the application protocol to the
profile. profile.
Communication between the requesting entity and the introspection Communication between the requesting entity and the introspection
endpoint at the AS MUST be integrity protected and encrypted. endpoint at the AS MUST be integrity protected and encrypted. The
Furthermore the two MUST perform mutual authentication. Finally the communication security protocol MUST also provide a binding between
AS SHOULD verify that the requesting entity has the right to access requests and responses. Furthermore the two interacting parties MUST
introspection information about the provided token. Profiles of this perform mutual authentication. Finally the AS SHOULD verify that the
framework that support introspection MUST specify how authentication requesting entity has the right to access introspection information
and communication security between the requesting entity and the AS about the provided token. Profiles of this framework that support
is implemented. introspection MUST specify how authentication and communication
security between the requesting entity and the AS is implemented.
The default name of this endpoint in an url-path is '/introspect', The default name of this endpoint in an url-path is '/introspect',
however implementations are not required to use this name and can however implementations are not required to use this name and can
define their own instead. define their own instead.
The figures of this section uses CBOR diagnostic notation without the The figures of this section uses CBOR diagnostic notation without the
integer abbreviations for the parameters or their values for better integer abbreviations for the parameters or their values for better
readability. readability.
Note that supporting introspection is OPTIONAL for implementations of Note that supporting introspection is OPTIONAL for implementations of
skipping to change at page 28, line 35 skipping to change at page 28, line 36
5.7.1. Introspection Request 5.7.1. Introspection Request
The requesting entity sends a POST request to the introspection The requesting entity sends a POST request to the introspection
endpoint at the AS, the profile MUST specify how the communication is endpoint at the AS, the profile MUST specify how the communication is
protected. If CBOR is used, the payload MUST be encoded as a CBOR protected. If CBOR is used, the payload MUST be encoded as a CBOR
map with a "token" entry containing either the access token or a map with a "token" entry containing either the access token or a
reference to the token (e.g., the cti). Further optional parameters reference to the token (e.g., the cti). Further optional parameters
representing additional context that is known by the requesting representing additional context that is known by the requesting
entity to aid the AS in its response MAY be included. entity to aid the AS in its response MAY be included.
For CoAP-based interaction, all messages MUST use the content type
"application/ace+cbor", while for HTTP-based interactions the
equivalent media type "application/ace+cbor" MUST be used.
The same parameters are required and optional as in Section 2.1 of The same parameters are required and optional as in Section 2.1 of
RFC 7662 [RFC7662]. RFC 7662 [RFC7662].
For example, Figure 13 shows a RS calling the token introspection For example, Figure 13 shows a RS calling the token introspection
endpoint at the AS to query about an OAuth 2.0 proof-of-possession endpoint at the AS to query about an OAuth 2.0 proof-of-possession
token. Note that object security based on COSE is assumed in this token. Note that object security based on OSCORE
example, therefore the Content-Format is "application/cose". [I-D.ietf-core-object-security] is assumed in this example, therefore
Figure 14 shows the decoded payload. the Content-Format is "application/oscore". Figure 14 shows the
decoded payload.
Header: POST (Code=0.02) Header: POST (Code=0.02)
Uri-Host: "as.example.com" Uri-Host: "as.example.com"
Uri-Path: "introspect" Uri-Path: "introspect"
Content-Format: "application/cose" Content-Format: "application/oscore"
Payload: Payload:
... COSE content ... ... COSE content ...
Figure 13: Example introspection request. Figure 13: Example introspection request.
{ {
"token" : b64'7gj0dXJQ43U', "token" : b64'7gj0dXJQ43U',
"token_type_hint" : "pop" "token_type_hint" : "pop"
} }
skipping to change at page 29, line 33 skipping to change at page 29, line 42
profile OPTIONAL. This indicates the profile that the RS MUST use profile OPTIONAL. This indicates the profile that the RS MUST use
with the client. See Section 5.6.4.3 for more details on the with the client. See Section 5.6.4.3 for more details on the
formatting of this parameter. formatting of this parameter.
Furthermore [I-D.ietf-ace-oauth-params] defines more parameters that Furthermore [I-D.ietf-ace-oauth-params] defines more parameters that
the AS MUST be able to use when responding to a request to the the AS MUST be able to use when responding to a request to the
introspection endpoint. introspection endpoint.
For example, Figure 15 shows an AS response to the introspection For example, Figure 15 shows an AS response to the introspection
request in Figure 13. request in Figure 13. Note that this example contains the "cnf"
parameter defined in [I-D.ietf-ace-oauth-params]/.
Header: Created Code=2.01) Header: Created Code=2.01)
Content-Format: "application/ace+cbor" Content-Format: "application/ace+cbor"
Payload: Payload:
{ {
"active" : true, "active" : true,
"scope" : "read", "scope" : "read",
"profile" : "coap_dtls", "profile" : "coap_dtls",
"cnf" : { "cnf" : {
"COSE_Key" : { "COSE_Key" : {
skipping to change at page 30, line 39 skipping to change at page 31, line 11
specification. In these cases, the authorization server MUST instead specification. In these cases, the authorization server MUST instead
respond with an introspection response with the "active" field set to respond with an introspection response with the "active" field set to
"false". "false".
5.7.4. Mapping Introspection parameters to CBOR 5.7.4. Mapping Introspection parameters to CBOR
If CBOR is used, the introspection request and response parameters If CBOR is used, the introspection request and response parameters
MUST be mapped to CBOR types as specified in Figure 16, using the MUST be mapped to CBOR types as specified in Figure 16, using the
given integer abbreviation for the map key. given integer abbreviation for the map key.
Note that we have aligned these abbreviations with the claim Note that we have aligned abbreviations that correspond to a claim
abbreviations defined in [RFC8392]. with the abbreviations defined in [RFC8392] and the abbreviations of
parameters with the same name from Section 5.6.5.
/-----------------+----------+----------------------------------\ /-------------------+----------+-------------------------\
| Parameter name | CBOR Key | Value Type | | Parameter name | CBOR Key | Value Type |
|-----------------+----------+----------------------------------| |-------------------+----------+-------------------------|
| iss | 1 | text string | | iss | 1 | text string |
| sub | 2 | text string | | sub | 2 | text string |
| aud | 3 | text string | | aud | 3 | text string |
| exp | 4 | integer or floating-point number | | exp | 4 | integer or |
| nbf | 5 | integer or floating-point number | | | | floating-point number |
| iat | 6 | integer or floating-point number | | nbf | 5 | integer or |
| cti | 7 | byte string | | | | floating-point number |
| scope | 9 | text OR byte string | | iat | 6 | integer or |
| token_type | 13 | text string | | | | floating-point number |
| token | 14 | byte string | | cti | 7 | byte string |
| active | 15 | True or False | | scope | 9 | text or byte string |
| profile | 16 | unsigned integer | | active | 10 | True or False |
| client_id | 24 | text string | | token | 12 | byte string |
| username | 33 | text string | | client_id | 24 | text string |
| token_type_hint | 36 | text string | | error | 30 | unsigned integer |
\-----------------+----------+----------------------------------/ | error_description | 31 | text string |
| error_uri | 32 | text string |
| token_type_hint | 33 | text string |
| token_type | 34 | text string |
| username | 36 | text string |
| profile | 39 | unsigned integer |
\-------------------+----------+-------------------------/
Figure 16: CBOR Mappings to Token Introspection Parameters. Figure 16: CBOR Mappings to Token Introspection Parameters.
5.8. The Access Token 5.8. The Access Token
This framework RECOMMENDS the use of CBOR web token (CWT) as This framework RECOMMENDS the use of CBOR web token (CWT) as
specified in [RFC8392]. specified in [RFC8392].
In order to facilitate offline processing of access tokens, this In order to facilitate offline processing of access tokens, this
draft uses the "cnf" claim from draft uses the "cnf" claim from
[I-D.ietf-ace-cwt-proof-of-possession] and specifies the "scope" [I-D.ietf-ace-cwt-proof-of-possession] and specifies the "scope"
claim for both JSON and CBOR web tokens. claim for both JSON and CBOR web tokens.
The "scope" claim explicitly encodes the scope of a given access The "scope" claim explicitly encodes the scope of a given access
token. This claim follows the same encoding rules as defined in token. This claim follows the same encoding rules as defined in
Section 3.3 of [RFC6749], but in addition implementers MAY use byte Section 3.3 of [RFC6749], but in addition implementers MAY use byte
arrays as scope values, to achieve compact encoding of large scope strings as scope values, to achieve compact encoding of large scope
elements. The meaning of a specific scope value is application elements. The meaning of a specific scope value is application
specific and expected to be known to the RS running that application. specific and expected to be known to the RS running that application.
If the AS needs to convey a hint to the RS about which key it should
use to authenticate towards the client, the rs_cnf claim MAY be used
with the same syntax and semantics as defined in
[I-D.ietf-ace-oauth-params].
If the AS needs to convey a hint to the RS about which profile it If the AS needs to convey a hint to the RS about which profile it
should use to communicate with the client, the AS MAY include a should use to communicate with the client, the AS MAY include a
"profile" claim in the access token, with the same syntax and "profile" claim in the access token, with the same syntax and
semantics as defined in Section 5.6.4.3. semantics as defined in Section 5.6.4.3.
5.8.1. The Authorization Information Endpoint 5.8.1. The Authorization Information Endpoint
The access token, containing authorization information and The access token, containing authorization information and
information about the key used by the client, needs to be transported information about the key used by the client, needs to be transported
to the RS so that the RS can authenticate and authorize the client to the RS so that the RS can authenticate and authorize the client
skipping to change at page 32, line 21 skipping to change at page 32, line 33
This section defines a method for transporting the access token to This section defines a method for transporting the access token to
the RS using a RESTful protocol such as CoAP. Profiles of this the RS using a RESTful protocol such as CoAP. Profiles of this
framework MAY define other methods for token transport. framework MAY define other methods for token transport.
The method consists of an authz-info endpoint, implemented by the RS. The method consists of an authz-info endpoint, implemented by the RS.
A client using this method MUST make a POST request to the authz-info A client using this method MUST make a POST request to the authz-info
endpoint at the RS with the access token in the payload. The RS endpoint at the RS with the access token in the payload. The RS
receiving the token MUST verify the validity of the token. If the receiving the token MUST verify the validity of the token. If the
token is valid, the RS MUST respond to the POST request with 2.01 token is valid, the RS MUST respond to the POST request with 2.01
(Created). This response MAY contain an identifier of the token (Created). Section Section 5.8.1.1 outlines how an RS MUST proceed
(e.g., the cti for a CWT) as a payload, in order to allow the client to verify the validity of an access token.
to refer to the token.
If the access token is a CWT and is sent via CoAP, the content format
"application/cwt" MUST be used. If a token is sent via HTTP the
equivalent media type "application/cwt" MUST be used.
The RS MUST be prepared to store at least one access token for future The RS MUST be prepared to store at least one access token for future
use. This is a difference to how access tokens are handled in OAuth use. This is a difference to how access tokens are handled in OAuth
2.0, where the access token is typically sent along with each 2.0, where the access token is typically sent along with each
request, and therefore not stored at the RS. request, and therefore not stored at the RS.
This specification RECOMMENDS that an RS stores only one token per
proof-of-possession key, meaning that an additional token linked to
the same key will overwrite any exiting token at the RS.
If the payload sent to the authz-info endpoint does not parse to a If the payload sent to the authz-info endpoint does not parse to a
token, the RS MUST respond with a response code equivalent to the token, the RS MUST respond with a response code equivalent to the
CoAP code 4.00 (Bad Request). If the token is not valid, the RS MUST CoAP code 4.00 (Bad Request).
respond with a response code equivalent to the CoAP code 4.01
(Unauthorized). If the token is valid but the audience of the token
does not match the RS, the RS MUST respond with a response code
equivalent to the CoAP code 4.03 (Forbidden). If the token is valid
but is associated to claims that the RS cannot process (e.g., an
unknown scope) the RS MUST respond with a response code equivalent to
the CoAP code 4.00 (Bad Request). In the latter case the RS MAY
provide additional information in the error response, in order to
clarify what went wrong.
The RS MAY use the error codes from section 3.1 of [RFC6750] when
giving error responses, in order to provide additional detail.
The RS MAY make an introspection request to validate the token before The RS MAY make an introspection request to validate the token before
responding to the POST request to the authz-info endpoint. responding to the POST request to the authz-info endpoint.
Profiles MUST specify whether the authz-info endpoint is protected, Profiles MUST specify whether the authz-info endpoint is protected,
including whether error responses from this endpoint are protected. including whether error responses from this endpoint are protected.
Note that since the token contains information that allow the client Note that since the token contains information that allow the client
and the RS to establish a security context in the first place, mutual and the RS to establish a security context in the first place, mutual
authentication may not be possible at this point. authentication may not be possible at this point.
The default name of this endpoint in an url-path is '/authz-info', The default name of this endpoint in an url-path is '/authz-info',
however implementations are not required to use this name and can however implementations are not required to use this name and can
define their own instead. define their own instead.
A RS MAY use introspection on a token received through the authz-info
endpoint, e.g. if the token is an opaque reference. Some transport
protocols may provide a way to indicate that the RS is busy and the
client should retry after an interval; this type of status update
would be appropriate while the RS is waiting for an introspection
response.
5.8.1.1. Verifying an Access Token
When an RS receives an access token, it MUST verify it before storing
it. The verification is based on the claims of the token and its
cryptographic wrapper (if any), so the RS needs to retrieve those
claims. If the claims cannot be retrieved the RS MUST discard the
token and in case of an interaction via the authz-info endpoint,
return an error message with a response code equivalent to the CoAP
code 4.00 (Bad Request).
Since the cryptographic wrapper of the token (e.g. a COSE message)
could include encryption, it needs to be verified first, based on
shared cryptographic material with recognized AS. If this
verification fails, the RS MUST discard the token and if this was an
interaction with authz-info it MUST respond with a response code
equivalent to the CoAP code 4.01 (Unauthorized).
The following claims MUST be checked if present, and errors returned
when a check fails, in the order of priority of this list:
iss The issuer claim must identify an AS that has the authority to
issue access tokens for the receiving RS. If that is not the case
the RS MUST respond with a response code equivalent to the CoAP
code 4.01 (Unauthorized).
exp The expiration date must be in the future. Note that this has
to be verified again at access time. If that is not the case the
RS MUST respond with a response code equivalent to the CoAP code
4.01 (Unauthorized).
aud The audience claim must refer to an audience that the RS
identifies with. If that is not the case the RS MUST respond with
a response code equivalent to the CoAP code 4.03 (Forbidden).
scope The RS must recognize value of the scope claim. If that is
not the case the RS MUST respond with a response code equivalent
to the CoAP code 4.00 (Bad Request). The RS MAY provide
additional information in the error response, in order to clarify
what went wrong.
If the access token contains any other claims that the RS cannot
process the RS MUST respond with a response code equivalent to the
CoAP code 4.00 (Bad Request). The RS MAY provide additional detail
in the error response to clarify which claim couldn't be processed.
Note that the Subject (sub) claim cannot always be verified when the
token is submitted to the RS, since the client may not have
authenticated yet. Also note that a counter for the expires_in (exi)
claim MUST be initialized when the RS first verifies this token.
When sending error responses, the RS MAY use the error codes from
section 3.1 of [RFC6750], in order to provide additional detail to
the client.
5.8.1.2. Protecting the Authzorization Information Endpoint
As this framework can be used in RESTful environments, it is
important to make sure that attackers cannot perform unauthorized
requests on the auth-info endpoints, other than submitting access
tokens.
Specifically it SHOULD NOT be possible to perform GET, DELETE or PUT
on the authz-info endpoint and on it's children (if any).
The POST method SHOULD NOT be allowed on children of the authz-info
endpoint.
The RS SHOULD implement rate limiting measures to mitigate attacks
aiming to overload the processing capacity of the RS by repeatedly
submitting tokens. For CoAP-based communication the RS could use the
mechanisms from [I-D.ietf-core-too-many-reqs] to indicate that it is
overloaded.
5.8.2. Client Requests to the RS 5.8.2. Client Requests to the RS
If an RS receives a request from a client, and the target resource If an RS receives a request from a client, and the target resource
requires authorization, the RS MUST first verify that it has an requires authorization, the RS MUST first verify that it has an
access token that authorizes this request, and that the client has access token that authorizes this request, and that the client has
performed the proof-of-possession for that token. performed the proof-of-possession for that token.
The response code MUST be 4.01 (Unauthorized) in case the client has The response code MUST be 4.01 (Unauthorized) in case the client has
not performed the proof-of-possession, or if RS has no valid access not performed the proof-of-possession, or if RS has no valid access
token for the client. If RS has an access token for the client but token for the client. If RS has an access token for the client but
skipping to change at page 33, line 47 skipping to change at page 35, line 34
Note: Matching the claims of the access token (e.g., scope) to a Note: Matching the claims of the access token (e.g., scope) to a
specific request is application specific. specific request is application specific.
If the request matches a valid token and the client has performed the If the request matches a valid token and the client has performed the
proof-of-possession for that token, the RS continues to process the proof-of-possession for that token, the RS continues to process the
request as specified by the underlying application. request as specified by the underlying application.
5.8.3. Token Expiration 5.8.3. Token Expiration
Depending on the capabilities of the RS, there are various ways in Depending on the capabilities of the RS, there are various ways in
which it can verify the validity of a received access token. Here which it can verify the expiration of a received access token. Here
follows a list of the possibilities including what functionality they follows a list of the possibilities including what functionality they
require of the RS. require of the RS.
o The token is a CWT and includes an "exp" claim and possibly the o The token is a CWT and includes an "exp" claim and possibly the
"nbf" claim. The RS verifies these by comparing them to values "nbf" claim. The RS verifies these by comparing them to values
from its internal clock as defined in [RFC7519]. In this case the from its internal clock as defined in [RFC7519]. In this case the
RS's internal clock must reflect the current date and time, or at RS's internal clock must reflect the current date and time, or at
least be synchronized with the AS's clock. How this clock least be synchronized with the AS's clock. How this clock
synchronization would be performed is out of scope for this synchronization would be performed is out of scope for this
specification. specification.
o The RS verifies the validity of the token by performing an o The RS verifies the validity of the token by performing an
introspection request as specified in Section 5.7. This requires introspection request as specified in Section 5.7. This requires
the RS to have a reliable network connection to the AS and to be the RS to have a reliable network connection to the AS and to be
able to handle two secure sessions in parallel (C to RS and AS to able to handle two secure sessions in parallel (C to RS and AS to
RS). RS).
o The RS and the AS both store a sequence number linked to their o In order to support token expiration for devices that have no
common security association. The AS increments this number for reliable way of synchronizing their internal clocks, this
each access token it issues and includes it in the access token, specification defines the following approach: The claim "exi"
which is a CWT. The RS keeps track of the most recently received ("expires in") can be used, to provide the RS with the lifetime of
sequence number, and only accepts tokens as valid, that are in a the token in seconds from the time the RS first receives the
certain range around this number. This method does only require token. This approach is of course vulnerable to malicious clients
the RS to keep track of the sequence number. The method does not holding back tokens they do not want to expire. Such an attack
provide timely expiration, but it makes sure that older tokens can only be prevented if the RS is able to communicate with the AS
cease to be valid after a certain number of newer ones got issued. in some regular intervals, so that the can AS provide the RS with
For a constrained RS with no network connectivity and no means of a list of expired tokens. The drawback of this mitigation is that
reliably measuring time, this is the best that can be achieved. the RS might as well use the communication with the AS to
synchronize its internal clock.
If a token that authorizes a long running request such as a CoAP If a token that authorizes a long running request such as a CoAP
Observe [RFC7641] expires, the RS MUST send an error response with Observe [RFC7641] expires, the RS MUST send an error response with
the response code equivalent to the CoAP code 4.01 (Unauthorized) to the response code equivalent to the CoAP code 4.01 (Unauthorized) to
the client and then terminate processing the long running request. the client and then terminate processing the long running request.
6. Security Considerations 6. Security Considerations
Security considerations applicable to authentication and Security considerations applicable to authentication and
authorization in RESTful environments provided in OAuth 2.0 [RFC6749] authorization in RESTful environments provided in OAuth 2.0 [RFC6749]
apply to this work. Furthermore [RFC6819] provides additional apply to this work. Furthermore [RFC6819] provides additional
security considerations for OAuth which apply to IoT deployments as security considerations for OAuth which apply to IoT deployments as
well. well. If the introspection endpoint is used, the security
considerations from [RFC7662] also apply.
A large range of threats can be mitigated by protecting the contents A large range of threats can be mitigated by protecting the contents
of the access token by using a digital signature or a keyed message of the access token by using a digital signature or a keyed message
digest (MAC) or an Authenticated Encryption with Associated Data digest (MAC) or an Authenticated Encryption with Associated Data
(AEAD) algorithm. Consequently, the token integrity protection MUST (AEAD) algorithm. Consequently, the token integrity protection MUST
be applied to prevent the token from being modified, particularly be applied to prevent the token from being modified, particularly
since it contains a reference to the symmetric key or the asymmetric since it contains a reference to the symmetric key or the asymmetric
key. If the access token contains the symmetric key, this symmetric key. If the access token contains the symmetric key, this symmetric
key MUST be encrypted by the authorization server so that only the key MUST be encrypted by the authorization server so that only the
resource server can decrypt it. Note that using an AEAD algorithm is resource server can decrypt it. Note that using an AEAD algorithm is
skipping to change at page 35, line 29 skipping to change at page 37, line 16
provided, and additional protection can be applied by encrypting the provided, and additional protection can be applied by encrypting the
token, for example encryption of CWTs is specified in Section 5.1 of token, for example encryption of CWTs is specified in Section 5.1 of
[RFC8392]. [RFC8392].
Developers MUST ensure that the ephemeral credentials (i.e., the Developers MUST ensure that the ephemeral credentials (i.e., the
private key or the session key) are not leaked to third parties. An private key or the session key) are not leaked to third parties. An
adversary in possession of the ephemeral credentials bound to the adversary in possession of the ephemeral credentials bound to the
access token will be able to impersonate the client. Be aware that access token will be able to impersonate the client. Be aware that
this is a real risk with many constrained environments, since this is a real risk with many constrained environments, since
adversaries can often easily get physical access to the devices. adversaries can often easily get physical access to the devices.
This risk can also be mitigated to some extent by making sure that
keys are refreshed more frequently.
If clients are capable of doing so, they should frequently request If clients are capable of doing so, they should frequently request
fresh access tokens, as this allows the AS to keep the lifetime of fresh access tokens, as this allows the AS to keep the lifetime of
the tokens short. This allows the AS to use shorter proof-of- the tokens short. This allows the AS to use shorter proof-of-
possession key sizes, which translate to a performance benefit for possession key sizes, which translate to a performance benefit for
the client and for the resource server. Shorter keys also lead to the client and for the resource server. Shorter keys also lead to
shorter messages (particularly with asymmetric keying material). shorter messages (particularly with asymmetric keying material).
When authorization servers bind symmetric keys to access tokens, they When authorization servers bind symmetric keys to access tokens, they
SHOULD scope these access tokens to a specific permissions. SHOULD scope these access tokens to a specific permission.
Furthermore access tokens using symmetric keys for proof-of-
possession SHOULD NOT be targeted at an audience that contains more
than one RS, since otherwise any RS in the audience that receives
that access token can impersonate the client towards the other
members of the audience.
6.1. Unprotected AS Information 6.1. Unprotected AS Information
Initially, no secure channel exists to protect the communication Initially, no secure channel exists to protect the communication
between C and RS. Thus, C cannot determine if the AS information between C and RS. Thus, C cannot determine if the AS information
contained in an unprotected response from RS to an unauthorized contained in an unprotected response from RS to an unauthorized
request (see Section 5.1.2) is authentic. It is therefore advisable request (see Section 5.1.2) is authentic. It is therefore advisable
to provide C with a (possibly hard-coded) list of trustworthy to provide C with a (possibly hard-coded) list of trustworthy
authorization servers. AS information responses referring to a URI authorization servers. AS information responses referring to a URI
not listed there would be ignored. not listed there would be ignored.
6.2. Use of Nonces for Replay Protection 6.2. Minimal security requirements for communication
This section summarizes the minimal requirements for the
communication security of the different protocol interactions.
C-AS All communication between the client and the Authorization
Server MUST be encrypted, integrity and replay protected.
Furthermore responses from the AS to the client MUST be bound to
the client's request to avoid attacks where the attacker swaps the
intended response for an older one valid for a previous request.
This requires that the client and the Authorization Server have
previously exchanged either a shared secret, or their public keys
in order to negotiate a secure communication. Furthermore the
client MUST be able to determine whether an AS has the authority
to issue access tokens for a certain RS. This can be done through
pre-configured lists, or through an online lookup mechanism that
in turn also must be secured.
RS-AS The communication between the Resource Server and the
Authorization Server via the introspection endpoint MUST be
encrypted, integrity and replay protected. Furthermore responses
from the AS to the RS MUST be bound to the RS's request. This
requires that the client and the Authorization Server have
previously exchanged either a shared secret, or their public keys
in order to negotiate a secure communication. Furthermore the RS
MUST be able to determine whether an AS has the authority to issue
access tokens itself. This is usually configured out of band, but
could also be performed through an online lookup mechanism
provided that it is also secured in the same way.
C-RS The initial communication between the client and the Resource
Server can not be secured in general, since the RS is not in
possession of on access token for that client, which would carry
the necessary parameters. Certain security mechanisms (e.g. DTLS
with server-side authentication via a certificate or a raw public
key) can be possible and are RECOMMEND if supported by both
parties. After the client has successfully transmitted the access
token to the RS, a secure communication protocol MUST be
established between client and RS for the actual resource request.
This protocol MUST provide encryption, integrity and replay
protection as well as a binding between requests and responses.
This requires that the client learned either the RS's public key
or received a symmetric proof-of-possession key bound to the
access token from the AS. The RS must have learned either the
client's public key or a shared symmetric key from the claims in
the token or an introspection request. Since ACE does not provide
profile negotiation between C and RS, the client MUST have learned
what profile the RS supports (e.g. from the AS or pre-configured)
and initiate the communication accordingly.
6.3. Use of Nonces for Replay Protection
The RS may add a nonce to the AS Information message sent as a The RS may add a nonce to the AS Information message sent as a
response to an unauthorized request to ensure freshness of an Access response to an unauthorized request to ensure freshness of an Access
Token subsequently presented to RS. While a time-stamp of some Token subsequently presented to RS. While a time-stamp of some
granularity would be sufficient to protect against replay attacks, granularity would be sufficient to protect against replay attacks,
using randomized nonce is preferred to prevent disclosure of using randomized nonce is preferred to prevent disclosure of
information about RS's internal clock characteristics. information about RS's internal clock characteristics.
6.3. Combining profiles 6.4. Combining profiles
There may be use cases were different profiles of this framework are There may be use cases were different profiles of this framework are
combined. For example, an MQTT-TLS profile is used between the combined. For example, an MQTT-TLS profile is used between the
client and the RS in combination with a CoAP-DTLS profile for client and the RS in combination with a CoAP-DTLS profile for
interactions between the client and the AS. Ideally, profiles should interactions between the client and the AS. Ideally, profiles should
be designed in a way that the security of system should not depend on be designed in a way that the security of system should not depend on
the specific security mechanisms used in individual protocol the specific security mechanisms used in individual protocol
interactions. interactions.
6.4. Error responses 6.5. Unprotected Information
The various error responses defined in this framework may leak Communication with the authz-info endpoint, as well as the various
information to an adversary. For example errors responses for error responses defined in this framework all potentially include
sending information over an unprotected channel. These messages may
leak information to an adversary. For example errors responses for
requests to the Authorization Information endpoint can reveal requests to the Authorization Information endpoint can reveal
information about an otherwise opaque access token to an adversary information about an otherwise opaque access token to an adversary
who has intercepted this token. This framework is written under the who has intercepted this token.
assumption that, in general, the benefits of detailed error messages
outweigh the risk due to information leakage. For particular use As far as error messages are concerned, this framework is written
cases, where this assessment does not apply, detailed error messages under the assumption that, in general, the benefits of detailed error
can be replaced by more generic ones. messages outweigh the risk due to information leakage. For
particular use cases, where this assessment does not apply, detailed
error messages can be replaced by more generic ones.
In some scenarios it may be possible to protect the communication
with the authz-info endpoint (e.g. through DTLS with only server-side
authentication). In cases where this is not possible this framework
RECOMMENDS to use encrypted CWTs or opaque references and need to be
subjected to introspection by the RS.
If the initial unauthorized resource request message (see
Section 5.1.1) is used, the client MUST make sure that it is not
sending sensitive content in this request. While GET and DELETE
requests only reveal the target URI of the resource, while POST and
PUT requests would reveal the whole payload of the intended
operation.
6.6. Denial of service against or with Introspection
The optional introspection mechanism provided by OAuth and supported
in the ACE framework allows for two types of attacks that need to be
considered by implementers.
First an attacker could perform a denial of service attack against
the introspection endpoint at the AS in order to prevent validation
of access tokens. To mitigate this attack, an RS that is configured
to use introspection MUST NOT allow access based on a token for which
it couln't reach the introspection endpoint.
Second an attacker could use the fact that an RS performs
introspection to perform a denial of service attack against that RS
by repeatedly sending tokens to its authz-info endpoint that require
an introspection call. RS can mitigate such attacks by implementing
a rate limit on how many introspection requests they perform in a
given time intervall and rejecting incoming requests to authz-info
for a certain amount of time, when that rate limit has been reached.
7. Privacy Considerations 7. Privacy Considerations
Implementers and users should be aware of the privacy implications of Implementers and users should be aware of the privacy implications of
the different possible deployments of this framework. the different possible deployments of this framework.
The AS is in a very central position and can potentially learn The AS is in a very central position and can potentially learn
sensitive information about the clients requesting access tokens. If sensitive information about the clients requesting access tokens. If
the client credentials grant is used, the AS can track what kind of the client credentials grant is used, the AS can track what kind of
access the client intends to perform. With other grants this can be access the client intends to perform. With other grants this can be
skipping to change at page 38, line 4 skipping to change at page 41, line 28
Name The name of the parameter Name The name of the parameter
CBOR Key CBOR map key for the parameter. Different ranges of values CBOR Key CBOR map key for the parameter. Different ranges of values
use different registration policies [RFC8126]. Integer values use different registration policies [RFC8126]. Integer values
from -256 to 255 are designated as Standards Action. Integer from -256 to 255 are designated as Standards Action. Integer
values from -65536 to -257 and from 256 to 65535 are designated as values from -65536 to -257 and from 256 to 65535 are designated as
Specification Required. Integer values greater than 65535 are Specification Required. Integer values greater than 65535 are
designated as Expert Review. Integer values less than -65536 are designated as Expert Review. Integer values less than -65536 are
marked as Private Use. marked as Private Use.
Value Type The CBOR data types allowable for the values of this Value Type The CBOR data types allowable for the values of this
parameter. parameter.
Reference This contains a pointer to the public specification of the Reference This contains a pointer to the public specification of the
grant type abbreviation, if one exists. grant type abbreviation, if one exists.
This registry will be initially populated by the values in Figure 2. This registry will be initially populated by the values in Figure 2.
The Reference column for all of these entries will be this document. The Reference column for all of these entries will be this document.
8.2. OAuth Extensions Error Registration 8.2. OAuth Extensions Error Registration
This specification registers the follwoing error values in the OAuth This specification registers the following error values in the OAuth
Extensions Error registry defined in [RFC6749]. Extensions Error registry defined in [RFC6749].
o Error name: "unsupported_pop_key" o Error name: "unsupported_pop_key"
o Error usage location: AS token endpoint error response o Error usage location: AS token endpoint error response
o Related protocol extension: The ACE framework [this document] o Related protocol extension: The ACE framework [this document]
o Change Controller: IESG o Change Controller: IESG
o Specification doucment(s): Section 5.6.3 of [this document] o Specification document(s): Section 5.6.3 of [this document]
o Error name: "incompatible_profiles" o Error name: "incompatible_profiles"
o Error usage location: AS token endpoint error response o Error usage location: AS token endpoint error response
o Related protocol extension: The ACE framework [this document] o Related protocol extension: The ACE framework [this document]
o Change Controller: IESG o Change Controller: IESG
o Specification doucment(s): Section 5.6.3 of [this document] o Specification document(s): Section 5.6.3 of [this document]
8.3. OAuth Error Code CBOR Mappings Registry 8.3. OAuth Error Code CBOR Mappings Registry
This specification establishes the IANA "OAuth Error Code CBOR This specification establishes the IANA "OAuth Error Code CBOR
Mappings" registry. The registry has been created to use the "Expert Mappings" registry. The registry has been created to use the "Expert
Review Required" registration procedure [RFC8126]. It should be Review Required" registration procedure [RFC8126]. It should be
noted that, in addition to the expert review, some portions of the noted that, in addition to the expert review, some portions of the
registry require a specification, potentially a Standards Track RFC, registry require a specification, potentially a Standards Track RFC,
be supplied as well. be supplied as well.
skipping to change at page 41, line 4 skipping to change at page 44, line 30
attribute. attribute.
Description Text giving an overview of the profile and the context Description Text giving an overview of the profile and the context
it is developed for. it is developed for.
CBOR Value CBOR abbreviation for this profile name. Different CBOR Value CBOR abbreviation for this profile name. Different
ranges of values use different registration policies [RFC8126]. ranges of values use different registration policies [RFC8126].
Integer values from -256 to 255 are designated as Standards Integer values from -256 to 255 are designated as Standards
Action. Integer values from -65536 to -257 and from 256 to 65535 Action. Integer values from -65536 to -257 and from 256 to 65535
are designated as Specification Required. Integer values greater are designated as Specification Required. Integer values greater
than 65535 are designated as Expert Review. Integer values less than 65535 are designated as Expert Review. Integer values less
than -65536 are marked as Private Use. than -65536 are marked as Private Use.
Reference This contains a pointer to the public specification of the Reference This contains a pointer to the public specification of the
profile abbreviation, if one exists. profile abbreviation, if one exists.
8.8. OAuth Parameter Registration 8.8. OAuth Parameter Registration
This specification registers the following parameter in the "OAuth This specification registers the following parameter in the "OAuth
Parameters" registry [IANA.OAuthParameters]: Parameters" registry [IANA.OAuthParameters]:
o Name: "profile" o Name: "profile"
o Parameter Usage Location: token response o Parameter Usage Location: token response
o Change Controller: IESG o Change Controller: IESG
o Reference: Section 5.6.4.3 of [this document] o Reference: Section 5.6.4.3 of [this document]
8.9. OAuth CBOR Parameter Mappings Registry 8.9. Token Endpoint CBOR Mappings Registry
This specification establishes the IANA "Token Endpoint CBOR This specification establishes the IANA "Token Endpoint CBOR
Mappings" registry. The registry has been created to use the "Expert Mappings" registry. The registry has been created to use the "Expert
Review Required" registration procedure [RFC8126]. It should be Review Required" registration procedure [RFC8126]. It should be
noted that, in addition to the expert review, some portions of the noted that, in addition to the expert review, some portions of the
registry require a specification, potentially a Standards Track RFC, registry require a specification, potentially a Standards Track RFC,
be supplied as well. be supplied as well.
The columns of this registry are: The columns of this registry are:
skipping to change at page 41, line 41 skipping to change at page 45, line 19
CBOR Key CBOR map key for this parameter. Different ranges of CBOR Key CBOR map key for this parameter. Different ranges of
values use different registration policies [RFC8126]. Integer values use different registration policies [RFC8126]. Integer
values from -256 to 255 are designated as Standards Action. values from -256 to 255 are designated as Standards Action.
Integer values from -65536 to -257 and from 256 to 65535 are Integer values from -65536 to -257 and from 256 to 65535 are
designated as Specification Required. Integer values greater than designated as Specification Required. Integer values greater than
65535 are designated as Expert Review. Integer values less than 65535 are designated as Expert Review. Integer values less than
-65536 are marked as Private Use. -65536 are marked as Private Use.
Value Type The allowable CBOR data types for values of this Value Type The allowable CBOR data types for values of this
parameter. parameter.
Reference This contains a pointer to the public specification of the Reference This contains a pointer to the public specification of the
grant type abbreviation, if one exists. parameter abbreviation, if one exists.
This registry will be initially populated by the values in Figure 12. This registry will be initially populated by the values in Figure 12.
The Reference column for all of these entries will be this document. The Reference column for all of these entries will be this document.
Note that these mappings intentionally coincide with the CWT claim Note that the mappings of parameters corresponding to claim names
name mappings from [RFC8392]. intentionally coincide with the CWT claim name mappings from
[RFC8392].
8.10. OAuth Introspection Response Parameter Registration 8.10. OAuth Introspection Response Parameter Registration
This specification registers the following parameter in the OAuth This specification registers the following parameter in the OAuth
Token Introspection Response registry Token Introspection Response registry
[IANA.TokenIntrospectionResponse]. [IANA.TokenIntrospectionResponse].
o Name: "profile" o Name: "profile"
o Description: The communication and communication security profile o Description: The communication and communication security profile
used between client and RS, as defined in ACE profiles. used between client and RS, as defined in ACE profiles.
skipping to change at page 42, line 30 skipping to change at page 46, line 4
Mappings" registry. The registry has been created to use the "Expert Mappings" registry. The registry has been created to use the "Expert
Review Required" registration procedure [RFC8126]. It should be Review Required" registration procedure [RFC8126]. It should be
noted that, in addition to the expert review, some portions of the noted that, in addition to the expert review, some portions of the
registry require a specification, potentially a Standards Track RFC, registry require a specification, potentially a Standards Track RFC,
be supplied as well. be supplied as well.
The columns of this registry are: The columns of this registry are:
Name The OAuth Parameter name, refers to the name in the OAuth Name The OAuth Parameter name, refers to the name in the OAuth
parameter registry, e.g., "client_id". parameter registry, e.g., "client_id".
CBOR Key CBOR map key for this parameter. Different ranges of CBOR Key CBOR map key for this parameter. Different ranges of
values use different registration policies [RFC8126]. Integer values use different registration policies [RFC8126]. Integer
values from -256 to 255 are designated as Standards Action. values from -256 to 255 are designated as Standards Action.
Integer values from -65536 to -257 and from 256 to 65535 are Integer values from -65536 to -257 and from 256 to 65535 are
designated as Specification Required. Integer values greater than designated as Specification Required. Integer values greater than
65535 are designated as Expert Review. Integer values less than 65535 are designated as Expert Review. Integer values less than
-65536 are marked as Private Use. -65536 are marked as Private Use.
Value Type The allowable CBOR data types for values of this Value Type The allowable CBOR data types for values of this
parameter. parameter.
Reference This contains a pointer to the public specification of the Reference This contains a pointer to the public specification of the
grant type abbreviation, if one exists. grant type abbreviation, if one exists.
This registry will be initially populated by the values in Figure 16. This registry will be initially populated by the values in Figure 16.
The Reference column for all of these entries will be this document. The Reference column for all of these entries will be this document.
Note that the mappings of parameters corresponding to claim names
intentionally coincide with the CWT claim name mappings from
[RFC8392].
8.12. JSON Web Token Claims 8.12. JSON Web Token Claims
This specification registers the following new claims in the JSON Web This specification registers the following new claims in the JSON Web
Token (JWT) registry of JSON Web Token Claims Token (JWT) registry of JSON Web Token Claims
[IANA.JsonWebTokenClaims]: [IANA.JsonWebTokenClaims]:
o Claim Name: "scope" o Claim Name: "scope"
o Claim Description: The scope of an access token as defined in o Claim Description: The scope of an access token as defined in
[RFC6749]. [RFC6749].
o Change Controller: IESG o Change Controller: IESG
o Reference: Section 5.8 of [this document] o Reference: Section 5.8 of [this document]
o Claim Name: "profile" o Claim Name: "profile"
o Claim Description: The profile a token is supposed to be used o Claim Description: The profile a token is supposed to be used
with. with.
o Change Controller: IESG o Change Controller: IESG
o Reference: Section 5.8 of [this document] o Reference: Section 5.8 of [this document]
o Claim Name: "rs_cnf" o Claim Name: "exi"
o Claim Description: The public key the RS is supposed to use to o Claim Description: "Expires in". Lifetime of the token in seconds
authenticate to the client wielding this token. from the time the RS first sees it. Used to implement a weaker
from of token expiration for devices that cannot synchronize their
internal clocks.
o Change Controller: IESG o Change Controller: IESG
o Reference: Section 5.8 of [this document] o Reference: Section 5.8.3 of [this document]
8.13. CBOR Web Token Claims 8.13. CBOR Web Token Claims
This specification registers the following new claims in the "CBOR This specification registers the following new claims in the "CBOR
Web Token (CWT) Claims" registry [IANA.CborWebTokenClaims]. Web Token (CWT) Claims" registry [IANA.CborWebTokenClaims].
o Claim Name: "scope" o Claim Name: "scope"
o Claim Description: The scope of an access token as defined in o Claim Description: The scope of an access token as defined in
[RFC6749]. [RFC6749].
o JWT Claim Name: N/A o JWT Claim Name: N/A
o Claim Key: 12 o Claim Key: TBD (suggested: 9)
o Claim Value Type(s): byte string or text string o Claim Value Type(s): byte string or text string
o Change Controller: IESG o Change Controller: IESG
o Specification Document(s): Section 5.8 of [this document] o Specification Document(s): Section 5.8 of [this document]
o Claim Name: "profile" o Claim Name: "profile"
o Claim Description: The profile a token is supposed to be used o Claim Description: The profile a token is supposed to be used
with. with.
o JWT Claim Name: N/A o JWT Claim Name: N/A
o Claim Key: 16 o Claim Key: TBD (suggested: 39)
o Claim Value Type(s): integer o Claim Value Type(s): integer
o Change Controller: IESG o Change Controller: IESG
o Specification Document(s): Section 5.8 of [this document] o Specification Document(s): Section 5.8 of [this document]
o Claim Name: "rs_cnf"
o Claim Description: The public key the RS is supposed to use to
authenticate to the client wielding this token.
o JWT Claim Name: N/A
o Claim Key: 17
o Claim Value Type(s): map
o Change Controller: IESG
o Specification Document(s): Section 5.8 of [this document]
8.14. Media Type Registrations 8.14. Media Type Registrations
This specification registers the 'application/ace+cbor' media type This specification registers the 'application/ace+cbor' media type
for messages of the protocols defined in this document carrying for messages of the protocols defined in this document carrying
parameters encoded in CBOR. This registration follows the procedures parameters encoded in CBOR. This registration follows the procedures
specified in [RFC6838]. specified in [RFC6838].
Type name: application Type name: application
Subtype name: ace+cbor Subtype name: ace+cbor
skipping to change at page 45, line 35 skipping to change at page 49, line 11
Thanks to the authors of draft-ietf-oauth-pop-key-distribution, from Thanks to the authors of draft-ietf-oauth-pop-key-distribution, from
where large parts of the security considerations where copied. where large parts of the security considerations where copied.
Thanks to Stefanie Gerdes, Olaf Bergmann, and Carsten Bormann for Thanks to Stefanie Gerdes, Olaf Bergmann, and Carsten Bormann for
contributing their work on AS discovery from draft-gerdes-ace-dcaf- contributing their work on AS discovery from draft-gerdes-ace-dcaf-
authorize (see Section 5.1). authorize (see Section 5.1).
Thanks to Jim Schaad and Mike Jones for their comprehensive reviews. Thanks to Jim Schaad and Mike Jones for their comprehensive reviews.
Thanks to Benjamin Kaduk for his input on various questions related
to this work.
Ludwig Seitz and Goeran Selander worked on this document as part of Ludwig Seitz and Goeran Selander worked on this document as part of
the CelticPlus project CyberWI, with funding from Vinnova. the CelticPlus project CyberWI, with funding from Vinnova.
10. References 10. References
10.1. Normative References 10.1. Normative References
[I-D.ietf-ace-cwt-proof-of-possession] [I-D.ietf-ace-cwt-proof-of-possession]
Jones, M., Seitz, L., Selander, G., Erdtman, S., and H. Jones, M., Seitz, L., Selander, G., Erdtman, S., and H.
Tschofenig, "Proof-of-Possession Key Semantics for CBOR Tschofenig, "Proof-of-Possession Key Semantics for CBOR
Web Tokens (CWTs)", draft-ietf-ace-cwt-proof-of- Web Tokens (CWTs)", draft-ietf-ace-cwt-proof-of-
possession-03 (work in progress), June 2018. possession-05 (work in progress), November 2018.
[I-D.ietf-ace-oauth-params] [I-D.ietf-ace-oauth-params]
Seitz, L., "Additional OAuth Parameters for Authorization Seitz, L., "Additional OAuth Parameters for Authorization
in Constrained Environments (ACE)", draft-ietf-ace-oauth- in Constrained Environments (ACE)", draft-ietf-ace-oauth-
params-00 (work in progress), September 2018. params-00 (work in progress), September 2018.
[IANA.CborWebTokenClaims] [IANA.CborWebTokenClaims]
IANA, "CBOR Web Token (CWT) Claims", IANA, "CBOR Web Token (CWT) Claims",
<https://www.iana.org/assignments/cwt/cwt.xhtml#claims- <https://www.iana.org/assignments/cwt/cwt.xhtml#claims-
registry>. registry>.
skipping to change at page 48, line 5 skipping to change at page 51, line 30
Seitz, L. and S. Erdtman, "Raw-Public-Key and Pre-Shared- Seitz, L. and S. Erdtman, "Raw-Public-Key and Pre-Shared-
Key as OAuth client credentials", draft-erdtman-ace- Key as OAuth client credentials", draft-erdtman-ace-
rpcc-02 (work in progress), October 2017. rpcc-02 (work in progress), October 2017.
[I-D.ietf-core-object-security] [I-D.ietf-core-object-security]
Selander, G., Mattsson, J., Palombini, F., and L. Seitz, Selander, G., Mattsson, J., Palombini, F., and L. Seitz,
"Object Security for Constrained RESTful Environments "Object Security for Constrained RESTful Environments
(OSCORE)", draft-ietf-core-object-security-15 (work in (OSCORE)", draft-ietf-core-object-security-15 (work in
progress), August 2018. progress), August 2018.
[I-D.ietf-core-too-many-reqs]
Keranen, A., "Too Many Requests Response Code for the
Constrained Application Protocol", draft-ietf-core-too-
many-reqs-06 (work in progress), November 2018.
[I-D.ietf-oauth-device-flow] [I-D.ietf-oauth-device-flow]
Denniss, W., Bradley, J., Jones, M., and H. Tschofenig, Denniss, W., Bradley, J., Jones, M., and H. Tschofenig,
"OAuth 2.0 Device Flow for Browserless and Input "OAuth 2.0 Device Flow for Browserless and Input
Constrained Devices", draft-ietf-oauth-device-flow-12 Constrained Devices", draft-ietf-oauth-device-flow-13
(work in progress), August 2018. (work in progress), October 2018.
[I-D.ietf-tls-dtls13]
Rescorla, E., Tschofenig, H., and N. Modadugu, "The
Datagram Transport Layer Security (DTLS) Protocol Version
1.3", draft-ietf-tls-dtls13-30 (work in progress),
November 2018.
[Margi10impact] [Margi10impact]
Margi, C., de Oliveira, B., de Sousa, G., Simplicio Jr, Margi, C., de Oliveira, B., de Sousa, G., Simplicio Jr,
M., Barreto, P., Carvalho, T., Naeslund, M., and R. Gold, M., Barreto, P., Carvalho, T., Naeslund, M., and R. Gold,
"Impact of Operating Systems on Wireless Sensor Networks "Impact of Operating Systems on Wireless Sensor Networks
(Security) Applications and Testbeds", Proceedings of (Security) Applications and Testbeds", Proceedings of
the 19th International Conference on Computer the 19th International Conference on Computer
Communications and Networks (ICCCN), 2010 August. Communications and Networks (ICCCN), 2010 August.
[RFC4949] Shirey, R., "Internet Security Glossary, Version 2", [RFC4949] Shirey, R., "Internet Security Glossary, Version 2",
skipping to change at page 50, line 5 skipping to change at page 53, line 40
[RFC8259] Bray, T., Ed., "The JavaScript Object Notation (JSON) Data [RFC8259] Bray, T., Ed., "The JavaScript Object Notation (JSON) Data
Interchange Format", STD 90, RFC 8259, Interchange Format", STD 90, RFC 8259,
DOI 10.17487/RFC8259, December 2017, <https://www.rfc- DOI 10.17487/RFC8259, December 2017, <https://www.rfc-
editor.org/info/rfc8259>. editor.org/info/rfc8259>.
[RFC8414] Jones, M., Sakimura, N., and J. Bradley, "OAuth 2.0 [RFC8414] Jones, M., Sakimura, N., and J. Bradley, "OAuth 2.0
Authorization Server Metadata", RFC 8414, Authorization Server Metadata", RFC 8414,
DOI 10.17487/RFC8414, June 2018, <https://www.rfc- DOI 10.17487/RFC8414, June 2018, <https://www.rfc-
editor.org/info/rfc8414>. editor.org/info/rfc8414>.
[RFC8446] Rescorla, E., "The Transport Layer Security (TLS) Protocol
Version 1.3", RFC 8446, DOI 10.17487/RFC8446, August 2018,
<https://www.rfc-editor.org/info/rfc8446>.
Appendix A. Design Justification Appendix A. Design Justification
This section provides further insight into the design decisions of This section provides further insight into the design decisions of
the solution documented in this document. Section 3 lists several the solution documented in this document. Section 3 lists several
building blocks and briefly summarizes their importance. The building blocks and briefly summarizes their importance. The
justification for offering some of those building blocks, as opposed justification for offering some of those building blocks, as opposed
to using OAuth 2.0 as is, is given below. to using OAuth 2.0 as is, is given below.
Common IoT constraints are: Common IoT constraints are:
skipping to change at page 51, line 45 skipping to change at page 55, line 35
other protocols such as HTTP, HTTP/2 or other specific protocols, other protocols such as HTTP, HTTP/2 or other specific protocols,
such as Bluetooth Smart communication, that do not necessarily use such as Bluetooth Smart communication, that do not necessarily use
IP could also be used. The latter raises the need for application IP could also be used. The latter raises the need for application
layer security over the various interfaces. layer security over the various interfaces.
In the light of these constraints we have made the following design In the light of these constraints we have made the following design
decisions: decisions:
CBOR, COSE, CWT: CBOR, COSE, CWT:
This framework REQUIRES the use of CBOR [RFC7049] as data format. This framework RECOMMENDS the use of CBOR [RFC7049] as data
Where CBOR data needs to be protected, the use of COSE [RFC8152] format. Where CBOR data needs to be protected, the use of COSE
is RECOMMENDED. Furthermore where self-contained tokens are [RFC8152] is RECOMMENDED. Furthermore where self-contained tokens
needed, this framework RECOMMENDS the use of CWT [RFC8392]. These are needed, this framework RECOMMENDS the use of CWT [RFC8392].
measures aim at reducing the size of messages sent over the wire, These measures aim at reducing the size of messages sent over the
the RAM size of data objects that need to be kept in memory and wire, the RAM size of data objects that need to be kept in memory
the size of libraries that devices need to support. and the size of libraries that devices need to support.
CoAP: CoAP:
This framework RECOMMENDS the use of CoAP [RFC7252] instead of This framework RECOMMENDS the use of CoAP [RFC7252] instead of
HTTP. This does not preclude the use of other protocols HTTP. This does not preclude the use of other protocols
specifically aimed at constrained devices, like, e.g., Bluetooth specifically aimed at constrained devices, like, e.g., Bluetooth
Low Energy (see Section 3.2). This aims again at reducing the Low Energy (see Section 3.2). This aims again at reducing the
size of messages sent over the wire, the RAM size of data objects size of messages sent over the wire, the RAM size of data objects
that need to be kept in memory and the size of libraries that that need to be kept in memory and the size of libraries that
devices need to support. devices need to support.
Access Information: Access Information:
This framework defines the name "Access Information" for data This framework defines the name "Access Information" for data
concerning the RS that the AS returns to the client in an access concerning the RS that the AS returns to the client in an access
token response (see Section 5.6.2). This includes the "profile" token response (see Section 5.6.2). This aims at enabling
and the "rs_cnf" parameters. This aims at enabling scenarios, scenarios, where a powerful client, supporting multiple profiles,
where a powerful client, supporting multiple profiles, needs to needs to interact with a RS for which it does not know the
interact with a RS for which it does not know the supported supported profiles and the raw public key.
profiles and the raw public key.
Proof-of-Possession: Proof-of-Possession:
This framework makes use of proof-of-possession tokens, using the This framework makes use of proof-of-possession tokens, using the
"cnf" claim [I-D.ietf-ace-cwt-proof-of-possession]. A "cnf" claim [I-D.ietf-ace-cwt-proof-of-possession]. A
semantically and syntactically identical request and response semantically and syntactically identical request and response
parameter is defined for the token endpoint, to allow requesting parameter is defined for the token endpoint, to allow requesting
and stating confirmation keys. This aims at making token theft and stating confirmation keys. This aims at making token theft
harder. Token theft is specifically relevant in constrained use harder. Token theft is specifically relevant in constrained use
cases, as communication often passes through middle-boxes, which cases, as communication often passes through middle-boxes, which
skipping to change at page 53, line 10 skipping to change at page 56, line 47
packet gets lost. Thus separating sending of the request and packet gets lost. Thus separating sending of the request and
sending of the access tokens helps to reduce fragmentation. sending of the access tokens helps to reduce fragmentation.
Client Credentials Grant: Client Credentials Grant:
This framework RECOMMENDS the use of the client credentials grant This framework RECOMMENDS the use of the client credentials grant
for machine-to-machine communication use cases, where manual for machine-to-machine communication use cases, where manual
intervention of the resource owner to produce a grant token is not intervention of the resource owner to produce a grant token is not
feasible. The intention is that the resource owner would instead feasible. The intention is that the resource owner would instead
pre-arrange authorization with the AS, based on the client's own pre-arrange authorization with the AS, based on the client's own
credentials. The client can the (without manual intervention) credentials. The client can then (without manual intervention)
obtain access tokens from the AS. obtain access tokens from the AS.
Introspection: Introspection:
This framework RECOMMENDS the use of access token introspection in This framework RECOMMENDS the use of access token introspection in
cases where the client is constrained in a way that it can not cases where the client is constrained in a way that it can not
easily obtain new access tokens (i.e. it has connectivity issues easily obtain new access tokens (i.e. it has connectivity issues
that prevent it from communicating with the AS). In that case that prevent it from communicating with the AS). In that case
this framework RECOMMENDS the use of a long-term token, that could this framework RECOMMENDS the use of a long-term token, that could
be a simple reference. The RS is assumed to be able to be a simple reference. The RS is assumed to be able to
skipping to change at page 56, line 4 skipping to change at page 59, line 41
This section lists the requirements on profiles of this framework, This section lists the requirements on profiles of this framework,
for the convenience of profile designers. for the convenience of profile designers.
o Specify the communication protocol the client and RS the must use o Specify the communication protocol the client and RS the must use
(e.g., CoAP). Section 5 and Section 5.6.4.3 (e.g., CoAP). Section 5 and Section 5.6.4.3
o Specify the security protocol the client and RS must use to o Specify the security protocol the client and RS must use to
protect their communication (e.g., OSCORE or DTLS over CoAP). protect their communication (e.g., OSCORE or DTLS over CoAP).
This must provide encryption, integrity and replay protection. This must provide encryption, integrity and replay protection.
Section 5.6.4.3 Section 5.6.4.3
o Specify how the client and the RS mutually authenticate. o Specify how the client and the RS mutually authenticate.
Section 4 Section 4
o Specify the proof-of-possession protocol(s) and how to select one, o Specify the proof-of-possession protocol(s) and how to select one,
if several are available. Also specify which key types (e.g., if several are available. Also specify which key types (e.g.,
symmetric/asymmetric) are supported by a specific proof-of- symmetric/asymmetric) are supported by a specific proof-of-
possession protocol. Section 5.6.4.2 possession protocol. Section 5.6.4.2
o Specify a unique profile identifier. Section 5.6.4.3 o Specify a unique profile identifier. Section 5.6.4.3
o If introspection is supported: Specify the communication and o If introspection is supported: Specify the communication and
security protocol for introspection.Section 5.7 security protocol for introspection. Section 5.7
o Specify the communication and security protocol for interactions o Specify the communication and security protocol for interactions
between client and AS. Section 5.6 between client and AS. This must provide encryption, integrity
protection, replay protection and a binding between requests and
responses. Section 5 and Section 5.6
o Specify how/if the authz-info endpoint is protected, including how o Specify how/if the authz-info endpoint is protected, including how
error responses are protected. Section 5.8.1 error responses are protected. Section 5.8.1
o Optionally define other methods of token transport than the authz- o Optionally define other methods of token transport than the authz-
info endpoint. Section 5.8.1 info endpoint. Section 5.8.1
Appendix D. Assumptions on AS knowledge about C and RS Appendix D. Assumptions on AS knowledge about C and RS
This section lists the assumptions on what an AS should know about a This section lists the assumptions on what an AS should know about a
client and a RS in order to be able to respond to requests to the client and a RS in order to be able to respond to requests to the
token and introspection endpoints. How this information is token and introspection endpoints. How this information is
skipping to change at page 58, line 28 skipping to change at page 62, line 24
| | Payload: <Request-Payload> | | Payload: <Request-Payload>
| | | |
B: |<--------+ Header: 2.05 Content B: |<--------+ Header: 2.05 Content
| 2.05 | Content-Format: application/ace+cbor | 2.05 | Content-Format: application/ace+cbor
| | Payload: <Response-Payload> | | Payload: <Response-Payload>
| | | |
Figure 17: Token Request and Response Using Client Credentials. Figure 17: Token Request and Response Using Client Credentials.
The information contained in the Request-Payload and the Response- The information contained in the Request-Payload and the Response-
Payload is shown in Figure 18. Payload is shown in Figure 18 Note that the parameter "rs_cnf" from
[I-D.ietf-ace-oauth-params] is used to inform the client about the
resource server's public key.
Request-Payload : Request-Payload :
{ {
"grant_type" : "client_credentials", "grant_type" : "client_credentials",
"req_aud" : "tempSensorInLivingRoom", "req_aud" : "tempSensorInLivingRoom",
"client_id" : "myclient", "client_id" : "myclient",
"client_secret" : "qwerty" "client_secret" : "qwerty"
"req_cnf" : { "req_cnf" : {
"COSE_Key" : { "COSE_Key" : {
"kid" : b64'1Bg8vub9tLe1gHMzV76e8', "kid" : b64'1Bg8vub9tLe1gHMzV76e8',
skipping to change at page 66, line 42 skipping to change at page 70, line 42
F.7. Version -09 to -10 F.7. Version -09 to -10
o Removed CBOR major type numbers. o Removed CBOR major type numbers.
o Removed the client token design. o Removed the client token design.
o Rephrased to clarify that other protocols than CoAP can be used. o Rephrased to clarify that other protocols than CoAP can be used.
o Clarifications regarding the use of HTTP o Clarifications regarding the use of HTTP
F.8. Version -08 to -09 F.8. Version -08 to -09
o Allowed scope to be byte arrays. o Allowed scope to be byte strings.
o Defined default names for endpoints. o Defined default names for endpoints.
o Refactored the IANA section for briefness and consistency. o Refactored the IANA section for briefness and consistency.
o Refactored tables that define IANA registry contents for o Refactored tables that define IANA registry contents for
consistency. consistency.
o Created IANA registry for CBOR mappings of error codes, grant o Created IANA registry for CBOR mappings of error codes, grant
types and Authorization Server Information. types and Authorization Server Information.
o Added references to other document sections defining IANA entries o Added references to other document sections defining IANA entries
in the IANA section. in the IANA section.
F.9. Version -07 to -08 F.9. Version -07 to -08
 End of changes. 79 change blocks. 
245 lines changed or deleted 446 lines changed or added

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