ISARA Catalyst OpenSSL Connector 2.0 User’s Guide

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

These algorithms are specifically designed for ephemeral key exchange. They are only used in the s_server, s_client and demo applications that run the TLS protocol. They are also featured in the ciphers application that shows the name of the 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 OpenSSL Connector package includes simple demos of how to use these algorithms. See openssl_*_with_asn1.c.

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

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

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

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.

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:

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:

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:

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:

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:

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:

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

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

Use one of these values for h:

Use one of these values for s:

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

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

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

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

Use one of these combinations for h and l:

Use one of these values for s:

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

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

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

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

Use one of these values for so:

Use one of these values for o:

Use one of these values for s:

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

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

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:

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:

The following new applications were created to support Catalyst Certificats, Catalyst CSRs and Dual Private Keys.

See ISARA Catalyst OpenSSL Connector 2.0 QS Certificate Tutorial for an in-depth explanation of these applications.

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

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

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

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

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.

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

You can 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:

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

You can 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:

You can 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:

You can 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:

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

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

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

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

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

NTRUP has no parameters to set.

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

You can 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:

You can 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:

You can 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:

You can 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:

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

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

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

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

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

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

You can call EVP_PKEY_CTX_ctrl_str() with "tree_height" and then "tree_layers" to specify the tree height and layers when generating a key. Only the following combinations are valid:

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

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

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 classical cipher suites supported by OpenSSL. They are assigned from the IANA private range and are only compatible with other ISARA TLS implementations. The following is the list of all supported quantum-safe cipher suites in priority order from highest to lowest.

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.

As shown in the cipher suites above, the following quantum-safe algorithms are supported.
Key exchange: 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.

You can see the complete list of cipher suites 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 cipher suite:

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.

The libssl library provides a list of public functions to set and get parameters for quantum-safe key exchange algorithms used during a TLS handshake.

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 roots 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 for TLS peer 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 with Catalyst employs a similar mechanism as that of server authentication, except that 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.

The ISARA Catalyst OpenSSL Connector Binaries are licensed for use:

Copyright © 2017-2020, 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.