]> Okta

panva.ip@gmail.com

Security Web Authorization Protocol oauth pkce dpop mtls This document defines SHA-384 as an additional hash algorithm option for OAuth 2.0 Proof Key for Code Exchange (PKCE), Demonstrating Proof of Possession (DPoP), and mutual-TLS certificate-bound access tokens. These mechanisms currently mandate the use of SHA-256. About This Document Status information for this document may be found at . Source for this draft and an issue tracker can be found at .

Introduction Several OAuth 2.0 mechanisms exclusively mandate the use of SHA-256: Proof Key for Code Exchange (PKCE) , Demonstrating Proof of Possession (DPoP) , and mutual-TLS certificate-bound access tokens . Security policies, such as the US Commercial National Security Algorithm (CNSA 2.0) Suite , prohibit the use of SHA-256 and mandate SHA-384 as the minimum acceptable hash algorithm. This prevents the deployment of these OAuth 2.0 mechanisms in such environments. This document addresses this gap by defining SHA-384 alternatives for each of these mechanisms. For PKCE, a new S384 code challenge method is defined. For mutual-TLS certificate-bound access tokens, a new x5t#S384 confirmation method is defined. For DPoP, this document defines SHA-384 alternatives for the JWK Thumbprint confirmation method (jkt#S384) and the access token hash claim (ath#S384), as well as an extensible framework for DPoP authorization code binding and access token hash algorithm negotiation.

Conventions and Definitions The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in BCP 14 when, and only when, they appear in all capitals, as shown here. All references to "CNSA 2.0" in this document refer to CNSA 2.0 , unless stated otherwise.

SHA-384 PKCE Code Challenge Method

S384 Code Challenge Method This document defines a new code challenge method for use with PKCE . The client creates a code challenge derived from the code verifier by using the following transformation on the code verifier:

S384:

code_challenge = BASE64URL(SHA-384(ASCII(code_verifier)))

The server-side verification of the code verifier follows , using SHA-384 as the hash algorithm.

Authorization Server Metadata An Authorization Server that supports the S384 code challenge method MUST advertise its support by including S384 in the code_challenge_methods_supported metadata parameter value, as defined in OAuth 2.0 Authorization Server Metadata or OpenID Connect Discovery 1.0 . A Client intending to use the S384 code challenge method MUST first confirm that the Authorization Server supports it by checking the code_challenge_methods_supported metadata value. A Client MUST NOT use the S384 code challenge method if the Authorization Server does not advertise support for it.

DPoP Authorization Code Binding Methods

dpop_jkt_method Authorization Request Parameter RFC 9449 defines the dpop_jkt authorization request parameter as the JWK Thumbprint of the DPoP public key using SHA-256. This document defines the dpop_jkt_method authorization request parameter, sent alongside dpop_jkt, to indicate the hash algorithm used to compute the JWK Thumbprint. The following method values are defined:

S256:

JWK Thumbprint using SHA-256, as originally defined in .

S384:

JWK Thumbprint using SHA-384.

When dpop_jkt_method is absent from the authorization request, the Authorization Server MUST assume the value S256. The value of dpop_jkt MUST be computed using the hash algorithm indicated by dpop_jkt_method.

DPoP Authorization Server Metadata This document defines the dpop_jkt_methods_supported Authorization Server metadata parameter. Its value is a JSON array containing the dpop_jkt_method values that the Authorization Server supports. An Authorization Server that supports dpop_jkt_method values beyond S256 MUST advertise its support by including the supported values in the dpop_jkt_methods_supported metadata parameter. A Client intending to use a dpop_jkt_method value other than S256 MUST first confirm that the Authorization Server supports it by checking the dpop_jkt_methods_supported metadata value. A Client MUST NOT use a dpop_jkt_method value that the Authorization Server does not advertise support for.

SHA-384 DPoP Hash Algorithms

jkt#S384 Confirmation Method RFC 9449 defines the jkt confirmation method member for binding access tokens to a DPoP public key using a SHA-256 JWK Thumbprint . This document defines an analogous confirmation method member jkt#S384 that uses SHA-384 as the hash algorithm:

jkt#S384:

The value is the base64url encoding of the JWK Thumbprint computed using SHA-384 of the DPoP public key (in JWK format) to which the access token is bound.

When using jkt#S384, the Authorization Server computes the SHA-384 JWK Thumbprint of the DPoP public key and includes the result as the jkt#S384 member of the cnf claim in the access token (for JWT access tokens) or associates it with the token for later retrieval via token introspection. The Resource Server MUST compute the SHA-384 JWK Thumbprint of the DPoP public key and compare it with the jkt#S384 value in the cnf claim. If the values do not match, the Resource Server MUST reject the request. The choice of jkt#S384 over jkt is a deployment decision based on the Resource Server configuration at the Authorization Server.

