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.
• Optionally, the key backend where the private key is generated and stored. Defaults to software.
• 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",
  "keyBackend": "software",
  "countryName": "NL",
  "commonName": "Example Company BV",
  "issuerAlternativeNameUrl": "https://example.com"
}

Key Backends

The key backend decides where a certificate’s private key is generated and stored:

• software: in software. Always available, and the default.
• gcpKms: in Google Cloud KMS. The private key never leaves Google Cloud.

External backends are available from the Builder tier upwards, once enabled for your deployment. The dashboard only shows the backends you can use, and GET /v1/wallets/{walletId}/key-backends lists them with the key types each can create. Cloud KMS can’t create Ed25519 keys, so certificates on it must use P-256.

The leaf certificate Paradym derives from a root uses the same backend, so credentials and presentation requests are signed there too.

External keys are billed per key for as long as they exist, with an allowance included in your tier. A root certificate on an external backend gives you two keys, since its leaf certificate has its own. See Billing and Usage.

See External Key Backends for how external keys are isolated and cleaned up.

Keys

Paradym tracks every key it creates, including the ones behind signing requests, so you can see which keys exist, where they live and what’s scheduled to happen to them. Find them under Trust -> My Keys in the dashboard, or with GET /v1/wallets/{walletId}/keys. A certificate’s keyId points to its key.

A key has:

• id: how you refer to the key in Paradym.
• backendKeyId: the key’s identifier in its backend, such as a Cloud KMS key version. Only returned on on-premise deployments.
• status: active, pendingDeletion or deleted.
• scheduledDeletionAt and deletedAt: when the key is expected to be, and actually was, destroyed.

To see which backend a key lives on, or what it’s used for, use include:

GET /v1/wallets/{walletId}/keys?include=keyBackend,certificate,certificateSigningRequest

keyBackend is returned in the same shape as GET /v1/wallets/{walletId}/key-backends lists it. An imported certificate reuses its signing request’s key, so both are returned for it.

Filter with ?filter[status]= (active, pendingDeletion, deleted) and ?filter[keyBackend.type]= (software, gcpKms, openbao).

Key Lifecycle

Once every certificate a key backs is revoked or expired, the key is retired: it stops working immediately, and it’s destroyed after a grace period (30 days by default). Deactivating a certificate doesn’t retire its key, because a deactivated certificate can still revoke the credentials it issued.

Some backends take a while to destroy a key, so it stays pendingDeletion until the backend has actually destroyed it.

Deleting a Key

Paradym never revokes imported certificates (only the issuing CA can), so their keys are kept until the certificate expires. To release a key sooner, delete it:

DELETE /v1/wallets/{walletId}/keys/{keyId}

or use Delete on the key under Trust -> My Keys. The key stops working immediately and is destroyed after the grace period.

The deletion is refused while something still needs the key:

• a certificate that is active, pendingActivation or pendingRevocation
• an active signing request, whose certificate could still be imported

Revoke or deactivate those certificates, and import or delete those signing requests, first. The error lists everything that’s blocking.

Cancelling a Deletion

While a key is pendingDeletion, you can undo the deletion:

POST /v1/wallets/{walletId}/keys/{keyId}/cancel-deletion

or use Cancel deletion in the dashboard. The key works again straight away, on every backend.

You can only cancel when that gives you back a usable key. If the key’s certificate is revoked or expired, or it has neither a certificate nor an active signing request, the key can’t sign anything useful anymore, so cancelling is refused. The dashboard shows Cancel deletion disabled, with the reason. Those are also the keys Paradym deletes automatically, so automatic deletions can’t be cancelled: create a new certificate instead.

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, one month after they are created if no certificate has been imported yet.

Only the signing is external: Paradym generates the key on the key backend you choose with keyBackend, and the imported certificate reuses it. The backend can’t be changed afterwards.

{
  "type": "verifierSignRequest",
  "keyType": "P-256",
  "keyBackend": "software",
  "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.

If your certificate authority uses a multi-level PKI hierarchy (i.e. the leaf certificate is not directly signed by the root certificate), you can provide additional intermediate certificates that form a chain. The certificates should be ordered from leaf-adjacent to root-adjacent. If a root certificate is included in the list, it will be ignored.

{
  "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-----",
  "parentCertificates": [
    "-----BEGIN CERTIFICATE-----\n<intermediate-certificate>\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.

A revocation is published on the root certificate’s revocation list, which is signed with the root’s key. Revoking is therefore refused once that key has been deleted, since the revocation could never be published and the certificate would sit pending revocation for good. If the key is still pendingDeletion, cancelling the deletion restores it and the revocation can go ahead. Deleting a leaf certificate’s key does not affect this: the revocation list is signed by the root.

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.