Overview

Chain of trust

When holder applications request wallet attestation tokens from their tethered MATTR VII tenant, issuers need a way to confirm the wallet's identity and decide whether to trust these tokens. This is accomplished using a chain of trust, a hierarchy of certificates that proves the wallet's authenticity.

The following diagram depicts how MATTR implements the chain of trust model when signing wallet attestation tokens:

1. Holder root CA certificate: The root of the trust chain. A self-signed X.509 certificate that identifies the holder application operator. It is used to sign wallet attestation signer certificates.
2. Wallet Attestation Signer Certificate (WASC): An end-entity X.509 certificate signed by the Holder root CA. It is used to sign wallet attestation JWTs that are presented to credential issuers as Wallet Attestation proofs during credential claiming flows.
3. Wallet attestation JWT: The end-entity of the chain. A signed JWT presented to the credential issuer that attests the holder application's identity and authenticity.

Managed vs. unmanaged certificates

MATTR VII supports both managed and unmanaged (external) Holder root CA certificates, giving you flexibility in how you manage your certificate infrastructure.

Managed certificates

With managed certificates, MATTR VII generates and manages the Holder root CA certificate and its private key on your behalf. Wallet attestation signers are automatically provisioned on demand when the first wallet attestation request is made, and you do not need to create them explicitly.

This is the simplest approach and is recommended for most use cases.

Unmanaged (external) certificates

With unmanaged certificates, you supply your own externally-managed Holder root CA in PEM format. You are then responsible for:

• Generating and protecting the Holder root CA certificate and its private key.
• Creating wallet attestation signers and using the returned Certificate Signing Request (CSR) to obtain signed certificates from your root CA.
• Uploading the signed certificates to MATTR VII.
• Managing certificate rotation and lifecycle.

This approach gives you full control over the certificate chain but requires more operational overhead. See the external certificates documentation for more details on the unmanaged certificate model.

Certificate limits

• A maximum of three Holder root CA certificates can be created per tenant.
• Only one Holder root CA can be active at a time. Activating a new root automatically deactivates the previously active one.
• A maximum of five wallet attestation signers can be created per Holder root CA certificate.

Certificate requirements

The following lists depict the requirements for certificates used in the holder certificate chain. Some requirements are common across all certificates, while others are specific to the type of certificate (Holder root CA, wallet attestation signer certificate).

• When using managed holder certificates, MATTR VII automatically ensures that all certificates meet these requirements.
• When using unmanaged holder certificates, it is the responsibility of the holder application operator to ensure compliance.

Common certificate requirements

• Certificate format & basic attributes:

  • PEM format must contain a valid X.509 certificate.
  • Version must be v3.
  • Issuer field must be present and valid.
  • Issuer Alternative Name must be present and contain a valid email address or URI.
  • Serial Number:
    • Must be present.
    • Must contain 1-20 digits (Best practice: Use a positive, non-sequential value).

• Subject attributes:

  • Subject field must be present:
    • Country (C): must be present and be a valid ISO 3166-1 alpha-2 code.
    • Common Name (CN): must be present and non-empty.

• Public Key requirements:

  • Subject Public Key must be present.

• Extensions:

  • Certificate must include extensions.
  • Duplicate extensions are not allowed (No more than one extension with the same extnID).
  • Mandatory extensions:
    • Subject Key Identifier: Must be present and non-empty.
    • Key Usage:
      • Must be present.
      • Must match the intended use of the certificate (e.g. Holder root CA, wallet attestation signer).

• Validity period:

  • NotAfter must be after NotBefore.
  • NotAfter cannot be in the past (expired certificates are invalid).
  • Future dated certificates are valid (e.g. notBefore can be in the future).

• Certificate Revocation List (CRL):

  • If a CRL is provided, it must be valid and signed by the Holder root CA.
  • The CRL must be accessible via a valid URI.

Holder root CA specific requirements

• Must include the keyCertSign and cRLSign key usages.
• Basic constraints must be present and CA must be set to TRUE.
• Issuer Alternative Name must be present and contain a valid email address or URI.
• Signature must be self-signed and verifiable.
• Public key must use one of the supported public key algorithms and curves:
  • ECDSA curves: P-256, P-384, P-521, brainpoolP256r1, brainpoolP320r1, brainpoolP384r1, brainpoolP512r1
  • EdDSA key types: Ed25519, Ed448

Wallet attestation signer certificate specific requirements

• Must be signed by a valid Holder root CA.
• Common name must differ from parent/root Holder root CA.
• Issuer field must be present and must match the exact binary value of the Holder root CA certificate subject.
• Must include the digitalSignature key usage exclusively.
• Signature must be verifiable against the Holder root CA.
• Authority Key Identifier must be present and match the Holder root CA's Subject Key Identifier.
• Must not exceed parent Holder root CA's validity period (i.e. notBefore and notAfter must be within the Holder root CA's validity period).
• Public key must match the CSR provided during wallet attestation signer creation.