Introduction

The ISARA Radiate OpenSSL Connector lets you implement OpenSSL using the algorithms provided in the ISARA Radiate Security Solution Suite. ISARA Radiate gives you the cryptographic building blocks to create applications that will resist attacks by quantum computers.

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

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

Version 1.3 of the ISARA Radiate OpenSSL Connector package contains:

  • Documentation and diagrams about the ISARA Radiate 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 Radiate OpenSSL Engine built using OpenSSL and the ISARA Radiate Security Solution Suite.

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

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

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

  • OpenSSL-1.0.2k

  • OpenSSL-1.0.2l

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

The User’s Guide covers the following topics:

Packaging

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

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

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

  • OpenSSL-Connector-MPKAC-Tutorial.html — Information about how to create and verify multiple public key algorithm certificates.

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

    • OpenSSL-1.0.2k

    • OpenSSL-1.0.2l

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

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

  • 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 Radiate Security Solution Suite documentation is available on https://www.isara.com. The ISARA Radiate Security Solution Suite Developer’s Guide provides more insights into the meaning of the parameters and has references to algorithm specifications.

For more details and requirements, please refer to the ISARA Radiate Security Solution Suite 1.3 Developer’s Guide.

Introduction to ISARA’s Algorithms

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

  • Key Exchange Schemes

    • NewHope Family of Key Exchange Variants (NHF):

      • Reference NewHope (NH)

      • Lattice-based Unique Key Exchange (LUKE), an ISARA Proprietary Algorithm

    • Supersingular Isogeny Diffie-Hellman Key Exchange (SIDH)

  • Key Encapsulation Mechanisms

    • McEliece with Quasi-Cyclic Moderate Density Parity-Check Code KEM (MCQ)

    • Kyber Lattice-Based KEM

    • NTRU Prime Lattice-Based KEM (NTRUP)

  • Signature Schemes

    • Leighton-Micali Signature Scheme (LMS)

    • Dilithium Lattice-Based Signature Scheme

    • Rainbow Multivariate Signature Scheme

Note
The abbreviations in parentheses above are not the official algorithm abbreviations. They are the compact names of the algorithms used in the code of the ISARA Radiate OpenSSL Connector.

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

  • LMS keys can only produce a specific number of signatures. The total number of signatures available to an LMS private key depends on parameter selection.

  • LMS private keys require special care during the signing operation. A new pkey option called lms_index must be set to a unique OTS index. Please see our special note on lms_index 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 LMS because that would use up 2 OTSs which is undesirable. Both the x509 and req commands can be used to directly create a root certificate thereby only using 1 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 establishment algorithms require that the participants know whether their identity (for example, initiator, responder, Alice, Bob) which is different from Diffie-Hellman requirements.

  • All our signature schemes (LMS, Rainbow, Dilithium) only accept 512 bit (64 byte) digests as input for security reasons. This may be different from other implementations of these signature algorithms.

  • Our new X.509 multiple public key algorithm certificates (see Special Note on Multiple Public Key Algorithm Certificates) will have 2 private keys associated with each certificate. This is not compatible with the PKCS12_parse() API which can only return a single private key per certificate.

Applying the ISARA Radiate OpenSSL Connector Patch to OpenSSL

The ISARA Radiate OpenSSL Connector is supplied as a patch to OpenSSL. 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:

  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. Build the demo applications. Each source file in the demos directory is its own self-contained application. The ISARA Radiate OpenSSL Connector uses the following compiler and linker flags to build these applications: -O3 -DNDEBUG -rdynamic -lcrypto. Your system might require different parameters.

  5. Run the ISARA Radiate 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 Radiate 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 Algorithms By Application
Application NHF SIDH MCQ Kyber NTRUP LMS Dilithium Rainbow NextID

req

x509

verify

cms

genpkey

pkey

pkeyutl

ciphers

s_server

s_client

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.

Key Exchange Protocols

