Introduction
The ISARA Catalyst™ Connector for OpenSSL lets you use the authentication algorithms provided in the ISARA Radiate™ Security Solution Suite to create:
-
Catalyst certificates
-
PKCS10 Catalyst certificate signing requests
-
Dual private key files
-
CMS messages that are verifiable using embedded Catalyst certificates
-
PKCS12 files with Catalyst certificates and associated dual private keys
For more information about ISARA quantum-safe solutions, visit https://www.isara.com.
This tutorial assumes that you are already familiar with X.509 certificates, certificate signing requests, and OpenSSL, and have extensive experience with them.
One of the design goals of the ISARA Catalyst certificate scheme is to make sure that integration into pre-existing systems is simple. This can be seen in the newly added utilities and APIs.
ISARA created minimalist utilities that transform already existing certificate signing requests, X.509 certificates, certificate revocation lists and PKCS12 files into their Catalyst variants. This means that if you already have scripts and infrastructure in place, you should not need to change any of your pre-existing commands, only add new ones. This also means that if you have created applications or libraries that use OpenSSL, you can begin integration by only inserting code and not changing your pre-existing code. This is potentially inefficient, but eases your prototyping. As efficiency becomes a priority, you can begin removing redundancies.
The architecture for ISARA Catalyst cryptographic artifacts is limited to creating and inserting attributes and extensions into the cryptographic artifacts mentioned above. Since OpenSSL already provides APIs for doing these operations to attributes and extensions, the only new additions to the OpenSSL API that are related to Catalyst certificates are for ASN.1 encoding and decoding of these new attributes and extensions. Details of how to use these new additions can be found in the Programmer’s Guide To Catalyst Certificates section below.
An important feature of Catalyst cryptographic artifacts is that they are backwards compatible with systems that are not aware of the Catalyst extensions. In situations where the system does not understand Catalyst extensions, those extensions will be ignored and the artifacts will be processed in the usual manor.
This Catalyst Certificate Tutorial covers the following topics:
Introduction to the Authentication Schemes
The ISARA Catalyst Connector adds the following quantum-safe authentication schemes to OpenSSL:
-
Quantum-Safe Stateful Hash-Based Signature Schemes
-
Hierarchical Signature Scheme (HSS)
-
eXtended Merkle Signature Scheme (XMSS)
-
eXtended Merkle Signature Scheme - Multi-Tree (XMSSMT)
-
-
Quantum-Safe Signature Schemes
-
Dilithium Lattice Based Signature Scheme (DILITHIUM)
-
Rainbow Multivariate Signature Scheme (RAINBOW)
-
SPHINCS+ Signature Scheme. (SPHINCS)
-
Note
|
The names in parentheses above are not official algorithm names. They are compact names of the algorithms used in the code of the ISARA Catalyst Connector. |
Many of the algorithms' details are abstracted via the EVP PKEY API. For more information, see ISARA Catalyst Connector 2.1 for OpenSSL Developer’s Guide.
This document has several diagrams. The following is a legend of the various artifacts in the diagrams.

Caveats
-
Stateful hash-based signature scheme private keys can only produce a specific number of signatures. The total number of signatures available to such a private key depends on parameter selection.
-
Stateful hash based signature scheme private keys require special care during the signing operation. A new pkey option called
state_filename
must be set to a file name that can be created. This is discussed below, but for more details, see the ISARA Catalyst Connector 2.1 for OpenSSL User’s Guide. -
All the newly addded signature schemes only perform intrinsic signing. No pre-hashing is expected.
-
Each Catalyst certificate will have a dual private key file associated with it.
Introduction to Conventional X.509 Certificates, Certificate Signing Requests and Certificate Revocation Lists

