Attesto.CredentialEncryption (Attesto v2.28.0)

Copy Markdown View Source

OpenID4VCI 1.0 Credential Request and Credential Response encryption (§8.2, §9, §10, §12.2.4).

Pure, conn-free helpers built over Attesto.JWE for:

  • building credential_request_encryption and credential_response_encryption metadata blocks from an issuer Attesto.Keystore,
  • normalizing and validating credential_response_encryption request objects and Deferred Credential Request payloads,
  • decrypting compact application/jwt encrypted credential and deferred credential requests using keys from the configured keystore, and
  • encrypting Credential Response objects as application/jwt compact JWEs.

Summary

Functions

Decrypt an application/jwt compact JWE Credential Request or Deferred Credential Request using a key from keystore, enforce protected-header and size bounds, and strictly decode the JSON request object.

Encrypt an OID4VCI Credential Response map as a compact application/jwt JWE to the wallet's validated response_encryption parameters.

Parse an OID4VCI Deferred Credential Request (§9.1) containing transaction_id and optional credential_response_encryption.

Normalize an optional credential_response_encryption object from an OID4VCI Credential Request or Deferred Credential Request (§8.2, §9.1, §10).

Build the credential_request_encryption metadata map (OID4VCI §12.2.4) from an Attesto.Keystore module providing EC P-256 keys.

Build the credential_response_encryption metadata map (OID4VCI §12.2.4).

JWE key management algorithms supported for OID4VCI credential encryption.

JWE content encryption algorithms supported for OID4VCI credential encryption.

Validate whether jwk is a usable public ECDH-ES P-256 recipient key.

Validate that normalized credential_response_encryption parameters are cryptographically supported (ECDH-ES P-256 public JWK on the curve, A128GCM or A256GCM content encryption, optional outbound-only zip: "DEF").

Types

encryption_error()

@type encryption_error() ::
  :invalid_encryption_parameters | :invalid_credential_request

Functions

decrypt_request(compact, keystore, opts \\ [])

@spec decrypt_request(binary(), module(), keyword()) ::
  {:ok, map()} | {:error, encryption_error()}

Decrypt an application/jwt compact JWE Credential Request or Deferred Credential Request using a key from keystore, enforce protected-header and size bounds, and strictly decode the JSON request object.

encrypt_response(response_map, response_encryption, opts \\ [])

@spec encrypt_response(map(), map(), keyword()) ::
  {:ok, binary()} | {:error, :invalid_encryption_parameters}

Encrypt an OID4VCI Credential Response map as a compact application/jwt JWE to the wallet's validated response_encryption parameters.

parse_deferred_request(request)

@spec parse_deferred_request(map()) ::
  {:ok, %{transaction_id: String.t(), response_encryption: map() | nil}}
  | {:error, :missing_transaction_id | :invalid_credential_response_encryption}

Parse an OID4VCI Deferred Credential Request (§9.1) containing transaction_id and optional credential_response_encryption.

parse_response_encryption(request)

@spec parse_response_encryption(map()) ::
  {:ok, map() | nil} | {:error, :invalid_credential_response_encryption}

Normalize an optional credential_response_encryption object from an OID4VCI Credential Request or Deferred Credential Request (§8.2, §9.1, §10).

Requires jwk (a map containing a non-empty string alg) and a non-empty string enc; accepts an optional non-empty string zip when present so the caller can reject unsupported compression parameters with invalid_encryption_parameters. Rejects top-level alg values that omit or contradict jwk["alg"].

request_metadata(keystore, opts \\ [])

@spec request_metadata(
  module(),
  keyword()
) :: %{required(String.t()) => term()}

Build the credential_request_encryption metadata map (OID4VCI §12.2.4) from an Attesto.Keystore module providing EC P-256 keys.

Every published public JWK carries "alg" => "ECDH-ES", "use" => "enc", and a distinct RFC 7638 "kid". Raises ArgumentError if any keystore PEM cannot be decoded as a private EC P-256 key.

response_metadata(opts \\ [])

@spec response_metadata(keyword()) :: %{required(String.t()) => term()}

Build the credential_response_encryption metadata map (OID4VCI §12.2.4).

supported_algs()

@spec supported_algs() :: [String.t()]

JWE key management algorithms supported for OID4VCI credential encryption.

supported_encs()

@spec supported_encs() :: [String.t()]

JWE content encryption algorithms supported for OID4VCI credential encryption.

valid_recipient_jwk?(key)

@spec valid_recipient_jwk?(term()) :: boolean()

Validate whether jwk is a usable public ECDH-ES P-256 recipient key.

validate_response_encryption(params)

@spec validate_response_encryption(term()) ::
  :ok | {:error, :invalid_encryption_parameters}

Validate that normalized credential_response_encryption parameters are cryptographically supported (ECDH-ES P-256 public JWK on the curve, A128GCM or A256GCM content encryption, optional outbound-only zip: "DEF").