How to configure external (unmanaged) verifier certificates

Generate a self-signed root certificate (Verifier root CA)

Use your preferred cryptographic library or tool to generate a self-signed root certificate (Verifier root CA certificate). This certificate will later be used to sign the Verification Request Signer Certificates (VRSCs). Ensure it meets the requirements specified in the certificate requirements section.

When using unmanaged (external) certificates, the DTS provider 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 external Verifier root CA certificate with MATTR VII

Make a request of the following structure to create an unmanaged Verifier root CA:

POST /v2/presentations/certificates/ca

{
    "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 Verifier root CA certificate. The certificate must meet the following requirements:

  • Valid
  • Not expired
  • Compliant with MATTR VII’s certificate requirements.

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

Create a Verification Request Signer

Make a request of the following structure to create a Verification Request Signer that references the unmanaged Verifier root CA:

POST /v2/presentations/certificates/verifier-signers

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

• caId : Replace with the id value obtained when you created the unmanaged Verifier root CA in the previous step. Attempts to provide a managed Verifier root CA identifier for manual Verification Request 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 Verification Request Signer. This identifier will be used in subsequent operations to reference this Verification Request Signer.
• csrPem : The X.509 Certificate Signing Request (CSR) in PEM format. You will use this CSR to generate a valid Verification Request Signer Certificate (VSC) in the next step.

Generate and sign the Verification Request Signer Certificate (VRSC)

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

Associate the VRSC with the Verification Request Signer

Make a request of the following structure to update the Verification Request Signer to activate and associate it with the generated VRSC:

PUT /v2/presentations/certificates/verifier-signers/{verifierSignerId}

• verifierSignerId : Replace with the id value obtained when you created the Verification Request 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 Verification Request Signer is active or not. Can only be set to true when a certificatePem is provided. Only active Verification Request Signers can be used to sign verification requests.
• certificatePem : This required parameter contains the PEM-encoded VRSC created in the previous step.

Activate the Verifier root CA

Make a request of the following structure to update the unmanaged Verifier root CA and activate it:

PUT /v2/presentations/certificates/ca/{certificateId}

• certificateId : Replace with the id value obtained when you registered the unmanaged Verifier root CA.

{
    "active": true
}

Create a Verification Request

Once the Verifier root CA and Verification Request Signer are activated, they can be used to sign verification requests. MATTR VII will automatically select a valid and active Verification Request Signer when attempting to create a remote verification request.

If there is no valid and active Verification Request Signer, MATTR VII will return an error stating that no valid Verification Request Signer is available for signing. Unlike the managed flow, MATTR VII does not automatically create new Verification Request Signers in the unmanaged flow, and the verifier is responsible for manually creating and uploading them as needed.