Skip to main content

Certificates

Use X.509 certificates to issue and verify.

X.509 certificates are used to bind a public key to an entity through the signature of a trusted Certificate Authority (CA). This lets wallet holders know with whom they interact, and it lets verifiers know that presented credentials are signed by trusted issuers.

Working with certificates​

Check if you can use certificates​

Retrieve the configuration through the API and check two things:

  1. Whether certificates are enabled in your system. The identifier object determines the types of identifier available to you:

"identifier": {
    "CERTIFICATE": {
      "display": "identifier.certificate",
      "enabled": true,
      "order": 1
    },
  },

  1. Whether the credential format you want to work with is compatible with certificates. Formats have three capabilities to tell you which identifier types are compatible:

"format":
    "EXAMPLE_FORMAT": {
      "capabilities": {
        "holderIdentifierTypes": [
          "DID"
        ],
        "issuanceIdentifierTypes": [
          "DID"
          "CERTIFICATE"                     // You can use certificates to issue credentials of this format
        ],
        "verificationIdentifierTypes": [
          "DID"
          "CERTIFICATE"                     // You can use certificates to verify credentials of this format
        ],
      },
      "display": "format.example",
      "type": "EXAMPLE_FORMAT"
    },

Certificate workflow​

You will use the system to create ingredients for your certificate, get a signature from a CA outside of the system, then you will upload the signed certificate as an identifier.

Once the signed certificate is in the system you can use it to issue and verify credentials.

  • Issuance: when you create the credential, use the certificate's UUID as the issuer
  • Verification: when you create the proof request, use the certificate's UUID as the verifier

Create a certificate​

  1. Create a key pair

  2. Create a Certificate Signing Request (CSR)

  3. Get it signed

  4. Upload it

Create a key pair​

Generate an ECDSA or EDDSA key pair.

Related guide: Create a key pair

Create a CSR​

CSR operations

Core API | Desk API

If you plan on issuing ISO mDL (DocType: org.iso.18013.5.1.mDL), set the profile to MDL to add the necessary extensions to the CSR. Otherwise, set to GENERIC.

Get it signed​

You must submit your CSR to a Certificate Authority (CA) that offers SHA256 signatures. When your request is completed, download the signed certificate in PEM format.

Upload it​

Identifier operations

Core API | Desk API

To add your certificate to the system, create a new identifier. Put your certificate in chain and reference the key ID you used to create the CSR. If your certificate has no common name you must provide a name for the certificate during identifier creation.

You must put the leaf certificate in chain, but you can also include more certificates going up the chain if you wish. chain should look like this:

"-----BEGIN CERTIFICATE-----
MIIDo.....
-----END CERTIFICATE-----
-----BEGIN CERTIFICATE-----
MIIC6j....
-----END CERTIFICATE-----
"

When you create the identifer the system checks that it's a valid-now certificate, that your referenced key matches the one used in the certificate, and that the chain is valid, if one is provided.

Certificate status​

Identifier detail

Core API | Desk API

Retrieve the identifier detail and check the state field for certificate status: ACTIVE or DEACTIVATED. You can also run a task using the Core API with the following request body to update certificate status:

{
  "name": "CERTIFICATE_CHECK"
}