A detailed discussion of X.509 certificates and PKCS10 certificate signing requests is outside the scope of this document. More details about X.509 certifcates can be found in RFC-5280. More details about PKCS10 certificate signing requests can be found in RFC-2986.
Generally speaking, each X.509 certificate must contain a subject identifier, a public key, a signature algorithm identifier, and a signature. The main purpose of the certificate is to bind the subject that is identified by the subject identifier to the public key that is in the certificate. This binding is certified by having a "trusted" third party sign the certificate with their private key and add that signature into the certificate. The third party then publishes their public key to let anyone verify the signature in the certificate. How does the third party gain their status as "trusted"? The simplest way is to publish their public key in a certificate that was signed by another "actually trusted" third party. How a third party gains the status of "actually trusted" is beyond the scope of this document.
The "actually trusted" third parties distribute their certificates as self-signed certificates. That is, the private key that signs the certificate is the one that corresponds to the public key in the certificate. These are known as root certificates.
Thus you could have a chain of certificates where each certificate is signed by another subject, called the issuer, and verifiable by the public key in the issuer’s certificate. If the top of this chain is a root certificate whose subject is "actually trusted" then you would say that all certificates in that chain are trusted subject to other conditions of validity.
An issuer must bind the subject identified by the subject identifier to the public key. This is done by having the subject create a certificate signing request. Generally speaking, to prove possession of the private key, each certificate signing request must contain a subject identifier, a public key, a signature algorithm identifier and signature where the signature was created by the public key’s corresponding private key. The subject sends the issuer the certificate signing request and the issuer verifies the signature. The issuer can then create a certificate containing the subject identifier and public key from the certificate signing request and sign that certificate with their private key and attach that signature to the newly created certificate.
As the name suggests, a certificate revocation list is a list of revoked certificates. This list is signed by the issuer of the revoked certificates.
Introduction to Catalyst Certificates, Certificate Signing Requests and Certificate Revocation Lists

