Introduction

The ISARA Catalyst™ OpenSSL Connector lets you implement OpenSSL using the algorithms provided in the ISARA Radiate™ Quantum-Safe Security Solution Suite. ISARA Catalyst 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.0 of the ISARA Catalyst OpenSSL Connector package contains:

  • Documentation and diagrams about the ISARA Catalyst OpenSSL 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 OpenSSL 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 OpenSSL Connector.

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

The patch files and engine have been tested against these versions of OpenSSL:

  • OpenSSL—​1.0.2q

  • OpenSSL—​1.0.2r

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

The User’s Guide covers the following topics:

Packaging

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

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

  • OpenSSL-Connector-Guide.html — This file.

  • OpenSSL-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 one of the following:

    • OpenSSL—​1.0.2q

    • OpenSSL—​1.0.2r

  • 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 OpenSSL Connector Engine Library

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

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

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

  • demos/demos_sln_Visual_Studio_2017/ — Contains solution files for building the demos on Windows. (on Windows)

  • demos_script.txt — Script used to demonstrate using OpenSSL with our algorithms

  • demos_script_expected_output.txt — Expected output of the demos_script.txt

  • TLS_test_script.txt — Script used to perform OpenSSL client-server TLS secure handshakes and message communications using ISARA quantum-safe ciphersuites

  • TLS_test_script_expected_output.txt — Expected output of the TLS_test_script.txt

  • data/ — Configuration and output files for the scripts above

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.0 Developer’s Guide.

Introduction to ISARA’s Algorithms

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

  • Key Exchange Schemes

    • Frodo Diffie-Hellman Key Exchange (FRODODH)

    • NewHope Diffie-Hellman Key Exchange (NHDH)

    • Supersingular Isogeny Diffie-Hellman Key Exchange (SIDH)

  • Key Encapsulation Mechanisms

    • Classic McEliece KEM (CMC)

    • Frodo KEM (FRODOKEM)

    • Kyber Lattice-Based KEM (KYBER)

    • NTRU Prime Lattice-Based KEM (NTRUP)

    • 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 OpenSSL Connector and algorithm specifier in 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.

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 key exchange algorithms 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.

Applying the ISARA Catalyst OpenSSL Connector Patch to OpenSSL

The ISARA Catalyst OpenSSL 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. In the unpacked directory, apply the patch using the following command: patch -p2 < OpenSSL_<version>_ISARA.patch

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.

  2. Execute make depend

  3. Execute make all

  4. Execute make test

  5. Build the demo applications. The ISARA Catalyst OpenSSL Connector uses the following compiler and linker flags to build these applications: -O3 -DNDEBUG -rdynamic -lcrypto. Your system might require different parameters.

  6. Run the ISARA Catalyst OpenSSL Connector demos and the OpenSSL standard utilities as shown in demo_script.txt to see if you get similar console output to what is shown in demos_script_expected_output.txt and similar output files in the data directory.

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/namke commands from a VC++ x64 environment. This can be done by running VCVARSALL x64 from the command prompt. 2. Execute ms\do_win64a 3. Execute nmake -f ms\ntdll.mak 4. Execute nmake -f ms\ntdll.mak test 5. Execute nmake -f ms\ntdll.mak install 6. Build the demo applications. The .sln in package/demos expects to find your custom build of OpenSSL installed in package/openssl. Copy your build to this folder prior to building the demos, or use --prefix=package\openssl in the Configure step of the OpenSSL build. 7. Run the ISARA Catalyst OpenSSL Connector demos and the OpenSSL standard utilities as shown in demo_script.txt to see if you get similar console output to what is shown in demos_script_expected_output.txt and similar output files in the data directory.

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, demos_script_expected_output.txt does 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.0.2/apps/

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

ISARA_VERBOSE=1

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

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

SIDH

CMC

FRODOKEM

KYBER

NTRUP

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 ciphersuites. To try one of the ISARA Catalyst ciphersuites, run the ciphers command to get a list of all supported ciphersuites and pick the one you want. When you execute s_client, pass in that ciphersuite with the -cipher command line option.

Special Note on Ephemeralness

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

  • FRODODH

  • NHDH

  • SIDH

These algorithms are specifically designed for ephemeral key exchange. They are only used in the s_server, s_client and demo applications that run the TLS protocol. They are also featured in the ciphers application that shows the name of the ciphersuites 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 OpenSSL 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 can 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

A

IQR_CLASSICMCELIECE_6

