 |
Software APIs
|
|
Software APIs
|
Key import/export for the OpenTitan cryptography library. More...
#include "datatypes.h"Go to the source code of this file.
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.
| OT_WARN_UNUSED_RESULT 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 318 of file key_transport.c.
| OT_WARN_UNUSED_RESULT 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 59 of file key_transport.c.
| OT_WARN_UNUSED_RESULT 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 279 of file key_transport.c.
| OT_WARN_UNUSED_RESULT otcrypto_status_t otcrypto_key_unwrap | ( | otcrypto_const_word32_buf_t | wrapped_key, |
| const otcrypto_blinded_key_t * | key_kek, | ||
| hardened_bool_t * | success, | ||
| otcrypto_blinded_key_t * | unwrapped_key | ||
| ) |
Unwraps (decrypts) a secret key.
The key unwrap function uses AES-KWP (key wrapping with padding), an authenticated encryption mode designed for encrypting key material.
The caller must allocate space for the keyblob and set the keyblob-length and keyblob fields in unwrapped_key accordingly. If there is not enough space in the keyblob, this function will return an error. Too much space in the keyblob is okay; this function will write to the first part of the keyblob buffer and set the keyblob length field to the correct exact value for the unwrapped key, at which point it is safe to check the new length and free the remaining keyblob memory. It is always safe to allocate a keyblob the same size as the wrapped key; this will always be enough space by definition.
The caller does not need to populate the blinded key configuration, since this information is encrypted along with the key. However, the caller may want to check that the configuration matches expectations.
An OK status from this function does NOT necessarily mean that unwrapping succeeded; the caller must check both the returned status and the success parameter before reading the unwrapped key.
| wrapped_key | Encrypted key data. | |
| key_kek | AES-KWP key used to decrypt wrapped_key. | |
| [out] | success | Whether the wrapped key was valid. |
| [out] | unwrapped_key | Decrypted key data. |
Definition at line 218 of file key_transport.c.
| OT_WARN_UNUSED_RESULT otcrypto_status_t otcrypto_key_wrap | ( | const otcrypto_blinded_key_t * | key_to_wrap, |
| const otcrypto_blinded_key_t * | key_kek, | ||
| otcrypto_word32_buf_t | wrapped_key | ||
| ) |
Wraps (encrypts) a secret key.
The key wrap function uses AES-KWP (key wrapping with padding), an authenticated encryption mode designed for encrypting key material.
The caller should allocate space for the wrapped_key buffer according to otcrypto_wrapped_key_len, and set the length of expected output in the len field of wrapped_key. If the user-set length and the output length do not match, an error message will be returned.
The blinded key struct to wrap must be 32-bit aligned.
| key_to_wrap | Blinded key that will be encrypted. | |
| key_kek | AES-KWP key used to encrypt key_to_wrap. | |
| [out] | wrapped_key | Encrypted key data. |
Definition at line 164 of file key_transport.c.
| OT_WARN_UNUSED_RESULT 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 19 of file key_transport.c.
| OT_WARN_UNUSED_RESULT otcrypto_status_t otcrypto_wrapped_key_len | ( | const otcrypto_key_config_t | config, |
| size_t * | wrapped_num_words | ||
| ) |
Returns the length that the blinded key will have once wrapped.
| config | Key configuration. | |
| [out] | wrapped_num_words | Number of 32b words for the wrapped key. |
Definition at line 88 of file key_transport.c.