Skip to main content

Generate certificate thumbprints

A certificate ‘thumbprint’ (also sometimes known as a ‘fingerprint’) is a unique identifier for a certificate that can be derived from the certificate itself. The DCS uses thumbprints to identify which keys and certificates are being used when handling messages.

The thumbprint format is a Base64url encoded SHA256 hash of the certificate.

You will need to include a certificate thumbprint in the JSON Web Signature (JWS) and JSON Web Encryption (JWE) objects you build when you sign and encrypt a Document Checking Service (DCS) payload. You may also want to generate thumbprints for DCS signing certificates if you enable dual running of the DCS signing certificates.

The library you use to build JWS and JWE objects may be able to create thumbprints for you.

If you need to create the thumbprints manually yourself, you will need to:

  1. Check your certificate is in binary DER format.
  2. Hash the binary representation of the certificate.
  3. Base64url encode the hash.

Check your certificate is in binary DER format

You will have a certificate in either plain text Privacy Enhanced Mail (PEM) format or binary DER format.

If your certificate is already in binary DER format, you can move on to hash the binary representation of the certificate.

If your certificate is in PEM format, you’ll need to convert it into DER format. To do this, you can:

  • use a language-appropriate x509 library to load the whole certificate and convert it to DER format
  • extract the Base64 representation of your certificate and decode it into a binary representation

Extract the Base64 representation of your certificate

PEM format certificates will look similar to this:

-----BEGIN CERTIFICATE-----
MIIDITCCAgmgAwIBAgIUYrkheDECIIeoWoUM62Wuq0ng7FUwDQYJKoZIhvcNAQEL
BQAwIDELMAkGA1UEBhMCR0IxETAPBgNVBAMMCGRjcyBkb2NzMB4XDTIwMDIyNDEz
NTYwNloXDTIxMDIyMzEzNTYwNlowIDELMAkGA1UEBhMCR0IxETAPBgNVBAMMCGRj
cyBkb2NzMIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA6rhwmV4Eck67
smukeuNxp0DB4S1hDCSWIMhsI3Fc0Hd9UjNJWgVn7TSjv60zS4DM9X09qzoyFa43
jCyhbwr+fxvuL02cX6KYzauN9R0RejLx0eT7o9ov2AYh69OiMPAwrD8nZOpYibAu
csz2q2BQNd/FfUaqj0nYAgj5pwyIf72bUKC/UgJpVDUKiI3+pgiL+FcEJne7vZue
ptWEMDYcU4Gnne9SAm0yKe4pfduYTyEhNh/+A+ymHZk9pR0FdlsaxMU+fVwpXjZc
w3skOw2hgxFeNkkT4a/FHfaxdCmHCL4dQ6iVgajjrd8au8bAc4KjLraMp+9N6VbQ
wed/D97sxwIDAQABo1MwUTAdBgNVHQ4EFgQUmFHWe0ZP8a4PCZqmOmnr6pUNK4gw
HwYDVR0jBBgwFoAUmFHWe0ZP8a4PCZqmOmnr6pUNK4gwDwYDVR0TAQH/BAUwAwEB
/zANBgkqhkiG9w0BAQsFAAOCAQEAkOjU6uRNGdhTroEuVw0unidlj5RT7/x5BxDy
JU39dnStMO8nASBpW5Gm3uZh/z5f9RYhq3/uvJH70NRshKwuVu8xCQe2E83tpl6S
BfUP68ykEqHgA+eNuhZoUpspY+PaQ6SdZbJqaz13mAftfFVIQhYxBO2lWlg/zMUd
kl33AFrd5Mf4E2eRHqngsIrWL6H2SHLJbJ5l3MhqjrdgFktOGXnC57lJifeAtUsS
/5tKej3jNUEi6FCHKUBpBp8hAKH8WOieAdqiheSAYzR8Jq7CMRYQgHRJF/bvPFHr
xHllK2Kqd5dTQQavfdPYdGIm8w8j6ow/LUPvoCLwwDu+wtgb5Q==
-----END CERTIFICATE-----

The certificate may have a large block of text describing its contents before the certificate block. You can ignore this.

In the PEM format, the text between -----BEGIN CERTIFICATE----- and -----END CERTIFICATE----- is the Base64 encoding of the binary DER format.

You must then decode the Base64 string to get the binary DER.

Hash the binary representation of the certificate

Use a library or a command line tool to hash the certificate.

You need to generate the SHA256 hash of your certificate’s binary DER.

You need to make sure the hash is in raw bytes - some tools return a Base64 string or hex string by default.

Base64url encode the hash

Use a library or command line tool to Base64url encode the hash.

  1. Encode the bytes into Base64url.
  2. Remove padding by stripping any = characters.

Base64url uses - and _ in place of + and / characters.

If your library or command line tool cannot encode bytes to Base64url directly, you’ll have to:

  1. Encode the bytes to Base64.
  2. Convert the Base64 string to Base64url in your own code.
This page was last reviewed on 11 November 2020.