Introduction

The ISARA Catalyst™ Connector 2.1 for OpenSSL lets you integrate OpenSSL using the algorithms provided in the ISARA Radiate™ Quantum-Safe Security Solution Suite. ISARA Catalyst Connector gives you the cryptographic building blocks to create applications that will resist attacks by quantum computers.

For more information about ISARA quantum-safe solutions, visit https://www.isara.com.

This User’s Guide assumes that you are already familiar with OpenSSL and have extensive experience using it.

Version 2.1 of the ISARA Catalyst Connector package contains:

  • Documentation and diagrams about the ISARA Catalyst Connector.

  • A set of patch files to be applied to the appropriate version of the OpenSSL source.

  • The ISARA Radiate toolkit library binary.

  • The ISARA Catalyst Connector Engine built using OpenSSL and the ISARA Radiate Quantum Safe Security Solution Suite.

  • The source code for several demo applications that demonstrate how to use the ISARA Catalyst Connector.

  • Scripts that run OpenSSL utility applications and ISARA Catalyst Connector demonstration applications, and their expected output.

The patch files and engine have been tested against this version of OpenSSL:

  • OpenSSL-1.1.1k

The resulting source code was built against version 2.1 of the ISARA Radiate toolkit library included in this package.

The User’s Guide covers the following topics:

Packaging

The ISARA Catalyst Connector package contains the following files and directories:

  • README.html — Information about the ISARA Catalyst Connector package

  • ISARA-Catalyst-Connector-for-OpenSSL-Guide.html — This file.

  • ISARA-Catalyst-Connector-MPKAC-Tutorial.html — Information about how to create and verify ISARA Catalyst certificates.

  • <OPENSSL_VERSION>_ISARA.patch — Patch to apply to OpenSSL where <OPENSSL_VERSION> is the following:

    • OpenSSL-1.1.1k

  • lib/libiqr_toolkit.so — ISARA Radiate toolkit library (on Linux)

  • lib/libiqr_toolkit.dylib — ISARA Radiate toolkit library (on macOS)

  • lib/libiqre_engine.so — ISARA Catalyst Connector Engine Library (on Linux and macOS)

  • lib/libiqr_toolkit.dll — ISARA Radiate toolkit library (on Windows)

  • lib/<OPENSSL_VERSION>/libiqre_engine.dll — ISARA Catalyst Connector engine (on Windows)

  • demos/ — Demo source code showing some of the new features

  • crypto_demo_script.txt — Script used to demonstrate using OpenSSL with our quantum-safe crypto algorithms

  • crypto_demo_script_expected_output.txt — Expected output of the crypto_demo_script.txt

  • crypto_demo_data/ — Configuration and output files for the crypto_demo_script.txt

  • tls12_demo_script.txt — Script used to demonstrate OpenSSL client-server TLS 1.2 secure handshakes and message communications using ISARA quantum-safe cipher suites

  • tls12_demo_script_expected_output.txt — Expected output of the tls12_demo_script.txt

  • dtls12_demo_script.txt — Script used to demonstrate OpenSSL client-server DTLS 1.2 secure handshakes and message communications using ISARA quantum-safe cipher suites

  • dtls12_demo_script_expected_output.txt — Expected output of the dtls12_demo_script.txt

  • tls_demo_data/ — Configuration and output files for the tls12_demo_script.txt, and dtls12_demo_script.txt

Getting Help

The latest version of this User’s Guide and other ISARA Catalyst Security Solution Suite documentation is available on https://www.isara.com. The ISARA Radiate Quantum Safe Toolkit Developer’s Guide provides more insights into the meaning of the parameters and has references to algorithm specifications.

For more details and requirements, refer to the ISARA Radiate Quantum-Safe Toolkit 2.1 Developer’s Guide.

Introduction to ISARA’s Algorithms

The ISARA Catalyst Connector adds the following quantum-safe algorithms to OpenSSL:

  • Diffie-Hellman-Like Key Exchange Schemes

    • Frodo Diffie-Hellman Key Exchange (FRODODH)

    • NewHope Diffie-Hellman Key Exchange (NHDH)

    • Supersingular Isogeny Diffie-Hellman Key Exchange (SIDH)

    • Samwise Key Exchange (SAMWISE)

  • Key Encapsulation Mechanisms

    • Classic McEliece KEM (CMC)

    • Frodo KEM (FRODOKEM)

    • Kyber Lattice-Based KEM (KYBER)

    • NTRU Prime Lattice-Based KEM (NTRUP)

    • SABER KEM (SABER)

    • SIKE KEM (SIKE)

  • Signature Schemes

    • Dilithium Lattice-Based Signature Scheme (DILITHIUM)

    • eXtended Merkle Signature Scheme (XMSS)

    • eXtended Merkle Signature Scheme - Multi-Tree (XMSSMT)

    • Hierarchical Signature Scheme (HSS)

    • Rainbow Multivariate Signature Scheme (RAINBOW)

    • SPHINCS+ Signature Scheme (SPHINCS)

Note
The algorithm names in parentheses above are not the official names. They are the compact names of the algorithms used in the code of the ISARA Catalyst Connector and algorithm specifier in the applications.

Many of the algorithm details are abstracted via the EVP PKEY API. For details, see Using libcrypto APIs For Quantum-Safe Public Key Cryptography.

All the algorithms have new ISARA defined OIDs and associated NIDs. These OIDs will be used in the same way that classical algorithm OIDs are used. For example, they are embedded in the algorithm identifier of SubjectPublicKeyInfo in X.509 certificates.

All of the signature algorithms only support intrinsic signing so for signatureAlgorithm in an X.509 certificate and certificate signing requests, the embeded OID must be the same as the one in the issuer’s SubjectPublicKeyInfo. The parameters field must be absent.

Caveats

  • HSS, XMSS and XMSSMT keys can only produce a specific number of signatures. The total number of signatures available depends on parameter selection.

  • HSS, XMSS and XMSSMT private keys require special care during the signing operation. A new -pkeyopt option called state_filename must be set to a file name. See the Special Note on stateful hash-based signature schemes for more details.

  • We do not support converting a certificate signing request into a self-signed X.509 root certificate where the signing algorithm is HSS, XMSS or XMSSMT because that would use up two OTSs, which is undesirable. Both the x509 and req commands can be used to directly create a root certificate thereby using only one OTS.

  • All our new Diffie-Hellman-Like key exchange schemes must initiate and finish in the same transaction. The operation cannot be restarted from a previously initialized state. This is to enforce ephemeralness.

  • All our new key exchange algorithms require that the participants know their identity (for example, initiator vs. responder, Alice vs. Bob). This is different from Diffie-Hellman requirements.

  • Our new ISARA Catalyst certificates (see Special Note on Catalyst Certificates) will have two private keys associated with each certificate. This is not compatible with the PKCS12_parse() API that will only return a single private key per certificate.

  • Our new signature schemes only support intrinsic signing. Therefore, the use of the -[digest] parameters in some of the OpenSSL applications in combination with our signature schemes can cause errors.

  • Unlike the openssl verify utility, openssl x509AltVerify does not have an equivalent to the -check-ss-sig to trigger verification of the self-signed root certificate. Instead, the openssl x509AltVerify utility verifies the root certificate by default, but this behavior can be turned off using the -skip-trusted flag which will ensure that any certificate in the trusted store is not verified.

  • For TLS connections strict mode is enabled by default. This is required for Catalyst certificate support. Note that the openssl s_client and `openssl s_server`utilities disable strict mode because they are used by the OpenSSL unit tests which expect strict mode to be disabled.

  • By default, OpenSSL’s TLS server implementation sends a NewSessionTicket handshake message. If the client sent a certificate to the server, then the server sends that certificate back to the client as part of this message. However, OpenSSL’s TLS client implementation has arbitrarily set the size limit of this message to 16k. Therefore, you will need to ensure that entity certificates that are generated for client authentication in TLS can fit within this limit along with other data that are sent in this message. See RFC 5077 for more information about this message.

