End-to-End Encryption

Overview

End-to-End Encryption (E2E Encryption) provides an additional layer of security for credential issuance workflows where intermediary services are involved between the credential issuer and the wallet application.

In some credential issuance scenarios, a wallet application's backend server acts as a proxy or middleman between the credential issuer (MATTR VII) and individual wallet app instances. In these architectures, the credential response passes through the wallet provider's backend infrastructure before reaching the specific wallet instance on a user's device.

E2E Encryption ensures that credential data and personally identifiable information (PII) remain confidential and unreadable to intermediary backend servers, even as they facilitate the credential delivery process. The credentials are encrypted end-to-end, from the issuer directly to the specific wallet instance, ensuring that only the intended recipient can decrypt and access the credential data.

To understand where End-to-End Encryption fits within the credential issuance process, consider the standard OpenID4VCI workflow:

1. The wallet obtains an Authorization Code (either after the user authenticates with the configured authentication provider in an Authorization Code flow, or directly from the credential offer in a Pre-authorized Code flow).
2. The wallet makes a request to a Token endpoint to exchange the Authorization Code for a Token.
3. The wallet makes a request to the credential endpoint to issue the credential using the Token.
4. The MATTR VII tenant responds with the issued credential.

With End-to-End Encryption enabled, both the credential request (step 3) and the credential response (step 4) can be encrypted.

Request encryption and response encryption are independent, allowing implementations to encrypt just the request, just the response, or both. When both the request and response are encrypted, this provides complete End-to-End (E2E) Encryption throughout the credential issuance process.

How it works

End-to-End Encryption operates through a policy-based system that can be configured on a per-issuer, per-client (wallet app) basis. This flexible approach allows issuers to set specific encryption requirements for different wallet applications based on their security and privacy needs:

• Encryption Policies: Configure encryption requirements for both credential requests and credential responses independently, providing granular control over data protection throughout the issuance workflow.
  • Request Encryption Policy: Determine whether wallet applications must encrypt their credential requests (Required or Optional), ensuring sensitive information in the request is protected in transit.
  • Response Encryption Policy: Determine whether credential responses must be encrypted back to the wallet instance (Required or Optional), protecting issued credentials and PII from intermediary visibility.
• OpenID4VCI Compliance: Encryption policies can be declared through the standard .well-known/openid-credential-issuer endpoint to comply with OpenID4VCI-compliant wallet applications. However, per-client policies configured in MATTR VII take precedence over metadata declarations.
• HPKE Support: MATTR VII currently supports Hybrid Public Key Encryption (HPKE) for both request and response encryption, providing modern, standards-based cryptographic protection. This release focuses on HPKE-7. Support for additional algorithms, such as HPKE-0, is planned for future updates to broaden interoperability and flexibility.

Setting encryption policies

Encryption policies are established for trusted wallet applications. Each policy defines the encryption requirements for that specific wallet client's interaction with the issuer:

• Request Encryption Policy: Whether the wallet client must encrypt credential requests sent to the MATTR VII tenant:

  • Required: Wallet must encrypt all credential requests. MATTR VII will reject unencrypted requests from this wallet.
  • Optional: Wallet may send encrypted or unencrypted requests. MATTR VII will accept both.

• Response Encryption Policy: Whether MATTR VII must encrypt credential responses to this wallet:

  • Required: MATTR VII will encrypt all credential responses to this wallet.
  • Optional: MATTR VII will encrypt credential responses based on wallet request. If no encryption details are provided, the response will be unencrypted.

Credential request encryption

When a wallet application sends an encrypted credential request, MATTR VII will decrypt it as part of the issuance flow. The system enforces the configured encryption policies and handles various scenarios:

Encrypting the request

To encrypt the request, follow the encryption process defined in HPKE with JWE.

The following simplified steps are derived from Section 7.1 of the specification, focusing on Integrated Encryption Mode with HPKE-7 and encoded with JWE Compact Serialization:

1. Retrieve the credential request encryption key from the well-known credential issuer metadata endpoint.
2. Establish the HPKE sender context:

• The recipient public key should be the public key extracted from the credential issuer metadata in the previous step.
• No info is required.

