External issuer certificates

Overview

MATTR VII offers a robust out-of-the-box solution for issuer 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 issuers prefer (or are required to) manage their own certificates required for credential issuance and management workflows:

• Issuing Authority Certificates (IACAs): The root certificate that identifies the issuer and is used to sign Document Signer Certificates (DSCs) and Status List Signer Certificates (SLSCs).
• Document Signer Certificates (DSCs): Used to sign individual mDocs.
• Status List Signer Certificates (SLSCs): Used to sign status list tokens which indicate the revocation status of mDocs.

MATTR VII supports this external certificate flow while still enforcing the same chain-of-trust validation and signing mechanisms.

Using external certificates in MATTR VII offers flexibility for organizations with specific Public Key Infrastructure (PKI) requirements. It preserves the integrity of the mDoc trust chain while giving issuers full control over their cryptographic materials.

Internal vs external issuer certificates

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

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

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

The Document/Status List Signer is like a digital “signing machine” within MATTR, whereas The DSC/SLSC is the official “license” issued by a trusted authority (e.g., IACA) stating the signer is valid and authorized.

Enabling external issuer certificates

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

1. Root IACA certificate generation: The issuer generates a private/public key pair and uses the private key to sign a self-signed root certificate (IACA).
2. Unmanaged IACA registration: The issuer uses a MATTR VII endpoint to register the unmanaged IACA by providing the IACA in PEM format, which includes the public key and other necessary information. This IACA is not managed by MATTR VII, meaning MATTR will not store the private key or handle its lifecycle. An IACA identifier is generated by MATTR VII and is used to reference this unmanaged IACA in subsequent operations.
3. Document/Status List Signer Creation: The issuer uses a MATTR VII endpoint to create a Document/Status List Signer which references the unmanaged IACA identifier. Attempts to provide a managed IACA identifier for manual Document/Status List Signer creation will result in an error. Status List Signers are only required if the issuer intends to implement revocation capabilities for mDocs.
4. Certificate Signing Request (CSR): When a Document/Status List 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 issuer to issue a valid certificate that meets MATTR’s requirements (subject fields, extensions).
5. DSC/SLSC generation: The issuer uses the CSR to generate and sign a DSC/SLSC which meets the following requirements:
   • Must include the public key from the CSR.
   • Must be signed by the IACA’s private key.
   • Must match the structure and values expected by MATTR, as described in the CSR.
6. Certificate upload: After the DSC/SLSC is signed, the issuer uses a MATTR VII endpoint to upload it in PEM format and associate it with the Document Signer.
7. Certificate validation: MATTR VII will validate the uploaded certificate to ensure it is signed by the expected IACA, contains the correct public key, and includes the necessary X.509 extensions and usages. See certificate requirements below for more details.
8. Signer and IACA activation: Once the certificate is validated, the Document/Status List Signers, followed by the registered unmanaged IACA, can be activated, allowing them to be used when signing mDocs and Status List tokens. MATTR VII will not select any Document/Status List signers if their referenced IACA is not active.
9. Credential issuance: The Document/Status List Signer can now be used when signing mDocs:
   • Signing the mDocs: During issuance, MATTR VII uses the uploaded DSC and the corresponding private key stored in its KMS to sign the mDoc. This process ensures the mDoc is signed by the correct Document Signer and maintains the chain of trust.
   • Signing the Status List Tokens: If the issuer has implemented revocation, MATTR VII uses the SLSC to sign a new status list token. This ensures that relying parties can verify the status of mDocs against signed status list tokens. The validity of these tokens is guaranteed by the SLSC, which is signed by the IACA.
10. Credential verification: When a relying party attempts to verify the signed mDoc, they will:
    • Ensure the DSC is valid, and trace the DSC back to the registered root certificate (IACA) and check each certificate’s signature and validity along the chain of trust.
    • If revocation is implemented, they will also verify the status of the mDoc against the signed status list token, which is signed by the SLSC.
11. Certificate lifecycle management: The issuer is responsible for managing the lifecycle of the external certificates, including renewal and revocation. MATTR VII will not automatically handle these tasks for unmanaged IACAs.

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 (IACA, DSC, SLSC).

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.
    • If State or Province (ST) is present, it must be a valid ISO 3166-2 code  and match the Country (C).

• 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. IACA, DSC, SLSC).

• 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:
    • IACA: Maximum 20 years from issuance.
    • DSC/SLSC: Maximum 10 years from issuance.

• Certificate Revocation List (CRL):

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

IACA 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.
• Status List Distribution URI must be valid, if present:
  • OID: 1.3.6.1.4.1.61546.100
  • Value: Must point to a valid location where the Status List can be retrieved (e.g. https://{tenant-subdomain}/v2/credentials/mobile/status-lists/distribution).
• 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

DSC/SLSC specific requirements

• Must be signed by a valid IACA.
• Common name must differ from parent/root IACA.
• Issuer field must be present and must match the exact binary value of the IACA certificate subject.
• Must include the digitalSignature key usage exclusively.
• Extended key usage must be present and include the correct OID:
  • For DSCs:
    • 1.0.18013.5.1.2 (required, used for signing mDLs).
    • 1.3.6.1.4.1.61546.0 (optional, used for signing any other mDocs).
  • For SLSCs: 1.3.6.1.4.1.61546.1.
• Signature must be verifiable against the IACA.
• Authority Key Identifier must be present and match the IACA’s Subject Key Identifier.
• Must not exceed parent IACA’s validity period (i.e. notBefore and notAfter must be within the IACA’s validity period).
• Public key must match the CSR provided during Document/Status List Signer creation.

Example certificates

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

• IACA 
• DSC 
• SLSC 

Additional resources

Guides

API Reference