light-mode-image
Learn
Certificates

How to create issuer certificates

Overview

An IACA (Issuing Authority Certificate Authority) is a X.509 based certificate used to identify an mDoc issuer and verify the mDocs they issue.

MATTR VII supports both managed and unmanaged issuer certificates, allowing issuers to choose how they want to manage their certificate infrastructure:

  • Managed IACAs : MATTR VII automatically creates, stores, and manages the lifecycle of the IACA, including the private key, as well as signing and managing any Document Signer Certificates (DSCs) that are required to sign mDocs.
  • Unmanaged (external) IACAs : The customer creates and manages their own IACA, including the private key, and registers it with MATTR VII. They are then responsible for signing and managing any Document Signer Certificates (DSCs) and Status List Signer Certificates (SLSCs) that are required to sign mDocs and Status lists.

Creating an IACA

  1. Log into the MATTR Portal.
  2. In the navigation panel on the left-hand side, expand the Platform Management menu.
  3. Select Certificates.
  4. Select the Create new button.
  5. Use the Type radio button to select IACA - Issuing Authority Certificate Authority.
  6. Use the Management method radio button to select MATTR managed.
  7. Use the Country dropdown list to select an issuing country.
  8. Select the Create button to create the IACA certificate.
    The IACA is created as inactive by default.
  9. Use the Status radio button to select Active.
  10. Select the Update button to activate the IACA certificate.

Create a managed IACA

Make a request of the following structure to create a managed IACA:

POST /v2/credentials/mobile/iacas
{
  "commonName": "Example IACA",
  "country": "US",
  "stateOrProvinceName": "US-AL",
  "notBefore": "2024-09-26",
  "notAfter": "2034-09-26"
}
  • commonName : This optional parameter indicates the common name of the IACA certificate. When specified, the value must be a valid PrintableString and cannot be an empty string. If not provided and a custom domain is configured and verified, the custom domain is used followed by the word IACA. If no custom domain is configured, the tenant subdomain is used instead.
  • country : This optional parameter indicates the issuer country. If not provided, a country is selected based on the region of the tenant subdomain cloud host. When specified, the value must be uppercase and a valid country code as per ISO 3166-1.
  • stateOrProvinceName: This optional parameter indicates the issuer state or province. When specified, the value must be uppercase and a valid country code as per ISO 3166-2.
  • notBefore : This optional parameter is used to set when the IACA becomes valid and can be used to sign mDocs. This can be used alongside the active field to support IACA rotation by creating inactive IACAs and distributing them to relying parties in advance. When not provided, defaults to time of creation.
  • notAfter : This optional parameter is used to set the date and time when the IACA expires. When not provided, defaults to 10 years from notBefore, or from issuance if notBefore is not provided. Maximum value is 20 years from issuance.

Response

{
  "id": "e86dd9bc-1414-4f60-aeb1-9143451424bb",
  "certificatePem": "-----BEGIN CERTIFICATE-----\r\nMIIBwzCCAWigAwIBAgIKRGC+CqoTGJKkkTAKBggqhkjOPQQDAjAgMR4wCQYDVQQG\r\nEwJOWjARBgNVBAMTCk1BVFRSIElBQ0EwHhcNMjMwODA4MDAwOTIxWhcNMzMwODA1\r\nMDAwOTIxWjAgMR4wCQYDVQQGEwJOWjARBgNVBAMTCk1BVFRSIElBQ0EwWTATBgcq\r\nhkjOPQIBBggqhkjOPQMBBwNCAASRu69fzdgM4odkyPtRcZd3eGWCw4BB7StZNGRm\r\nuIlrraUyv9SWPHgUYjYmRB1g7ERzj/pOSAspk71Y+QA+j9nPo4GJMIGGMBIGA1Ud\r\nEwEB/wQIMAYBAf8CAQMwDgYDVR0PAQH/BAQDAgAGMB0GA1UdDgQWBBSONcHGh4If\r\nO1dYorRpsuFrs+f8SDAcBgNVHRIEFTATgRFpbmZvQG1hdHRyLmdsb2JhbDAjBgNV\r\nHR8EHDAaMBiiFoYUaHR0cHM6Ly9tYXR0ci5nbG9iYWwwCgYIKoZIzj0EAwIDSQAw\r\nRgIhAPKJIGDSvp7VxRBLCWWeghqi8UUeO+dZsC49TUZcDMNxAiEAoh+7dT+l+GzX\r\nk0J2SoGmPiagrbAuIYyTHwzZZuYr1W4=\r\n-----END CERTIFICATE-----\r\n",
  "certificateData": {
    "commonName": "Example IACA",
    "country": "US",
    "stateOrProvinceName": "US-AL",
    "notBefore": "2024-09-26T00:09:21.000Z",
    "notAfter": "2034-09-26T00:09:21.000Z"
  },
  "certificateFingerprint": "57b178a6c2b8c1877dba515ad4fd60f9c805efc309287182db7debfe43a22928",
  "publicKeyJwk": {
    "kty": "EC",
    "crv": "P-256",
    "x": "kbuvX83YDOKHZMj7UXGXd3hlgsOAQe0rWTRkZriJa60",
    "y": "pTK_1JY8eBRiNiZEHWDsRHOP-k5ICymTvVj5AD6P2c8"
  },
  "active": false,
  "isManaged": true
}
  • id : Unique identifier created for each IACA. You will use it to activate the IACA in the next step.
  • certificatePEM : Certificate PEM format.
  • certificateData : Key details regarding the created IACA:
    • commonName : IACA's name, as provided in the request.
    • country : IACA’s issuer country, as provided in the request.
    • stateOrProvinceName : IACA’s issuer state/province, as provided in the request.
    • notBefore : Data and time when IACA becomes valid.
    • notAfter : Date and time when IACA expires.
  • certificateFingerprint : Hashed value of the IACA certificate that includes all certificate data and its signature.
  • publicKeyJwk : JWK format of the IACA public key.
  • active: IACA status. IACAs are always created as inactive, meaning they cannot be used to sign mDocs until they are activated. This is useful for IACA rotation, allowing you to create a new IACA in advance and distribute it to relying parties before it becomes active.
  • isManaged : Indicates that this is a managed IACA.

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
}