3. Construct the credential_request as a JSON object:

{
  "format": "mso_mdoc",
  "doctype": "org.iso.18013.5.1.mDL2",
  "credential_response_encryption": {
      "jwk": {
          "kid": "yCnfbmYMZcWrKDt_DjNebRCB1vxVoqv4umJ4WK8RYjk",
          "kty": "EC",
          "use": "enc",
          "alg": "HPKE-7",
          "crv": "P-256",
          "x": "gixQJ0qg4Ag-6HSMaIEDL_zbDhoXavMyKlmdn__AQVE",
          "y": "ZxTgRLWaKONCL_GbZKLNPsW9EW6nBsN4AwQGEFAFFbM"
      },
      "enc": "A256GCM"
  },
  "proof": {
      "proof_type": "jwt",
      "jwt": "eyJhbGciOiJFUzI1NiIsImp3ayI6eyJrdHkiOiJFQyIsIngiOiJZY1pHUXV6X0ZkQVFuTGM5MDY1RWJDM29PQ3dZd0lWZ0hSUFFSX0R3aXVNIiwieSI6InVqcDg4ZTBjWEo0SkZjeWRCZEt6clFaazM1X2puOWVjanhaTTdkbFpleU0iLCJjcnYiOiJQLTI1NiJ9fQ.eyJqdGkiOiJiN2NmMjcxZC0yMmFiLTRlN2ItYjM5MS1mOGM0YmM4MmFkM2EiLCJpc3MiOiJtb2JpbGV3YWxsZXQiLCJhdWQiOiJodHRwczovL2VuZy1jeS52aWkuYXUzMDEubWF0dHJsYWJzLmlvIiwiaWF0IjoxNzY1NzQ1NTU5fQ.tyNqDw7rkOmRrOeBEDYdeMqOlKq2VrkcvKLAH_hYCWtKHBwXO631AHBGMCOroh8ZYc2kOFp1THWsEIBYExK6EQ"
  }
}

3. Construct the jwe_protect_header as a JSON object:

{
  "alg": "HPKE-7", // HPKE base mode
  "enc": "A256GCM",
  "kid": RECIPIENT_PUBLIC_JWK.kid,
};

4. Compute encoded_jwe_protect_header as base64url(UTF8(JSON.stringify(jwe_protect_header))).
5. Encrypt HPKE with sender context:

• plaintext should be the binary encoded credential_request created above.
• Additional data (aad) should be the UTF8(encoded_jwe_protect_header).

6. Construct the JWE as a JWE Compact serialization format:

{encoded_jwe_protect_header}.{encoded_encrypted_key}.{encoded_iv}.{encoded_ciphertext}.{encoded_tag}

• encoded_encrypted_key should be the base64Url encoded encapsulated key from the sender context.
• encoded_ciphertext should be the base64url encoded encrypted data from step 5.
• encoded_iv should be an empty string.
• encoded_tag should be an empty string.

7. Share the resulting JWE string as the value of the credential_request parameter when making a request to the credential endpoint.

Credential request encryption metadata

The issuer's encryption capabilities are declared in the .well-known/openid-credential-issuer endpoint metadata. This allows wallet applications to discover the issuer's encryption support and requirements.

The credential_request_encryption object declares the issuer's ability to receive and decrypt credential requests:

{
  "credential_request_encryption": {
    "jwks": {
      "keys": [
        {
          "kty": "EC",
          "kid": "issuer-enc-key",
          "use": "enc",
          "crv": "P-256",
          "alg": "HPKE-7",
          "x": "YO4epjifD-KWeq1sL2tNmm36BhXnkJ0He-WqMYrp9Fk",
          "y": "Hekpm0zfK7C-YccH5iBjcIXgf6YdUvNUac_0At55Okk"
        }
      ]
    },
    "enc_values_supported": ["A256GCM"],
    "encryption_required": false
  }
}

Credential response encryption

MATTR VII can encrypt credential responses to specific wallet instances using encryption keys provided by the wallet application. This follows the OpenID4VCI standard for credential response encryption.

Encryption key provisioning

