Shared datatypes for the OpenTitan cryptography library. More...

#include <stddef.h>
#include <stdint.h>
#include "api_config.h"
#include "freestanding/absl_status.h"
#include "freestanding/defs.h"
#include "freestanding/hardened.h"

Data Structures
struct	otcrypto_generic_buf
	Generic struct to hold a fixed-length byte array. More...

struct	otcrypto_byte_buf
	Struct to hold a fixed-length byte array. More...

struct	otcrypto_const_byte_buf
	Struct to hold a constant fixed-length byte array. More...

struct	otcrypto_word32_buf
	Struct to hold a fixed-length word array. More...

struct	otcrypto_const_word32_buf
	Struct to hold a constant fixed-length word array. More...

struct	otcrypto_key_config
	* Struct to represent the configuration of a blinded key. More...

struct	otcrypto_unblinded_key
	Struct to handle unmasked key type. More...

struct	otcrypto_blinded_key
	Struct to handle masked key type. More...

struct	otcrypto_hash_digest
	Container for a hash digest. More...

Typedefs
typedef status_t	otcrypto_status_t
	Return values for the crypto library.

typedef enum otcrypto_status_value	otcrypto_status_value_t
	Possible status values for the cryptolib.

typedef struct otcrypto_generic_buf	otcrypto_generic_buf_t
	Generic struct to hold a fixed-length byte array.

typedef struct otcrypto_byte_buf	otcrypto_byte_buf_t
	Struct to hold a fixed-length byte array.

typedef struct otcrypto_const_byte_buf	otcrypto_const_byte_buf_t
	Struct to hold a constant fixed-length byte array.

typedef struct otcrypto_word32_buf	otcrypto_word32_buf_t
	Struct to hold a fixed-length word array.

typedef struct otcrypto_const_word32_buf	otcrypto_const_word32_buf_t
	Struct to hold a constant fixed-length word array.

typedef enum otcrypto_key_type	otcrypto_key_type_t
	Enum to denote the key type of the handled key.

typedef enum otcrypto_aes_key_mode	otcrypto_aes_key_mode_t
	Enum to specify the AES modes that use a key.

typedef enum otcrypto_hmac_key_mode	otcrypto_hmac_key_mode_t
	Enum to specify the HMAC modes that use a key.

typedef enum otcrypto_kmac_key_mode	otcrypto_kmac_key_mode_t
	Enum to specify the KMAC modes that use a key.

typedef enum otcrypto_rsa_key_mode	otcrypto_rsa_key_mode_t
	Enum to specify the RSA modes that use a key.

typedef enum otcrypto_ecc_key_mode	otcrypto_ecc_key_mode_t
	Enum to specify the ECC modes that use a key.

typedef enum otcrypto_kdf_key_mode	otcrypto_kdf_key_mode_t
	Enum to specify the KDF modes that use a key.

typedef enum otcrypto_pqc_key_mode	otcrypto_pqc_key_mode_t
	Enum to specify the PQC modes that use a key.

typedef enum otcrypto_key_mode	otcrypto_key_mode_t
	Enum for opentitan crypto modes that use a key.

typedef enum otcrypto_key_security_level	otcrypto_key_security_level_t
	* Enum to denote key security level.

typedef enum otcrypto_lib_version	otcrypto_lib_version_t
	* Enum to denote the crypto library version.

typedef struct otcrypto_key_config	otcrypto_key_config_t
	* Struct to represent the configuration of a blinded key.

typedef struct otcrypto_unblinded_key	otcrypto_unblinded_key_t
	Struct to handle unmasked key type.

typedef struct otcrypto_blinded_key	otcrypto_blinded_key_t
	Struct to handle masked key type.

typedef enum otcrypto_hash_mode	otcrypto_hash_mode_t
	Enum to define supported hashing modes.

typedef struct otcrypto_hash_digest	otcrypto_hash_digest_t
	Container for a hash digest.

Enumerations
enum	otcrypto_status_value { kOtcryptoStatusValueOk = (int32_t)0x739 , kOtcryptoStatusValueBadArgs = (int32_t)0x8000fea0 \| kInvalidArgument , kOtcryptoStatusValueInternalError = (int32_t)0x80005340 \| kAborted , kOtcryptoStatusValueFatalError = (int32_t)0x80006d80 \| kFailedPrecondition , kOtcryptoStatusValueAsyncIncomplete = (int32_t)0x8000ea40 \| kUnavailable , kOtcryptoStatusValueNotImplemented = (int32_t)0x80008d20 \| kUnimplemented }
	Possible status values for the cryptolib. More...

