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 thedemos_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 theTLS_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.
-
ISARA website (https://www.isara.com)
-
ISARA Radiate OpenSSL Connector Documentation (https://www.isara.com/openssl/1/)
-
ISARA Support email (support@isara.com)
-
+1-877-319-8576 Toll-free (Please refer to your support contract.)
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 onlms_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
andreq
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/
-
Unpack the OpenSSL source.
-
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:
-
Configure OpenSSL. See the relevant
INSTALL
file in the OpenSSL directory for more information. For example:./Configure shared <OPENSSL_CONFIGURATION>
NOTE: You must useshared
for dynamic engine support. -
Execute
make depend
-
Execute
make all
-
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. -
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 indemos_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:
Application | NHF | SIDH | MCQ | Kyber | NTRUP | LMS | Dilithium | Rainbow | NextID |
---|---|---|---|---|---|---|---|---|---|
|
✓ |
✓ |
✓ |
||||||
|
✓ |
✓ |
✓ |
||||||
|
✓ |
✓ |
✓ |
||||||
|
✓ |
✓ |
✓ |
✓ |
✓ |
||||
|
✓ |
✓ |
✓ |
✓ |
✓ |
✓ |
|||
|
✓ |
✓ |
✓ |
✓ |
✓ |
✓ |
|||
|
✓ |
✓ |
✓ |
||||||
|
✓ |
✓ |
✓ |
✓ |
|||||
|
✓ |
✓ |
✓ |
✓ |
✓ |
||||
|
✓ |
✓ |
✓ |
✓ |
✓ |
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
:
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
:
w |
Winternitz Value |
---|---|
0 |
1 |
1 |
2 |
2 |
4 |
3 |
8 |
Use one of these values for h
:
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
:
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:
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.
Algorithm | EVP_PKEY_asn1_find_str() |
EVP_PKEY_CTX_new_id() |
---|---|---|
LMS |
"LMS" |
|
Rainbow |
"Rainbow" |
|
Dilithium |
"Dilithium" |
|
QC-MDPC |
"MCQ" |
|
NTRU Prime |
"NTRUP" |
|
Kyber |
"Kyber" |
|
NewHope |
"NH" |
|
LUKE |
"LUKE" |
|
SIDH |
"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()
.
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 |
|
N/A |
LUKE Initiator |
|
N/A |
SIDH Initiator |
|
N/A |
For LMS tree height, the EVP_PKEY_CTX_ctrl_str()
will accept the ASCII
encoding of a value from 0 to 4:
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:
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:
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:
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:
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)
withcmd
set to "cipher" andvalue
set to one of the strings from theciphers
command. -
Use
SSL_CTX_set_cipher_list(SSL_CTX *ctx, const char *str)
withstr
set to one of the strings from theciphers
command. -
Use
SSL_set_cipher_list(SSL *ssl, const char *str)
withstr
set to one of the strings from theciphers
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.
Legal
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
)