Each X.509 certificate contains a public key, a signature algorithm identifier, and a signature. As specified in RFC-5280, X.509 certificates may contain extensions. Catalyst certificates are simply X.509 certificates that contain newly defined extensions with a subject alternative public key, an alternative signature algorithm identifier, and an alternative signature. These all mirror the original formats and purposes from normal X.509 certificates.
Each certificate signing request contains a public key, a signature algorithm identifier, and a signature. As specified in RFC-2986, certificate signing requests may contain attributes. Catalyst certificate signing requests are simply certificate signing requests with newly defined attributes that contain a subject alternative public key, an alternative signature algorithm identifier, and an alternative signature. These all mirror the original formats and purposes from normal certificate signing requests.
Each certificate revocation list contains a signature algorithm identifier and a signature. As specified in RFC-5280, certificate revocation lists may contain extensions. Catalyst certificate revocation lists are simply certificate revocation lists that contain an alternative signature algorithm identifier and an alternative signature. These all mirror the original formats and purposes from normal certificate revocation lists.
Introduction to Catalyst CMS Messages and Dual Private Key Files
Each signed Cryptographical Messaging Syntax (CMS) message contains at least one X.509 certificate and at least one SignerInfo structure as specified in RFC-5280. SignerInfo structures may contain unsigned attributes. Catalyst CMS messages are simply messages with a Catalyst certificate and a SignerInfo structure that contains an attribute that contains an alternative signature algorithm identifier and an attribute that contains an alternative signature. The signature resulted from signing the CMS message.
A PKCS8 private key file contains the ASN.1 encoding of a private key as specified in RFC-5208. When PEM encoded, the beginning of the private key is marked with one of the following markers:
-----BEGIN PRIVATE KEY-----
-----BEGIN ENCRYPTED PRIVATE KEY-----
The end of the private key is marked with one of the following markers:
-----END PRIVATE KEY-----
-----END ENCRYPTED PRIVATE KEY-----
A dual private key file has an alternative PKCS8 private key directly after the end marker above. The beginning of the alternative private key is marked with one of the following markers:
-----BEGIN ALT PRIVATE KEY-----
-----BEGIN ENCRYPTED ALT PRIVATE KEY-----
The end of the alternative private key is marked with one of the following markers:
-----END ALT PRIVATE KEY-----
-----END ENCRYPTED ALT PRIVATE KEY-----
The first private key is associated with the subject public key. The alternative private key is associated with the subject alternative public key.
Some of the new AltExtend applications also automatically merge the conventional and alternative private key files for your convenience. ISARA Catalyst Connector 2.1 also provides two new utilities:
-
privAltExtend.py
-
Extend two conventional private keys into a dual private key. Note that this utility simply concatenates and changes the header and footer of the alternative private key. It is the responsibility of the user to ensure that both private keys are either unencrypted or encrypted under the same password.
-
-
privAltSplit.py
-
Split a dual private key into two conventional private keys.
-
A PKCS12 file contains various cryptographic artifacts. The original pkcs12
application that comes with OpenSSL only supports creating such files with
a single X.509 certificate and private key. Dual private key PKCS12 files
include the alternative private key as well.
Introduction to the New Utilities
ISARA Catalyst Connector 2.1 provides a utility called
reqAltExtend
that transforms a certificate signing request into its Catalyst
variant and produces a dual private key file.
ISARA Catalyst Connector 2.1 provides two different
utilities to transform an X.509 certificate into a Catalyst certificate. The
first utility is called x509AltDirectExtend
. This utility is meant for
transforming self-signed root certificates or quickly transforming
experimental certificates directly into its Catalyst variant; no certificate
signing request is required. The second utility is called x509AltExtend
and
uses a Catalyst certificate signing request to transform an X.509 certificate
into its Catalyst variant.
ISARA Catalyst Connector 2.1 provides a utility
called x509AltVerify
that performs verification of the alternative signatures
in the certificates given a Catalyst certificate chain.
ISARA Catalyst Connector 2.1 provides a utility
called crlAltExtend
that transforms a CRL into its Catalyst variant.
It does this by creating alternative signature algorithm and alternative
signature value extensions and inserting them into the CRL.
ISARA Catalyst Connector 2.1 provides a utility
called crlAltVerify
that performs verification of the alternative
signature in a CRL’s extensions.
ISARA Catalyst Connector 2.1 provides a utility
called cmsAltExtend
that transforms a CMS message into its Catalyst variant.
It does this by creating alternative signature algorithm and alternative
signature value attributes and inserting them into the SignerInfo’s unsigned
attributes.
ISARA Catalyst Connector 2.1 provides a utility
called cmsAltVerify
that performs verification of the alternative signature in
a CMS message’s SignerInfo’s unsigned attributes.
ISARA Catalyst Connector 2.1 provides a utility
called pkcs12AltExtend
that adds a new alternative private key into a
pre-existing PKCS12 file that already contains a Catalyst certificate and
conventional private key.
For the utilities that accept quantum-safe private keys as input to create
alternative signatures, ISARA Catalyst Connector 2.1 always
accepts the optional -privalt_engine
parameter. This specifies that the private
key should be loaded by the engine and is only appropriate for stateful hash
based signature schemes. This is required to let you append the state file name
to the private key flle name. If the private key is not for a stateful
hash-based signature scheme, (i.e., Dilithium) the utility will return an error.
For the utilities that accept private keys as input to create signatures, use
the optional -passin arg
and -passinalt arg
parameters. These
specify the key password source. For more information about the format of arg
,
see the PASS PHRASE ARGUMENTS section at
openssl.
reqAltExtend

This utility transforms a previously generated certificate signing request into a Catalyst certificate signing request by:
-
adding a subject alternative public key attribute to the request based on the alternative public key.
-
adding an alternative signature algorithm attribute to the request based on the alternative private key.
-
adding an alternative signature attribute to the request based on the alternative private key.
-
creating a dual private key based on the conventional and alternative private keys. If a cipher is specified, the conventional and alternative private keys will both be encrypted with the same algorithm and password. If no cipher is specified, neither of the keys will be encrypted.
The first two attributes are inserted into the certificate signing request. The alternative signature attribute is then generated by signing the certificate signing request and adding it in. The certificate signing request is then re-signed with the conventional private key. Finally, the alternative private key file is replaced with the dual private key.
x509AltDirectExtend
This utility transforms a previously generated X.509 certificate into a Catalyst certificate by:
-
adding a subject alternative public key extension to the certificate based on the alternative public key.
-
adding an alternative signature algorithm extension based on the alternative private key
-
adding an alternative signature extension based on the alternative private key
-
creating a dual private key based on the conventional and alternative private keys. If a cipher is specified, the conventional and alternative private keys will both be encrypted with the same algorithm and password. If no cipher is specified, neither of the keys will be encrypted.
The first two extensions are inserted into the certificate. Then the alternative signature is generated and transformed into an alternative signature extension and added to the certificate. The X.509 certificate is signed with the conventional private key. Finally, the alternative private key file is replaced with the dual private key.