enum	otcrypto_key_type { kOtcryptoKeyTypeAes = 0x8e9 , kOtcryptoKeyTypeHmac = 0xe3f , kOtcryptoKeyTypeKmac = 0xb74 , kOtcryptoKeyTypeRsa = 0x7ee , kOtcryptoKeyTypeEcc = 0x15b , kOtcryptoKeyTypeKdf = 0xb87 , kOtcryptoKeyTypePqc = 0xabc }
	Enum to denote the key type of the handled key. More...

enum	otcrypto_aes_key_mode { kOtcryptoAesKeyModeEcb = 0x1b6 , kOtcryptoAesKeyModeCbc = 0xf3a , kOtcryptoAesKeyModeCfb = 0x0f9 , kOtcryptoAesKeyModeOfb = 0xb49 , kOtcryptoAesKeyModeCtr = 0x4ce , kOtcryptoAesKeyModeGcm = 0xaa5 , kOtcryptoAesKeyModeKwp = 0x7d5 , kOtcryptoAesKeyModeCmac = 0x1a2 }
	Enum to specify the AES modes that use a key. More...

enum	otcrypto_hmac_key_mode { kOtcryptoHmacKeyModeSha256 = 0x7fd , kOtcryptoHmacKeyModeSha384 = 0x43b , kOtcryptoHmacKeyModeSha512 = 0x7a2 }
	Enum to specify the HMAC modes that use a key. More...

enum	otcrypto_kmac_key_mode { kOtcryptoKmacKeyModeKmac128 = 0xa56 , kOtcryptoKmacKeyModeKmac256 = 0x663 }
	Enum to specify the KMAC modes that use a key. More...

enum	otcrypto_rsa_key_mode { kOtcryptoRsaKeyModeSignPkcs = 0x3d4 , kOtcryptoRsaKeyModeSignPss = 0x761 , kOtcryptoRsaKeyModeEncryptOaep = 0x585 }
	Enum to specify the RSA modes that use a key. More...

enum	otcrypto_ecc_key_mode { kOtcryptoEccKeyModeEcdsaP256 = 0x31e , kOtcryptoEccKeyModeEcdsaP384 = 0x695 , kOtcryptoEccKeyModeEcdhP256 = 0x5fc , kOtcryptoEccKeyModeEcdhP384 = 0x1c7 , kOtcryptoEccKeyModeEd25519 = 0x663 , kOtcryptoEccKeyModeX25519 = 0x0bb }
	Enum to specify the ECC modes that use a key. More...

enum	otcrypto_kdf_key_mode { kOtcryptoKdfKeyModeCtrHmac = 0x12f , kOtcryptoKdfKeyModeKmac128 = 0xe5e , kOtcryptoKdfKeyModeKmac256 = 0x353 }
	Enum to specify the KDF modes that use a key. More...

enum	otcrypto_pqc_key_mode { kOtcryptoPqcKeyModeMldsa87 = 0xcee }
	Enum to specify the PQC modes that use a key. More...

enum	otcrypto_key_mode { kOtcryptoKeyModeAesEcb = kOtcryptoKeyTypeAes << 16 \| kOtcryptoAesKeyModeEcb , kOtcryptoKeyModeAesCbc = kOtcryptoKeyTypeAes << 16 \| kOtcryptoAesKeyModeCbc , kOtcryptoKeyModeAesCfb = kOtcryptoKeyTypeAes << 16 \| kOtcryptoAesKeyModeCfb , kOtcryptoKeyModeAesOfb = kOtcryptoKeyTypeAes << 16 \| kOtcryptoAesKeyModeOfb , kOtcryptoKeyModeAesCtr = kOtcryptoKeyTypeAes << 16 \| kOtcryptoAesKeyModeCtr , kOtcryptoKeyModeAesGcm = kOtcryptoKeyTypeAes << 16 \| kOtcryptoAesKeyModeGcm , kOtcryptoKeyModeAesKwp = kOtcryptoKeyTypeAes << 16 \| kOtcryptoAesKeyModeKwp , kOtcryptoKeyModeAesCmac = kOtcryptoKeyTypeAes << 16 \| kOtcryptoAesKeyModeCmac , kOtcryptoKeyModeHmacSha256 , kOtcryptoKeyModeHmacSha384 , kOtcryptoKeyModeHmacSha512 , kOtcryptoKeyModeKmac128 , kOtcryptoKeyModeKmac256 , kOtcryptoKeyModeRsaSignPkcs , kOtcryptoKeyModeRsaSignPss , kOtcryptoKeyModeRsaEncryptOaep , kOtcryptoKeyModeEcdsaP256 , kOtcryptoKeyModeEcdsaP384 , kOtcryptoKeyModeEcdhP256 , kOtcryptoKeyModeEcdhP384 , kOtcryptoKeyModeEd25519 , kOtcryptoKeyModeX25519 , kOtcryptoKeyModeKdfCtrHmac , kOtcryptoKeyModeKdfKmac128 , kOtcryptoKeyModeKdfKmac256 , kOtcryptoKeyModePqcMldsa87 }
	Enum for opentitan crypto modes that use a key. More...

