# Updates to the ACE-OAuth Framework

[toc]

## Contribution overview

The proposed update is mainly about the following points.

* An alternative, new workflow where the AS (instead of the Client) uploads the Access Token to RS on behalf of the Client.

* New parameters and Access Token claims that enable or improve functionalities in the ACE framework.

* Guidelines on how the new features can specifically enhance the existing transport profiles of ACE.

## New workflow

Instead of the Client \(C\), the AS uploads the Access Token to RS on behalf of C.

Overall design rationale:

* The AS uploads the Access Token to RS just like C would in the used transport profile.
* POST requests from the AS to /authz-info and related responses are protected only when uploading an Access Token for dynamically updating access rights. These messages are protected with the secure association between the AS and RS.
* Other POST requests from the AS to /authz-info and related responses are not protected.
* This is consistent with what is defined in RFC 9202 and RFC 9203 for dynamically updating access rights.

* The AS indicates to C that the Access Token has been posted to RS.
* New parameter ***'token_uploaded'***. The AS includes it with value "true" ("false") in the AS->C access token response, in case of successful (failed) upload of the Access Token to RS.

### Problem 1 - Keep the dynamic update of access rights possible

When performing a dynamic update of access rights, the secure association between AS and RS does not help the RS to retrieve the stored Access Token to supersede. This works in the original workflow where C uploads the new Access Token, since the C<->RS secure association used to protect the message exchange is bound to the stored Access Token to supersede.

In order to cover any current and future transport profile, we need an explicit link between the new Access Token and the current one to supersede. This link has to be present in the new Access Token. In some profiles, such a link is in fact present:

* **OSCORE profile**: the link is the 'kid' parameter within the 'cnf' claim, with the same value of the 'id' parameter in the OSCORE_Input_Material object within the 'cnf' claim from the first Access Token of the current token series.
* **DTLS profile (Pre-Shared Key mode)**: the link is the 'kid' parameter within the 'cnf' claim, with the same value of the 'kid' parameter in the COSE_Key within the 'cnf' claim from the first Access Token of the current token series.
* **EDHOC profile**: the link is the 'kid' parameter within the 'cnf' claim, with the same value of the 'id' parameter in the EDHOC_Information object within the 'cnf' claim from the first Access Token of the current token series.
* Note: the EDHOC profile currently says that a dynamic update of access rights is not possible when using the new workflow. However, it is actually possible by using the construction above.

In the cases above, the dynamic update of access rights is fundamentally possible because there is a value used as de-facto "token series ID". This value does not change throughout the lifetime of a token series, and it is used to link the new Access Token with the previous one in the same series to be superseded.

Such a token series ID has to take a unique value from a namespace/pool under exclusive control of the AS. This is what happens in the three cases above, where the AS is the entity creating the mentioned objects or COSE Key included in the first Access Token of a token series.

However, this is not what happens in the other known cases, i.e., the DTLS profile in Raw Public Key mode and the Group OSCORE profile. In those cases, the dynamic update of access rights is fundamentally not possible, **neither in the original nor in the new workflow**.

In order to allow the dynamic update of access rights to be possible also for such cases, those can rely on an explicit, new parameter and claim ***'token_series_id'***. Irrespective of the workflow used for posting the Access Token to RS:

* The parameter is specified in the AS->C access token response, when issuing the first Access Token in a token series.
* The claim is specified in the first Access Token in a token series.

Later on, when C requests a new Access Token in the same token series for dynamically updating its access rights:

* In the C->AS access token request, the same value is used for the 'kid' parameter within the 'req_cnf' parameter.
* In the new Access Token, the same value is used for the 'kid' parameter within the 'cnf' claim.

As to existing transport profiles, the above has no intention to change the current behavior when the update of access rights occurs, irrespective of the used workflow and especially when using the original workflow.

If future profiles rely on a construction where the AS creates the object or key included in the 'cnf' claim of the first Access Token in a token series, and a unique ID generated by the AS is included in such object or key, then that ID must be used as de-facto "token series ID", rather than the new parameter 'token_series_id'.

**Note**: this new document may need to provide a proto-definition of "token series", that a transport profile can specialize if need be (e.g., like the EDHOC profile does). For sure, all the Access Tokens in a token series are issued by the same AS and for the same pair (Client, Audience).

### Problem 2 - Keep the token re-posting possible (e.g., for key update)

If the AS uploads the Access Token to RS on behalf of C, that makes it impossible for C to re-upload the Access Token to RS by itself, e.g., in order to perform a key update. In fact, C never obtains the actual Access Token.

