 |
Software APIs
|
|
Software APIs
|
Key import/export for the OpenTitan cryptography library. More...
#include "datatypes.h"Go to the source code of this file.
Functions | |
| otcrypto_status_t | otcrypto_symmetric_keygen (otcrypto_const_byte_buf_t perso_string, otcrypto_blinded_key_t *key) |
| Generates a new, random symmetric key. More... | |
| otcrypto_status_t | otcrypto_hw_backed_key (uint32_t version, const uint32_t salt[7], otcrypto_blinded_key_t *key) |
| Creates a handle for a hardware-backed key. More... | |
| otcrypto_status_t | otcrypto_import_blinded_key (const otcrypto_const_word32_buf_t key_share0, const otcrypto_const_word32_buf_t key_share1, otcrypto_blinded_key_t *blinded_key) |
| Creates a blinded key struct from masked key material. More... | |
| otcrypto_status_t | otcrypto_export_blinded_key (const otcrypto_blinded_key_t blinded_key, otcrypto_word32_buf_t key_share0, otcrypto_word32_buf_t key_share1) |
| Exports a blinded key to the user provided key buffer, in shares. More... | |
Key import/export for the OpenTitan cryptography library.
These functions allow library users to translate to and from the crypto library's key representations.
Definition in file key_transport.h.
| otcrypto_status_t otcrypto_export_blinded_key | ( | const otcrypto_blinded_key_t | blinded_key, |
| otcrypto_word32_buf_t | key_share0, | ||
| otcrypto_word32_buf_t | key_share1 | ||
| ) |
Exports a blinded key to the user provided key buffer, in shares.
This function will copy data from the keyblob into the shares; after the call, it is safe to free the blinded key and the data pointed to by blinded_key.keyblob.
Hardware-backed, non-exportable, and asymmetric (ECC or RSA) keys cannot be exported this way. For asymmetric keys, use an algorithm-specific funtion.
| blinded_key | Blinded key struct to be exported. | |
| [out] | key_share0 | First share of the blinded key. |
| [out] | key_share1 | Second share of the blinded key. |
Definition at line 125 of file key_transport.c.
| otcrypto_status_t otcrypto_hw_backed_key | ( | uint32_t | version, |
| const uint32_t | salt[7], | ||
| otcrypto_blinded_key_t * | key | ||
| ) |
Creates a handle for a hardware-backed key.
This routine may be used for both symmetric and asymmetric algorithms, since conceptually it only creates some data that the key manager can use to generate key material at the time of use. However, not all algorithms are suitable for hardware-backed keys (for example, RSA is not suitable), so some choices of algorithm may result in errors.
The caller should partially populate the blinded key struct; they should set the full key configuration and the keyblob length (always 32 bytes), and then allocate 32 bytes of space for the keyblob and set the keyblob pointer.
This function will populate the checksum field and copy the salt/version data into the keyblob buffer in the specific order that the rest of cryptolib expects.
| version | Key version. | |
| salt | Key salt (diversification data for KDF). | |
| [out] | key | Destination blinded key struct. |
Definition at line 57 of file key_transport.c.
| otcrypto_status_t otcrypto_import_blinded_key | ( | const otcrypto_const_word32_buf_t | key_share0, |
| const otcrypto_const_word32_buf_t | key_share1, | ||
| otcrypto_blinded_key_t * | blinded_key | ||
| ) |
Creates a blinded key struct from masked key material.
The caller should allocate and partially populate the blinded key struct, including populating the key configuration and allocating space for the keyblob. The keyblob should be twice the length of the user key. Hardware-backed and asymmetric (ECC or RSA) keys cannot be imported this way. For asymmetric keys, use algorithm-specific key construction methods.
This function will copy the data from the shares into the keyblob; it is safe to free key_share0 and key_share1 after this call.
| key_share0 | First share of the user provided key. | |
| key_share1 | Second share of the user provided key. | |
| [out] | blinded_key | Generated blinded key struct. |
Definition at line 86 of file key_transport.c.
| otcrypto_status_t otcrypto_symmetric_keygen | ( | otcrypto_const_byte_buf_t | perso_string, |
| otcrypto_blinded_key_t * | key | ||
| ) |
Generates a new, random symmetric key.
Use this only for symmetric algorithms (e.g. AES, HMAC, KMAC). Asymmetric algorithms (e.g. ECDSA, RSA) have their own specialized key-generation routines. Cannot be used for hardware-backed keys; use otcrypto_hw_backed_key instead to generate these.
The caller should allocate space for the keyblob and populate the blinded key struct with the length of the keyblob, the pointer to the keyblob buffer, and the key configuration. The value in the checksum field of the blinded key struct will be populated by the key generation function. The keyblob should be twice the length of the unblinded key. This function will return an error if the keyblob length does not match expectations based on the key mode and configuration.
The keyblob should be twice the length of the key. The caller only needs to allocate the keyblob, not populate it.
The personalization string may empty, and may be up to 48 bytes long; any longer will result in an error. It is passed as an extra seed input to the DRBG, in addition to the hardware TRNG.
| perso_string | Optional personalization string to be passed to DRBG. | |
| [out] | key | Destination blinded key struct. |
Definition at line 17 of file key_transport.c.