Skip to Content
DocsCredential verificationEstablishing trust

Establishing trust with verifiers

Chain of trust

When verifiers request digital credentials, holders need a way to confirm the verifier’s identity and decide whether to trust them with their information. This trust is established using a chain of trust—a hierarchy of certificates that proves the verifier’s authenticity.

Certificate chains of trust comprise three parts:

  • Root certificate: This digital certificate belongs to the Certificate Authority (CA), and as its name implies, is at the root of the trust chain. Any certificate along the chain of trust must be linked to the root certificate. In the context of establishing trust with a verifier this would be the Verifier root CA certificate.
  • Intermediate certificate: This digital certificate is linked to the root certificate and acts as an intermediary between the root certificate and the end-entity, or between other intermediate certificates. The final certificate in the chain of certificates is referred to as a leaf certificate or an end-entity certificate, and is being used to sign the end-entity. When signing a verification request, this would be a Verification Request Signer Certificate (VRSC).
  • End-entity: This is the final object that is being signed and is later verified by relying parties. It is signed by the leaf/end-entity certificate (the last certificate in the chain of certificates). In the DTS context, this would be a single Verification request shared with a holder.

The following diagram depicts how MATTR implements the chain of trust model when signing verification requests:

Chain of trust

Internal vs external (unmanaged) certificates

MATTR VII offers a robust out-of-the-box solution for verifier certificate management. This includes generation, storage, and usage of signing certificates, where all the associated private and public keys managed securely within MATTR’s Key Management System (KMS).

However, some verifiers prefer (or are required to) manage their own certificates required for verification workflows. Using external verifier certificates offers flexibility for organizations with specific Public Key Infrastructure (PKI) requirements. It preserves the integrity of the trust chain while giving verifiers full control over their cryptographic materials.

Internal vs external (unmanaged) certificates

The following table depicts the differences between managed and unmanaged certificates in MATTR VII:

Internal (Managed) CertificatesExternal (Unmanaged) Certificates
MATTR VII provisions and manages all required certificatesMATTR VII provides tools to assist verifiers in managing their own certificates
All private keys are managed by MATTR VIIVerifiers manage their root CA certificate private key, while MATTR VII manages Verification Request Signers private keys
MATTR VII automatically generates and signs certificates required for signing verification requestsMATTR VII integrates external certificates provided by the verifier into verification workflows
Certificates are automatically validated and managed by MATTR VIIVerifiers must ensure their certificates meet MATTR’s validation requirements
MATTR VII handles all certificate lifecycle management tasksVerifiers must manage the lifecycle of their own certificates

In both models, MATTR VII must be able to associate and understand:

  • Who is performing the signing: This is the Verification Request Signer, an internal MATTR entity that represents a signer. It contains the signer’s unique identifier and (if managed) the private key in the KMS.
  • What certificate is associated with that signer: This is the Verification Request Signer Certificate (VRSC), which is an X.509 certificate that links the signer’s public key to its identity. In the external (unmanaged) certificate flow, the verifier is responsible for creating and uploading this certificate to MATTR VII, so it can be associated with the corresponding signer entities.

The Verification Request Signer is like a digital “signing machine” within MATTR, whereas The VRSC is the official “license” issued by a trusted authority (e.g., Verifier root CA) stating the signer is valid and authorized.

Whenever a verification request is created and signed, the signing process involves the use of the entire certificate chain, from the root CA down to the specific VRSC used for signing. This ensures that the verification request can be verified against the established chain of trust. MATTR VII will automatically select active and valid certificates from the chain.

  • When using managed verifier certificates, if no valid certificates exist, MATTR VII automatically creates new ones as needed.
  • When using unmanaged verifier certificates, it is the responsibility of the verifier to ensure valid certificates are available before creating the verification request. If no valid certificates exist, the creating a verification request operation will fail.

Enabling external (unmanaged) verifier certificates

The following steps outline how to enable and use external verifier certificates in MATTR VII:

Step-by-step instructions and API requests examples are available in the External Verifier certificates guide.

  1. Verifier root CA certificate generation: The verifier generates a private/public key pair and uses the private key to sign a self-signed root certificate. This is the Verifier root CA.
  2. External Verifier root CA registration: The Verifier uses a MATTR VII endpoint to register the external Verifier root CA by providing it in PEM format, which includes the public key and other necessary information. This certificate is not managed by MATTR VII, meaning MATTR will not store the private key or handle its lifecycle. A Verifier root CA identifier is generated by MATTR VII and is used to reference this external Verifier root CA in subsequent operations.
  3. Verification Request Signer creation: The verifier uses a MATTR VII endpoint to create a Verification Request Signer which references the external Verifier root CA identifier. Attempts to provide a managed Verifier root CA identifier for manual Verification Request Signer creation will result in an error.
  4. Certificate Signing Request (CSR): When a Verification Request Signer is created, MATTR VII generates a new private/public key pair:
    • The private key is stored in the MATTR KMS and used to sign a CSR.
    • The public key is included in the CSR, alongside all necessary information to enable the verifier to issue a valid certificate that meets MATTR’s requirements (subject fields, extensions).
  5. VRSC generation: The verifier uses the CSR to generate and sign a Verification Request Signer Certificate (VRSC) which meets the following requirements:
    • Must include the public key from the CSR.
    • Must be signed by the Verifier root CA’s private key.
    • Must match the structure and values expected by MATTR, as described in the CSR.
  6. Certificate upload: After the VRSC is signed, the verifier uses a MATTR VII endpoint to upload it in PEM format and associate it with the Verification Request Signer.
  7. Certificate validation: MATTR VII will validate the uploaded certificate to ensure it is signed by the expected Verifier root CA, contains the correct public key, and includes the necessary X.509 extensions and usages. See certificate requirements below for more details.
  8. Signer and Verifier root CA activation: Once the certificate is validated, the Verification Request Signer, followed by the registered external Verifier root CA, can be activated, allowing them to be used when signing verification requests. MATTR VII will not select any Verification Request Signers if they reference an inactive external Verifier root CAe.
  9. Signing verification requests: MATTR VII uses the uploaded VRSC and the corresponding private key stored in its KMS to sign verification requests. This process ensures the request is cryptographically secure and can be verified by relying parties.
  10. Verification request signature verification: When a relying party attempts to verify a signed verification request, they will ensure the VRSC is valid, trace it back to the registered root certificate (Verifier root CA) and check each certificate’s signature and validity along the chain of trust.
  11. Certificate lifecycle management: The verifier is responsible for managing the lifecycle of the external certificates, including renewal and revocation. MATTR VII will not automatically handle these tasks for external verifier certificates.

Certificate requirements

The following lists depicts the requirements for external certificates used in MATTR VII. Some of the requirements are common across all certificates, while others are specific to the type of certificate (Verifier root CA, VRSC).

  • When using managed verifier certificates, MATTR VII automatically ensures that all certificates meet these requirements.
  • When using unmanaged verifier certificates, it is the responsibility of the verifier 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:
  • 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. Verifier root CA, VRSC).
  • 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).
    • Must be within allowed limits for certificate type:
      • VRSC: Maximum 1187 days from issuance.
  • Certificate Revocation List (CRL):

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

Verifier 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 Elliptic Curves (EC) as defined in ISO/IEC 18013-5:2021 B.3:
    • P-256
    • P-384
    • P-521
    • brainpoolP256r1
    • brainpoolP320r1
    • brainpoolP384r1
    • brainpoolP512r1

VRSC specific requirements

  • Must be signed by a valid Verifier root CA.
  • Common name must differ from parent/root Verifier root CA.
  • Issuer field must be present and must match the exact binary value of the Verifier root CA certificate subject.
  • Must include the digitalSignature key usage exclusively.
  • Must include the Subject Alternative Name extension with a value that matches the requirement in the CSR.
  • Extended key usage must be present and include the correct OID:
    • 1.0.18013.5.1.6.
  • Signature must be verifiable against the Verifier root CA.
  • Authority Key Identifier must be present and match the Verifier root CA’s Subject Key Identifier.
  • Must not exceed parent Verifier root CA’s validity period (i.e. notBefore and notAfter must be within the Verifier root CA’s validity period).
  • Public key must match the CSR provided during Verification Request Signer creation.

Example certificates

See an example of valid certificates parsed using the MATTR Labs X.509 certificate decoder:

Certificates rotation

To support certificates rotation, a single MATTR VII tenant can manage multiple Verifier root CA certificates. This approach allows issuers to distribute new Verifier root CAs in advance, ensuring seamless continuity of verification workflows.

The process involves creating a new Verifier root CA certificate without activating it, which means it will not be used by MATTR VII to sign new VRSCs. However, this inactive Verifier root CA can be shared with holders ahead of its activation.

When ready, the issuer can activate the new Verifier root CA and then deactivate the old one. After this switch, new VRSCs will be signed using the new Verifier root CA, and holders will be able to verify verification requests signed by these VRSCs immediately, as the Verifier root CA was pre-distributed to them.

Verifier root CA rotation should be performed as follows:

  1. Identify that the current active Verifier root CA (Verifier root CA #1) must be rotated as it is about to expire.
  2. Create a new Verifier root CA #2.
  3. Distribute Verifier root CA #2 to all holders.

Step #3 must be performed out-of-band. Creating a new Verifier root CA on MATTR VII doesn’t update any existing trusted verifiers lists which include this Verifier root CA.

  1. Set Verifier root CA #2 to active.

Additional resources

Guides

API Reference

MATTR Labs tools

Last updated on