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 thecrypto_demo_script.txt
-
crypto_demo_data/
— Configuration and output files for thecrypto_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 thetls12_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 thedtls12_demo_script.txt
-
tls_demo_data/
— Configuration and output files for thetls12_demo_script.txt
, anddtls12_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.
-
ISARA website (https://www.isara.com)
-
ISARA Catalyst Connector documentation (https://www.isara.com/openssl/2/)
-
ISARA Support email (support@isara.com)
-
+1-877-319-8576 Toll-free (Refer to your support contract.)
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 calledstate_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
andreq
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, theopenssl 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/
-
Unpack the OpenSSL source.
-
Copy the patch from where you unpacked the package into the newly created OpenSSL directory.
-
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:
-
Configure OpenSSL. See the relevant
INSTALL
file in the OpenSSL directory for more information. For example:./Configure shared <OPENSSL_CONFIGURATION>
NoteYou must use shared
for dynamic engine support because the engine calls APIs inlibcrypto
and thus requires the symbols in the shared library for dynamic linking. For Linux, when your applications are executed, they might need theLD_LIBRARY_PATH
environment variable set to specify the location of thelibcrypto.so
,libssl.so
, andlibiqr_toolkit.so
library files. For Darwin, the environment variable is calledDYLD_LIBRARY_PATH
. See thecrypto_demo_script.txt
file for an example of how to do this. -
Execute
make all
-
Execute
make test
(This step is optional.) -
Build the demo applications. Each
.c
file in thedemos
directory is a demo application, exceptopenssl_tls.c
.openssl_tls_server_1_2.c
,openssl_tls_client_1_2.c
, openssl_dtls_server_1_2.c` andopenssl_dtls_client_1_2.c
share code inopenssl_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 aMakefile.example
file to help you build the demo applications. -
Run the ISARA Catalyst Connector crypto demos and the OpenSSL standard utilities as shown in
crypto_demo_script.txt
and TLS demos as shown intls12_demo_script.txt
anddtls12_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 thecrypto_demo_data
andtls_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:
-
Configure OpenSSL. See the relevant
INSTALL
file in the OpenSSL directory for more information. For example:perl configure VC-WIN64A
NoteRun the following ms/nmake commands from a VC++ x64 environment. This can be done by running VCVARSALL x64
from the command prompt. -
Execute
nmake
-
Execute
nmake test
-
Execute
nmake install
-
Build the demo applications. Each
.c
file in thedemos
directory is a demo application, exceptopenssl_tls.c
.openssl_tls_server_1_2.c
,openssl_tls_client_1_2.c
,openssl_dtls_server_1_2.c
andopenssl_dtls_client_1_2.c
share code inopenssl_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 aMakefile.example
file to help you build the demo applications. Edit the the file to enable the windows specificLIBS
andLDFLAGS
variables. Executecd demos; `nmake -f Makefile.example all
-
Run the ISARA Catalyst Connector crypto demos and the OpenSSL standard utilities as shown in
crypto_demo_script.txt
and TLS demos as shown inTLS_demo_script.txt
to see if you get similar console output to what is shown incrypto_demos_script_expected_output.txt
andTLS_demos_script_expected_output.txt
and similar output files in thecrypto_demo_data
andtls_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:
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:
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:
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:
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:
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:
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:
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:
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
:
h |
---|
10 |
16 |
20 |
Use one of these values for s
:
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
:
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
:
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
:
so |
---|
2E15 |
2E20 |
2E30 |
2E45 |
2E65 |
Use one of these values for o
:
o |
---|
fast |
small |
Use one of these values for s
:
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:
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:
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:
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.
Algorithm | EVP_PKEY_asn1_find_str() |
EVP_PKEY_CTX_new_id() |
---|---|---|
FRODODH |
frododh |
|
NHDH |
nhdh |
|
SAMWISE |
samwise |
|
SIDH |
sidh |
|
CMC |
cmc |
|
FRODOKEM |
frodokem |
|
KYBER |
kyber |
|
NTRUP |
ntrup |
|
SABER |
saber |
|
SIKE |
sike |
|
DILITHIUM |
dilithium |
|
HSS |
hss |
|
RAINBOW |
rainbow |
|
SPHINCS |
sphincs |
|
XMSS |
xmss |
|
XMSSMT |
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:
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:
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:
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:
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:
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:
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:
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:
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:
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:
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:
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:
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:
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:
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:
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:
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:
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:
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:
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:
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:
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:
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:
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:
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)
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.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.
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
ands_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 ofBIO_free()
to freeindata
. This is required because in order to support intrinsic signing we had to add a specialBIO
to the BIO chain to fully buffer the message data. UsingBIO_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.
Legal
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
)