Guida per il toolkit ottimizzato per docker PQC

This guide is for the PQC dockerized toolkit. For instructions on setting up the DigiCert PQC toolkit, see PQC toolkit setup guide.

Introduction

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:

  • Start the Docker container using docker-compose.
  • Enter the running PQC container.
  • Execute the included demo scripts to test example PQC certificates.
  • Generate post-quantum cryptographic keys.
  • Create a complete hybrid certificate chain, including root, intermediate, and server certificates.
  • Test the certificates using OpenSSL's 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.

PQC dockerized toolkit contents

DigiCert PQC dockerized toolkit contains these files:

  • Dockerfile
  • docker-compose.yml
  • Compiled OpenSSL patched with ISARA Catalyst OpenSSL Connector
  • Demo certificates and config files
  • Bash scripts to test certificate generation and functionality

Prerequisites

Before using this guide, make sure these prerequisites are met:

Check your Docker version

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.

Linux/macOS

Open a terminal window and run docker --version and docker-compose --version. This should return a similar output as seen below.

bash 
$ docker --version
Docker version 18.03.0-ce, build 0520e24

$ docker-compose --version
docker-compose version 1.20.1, build 5d8c71b

Windows

Open a Command Prompt or PowerShell window and run docker --version. This should return a similar output as seen below.

powershell 
> docker --version
Docker version 18.03.0-ce, build 0520e24

Download and extract PQC dockerized toolkit

  1. Sign in to your CertCentral account.
  2. In the sidebar menu, click Certificates > Orders.
  3. On the Orders page, locate your Secure Site Pro certificate order and click its order number.
  4. On the certificate's order details page, click PQC toolkit.
  5. On the Post-quantum cryptography (PQC) page, click Download Docker support files and save the zip file.
  6. Locate the saved zip file (DigiCert-PQC.zip) and extract its contents.

Build and run PQC toolkit container

With 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.

bash 
cd [path/to/dir/]digicert-pqc-docker

Next, 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.

bash 
docker-compose build

Now you're ready to start the PQC toolkit container in detached mode.

bash 
docker-compose up -d
Starting digicert-pqc-docker_pqc_1 ... done

Congratulations! The PQC dockerized toolkit container is up and running.

To access the container environment and start experimenting, see Enter the container.

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.

bash 
docker-compose exec pqc /bin/bash

Directory tree

When 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.

Generate demo certificates

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:

  • All files in the /app/digicert-pqc/demo/certs directory are deleted.
  • A complete quantum-safe certificate chain (including root, intermediate, and server certificates) is generated. Files are saved in /app/digicert-pqc/demo/certs.
  • The certificate chain is verified using legacy cryptography.
  • The certificate chain is verified using quantum-safe cryptography.

Before you generate demo certificates, make sure you're in the /app/digicert-pqc/demo directory.

Then, execute the script.

bash 
cd /app/digicert-pqc/demo
./cert_gen_demo.sh

You'll see this output:

bash 
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!!

Start a demo server

To test generated demo certificates, execute the run_server.sh script. This script can be executed in one of two modes: basic or HTTP.

  • For basic mode, omit the optional http argument.
  • For HTTP mode, include the optional 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.

Start a server in basic mode

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.

bash 
./run_server.sh

You'll see this output:

bash 
engine "IQREngine" set.
Using default temp DH parameters
ACCEPT

Now 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.

Start a server in HTTP mode

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.

bash 
./run_server.sh http

You'll see this output:

bash 
engine "IQREngine" set.
Using default temp DH parameters
ACCEPT

The 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.

Connect to a running demo server

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:

Basic mode: Connect using run_client.sh script

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.

bash 
cd [path/to/dir/]digicert-pqc-docker
docker-compose exec pqc /bin/bash

Navigate to the demo directory and execute the run_client.sh script.

bash 
cd /app/digicert-pqc/demo
./run_client.sh

You'll see this output:

bash 
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:

bash 
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 supported

HTTP mode: Connect using cURL

To 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.

bash 
cd [path/to/dir/]digicert-pqc-docker
docker-compose exec pqc /bin/bash

Now, 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.

bash 
curl -k https://digicert.pqc/demo.html

You'll see this output:

bash 
<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:

bash 
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...
[...]
ACCEPT

Congratulations! You've successfully set up and tested your PQC dockerized toolkit environment. Feel free to experiment with creating certificates and establishing quantum-safe connections.

Informazioni

DigiCert is the world's leading provider of scalable TLS/SSL, IoT and PKI solutions for identity and encryption. The most innovative companies, including 89% of the Fortune 500 and 97 of the 100 top global banks, choose DigiCert for its expertise in identity and encryption for web servers and Internet of Things devices. DigiCert supports TLS and other digital certificates for PKI deployments at any scale through its certificate lifecycle management solution, CertCentral®. The company is recognized for its enterprise-grade certificate management platform, fast and knowledgeable customer support, and market-leading security solutions. For the latest DigiCert news and updates, visit digicert.com or follow @digicert.

©2020 DigiCert, Inc. All rights reserved. DigiCert, its logo and CertCentral are registered trademarks of DigiCert, Inc. Norton and the Checkmark Logo are trademarks of NortonLifeLock Inc. used under license. Other names may be trademarks of their respective owners.