As NewHope, LUKE and SIDH are specifically designed for ephemeral key exchange, they are only used in the s_server and s_client applications that run the TLS protocols and the ciphers application that shows the name of the ciphersuites.

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 in the first place. The ISARA Radiate OpenSSL Connector package includes a simple demo of how to use these algorithms. See openssl_nh_with_asn1.c.

Note
The ciphers application lists all supported ciphersuites. To try one of the ISARA Radiate 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.

McEliece with Quasi-Cyclic Moderate Density Parity-Check Code KEM

If the application has an -algorithm parameter, you can specify QC-MDPC with -algorithm MCQ

Kyber Lattice-Based KEM

If the application has an -algorithm parameter, you can specify Kyber with -algorithm kyber

You can use the following option when generating a key pair to specify the QS Security Level:

  • -pkeyopt qs_security_level:l

Use one of these values for l:

Table 2. Kyber Security Levels
l QS Security Levels

0

KYBER_QS_SECURITY_LEVEL_128

1

KYBER_QS_SECURITY_LEVEL_224

NTRU Prime Lattice-Based KEM

If the application has an -algorithm parameter, you can specify NTRU Prime with -algorithm NTRUP

Leighton-Micali Signature Scheme

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

You can use the following options when generating a key pair to specify the Winternitz value and tree height:

  • -pkeyopt winternitz_value:w

  • -pkeyopt tree_height:h

Use one of these values for w:

Table 3. LMS Winternitz Values
w Winternitz Value

0

1

1

2

2

4

3

8

Use one of these values for h:

Table 4. LMS Tree Height Values
h Tree Height OTS Keys

0

5

32

1

10

1024

2

15

32768

3

20

1048576

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

For any applications that perform signing operations, you can use one of the following options to specify the LMS index depending on which application it is:

  • -pkeyopt lms_index:i

  • -sigopt lms_index:i

The possible values of i, also known as the lms_index, depends on the tree height parameter specified when the private key was generated. The lms_index value specifies the index of the OTS to use. For example, if a private key was generated with the h parameter set to 1, then the tree height would be 10 and the number of OTS keys available would be 1024. These keys are zero indexed so lms_index could be any value from 0 to 1023. Note that each possible value of the lms_index must only be used once to generate a signature. Using it multiple times would constitute a security problem.

Dilithium Lattice-Based Signature Scheme

If the application has an -algorithm parameter, you can specify Dilithium with -algorithm dilithium

You can use the following option when generating a key pair to specify the QS Security Level:

  • -pkeyopt qs_security_level:l

Use one of these values for l:

Table 5. Dilithium Security Levels
l QS Security Levels

0

DILITHIUM_QS_SECURITY_LEVEL_128

1

DILITHIUM_QS_SECURITY_LEVEL_160

Rainbow Multivariate Signature Scheme

If the application has an -algorithm parameter, you can specify Rainbow with -algorithm rainbow

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

LMS

Rainbow

Dilithium

QC-MDPC

NTRU Prime

Kyber

NewHope Variants

SIDH

Note
These API names have been shortened and simplified. For example, Derive refers to EVP_PKEY_derive_init() and EVP_PKEY_derive().

Loading the Engine

You must load the ISARA Radiate 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 Radiate 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 algorithms and their associated strings and constants. When using these strings, case is not an issue.

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

LMS

"LMS"

EVP_PKEY_LMS

Rainbow

"Rainbow"

EVP_PKEY_RAINBOW

Dilithium

"Dilithium"

EVP_PKEY_DILITHIUM

QC-MDPC

"MCQ"

EVP_PKEY_MCQ

NTRU Prime

"NTRUP"

EVP_PKEY_NTRUP

Kyber

"Kyber"

EVP_PKEY_KYBER

NewHope

"NH"

EVP_PKEY_NH

LUKE

"LUKE"

EVP_PKEY_LUKE

SIDH

"SIDH"

EVP_PKEY_SIDH

Setting Parameters

Each algorithm requires different parameters.

For LMS, there are winternitz_value, tree_height and lms_index.