Applying the ISARA Catalyst Connector Patch to OpenSSL

The ISARA Catalyst Connector is supplied as a patch to OpenSSL. This patch can be applied using any commonly available patch utility. It is expected that you are maintaining your own version of OpenSSL with your own customizations to fit into your own system.

The source code for OpenSSL can be found on the OpenSSL.org website: https://www.openssl.org/source/old/

  1. Unpack the OpenSSL source.

  2. Copy the patch from where you unpacked the package into the newly created OpenSSL directory.

  3. In the unpacked directory, apply the patch using the following command: patch -p2 < OpenSSL_<version>_ISARA.patch where <version> is:

    • OpenSSL-1.1.1k

If the patch doesn’t apply cleanly, start over and make sure you’re running the patch command from inside the OpenSSL directory. (For example, the directory for OpenSSL 1.0.2l is named openssl-1.0.2l.) Also ensure that you are using the appropriate patch for your version of OpenSSL.

Build Instructions

After patching the source for OpenSSL, build it.

For Posix systems:

  1. Configure OpenSSL. See the relevant INSTALL file in the OpenSSL directory for more information. For example: ./Configure shared <OPENSSL_CONFIGURATION>

    Note
    You must use shared for dynamic engine support because the engine calls APIs in libcrypto and thus requires the symbols in the shared library for dynamic linking. For Linux, when your applications are executed, they might need the LD_LIBRARY_PATH environment variable set to specify the location of the libcrypto.so, libssl.so, and libiqr_toolkit.so library files. For Darwin, the environment variable is called DYLD_LIBRARY_PATH. See the crypto_demo_script.txt file for an example of how to do this.
  2. Execute make all

  3. Execute make test (This step is optional.)

  4. Build the demo applications. Each .c file in the demos directory is a demo application, except openssl_tls.c. openssl_tls_server_1_2.c, openssl_tls_client_1_2.c, openssl_dtls_server_1_2.c` and openssl_dtls_client_1_2.c share code in openssl_tls.c. OpenSSL libcrypto and libssl libraries built in the previous steps need to be linked in when building the demo applications. Alternatively, we have supplied a Makefile.example file to help you build the demo applications.

  5. Run the ISARA Catalyst Connector crypto demos and the OpenSSL standard utilities as shown in crypto_demo_script.txt and TLS demos as shown in tls12_demo_script.txt and dtls12_demo_script.txt to see if you get similar console output to what is shown in the expected output files and similar output files in the crypto_demo_data and tls_demo_data directories.

Note
You will not get an exact match in output as there is some randomness associated with these algorithms and potential differences across run time environments. Also, the files specify expected output do not contain the output to stderr.

For Windows:

  1. Configure OpenSSL. See the relevant INSTALL file in the OpenSSL directory for more information. For example: perl configure VC-WIN64A

    Note
    Run the following ms/nmake commands from a VC++ x64 environment. This can be done by running VCVARSALL x64 from the command prompt.
  2. Execute nmake

  3. Execute nmake test

  4. Execute nmake install

  5. Build the demo applications. Each .c file in the demos directory is a demo application, except openssl_tls.c. openssl_tls_server_1_2.c, openssl_tls_client_1_2.c, openssl_dtls_server_1_2.c and openssl_dtls_client_1_2.c share code in openssl_tls.c. OpenSSL libcrypto and libssl libraries built in the previous steps need to be linked in when building the demo applications. Alternatively, we have supplied a Makefile.example file to help you build the demo applications. Edit the the file to enable the windows specific LIBS and LDFLAGS variables. Execute cd demos; `nmake -f Makefile.example all

  6. Run the ISARA Catalyst Connector crypto demos and the OpenSSL standard utilities as shown in crypto_demo_script.txt and TLS demos as shown in TLS_demo_script.txt to see if you get similar console output to what is shown in crypto_demos_script_expected_output.txt and TLS_demos_script_expected_output.txt and similar output files in the crypto_demo_data and tls_demo_data directories.

Note
You will not get an exact match in output as there is some randomness associated with these algorithms and potential differences across run time environments. Also, the files specifying expected output do not contain the output to stderr.

Using OpenSSL Utilities For Quantum-Safe Public Key Cryptography

The functionality of the standard utilities from the OpenSSL package has not changed. These utilities are documented on the OpenSSL.org website: https://www.openssl.org/docs/man1.1.1/man1/

Since ISARA’s algorithms are implemented in an engine, use the -engine parameter to specify the path and file name of the ISARA Catalyst Connector engine. This engine can print debug and status information to stderr by defining the following environment variable at runtime:

ISARA_VERBOSE=1

See the crypto_demo_script.txt file for an example of how to do this.

An alternative way to specify the engine is via a .conf configuration file. This is an example of a simple iqre.conf file that specifies the location of the engine:

openssl_conf = openssl_init

[openssl_init]
engines = engine_section

[ engine_section ]
iqre = iqre_section

[ iqre_section ]
engine_id = iqre
dynamic_path = /path/to/libiqre_engine.so
default_algorithms = ALL

To use iqre.conf, define the following environment variable at runtime:

OPENSSL_CONF=/path/to/iqre.conf

For more information on how to write .conf files, please see https://www.openssl.org/docs/man1.1.1/man5/config.html.

The following standard OpenSSL utilities can be used with the indicated algorithms:

Table 1. Supported Application By Algorithms
Algorithm req x509 verify cms genpkey pkey pkeyutl ciphers s_server s_client

FRODODH

NHDH

SAMWISE

SIDH

CMC

FRODOKEM

KYBER

NTRUP

SABER

SIKE

DILITHIUM

HSS

RAINBOW

SPHINCS

XMSS

XMSSMT

Note
If you choose to use genpkey to generate keys of a type that are not supported by the engine, you must not specify the engine on the command line. For example, do not use the -engine <iqre_engine> flags if you are going to generate RSA keys. Doing so results in an error.
Note
The ciphers application lists all supported cipher suites. To try one of the ISARA quantum-safe cipher suites, run the ciphers utiltity with the cipherlist command line option set as QS and a list of ISARA’s new cipher suites will appear. Pick the one you want. When you execute openssl s_client, pass in that cipher suite with the -cipher command line option.
Note
Some algorithms allow you to generate a parameter file by specifying -genparam. None of our quantum safe algorithms support this. Instead, when generating a key, simply use the relevant -pkeyopt options.