enum	otcrypto_key_security_level { kOtcryptoKeySecurityLevelLow = 0x1e9 , kOtcryptoKeySecurityLevelMedium = 0xeab , kOtcryptoKeySecurityLevelHigh = 0xa7e }
	* Enum to denote key security level. More...

enum	otcrypto_lib_version { kOtcryptoLibVersion1 = 0x7f4 }
	* Enum to denote the crypto library version. More...

enum	{ kOtcryptoWrappedKeyMaxWords }
	Maximum number of 32-bit words in a wrapped key. More...

enum	otcrypto_hash_mode { kOtcryptoHashModeSha256 = 0x69b , kOtcryptoHashModeSha384 = 0x7ae , kOtcryptoHashModeSha512 = 0x171 , kOtcryptoHashModeSha3_224 = 0x516 , kOtcryptoHashModeSha3_256 = 0x2d4 , kOtcryptoHashModeSha3_384 = 0x267 , kOtcryptoHashModeSha3_512 = 0x44d , kOtcryptoHashXofModeShake128 = 0x5d8 , kOtcryptoHashXofModeShake256 = 0x34a , kOtcryptoHashXofModeCshake128 = 0x0bd , kOtcryptoHashXofModeCshake256 = 0x4e2 }
	Enum to define supported hashing modes. More...

Detailed Description

Shared datatypes for the OpenTitan cryptography library.

This header defines status codes, byte buffer representations, and key representations that are shared between different algorithms within the library.

Definition in file datatypes.h.

Data Structure Documentation

◆ otcrypto_generic_buf

struct otcrypto_generic_buf

Generic struct to hold a fixed-length byte array.

Made to generalize the structures defined below.

Definition at line 91 of file datatypes.h.

Data Fields
const void *	data	Pointer to the data.
size_t	len	Length of the data in bytes.
uint32_t	ptr_checksum	Integrity of the buffer which is over the address and the length but not the contents.

◆ otcrypto_byte_buf

struct otcrypto_byte_buf

Struct to hold a fixed-length byte array.

Note: the caller must (1) allocate sufficient space; (2) set the len field and data pointer when otcrypto_byte_buf_t is used for output; and (3) set the ptr_checksum using the OTCRYPTO_MAKE_BUF macro. The crypto library will throw an error if len doesn't match expectations.

Definition at line 111 of file datatypes.h.

Data Fields
uint8_t *	data	Pointer to the data.
size_t	len	Length of the data in bytes.
uint32_t	ptr_checksum	Integrity of the buffer which is over the address and the length but not the contents.

◆ otcrypto_const_byte_buf

struct otcrypto_const_byte_buf

Struct to hold a constant fixed-length byte array.

The const annotations prevent any changes to the byte buffer. It is necessary to have this structure separate from otcrypto_byte_buf_t because data pointed to by a struct does not inherit const, so const otcrypto_byte_buf_t would still allow data to change.

Definition at line 131 of file datatypes.h.

Data Fields
const uint8_t *const	data	Pointer to the data.
const size_t	len	Length of the data in bytes.
uint32_t	ptr_checksum	Integrity of the buffer which is over the address and the length but not the contents.

◆ otcrypto_word32_buf

struct otcrypto_word32_buf

Struct to hold a fixed-length word array.

Note: the caller must (1) allocate sufficient space; (2) set the len field and data pointer when otcrypto_word32_buf_t is used for output; and (3) set the ptr_checksum using the OTCRYPTO_MAKE_BUF macro. The crypto library will throw an error if len doesn't match expectations.

Definition at line 151 of file datatypes.h.

Data Fields
uint32_t *	data	Pointer to the data.
size_t	len	Length of the data in words.
uint32_t	ptr_checksum	Integrity of the buffer which is over the address and the length but not the contents.

