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:

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 and draft-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.