B

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

A

IQR_FRODOKEM_976_AES

B

IQR_FRODOKEM_976_CSHAKE

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

A

IQR_KYBER_768

B

IQR_KYBER_1024

NTRU Prime KEM

If the application has an -algorithm parameter, you can specify NTRU Prime with -algorithm ntrup. There is only one parameter set supported by the toolkit.

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 5. SIKE Parameter Sets
p Radiate Variant

A

IQR_SIKE_P503

B

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 6. DILITHIUM Parameter Sets
p Radiate Variant

A

IQR_DILITHIUM_128

B

IQR_DILITHIUM_160

eXtended Merkle Signature Scheme

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

You can 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 7. XMSS Tree Height
h

10

16

20

Use one of these values for s:

Table 8. 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.0 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 can 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 9. 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 10. 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.0 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 can 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 11. HSS Sign Operations
so

2E30

2E45

2E65

Use one of these values for o:

Table 12. HSS Optimization
o

fast

small

Use one of these values for s:

Table 13. 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.0 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 14. RAINBOW Parameter Sets
p Radiate Variant

A

IQR_RAINBOW_GF31_64_32_48

B

IQR_RAINBOW_GF256_68_36_36

C

IQR_RAINBOW_GF16_56_48_48

D

IQR_RAINBOW_GF256_92_48_48

E

IQR_RAINBOW_GF16_76_64_64

F

IQR_RAINBOW_GF31_84_56_56

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 15. SPHINCS Parameter Sets
p Radiate Variant

A

IQR_SPHINCS_SHAKE_256_192S

B

IQR_SPHINCS_SHAKE_256_192F

C

IQR_SPHINCS_SHAKE_256_256S

D

IQR_SPHINCS_SHAKE_256_256F

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 16. EVP APIs per Algorithm
Algorithm CTX_new_id Keygen Sign Verify SetPeer Derive

FRODODH

NHDH

SIDH

CMC

FRODOKEM

KYBER

NTRUP

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. We do not expose our KEMs for key transport in TLS. However, we do expose them via the EVP PKEY derive()/derive_set_peer() APIs.

Loading the Engine

You must load the ISARA Catalyst 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:

