Certificates

Paradym enables you to use X.509 certificates to sign OpenID4VC presentation requests, issue mDoc/SD-JWT-VC credentials, and sign credential revocation status lists.

To do so, you can either create a root certificate within Paradym for the specific use case, or create a certificate signing request to request an externally signed certificate.

When you create a root certificate within Paradym, the root certificate is used to automatically generate leaf certificates, which are used for the actual signing of credentials and OpenID4VP presentation requests. When you use an externally signed certificate, you need to first create a certificate signing request, get your certificate signed by an external certificate authority, and then import the resulting certificate into Paradym.

Creating a Root Certificate

When creating a root certificate, you need to provide the following information:

• The type of the root certificate to create. At the moment you can choose to create a verifier root certificate (which will generate a leaf certificate used for OpenID4VP presentation requests), or an issuer root certificate (which will generate a leaf certificate used for signing credentials).
• The type of the Private Key used to sign the root certificate.
• The ISO 3166-1 2-letter country code of the country where the issuer is located, and, optionally, a human-readable common name, identifying the certificate issuer.
• The issuer alternative name, which is the URL that identifies the issuer.

By default, the root certificate has a validity of 5 years. If you need to renew it beforehand because, for example, your details have changed, you can create a new certificate, and activate it. This will automatically deactivate the old one (but not revoke it).

{
  "type": "verifierRoot",
  "keyType": "P-256",
  "countryName": "NL",
  "commonName": "Example Company BV",
  "issuerAlternativeNameUrl": "https://example.com"
}

Creating a Certificate Signing Request

In a lot of cases the authority issuing certificates is external to your issuer or verifier solution, in which case it is not possible to directly generate a certificate that will be trusted by other parties within Paradym.

Paradym supports creating Certificate Signing Requests based on PKCS#10 if you need a certificate to be signed by an external certificate issuer. A certificate signing request can only be created for leaf certificates (the certificate that will be used directly to sign a credential or OpenID4VP presentation request). Certificate Signing Requests are automatically removed, including the associated cryptographic keys, after 30 days if no certificate has been imported yet.

{
  "type": "verifierSignRequest",
  "keyType": "P-256",
  "countryName": "NL",
  "commonName": "Example Company BV"
}

Once the certificate signing request has been created you should share the request with the certificate issuer. The signed certificate can then be imported into Paradym, see Importing an Externally Signed Certificate below.

Importing an Externally Signed Certificate

When the certificate has been signed by the certificate issuer, you can import it into Paradym through the dashboard or API.

Make sure you import the certificate for the correct certificate signing request. The imported certificate must match the certificate signing request (subject, public key, and extensions), and will be rejected otherwise.

{
  "certificate": "-----BEGIN CERTIFICATE-----\nMIIB0zCCAYWgAwIBAgIUcxM9poL1rQ9qE+zKG66d1Ot/sswwBQYDK2VwMD8xCzAJ\nBgNVBAYTAk5MMRgwFgYDVQQKDA9BbmltbyBTb2x1dGlvbnMxFjAUBgNVBAMMDUFu\naW1vIFJvb3QgQ0EwHhcNMjYwMTEwMTYxMzU5WhcNMjcwMTEwMTYxMzU5WjApMRow\nGAYDVQQDExFVdG9waWEgR292ZXJubWVudDELMAkGA1UEBhMCTkwwWTATBgcqhkjO\nPQIBBggqhkjOPQMBBwNCAAT9WNvzCjNN2jMErOQ8SngFl9kOYrF2vGM6wzcjOlm5\nZkmP8hAw1Mq4ufWXLrJJSt6nttLmnjp+fhFtt5PLlWg4o3oweDAdBgNVHQ4EFgQU\niYGgIscPPL8onQf7XSjGoh02JgwwDgYDVR0PAQH/BAQDAgeAMCYGA1UdEQQfMB2C\nGzJlM2FmNDdlMTA3Ni5uZ3Jvay1mcmVlLmFwcDAfBgNVHSMEGDAWgBQZnA7JLD1U\nwdTyQo+7q6q34fq6HzAFBgMrZXADQQDUvLOLNklte8eSVzpd0RsPuAZPAdF1cFc3\ngHH2IjAugRiBnCMZ/iz/wtQRymwa5nmCX/xJF+f/n+C3e3jpNtoI\n-----END CERTIFICATE-----"
}

Activate a Certificate

If you have a certificate of a certain certificate type and key type combination and create a new one, the new one will be “pending activation”. This means that the new certificate won’t be used until it is activated. That happens automatically when the currently active one expires.

However, you can manually activate the new one, which automatically deactivates the old one. This can be useful when you want to update information contained in the certificate, or during renewal, if you have already shared the new certificate with all relevant parties and want to start using the new one immediately.

Revoking a Certificate

Revoking a certificate should be done if the certificate is compromised. This can be easily done via the dashboard or the API. Afterwards, the certificate will be pending revocation. Once the Certificate Revocation List has been updated, the certificate status will change to revoked.

Note that revoking a certificate is an irreversible operation. In addition, if you revoke a root certificate, we will automatically revoke all its children certificates.

Presentation Templates

You can use the certificates to authenticate presentation requests. To do so, you first need to create a certificate, as described above. Then, you need to create a Presentation Template as described in the documentation. In that page, you can choose the authentication method, which, by default, will be did:web. You can also choose to use any of the available X.509 certificates.