Skip to main content

Obtaining key

To perform any asymmetric key operation, you must first obtain a key in one of the following ways:

  • Key generation: Generate a new key as a private/public keypair.

  • Key setting: Set a key’s parameters from known raw values.

  • Key deserialization: Deserialize a key from a standard PEM or DER format.

  • Receive a custom key BLOB provided by DigiCert.

To use the first two options, create an empty key-shell (i.e., allocate space to hold the key to be generated or set) by calling one of the following APIs:

  • CRYPTO_INTERFACE_RSA_createKeyAux 

  • CRYPTO_INTERFACE_EC_newKeyAux 

  • CRYPTO_INTERFACE_DSA_createKey 

  • CRYPTO_INTERFACE_DH_allocate 

The following APIs each allocate an instance of the appropriate key structure:

  • RSAKey 

  • ECCKey 

  • DSAKey 

  • diffieHellmanContext 

These structures are now ready to hold either a private/public keypair, or just a public key. Some of these APIs are described below. Please refer to the Crypto Interface API reference for more information.

Key generation

Each cipher contains the following APIs to generate a new key pair:

  • CRYPTO_INTERFACE_RSA_generateKey 

  • CRYPTO_INTERFACE_EC_generateKeyPairAux 

  • CRYPTO_INTERFACE_DSA_generateKeyAux 

  • CRYPTO_INTERFACE_DH_generateKeyPair 

The RSA and DSA APIs generate the domain parameters in addition to the keys, including large prime numbers; hence the process is not a quick operation. The ECC and DH APIs, on the other hand, only generate the keypair. The domain parameters for ECC (i.e., which curve) and for DH (i.e., which group) are input when the key-shell is allocated via the appropriate create or new key API. There are also other variants of these generate key APIs for allocation and generation in a single step, or for generating TAP (Trust Anchor Platform) keys.

Examples of ECC, RSA, and DSA key generation may be found at:

${MSS_SRC_PKG}/mss/src/crypto_interface/example/crypto_interface_keygen_example.c

Key setting

The following APIs or their variants may be used to set raw key values into an allocated key:

  • CRYPTO_INTERFACE_RSA_setPublicKeyParameters 

  • CRYPTO_INTERFACE_RSA_setAllKeyParameters 

  • CRYPTO_INTERFACE_RSA_setAllKeyData 

  • CRYPTO_INTERFACE_EC_setKeyParametersAux 

  • CRYPTO_INTERFACE_DSA_setKeyParametersAux 

  • CRYPTO_INTERFACE_DH_setKeyParameters 

There are also analogous APIs for retrieving raw key parameters from a key. The ability to obtain the public key is especially important, because the public key is always a component of what is sent to the other party.

Key deserialization

Key deserialization can be performed before knowing whether the key is an ECC, RSA, or DSA key. Note that the DH keys are typically ephemeral and not serialized.

The following generic asymmetric key structure is defined in ${MSS_SRC_PKG}/src/crypto/pubcrypto.h and can store any one of these key types (ECC, RSA, or DSA):

struct AsymmetricKey asymKey = {0};

To deserialize and use a key from a buffer containing either PEM format, DER format, or a DigiCert-provided custom key BLOB format, make the following calls to initialize and deserialize:

  • CRYPTO_initAsymmetricKey(&asymKey); 

  • CRYPTO_deserializeAsymKey(pSerializedKey, serializedKeyLen, pMocCtx, &asymKey); 

The pMocCtx may be NULL if the underlying (operator) implementation of the serialization routines does not need one. The AsymmetricKey structure has a type field (i.e., asymKey.type), and may be one of the following values to indicate which type of key it is:

  • akt_rsa 

  • akt_ecc 

  • akt_ecc_ed 

  • akt_dsa 

Note that Edward’s form ECC keys have their own type. There are also separate types for TAP form keys that are not described in this document. The internal RSAKey structure for use in Crypto Interface RSA APIs may be accessed via:

  • asymKey.key.pRSA 

  • asymKey.key.pECC (for both akt_ecc and akt_ecc_ed types)

  • asymKey.key.pDSA 

After obtaining a key, you may perform a cipher operation with that key.

In this section: