JOSE: JavaScript Object Signing and Encryption

Definition

The Five JOSE Specifications

The JOSE framework consists of five interrelated specifications, each published as an IETF RFC (Request for Comments). Understanding how these pieces fit together is essential for working with EUDI Wallet credential formats.

JWS (RFC 7515) defines how to digitally sign or create a MAC (Message Authentication Code) for arbitrary content using JSON-based data structures. JWS supports two serialization formats: compact (a URL-safe string with three Base64URL-encoded parts separated by dots) and JSON (a full JSON object). In EUDI Wallets, JWS is used to sign credentials, ensuring their integrity and authenticity.

JWE (RFC 7516) defines how to encrypt content, providing confidentiality. Like JWS, it supports both compact and JSON serialization. JWE uses a two-layer encryption approach: a Content Encryption Key (CEK) encrypts the payload, and the CEK itself is encrypted with the recipient's public key. This is used in EUDI Wallet communications to protect sensitive credential data in transit.

JWK (RFC 7517) defines a JSON format for representing cryptographic keys, including RSA, elliptic curve, and symmetric keys. JWK Sets allow multiple keys to be grouped together, facilitating key rotation and discovery. EUDI Wallet issuers publish their public keys as JWK Sets, enabling verifiers to validate credential signatures.

JWT (RFC 7519) defines a compact, URL-safe format for representing claims between parties. A JWT is either a JWS or JWE with a JSON claims payload. EUDI Wallet credentials in SD-JWT format are built on top of JWT, with additional mechanisms for selective disclosure.

JWA (RFC 7518) registers the cryptographic algorithms used by JWS, JWE, and JWK. It defines algorithm identifiers like ES256 (ECDSA with P-256 and SHA-256), RS256 (RSASSA-PKCS1-v1_5 with SHA-256), and A256GCM (AES-256 in GCM mode). The EUDI Wallet specifications mandate specific algorithms from this registry for interoperability.

JOSE in EUDI Wallet Credential Formats

The EUDI Wallet Architecture and Reference Framework defines two primary credential formats: ISO 18013-5 mDoc (using CBOR encoding) and SD-JWT (using JOSE encoding). The SD-JWT format is the JOSE-based credential format, built entirely on the JOSE stack for signing, encryption, and key management.

When an issuer creates an SD-JWT verifiable credential, the process involves creating a JWT containing the credential claims (name, date of birth, address, etc.), signing it with the issuer's private key using JWS, and optionally adding hash-based selective disclosure mechanisms. The issuer's public key is published as a JWK, allowing any verifier to validate the signature.

During credential presentation via OpenID4VP, the wallet constructs a verifiable presentation that includes the original SD-JWT credential and disclosures for the specific claims the verifier requested. The entire presentation is itself wrapped in a JOSE structure, with the wallet applying a key binding proof using its device key. This layered use of JOSE ensures end-to-end security from issuance through presentation.

Security Considerations and Algorithm Selection

The security of the entire EUDI Wallet credential ecosystem depends on the proper use of JOSE cryptographic primitives. The EU ARF specifies which algorithms from JWA are acceptable for EUDI Wallet operations, generally requiring ECDSA with P-256 (ES256) or EdDSA with Ed25519 for digital signatures, and ECDH-ES with A256GCM for encryption.

Implementers must follow JOSE security best practices including validating all input according to the relevant RFCs, checking algorithm headers against an allowlist to prevent algorithm confusion attacks, using appropriate key lengths, implementing proper key rotation procedures, and rejecting tokens with missing or unexpected headers.

The JOSE library ecosystem is mature, with well-maintained implementations available in Java (Nimbus JOSE+JWT), JavaScript/TypeScript (jose), Python (python-jose), Go (go-jose), Rust (josekit), and virtually every other major programming language. This broad support is one reason JOSE was selected as the cryptographic foundation for the EUDI Wallet's JWT-based credential format.

Related Terms