DocsmDocsChain of trust

Chain of trust

mDocs are verified based on a chain of trust model. In this model, each mDoc is linked to its issuer via a series of certificates, all of which must be validated for the mDoc to be verified.

Chains of trust comprise three parts:

  • Root certificate: This digital certificate belongs to the issuing 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.
  • 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.
  • End-entity: This is the final object that is being issued to holders and sent to verifiers when required. It is signed by is signed by the leaf/end-entity certificate (the last certificate in the chain of certificates).

This model offers the following advantages:

  • Scalability: It allows trust to be extended from a trusted authority down to other entities or components. For example, a root certificate authority (CA) can delegate trust to intermediate CAs, which can further delegate trust to end-user certificates. This makes it easier to manage trust across a large network or ecosystem of trust relationships.
  • Security: It implements multiple layers of security, with each layer depending on the security of the previous one. This approach can deter attackers and provide more opportunities to detect and mitigate breaches. If one component fails or is compromised, the impact can be isolated, thereby minimizing the impact and preventing further spread of the breach.
  • Transparency and auditability: Every step in the chain is typically documented and can be audited, which makes it easier to track where trust was delegated and to ensure that trust relationships have been correctly established and maintained. This transparency is crucial for compliance and security audits.
  • Interoperability: The chain of trust is a well-understood and widely adopted model in various security standards, such as SSL/TLS for web security, PKI (Public Key Infrastructure) for digital certificates, and blockchain technologies. This makes it easier to integrate with other systems and ensures compatibility across different platforms.

Overall, the chain of trust model provides a robust, scalable, and manageable way to establish and maintain trust across various components of a digital ecosystem, making it a cornerstone of modern security architectures.

mDocs chain of trust

The following diagram depicts how MATTR’s mDocs implement the chain of trust model:

Chain of trust

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 via an API request. This endpoint is publicly available by design, and can also be obtained by querying the tenant’s /.well-known/openid-credential-issuer endpoint and inspecting the mdoc_iacas_uri property in the response.

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 sign an mDoc, a valid and active DSC must be used. The DSC is included in the signed mDoc, so a relying party only needs to retrieve the IACA to verify an mDoc. Refer to Certificate selection for signing mDocs below to learn more about how MATTR VII automatically manages DSC generation and selection when signing mDocs.

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.

Currently our APIs for both IACAs and DSCs only support the ECDSA with P-256 (ES256) algorithm. Contact us if you want to better understand the rationale for this choice.

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:

Certificate validity timeline

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 for signing mDocs

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:

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 multiple IACAs meet these requirements, the earliest-created one will be used.

If no IACAs meet these requirements, issuance will fail.

DSC selection

Once an IACA is selected, MATTR VII will review all DSCs signed by the selected IACA and attempt to select a DSC that is:

  • Active.

  • 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, MATTR VII automatically creates a suitable DSC that is:

  • Valid from time of creation.

  • Valid until the later of the following:

    • 30 days from the DSC creation date.
    • 10 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).

IACA rotation

To support IACA rotation, a single MATTR VII tenant can manage multiple IACAs. This approach allows issuers to distribute new IACAs in advance, ensuring seamless continuity of issuance and verification workflows.

The process involves creating an inactive IACA, which is not used by MATTR VII to sign mDocs. However, this inactive IACA can be shared with relying parties ahead of its activation. When ready, the issuer can activate the new IACA and then deactivate the old one. After this switch, new mDocs will be signed using the new IACA, and relying parties will be able to verify them immediately, as the IACA was pre-distributed to them.

IACA rotation should be performed as follows:

  1. Identify that existing active IACA (IACA #1) must be rotated as it is about to expire.
  2. Create IACA #2 as an inactive IACA.
  3. Distribute IACA #2 to all relying parties.

Step #3 must be performed out-of-band. Creating a new IACA on MATTR VII doesn’t update any existing VICALs or trusted issuers list which include this IACA.

  1. Set IACA #2 to active.
  2. Set IACA #1 to inactive.
⚠️

MATTR VII enables having two active IACAs simultaneously to support IACA rotation. However, it is strongly recommended to avoid having more than one active IACA beyond the minimum required time to perform the rotation. That is because having multiple IACAs active might lead to unexpected behaviour when signing mDocs.

Additional resources

Guides

API Reference

MATTR Labs tools

Last updated on