]> Bundesdruckerei GmbH

bastianpaul@googlemail.com

Bundesdruckerei GmbH

kraus.micha@gmail.com

IDsec Solutions

stefan@aaa-sec.com

The Agency for Digital Government

altmann@mail.com

Security Javascript Object Signing and Encryption JOSE JWS This specification defines the use of a Diffie-Hellman key agreement (DH-KA) protocol combined with a key derivation function (KDF) to derive a symmetric Message Authentication Code (MAC) key from public information conveyed within a JSON Web Signature (JWS). About This Document The latest revision of this draft can be found at . Status information for this document may be found at . Discussion of this document takes place on the Javascript Object Signing and Encryption Working Group mailing list (), which is archived at . Subscribe at . Source for this draft and an issue tracker can be found at .

Introduction JSON Web Signature (JWS) and JSON Web Algorithms (JWA) specify how to secure content with Hash-based Message Authentication Codes (HMAC) using a shared symmetric key. These specifications do not provide means to dynamically derive a MAC key for JWS validation using only public information embedded in the JWS. This specification defines a new protected header parameter, pkds (public key derived secret), which contains information required to derive an HMAC key using a Diffie-Hellman key agreement (DH-KA) and a key derivation function (KDF). The JWS Producer's DH-KA public key appears either in the pkds parameter or in a claims element for use in the key agreement computation. The pkds parameter also includes the JWS Recipient's DH-KA public key, used by the JWS Producer during key agreement, as well as the KDF parameters necessary for deriving the MAC key. This specification also defines new alg parameter values, that are fully-specified according to Fully Specified Algorithms. The method is useful in settings where pre-shared keys are undesirable or infeasible, and where direct key distribution or key wrapping introduces operational concerns. It enables the use of HMAC-based signatures that can be validated solely with information embedded in a JWS. A primary motivation for this work is to enable HMAC signature validation from information contained within an SD-JWT, mirroring capabilities available in credential formats like .

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.

Terminology The draft uses "JSON Web Signature", "JOSE Header", "JWS Signature", "JWS Signing Input" as defined by .

Producer:

The party that performs the DH-KA first, derives the MAC key via a KDF, constructs the JOSE Header and JWS Payload, and computes the JWS Signature.

Recipient:

The party that performs the DH-KA second, derives the MAC key via information in the JWS, and validates the JWS using the MAC key according to .

Cryptographic Dependencies This specification relies on the following primitives:

• A Diffie-Hellman Key Agreement (KA-DH), for example ECKA-DH defined in :
  • DH(skX, pkY): Perform a non-interactive Diffie-Hellman exchange using the private key skX and public key pkY to produce a Diffie-Hellman shared secret of length Ndh. This function can raise a ValidationError.
  • Ndh: The length in bytes of a Diffie-Hellman shared secret produced by DH().
  • Nsk: The length in bytes of a Diffie-Hellman private key.
• A key derivation function (KDF), for example HKDF defined in :
  • Extract(salt, ikm): Extract a pseudorandom key of fixed length Nh bytes from input keying material ikm and an optional byte string salt.
  • Expand(prk, info, L): Expand a pseudorandom key prk using optional string info into L bytes of output keying material.
  • Nh: The output size of the Extract() function in bytes.
• A Message Authentication Code algorithm (MAC), for example HMAC defined in :
  • MacSign(k, i): Returns an authenticated tag for the given input i and key k.
  • Nk: The length in bytes of key k.

Public Key Derived HMAC A public key derived HMAC requires three components for an algorithm:

1. a Diffie-Hellman Key Agreement (DHKA)
2. a Key Derivation Function (KDF)
3. a Message Authentication Code algorithm (MAC)

In general, these parameters are chosen by the Producer. These parameters need to be communicated to the Recipient to be able to verify the HMAC.

Signature Generation The generation of the public key derived HMAC uses the Producer’s private key, the Recipient’s public key, and the message as inputs, along with optional parameters. The retrieval and communication of the Recipient's public key is out of scope of this specification and subject to the implementing protocols. Input:

• skP: private key of the Producer
• pkR: public key of the Recipient
• msg: JWS Signing Input
• salt : Optional salt for key derivation
• info : Optional info for key derivation

Function:

Signature Verification The generation of the public key derived HMAC uses the Recipient's private key, the Producer's public key, and the message as inputs, along with optional parameters. Input:

• skR: private key of the Recipient
• pkS: public key of the Producer
• msg: JWS Signing Input
• salt : Optional salt for key derivation
• info : Optional info for key derivation
• signature : the Message Authentication Code

Function:

Signature Suites Algorithms MUST follow the naming **TODO**.

Public Key Derived HMAC for JOSE Public Key Derived HMAC behave like a digital signature as described in Section 3 of and are intended for use in JSON Web Signatures (JWS) as described in . The Producer performs the Message Signature or MAC Computation as defined by Section 5.1 of . The Recipient performs the Message Signature or MAC Validation as defined by Section 5.2 of . The following JWS headers are used to convey Public Key Derived HMAC for JOSE:

• alg : REQUIRED. The algorithm parameter describes the chosen signature suite, for example the ones described in Suites.
• pkds : REQUIRED. The pkds (Public key derived secret) parameter specifies the inputs needed to derive a symmetric key for MAC PKDS Headermake.
• nonce : OPTIONAL. The nonce may be provided by the Recipient additional to it's public key and ensure additional freshness of the signature. If provided, the Producer SHOULD add the nonce to the header.