Special Note on Ephemeralness

The following algorithms are not compatible with genpkey in order to enforce ephemeralness:

  • FRODODH

  • NHDH

  • SAMWISE

  • SIDH

These algorithms are specifically designed for ephemeral key exchange. They are only used in the openssl s_server, openssl s_client and demo applications that run the TLS protocols. They are also featured in the ciphers application that shows the name of the cipher suites and some demo applications that show how to use them in custom applications.

These are exposed by the Derive/SetPeer EVP PKEY APIs, but pkeyutl cannot be used with these algorithms. A peer key file cannot be properly supplied for the initiator because construction depends on the responder’s data. The responder must have the initiator’s peer key first. The initiator’s peer key does not exist yet; that is why you are running pkeyutl.

The ISARA Catalyst Connector package includes simple demos of how to use these algorithms. See openssl_*_with_asn1.c.

Special Note on Stateful Hash Based Signature Schemes

HSS, XMSS and XMSSMT are all stateful hash based signature schemes and therefore have special files for maintaining the state.

For any applications that perform key generation, you must use one of the following options to specify the state file depending on which application it is:

  • -pkeyopt state_filename:filename.bin

  • -sigopt state_filename:filename.bin

For any appications that perform the signing operation (for example, req, x509, pkeyutl), you will be required to use the following parameters:

  • -keyform ENGINE -key /path/to/key.pem::/path/to/filename.bin

The value of /path/to/filename.bin, also known as the state, must be a valid file name with no whitespace. Never set the file to read-only status on the file system as the state needs to be re-written after each signing operation.

Classic McEliece KEM

If the application has an -algorithm parameter, you can specify Classic McEliece KEM with -algorithm cmc and specify the parameter set p with -pkeyopt parameter_set:p where p can be one of the following:

Table 2. CMC Parameter Sets
p Radiate Variant

ClassicMcEliece_6960119_r2

IQR_CLASSICMCELIECE_6

ClassicMcEliece_8192128_r2

IQR_CLASSICMCELIECE_8

Frodo KEM

If the application has an -algorithm parameter, you can specify Frodo KEM with -algorithm frodokem and specify the parameter set p with -pkeyopt parameter_set:p where p can be one of the following:

Table 3. FRODOKEM Parameter Sets
p Radiate Variant

FrodoKEM_640_AES_r2

IQR_FRODOKEM_640_AES

FrodoKEM_640_SHAKE_r2

IQR_FRODOKEM_640_SHAKE

FrodoKEM_976_AES_r2

IQR_FRODOKEM_976_AES

FrodoKEM_976_SHAKE_r2

IQR_FRODOKEM_976_SHAKE

FrodoKEM_1344_AES_r2

IQR_FRODOKEM_1344_AES

FrodoKEM_1344_SHAKE_r2

IQR_FRODOKEM_1344_SHAKE

Kyber KEM

If the application has an -algorithm parameter, you can specify Kyber with -algorithm kyber and specify the parameter set p with -pkeyopt parameter_set:p where p can be one of the following:

Table 4. KYBER Parameter Sets
p Radiate Variant

Kyber_512_r2

IQR_KYBER_512

Kyber_768_r2

IQR_KYBER_768

Kyber_1024_r2

IQR_KYBER_1024

NTRU Prime KEM

If the application has an -algorithm parameter, you can specify NTRU Prime with -algorithm ntrup and specify the parameter set p with -pkeyopt parameter_set:p where p can be the following:

Table 5. NTRUP Parameter Sets
p Radiate Variant

NTRUPrime_sntrup653_r2

IQR_SNTRUP_653

NTRUPrime_sntrup761_r2

IQR_SNTRUP_761

NTRUPrime_sntrup857_r2

IQR_SNTRUP_857

Saber KEM

If the application has an -algorithm parameter, you can specify SABER with -algorithm saber and specify the parameter set p with -pkeyopt parameter_set:p where p can be the following:

Table 6. SABER Parameter Sets
p Radiate Variant

Saber_LightSaber_r2

IQR_LIGHT_SABER

Saber_Saber_r2

IQR_SABER

Saber_FireSaber_r2

IQR_FIRE_SABER

SIKE KEM

If the application has an -algorithm parameter, you can specify SIKE with -algorithm sike and specify the parameter set p with -pkeyopt parameter_set:p where p can be one of the following:

Table 7. SIKE Parameter Sets
p Radiate Variant

SIKE_p434_r2

IQR_SIKE_P434

SIKE_p503_r2

IQR_SIKE_P503

SIKE_p610_r2

IQR_SIKE_P610

SIKE_p751_r2

IQR_SIKE_P751

Dilithium Signature Scheme

If the application has an -algorithm parameter, you can specify Dilithium with -algorithm dilithium and specify the parameter set p with -pkeyopt parameter_set:p where p can be one of the following:

Table 8. Dilithium Parameter Sets
p Radiate Variant

Dilithium_II_SHAKE_r2

IQR_DILITHIUM_80

Dilithium_III_SHAKE_r2

IQR_DILITHIUM_128

Dilithium_IV_SHAKE_r2

IQR_DILITHIUM_160

eXtended Merkle Signature Scheme

If the application has an -algorithm parameter, you can specify XMSS with -algorithm xmss.

You must use the following options when generating a key pair to specify the variant:

  • -pkeyopt tree_height:h

  • -pkeyopt strategy:s

  • -pkeyopt state_filename:filename.bin

Use one of these values for h:

Table 9. XMSS Tree Height
h

10

16

20

Use one of these values for s:

Table 10. XMSS Strategy
s

cpu_constrained

memory_constrained

full

See the Special Note on Stateful Hash Based Signature Schemes for details about the state_filename option.

See the IETF specification referenced in the ISARA Catalyst Security Solution Suite 2.1 Developer’s Guide for more details about these values.

eXtended Merkle Signature Scheme - Multi-Tree

If the application has an -algorithm parameter, you can specify XMSSMT with -algorithm xmssmt.

You must use the following options when generating a key pair to specify the variant:

  • -pkeyopt tree_height:h

  • -pkeyopt tree_layers:l

  • -pkeyopt strategy:s

  • -pkeyopt state_filename:filename.bin

Use one of these combinations for h and l:

Table 11. XMSSMT Tree Height and Layer Combinations
h l

20

2

20

4

40

2

40

4

40

8

60

3

60

6

60

12

Use one of these values for s:

Table 12. XMSSMT Strategy
s

cpu_constrained

memory_constrained

full

See the Special Note on Stateful Hash Based Signature Schemes for details about the state_filename option.

See the IETF specification referenced in the ISARA Catalyst Security Solution Suite 2.1 Developer’s Guide for more details about these values.

Hierarchical Signature Scheme

If the application has an -algorithm parameter, you can specify HSS with -algorithm hss.

You must use the following options when generating a key pair to specify the variant:

  • -pkeyopt sign_operations:so

  • -pkeyopt optimization:o

  • -pkeyopt strategy:s

  • -pkeyopt state_filename:filename.bin

Use one of these values for so:

Table 13. HSS Sign Operations
so

2E15

2E20

