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.

1 Legend
Figure 1. Key Legend

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

2 Traditional Chain
Figure 2. Traditional X.509 Certificate Chain

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

3 x509Alt
Figure 3. Catalyst Certificate Chain

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

4 reqAltExtend
Figure 4. Creating a Catalyst Certificate Signing Request

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.

5 x509AltDirectExtend Root
Figure 5. Creating a Root Catalyst Certificate

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.

6 x509AltDirectExtend quick
Figure 6. Creating a Catalyst Certificate Without a Certificate Signing Request

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

7 x509AltExtend
Figure 7. Creating a Catalyst Certificate With a Catalyst Certificate Signing Request

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

8 x509AltVerify
Figure 8. Verifying a Catalyst Certificate

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

9 crlAlt
Figure 9. Signing a CRL with an Alternative Private key Corresponding to the Alternative Public key in a Catalyst Certificate

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

9 cmsAlt
Figure 10. Signing a CMS Message with an Alternative Private key Corresponding to the Alternative Public key in a Catalyst Certificate

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

10 pkcs12
Figure 11. Adding an Alternative Private Key Corresponding to the Alternative Public Key in a Catalyst Certificate in a PKCS12 File.

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.

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.