The "token re-posting" from C can be re-enabled in the alternative workflow, by introducing a new parameter **'token_hash'**. The parameter can be included in the AS->C access token response, upon issuing any Access Token in a token series that AS will upload to RS. The parameter value is the hash computed over the value that the 'access_token' parameter would have in that same response message, if it was included therein.

After that, C can "re-post" the Access Token to RS, by sending to /authz-info a request actually including the parameter 'token_hash' instead of the parameter 'access_token' (possibly together with other parameters, depending on the specific transport profile).

**Note**: This is actually a second reason to introduce such a parameter. In addition to that, this parameter allows C to still benefit from the AS functionality defined in draft-ietf-ace-revoked-token-notification, even when the new workflow is used and C never obtains the Access Token for computing the corresponding hash by itself.

### Problem 3 - Ensure applicability to any ACE profile

Some ACE profiles require that C and RS generate some information to be exchanged contextually with the uploading of the Access Token. Examples:

* **OSCORE profile**: an exchange of the nonces N1 and N2 is required, when posting the first Access Token of a token series, as well as when re-posting any Access Token (e.g., in order to perform a key update).
* **EDHOC profile**: an exchange of the nonces N1 and N2 is required, when re-posting any Access Token in order to renew the OSCORE Security Context through EDHOC-KeyUpdate.

Using the new workflow prevents the above, since the uploading of the Access Token does not rely on a direct interaction of C and RS anymore.

This problem can be solved by having the AS acting as intermediary also for the exchange of C- and RS-generated information, such as nonces. In particular, we can rely on the following two new parameters.

* **'to_rs'**: this can be included in the C->AS access token request, in order to provide the AS with information that has to be uploaded to RS when uploading the Access Token. The ACE profile has to define the detailed content and semantics of what is encapsulated in the parameter value.
* **'from_rs'**: this can be included in the AS->C access token response, in order to provide C with information that has been returned by RS after the uploading of the Access Token. The ACE profile has to define the detailed content and semantics of what is encapsulated in the parameter value.

With reference to the two cases mentioned above, 'to_rs' can specify the nonce N1 generated by C, while 'from_rs' can specify the nonce N2 generated by RS.

## New parameters and claims

### 'rs_cnf2'

**Motivation**: ensure the effective issue of an Access Token based on asymmetric authentication credentials and intended to an "audience" that includes multiple RSs. This is irrespective of the used workflow for uploading an Access Token to RS.

**Where used**: in the AS->C access token response

**Encoding**: CBOR array. Each element of the array is a CBOR map with the same semantics of the parameter 'rs_cnf'. That is, the i-th element of the array is the public authentication credential of the i-th RS in the audience.

**Note**: There is no such issue to address in the Group OSCORE profile, since C does not obtain the asymmetric authentication credentials of the RSs from the AS, but instead from the Group Manager.

### 'subject_ids'

**Motivation**: ensure the effective issue of an Access Token based on asymmetric authentication credentials and intended to an "audience" that includes multiple RSs. This is irrespective of the used workflow for uploading an Access Token to RS.

**Where used**: in the AS->C access token response. This parameter must be included when the parameter 'rs_cnf2' is included.

**Encoding**: CBOR array, with as many elements as in the CBOR array of the parameter 'rs_cnf2'. The i-th element of the array is paired with the i-th element of the array of the parameter 'rs_cnf2', and specifies the URI/CRI that identifies the corresponding RS. Each element of the array is a CBOR text string if encoding a URI, or a CBOR array if encoding a CRI. In either case, the only encoded components are the URI scheme and authority (i.e., no local part).

**Note**: C is ultimately responsible for resolving these RS identifiers into network addresses.

### 'token_uploaded'

**Motivation**: confirm to C that the AS has uploaded the Access Token to AS, as per the new workflow.

**Where used**: in the AS->C access token response

**Encoding**: CBOR simple value "true" or "false"

**Note**: When this parameter is included with value false: i) the CoAP response from the AS still has a 2.04 (Changed) response code; and ii) the AS may want to include the 'token' parameter with value the just issued the Access Token, so that C can try to upload it to the RS by itself.

### 'token_series_id'

**Motivation**: ensure a way to perform dynamic update of access rights when it would not be possible otherwise. Examples: DTLS profile in Raw Public Key mode; Group OSCORE profile. This is irrespective of the used workflow to post the Access Token to the RS.

