How to configure external (unmanaged) DTS certificates

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

Use your preferred cryptographic library or tool to generate a self-signed root certificate (DTS root CA). This certificate will later be used to sign the VICAL Signer Certificates (VSCs). Ensure it meets the requirements specified in ISO/IEC 18013-5:2021 .

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 DTS root CA certificate with MATTR VII

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

POST /v1/ecosystems/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 DTS root CA certificate. The certificate must meet the following requirements:

  • Valid
  • Not expired
  • Compliant with ISO/IEC 18013-5:2021 

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

Create a VICAL Signer

Make a request of the following structure to create a VICAL Signer that references the unmanaged DTS root CA:

POST /v1/ecosystems/certificates/vical-signers

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

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

Generate and sign the VICAL Signer Certificate (VSC)

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

Associate the VSC with the VICAL Signer

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

PUT /v1/ecosystems/certificates/vical-signers/{vicalSignerId}

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

Activate the DTS root CA

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

PUT /v1/ecosystems/certificates/ca/{dtsCaCertificateId}

• dtsCaCertificateId : Replace with the id value obtained when you registered the unmanaged DTS root CA.

{
    "active": true
}

Create a VICAL

Once the DTS root CA and VICAL Signer are activated, they can be used to sign a VICAL. MATTR VII will automatically select a valid and active VICAL Signer when attempting to create a VICAL.

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