◆ otcrypto_const_word32_buf

struct otcrypto_const_word32_buf

Struct to hold a constant fixed-length word array.

The const annotations prevent any changes to the word buffer. It is necessary to have this structure separate from otcrypto_word32_buf_t because data pointed to by a struct does not inherit const, so const otcrypto_word32_buf_t would still allow data to change.

Definition at line 171 of file datatypes.h.

Data Fields
const uint32_t *const	data	Pointer to the data.
const size_t	len	Length of the data in words.
uint32_t	ptr_checksum	Integrity of the buffer which is over the address and the length but not the contents.

◆ otcrypto_key_config

struct otcrypto_key_config

* Struct to represent the configuration of a blinded key.

Definition at line 454 of file datatypes.h.

Data Fields
hardened_bool_t	exportable	Whether the key can be exported (always false if `hw_backed` is true).
hardened_bool_t	hw_backed	Whether the hardware key manager should produce this key. If this is set to `true`, the keyblob must be exactly 8 words long, where the first word is the version and the remaining 7 words are the salt.
uint32_t	key_length	Length in bytes of the unblinded form of this key.
otcrypto_key_mode_t	key_mode	Mode for which the key usage is intended.
otcrypto_key_security_level_t	security_level	Key security level.
otcrypto_lib_version_t	version	Crypto library version for this key.

◆ otcrypto_unblinded_key

struct otcrypto_unblinded_key

Struct to handle unmasked key type.

Definition at line 492 of file datatypes.h.

Data Fields
uint32_t	checksum	Implementation specific, checksum for this struct.
uint32_t *	key	Implementation specific, storage provided by caller.
uint32_t	key_length	Key length in bytes.
otcrypto_key_mode_t	key_mode	Mode for which the key usage is intended.

◆ otcrypto_blinded_key

struct otcrypto_blinded_key

Struct to handle masked key type.

Definition at line 506 of file datatypes.h.

Data Fields
uint32_t	checksum	Implementation specific, checksum for this struct.
const otcrypto_key_config_t	config	Key configuration information.
uint32_t *	keyblob	Implementation specific, storage provided by caller.
const uint32_t	keyblob_length	Length of blinded key material in bytes.

◆ otcrypto_hash_digest

struct otcrypto_hash_digest

Container for a hash digest.

Definition at line 550 of file datatypes.h.

Data Fields
uint32_t *	data	Digest data.
size_t	len	Digest length in 32-bit words.
otcrypto_hash_mode_t	mode	Digest type.

Typedef Documentation

◆ otcrypto_aes_key_mode_t

typedef enum otcrypto_aes_key_mode otcrypto_aes_key_mode_t

Enum to specify the AES modes that use a key.

This will be used in the otcrypto_key_mode_t struct to indicate the mode for which the provided key is intended for.

Values are hardened.

◆ otcrypto_byte_buf_t

typedef struct otcrypto_byte_buf otcrypto_byte_buf_t

Struct to hold a fixed-length byte array.

Note: the caller must (1) allocate sufficient space; (2) set the len field and data pointer when otcrypto_byte_buf_t is used for output; and (3) set the ptr_checksum using the OTCRYPTO_MAKE_BUF macro. The crypto library will throw an error if len doesn't match expectations.

◆ otcrypto_const_byte_buf_t

typedef struct otcrypto_const_byte_buf otcrypto_const_byte_buf_t

Struct to hold a constant fixed-length byte array.

The const annotations prevent any changes to the byte buffer. It is necessary to have this structure separate from otcrypto_byte_buf_t because data pointed to by a struct does not inherit const, so const otcrypto_byte_buf_t would still allow data to change.

◆ otcrypto_const_word32_buf_t

typedef struct otcrypto_const_word32_buf otcrypto_const_word32_buf_t

Struct to hold a constant fixed-length word array.

The const annotations prevent any changes to the word buffer. It is necessary to have this structure separate from otcrypto_word32_buf_t because data pointed to by a struct does not inherit const, so const otcrypto_word32_buf_t would still allow data to change.

◆ otcrypto_ecc_key_mode_t

typedef enum otcrypto_ecc_key_mode otcrypto_ecc_key_mode_t

Enum to specify the ECC modes that use a key.

This will be used in the otcrypto_key_mode_t struct to indicate the mode for which the provided key is intended for.

Values are hardened.

◆ otcrypto_generic_buf_t

typedef struct otcrypto_generic_buf otcrypto_generic_buf_t

Generic struct to hold a fixed-length byte array.