If you are using this utility because you want to transform a self-signed root
certificate, you may not want to bother producing a separate public key file.
In that case, you can use the -self_sign
flag to specify that the public key
should be found in the file specified by -privalt
. If you use the -self_sign
flag you must not use the -pubalt
flag; doing so will generate an error.

If you are using this utility because you want to quickly create an experimental
X.509 certificate skipping the step of creating a certificate signing request,
then you must use the -pubalt
flag and not use the -self_sign
flag; doing
so will generate an error.
x509AltExtend

This utility combines a previously generated X.509 certificate and Catalyst certificate signing request into a Catalyst certificate by:
-
adding a subject alternative public key extension to the certificate based on the alternative public key in the PKCS10 certificate signing request.
-
adding an alternative signature algorithm extension based on the alternative private key
-
adding an alternative signature extension based on the alternative private key
The first two extensions are inserted into the certificate. Then the alternative signature is generated with the alternative private key, transformed into an alternative signature extension and added to the certificate. The certificate is then re-signed with the conventional private key.
x509AltVerify

This utility primarily shows how to perform alternative signature verification
of Catalyst certificate chains. It is important to note that this utility does
not do verification of the conventional signatures in the Catalyst certificates
in the chain and only checks the validity of the alternative signatures in the
chain. However, the vanilla openssl verify
utility can still function
correctly with Catalyst certificates as the new extensions are optional and will
be ignored by openssl verify
. In short, this utility was meant to complement
openssl verify
, not replace it.
Note
|
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, the openssl x509AltVerify utility
verifies trusted certificates by default. Use the -skip-trusted flag to
to skip verification of trusted certificates.
|
crlAltExtend

This utility transforms a previously generated certificate revocation list into a Catalyst certificate revocation list by:
-
adding an alternative signature algorithm extension to the certificate revocation list’s extensions. The signature algorithm is based on the alternative private key.
-
adding an alternative signature value extension to the certificate revocation list’s extensions. The signature is based on the alternative private key.
Note
|
Nothing in the API requires that encrypted private keys in the dual private key file share the same password. However, this utility expects that the conventional and alternative private keys in the dual private key file were encrypted under the same password. |
crlAltVerify
This utility primarily shows how to perform alternative signature verification
of a Catalyst certificate revocation list. It is important to note that this
utility does not do verification of the conventional signature and only
checks the validity of the signature in the alternative signature value
extension. However, the vanilla openssl crl
utility can still verify correctly
as the new attributes will be ignored by openssl crl
. In short, this utility
was meant to complement the openssl crl
utility’s verification functionality,
not replace it.
cmsAltExtend

This utility transforms a previously signed CMS Message into a Catalyst CMS message by:
-
adding an alternative signature algorithm attribute to the SignerInfo’s unsigned attributes. The signature algorithm is based on the alternative private key.
-
adding an alternative signature attribute to the SignerInfo’s unsigned attributes. The signature is based on the alternative private key.
Note that this requires that the certificate that was already embedded in the CMS message be a Catalyst certificate and the alternative public key be the one that corresponds to the alternative private key. Nothing in the API requires that encrypted private keys in the dual private key file share the same password. However, this utility expects that the conventional and alternative private keys in the dual private key file were encrypted under the same password.
cmsAltVerify
This utility primarily shows how to perform alternative signature verification
of a CMS message. It is important to note that this utility does not do
verification of the conventional signature in the CMS message’s SignerInfo and
only checks the validity of the signature in the alternative signature
attribute in the SignerInfo’s unsigned attributes. However, the vanilla
openssl cms
utility can still verify correctly as the new attributes will be
ignored by openssl cms
. In short, this utility was meant to complement the
openssl cms
utility’s verification functionality, not replace it.
pkcs12AltExtend

