How to configure unmanaged issuer certificates

mDocs are verified based on a chain of trust model, where each mDoc is linked to its issuer via a series of certificates. MATTR VII supports both managed and unmanaged issuer certificates, allowing issuers to choose how they want to manage their certificate infrastructure.

The following guide describes how to use MATTR VII to configure an issuance solution using unmanaged issuer certificates. When using unmanaged issuer certificates, the issuer is responsible for creating, managing, and uploading the Issuing Authority Certificate Authority (IACA) and Document Signer Certificates (DSCs) to MATTR VII. Refer to external issuer certificates for more information.

Generate a self-signed root certificate (IACA)

Use your preferred cryptographic library or tool to generate a self-signed root certificate (IACA). This certificate will be used to sign the Document Signer Certificates (DSCs) for mDoc issuance. Ensure the IACA meets the requirements specified in ISO/IEC 18013-5:2021 Annex B.1.2 (https://www.iso.org/standard/69084.html ).

When using unmanaged (external) certificates, the issuer assumes complete responsibility for the secure management of the uploaded root certificates and all subordinate certificates. This includes ensuring the protection, proper issuance, and timely revocation of certificates under the uploaded root, as MATTR VII does not manage or monitor these certificates on the issuer’s behalf.

Register the unmanaged IACA with MATTR VII

Make a request of the following structure to create an unmanaged IACA:


POST /v2/credentials/mobile/iacas


{
    "certificatePem": "-----BEGIN CERTIFICATE-----\r\nMIICDjCCAbSgAwIBAgIKdeZsA5NPKimuAzAKBggqhkjOPQQDAjAiMSAwCQYDVQQG\r\nEwJOWjATBgNVBAMTDEV4YW1wbGUgSUFDQTAeFw0yMzA5MTEyMzM0MjJaFw0zMzA5\r\nMDgyMzM0MjJaMCIxIDAJBgNVBAYTAk5aMBMGA1UEAxMMRXhhbXBsZSBJQUNBMFkw\r\nEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEBbK7JKKFMWuu8kHQK2qaML+MQ0Ykk3Qg\r\n/p3TC6lQKvYJozPSpLXbJQIzMPq9u/dG+j4vq1iX/G/jFIwfiEiKEqOB0TCBzjAS\r\nBgNVHRMBAf8ECDAGAQH/AgEAMA4GA1UdDwEB/wQEAwIABjAdBgNVHQ4EFgQU9zTh\r\nKsqFxAgRJDDGW1au+ewJK6owHgYDVR0SBBcwFYYTaHR0cHM6Ly9leGFtcGxlLmNv\r\nbTBpBgNVHR8EYjBgMF6gXKBahlhodHRwczovL2V4YW1wbGUuY29tL3YyL2NyZWRl\r\nbnRpYWxzL21vYmlsZS9pYWNhcy8yZTg5YzE1Ni0zMWQ1LTQ3ODMtYmQ1OS05MDU1\r\nYjVmOGU3ZDIvY3JsMAoGCCqGSM49BAMCA0gAMEUCIQDD+eU8iOsYYC0v41L94fhF\r\nZ0brPo4gx2aRxrhE3NLFpwIgIgHCPBXJ+JICJg3K7dEsr153So4SEZzAA1rRn4eF\r\nvkM=\r\n-----END CERTIFICATE-----\r\n"
}

certificatePem : This required parameter contains the PEM-encoded IACA certificate. The certificate must meet the following requirements:
- Valid
- Not expired
- Compliant with ISO/IEC 18013-5:2021 Annex B.1.2 (https://www.iso.org/standard/69084.html )

The response will include an id property, which is a unique identifier for the unmanaged IACA. This identifier will be used in subsequent operations to reference this unmanaged IACA.

Create a Document Signer

Make a request of the following structure to create a Document Signer that references the unmanaged IACA:


POST /v2/credentials/mobile/document-signers


{
    "iacaId": "080c670a-2e90-4023-b79f-b706e55e9bc6"
}

iacaId : Replace with the id value obtained when you created the unmanaged IACA in the previous step. Attempts to provide a managed IACA identifier for manual Document Signer creation will result in an error.

The response will include two properties which you will use later in this guide:

id : The unique identifier for the Document Signer. This identifier will be used in subsequent operations to reference this Document Signer.
csrPem : The X.509 Certificate Signing Request (CSR) in PEM format. You will use this CSR to generate a valid Document Signer Certificate in the next step.

Generate and sign the Document Signer Certificate (DSC)

Use your preferred cryptographic library or tool to generate and sign a Document Signer Certificate (DSC) using the CSR provided in the response from the previous step. Refer to the certificate requirements section in the external issuer certificates documentation for details on how to structure a valid DSC.

Associate the DSC with the Document Signer

Make a request of the following structure to update the Document Signer to activate and associate it with the generated DSC:


PUT /v2/credentials/mobile/document-signers/{documentSignerId}

documentSignerId : Replace with the id value obtained when you created the Document Signer in the previous step.


{
    "active": true,
    "certificatePem": "-----BEGIN CERTIFICATE-----\r\nMIICbzCCAhSgAwIBAgIKfS7sskyJEh+DOzAKBggqhkjOPQQDAjAiMSAwCQYDVQQG\r\nEwJOWjATBgNVBAMTDEV4YW1wbGUgSUFDQTAeFw0yMzA5MTEyMzM0MjJaFw0yNDA5\r\nMTAyMzM0MjJaMDExLzAJBgNVBAYTAk5aMCIGA1UEAxMbZXhhbXBsZS5jb20gRG9j\r\ndW1lbnQgU2lnbmVyMFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAE7fa+jv9zCtHQ\r\nmKn7o1dS6lBHD5thlhPqjlx7qEfqy8Im9AcQJDal2sr/fUxhHwf/G4ublS7AL04U\r\n73dzr/ozxaOCASEwggEdMAwGA1UdEwEB/wQCMAAwHQYDVR0OBBYEFLdNNPTmPxt0\r\nLqvlZnV/QL86MXOxMB8GA1UdIwQYMBaAFPc04SrKhcQIESQwxltWrvnsCSuqMA4G\r\nA1UdDwEB/wQEAwIAgDAeBgNVHREEFzAVhhNodHRwczovL2V4YW1wbGUuY29tMB4G\r\nA1UdEgQXMBWGE2h0dHBzOi8vZXhhbXBsZS5jb20waQYDVR0fBGIwYDBeoFygWoZY\r\naHR0cHM6Ly9leGFtcGxlLmNvbS92Mi9jcmVkZW50aWFscy9tb2JpbGUvaWFjYXMv\r\nMmU4OWMxNTYtMzFkNS00NzgzLWJkNTktOTA1NWI1ZjhlN2QyL2NybDASBgNVHSUE\r\nCzAJBgcogYxdBQECMAoGCCqGSM49BAMCA0kAMEYCIQCfgn6+QoNfDVelJANl+Jp9\r\ncq7X9paZylfnI6UGr1FM6gIhAIzhiyclDa8+/ZSRfu7KfgGrNRaJ8YQ6vevskJls\r\nIavC\r\n-----END CERTIFICATE-----\r\n"
}

active : This required boolean indicates whether the Document Signer is active or not. Can only be set to true when a certificatePem is provided. Only active Document Signers can be used to sign mDocs.
certificatePem : This required parameter contains the PEM-encoded Document Signer Certificate (DSC) created in the previous step.

Create a Status List Signer

The following steps are only required when implementing mDocs revocation capabilities. If you are not implementing revocation, you can skip to step 9.

Make a request of the following structure to create a Status List Signer that references the unmanaged IACA:


POST /v2/credentials/mobile/status-list-signers


{
    "iacaId": "080c670a-2e90-4023-b79f-b706e55e9bc6"
}

iacaId : Replace with the id value obtained when you created the unmanaged IACA in the previous step. Attempts to provide a managed IACA identifier for manual Status List Signer creation will result in an error.

The response will include two properties which you will use later in this guide:

id : The unique identifier for the Status List Signer. This identifier will be used in subsequent operations to reference this Status List Signer.
csrPem : The X.509 Certificate Signing Request (CSR) in PEM format. You will use this CSR to generate a valid Document Signer Certificate in the next step.

Generate and sign the Status List Signer Certificate (SLSC)

Use your preferred cryptographic library or tool to generate and sign a Status List Signer Certificate (SLSC) using the CSR provided in the response from the previous step. Refer to the certificate requirements section in the external issuer certificates documentation for details on how to structure a valid SLSC.

Associate the SLSC with the Status List Signer

Make a request of the following structure to update the Status List Signer to active and associate it with the Status List Signer:


PUT /v2/credentials/mobile/status-list-signers/{statusListSignerId}

statusListSignerId : Replace with the id value obtained when you created the Status List Signer in the previous step.


{
    "active": true,
    "certificatePem": "-----BEGIN CERTIFICATE-----\r\nMIICbzCCAhSgAwIBAgIKfS7sskyJEh+DOzAKBggqhkjOPQQDAjAiMSAwCQYDVQQG\r\nEwJOWjATBgNVBAMTDEV4YW1wbGUgSUFDQTAeFw0yMzA5MTEyMzM0MjJaFw0yNDA5\r\nMTAyMzM0MjJaMDExLzAJBgNVBAYTAk5aMCIGA1UEAxMbZXhhbXBsZS5jb20gRG9j\r\ndW1lbnQgU2lnbmVyMFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAE7fa+jv9zCtHQ\r\nmKn7o1dS6lBHD5thlhPqjlx7qEfqy8Im9AcQJDal2sr/fUxhHwf/G4ublS7AL04U\r\n73dzr/ozxaOCASEwggEdMAwGA1UdEwEB/wQCMAAwHQYDVR0OBBYEFLdNNPTmPxt0\r\nLqvlZnV/QL86MXOxMB8GA1UdIwQYMBaAFPc04SrKhcQIESQwxltWrvnsCSuqMA4G\r\nA1UdDwEB/wQEAwIAgDAeBgNVHREEFzAVhhNodHRwczovL2V4YW1wbGUuY29tMB4G\r\nA1UdEgQXMBWGE2h0dHBzOi8vZXhhbXBsZS5jb20waQYDVR0fBGIwYDBeoFygWoZY\r\naHR0cHM6Ly9leGFtcGxlLmNvbS92Mi9jcmVkZW50aWFscy9tb2JpbGUvaWFjYXMv\r\nMmU4OWMxNTYtMzFkNS00NzgzLWJkNTktOTA1NWI1ZjhlN2QyL2NybDASBgNVHSUE\r\nCzAJBgcogYxdBQECMAoGCCqGSM49BAMCA0kAMEYCIQCfgn6+QoNfDVelJANl+Jp9\r\ncq7X9paZylfnI6UGr1FM6gIhAIzhiyclDa8+/ZSRfu7KfgGrNRaJ8YQ6vevskJls\r\nIavC\r\n-----END CERTIFICATE-----\r\n"
}

active : This required boolean indicates whether the Status List Signer is active or not. Can only be set to true when a certificatePem is provided. Only active Status List Signers can be used to sign mDocs.
certificatePem : This required parameter contains the PEM-encoded Status List Signer Certificate (SLSC) created in the previous step.

Activate the IACA

Make a request of the following structure to update the unmanaged IACA and activate it:


PUT /v2/credentials/mobile/iacas/{iacaId}

iacaId : Replace with the id value obtained when you registered the unmanaged IACA.


{
    "active": true
}

Credential issuance

Signing the mDoc

Once the Document Signer and IACA are activated, they can be used to sign mDocs. MATTR VII will automatically select a valid Document Signer based on the certificate selection logic.

If there is no Document Signer that meets the selection criteria, MATTR VII will return an error stating that no valid Document Signer is available for signing. For example, if you attempt to sign an mDoc with an expiry date later than the notAfter date of all available Document Signers, MATTR VII will not find a suitable Document Signer and will return an error.

Unlike the managed IACA flow, MATTR VII does not automatically create new Document Signers in the unmanaged flow, and the issuer is responsible for manually creating and uploading them as needed.

Signing the Status List Token

If the issued mDoc is configured as revocable, it will be associated with a Status List. MATTR VII will then automatically attempt to sign a Status List Token for that Status List using an appropriate Status List Signer. The Status List Signer is selected according to the following criteria:

The Status List Signer must be active.
The Status List Signer must reference the same IACA as the Document Signer used to sign the mDoc.

If there is no Status List Signer that meets the selection criteria, MATTR VII will return an error stating that no valid Status List Signer is available for signing. For example, if you attempt to sign an mDoc using a Document Signer that was created with an IACA that does not have an active Status List Signer, MATTR VII will not find a suitable Status List Signer and will return an error.

Unlike the managed IACA flow, MATTR VII does not automatically create new Status List Signers in the unmanaged flow, and the issuer is responsible for manually creating and uploading them as needed.