Made to generalize the structures defined below.

◆ otcrypto_hash_mode_t

typedef enum otcrypto_hash_mode otcrypto_hash_mode_t

Enum to define supported hashing modes.

Values are hardened.

◆ otcrypto_hmac_key_mode_t

typedef enum otcrypto_hmac_key_mode otcrypto_hmac_key_mode_t

Enum to specify the HMAC modes that use a key.

This will be used in the otcrypto_key_mode_t struct to indicate the mode for which the provided key is intended for.

Values are hardened.

◆ otcrypto_kdf_key_mode_t

typedef enum otcrypto_kdf_key_mode otcrypto_kdf_key_mode_t

Enum to specify the KDF modes that use a key.

This will be used in the otcrypto_key_mode_t struct to indicate the mode for which the provided key is intended for.

Values are hardened.

◆ otcrypto_key_config_t

typedef struct otcrypto_key_config otcrypto_key_config_t

* Struct to represent the configuration of a blinded key.

◆ otcrypto_key_mode_t

typedef enum otcrypto_key_mode otcrypto_key_mode_t

Enum for opentitan crypto modes that use a key.

Denotes the crypto mode for which the provided key is to be used. This otcrypto_key_mode_t will be a parameter in the otcrypto_blinded_key_t and otcrypto_unblinded_key_t structs.

Values are hardened.

◆ otcrypto_key_security_level_t

typedef enum otcrypto_key_security_level otcrypto_key_security_level_t

* Enum to denote key security level.

* * At high security levels, the crypto library will prioritize * protecting the key from sophisticated attacks, even at large * performance costs. If the security level is low, the crypto * library will still try to protect the key, but may forgo the * most costly protections against e.g. sophisticated physical * attacks. * * Values are hardened.

◆ otcrypto_key_type_t

typedef enum otcrypto_key_type otcrypto_key_type_t

Enum to denote the key type of the handled key.

Values are hardened.

◆ otcrypto_kmac_key_mode_t

typedef enum otcrypto_kmac_key_mode otcrypto_kmac_key_mode_t

Enum to specify the KMAC modes that use a key.

This will be used in the otcrypto_key_mode_t struct to indicate the mode for which the provided key is intended for.

Values are hardened.

◆ otcrypto_lib_version_t

typedef enum otcrypto_lib_version otcrypto_lib_version_t

* Enum to denote the crypto library version.

* * In future updates, this enum will be extended to preserve some * level of backwards-compatibility despite changes to internal * details (for example, the preferred masking scheme for blinded * keys). * * Values are hardened.

◆ otcrypto_pqc_key_mode_t

typedef enum otcrypto_pqc_key_mode otcrypto_pqc_key_mode_t

Enum to specify the PQC modes that use a key.

This will be used in the otcrypto_key_mode_t struct to indicate the mode for which the provided key is intended for.

Values are hardened.

◆ otcrypto_rsa_key_mode_t

typedef enum otcrypto_rsa_key_mode otcrypto_rsa_key_mode_t

Enum to specify the RSA modes that use a key.

This will be used in the otcrypto_key_mode_t struct to indicate the mode for which the provided key is intended for.

Values are hardened.

◆ otcrypto_status_t

typedef status_t otcrypto_status_t

Return values for the crypto library.

The crypto library's return value is defined as OpenTitan's internal status_t in order to simplify testing. However, informally the library guarantees that the concrete value contained in the status will be one of the members of the otcrypto_status_value enum below.

Definition at line 42 of file datatypes.h.

◆ otcrypto_status_value_t

typedef enum otcrypto_status_value otcrypto_status_value_t

Possible status values for the cryptolib.

As long as the OTCRYPTO_STATUS_DEBUG define is unset, all otcrypto_status_t codes returned by the cryptolib should be bit-by-bit equivalent with one of the values in this enum.

Values are built to be bit-compatible with OpenTitan's internal status_t datatypes. The highest (sign) bit indicates if the value is an error (1) or not (0). For non-error statuses, the rest can be anything; in cryptolib status codes it is always kHardenedBoolTrue. For errors:

The next 15 bits are a module identifier, which is always 0 in the cryptolib status codes
The next 11 bits are a line number or other information; in the cryptolib status codes, it is a hardened value created to have high Hamming distance with the other valid status codes
The final 5 bits are an Abseil-compatible error code

The hardened values for error codes were generated with: $ ./util/design/sparse-fsm-encode.py -d 5 -m 5 -n 11 \ -s 4232058530 –language=sv –avoid-zero