ath#S384 Access Token Hash RFC 9449 defines the ath claim in the DPoP proof JWT as the base64url-encoded SHA-256 hash of the ASCII encoding of the access token value. This document defines an analogous claim ath#S384 that uses SHA-384 as the hash algorithm:

ath#S384:

The value is the base64url encoding of the SHA-384 hash of the ASCII encoding of the associated access token's value.

When used, ath#S384 is included in the DPoP proof JWT in place of ath. A Client that used a dpop_jkt_method value of S384 during the authorization request MUST use ath#S384 in DPoP proofs sent to Resource Servers. A Resource Server MAY signal the required access token hash method by including the ath_method parameter in the WWW-Authenticate: DPoP challenge. The value of ath_method is the name of the claim the Client MUST use: ath for SHA-256 or ath#S384 for SHA-384. When ath_method is absent, the Client MUST use ath.

Resource Server Metadata This document defines the dpop_ath_methods_supported Resource Server metadata parameter . Its value is a JSON array containing the access token hash claim names that the Resource Server supports. Defined values are ath and ath#S384. When this metadata parameter is absent, the Client MUST assume that the Resource Server supports only ath.

SHA-384 Mutual-TLS Certificate Hash

x5t#S384 Confirmation Method RFC 8705 defines the x5t#S256 confirmation method member for binding access tokens to a client certificate using a SHA-256 hash of the DER-encoded X.509 certificate. This document defines an analogous confirmation method member x5t#S384 that uses SHA-384 as the hash algorithm:

x5t#S384:

The value is a base64url-encoded SHA-384 hash of the DER encoding of the X.509 certificate.

When using x5t#S384, the Authorization Server computes the SHA-384 hash of the client certificate presented during mutual-TLS and includes the result as the x5t#S384 member of the cnf claim in the access token (for JWT access tokens) or associates it with the token for later retrieval via token introspection. The Resource Server MUST compute the SHA-384 hash of the client certificate presented during mutual-TLS and compare it with the x5t#S384 value in the cnf claim. If the values do not match, the Resource Server MUST reject the request. The choice of x5t#S384 over x5t#S256 is a deployment decision based on the Resource Server configuration at the Authorization Server.

Security Considerations The S384 code challenge method provides the same structural security properties as S256. It is a one-way transformation of the code verifier that prevents an attacker who intercepts the authorization code from computing the code verifier needed to exchange it for tokens. The jkt#S384 confirmation method, dpop_jkt_method parameter, and ath#S384 claim provide the same structural security properties as their SHA-256 counterparts defined in DPoP . The authorization code binding via dpop_jkt and the access token binding via ath remain intact regardless of the hash algorithm used. SHA-384 provides a 192-bit collision resistance and 384-bit preimage resistance, exceeding the 128-bit and 256-bit levels provided by SHA-256. The use of SHA-384 is suitable for deployments with elevated security requirements. Deployments that do not have specific requirements mandating SHA-384 do not need to migrate away from the established SHA-256 based mechanisms.

IANA Considerations

PKCE Code Challenge Method Registration This document requests registration of the following value in the "PKCE Code Challenge Methods" registry established by :

Code Challenge Method Parameter Name:

S384

Change Controller:

IETF

Specification Document(s):

of this document

DPoP Authorization Code Binding Methods Registry This document establishes the "DPoP Authorization Code Binding Methods" registry for dpop_jkt_method values. New entries are registered using the Specification Required policy . The initial contents of the registry are:

Method Name:

S256

Change Controller:

IETF

Specification Document(s):

Method Name:

S384

Change Controller:

IETF

Specification Document(s):

of this document

OAuth Parameters Registrations This document requests registration of the following value in the "OAuth Parameters" registry established by :

Parameter Name:

dpop_jkt_method

Parameter Usage Location:

authorization request

Change Controller:

IETF

Specification Document(s):

of this document

OAuth Authorization Server Metadata Registration This document requests registration of the following value in the "OAuth Authorization Server Metadata" registry established by :

Metadata Name:

dpop_jkt_methods_supported

Metadata Description:

JSON array containing a list of the dpop_jkt_method values supported by the Authorization Server

Change Controller:

IETF

Specification Document(s):

of this document

JWT Claims Registration This document requests registration of the following value in the "JSON Web Token Claims" registry established by :

Claim Name:

ath#S384

Claim Description:

The base64url-encoded SHA-384 hash of the ASCII encoding of the associated access token's value

Change Controller:

IETF

Specification Document(s):

of this document

OAuth Protected Resource Metadata Registration This document requests registration of the following value in the "OAuth Protected Resource Metadata" registry established by :

