dcaf library
An implementation of the ACE-OAuth framework.
This library implements the ACE-OAuth
(Authentication and Authorization for Constrained Environments
using the OAuth 2.0 Framework) framework as defined in
draft-ietf-ace-oauth-authz-46
.
Its main feature is CBOR-(de-)serializable data models such as
AccessTokenRequest.
This library is heavily based on dcaf-rs
,
a similar implementation of the ACE-OAuth framework in Rust, which is
intended for all actors in the ACE-OAuth protocol flow
(e.g. Authorization Servers too). In contrast, this library is mainly
intended for the "Client", hence missing some features present in dcaf-rs
.
Note that actually transmitting the serialized values (e.g. via CoAP) is out of scope for this library.
The name DCAF was chosen because eventually, it's planned for this
library to support functionality from the
Delegated CoAP Authentication and Authorization Framework (DCAF)
specified in draft-gerdes-ace-dcaf-authorize
(which was specified prior to ACE-OAuth and inspired many design
choices in it)---specifically, it's planned to support using a CAM
(Client Authorization Manager)
instead of just a SAM (Server Authorization Manager),
as is done in ACE-OAuth.
Compatibility with the existing DCAF implementation in C
(which we'll call libdcaf
to disambiguate from dcaf
referring
to this library) is also an additional design goal, though the primary
objective is still to support ACE-OAuth.
Example
As mentioned, the main feature of this library is ACE-OAuth data models.
For example,
say you (the client) want to request an access token from an
Authorization Server. For this, you'd need to create an
AccessTokenRequest, which has to include at least a
clientId
. We'll also specify an audience,
a scope (using TextScope---note that
BinaryScopes or AifScopes would also work), as well as a
ProofOfPossessionKey
(the key the access token should be bound to) in the reqCnf
field.
Creating, serializing and then de-serializing such a structure would look like this:
final request = AccessTokenRequest(
clientId: "myclient",
audience: "valve242",
scope: TextScope("read"),
reqCnf: KeyId([0xDC, 0xAF]));
final List<int> serialized = request.serialize();
assert(AccessTokenRequest.fromSerialized(serialized) == request);
Provided Data Models
Token Endpoint
The most commonly used models will probably be the token endpoint's AccessTokenRequest and AccessTokenResponse described in section 5.8 of the ACE-OAuth draft. In case of an error, an ErrorResponse should be used.
After an initial Unauthorized Resource Request Message, an AuthServerRequestCreationHint can be used to provide additional information to the client, as described in section 5.3 of the ACE-OAuth draft.
Common Data Types
Some types used across multiple scenarios include:
- Scope (as described in section 5.8.1 of the ACE-OAuth draft), either as a TextScope, BinaryScope, or an AifScope.
- ProofOfPossessionKey as specified in section 3.1 of RFC 8747.
For example, this will be used in the access token's
cnf
claim.
Classes
- AccessTokenRequest
-
Request for an access token, sent from the client, as defined in
section 5.8.1 of
draft-ietf-ace-oauth-authz
. - AccessTokenResponse
-
Response to an AccessTokenRequest containing the Access Token
among additional information, as defined in
section 5.8.2 of
draft-ietf-ace-oauth-authz
. - AifScope
- A scope encoded using the Authorization Information Format (AIF) for ACE.
- AifScopeElement
- An element as part of an AifScope, consisting of a path and a set of permissions which are specified as a set of REST methods.
- AuthServerRequestCreationHint
- This is sent by an RS as a response to an Unauthorized Resource Request Message to help the sender of the Unauthorized Resource Request Message acquire a valid access token.
- BinaryScope
- A scope encoded using a custom binary encoding. See Scope for more information.
- CoseKey
- A COSE Key structure as specified in RFC 8152, section 7.
- EncryptedCoseKey
- An encrypted CoseKey used to represent a symmetric key.
- ErrorResponse
- Details about an error which occurred for an access token request.
- LibdcafScope
- A scope encoded using the Authorization Information Format (AIF) for ACE as in AifScope, but only consisting of a single AifScopeElement instead of an array of them.
- PlainCoseKey
- An unencrypted CoseKey used to represent an asymmetric public key or (if the CWT it's contained in is encrypted) a symmetric key.
- PlainKeyId
- Proof-of-possession key represented by only its Key ID.
- ProofOfPossessionKey
- A proof-of-possession key as specified by RFC 8747, section 3.1.
- Scope
-
Scope of an access token as specified in
draft-ietf-ace-oauth-authz
, section 5.8.1. - TextScope
- A scope encoded as a space-delimited list of strings, as defined in RFC 6749, section 1.3.
Enums
- AceProfile
-
Profiles for ACE-OAuth as specified in section 5.8.4.3 of
draft-ietf-ace-oauth-authz
. - AifRestMethod
- Possible REST (CoAP or HTTP) methods, intended for use in an AifScopeElement.
- Algorithm
-
COSE algorithms as described in
draft-ietf-cose-rfc8152bis-algs
anddraft-ietf-cose-hash-algs
. - ErrorCode
-
Error code specifying what went wrong for a token request, as specified in
section 5.2 of RFC 6749 and
section 5.8.3 of
draft-ietf-ace-oauth-authz
. - GrantType
- Type of the resource owner's authorization used by the client to obtain an access token. For more information, see section 1.3 of RFC 6749.
- KeyOperation
- An operation that a key can be used for, as defined in Table 4 of section 7.1 of RFC 8152.
- KeyType
- Denotes a family of keys.
- TokenType
- The type of the token issued as described in section 7.1 of RFC 6749.