Use the same seed value and a larger -m argument to generate new values without changing all error codes. Remove the seed (-s argument) to generate completely new 11-bit values.

◆ otcrypto_word32_buf_t

typedef struct otcrypto_word32_buf otcrypto_word32_buf_t

Struct to hold a fixed-length word array.

Note: the caller must (1) allocate sufficient space; (2) set the len field and data pointer when otcrypto_word32_buf_t is used for output; and (3) set the ptr_checksum using the OTCRYPTO_MAKE_BUF macro. The crypto library will throw an error if len doesn't match expectations.

Enumeration Type Documentation

◆ anonymous enum

anonymous enum

Maximum number of 32-bit words in a wrapped key.

Sized for the largest supported key (RSA-4096 private key). Callers can use this to bound input buffers passed to otcrypto_key_unwrap.

Definition at line 477 of file datatypes.h.

◆ otcrypto_aes_key_mode

enum otcrypto_aes_key_mode

Enum to specify the AES modes that use a key.

This will be used in the otcrypto_key_mode_t struct to indicate the mode for which the provided key is intended for.

Values are hardened.

Enumerator
kOtcryptoAesKeyModeEcb	Mode AES ECB.
kOtcryptoAesKeyModeCbc	Mode AES CBC.
kOtcryptoAesKeyModeCfb	Mode AES CFB.
kOtcryptoAesKeyModeOfb	Mode AES OFB.
kOtcryptoAesKeyModeCtr	Mode AES CTR.
kOtcryptoAesKeyModeGcm	Mode AES GCM.
kOtcryptoAesKeyModeKwp	Mode AES KWP.
kOtcryptoAesKeyModeCmac	Mode AES CMAC.

Definition at line 213 of file datatypes.h.

◆ otcrypto_ecc_key_mode

enum otcrypto_ecc_key_mode

Enum to specify the ECC modes that use a key.

This will be used in the otcrypto_key_mode_t struct to indicate the mode for which the provided key is intended for.

Values are hardened.

Enumerator
kOtcryptoEccKeyModeEcdsaP256	Mode ECDSA/P-256.
kOtcryptoEccKeyModeEcdsaP384	Mode ECDSA/P-384.
kOtcryptoEccKeyModeEcdhP256	Mode ECDH/P-256.
kOtcryptoEccKeyModeEcdhP384	Mode ECDH/P-384.
kOtcryptoEccKeyModeEd25519	Mode Ed25519.
kOtcryptoEccKeyModeX25519	Mode X25519.

Definition at line 289 of file datatypes.h.

◆ otcrypto_hash_mode

enum otcrypto_hash_mode

Enum to define supported hashing modes.

Values are hardened.

Enumerator
kOtcryptoHashModeSha256	SHA2-256 mode.
kOtcryptoHashModeSha384	SHA2-384 mode.
kOtcryptoHashModeSha512	SHA2-512 mode.
kOtcryptoHashModeSha3_224	SHA3-224 mode.
kOtcryptoHashModeSha3_256	SHA3-256 mode.
kOtcryptoHashModeSha3_384	SHA3-384 mode.
kOtcryptoHashModeSha3_512	SHA3-512 mode.
kOtcryptoHashXofModeShake128	Shake128 mode.
kOtcryptoHashXofModeShake256	Shake256 mode.
kOtcryptoHashXofModeCshake128	cShake128 mode.
kOtcryptoHashXofModeCshake256	cShake256 mode.

Definition at line 522 of file datatypes.h.

◆ otcrypto_hmac_key_mode

enum otcrypto_hmac_key_mode

Enum to specify the HMAC modes that use a key.

This will be used in the otcrypto_key_mode_t struct to indicate the mode for which the provided key is intended for.

Values are hardened.

Enumerator
kOtcryptoHmacKeyModeSha256	Mode HMAC SHA256.
kOtcryptoHmacKeyModeSha384	Mode HMAC SHA384.
kOtcryptoHmacKeyModeSha512	Mode HMAC SHA512.

Definition at line 240 of file datatypes.h.

◆ otcrypto_kdf_key_mode

enum otcrypto_kdf_key_mode

Enum to specify the KDF modes that use a key.

This will be used in the otcrypto_key_mode_t struct to indicate the mode for which the provided key is intended for.

Values are hardened.

Enumerator
kOtcryptoKdfKeyModeCtrHmac	Mode KDF-CTR with HMAC as PRF.
kOtcryptoKdfKeyModeKmac128	Mode KDF-KMAC with KMAC128 as PRF.
kOtcryptoKdfKeyModeKmac256	Mode KDF-KMAC with KMAC256 as PRF.