**Where used (parameter)**: in the AS->C access token response, when issuing the first Access Token in a token series.

**Where used (claim)**: in the first Access Token of a token series.

**Encoding**: CBOR byte string.

### 'token_hash'

**Motivation**: ensure that, even when the new workflow is used, C can still perform a token re-post (e.g., in order to perform key update) and rely on the notification of revoked access tokens from the AS.

**Where used**: in the AS->C access token response

**Encoding**: CBOR byte string

**Note**: If this parameter is included in the AS->C access token response, there is no reason to also include 'token_uploaded' (which would have value "true"), as it would be redundant.

### 'to_rs'

**Motivation**: ensure that, even when the new workflow is used, RS can receive information generated by C and to be exchanged contextually with the uploading of an Access Token.

**Where used**: in the C->AS access token request

**Encoding**: CBOR byte string

### 'from_rs'

**Motivation**: ensure that, even when the new workflow is used, C can receive information generated by RS and to be exchanged contextually with the uploading of an Access Token.

**Where used**: in the AS->C access token response

**Encoding**: CBOR byte string

## How do the existing ACE profiles benefit of this contribution?

For any ACE profile, the following holds.

* The new workflow is effectively possible to use. This is beneficial for deployments where the C<->RS leg is constrained, but the AS<->RS leg is not.

* When the new workflow is used, the parameter 'token_uploaded' confirms to C that the AS has uploaded the Access Token to AS, or informs that the uploading has failed.

* When the AS provides notification of revoked Access Tokens (see draft-ietf-ace-revoked-token-notification), the parameter 'token_hash' ensures that C can still rely on such a service also when the new workflow is used.

### DTLS profile - Raw Public Key mode

https://datatracker.ietf.org/doc/html/rfc9202#name-raw-public-key-mode

* The parameters 'rs_cnf2' and 'subject_ids' ensure the effective issue of an Access Token intended to an "audience" that includes multiple RSs.

* The parameter 'token_series_id' ensures a way to perform dynamic update of access rights, which is otherwise not possible even in the original workflow.

### DTLS profile - Pre-Shared Key mode

https://datatracker.ietf.org/doc/html/rfc9202#name-pre-shared-key-mode

* No benefits provided.

### OSCORE profile

https://datatracker.ietf.org/doc/html/rfc9203

* The parameter 'token_hash' ensures that, if the new workflow is used for the first uploading of an Access Token to RS, then C can still perform a token re-post combined with an exchange of nonces (e.g., in order to update the OSCORE Security Context).

The re-post will however have to happen directly from C to RS, i.e., not through the AS.

* The parameters 'to_rs' and 'from_rs' ensure that, if the new workflow is used for the first uploading of an Access Token to RS, the AS can also relay the nonces N1 and N2 between C and RS.

This enables the use of the OSCORE profile with the new flow altogether, and to accordingly upload through the AS the first Access Token of a token series together the exchange of nonces N1 and N2.

### EDHOC profile

https://datatracker.ietf.org/doc/html/draft-ietf-ace-edhoc-oscore-profile

* The parameters 'rs_cnf2' and 'subject_ids' ensure the effective issue of an Access Token intended to an "audience" that includes multiple RSs.

* The parameter 'token_hash' ensures that, if the new workflow is used for the first uploading of an Access Token to RS, C can still perform a token re-post combined with an exchange of nonces (e.g., in order to renew the OSCORE Security Context through EDHOC-KeyUpdate).

The re-post will however have to happen directly from C to RS, i.e., not through the AS.

* The parameters 'to_rs' and 'from_rs' ensure that, if the new workflow is used for the first uploading of an Access Token to RS, the AS can also relay the nonces N1 and N2 between C and RS.

If the previously completed EDHOC session between C and RS is still valid, this allows C to establish a new OSCORE Security Context through EDHOC-KeyUpdate, following the uploading of the first Access Token of a token series by the AS, with the contextual exchange of N1 and N2 between C and RS through the AS.

### Group OSCORE profile

https://datatracker.ietf.org/doc/html/draft-tiloca-ace-group-oscore-profile

* The parameter 'token_series_id' ensures a way to perform dynamic update of access rights, which is otherwise not possible even in the original workflow.
* Note: in practice, this can happen only as long as the ID Context in the OSCORE group and the Sender ID that C has in the OSCORE group have not changed since the issue of the first Access Token in the token series. After that, C just has to ask for a new Access Token from a new token series. When posted to RS (irrespective of through which workflow), the new Access Token will anyway supersede the old one.