For NewHope (NH), LUKE and SIDH the parameter specifies whether the participant is the initiator or responder.

For Kyber and Dilithium there is "qs_security_level".

These parameters can be set using EVP_PKEY_CTX_ctrl() or EVP_PKEY_CTX_ctrl_str().

Table 8. Parameter Names
Parameter EVP_PKEY_CTX_ctrl() EVP_PKEY_CTX_ctrl_str()

LMS Tree Height

N/A

"tree_height"

LMS Winternitz Value

N/A

"winternitz_value"

LMS OTS Index

N/A

"lms_index"

Dilithium QS Security Level

N/A

"qs_security_level"

Kyber QS Security Level

N/A

"qs_security_level"

NH Initiator

EVP_PKEY_CTRL_NHF_PARAMSET

N/A

LUKE Initiator

EVP_PKEY_CTRL_NHF_PARAMSET

N/A

SIDH Initiator

EVP_PKEY_CTRL_SIDH_PARAMSET

N/A

For LMS tree height, the EVP_PKEY_CTX_ctrl_str() will accept the ASCII encoding of a value from 0 to 4:

Table 9. LMS Values for Tree Height
Value Tree Height OTS Keys

"0"

5

32

"1"

10

1024

"2"

15

32768

"3"

20

1048576

For LMS Winternitz value, the EVP_PKEY_CTX_ctrl_str() will accept the ASCII encoding of a value from 0 to 3:

Table 10. LMS Values for Winternitz Value
Value Winternitz Value

"0"

1

"1"

2

"2"

4

"3"

8

The possible values of lms_index depends on the tree height parameter specified when the private key was generated. The lms_index value specifies the index of the OTS to use. For example, if a private key was generated with the tree_height parameter set to 1, then the tree height would be 10 and the number of OTS keys would be 1024. These keys are zero indexed so lms_index could be any value from 0 to 1023. Note that each possible value of the lms_index must only be used once to generate a signature. Using it multiple times would constitute a security problem.

For the Dilithium Signature Scheme’s QS security level, the EVP_PKEY_CTX_ctrl_str() will accept the ASCII encoding of a value of 0 or 1:

Table 11. Dilithium Values for QS Security Level
Value QS Security Level

"0"

DILITHIUM_QS_SECURITY_LEVEL_128

"1"

DILITHIUM_QS_SECURITY_LEVEL_160

For the Kyber KEM’s QS security level, the EVP_PKEY_CTX_ctrl_str() will accept the ASCII encoding of a value of 0 or 1:

Table 12. Kyber Values for QS Security Level
Value QS Security Level

"0"

KYBER_QS_SECURITY_LEVEL_128

"1"

KYBER_QS_SECURITY_LEVEL_224

For the NewHope Family and SIDH, EVP_PKEY_CTX_ctrl() accepts an integer with the following values:

Table 13. NewHope Family and SIDH Initiator Values
Value Description

0

I am the Responder.

1

I am the Initiator.

Special Note on our KEMs

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. We expose them via CMS as key agreement. They are more appropriate for this as they involve static public and private keys.

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 LMS

Due to the dynamic nature of the LMS private keys, LMS is not appropriate for real-time signing of challenges. As such, LMS is only used for roots of trust and intermediate CA certificates within the X.509 certificate chain.

Special Note on Multiple Public Key Algorithm Certificates

We have developed multiple public key algorithm certificates as a means of easing the transition to QS algorithms for larger organizations with complex infrastructures. We have created a tutorial document on how to create and use these kinds of certificates. Please see ISARA Radiate OpenSSL Connector 1.3 QS Multiple Public Key Algorithm Certificate Tutorial.

The ISARA Radiate OpenSSL Connector Binaries are licensed for use:

Copyright © 2017, 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 Radiate OpenSSL Connector (ID 556a4b8d323732849d6ca74b882d64f363559530)

  • ISARA Radiate Security Solution Suite (ID 33a63cc52c72976bc5f64ecfe07115f1e8112d49)