The "pkds" Header Parameter The pkds protected header parameter specifies the inputs needed to derive a symmetric key for MAC computation using a key agreement and derivation scheme. Its value is a JSON object that includes identifiers, public keys, and algorithm-specific parameters relevant to the derivation.

Syntax and semantics The pkds Header Parameter value MUST be a JSON object with the following fields:

• rpk (object, REQUIRED): The Recipient's public key used in DH-KA. The rpk object MUST contain at least one key claim as defined in Section 4.1 of . Implementations MUST reject a JWS if the rpk key cannot be resolved unambiguously at validation time.
• ppk (object, OPTIONAL): The JWS Producer’s public key used in DH-KA. The ppk object MUST contain at least one key claim as defined in Section 4.1 of . Implementations MUST reject a JWS if the ppk key cannot be resolved unambiguously at validation time or is incompatible with the key information in rpk.
• info (string, OPTIONAL): Context- and application-specific information used as the info parameter to the KDF.

For a machine-readable definition of these fields, see the JSON Schema in Appendix A.

Example JWT (TODO) The JWT/JWS header: The JWT/JWS payload (TODO!: The JWT/JWS signature: This specification described instantiations of Public Key Derived HMAC using specific algorithm combinations:

Security Considerations

Replay Attack Detection Recipient MUST ensure the freshness of signatures by utilizing ephemeral keys in rpk or by providing a nonce for nonce.

Limited Repudiability A malicious Recipient can weaken the repudiability property by involving certain third parties in the protocol steps.

• One method is to have a third party observe all protocol steps so that third party can be sure that the signature originates by the Producer.
• Another method requires that the Recipient's public key is a shared key that has previously been calculated with the keys of certain specific third parties so that the proof of authenticity can be done with Multi Party Computation involving all parties (see ).

IANA Considerations Define:

• define new pkds header parameter
• alg values for TODO and some more

References Normative References JSON Web Signature (JWS) represents content secured with digital signatures or Message Authentication Codes (MACs) using JSON-based data structures. Cryptographic algorithms and identifiers for use with this specification are described in the separate JSON Web Algorithms (JWA) specification and an IANA registry defined by that specification. Related encryption capabilities are described in the separate JSON Web Encryption (JWE) specification. A JSON Web Key (JWK) is a JavaScript Object Notation (JSON) data structure that represents a cryptographic key. This specification also defines a JWK Set JSON data structure that represents a set of JWKs. Cryptographic algorithms and identifiers for use with this specification are described in the separate JSON Web Algorithms (JWA) specification and IANA registries established by that specification. This specification registers cryptographic algorithms and identifiers to be used with the JSON Web Signature (JWS), JSON Web Encryption (JWE), and JSON Web Key (JWK) specifications. It defines several IANA registries for these identifiers. This document describes a scheme for hybrid public key encryption (HPKE). This scheme provides a variant of public key encryption of arbitrary-sized plaintexts for a recipient public key. It also includes three authenticated variants, including one that authenticates possession of a pre-shared key and two optional ones that authenticate possession of a key encapsulation mechanism (KEM) private key. HPKE works for any combination of an asymmetric KEM, key derivation function (KDF), and authenticated encryption with additional data (AEAD) encryption function. Some authenticated variants may not be supported by all KEMs. We provide instantiations of the scheme using widely used and efficient primitives, such as Elliptic Curve Diffie-Hellman (ECDH) key agreement, HMAC-based key derivation function (HKDF), and SHA2. This document is a product of the Crypto Forum Research Group (CFRG) in the IRTF. This document specifies a simple Hashed Message Authentication Code (HMAC)-based key derivation function (HKDF), which can be used as a building block in various protocols and applications. The key derivation function (KDF) is intended to support a wide range of applications and requirements, and is conservative in its use of cryptographic hash functions. This document is not an Internet Standards Track specification; it is published for informational purposes. This document describes HMAC, a mechanism for message authentication using cryptographic hash functions. HMAC can be used with any iterative cryptographic hash function, e.g., MD5, SHA-1, in combination with a secret shared key. The cryptographic strength of HMAC depends on the properties of the underlying hash function. This memo provides information for the Internet community. This memo does not specify an Internet standard of any kind 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. Informative References

Acknowledgments Thanks to:

• Brian Campbell
• John Bradley

Appendix A. JSON Schema for the "pkds" Header Parameter JSON { "$schema": "https://json-schema.org/draft/2020-12/schema", "$id": "https://example.com/schemas/pkds.schema.json", "title": "JOSE Header Parameter: pkds", "type": "object", "properties": { "ppk": { "$ref": "#/$defs/keyRef" }, "rpk": { "$ref": "#/$defs/keyRef" }, "params": { "type": "object" } }, "required": [ "rpk" ], "additionalProperties": false, "$defs": { "keyRef": { "type": "object", "properties": { "jwk": { "type": "object" }, "kid": { "type": "string" }, "jkt": { "type": "string" }, "jku": { "type": "string" }, "x5c": { "type": "array", "items": { "type": "string" } }, "x5u": { "type": "string" }, "x5t": { "type": "string" } }, "anyOf": [ { "required": [ "jwk" ] }, { "required": [ "kid" ] }, { "required": [ "jkt" ] }, { "required": [ "jku" ] }, { "required": [ "x5c" ] }, { "required": [ "x5u" ] }, { "required": [ "x5t" ] } ], "additionalProperties": false } } }