This utility takes a PKCS12 file that contains a Catalyst Certificate and a conventional private key and then adds an alternative private key that corresponds to the Alternative Public Key in the certificate.
Note that this requires that the certificate and conventional private key are already embedded in the PKCS12 file and the alternative public key be the one that corresponds to the alternative private key.
Programmer’s Guide To Catalyst Certificates
The following is a list of operations you might want to do in your applications related to transforming cryptographic artifacts into their Catalyst variants.
Each section begins with a description of what can be accomplished and where you can find the full source code to get more details.
Adding Alternative Attributes to CSRs
To learn how to create and add a subject alternative public key information
attribute, an alternative signature algorithm identifier attribute and an
alternative signature attribute to a certificate signing request, see
create_SAPKI_ATTRIBUTE()
, create_ALTSIGALG_ATTRIBUTE()
and
create_ALTSIG_ATTRIBUTE()
in reqAltExtend.c
.
Parsing Alternative Attributes in CSRs
To learn how to parse an X509_ATTRIBUTE
to get a
SUBJECT_ALT_PUBLIC_KEY_INFO
, see the get_SAPKI_from_ATTRIBUTE()
function in
x509AltExtend.c
.
To learn how to use the get_SAPKI_from_ATTRIBUTE()
function to obtain an
EVP_PKEY
from a Catalyst certificate signing request,
find where it is called in x509AltExtend.c
.
To learn how to parse an X509_ATTRIBUTE
to get an ASN1_BIT_STRING
which is
the actual alternative signature, see the get_ALTSIG_from_ATTRIBUTE()
function in x509AltExtend.c
.
To learn how to parse an X509_ATTRIBUTE
to get an X509_ALGOR
which is the
alternative signature algorithm identifier, see the
get_ALTSIGALG_from_ATTRIBUTE()
function in x509AltExtend.c
.
Alternative Verification of a Catalyst CSR
To learn how to use the functions above and the EVP_PKEY
that is the subject
alternative public key to verify the certificate signing request using the
alternative signature scheme, find where they are called in x509AltExtend.c
.
Adding Alternative Extensions to X.509 Certificates
To learn how to create the various alternative extensions using the
X509V3_EXT_i2d()
function. See how it is used in x509AltExtend.c
.
Parsing Alternative Extensions in X.509 Certificates
To learn how to get the subject alternative public key as an EVP_PKEY
from a
Catalyst certificate, see get_SAPKI_pubkey()
in x509AltVerify.c
.
To learn how to get the alternative signature algorithm and alternative
signature, see how X509_get_ext()
is used in x509AltVerify.c
.
Alternative Verification of a Catalyst Certificate
To learn how to write a callback function that verifies the alternative
signature in a Catalyst certificate, please see the
X509_catalyst_cert_chain_verify_cb()
function in x509_vfy.c
. This callback
would be passed into OpenSSL via X509_STORE_set_verify()
.
Adding Alternative Signatures to a CRL
To learn how to create the various alternative extensions using the
X509V3_EXT_i2d()
function. See how it is used in crlAltExtend.c
.
Verifying Alternative Signatures in a CRL
To learn how to get the alternative signature algorithm and alternative
signature, see how X509_CRL_get_ext()
is used in crlAltVerify.c
.
To learn how to verify the alternative signature, see how
X509_CRL_pretbs_verify()
is used in crlAltVerify.c
.
Adding Alternative Signatures to a CMS Message
To learn how to create a SignerInfo to add the alternative signature algorithm
attribute and alternative signature attribute, see how
CMS_SignerInfo_set1_altpriv()
is used in cmsAltExtend.c
and how it is
implemented in cms_sd.c
.
Verifying Alternative Signatures in a CMS Message
To learn how the alternative signature is verified in a CMS message, see how
CMS_SignerInfo_altverify()
is used in cmsAltVerify.c and how it is implemented
in cms_sd.c
.
Adding an Alternative Private Key to a PKCS12 file
PKCS12_add_key()
is used to add the alternative private key. Note that it is
given the same "friendly name" as the conventional private key except with an
"[ALT]" marker prepended to it. It also is given the same keyID as the
conventional private key.
TLS and Catalyst Certificates
New APIs are also added to OpenSSL’s libssl library to facilitate the usage of Catalyst certificates for TLS secure handshake.
To load Catalyst certificates into the SSL context for peer authentication during TLS secure handshake, no change is needed regarding libssl API usage; existing APIs can continue to be used.
For instance, to load the end entity certificate and any accompanying intermediate CA certificates needed to form the complete certificate chain into the SSL context, for the purpose of sending them to the peer for entity authentication, the following function can be used.
int SSL_CTX_use_certificate_chain_file(SSL_CTX *ctx, const char *file);
This function loads a Catalyst certificate chain from file
into
ctx
. The certificates must be in PEM format and must be sorted starting with
the end entity certificate (actual client or server certificate), followed by
intermediate CA certificates, if any. For more details on this function, and
other similar functions, refer to OpenSSL manpages
(https://www.openssl.org/docs/man1.1.1/).
To load root CA certificates into the SSL context, for the purpose of verifying peer’s certificates, the following function can be used.
int SSL_CTX_load_verify_locations(SSL_CTX *ctx, const char *CAfile, const char *CApath);
This function loads the Catalyst certificate specified by CAfile
and/or CApath
as trusted CA certificates for ctx
. For more details on this
function, refer to OpenSSL manpages (https://www.openssl.org/docs/man1.1.1/).
To load private keys into the SSL context for operations such as digital
signature creation during TLS secure handshake, new APIs have been added to
libssl for loading alternative private keys.
Each Catalyst certificate corresponds to two private keys, the conventional private key corresponding to the public key in the subject public key info of the certificate, and the alternative private key corresponding to the subject alternative public key in the extension of the certificate.
The conventional private key can be loaded into the SSL context using existing
libssl functions such as SSL_CTX_use_PrivateKey()
. To load the alternative
private key, the following new functions are introduced.
int SSL_CTX_use_ALTPrivateKey(SSL_CTX *ctx, EVP_PKEY *pkey);
This function loads pkey
as the alternative private key to ctx
. Note that
the private key must correspond to the end entity certificate loaded into the
SSL context.
int SSL_CTX_use_ALTPrivateKey_ASN1(int type, SSL_CTX *ctx, const unsigned char *d, long len);
This function loads the alternative private key of type type
stored at memory
location d
with length len
to ctx
.
Note
|
For end entity certificates, Dilithium lattice-based signature scheme
keys can be used. Stateful hash-based signature schemes can only be used
for root and intermediate certificates; not for end entity certificates
(i.e., HSS public keys cannot be used for SubjectAltPublicKeyInfo for
an end entity certificate). This is reflected by the absence of stateful
hash-based signature schemes in the cipher suites.
|
int SSL_CTX_use_ALTPrivateKey_file(SSL_CTX *ctx, const char *file, int type);
This function loads the first private key found in file
to ctx
.
The formatting type type
must be either SSL_FILETYPE_PEM
or
SSL_FILETYPE_ASN1
.
All of the three new functions return 1 on success. Otherwise, check the error stack to find out the error reason.
For an example of how these APIs are used in establishing a secure TLS connection, see the following ISARA demo code:
-
openssl_tls.c
-
openssl_tls.h
-
openssl_tls_server_1_2.c
-
openssl_tls_client_1_2.c
-
openssl_dtls_client_1_2.c
-
openssl_dtls_server_1_2.c
Note: For certificate chain verification the libssl library internally calls
ISARA’s certificate verification procedure which is capable of verifying
Catalyst certificates. If you register your own custom certificate
verification procedure for the libssl library (e.g., using
SSL_CTX_set_cert_verify_callback()
or X509_STORE_set_verify_func()
),
your procedure will be used instead of ISARA’s certificate verification
procedure.
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.