Once a managed IACA is activated, MATTR VII will automatically use it to sign DSCs required to sign mDocs. Refer to Certificate selection for signing mDocs 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.

When using unmanaged (external) certificates, the issuer assumes full 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

  1. Log into the MATTR Portal.
  2. In the navigation panel on the left-hand side, expand the Platform Management menu.
  3. Select Certificates.
  4. Select the Create new button.
  5. Use the Type radio button to select IACA - Issuing Authority Certificate Authority.
  6. Use the Management method radio button to select Externally managed.
  7. Use the Certificate PEM file field to upload the PEM-encoded IACA certificate you generated in the previous step.
  8. Select the Create button to create the IACA certificate.
    The IACA is created as inactive by default, and new forms are displayed to enable you to create the required child certificates in the next steps.

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:

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

  1. Scroll down to the Child certificates area.
  2. In the Document Signer Certificate section, select the Add new button.
  3. Select the Create button in the pop up window.
    A new Document Signer Certificate (DSC) will be created, and you'll be navigated to its details screen.
  4. In the Download the DSC Certificate Signing Request section, download the DSC CSR file.
    This file contains the PEM-encoded Certificate Signing Request (CSR) that you'll use to generate and sign the DSC in the next step.

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

  1. Return to the Document Signer details screen in the MATTR Portal.
  2. In the Upload signed DSC section, use the Certificate PEM file field to upload the PEM-encoded DSC you created in the previous step.
  3. Use the Status radio button to select Active.
  4. Select the Update button to 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 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.

  1. Return to the IACA certificate detail screen in the MATTR Portal.
  2. Scroll down to the Child certificates area.
  3. In the Status List Signer Certificate section, select the Add new button.
  4. Select the Create button in the pop up window.
    A new Status List Signer Certificate (SLSC) will be created, and you'll be navigated to its details screen.
  5. In the Download the SLSC Certificate Signing Request section, download the SLSC CSR file.
    This file contains the PEM-encoded Certificate Signing Request (CSR) that you'll use to generate and sign the SLSC in the next step.

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

  1. Return to the Status List Signer details screen in the MATTR Portal.
  2. In the Upload signed SLSC section, use the Certificate PEM file field to upload the PEM-encoded SLSC you created in the previous step.
  3. Use the Status radio button to select Active.
  4. Select the Update button to 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

Once you have created and associated the required child certificates (DSC and, if applicable, SLSC), you can activate the unmanaged IACA to make it available for signing mDocs.

  1. Return to the IACA certificate detail screen in the MATTR Portal.
  2. Use the Status radio button to select Active.
  3. Select the Update button to activate the IACA certificate.

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
}

Usage

Signing the mDoc

Once the IACA is activated, it 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 automatically create a suitable one. 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 create a new Document Signer that can accommodate the requested expiry date.

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 automatically create a suitable one. 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 create a new Status List Signer that meets the criteria.

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.

IACA Distribution

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.

How would you rate this page?

Overview

Previous Page

IACA

Next Page

On this page

OverviewCreating an IACAUsageIACA Distribution