Definition at line 312 of file datatypes.h.

◆ otcrypto_key_mode

enum otcrypto_key_mode

Enum for opentitan crypto modes that use a key.

Denotes the crypto mode for which the provided key is to be used. This otcrypto_key_mode_t will be a parameter in the otcrypto_blinded_key_t and otcrypto_unblinded_key_t structs.

Values are hardened.

Enumerator
kOtcryptoKeyModeAesEcb	Key is intended for AES ECB mode.
kOtcryptoKeyModeAesCbc	Key is intended for AES CBC mode.
kOtcryptoKeyModeAesCfb	Key is intended for AES CFB mode.
kOtcryptoKeyModeAesOfb	Key is intended for AES OFB mode.
kOtcryptoKeyModeAesCtr	Key is intended for AES CTR mode.
kOtcryptoKeyModeAesGcm	Key is intended for AES GCM mode.
kOtcryptoKeyModeAesKwp	Key is intended for AES KWP mode.
kOtcryptoKeyModeAesCmac	Key is intended for AES CMAC mode.
kOtcryptoKeyModeHmacSha256	Key is intended for HMAC SHA256 mode.
kOtcryptoKeyModeHmacSha384	Key is intended for HMAC SHA384 mode.
kOtcryptoKeyModeHmacSha512	Key is intended for HMAC SHA512 mode.
kOtcryptoKeyModeKmac128	Key is intended for KMAC128 mode.
kOtcryptoKeyModeKmac256	Key is intended for KMAC256 mode.
kOtcryptoKeyModeRsaSignPkcs	Key is intended for RSA signature RSASSA-PKCS mode.
kOtcryptoKeyModeRsaSignPss	Key is intended for RSA signature RSASSA-PSS mode.
kOtcryptoKeyModeRsaEncryptOaep	Key is intended for RSA encryption RSAES-OAEP mode.
kOtcryptoKeyModeEcdsaP256	Key is intended for ECDSA with P-256.
kOtcryptoKeyModeEcdsaP384	Key is intended for ECDSA with P-384.
kOtcryptoKeyModeEcdhP256	Key is intended for ECDH with P-256.
kOtcryptoKeyModeEcdhP384	Key is intended for ECDH with P-384.
kOtcryptoKeyModeEd25519	Key is intended for Ed25519 mode.
kOtcryptoKeyModeX25519	Key is intended for X25519 mode.
kOtcryptoKeyModeKdfCtrHmac	Key is intended for KDF-CTR with HMAC as PRF.
kOtcryptoKeyModeKdfKmac128	Key is intended for KDF with KMAC128 as PRF.
kOtcryptoKeyModeKdfKmac256	Key is intended for KDF with KMAC256 as PRF.

Definition at line 343 of file datatypes.h.

◆ otcrypto_key_security_level

enum otcrypto_key_security_level

* Enum to denote key security level.

* * At high security levels, the crypto library will prioritize * protecting the key from sophisticated attacks, even at large * performance costs. If the security level is low, the crypto * library will still try to protect the key, but may forgo the * most costly protections against e.g. sophisticated physical * attacks. * * Values are hardened.

Enumerator
kOtcryptoKeySecurityLevelLow	Security level low.
kOtcryptoKeySecurityLevelMedium	Security level medium.
kOtcryptoKeySecurityLevelHigh	Security level high.

Definition at line 427 of file datatypes.h.

◆ otcrypto_key_type

enum otcrypto_key_type

Enum to denote the key type of the handled key.

Values are hardened.

Enumerator
kOtcryptoKeyTypeAes	Key type AES.
kOtcryptoKeyTypeHmac	Key type HMAC.
kOtcryptoKeyTypeKmac	Key type KMAC.
kOtcryptoKeyTypeRsa	Key type RSA.
kOtcryptoKeyTypeEcc	Key type ECC.
kOtcryptoKeyTypeKdf	Key type KDF.

Definition at line 188 of file datatypes.h.

◆ otcrypto_kmac_key_mode

enum otcrypto_kmac_key_mode

Enum to specify the KMAC modes that use a key.

This will be used in the otcrypto_key_mode_t struct to indicate the mode for which the provided key is intended for.

Values are hardened.

Enumerator
kOtcryptoKmacKeyModeKmac128	Mode KMAC128.
kOtcryptoKmacKeyModeKmac256	Mode KMAC256.

