Tutorial - SignServer Post-Quantum signing

This tutorial uses SignServer version 6.x or SignServer 7.

Learn how to sign data using SignServer with the NIST candidate algorithm ML-DSA (Dilithium).

The following sections demonstrates how to try out creating post-quantum keys and signatures in SignServer using the CA certificates downloaded in EJBCA by following the tutorial Create a Post-Quantum PKI.

NIST has published three post-quantum cryptography standards from the competition it held to develop cryptography able to withstand the threat of quantum computers breaking current standards. You can begin testing the candidate algorithms to see how they behave and prepare for the migration. Note however that these candidate implementations are useful for experimentation and testing but not suitable to be used in production.

In this tutorial, you will learn how to:

Create SignServer Signer
Certificate Signing Request (CSR)
Issue signing certificate from Certificate Authority (CA)
Import signing certificate in SignServer
Sign data with SignServer
Verify signature

Prerequisites

This tutorial uses SignServer Community and EJBCA Community docker containers.

Before you begin, you need SignServer running, and EJBCA running with a post-quantum PKI setup.

To learn how to get set up post-quantum PKI with EJBCA Community as a Docker container, you can follow the tutorial Create a Post-Quantum PKI.
To learn how to get started with SignServer Community as a Docker container, you can follow the tutorial Start SignServer Container with Client Certificate Authenticated Access.

You also need to have Docker installed. To download and install, refer to the Docker documentation. This tutorial runs the docker commands with sudo.

Step 1 - Create signing key and CSR in SignServer

The following steps describe how to create a signing key that is stored in the SignServer database and create a Certificate Signing Request (CSR) for the signing key.

Create Crypto Token

SignServer workers use a crypto token to interact with the software keystore so start with setting up a worker to hold this crypto token.

In SignServer, add a crypto token for storing the private keys.

Go to the SignServer Administration Web Workers page and click Add to add a new worker.
On the Add Worker / Load Configuration page, choose the method From Template.
In the Load From Template list menu, select the keystore-crypto.properties worker template and click Next.
Update the following in the configuration:
- Change the keystore type "WORKERGENID1.KEYSTORETYPE=PKCS12" to "WORKERGENID1.KEYSTORETYPE=INTERNAL to store the signing keys in the SignServer database.
- Remove the line starting with "WORKERGENID1.KEYSTOREPATH" in order to not provide a path to any existing keystore.
Click Apply to add the crypto token.
To activate the crypto token, select the newly created "CryptoTokenP12" in the Workers list and click Activate.
Specify a new password to create this keystore in the database, and then click Activate.
Make sure to remember this password as it will be used again to re-activate the crypto token.

Generate Signing Key

To generate a signing key for the crypto token:

On the SignServer Workers page, select the CryptoTokenP12 and then click the Crypto Token tab.
On the Crypto Token page, click Generate key.
- For New Key Alias, specify a name for the key such as "CMSSigner".
- For Key Algorithm, select Dilithium.
- For Key Specification, use Dilithium2.
Click Generate and verify that the worker is now in state ACTIVE.

Now that you have created your signing key, you can create your signing worker.

Create Signing Worker

To create the signing worker:

On the SignServer Workers page, click Add.
On the Add Worker / Load Configuration page, choose the method From Template.
In the Load From Template list menu, select the cmssigner.properties worker template and click Next.
Update the following in the configuration:
- Specify that the worker should use the "CMSSigner" key by changing "WORKERGENID1.DEFAULTKEY=00003" to "WORKERGENID1.DEFAULTKEY=CMSSigner"
- Specify to use detached signatures by setting WORKERGENID1.DETACHEDSIGNATURE=TRUE
- Specify the signature algorithm the worker will use to sign data by changing WORKERGENID1.SIGNATUREALGORITHM=Dilithium
Click Apply to load the configuration.

The signing worker is listed as OFFLINE since it needs a certificate. You now have a crypto worker and your key, you will next create a Certificate Signing Request (CSR).

Generate CSR

To create a Certificate Signing Request (CSR) for the signing key, do the following:

Select the CMSSigner in the Workers list, and click Generate CSR.
Update the following:
- For Signature Algorithm, select Dilithium.
- For DN (distinguished name) for the certificate, specify a common name such as "CN=CMSSigner".
Click Generate and then click Download to store the CSR as a PKCS#10 file (CMSSigner-CMSSigner.p10).

Next, use the downloaded signing request to issue a certificate in EJBCA that then can be imported into SignServer.

Step 2 - Issue signing certificate

Once you have downloaded the Certificate Signing Request (CSR), you need to bring the CSR to your Certificate Authority (CA) to issue a signing certificate.

This tutorial uses the EJBCA CA. To learn how to get started with EJBCA, you can follow the tutorial Create a Post-Quantum PKI.

The following sections describe how to create basic profiles in EJBCA and issue a digital signing certificate based on the downloaded CSR.

Create Certificate Profile

Certificate profiles define the constraints of the certificate, for example, what keys it can use, and what the extensions will be.

To create a certificate profile that the certificate will be issued under, follow these steps:

In EJBCA, under CA Functions, click Certificate Profiles.
Click the bottom row of the List of Certificate Profiles, specify the name CMSSigner, and then click Add.
The newly created template is displayed in the list of certificate profiles.
Click Edit for the CMSSigner profile and specify the following:
- For Available Key Algorithms, select Dilithium2.
- For Validity or end date of the certificate, specify 1y for one-year validity.
- For Key Usage, clear Non-repudiation and Key encipherment to only use Digital Signature.
  For Extended Key Usage, clear Use to not use any extended key usage.
Leave the rest of the fields as default and click Save to store the profile.

Create End Entity Profile

