]> Transmute

orie@transmute.industries

Security Javascript Object Signing and Encryption JOSE COSE HPKE This document contains a set of examples using JSON Object Signing and Encryption (JOSE), CBOR Object Signing and Encryption (COSE) and Hybrid Public Key Encryption (HPKE) to protect data. These examples are meant to coverage the edge cases of both JOSE and COSE, including different structures for single and multiple recipients, external additional authenticated data, and key derivation function (KDF) context binding. 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 This document is inspired by Examples of Protecting Content Using JSON Object Signing and Encryption (JOSE) . JOSE support for HPKE is described in . COSE support for HPKE is described in . Both drafts are still work in progress. The current set of examples are incomplete.

Terminology 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. The term "JSON Web Key (JWK)" is defined in . The term "COSE Key" is defined in . The terms "JSON Web Encryption (JWE)", "Direct Key Agreement", "Key Agreement with Key Wrapping", "JWE Compact Serialization" and "General JWE JSON Serialization" are defined in . The terms "Direct Encryption", and "Key Agreement with Key Wrap" are defined in . The term "encapsulated key" is defined in . This document does not define any new terms for JOSE or COSE.

Overview Note that JSON (JavaScript Object Notation) and EDN (Extended Diagnostic Notation) may not exactly match the bytes provided for each example. The hexadecimal encoded binary messages are the source of truth, the JSON and EDN examples are for readability. NOTE: '' line wrapping per in HTTP examples.

Private Key This section provides private key representations that are used throught the following sections. Public key representations for these keys are left as an excercise for the reader. The keys in this section are restricted to a single algorithm in both JOSE and COSE: HPKE-Base-P256-SHA256-AES128GCM. Additional algorithms and their private key representations may be provided in future versions of this draft.

application/jwk+json This section provides a JSON Web Key for HPKE-Base-P256-SHA256-AES128GCM.

JSON Web Key Bytes

JSON Web Key

application/cose-key This section provides a COSE Key for HPKE-Base-P256-SHA256-AES128GCM.

COSE Key Bytes

COSE Key Diagnostic

Direct Encryption JOSE and COSE HPKE both support a "Direct Encryption Mode", where HPKE encrypt a plaintext message and optional additional authenticated data directly to a recipient public key. Note that HPKE Direct Encryption is not exactly the same as "Direct Encryption" as described in and . In this section we provide direct encryption examples to the private keys in the previous section.

Direct Encryption Message

Direct Encryption AAD

application/jose+json

JOSE Direct Encryption Bytes

JOSE Direct Encryption

JOSE Direct Encryption Decoded Protected Header

application/cose

COSE Direct Encryption Bytes

COSE Direct Encryption Diagnostic

Note that JOSE and COSE transport the encapsulated key "ek" differently.

Key Encryption JOSE and COSE HPKE both support a "Key Encryption Mode", where HPKE encrypt a content encryption key to a recipient public key, and a plaintext message and optional additional authenticated with the content encryption key. Note that HPKE Key Encryption Mode is not exactly the same as "Key Agreement with Key Wrap" as described in and . In this section we provide direct encryption examples to the private keys in the previous section.

Key Encryption Message

Key Encryption AAD

application/jose+json

JOSE Key Encryption Bytes

JOSE Key Encryption JSON

JOSE Key Encryption Decoded Protected Header

Note that the ephemeral public key (epk) is present in the protected header due to there only being a single recipient for this message.

application/cose

COSE Key Encryption Bytes

COSE Key Encryption Diagnostic

Security Considerations TODO Security

IANA Considerations This document has no IANA actions.

References Normative References Nokia Nokia Transmute independent This specification defines Hybrid public-key encryption (HPKE) for use with Javascript Object Signing and Encryption (JOSE). HPKE offers a variant of public-key encryption of arbitrary-sized plaintexts for a recipient public key. HPKE works for any combination of an asymmetric key encapsulation mechanism (KEM), key derivation function (KDF), and authenticated encryption with additional data (AEAD) function. Authentication for HPKE in JOSE is provided by JOSE-native security mechanisms or by one of the authenticated variants of HPKE. This document defines the use of the HPKE with JOSE. Transmute Security Theory LLC This specification defines hybrid public-key encryption (HPKE) for use with CBOR Object Signing and Encryption (COSE). HPKE offers a variant of public-key encryption of arbitrary-sized plaintexts for a recipient public key. HPKE works for any combination of an asymmetric key encapsulation mechanism (KEM), key derivation function (KDF), and authenticated encryption with additional data (AEAD) function. Authentication for HPKE in COSE is provided by COSE-native security mechanisms or by one of the authenticated variants of HPKE. This document defines the use of the HPKE with COSE. 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 This document defines two strategies for handling long lines in width-bounded text content. One strategy, called the "single backslash" strategy, is based on the historical use of a single backslash ('\') character to indicate where line-folding has occurred, with the continuation occurring with the first character that is not a space character (' ') on the next line. The second strategy, called the "double backslash" strategy, extends the first strategy by adding a second backslash character to identify where the continuation begins and is thereby able to handle cases not supported by the first strategy. Both strategies use a self-describing header enabling automated reconstitution of the original content. JSON Web Encryption (JWE) represents encrypted content 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 IANA registries defined by that specification. Related digital signature and Message Authentication Code (MAC) capabilities are described in the separate JSON Web Signature (JWS) specification. Concise Binary Object Representation (CBOR) is a data format designed for small code size and small message size. There is a need to be able to define basic security services for this data format. This document defines the CBOR Object Signing and Encryption (COSE) protocol. This specification describes how to create and process signatures, message authentication codes, and encryption using CBOR for serialization. This specification additionally describes how to represent cryptographic keys using CBOR. This document, along with RFC 9053, obsoletes RFC 8152. 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 document contains a set of examples using JSON Object Signing and Encryption (JOSE) technology to protect data. These examples present a representative sampling of JSON Web Key (JWK) objects as well as various JSON Web Signature (JWS) and JSON Web Encryption (JWE) results given similar inputs. 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.

Acknowledgments TODO acknowledge.