Definition at line 257 of file datatypes.h.

◆ otcrypto_lib_version

enum otcrypto_lib_version

* Enum to denote the crypto library version.

* * In future updates, this enum will be extended to preserve some * level of backwards-compatibility despite changes to internal * details (for example, the preferred masking scheme for blinded * keys). * * Values are hardened.

Enumerator
kOtcryptoLibVersion1	Version 1.

Definition at line 446 of file datatypes.h.

◆ otcrypto_pqc_key_mode

enum otcrypto_pqc_key_mode

Enum to specify the PQC modes that use a key.

This will be used in the otcrypto_key_mode_t struct to indicate the mode for which the provided key is intended for.

Values are hardened.

Definition at line 329 of file datatypes.h.

◆ otcrypto_rsa_key_mode

enum otcrypto_rsa_key_mode

Enum to specify the RSA modes that use a key.

This will be used in the otcrypto_key_mode_t struct to indicate the mode for which the provided key is intended for.

Values are hardened.

Enumerator
kOtcryptoRsaKeyModeSignPkcs	Mode RSA Sign, RSASSA-PKCS.
kOtcryptoRsaKeyModeSignPss	Mode RSA Sign, RSASSA-PSS.
kOtcryptoRsaKeyModeEncryptOaep	Mode RSA Encrypt, RSAES-OAEP.

Definition at line 272 of file datatypes.h.

◆ otcrypto_status_value

enum otcrypto_status_value

Possible status values for the cryptolib.

As long as the OTCRYPTO_STATUS_DEBUG define is unset, all otcrypto_status_t codes returned by the cryptolib should be bit-by-bit equivalent with one of the values in this enum.

Values are built to be bit-compatible with OpenTitan's internal status_t datatypes. The highest (sign) bit indicates if the value is an error (1) or not (0). For non-error statuses, the rest can be anything; in cryptolib status codes it is always kHardenedBoolTrue. For errors:

The next 15 bits are a module identifier, which is always 0 in the cryptolib status codes
The next 11 bits are a line number or other information; in the cryptolib status codes, it is a hardened value created to have high Hamming distance with the other valid status codes
The final 5 bits are an Abseil-compatible error code

The hardened values for error codes were generated with: $ ./util/design/sparse-fsm-encode.py -d 5 -m 5 -n 11 \ -s 4232058530 –language=sv –avoid-zero

Use the same seed value and a larger -m argument to generate new values without changing all error codes. Remove the seed (-s argument) to generate completely new 11-bit values.

Definition at line 70 of file datatypes.h.

Data Structures

Typedefs

Enumerations

Detailed Description

Data Structure Documentation

◆ otcrypto_generic_buf

◆ otcrypto_byte_buf

◆ otcrypto_const_byte_buf

◆ otcrypto_word32_buf

◆ otcrypto_const_word32_buf

◆ otcrypto_key_config

◆ otcrypto_unblinded_key

◆ otcrypto_blinded_key

◆ otcrypto_hash_digest

Typedef Documentation

◆ otcrypto_aes_key_mode_t

◆ otcrypto_byte_buf_t

◆ otcrypto_const_byte_buf_t

◆ otcrypto_const_word32_buf_t

◆ otcrypto_ecc_key_mode_t

◆ otcrypto_generic_buf_t

◆ otcrypto_hash_mode_t

◆ otcrypto_hmac_key_mode_t

◆ otcrypto_kdf_key_mode_t

◆ otcrypto_key_config_t

◆ otcrypto_key_mode_t

◆ otcrypto_key_security_level_t

◆ otcrypto_key_type_t

◆ otcrypto_kmac_key_mode_t

◆ otcrypto_lib_version_t

◆ otcrypto_pqc_key_mode_t

◆ otcrypto_rsa_key_mode_t

◆ otcrypto_status_t

◆ otcrypto_status_value_t

◆ otcrypto_word32_buf_t

Enumeration Type Documentation

◆ anonymous enum

◆ otcrypto_aes_key_mode

◆ otcrypto_ecc_key_mode

◆ otcrypto_hash_mode

◆ otcrypto_hmac_key_mode

◆ otcrypto_kdf_key_mode

◆ otcrypto_key_mode

◆ otcrypto_key_security_level

◆ otcrypto_key_type

◆ otcrypto_kmac_key_mode

◆ otcrypto_lib_version

◆ otcrypto_pqc_key_mode

◆ otcrypto_rsa_key_mode

◆ otcrypto_status_value