2E30

2E45

2E65

Use one of these values for o:

Table 14. HSS Optimization
o

fast

small

Use one of these values for s:

Table 15. HSS Strategy
s

cpu_constrained

memory_constrained

full

See the Special Note on Stateful Hash Based Signature Schemes for details about the state_filename option.

See the IETF specification referenced in the ISARA Catalyst Security Solution Suite 2.1 Developer’s Guide for more details about these values.

Rainbow Signature Scheme

If the application has an -algorithm parameter, you can specify Rainbow with -algorithm rainbow and specify the parameter set p with -pkeyopt parameter_set:p where p can be one of the following:

Table 16. RAINBOW Parameter Sets
p Radiate Variant

Rainbow_IIIc_std_r2

IQR_RAINBOW_GF256_68_36_36

Rainbow_Vc_std_r2

IQR_RAINBOW_GF256_92_48_48

SPHINCS+ Signature Scheme

If the application has an -algorithm parameter, you can specify SPHINCS+ with -algorithm sphincs and specify the parameter set p with -pkeyopt parameter_set:p where p can be one of the following:

Table 17. SPHINCS Parameter Sets
p Radiate Variant

SPHINCS_SHAKE_256_192s_r2

IQR_SPHINCS_SHAKE_256_192S

SPHINCS_SHAKE_256_192f_r2

IQR_SPHINCS_SHAKE_256_192F

SPHINCS_SHAKE_256_256s_r2

IQR_SPHINCS_SHAKE_256_256S

SPHINCS_SHAKE_256_256f_r2

IQR_SPHINCS_SHAKE_256_256F

SPHINCS_SHA2_256_192s_r2

IQR_SPHINCS_SHA2_256_192S

SPHINCS_SHA2_256_192f_r2

IQR_SPHINCS_SHA2_256_192F

SPHINCS_SHA2_256_256s_r2

IQR_SPHINCS_SHA2_256_256S

SPHINCS_SHA2_256_256f_r2

IQR_SPHINCS_SHA2_256_256F

New AltExtend Applications

The following new applications were created to support Catalyst certificates, Catalyst CSRs, Catalyst CRLs, dual private keys and Catalyst CMS messages.

  • cmsAltExtend

  • cmsAltVerify

  • crlAltExtend

  • crlAltVerify

  • pkcs12AltExtend

  • reqAltExtend

  • x509AltDirectExtend

  • x509AltExtend

  • x509AltVerify

See ISARA Catalyst Connector 2.1 Alt Certificate Tutorial for an in-depth explanation of these applications.

Using libcrypto APIs For Quantum-Safe Public Key Cryptography

All of ISARA’s algorithms are abstracted by the EVP PKEY API layer. Here are the relevant APIs for each of the algorithms:

Table 18. EVP APIs per Algorithm
Algorithm CTX_new_id Keygen Sign Verify SetPeer Derive

FRODODH

NHDH

SAMWISE

SIDH

CMC

FRODOKEM

KYBER

NTRUP

SABER

SIKE

DILITHIUM

HSS

RAINBOW

SPHINCS

XMSS

XMSSMT

Note
These API names have been shortened and simplified. For example, Derive refers to EVP_PKEY_derive_init() and EVP_PKEY_derive().
Note
The EVP_PKEY API in libcrypto does not support the notion of KEMs. That is to say, there are no encapsulate() and decapsulate() methods in the EVP_PKEY API. Therefore, we expose them via the EVP_PKEY_derive_init() / EVP_PKEY_derive_set_peer() / EVP_PKEY_derive() APIs.

Loading the Engine

