This guide is for the PQC dockerized toolkit. For instructions on setting up the DigiCert PQC toolkit, see PQC toolkit setup guide.
DigiCert's post-quantum cryptographic (PQC) dockerized toolkit contains everything needed to quickly set up a docker environment where you can create a hybrid TLS certificate. This hybrid certificate uses a post-quantum cryptographic algorithm paired with a classical cryptographic algorithm. This pairing allows you to test the viability of deploying post-quantum hybrid TLS certificates while also maintaining backwards compatibility.
This guide walks you through using the DigiCert PQC dockerized toolkit to:
docker-compose.s_server and s_client utilities.DigiCert PQC dockerized toolkit is available to download for all Secure Site Pro customers. Learn more about what's included with each Secure Site Pro certificate.
DigiCert PQC dockerized toolkit contains these files:
Before using this guide, make sure these prerequisites are met:
Before downloading the PQC dockerized toolkit, verify that Docker Engine and Docker Compose are installed on your system.
If these commands aren't recognized, Docker is not installed on your system. See Prerequisites for information on installing Docker on your system.
Open a terminal window and run docker --version and docker-compose --version. This should return a similar output as seen below.
$ docker --version
Docker version 18.03.0-ce, build 0520e24
$ docker-compose --version
docker-compose version 1.20.1, build 5d8c71bOpen a Command Prompt or PowerShell window and run docker --version. This should return a similar output as seen below.
> docker --version
Docker version 18.03.0-ce, build 0520e24With the PQC dockerized toolkit downloaded and extracted, you're ready to build the container using docker-compose.
Open a terminal window and navigate to the extracted digicert-pqc-docker directory.
cd [path/to/dir/]digicert-pqc-dockerNext, build the PQC toolkit container. This downloads all image dependencies and configures the container environment.
If this is your first time running the command, you might have to wait for the required Ubuntu image to download from Docker Hub.
docker-compose buildNow you're ready to start the PQC toolkit container in detached mode.
docker-compose up -d
Starting digicert-pqc-docker_pqc_1 ... doneCongratulations! The PQC dockerized toolkit container is up and running.
To access the container environment and start experimenting, see Enter the container.
To experiment with the included demo scripts and modified OpenSSL app, you first need to enter the container environment.
Use docker-compose exec to start a bash session inside the running container.
docker-compose exec pqc /bin/bashWhen you first enter the container, you'll be in the /app directory. This directory is home to the entire PQC toolkit and supplemental resources. The following table describes the important subdirectories and files that are located in the /app directory:
| Directory/file | Description |
|---|---|
| digicert-pqc/ | Primary toolkit directory. |
| certs/ | Directory to store generated certificates. |
| connector/ | ISARA Catalyst OpenSSL Connector resources. |
| demo/ | Demo scripts and resources. |
| certs/ | Directory to store generated demo certificates. |
| configs/ | Contains certificate configuration files that are used when generating demo certificates. |
| demo.html | HTML file that can be served via the run_server.sh script when executed in web server mode. |
| cert_gen_demo.sh |
Generates and tests a complete quantum-safe certificate chain using config files located in /app/digicert-pqc/demo/configs. See Generate demo certificates. |
| run_client.sh |
Connects to a running s_server using OpenSSL's s_client utility to test certificate functionality. See Basic mode: Connect using run_client.sh script. |
| run_server.sh |
Starts a basic web server using OpenSSL's s_server utility and loads the certificates located in /app/digicert-pqc/demo/certs. See Start a demo server. |
| pqpki-openssl-1.0.2r/ | Compiled OpenSSL version 1.0.2r modified using the ISARA OpenSSL Connector patch. |
| resources/ | Supplemental PQC toolkit resource files. |
To customize any of the certificate's field values, modify the certificate configuration files (located in /app/digicert-pqc/demo/configs).
To generate a complete quantum-safe certificate chain, use the cert_gen_demo.sh script (located in /app/digicert-pqc/demo). When executed:
Before you generate demo certificates, make sure you're in the /app/digicert-pqc/demo directory.
Then, execute the script.
cd /app/digicert-pqc/demo
./cert_gen_demo.shYou'll see this output:
engine "IQREngine" set.
XMSS key pair has been generated:
engine "IQREngine" set.
DILITHIUM key pair has been generated:
engine "IQREngine" set.
RAINBOW key pair has been generated:
engine "IQREngine" set.
engine "IQREngine" set.
engine "IQREngine" set.
Generating a EC private key
writing new private key to '/app/digicert-pqc/demo/certs/ecdsa_without_xmss_catalyst_mixed_chain_root_private_key.pem'
-----
Signature ok
subject=/C=US/ST=Utah/L=Lehi/O=DigiCert, Inc./OU=DigiCert PQC/CN=DigiCert PQC Root
Getting Private key
engine "IQREngine" set.
Successfully created XMSS signature
Generating a EC private key
writing new private key to '/app/digicert-pqc/demo/certs/ecdsa_without_dilithium_catalyst_mixed_chain_intermediate_private_key.pem'
-----
engine "IQREngine" set.
Signature ok
subject=/C=US/ST=Utah/L=Lehi/O=DigiCert, Inc./OU=DigiCert PQC/CN=DigiCert PQC Test Intermediate CA
Getting CA Private Key
engine "IQREngine" set.
Successfully created XMSS signature
Generating a EC private key
writing new private key to '/app/digicert-pqc/demo/certs/ecdsa_without_rainbow_catalyst_mixed_chain_private_key.pem'
-----
engine "IQREngine" set.
Signature ok
subject=/C=US/ST=Utah/L=Lehi/O=DigiCert, Inc./OU=DigiCert PQC/CN=digicert.pqc
Getting CA Private Key
engine "IQREngine" set.
engine "IQREngine" set.
/app/digicert-pqc/demo/certs/rainbow_ecdsa_x509_catalyst_mixed_chain_server_certificate.pem: OK
engine "IQREngine" set.
2 : ok : /C=US/ST=Utah/L=Lehi/O=DigiCert, Inc./OU=DigiCert PQC/CN=DigiCert PQC Root
1 : ok : /C=US/ST=Utah/L=Lehi/O=DigiCert, Inc./OU=DigiCert PQC/CN=DigiCert PQC Test Intermediate CA
0 : ok : /C=US/ST=Utah/L=Lehi/O=DigiCert, Inc./OU=DigiCert PQC/CN=digicert.pqc
Success!!To test generated demo certificates, execute the run_server.sh script. This script can be executed in one of two modes: basic or HTTP.
http argument.http argument.| Mode | Command | Description |
|---|---|---|
| basic |
./run_server.sh
|
Starts an OpenSSL s_server that accepts connections using the OpenSSL s_client utility. |
| HTTP |
./run_server.sh http
|
Starts an OpenSSL s_server that accepts HTTPS connections on port 443. |
To stop a running s_server, in the terminal window running the server, press CTRL+C.
Before starting a demo server in basic mode, make sure you're in the /app/digicert-pqc/demo directory and that you've generated the demo certificates.
Then, execute the script.
./run_server.shYou'll see this output:
engine "IQREngine" set.
Using default temp DH parameters
ACCEPTNow the s_server utility is running in basic mode and can accept connections via s_client. To connect to a running demo server, see Basic mode: Connect using run_client.sh script.
Before starting a demo server in HTTP mode, make sure you're in the /app/digicert-pqc/demo directory and that you've generated the demo certificates.
Then, execute the script and include the http argument.
./run_server.sh httpYou'll see this output:
engine "IQREngine" set.
Using default temp DH parameters
ACCEPTThe s_server utility is now running in HTTP mode and can accept connections via HTTPS on port 443. To connect to a running demo server, see Connect using cURL.
After running the run_server.sh script to start a demo server, you're ready to connect to it and test the demo certificate chain.
How you connect to the running demo server depends on the mode used to start the server:
The run_client.sh script uses the OpenSSL s_client utility to connect to a running s_server. Before executing this script, make sure you started an s_server by executing the run_server.sh script in basic mode. See Start a server in basic mode.
With an active s_server running basic mode in one of your terminal windows, open a new terminal window. In the new window, start another bash session with docker-compose exec.
cd [path/to/dir/]digicert-pqc-docker
docker-compose exec pqc /bin/bashNavigate to the demo directory and execute the run_client.sh script.
cd /app/digicert-pqc/demo
./run_client.shYou'll see this output:
engine "IQREngine" set.
CONNECTED(00000003)
depth=1 C = US, ST = Utah, L = Lehi, O = "DigiCert, Inc.", OU = DigiCert PQC, CN = DigiCert PQC Root
verify return:1
depth=0 C = US, ST = Utah, L = Lehi, O = "DigiCert, Inc.", OU = DigiCert PQC, CN = DigiCert PQC Test Intermediate CA
verify return:1
---
Certificate chain
0 s:/C=US/ST=Utah/L=Lehi/O=DigiCert, Inc./OU=DigiCert PQC/CN=DigiCert PQC Test Intermediate CA
i:/C=US/ST=Utah/L=Lehi/O=DigiCert, Inc./OU=DigiCert PQC/CN=DigiCert PQC Root
-----BEGIN CERTIFICATE-----
[...]
-----END CERTIFICATE-----
---
Server certificate
subject=/C=US/ST=Utah/L=Lehi/O=DigiCert, Inc./OU=DigiCert PQC/CN=DigiCert PQC Test Intermediate CA
issuer=/C=US/ST=Utah/L=Lehi/O=DigiCert, Inc./OU=DigiCert PQC/CN=DigiCert PQC Root
---
No client certificate CA names sent
Peer signing digest: SHA512
Server Temp Key: ECDH, P-256, 256 bits
---
SSL handshake has read 9868 bytes and written 2331 bytes
---
New, TLSv1/SSLv3, Cipher is ECDHE-NHDH-DILM-AES256-GCM-SHA384
Server public key is 521 bit
Secure Renegotiation IS supported
Compression: NONE
Expansion: NONE
No ALPN negotiated
SSL-Session:
Protocol : TLSv1.2
Cipher : ECDHE-NHDH-DILM-AES256-GCM-SHA384
Session-ID: {{Session-ID}}
Session-ID-ctx:
Master-Key: {{Master-Key}}
Key-Arg : None
PSK identity: None
PSK identity hint: None
SRP username: None
TLS session ticket lifetime hint: 7200 (seconds)
TLS session ticket:
[...]
Start Time: 1563994600
Timeout : 7200 (sec)
Verify return code: 0 (ok)
---In your other terminal window with the active s_server running, you'll see this output:
read from 0x5581e0750b80 [0x5581e07656f3] (5 bytes => 5 (0x5))
0000 - 16 03 01 00 96 .....
read from 0x5581e0750b80 [0x5581e07656f8] (150 bytes => 150 (0x96))
0000 - 01 00 00 92 03 03 d9 c0-5a 73 35 d0 4e f2 31 f6 ........Zs5.N.1.
[...]
write to 0x5581e0750b80 [0x5581e076e100] (71 bytes => 71 (0x47))
0000 - 16 03 03 00 42 02 00 00-3e 03 03 c2 3b df 2f 01 ....B...>...;./.
[...]
write to 0x5581e0750b80 [0x5581e0769c43] (4953 bytes => 4953 (0x1359))
0000 - 16 03 03 13 54 0b 00 13-50 00 13 4d 00 13 4a 30 ....T...P..M..J0
[...]
write to 0x5581e0750b80 [0x5581e0769c43] (4609 bytes => 4609 (0x1201))
0000 - 16 03 03 11 fc 0c 00 11-f8 03 00 17 41 04 0d 97 ............A...
[...]
write to 0x5581e0750b80 [0x5581e076e100] (9 bytes => 9 (0x9))
0000 - 16 03 03 00 04 0e 00 00-00 .........
read from 0x5581e0750b80 [0x5581e07656f3] (5 bytes => 5 (0x5))
0000 - 16 03 03 08 48 ....H
read from 0x5581e0750b80 [0x5581e07656f8] (2120 bytes => 2120 (0x848))
0000 - 10 00 08 44 41 04 29 0a-07 84 0c f3 a4 e4 3e d1 ...DA.).......>.
[...]
read from 0x5581e0750b80 [0x5581e07656f3] (5 bytes => 5 (0x5))
0000 - 14 03 03 00 01 .....
read from 0x5581e0750b80 [0x5581e07656f8] (1 bytes => 1 (0x1))
0000 - 01 .
read from 0x5581e0750b80 [0x5581e07656f3] (5 bytes => 5 (0x5))
0000 - 16 03 03 00 28 ....(
read from 0x5581e0750b80 [0x5581e07656f8] (40 bytes => 40 (0x28))
0000 - e1 d7 30 8b 12 ef d1 dc-31 90 97 d0 0e 54 9c aa ..0.....1....T..
[...]
write to 0x5581e0750b80 [0x5581e076e100] (175 bytes => 175 (0xAF))
0000 - 16 03 03 00 aa 04 00 00-a6 00 00 1c 20 00 a0 02 ............ ...
[...]
write to 0x5581e0750b80 [0x5581e076e100] (6 bytes => 6 (0x6))
0000 - 14 03 03 00 01 01 ......
write to 0x5581e0750b80 [0x5581e076e100] (45 bytes => 45 (0x2D))
0000 - 16 03 03 00 28 d0 99 97-94 6d a1 5c f8 b0 c0 65 ....(....m.\...e
[...]
-----BEGIN SSL SESSION PARAMETERS-----
[...]
-----END SSL SESSION PARAMETERS-----
Shared ciphers:ECDHE-NHDH-DILM-AES256-GCM-SHA384:ECDHE-NHDH-SIDH-DILM-AES256-GCM-SHA384
Signature Algorithms: RSA+SHA512:DSA+SHA512:ECDSA+SHA512:RSA+SHA384:DSA+SHA384:ECDSA+SHA384:RSA+SHA256:DSA+SHA256:ECDSA+SHA256:RSA+SHA224:DSA+SHA224:ECDSA+SHA224:RSA+SHA1:DSA+SHA1:ECDSA+SHA1:HSS+SHA512:XMSS+SHA512:XMSSmt+SHA512:DILITHIUM+SHA512:DILITHIUM+SHA512:0xE0+SHA512
Shared Signature Algorithms: RSA+SHA512:DSA+SHA512:ECDSA+SHA512:RSA+SHA384:DSA+SHA384:ECDSA+SHA384:RSA+SHA256:DSA+SHA256:ECDSA+SHA256:RSA+SHA224:DSA+SHA224:ECDSA+SHA224:RSA+SHA1:DSA+SHA1:ECDSA+SHA1:HSS+SHA512:DILITHIUM+SHA512:DILITHIUM+SHA512
Supported Elliptic Curve Point Formats: uncompressed:ansiX962_compressed_prime:ansiX962_compressed_char2
Supported Elliptic Curves: P-256:P-521:brainpoolP512r1:brainpoolP384r1:P-384:brainpoolP256r1:secp256k1:B-571:K-571:K-409:B-409:K-283:B-283:0xFE01
Shared Elliptic curves: P-256:P-521:brainpoolP512r1:brainpoolP384r1:P-384:brainpoolP256r1:secp256k1:B-571:K-571:K-409:B-409:K-283:B-283:UNDEF
CIPHER is ECDHE-NHDH-DILM-AES256-GCM-SHA384
Secure Renegotiation IS supportedTo use cURL to connect to a running s_server, make sure you started an s_server in HTTP mode. See Start a server in HTTP mode.
With an active demo server running in HTTP mode in one of your terminal windows, you first need to open a new terminal window. In the new window, start another bash session with docker-compose exec.
cd [path/to/dir/]digicert-pqc-docker
docker-compose exec pqc /bin/bashNow, connect to the running server using cURL. The demo certificates you generated are self-signed and will raise an untrusted certificate warning. To ignore these warnings, you must include the -k switch.
curl -k https://digicert.pqc/demo.htmlYou'll see this output:
<html>
<head></head>
<body>
<h1>Hello world! PQC FUTURE IS HERE!</h1>
</body>
</html>In your other terminal window with the active s_server running, you'll see this output:
read from 0x556d44ced1e0 [0x556d44cf61a3] (5 bytes => 5 (0x5))
0000 - 16 03 01 02 00 .....
read from 0x556d44ced1e0 [0x556d44cf61a8] (512 bytes => 512 (0x200))
0000 - 01 00 01 fc 03 03 a3 d2-a7 5e 12 44 88 93 78 fd .........^.D..x.
[...]
write to 0x556d44ced1e0 [0x556d44d05120] (94 bytes => 94 (0x5E))
0000 - 16 03 03 00 59 02 00 00-55 03 03 36 a7 a4 2d 57 ....Y...U..6..-W
[...]
write to 0x556d44ced1e0 [0x556d44cffc53] (4954 bytes => 4954 (0x135A))
0000 - 16 03 03 13 55 0b 00 13-51 00 13 4e 00 13 4b 30 ....U...Q..N..K0
[...]
write to 0x556d44ced1e0 [0x556d44d05120] (220 bytes => 220 (0xDC))
0000 - 16 03 03 00 d7 0c 00 00-d3 03 00 17 41 04 5a 06 ............A.Z.
[...]
write to 0x556d44ced1e0 [0x556d44d05120] (9 bytes => 9 (0x9))
0000 - 16 03 03 00 04 0e 00 00-00 .........
read from 0x556d44ced1e0 [0x556d44cf61a3] (5 bytes => 5 (0x5))
0000 - 16 03 03 00 46 ....F
read from 0x556d44ced1e0 [0x556d44cf61a8] (70 bytes => 70 (0x46))
0000 - 10 00 00 42 41 04 c3 ce-7a a8 53 76 28 fc 55 c5 ...BA...z.Sv(.U.
[...]
0040 - 6b c7 1a 5e f5 0e k..^..
read from 0x556d44ced1e0 [0x556d44cf61a3] (5 bytes => 5 (0x5))
0000 - 14 03 03 00 01 .....
read from 0x556d44ced1e0 [0x556d44cf61a8] (1 bytes => 1 (0x1))
0000 - 01 .
read from 0x556d44ced1e0 [0x556d44cf61a3] (5 bytes => 5 (0x5))
0000 - 16 03 03 00 28 ....(
read from 0x556d44ced1e0 [0x556d44cf61a8] (40 bytes => 40 (0x28))
0000 - 77 07 27 75 71 54 a9 bc-89 2f 69 df 45 6a 6c d8 w.'uqT.../i.Ejl.
[...]
write to 0x556d44ced1e0 [0x556d44d05120] (6 bytes => 6 (0x6))
0000 - 14 03 03 00 01 01 ......
write to 0x556d44ced1e0 [0x556d44d05120] (45 bytes => 45 (0x2D))
0000 - 16 03 03 00 28 78 f8 92-c1 cd d0 73 6b 72 6e 4c ....(x.....skrnL
[...]
read from 0x556d44ced1e0 [0x556d44cf61a3] (5 bytes => 5 (0x5))
0000 - 17 03 03 00 6d ....m
read from 0x556d44ced1e0 [0x556d44cf61a8] (109 bytes => 109 (0x6D))
0000 - 77 07 27 75 71 54 a9 bd-0c 8f e3 9c f3 90 35 a1 w.'uqT........5.
[...]
FILE:demo.html
write to 0x556d44ced1e0 [0x556d44cffc53] (117 bytes => 117 (0x75))
0000 - 17 03 03 00 70 78 f8 92-c1 cd d0 73 6c 14 de 14 ....px.....sl...
[...]
ACCEPTCongratulations! You've successfully set up and tested your PQC dockerized toolkit environment. Feel free to experiment with creating certificates and establishing quantum-safe connections.