To create an end entity profile with information about the holder of the certificate, follow these steps:

In EJBCA, under RA Functions, click End Entity Profiles.
In the Add End Entity Profile field, add a name for the new profile, in this example CMSSigner, and click Add profile.
The newly created profile is displayed in the list of end entity profiles.
Select the CMSSigner profile, and click Edit End Entity Profile.
Update the following to map the end entity profile to the CMSSigner certificate profile:
- Clear End Entity E-Mail.
- For Default Certificate Profile, select CMSSigner.
- For Available Certificate Profiles, select CMSSigner.
- For Default CA, select the PQCSubCA (created following the tutorial Create a Post-Quantum PKI).
- For Available CAs, select the PQCSubCA (created following the tutorial Create a Post-Quantum PKI).
- For Available Tokens, select User Generated.
Click Save to store the updated end entity profile.

Now that you have created the profiles, you can continue and issue the certificate in the next step.

Issue certificate

To issue the certificate using the EJBCA RA UI:

In EJBCA, click RA Web to access the EJBCA RA UI.
Under Request new certificate, select Make New Request.
For Select Request Template Certificate Type, select CMSSigner.
For Key-pair generation, select Provided by user since the key pair was generated in SignServer.
Under Upload CSR, click Browse and select to upload the CSR created earlier (CMSSigner-CMSSigner.p10).
Under Provide request info, verify that the Required Subject DN Attributes is the Common Name specified, in this example CMSSigner.
For Provide User Credentials, specify Username "CMSSigner" to save this in the EJBCA database under the user name CMSSigner.
Click Download PEM full chain to download the certificate chain as a PEM file.

Your certificate is downloaded as a CMSSigner.pem file that you will later upload to SignServer.

Step 3 - Download signing CA certificate chain from CA

To allow you to later verify the signature that you will create, download the CA certificate chain for the signer certificate:

In EJBCA, click RA Web to access the EJBCA RA UI.
For PQCRootCA, click DER in the Certificate column and save the Root CA certificate to a separate directory, for example named trust.
For PQCSubCA, click DER in the Certificate column and save the Sub CA certificate to the same directory as the Root CA certificate.

Step 4 - Activate signing worker in SignServer

Next, go back to SignServer and install the signer certificate issued by the CA to activate the CMSSigner worker.

To activate the signing worker in SignServer, do the following:

Go to the SignServer Administration Web Workers page, select the CMSSigner worker, and click Install Certificates.
Click Browse in the Upload column to select the PEM certificate file (CMSSigner.pem), and then click Add to upload the certificate chain.
Click Install to install the certificate in the worker.
Confirm that the CMSSigner worker is listed as ACTIVE and ready to be used.

Your active CMSSigner worker can now be used to sign data, which you will do in the next step.

Step 5 - Sign file with SignServer

The following example shows how to sign a file and get back the detached signature using the SignServer Public Web. You can test signing using any of the SignServer User Interfaces.

To sign a file with SignServer, follow these steps:

Navigate to the SignServer Public Web (https://localhost:1443/signserver/) and click Client Web to go to the SignServer Client Web.
Under Worker, specify the worker Name used, in this example CMSSigner.
Under Input File, click Browse and select a file to sign. In this example, the previously downloaded file CMSSigner.pem is used as sample data to be signed)
Click Submit and store the resulting downloaded signed file.

The detached signature file from SignServer is saved with the extension .p7s. Next, you can use a SignServer tool to verify the signature.

Step 6 - Verify signature

You can now verify that you trust the signature of the signed data. To verify the signature, you need to provide the signer certificate (CMSSigner.pem) and a certificate chain that you trust (in this example PQCRootCA.pem and PQCSubCA.pem).

The following steps describe how to use the SignServer Tool Post Quantum Signature Verifier App on Keyfactor GitHub to verify the signature.

To verify the signed data using the verifier tool, follow these steps:

Download the JAR file available on Keyfactor GitHub:

CODE

git clone git@github.com:Keyfactor/signserver-tools.git
cd signserver-tools/pq-demo/PQ-Verifier/target

Run the verifier tool and provide the signature .p7s file, the file you submitted to be signed (in this example, CMSSigner.pem), and the path to the trust store folder (created in Step 3 - Download signing CA certificate chain from CA) as input parameters:
CODE
```
java -jar PostQuantum-Verifier-jar-with-dependencies.jar ~/Downloads/demo/CMSSigner.pem.p7s ~/Downloads/demo/CMSSigner.pem ~/Downloads/demo/trust/
```
The following displays an example verification result:
CODE
```
0 [main] DEBUG org.signserver.pq.verifier.VerifierApp  - VerifierApp
Added PQCRootCA.cacert.cer as trust anchor
Added PQCSubCA.cacert.cer as trust anchor
Verifying signer CN=CmsSigner
alg: 1.3.6.1.4.1.2.267.7.4.4
algName: Dilithium2
Verified
Valid trusted signature using 1.3.6.1.4.1.2.267.7.4.4 from CN=CmsSigner
```
- To verify the verification result, you can for example check the following:
  - The output shows that the trust anchors are loaded
  - The output verifies the signer certificate
  - The output shows the Dilithium2 algorithm
  - The output contains Verified which means the signature is verified

Next steps

In this tutorial, you learned how to use SignServer to sign data using the post-quantum signature algorithm ML-DSA (Dilithium)

To find out more about creating quantum-safe keys and signatures in SignServer 7.1.1 using the NIST-approved ML-DSA and SLH-DSA quantum-safe algorithms through Bouncy Castle, see the Post-Quantum Code Signing How-to.

Next, you can also browse our other video tutorials on the Keyfactor Community YouTube channel.