When encrypting credential responses, MATTR VII uses the specific encryption key provided by the individual wallet instance claiming the credential, ensuring that only that instance can decrypt and access the credential.

Wallet applications provide encryption details in the credential request through the credential_response_encryption parameter when making a request to the credential endpoint:

{
  "credential_response_encryption": {
    "jwk": {
      "kid": "wallet-instance-key",
      "kty": "EC",
      "use": "enc",
      "crv": "P-256",
      "alg": "HPKE-7",
      "x": "...",
      "y": "..."
    },
    "enc": "A256GCM"
  }
}

• jwks : Contains the recipient (wallet instance) public key for encryption, this should be a key from the wallet client
  • alg :
    • Must be an HPKE-7, which refers to JWE Integrated Encryption with HPKE using DHKEM (P-256, HKDF-SHA256) KEM, HKDF-SHA256 KDF, and AES-256-GCM AEAD.
    • Must be a P-256 public key, which is required for HPKE-7.
• enc : must be A256GCM, required for HPKE-7.

Decrypting the response

The contents of an encrypted response will be encoded with JWE Compact Serialization format, with the media type set to application/jwt (instead of application/json used for unencrypted credential responses).

To decrypt the response content, follow the decryption process defined in HPKE with JWE.

The following simplified steps are derived from Section 7.2 of the specification, focusing on Integrated Encryption Mode with HPKE-7 and encoded with JWE Compact Serialization:

1. Parse the JWE Compact Serialization, splitting the JWE string into its five base64url-encoded components:

{encoded_protected_header}.{encoded_encrypted_key}.{encoded_iv}.{encoded_ciphertext}.{encoded_tag}

2. base64url decode and parse encoded_protected_header as JSON and validate the header payload. The headers should contain the following key material:

• alg should be HPKE-7.
• kid is optional depending on presence of kid in credential_response_encryption.jwks

{ 
  "alg":"HPKE-7",
  "kid":"{wallet-key-identifier}"
}

3. Establish the HPKE recipient context:

• The recipient key should be the private key of selected key from credential_response_encryption.jwk.
• The encapsulated key should be the base64Url decoded encoded_encrypted_key from the JWE.
• No info is required.

4. Decrypt HPKE with recipient context:

• The ciphertext should be the base64Url decoded encoded_ciphertext from the JWE.
• Additional data (aad) should be the UTF8(encoded_protected_header).
• encoded_protected_header is the exact first segment string from the compact JWE (before the first .), and not the decoded JSON.

5. Encode decrypted content into text and parse as JSON. The resulting JSON should contain an unencrypted credential response payload.

Credential response encryption metadata

The issuer's encryption capabilities are declared in the .well-known/openid-credential-issuer endpoint metadata. This allows wallet applications to discover the issuer's encryption support and requirements.

The credential_response_encryption object declares the issuer's ability to encrypt credential responses:

{
  "credential_response_encryption": {
    "alg_values_supported": ["HPKE-7"],
    "enc_values_supported": ["A256GCM"],
    "encryption_required": false
  }
}

Security considerations

When implementing End-to-End Encryption for credential issuance, consider the following security aspects:

• Key Management: Wallet instances must securely generate and manage their encryption keys. These keys should be protected at the device level and never shared with backend servers.
• Policy Enforcement: Encryption policies should be set based on the wallet application's architecture and trust requirements. Wallets that use proxy servers for credential delivery are prime candidates for required encryption policies.
• Encryption Algorithm: MATTR VII currently supports the HPKE-7 JWE algorithm.
  • This algorithm provides integrated encryption with HPKE using:
    • DHKEM (P-256, HKDF-SHA256) as the Key Encapsulation Mechanism (KEM)
    • HKDF-SHA256 as the Key Derivation Function (KDF)
    • AES-256-GCM as the Authenticated Encryption with Associated Data (AEAD)
  • This combination offers modern, secure cryptographic protection.
  • More algorithms will be supported in future releases.
• Wallet Identification: Only identified and approved wallet clients can participate in encrypted issuance flows. Ensure wallet clients are properly registered and configured with the appropriate policies.

Refer to the OID4VCI security considerations for more details.