You must load the ISARA Catalyst Connector engine before using the ISARA Radiate algorithms. The following sample code shows how to load the engine, where the engine parameter is a string that specifies the path to the engine’s file:

  > // SNIPPET_START_1
    ENGINE *setup_engine(const char *engine)
    {
        ENGINE *e = NULL;
        if ((e = ENGINE_by_id(engine)) == NULL) {
            fprintf(stderr, "Invalid engine \"%s\".\n", engine);
            fprintf(stderr, "    Did you use the correct path?\n");
            fprintf(stderr, "    Did you configure OpenSSL to build shared libraries?\n");
            fprintf(stderr, "    Does your system know where your OpenSSL shared libraries are located?\n");
            fprintf(stderr, "    Does your system know where your IQR Toolkit shared libraries are located?\n");
            return NULL;
        }

        if (!ENGINE_init(e)) {
            fprintf(stderr, "The engine did not initialize correctly.\n");
            ENGINE_free(e);
            return NULL;
        }

        if (!ENGINE_set_default(e, ENGINE_METHOD_ALL)) {
            fprintf(stderr, "Unable to use this engine.\n");
            ENGINE_free(e);
            return NULL;
        }

        fprintf(stdout, "Engine \"%s\" set.\n", ENGINE_get_id(e));
        return e;
    }

    int main(int argc, char **argv)
    {
        if (argc != 2) {
            fprintf(stderr, "Failure to specify the correct parameters.\n");
            usage(argv[0]);
            return EXIT_FAILURE;
        }

        CRYPTO_set_mem_debug(1);
        CRYPTO_mem_ctrl(CRYPTO_MEM_CHECK_ON);
        ERR_load_crypto_strings();
        ENGINE_load_dynamic();

        ENGINE *e = setup_engine(argv[1]);
        if (e == NULL) {
            usage(argv[0]);
            return EXIT_FAILURE;
        }
>   // SNIPPET_END_1

Much of the code has been omitted in this example. See the full code in openssl_engine_load.c.

An alternative way of specifying the engine would be to use a .conf file. Please see the section Using OpenSSL Utilities For Quantum-Safe Public Key Cryptography for more details.

Identifying the Algorithms

Artifacts encoded as .pem or .der files have OIDs (Object Identifiers) that define which algorithms they work with. The only place where you would have to identify the desired algorithm is during key generation. You can either do that with EVP_PKEY_asn1_find_str() or with EVP_PKEY_CTX_new_id().

EVP_PKEY_asn1_find_str() takes the algorithm name as a string and EVP_PKEY_CTX_new_id() takes an integer constant associated with the algorithm. Here is a table of the associated strings and constants. These strings are case insensitive.

Table 19. Algorithm Identifiers
Algorithm EVP_PKEY_asn1_find_str() EVP_PKEY_CTX_new_id()

FRODODH

frododh

EVP_PKEY_FRODODH

NHDH

nhdh

EVP_PKEY_NHDH

SAMWISE

samwise

EVP_PKEY_SAMWISE

SIDH

sidh

EVP_PKEY_SIDH

CMC

cmc

EVP_PKEY_CMC

FRODOKEM

frodokem

EVP_PKEY_FRODOKEM

KYBER

kyber

EVP_PKEY_KYBER

NTRUP

ntrup

EVP_PKEY_NTRUP

SABER

saber

EVP_PKEY_SABER

SIKE

sike

EVP_PKEY_SIKE

DILITHIUM

dilithium

EVP_PKEY_DILITHIUM

HSS

hss

EVP_PKEY_HSS

RAINBOW

rainbow

EVP_PKEY_RAINBOW

SPHINCS

sphincs

EVP_PKEY_SPHINCS

XMSS

xmss

EVP_PKEY_XMSS

XMSSMT

xmssmt

EVP_PKEY_XMSSMT

Setting Parameters

FRODODH

You must use the following options when calling EVP_PKEY_CTX_ctrl() with EVP_PKEY_CTRL_FRODODH_ROLE_SET when generating a key pair to specify if this is the initiator or responder:

Table 20. FRODODH Protocol Roles
Role Value

Initiator

1

Responder

0

You must use the following options when calling EVP_PKEY_CTX_ctrl() with EVP_PKEY_CTRL_FRODODH_PARAMETER_SET or calling EVP_PKEY_CTX_ctrl_str() with "parameter_set" when generating a key pair to specify the parameter set:

Table 21. FRODODH Parameter Sets
EVP_PKEY_CTRL_FRODODH_PARAMETER_SET parameter_set Radiate Variant

FRODODH_976_AES_R2

FrodoDH_976_AES_r2

IQR_FRODODH_976_AES

FRODODH_976_SHAKE_R2

FrodoDH_976_SHAKE_r2

IQR_FRODODH_976_SHAKE

NHDH

You must use the following options when calling EVP_PKEY_CTX_ctrl() with EVP_PKEY_CTRL_NHDH_ROLE_SET when generating a key pair to specify if this is the initiator or responder:

Table 22. NHDH Protocol Roles
Role Value

Initiator

1

Responder

0

You must use the following option when calling EVP_PKEY_CTX_ctrl() with EVP_PKEY_CTRL_NHDH_PARAMETER_SET or calling EVP_PKEY_CTX_ctrl_str() with "parameter_set" when generating a key pair to specify the parameter set:

Table 23. NHDH Parameter Sets
EVP_PKEY_CTRL_NHDH_PARAMETER_SET parameter_set Radiate Variant

NHDH_1024_V0

NHDH_1024_v0

N/A

SAMWISE

You must use the following options when calling EVP_PKEY_CTX_ctrl() with EVP_PKEY_CTRL_SAMWISE_ROLE_SET when generating a key pair to specify if this is the initiator or responder:

Table 24. SAMWISE Protocol Roles
Role Value

Initiator

1

Responder

0

You must use the following option when calling EVP_PKEY_CTX_ctrl() with EVP_PKEY_CTRL_SAMWISE_PARAMETER_SET or calling EVP_PKEY_CTX_ctrl_str() with "parameter_set" when generating a key pair to specify the parameter set:

Table 25. SAMWISE Parameter Sets
EVP_PKEY_CTRL_SAMWISE_PARAMETER_SET parameter_set Radiate Variant

SAMWISE_976_AES_V1

Samwise_976_AES_v1

IQR_SAMWISE_976_AES

SAMWISE_976_CHACHA20_V1

Samwise_976_ChaCha20_v1

IQR_SAMWISE_976_CHACHA20

SIDH

You must use the following options when calling EVP_PKEY_CTX_ctrl() with EVP_PKEY_CTRL_SIDH_ROLE_SET when generating a key pair to specify if this is Alice or Bob:

Table 26. SIDH Protocol Roles
Role Value

Alice

1

Bob

0

You must use the following options when calling EVP_PKEY_CTX_ctrl() with EVP_PKEY_CTRL_SIDH_PARAMETER_SET or calling EVP_PKEY_CTX_ctrl_str() with "parameter_set" when generating a key pair to specify the parameter set:

Table 27. SIDH Parameter Sets
EVP_PKEY_CTRL_SIDH_PARAMETER_SET parameter_set Radiate Variant

SIDH_P434_R2

SIDH_p434_r2

IQR_SIDH_P434

SIDH_P503_R2

SIDH_p503_r2

IQR_SIDH_P503

SIDH_P610_R2

SIDH_p610_r2

IQR_SIDH_P610

SIDH_P751_R2

SIDH_p751_r2

IQR_SIDH_P751

CMC KEM

You must use the following options when calling EVP_PKEY_CTX_ctrl() with EVP_PKEY_CTRL_CMC_PARAMETER_SET or calling EVP_PKEY_CTX_ctrl_str() with "parameter_set" when generating a key pair to specify the parameter set:

Table 28. CMC Parameter Sets
EVP_PKEY_CTRL_CMC_PARAMETER_SET parameter_set Radiate Variant

CMC_6960119_R2

ClassicMcEliece_6960119_r2

IQR_CLASSICMCELIECE_6

CMC_8192128_R2

ClassicMcEliece_8192128_r2

IQR_CLASSICMCELIECE_8

FRODOKEM

You must use the following options when calling EVP_PKEY_CTX_ctrl() with EVP_PKEY_CTRL_FRODOKEM_PARAMETER_SET or calling EVP_PKEY_CTX_ctrl_str() with "parameter_set" when generating a key pair to specify the parameter set:

Table 29. FRODOKEM Parameter Sets
EVP_PKEY_CTRL_FRODOKEM_PARAMETER_SET parameter_set Radiate Variant

FRODOKEM_640_AES_R2

FrodoKEM_640_AES_r2

IQR_FRODOKEM_640_AES

FRODOKEM_640_SHAKE_R2

FrodoKEM_640_SHAKE_r2

IQR_FRODOKEM_640_SHAKE

FRODOKEM_976_AES_R2

FrodoKEM_976_AES_r2

IQR_FRODOKEM_976_AES

FRODOKEM_976_SHAKE_R2

FrodoKEM_976_SHAKE_r2

IQR_FRODOKEM_976_SHAKE

FRODOKEM_1344_AES_R2

FrodoKEM_1344_AES_r2

IQR_FRODOKEM_1344_AES

FRODOKEM_1344_SHAKE_R2

FrodoKEM_1344_SHAKE_r2

IQR_FRODOKEM_1344_SHAKE

KYBER

You must use the following options when calling EVP_PKEY_CTX_ctrl() with EVP_PKEY_CTRL_KYBER_PARAMETER_SET or calling EVP_PKEY_CTX_ctrl_str() with "parameter_set" when generating a key pair to specify the parameter set:

Table 30. KYBER Parameter Sets
EVP_PKEY_CTRL_KYBER_PARAMETER_SET parameter_set Radiate Variant

KYBER_512_R2

Kyber_512_r2

IQR_KYBER_512

KYBER_768_R2

Kyber_768_r2

IQR_KYBER_768

KYBER_1024_R2

Kyber_1024_r2

IQR_KYBER_1024

NTRUP

You must use the following options when calling EVP_PKEY_CTX_ctrl() with EVP_PKEY_CTRL_NTRUP_PARAMETER_SET or calling EVP_PKEY_CTX_ctrl_str() with "parameter_set" when generating a key pair to specify the parameter set:

Table 31. NTRUP Parameter Sets
EVP_PKEY_CTRL_NTRUP_PARAMETER_SET parameter_set Radiate Variant

NTRUPRIME_SNTRUP653_R2

NTRUPrime_sntrup653_r2

IQR_SNTRUP_653

NTRUPRIME_SNTRUP761_R2

NTRUPrime_sntrup761_r2

IQR_SNTRUP_761

NTRUPRIME_SNTRUP857_R2

NTRUPrime_sntrup857_r2

IQR_SNTRUP_857

SABER

You must use the following options when calling EVP_PKEY_CTX_ctrl() with EVP_PKEY_CTRL_SABER_PARAMETER_SET or calling EVP_PKEY_CTX_ctrl_str() with "parameter_set" when generating a key pair to specify the parameter set:

Table 32. SABER Parameter Sets
EVP_PKEY_CTRL_SABER_PARAMETER_SET parameter_set Radiate Variant

SABER_LIGHTSABER_R2

Saber_LightSaber_r2

IQR_LIGHT_SABER

SABER_SABER_R2

Saber_Saber_r2

IQR_SABER

SABER_FIRESABER_R2

Saber_FireSaber_r2

IQR_FIRE_SABER

SIKE

You must use the following options when calling EVP_PKEY_CTX_ctrl() with EVP_PKEY_CTRL_SIKE_PARAMETER_SET or calling EVP_PKEY_CTX_ctrl_str() with "parameter_set" when generating a key pair to specify the parameter set:

Table 33. SIKE Parameter Sets
EVP_PKEY_CTRL_SIKE_PARAMETER_SET parameter_set Radiate Variant

SIKE_P434_R2

SIKE_p434_r2

IQR_SIKE_P434

SIKE_P503_R2

SIKE_p503_r2

IQR_SIKE_P503

SIKE_P610_R2

SIKE_p610_r2

IQR_SIKE_P610

SIKE_P751_R2

SIKE_p751_r2

IQR_SIKE_P751

DILITHIUM

You must use the following options when calling EVP_PKEY_CTX_ctrl() with EVP_PKEY_CTRL_DILITHIUM_PARAMETER_SET or calling EVP_PKEY_CTX_ctrl_str() with "parameter_set" when generating a key pair to specify the parameter set:

Table 34. Dilithium Parameter Sets
EVP_PKEY_CTRL_DILITHIUM_PARAMETER_SET parameter_set Radiate Variant

DILITHIUM_II_SHAKE_R2

Dilithium_II_SHAKE_r2

IQR_DILITHIUM_80

DILITHIUM_III_SHAKE_R2

Dilithium_III_SHAKE_r2

IQR_DILITHIUM_128

DILITHIUM_IV_SHAKE_R2

Dilithium_IV_SHAKE_r2

IQR_DILITHIUM_160

HSS

You must use the following options when calling EVP_PKEY_CTX_ctrl() with EVP_PKEY_CTRL_HSS_SIGOPS_SET or calling EVP_PKEY_CTX_ctrl_str() with "sign_operations" when generating a key pair to specify how many times you would like to perform the signing operation with the generated private key:

Table 35. HSS Signing Operations
EVP_PKEY_CTRL_HSS_SIGOPS_SET sign_operations

HSS_SIGOPS_2E15

2E15

HSS_SIGOPS_2E20

2E20

HSS_SIGOPS_2E30

2E30

HSS_SIGOPS_2E45

2E45

HSS_SIGOPS_2E65

2E65

You must use the following options when calling EVP_PKEY_CTX_ctrl() with EVP_PKEY_CTRL_HSS_OPTIMIZATION_SET or calling EVP_PKEY_CTX_ctrl_str() with "optimization" when generating a key pair to specify an optimization:

Table 36. HSS Optimization
EVP_PKEY_CTRL_HSS_OPTIMIZATION_SET optimization

HSS_OPTIMIZATION_FAST

fast

HSS_OPTIMIZATION_SMALL

small

You must use the following options when calling EVP_PKEY_CTX_ctrl() with EVP_PKEY_CTRL_HSS_STRATEGY_SET or calling EVP_PKEY_CTX_ctrl_str() with "strategy" when generating a key pair to specify HSS tree strategy:

Table 37. HSS Tree Strategy
EVP_PKEY_CTRL_HSS_STRATEGY_SET strategy

HSS_STRATEGY_CPU_CONSTRAINED

cpu_constrained

HSS_STRATEGY_MEMORY_CONSTRAINED

memory_constrained

HSS_STRATEGY_FULL

full

You must use the "state_filename" option with EVP_PKEY_CTX_ctrl_str() when generating a key pair to specify the HSS private key’s state file name. See the Special Note on Stateful Hash Based Signature Schemes for details about the "state_filename" option.

RAINBOW

You must use the following options when calling EVP_PKEY_CTX_ctrl_str() with "parameter_set" when generating a key pair to specify the parameter set:

Table 38. RAINBOW Parameter Sets
EVP_PKEY_CTRL_RAINBOW_PARAMETER_SET parameter_set Radiate Variant

RAINBOW_IIIC_STD_R2

Rainbow_IIIc_std_r2

IQR_RAINBOW_GF256_68_36_36

RAINBOW_VC_STD_R2

Rainbow_Vc_std_r2

IQR_RAINBOW_GF256_92_48_48

SPHINCS

You must use the following options when calling EVP_PKEY_CTX_ctrl_str() with "parameter_set" when generating a key pair to specify the parameter set:

Table 39. SPHINCS Parameter Sets
EVP_PKEY_CTRL_SPHINCS_PARAMETER_SET parameter_set Radiate Variant

SPHINCS_SHAKE_256_192F_R2

SPHINCS_SHAKE_256_192f_r2

IQR_SPHINCS_SHAKE_256_192F

SPHINCS_SHAKE_256_192S_R2

SPHINCS_SHAKE_256_192s_r2

IQR_SPHINCS_SHAKE_256_192S

SPHINCS_SHAKE_256_256F_R2

SPHINCS_SHAKE_256_256f_r2

IQR_SPHINCS_SHAKE_256_256F

SPHINCS_SHAKE_256_256S_R2

SPHINCS_SHAKE_256_256s_r2

IQR_SPHINCS_SHAKE_256_256S

SPHINCS_SHA2_256_192F_R2

SPHINCS_SHA2_256_192f_r2

IQR_SPHINCS_SHA2_256_192F

SPHINCS_SHA2_256_192S_R2

SPHINCS_SHA2_256_192s_r2

IQR_SPHINCS_SHA2_256_192S

SPHINCS_SHA2_256_256F_R2

SPHINCS_SHA2_256_256f_r2

IQR_SPHINCS_SHA2_256_256F

SPHINCS_SHA2_256_256S_R2

SPHINCS_SHA2_256_256s_r2

IQR_SPHINCS_SHA2_256_256S

XMSS

You must use the following options when calling EVP_PKEY_CTX_ctrl_str() with "tree_height" when generating a key pair to specify the XMSS tree height:

Table 40. XMSS Tree Height
tree_height

10

16

20

You must use the following options when calling EVP_PKEY_CTX_ctrl_str() with "strategy" when generating a key pair to specify the XMSS tree strategy:

Table 41. XMSS Tree Strategy
strategy

cpu_constrained

memory_constrained

full

You must use the "state_filename" option with EVP_PKEY_CTX_ctrl_str() when generating a key pair to specify the XMSS private key’s state file name. See the Special Note on Stateful Hash Based Signature Schemes for details about the "state_filename" option.

XMSSMT

You must use the "state_filename" and "tree_layers" options with EVP_PKEY_CTX_ctrl_str() to specify the tree height and layers when generating a key. Only the following combinations are valid:

Table 42. XMSSMT Tree Height and Layer Combinations
Height Layers

20

2

20

4

40

2

40

4

40

8

60

3

60

6

60

12

You must use the following options when calling EVP_PKEY_CTX_ctrl_str() with "strategy" when generating a key pair to specify the XMSSMT tree strategy:

Table 43. XMSSMT Tree Strategy
strategy

cpu_constrained

memory_constrained

full

You must use the "state_filename" option with EVP_PKEY_CTX_ctrl_str() when generating a key pair to specify the XMSSMT private key’s state file name. See the Special Note on Stateful Hash Based Signature Schemes for details about the "state_filename" option.

Using libssl APIs For Quantum-Safe TLS Protocol Messaging

Quantum-Safe TLS 1.2 Cipher Suites

The libssl library maintains its own list of cipher suites in priority order. The client and server negotiate a common cipher suite based on their priorities.

Specifically, it provides quantum-safe cipher suites in addition to the standard cipher suites supported by OpenSSL. They are assigned from the IANA private range and are only compatible with other ISARA TLS implementations such as ISARA Catayst TLS Testbed. To get a list of all supported quantum-safe cipher suites in priority order, run the ciphers utiltity with the cipherlist command line option set as QS. If you run the ciphers utility without specifying cipherlist you can get a list of all supported cipher suites in priority order.

Note
The new cipher suites are at the lowest priority. This is to prevent migration issues that might occur.

The quantum-safe key exchange and authentication algorithms used in the cipher suites are selected submissions to the NIST Post-Quantum Standardization evaluation process and are implemented in libcrypto.

The following quantum-safe algorithms are supported.
Key exchange: SABER, KYBER, SIKE, NHDH, SIDH
Authentication: DILITHIUM (DILM)

See section Using libcrypto APIs For Quantum-Safe Public Key Cryptography for more information on each of these algorithms.

In some of the cipher suites, more than one quantum-safe key exchange algorithms are combined together, such as ECDHE-KYBER-SIKE. Such hybrid key exchanges give the same amount of protection as the most secure algorithm, and if one were discovered to be insecure, others in the hybrid can continue to uphold the security as they are all based on different categories of math problems, and therefore are less likely to be broken at the same time.

Most of the cipher suites are also augmented with the classical ECDHE key exchange algorithm. These cipher suites are for the transitional period before large scale quantum computers capable of breaking classical algorithms become available. The security of such hybrid key exchanges is further underpinned by the tried-and-true classical ECDHE key exchange algorithm. In the event where all the relatively new quantum-safe algorithms were found to be insecure, the overall security would still be sustained with ECDHE during the transitional period.

To programmatically get a list of available cipher suites you can use SSL_get_ciphers() or SSL_get_cipher_list() which are documented on the OpenSSL.org website at https://www.openssl.org/docs/man1.1.1/man3/SSL_get_ciphers.html

To use a specific cipher suite:

  • Use SSL_CONF_cmd(SSL_CONF_CTX *cctx, const char *cmd, const char *value) with cmd set to "cipher" and value set to one of the strings from the ciphers command.

  • Use SSL_CTX_set_cipher_list(SSL_CTX *ctx, const char *str) with str set to one of the strings from the ciphers command.

  • Use SSL_set_cipher_list(SSL *ssl, const char *str) with str set to one of the strings from the ciphers command.

SSL_CONF_cmd() is documented on the OpenSSL.org website at https://www.openssl.org/docs/man1.1.1/man3/SSL_CONF_cmd.html SSL_CTX_set_cipher_list() and SSL_set_cipher_list() are documented at https://www.openssl.org/docs/man1.1.1/man3/SSL_CTX_set_cipher_list.html.

By default, the new quantum-safe cipher suites are set at a lower priority than the standard ones in order to facilitate a smooth migration.

API for Quantum-Safe Key Exchange Algorithm Parameters

The libssl library provides a list of public functions to set and get algorithm groups for key exchange algorithms used during a TLS handshake. They are documented at https://www.openssl.org/docs/man1.1.1/man3/SSL_CTX_set1_groups_list.html

The following table shows the NIDs for all supported groups in TLS 1.2 for each quantum-safe key exchange algorithm as well as in their string format, listed in the default decreasing preference order.

Table 44. TLS 1.2 Quantum-Safe Key Exchange Algorithm Parameters in NID and String Format
Algorithm Parameter — NID Parameter — String

SABER

NID_Saber_Saber_r2

Saber_Saber_r2

NID_Saber_LightSaber_r2

Saber_LightSaber_r2

NID_Saber_FireSaber_r2

NID_Saber_FireSaber_r2

Kyber

NID_Kyber_768_r2

Kyber_768_r2

NID_Kyber_512_r2

Kyber_512_r2

NID_Kyber_1024_r2

Kyber_1024_r2

SIKE

NID_SIKE_p610_r2

SIKE_p610_r2

NID_SIKE_p503_r2

SIKE_p503_r2

NID_SIKE_p434_r2

SIKE_p434_r2

NID_SIKE_p751_r2

SIKE_p751_r2

NHDH

NID_NewHope_1024_v0

NewHope_1024_v0

SIDH

NID_SIDH_p610_r2

SIDH_p610_r2

NID_SIDH_p503_r2

SIDH_p503_r2

NID_SIDH_p434_r2

SIDH_p434_r2

NID_SIDH_p751_r2

SIDH_p751_r2

If the API for setting parameters is not used, all parameters listed in table TLS 1.2 Quantum-Safe Key Exchange Algorithm Parameters in NID and String Format are set for each quantum-safe key exchange algorithm.

OpenSSL configuration command function and configuration file settings for quantum-safe key exchange algorithm parameters

Parameters can also be set using OpenSSL configuration command function:

int SSL_CONF_cmd(SSL_CONF_CTX *cctx, const char *cmd, const char *value);

See its documentation on the OpenSSL.org website at https://www.openssl.org/docs/man1.1.1/man3/SSL_CONF_cmd.html for detailed usage information.

Special Note on Signature Scheme Usage in TLS

Due to the dynamic nature of the private keys, stateful hash-based signature schemes (HSS, XMSS, XMSSMT) are not appropriate for real-time signing of TLS messages. As such, these are only used for root of trust and intermediate CA certificates within the X.509 certificate chain.

Due to large public keys and signatures, Rainbow and SPHINCS+ are not appropriate for use in TLS.

Special Note on Catalyst Certificates and Dual Private Keys

ISARA has developed ISARA Catalyst certificates as a means of easing the transition to Quantum-Safe algorithms for larger organizations with complex infrastructures. These certificates contain alternative public keys and signatures. As such, signing operations also require an alternative private key and so we have developed private key files with an alternative private key. We call them dual private keys. A quantum-safe private key is converted to a dual private key by combining it with the associated classical private key in privAltExtend.py, reqAltExtend or x509AltDirectExtend.

For the orginal OpenSSL utilities, the dual private key file can be used instead of the original private key file since the alternative key in the dual private key file will simply be ignored. However, openssl s_server and openssl s_client are notable exceptions. They will only accept a single private key file. If a TLS connection is being negotiated with a Catalyst certificate and the alternative authentication scheme is desired, there must be an alternative private key and so a dual private key file must be specified.

ISARA has created a tutorial document on how to create and use these kinds of certificates and private key files. See ISARA Catalyst Connector 2.1 Alt Certificate Tutorial.

TLS Entity Authentication with Catalyst Certificates

Note
This feature is only supported in TLS 1.2.
Note
This feature requires that strict mode be enabled so we have enabled it by default. Without it, proper selection of the conventional or alternative public key will not happen.

The libssl library can perform TLS entity authentication using ISARA Catalyst certificates. Please read the tutorial document ISARA Catalyst Connector 2.1 QS Certificate Tutorial to learn about Catalyst certificates before reading the rest of this section.

The TLS client and server need to load the Catalyst certificates and the corresponding private keys before they can perform Catalyst entity authentication during the TLS handshake process. See TLS and Catalyst Certificates Tutorial on how to load Catalyst certificates and private keys into OpenSSL’s TLS context.

The client and the server use a new proprietary TLS private use hello extension called "isara_catalyst" to signal to the peer that the end entity supports Catalyst authentication. Any client or server that does not have this extension in the TLS hello message is deemed as not Catalyst capable. All clients and servers that use ISARA Catalyst Connector’s libssl library will have this extension automatically added to the entity’s TLS hello message. (This extension is only added to the server’s hello message if the server has received the same extension from the client’s hello message and TLS 1.2 has been negotiated.) Note that entities that are not Catalyst capable may still use Catalyst certificates and the associated conventional keys to authenticate themselves. The alternative parts in the Catalyst certificates will not play a role in such authentication.

Cipher Suite Selection and Server Authentication

How the server chooses the cipher suite for the TLS session can be strongly influenced by whether the client supports Catalyst and whether the client supports all the alternative signature algorithms in the server’s Catalyst certificate chain.

For instance, if the client supports Catalyst as well as all the alternative signature algorithms in the server’s Catalyst certificate chain, then the server is free to consider cipher suites with an authentication algorithm the same as the alternative public key type in the server’s leaf Catalyst certificate. On the other hand, if the client does not support Catalyst or if the client does not support some of the alternative signature algorithms in the server’s Catalyst certificate chain, then the server is limited to choosing from only the set of cipher suites with an authentication algorithm the same as the conventional public key type in the server’s leaf Catalyst certificate.

For server authentication, the server sends the server’s Catalyst certificate chain to the client and uses the private key corresponding to the authentication algorithm in the selected cipher suite to sign the server key exchange message. The client then checks which public key type in the server’s leaf Catalyst certificate matches the authentication algorithm in the selected cipher suite, and verifies the corresponding certificate chain, which is either the "conventional certificate chain" (consisting of all the conventional signature values) or the "alternative certificate chain" (consisting of all the alternative signature values), contained in the server’s Catalyst certificate chain. The client also uses this public key to verify the signature contained in the server key exchange message.

Client Authentication

Client authentication with Catalyst employs a similar mechanism to server authentication, except the cipher suite no longer plays a role.

If the server advertises support of all the alternative signature algorithms in the client’s Catalyst certificate chain as well as the alternative public key type in the client’s leaf Catalyst certificate, then the client uses the alternative private key to produce the TLS certificate verify message. Otherwise, the client uses the conventional private key to produce the certificate verify message (which is also the case if the server is not Catalyst enabled).

The client sends its Catalyst certificate chain and the certificate verify message to the server for entity authentication. The server checks if it supports all the alternative signature algorithms in the client’s Catalyst certificate chain as well as the alternative public key type in the client’s leaf Catalyst certificate. If yes, it verifies the alternative certificate chain and uses the alternative public key to verify the certificate verify message. Otherwise, it verifies the conventional certificate chain and uses the conventional public key to verify the certificate verify message.

Application Level Changes

The following are descriptions of changes made to the applications and tests included within OpenSSL. It is important that you understand these changes as they would reflect changes that would be required in your own code. For more details, please see the patch file.

Note
We want the tests to continue to use classical algorithms and standard cipher suites to show that our changes have not broken any pre-existing functionality.

apps/s_cb.c and apps/apps.c

  • Add common code between multiple application to:

    • Disable strict mode. We enable it by default to do proper selection of the conventional or alternative public key. However, some of the OpenSSL tests that use s_server and s_client require strict mode to be disabled.

    • Load the alternative private key.

    • Handle quantum safe algorithms when printing signature types, variant names, and groups.

    • Allow loading large input files since artifacts for quantum-safe algorithms are generally larger than their classical counterparts.

apps/ca.c

  • Allow message digest to be NULL to accomodate intrinsic signing.

apps/cms.c

  • Use BIO_free_all() instead of BIO_free() to free indata. This is required because in order to support intrinsic signing we had to add a special BIO to the BIO chain to fully buffer the message data. Using BIO_free_all() insures it is freed.

apps/crl.c

  • Add support for specifying the engine on the command-line because all quantum-safe algorithms are implemented by the engine.

apps/pkcs12.c

  • Output the alternative private key if present.

apps/pkeyutl.c

  • Accomodate larger input files.

apps/s_server.c

  • Load alternative key in the case of a dual private key being specified.

apps/s_client.c

  • Load alternative key in the case of a dual private key being specified.

test/cipherlist_test.c

  • Add new cipher suites to a list.

test/ciphername_test.c

  • Add new code points and cipher suite names to a list.

test/clienthellotest.c

  • Change a test to use a single supported group and a single supported sigalg because the default would make it too long to trigger the condition for a specific test.

test/recipes/70-test_sslmessages.t

  • Make tests aware of the Catalyst TLS extension.

test/recipes/70-test_tls13kexmodes.t

  • Make tests aware of the Catalyst TLS extension.

test/recipes/70-test_tls13messages.t

  • Make tests aware of the Catalyst TLS extension.

test/recipes/80-test_ssl_old.t

  • Skip protocol tests for cipher suites with quantum safe algorithms because the testing infrastructure is not aware of the IQRE Engine.

test/ssl_test.c

  • Clear strict mode. We enabled strict mode by default, but these tests do not expect strict mode to be enabled and will fail if it is enabled.

test/sslapitest.c

  • Make tests aware of the Catalyst TLS extension.

test/sslcorrupttest.c

  • Explicitly specify that the tests should be run against the standard cipher suites thus avoiding cipher suites with quantum safe algorithms because the testing infrastructure is not aware of the IQRE Engine.

The ISARA Catalyst Connector Binaries are licensed for use:

Copyright © 2017-2021, ISARA Corporation, All Rights Reserved.

The code and other content set out herein is not in the public domain, is considered a trade secret and is confidential to ISARA Corporation. Use, reproduction or distribution, in whole or in part, of such code or other content is strictly prohibited except by express written permission of ISARA Corporation. Please contact ISARA Corporation at info@isara.com for more information.

  • ISARA Catalyst Connector (ID 60cc6d411e2b66cd8fe1fc34331254bec9e6eb27)