Metadata Name:

dpop_ath_methods_supported

Metadata Description:

JSON array containing a list of the access token hash claim names supported by the Resource Server

Change Controller:

IETF

Specification Document(s):

of this document

JWT Confirmation Methods Registrations This document requests registration of the following values in the "JWT Confirmation Methods" registry established by :

Confirmation Method Value:

x5t#S384

Confirmation Method Description:

X.509 Certificate SHA-384 Thumbprint

Change Controller:

IETF

Specification Document(s):

of this document

Confirmation Method Value:

jkt#S384

Confirmation Method Description:

JWK SHA-384 Thumbprint

Change Controller:

IETF

Specification Document(s):

of this document

References Normative References OAuth 2.0 public clients utilizing the Authorization Code Grant are susceptible to the authorization code interception attack. This specification describes the attack as well as a technique to mitigate against the threat through the use of Proof Key for Code Exchange (PKCE, pronounced "pixy"). This specification defines a method for computing a hash value over a JSON Web Key (JWK). It defines which fields in a JWK are used in the hash computation, the method of creating a canonical form for those fields, and how to convert the resulting Unicode string into a byte sequence to be hashed. The resulting hash value can be used for identifying or selecting the key represented by the JWK that is the subject of the thumbprint. This specification defines a metadata format that an OAuth 2.0 client can use to obtain the information needed to interact with an OAuth 2.0 authorization server, including its endpoint locations and authorization server capabilities. This document describes OAuth client authentication and certificate-bound access and refresh tokens using mutual Transport Layer Security (TLS) authentication with X.509 certificates. OAuth clients are provided a mechanism for authentication to the authorization server using mutual TLS, based on either self-signed certificates or public key infrastructure (PKI). OAuth authorization servers are provided a mechanism for binding access tokens to a client's mutual-TLS certificate, and OAuth protected resources are provided a method for ensuring that such an access token presented to it was issued to the client presenting the token. This document describes a mechanism for sender-constraining OAuth 2.0 tokens via a proof-of-possession mechanism on the application level. This mechanism allows for the detection of replay attacks with access and refresh tokens. This specification defines a metadata format that an OAuth 2.0 client or authorization server can use to obtain the information needed to interact with an OAuth 2.0 protected resource. In many standards track documents several words are used to signify the requirements in the specification. These words are often capitalized. This document defines these words as they should be interpreted in IETF documents. This document specifies an Internet Best Current Practices for the Internet Community, and requests discussion and suggestions for improvements. RFC 2119 specifies common key words that may be used in protocol specifications. This document aims to reduce the ambiguity by clarifying that only UPPERCASE usage of the key words have the defined special meanings. Many protocols make use of identifiers consisting of constants and other well-known values. Even after a protocol has been defined and deployment has begun, new values may need to be assigned (e.g., for a new option type in DHCP, or a new encryption or authentication transform for IPsec). To ensure that such quantities have consistent values and interpretations across all implementations, their assignment must be administered by a central authority. For IETF protocols, that role is provided by the Internet Assigned Numbers Authority (IANA). In order for IANA to manage a given namespace prudently, it needs guidelines describing the conditions under which new values can be assigned or when modifications to existing values can be made. If IANA is expected to play a role in the management of a namespace, IANA must be given clear and concise instructions describing that role. This document discusses issues that should be considered in formulating a policy for assigning values to a namespace and provides guidelines for authors on the specific text that must be included in documents that place demands on IANA. This document obsoletes RFC 2434. This document specifies an Internet Best Current Practices for the Internet Community, and requests discussion and suggestions for improvements. The OAuth 2.0 authorization framework enables a third-party application to obtain limited access to an HTTP service, either on behalf of a resource owner by orchestrating an approval interaction between the resource owner and the HTTP service, or by allowing the third-party application to obtain access on its own behalf. This specification replaces and obsoletes the OAuth 1.0 protocol described in RFC 5849. [STANDARDS-TRACK] JSON Web Token (JWT) is a compact, URL-safe means of representing claims to be transferred between two parties. The claims in a JWT are encoded as a JSON object that is used as the payload of a JSON Web Signature (JWS) structure or as the plaintext of a JSON Web Encryption (JWE) structure, enabling the claims to be digitally signed or integrity protected with a Message Authentication Code (MAC) and/or encrypted. This specification describes how to declare in a JSON Web Token (JWT) that the presenter of the JWT possesses a particular proof-of- possession key and how the recipient can cryptographically confirm proof of possession of the key by the presenter. Being able to prove possession of a key is also sometimes described as the presenter being a holder-of-key. Informative References National Security Agency

Acknowledgments TODO acknowledge.