ENGINE *setup_engine(const char *engine)
{
    ENGINE *e = NULL;
    if ((e = ENGINE_by_id(engine)) == NULL) {
        fprintf(stderr, "Invalid engine \"%s\".\n", engine);
        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_malloc_debug_init();
    CRYPTO_set_mem_debug_options(V_CRYPTO_MDEBUG_ALL);
    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;
    }

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

For security reasons, the ISARA Catalyst engine overrides the default RNG implementation in OpenSSL with ISARA’s HMAC-DRBG using SHA2-256. You can check to see if this override has taken effect with the following code:

    const RAND_METHOD *rm = RAND_get_rand_method();
    if(rm == RAND_SSLeay()) {
        fprintf(stdout, "After engine load, using default generator\n");
        return EXIT_FAILURE;
    } else {
        fprintf(stdout, "After engine load, NOT using default generator\n");
    }

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

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. When using these strings, case is not an issue.

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

FRODODH

"frododh"

EVP_PKEY_FRODODH

NHDH

"nhdh"

EVP_PKEY_NHDH

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

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

NTRUP has no parameters to set.

Each of the other algorithms require different parameters.

FRODODH

You can 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 18. FRODODH Protocol Roles
Role Value

Initiator

1

Responder

0

NHDH

You can 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 19. NHDH Protocol Roles
Role Value

Initiator

1

Responder

0

SIDH

You can 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 20. SIDH Protocol Roles
Role Value

Alice

1

Bob

0

You can 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 21. SIDH Parameter Sets
EVP_PKEY_CTRL_SIDH_PARAMETER_SET Radiate Variant

SIDH_PARAMETER_SET_A

IQR_SIDH_P503

SIDH_PARAMETER_SET_B

IQR_SIDH_P751

CMC KEM

You can 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 22. CMC Parameter Sets
EVP_PKEY_CTRL_CMC_PARAMETER_SET "parameter_set" Radiate Variant

CMC_PARAMETER_SET_A

"A"

IQR_CLASSICMCELIECE_6

CMC_PARAMETER_SET_B

"B"

IQR_CLASSICMCELIECE_8

FRODOKEM

You can 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 23. FRODOKEM Parameter Sets
EVP_PKEY_CTRL_FRODOKEM_PARAMETER_SET "parameter_set" Radiate Variant

FRODOKEM_PARAMETER_SET_A

"A"

IQR_FRODOKEM_976_AES

FRODOKEM_PARAMETER_SET_B

"B"

IQR_FRODOKEM_976_CSHAKE

KYBER

You can 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 24. KYBER Parameter Sets
EVP_PKEY_CTRL_KYBER_PARAMETER_SET "parameter_set" Radiate Variant

KYBER_PARAMETER_SET_A

"A"

IQR_KYBER_768

KYBER_PARAMETER_SET_B

"B"

IQR_KYBER_1024

SIKE

u can 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 25. SIKE Parameter Sets
EVP_PKEY_CTRL_SIKE_PARAMETER_SET "parameter_set" Radiate Variant

SIKE_PARAMETER_SET_A

"A"

IQR_SIKE_P503

SIKE_PARAMETER_SET_B

"B"

IQR_SIKE_P751

DILITHIUM

You can 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 26. Dilithium Parameter Sets
"parameter_set" Radiate Variant

"A"

IQR_DILITHIUM_128

"B"

IQR_DILITHIUM_160

HSS

You can use the following options when 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 27. HSS Signing Operations
"sign_operations"

"2E30"

"2E45"

"2E65"

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

Table 28. HSS Optimization
"optimization"

"fast"

"small"

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

Table 29. HSS Tree Strategy
"strategy"

"cpu_constrained"

"memory_constrained"

"full"

You can call EVP_PKEY_CTX_ctrl_str() with "state_filename" 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.

RAINBOW

You can 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 30. RAINBOW Parameter Sets
"parameter_set" Radiate Variant

"A"

IQR_RAINBOW_GF31_64_32_48

"B"

IQR_RAINBOW_GF256_68_36_36

"C"

IQR_RAINBOW_GF16_56_48_48

"D"

IQR_RAINBOW_GF256_92_48_48

"E"

IQR_RAINBOW_GF16_76_64_64

"F"

IQR_RAINBOW_GF31_84_56_56

SPHINCS

You can 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 31. SPHINCS Parameter Sets
"parameter_set" Radiate Variant

"A"

IQR_SPHINCS_SHAKE_256_192S

"B"

IQR_SPHINCS_SHAKE_256_192F

"C"

IQR_SPHINCS_SHAKE_256_256S

"D"

IQR_SPHINCS_SHAKE_256_256F

XMSS

You can 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 32. XMSS Tree Height
"tree_height"

"10"

"16"

"20"

You can 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 33. XMSS Tree Strategy
"strategy"

"cpu_constrained"

"memory_constrained"

"full"

You can call EVP_PKEY_CTX_ctrl_str() with "state_filename" 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 can call EVP_PKEY_CTX_ctrl_str() with "tree_height" and then "tree_layers" to specify the tree height and layers when generating a key. Only the following combinations are valid:

Table 34. 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 can 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 35. XMSSMT Tree Strategy
"strategy"

"cpu_constrained"

"memory_constrained"

"full"

You can call EVP_PKEY_CTX_ctrl_str() with "state_filename" 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

The libssl library maintains its own list of ciphersuites in priority order. The client and server negotiate a common ciphersuite based on their priorities. You can see that list by using the ciphers command.

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.0.2/ssl/SSL_get_ciphers.html

To use a specific ciphersuite:

  • 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.0.2/ssl/SSL_CONF_cmd.html. SSL_CTX_set_cipher_list() and SSL_set_cipher_list() are documented at https://www.openssl.org/docs/man1.0.2/ssl/SSL_CTX_set_cipher_list.html .

Special Note on Stateful Hash-Based Signature Schemes

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 challenges. As such, these are only used for roots of trust and intermediate CA certificates within the X.509 certificate chain.

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 privQSExtend.py, reqQSExtend or x509QSDirectExtend.

In most cases, the dual private key can optionally be used instead of the original private key since the alternative key in the dual private key file will simply be ignored. However, s_server and s_client are notable exceptions. They will only accept a single private key file. If a Catalyst quantum-safe TLS connection is being negotiated, the dual private key 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 OpenSSL Connector 2.0 QS Certificate Tutorial.

The ISARA Catalyst OpenSSL Connector Binaries are licensed for use:

Copyright © 2017-2019, 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 OpenSSL Connector (ID GITCOMIT)

  • ISARA Radiate Security Solution Suite (ID ``)