Introduction
The ISARA Catalyst™ OpenSSL Connector lets you use the authentication algorithms provided in the ISARA Radiate™ Security Solution Suite to create:
-
Quantum-Safe Catalyst certificates
-
PKCS10 Catalyst certificate signing requests
-
Dual private key files
-
CMS messages that are verifiable using embedded Catalyst certificates
-
PKCS12 files with Quantum-Safe 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 and X.509 certificates into their Catalyst variants. This means that if you already have scripts and infrastructure in place, you shouldn’t 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 certificates and certificate signing requests is limited to creating, inserting and removing attributes and extensions into/from certificate signing requests and X.509 certificates. Since OpenSSL already provides APIs for doing these things 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 certificates 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 certificate will be processed the same as a traditional X.509 certificate.
This Quantum-Safe Catalyst Certificate Tutorial covers the following topics:
Introduction to the Authentication Schemes
The ISARA Catalyst OpenSSL 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 OpenSSL Connector. |
Many of the algorithms' details are abstracted via the EVP PKEY API. For more information, see ISARA Catalyst OpenSSL Connector 2.0 Developer’s Guide.
This document has several diagrams. The following is a legend of the various keys 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_filenamemust be set to a file name that can be created. This is discussed below, but for more details, see the ISARA Catalyst OpenSSL Connector 2.0 User’s Guide. -
All ISARA Catalyst signature schemes only accept 512 or 256 bit (64 or 32 byte) digests as input. This may be different from other implementations of these algorithms.
-
Each Catalyst certificate will have a dual private key file associated with it.
Introduction to Generic X.509 Certificates and Certificate Signing Requests
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.
Introduction to Quantum-Safe Catalyst Certificates, Certificate Signing Requests, CMS Messages and Dual Private Key Files
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. QS 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. The only difference is that for our case, they will be associated with quantum-safe authentication schemes.
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. Quantum-Safe 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. The only difference is that in this case, they will be associated with quantum-safe authentication schemes.
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. Quantum-Safe Catalyst CMS messages are simply messages with a Catalyst certificate and a SignerInfo structure that contain an alternative signature algorithm identifier and an attribute that contains an alternative signature. The signature resulted from signing the CMS message. In our case, the algorithm will be a quantum-safe authentication scheme.
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 QSExtend applications also automatically merge the classical and quantum safe private key files for your convenience. ISARA Catalyst OpenSSL Connector 2.0 also provides two new utilities:
-
privQSExtend.py
-
Extend a classical private key and quantum-safe private key 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.
-
privQSSplit.py
-
Split a quantum-safe dual private key into a classical private key and quantum-safe private key.
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
We provide a utility called reqQSExtend that transforms a certificate
signing request into a Catalyst certificate and produces a dual private key
file.
ISARA Catalyst OpenSSL Connector 2.0 provides two different
utilities to transform an X.509 certificate into a Catalyst certificate. The
first and simpler utility is called x509QSDirectExtend. This utility is meant
for transforming self-signed root certificates or quickly transforming
experimental certificates directly from public keys; no certificate signing
request is required. The second utility is called x509QSExtend and uses a
Catalyst certificate signing request to transform an X.509 certificate into its
Catalyst variant.
ISARA Catalyst OpenSSL Connector 2.0 provides a utility called x509QSVerify that does verification of the
quantum-safe signatures in the certificates given a Catalyst certificate chain.
ISARA Catalyst OpenSSL Connector 2.0 provides a utility called cmsQSExtend that transforms a CMS message into a
Catalyst CMS message. It does this by creating quantum-safe signature algorithm
and signature attributes and inserting them into the SignerInfo’s unsigned
attributes.
ISARA Catalyst OpenSSL Connector 2.0 provides a utility called cmsQSVerify that does verification of the
quantum-safe signatures in a CMS message’s SignerInfo’s unsigned attributes.
ISARA Catalyst OpenSSL Connector 2.0 provides a utility called pkcs12QSExtend that adds a new Quantum-Safe private key into
a pre-existing PKCS12 file that already contains a Catalyst certificate and
classical private key.
For the utilities that accept quantum-safe private keys as input to create
signatures, ISARA Catalyst OpenSSL Connector 2.0 always
accepts the optional -privqs_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 -passinqs arg parameters. These
specify the key password source. For more information about the format of arg,
see the PASS PHRASE ARGUMENTS section at
openssl.
It is important to note that in order for the Catalyst certificates and certificate signing requests to be quantum-safe, the artifacts in the extensions and attributes must be associated with quantum-safe signature schemes. This is enforced by these utilities.
reqQSExtend
This utility transforms a previously generated certificate signing request into a quantum-safe Catalyst certificate signing request by:
-
adding a subject alternative public key attribute to the request based on the quantum-safe public key.
-
adding an alternative signature algorithm attribute to the request based on the quantum-safe private key.
-
adding an alternative signature attribute to the request based on the quantum-safe private key.
-
creating a dual private key based on the original and quantum-safe private keys. If a cipher is specified, the original and quantum-safe private key 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 to the certificate signing request. The certificate signing request is then re-signed with the original private key. Finally, the quantum-safe private key is replaced with the dual private key.
x509QSDirectExtend
This utility transforms a previously generated X.509 certificate into a quantum-safe Catalyst certificate by:
-
adding a subject alternative public key extension to the certificate based on the quantum-safe public key.
-
adding an alternative signature algorithm extension based on the quantum-safe private key
-
adding an alternative signature extension based on the quantum-safe private key
-
creating a dual private key based on the original and quantum-safe private keys. If a cipher is specified, the original and quantum-safe private key 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 quantum-safe signature is generated and transformed into an alternative signature extension and added to the certificate. The X.509 certificate is signed with the original private key. Finally, the quantum-safe private key is replaced with the dual private key.
If you are using this utility because you want to create 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 -privqs. If you use the -self_sign
flag you must not use the -pubqs flag.
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 not specify the -self_sign flag and must use the -pubqs flag
to specify a public key file.
x509QSExtend
This utility combines a previously generated X.509 certificate and quantum-safe Catalyst certificate signing request into a quantum-safe 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 quantum-safe private key
-
adding an alternative signature extension based on the quantum-safe private key
The first two extensions are inserted into the certificate. Then the quantum-safe 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 original private key.
x509QSVerify
This utility primarily shows how to perform quantum-safe signature verification
of Catalyst certificate chains. It is important to note that this utility does
not do verification of the conventional signatures in the X.509 certificates in
the chain and only checks the validity of the quantum-safe signatures in the
chain. However, the vanilla openssl verify utility can still function
correctly with quantum-safe 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 x509QSVerify does not have
an equivalent to the -check-ss-sig to trigger verification of the
self-signed root certificate. Instead, the openssl x509QSVerify utility
always verifies the root certificate.
|
cmsQSExtend
This utility transforms a previously signed CMS Message into a quantum-safe CMS message by:
-
adding an alternative signature algorithm attribute to the SignerInfo’s unsigned attributes. The signature algorithm is based on the quantum-safe private key.
-
adding an alternative signature attribute to the SignerInfo’s unsigned attributes. The signature is based on the quantum-safe 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 quantum-safe 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 classical and quantum safe private keys in the dual private key file were encrypted under the same password.
cmsQSVerify
This utility primarily shows how to perform quantum-safe signature verification
of a CMS message. It is important to note that this utility does not do
verification of the normal signature in the CMS message’s SignerInfo and only
checks the validity of the quantum-safe 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 verify utility, not replace it.
pkcs12QSExtend
This utility takes a PKCS12 file that contains a Catalyst Certificate and a regular private key and then adds a quantum-safe private key that corresponds to the Alternative Public Key in the certificate.
Note that this requires that the certificate and normal private key are already embedded in the PKCS12 file and the alternative public key be the one that corresponds to the quantum-safe 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 certificates and certificate signing requests 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 reqQSExtend.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
x509QSExtend.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 x509QSExtend.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 x509QSExtend.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 x509QSExtend.c.
Quantum Safe 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
quantum-safe signature scheme, find where they are called in x509QSExtend.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 x509QSExtend.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 x509QSVerify.c.
To learn how to get the alternative signature algorithm and alternative
signature, see how X509_get_ext() is used in x509QSVerify.c.
Quantum Safe Verification of a Catalyst Certificate
To learn how to write a callback function that verifies a signature of a
certificate using a quantum-safe signature scheme, please see the
qs_verification_cb() function in x509QSVerify.c. This callback would be
passed into OpenSSL via X509_STORE_set_verify_cb().
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 cmsQSExtend.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 cmsQSVerify.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 quantum-safe alternative private key.
Note that it is given the same "friendly name" as the regular private key except
with an "[ALT]" marker prepended to it.
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 (i.e., 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.0.2/).
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.0.2/).
To load private keys into the SSL context for operations such as digital
signature creation during TLS secure handshake, new APIs are added to libssl
for loading Quantum-Safe private keys.
Each Catalyst certificate corresponds to two private keys, one (the classical private key) corresponding to the subject public key in the subject public key info of the certificate, and the other (the Quantum-Safe private key) corresponding to the subject alternative public key in the extension of the certificate.
The classical private key can be loaded into the SSL context using existing
libssl functions such as SSL_CTX_use_PrivateKey(). To load the Quantum-Safe
private key, the following new functions are introduced.
int SSL_CTX_use_ALTPrivateKey(SSL_CTX *ctx, EVP_PKEY *pkey);
This function loads pkey as a private key to ctx. Note that the private
keys 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 private key of type type stored at memory location
d with length len to ctx. The private key types for Quantum-Safe private
keys for end entity certificates can be EVP_PKEY_DILITHIUM for the Dilithium
lattice-based signature scheme.
Note that stateful hash-based signature schemes can only be used for CA
certificates, and not for intermediate and 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 ciphersuites.
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 ISARA demo code openssl_tls.h, openssl_tls_server.c, and
openssl_tls_client.c.
Note that 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 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.