Overview

Chain of trust

When issuers issue mDocs they must ensure that relying parties can verify the authenticity and integrity of these credentials. This is accomplished using a chain of trust, a hierarchy of certificates that proves the issuer’s authenticity.

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

Issuing Authority Certificate Authority (IACA)

The root certificate, operated by or on behalf of an issuing authority. The IACA is a X.509 certificate used to identify an mDoc issuer and verify the mDocs they issue. An IACA can be valid for up to 20 years, and is used to sign Document Signer Certificates (DSCs), which are then in turn used to sign Mobile Security Objects (MSO) in mDocs. Refer to Certificate selection for signing mDocs below to learn more about how MATTR VII automatically selects a suitable IACA when signing mDocs.

Each IACA includes the following elements:

• Signature: As the IACA is the root certificate, it is self-signed and verified against its own public key also in the certificate.
• Public key: Used to verify the IACA’s certificate signature, as well as the DSC signature. The private key linked to the certificate is stored and managed in the highly secure and reliable Key Management System (KMS).
• Validity information: When the certificate becomes valid or expires, as well as information about how to check its revocation status.

IACAs can be distributed via different mechanisms, for example using a Verified Issuer Certificate Authority List (VICAL).

Alternatively, all active IACAs on a given tenant can be retrieved by:

1. Making a GET request to the issuer's /.well-known/openid-credential-issuer endpoint.
2. Inspecting the mdoc_iacas_uri property in the response and obtaining the IACA distribution URL. It will be structured as follows: https://{tenant-subdomain}/core/v1/openid/iacas.
3. Making a GET request to the IACA distribution URL. This would return a list of all active IACAs for that tenant.

Document Signer Certificate (DSC)

The end-entity certificate. The DSC is a X.509 certificate used to digitally sign Mobile Security Objects (MSOs) in mDocs. The DSC itself must be issued and signed by the root certificate, which is the Issuing Authority Certificate Authority (IACA).

To understand how mDocs are being signed, it is important to differentiate between a Document Signer and the Document Signer Certificate (DSC). The Document Signer is a logical entity that represents the device or application that signs the mDoc. It is responsible for signing the MSO payload contained within the mDoc. The DSC, on the other hand, is the actual digital certificate that authenticates the Document Signer and is used to verify the signature of the MSO

To sign an mDoc, you must use an active Document Signer that is linked to a valid DSC. The DSC is embedded within the signed mDoc, so verifiers only need to obtain the IACA to validate the mDoc. For details on how MATTR VII automatically manages DSC generation and selection during mDoc signing, see Certificate selection for signing mDocs below.

Each DSC includes the following elements:

• Signature: DSCs are signed by the IACA, and this signature is verified against the IACA’s public key.
• Public key: Used to verify the MSO signature.
• Validity information: When the certificate becomes valid or expires, as well as information about how to check its revocation status.

The ISO/IEC 18013:5:2021 standard determines that a chain of certificates that is used to sign an mDL can only include one IACA and one end-entity certificate, which is the DSC. Other mDocs do not have that limitation and can have more than one intermediate certificate, linking the IACA to the end-entity certificate.

Mobile Security Object (MSO)

The end-entity of the chain of trust, which is the issued signed data. mDocs include an IssuerAuth data structure, as defined in the ISO/IEC 18013-5:2021 standard. It contains the MSO payload, which comprises metadata and salted hashed claims.

Each MSO includes the following elements:

• Signature: MSOs are signed by the DSC. Their signature is checked against the DSC public key, and the DSC is validated all the way up to the IACA.
• Public key: Used to verify the signature of the device the mDoc was issued to, enabling device authentication.
• Validity information: When the MSO becomes valid or expires, as well as information about how to check its revocation status.

Certificates Validity

The concept of certificates validity is of paramount importance in the context of mDocs. For an mDoc to be verified, all the certificates within its chain of trust must be valid. If during the verifications process any of the certificates have expired, the mDoc cannot be verified:

Careful analysis must be conducted before determining the certificates life cycle. IACAs are usually created with long expiry dates, some as long as 10-15 years, while DSCs tend to have shorter validity periods. There are a variety of trade offs in making this duration longer or shorter.

Shorter expiration periods enable things like faster key rotation intervals and provide the opportunity to change the cryptographic algorithms being used if required.

On the other hand, short expiration periods come with increased deployment overhead. Whenever a new IACA is issued, the certificate must be distributed to all verifiers that verify mDocs from that issuer.

Understanding the unique needs and requirements of ecosystems is crucial to applying correct certificates validity periods.

Certificate selection

When signing an mDoc and issuing it to a holder, MATTR VII automatically selects IACA and DSC certificates to ensure a valid mDoc is issued. The selection criteria is consistent whether the issuer is using MATTR VII managed or unmanaged (external) certificates.

IACA selection

MATTR VII will first attempt to select an IACA that is:

• Active.

• Valid for the required time period:

  • Credential cannot be valid before the IACA becomes valid.
  • Credential cannot be valid after the IACA expires.

If no IACAs meet these requirements, issuance will fail.

DSC selection

After selecting an IACA, MATTR VII examines all existing Document Signers with DSCs signed by that IACA. It then tries to select a Document Signer that is:

• Active.

• Its DSC is valid for the required time period:

  • Credential cannot be valid before the DSC becomes valid.
  • Credential cannot be valid after the DSC expires.

If multiple DSCs meet these requirements, the most recently created one will be used.

If no existing DSCs meet these requirements and the issuer is using unmanaged (external) issuer certificates, issuance will fail.

If no existing DSCs meet these requirements and the issuer is using managed certificates, MATTR VII will automatically generate a new DSC that meets the following criteria:

• Valid from time of creation.

• Valid until the later of the following:

  • 30 days from the DSC creation date.
  • 30 days from the signed mDoc expiry date.

• Regardless of these validity settings:

  • The DSC cannot be valid after the IACA used to sign it expires.
  • The DSC cannot be valid for more than 10 years (3650 days).
  • The DSC cannot be valid for more than 457 days if the signed mDoc is an mDL (as indicated by the credential configuration type).

• Suitable for signing the requested mDoc type (DSCs generated by MATTR VII can sign any type of mDoc).

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