 |
Software APIs
|
|
Software APIs
|
Shared datatypes for the OpenTitan cryptography library. More...
#include <stddef.h>#include <stdint.h>#include "freestanding/absl_status.h"#include "freestanding/defs.h"#include "freestanding/hardened.h"Go to the source code of this file.
Data Structures | |
| 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. More... | |
| typedef enum otcrypto_status_value | otcrypto_status_value_t |
| Possible status values for the cryptolib. More... | |
| typedef struct otcrypto_byte_buf | otcrypto_byte_buf_t |
| Struct to hold a fixed-length byte array. More... | |
| typedef struct otcrypto_const_byte_buf | otcrypto_const_byte_buf_t |
| Struct to hold a constant fixed-length byte array. More... | |
| typedef struct otcrypto_word32_buf | otcrypto_word32_buf_t |
| Struct to hold a fixed-length word array. More... | |
| typedef struct otcrypto_const_word32_buf | otcrypto_const_word32_buf_t |
| Struct to hold a constant fixed-length word array. More... | |
| typedef enum otcrypto_key_type | otcrypto_key_type_t |
| Enum to denote the key type of the handled key. More... | |
| typedef enum otcrypto_aes_key_mode | otcrypto_aes_key_mode_t |
| Enum to specify the AES modes that use a key. More... | |
| typedef enum otcrypto_hmac_key_mode | otcrypto_hmac_key_mode_t |
| Enum to specify the HMAC modes that use a key. More... | |
| typedef enum otcrypto_kmac_key_mode | otcrypto_kmac_key_mode_t |
| Enum to specify the KMAC modes that use a key. More... | |
| typedef enum otcrypto_rsa_key_mode | otcrypto_rsa_key_mode_t |
| Enum to specify the RSA modes that use a key. More... | |
| typedef enum otcrypto_ecc_key_mode | otcrypto_ecc_key_mode_t |
| Enum to specify the ECC modes that use a key. More... | |
| typedef enum otcrypto_kdf_key_mode | otcrypto_kdf_key_mode_t |
| Enum to specify the KDF modes that use a key. More... | |
| typedef enum otcrypto_key_mode | otcrypto_key_mode_t |
| Enum for opentitan crypto modes that use a key. More... | |
| typedef enum otcrypto_key_security_level | otcrypto_key_security_level_t |
| * Enum to denote key security level. More... | |
| typedef enum otcrypto_lib_version | otcrypto_lib_version_t |
| * Enum to denote the crypto library version. More... | |
| typedef struct otcrypto_key_config | otcrypto_key_config_t |
| * Struct to represent the configuration of a blinded key. More... | |
| 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. More... | |
| 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 } |
| 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 } |
| 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 { kOtcryptoEccKeyModeEcdsa = 0x4e5, kOtcryptoEccKeyModeEcdh = 0x6bb, kOtcryptoEccKeyModeEd25519 = 0xd32, kOtcryptoEccKeyModeX25519 = 0x276 } |
| 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_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, kOtcryptoKeyModeHmacSha256, kOtcryptoKeyModeHmacSha384, kOtcryptoKeyModeHmacSha512, kOtcryptoKeyModeKmac128, kOtcryptoKeyModeKmac256, kOtcryptoKeyModeRsaSignPkcs, kOtcryptoKeyModeRsaSignPss, kOtcryptoKeyModeRsaEncryptOaep, kOtcryptoKeyModeEcdsa = kOtcryptoKeyTypeEcc << 16 | kOtcryptoEccKeyModeEcdsa, kOtcryptoKeyModeEcdh = kOtcryptoKeyTypeEcc << 16 | kOtcryptoEccKeyModeEcdh, kOtcryptoKeyModeEd25519, kOtcryptoKeyModeX25519, kOtcryptoKeyModeKdfCtrHmac, kOtcryptoKeyModeKdfKmac128, kOtcryptoKeyModeKdfKmac256 } |
| 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 | 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... | |
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.
| struct otcrypto_byte_buf |
Struct to hold a fixed-length byte array.
Note: the caller must (1) allocate sufficient space and (2) set the len field and data pointer when otcrypto_byte_buf_t is used for output. The crypto library will throw an error if len doesn't match expectations.
Definition at line 92 of file datatypes.h.
| Data Fields | ||
|---|---|---|
| uint8_t * | data | |
| size_t | len | |
| 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 107 of file datatypes.h.
| Data Fields | ||
|---|---|---|
| const uint8_t *const | data | |
| const size_t | len | |
| struct otcrypto_word32_buf |
Struct to hold a fixed-length word array.
Note: the caller must (1) allocate sufficient space and (2) set the len field and data pointer when otcrypto_word32_buf_t is used for output. The crypto library will throw an error if len doesn't match expectations.
Definition at line 121 of file datatypes.h.
| Data Fields | ||
|---|---|---|
| uint32_t * | data | |
| size_t | len | |
| 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 136 of file datatypes.h.
| Data Fields | ||
|---|---|---|
| const uint32_t *const | data | |
| const size_t | len | |
| struct otcrypto_key_config |
* Struct to represent the configuration of a blinded key.
Definition at line 381 of file datatypes.h.
| Data Fields | ||
|---|---|---|
| hardened_bool_t | exportable | |
| hardened_bool_t | hw_backed | |
| size_t | key_length | |
| otcrypto_key_mode_t | key_mode | |
| otcrypto_key_security_level_t | security_level | |
| otcrypto_lib_version_t | version | |
| struct otcrypto_unblinded_key |
Struct to handle unmasked key type.
Definition at line 401 of file datatypes.h.
| Data Fields | ||
|---|---|---|
| uint32_t | checksum | |
| uint32_t * | key | |
| size_t | key_length | |
| otcrypto_key_mode_t | key_mode | |
| struct otcrypto_blinded_key |
Struct to handle masked key type.
Definition at line 415 of file datatypes.h.
| Data Fields | ||
|---|---|---|
| uint32_t | checksum | |
| const otcrypto_key_config_t | config | |
| uint32_t * | keyblob | |
| const size_t | keyblob_length | |
| struct otcrypto_hash_digest |
Container for a hash digest.
Definition at line 459 of file datatypes.h.
| Data Fields | ||
|---|---|---|
| uint32_t * | data | |
| size_t | len | |
| otcrypto_hash_mode_t | mode | |
| 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.
| 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 and (2) set the len field and data pointer when otcrypto_byte_buf_t is used for output. The crypto library will throw an error if len doesn't match expectations.
| 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.
| 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.
| 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.
| typedef enum otcrypto_hash_mode otcrypto_hash_mode_t |
Enum to define supported hashing modes.
Values are hardened.
| 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.
| 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.
| typedef struct otcrypto_key_config otcrypto_key_config_t |
* Struct to represent the configuration of a blinded key.
| 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.
| 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.
| typedef enum otcrypto_key_type otcrypto_key_type_t |
Enum to denote the key type of the handled key.
Values are hardened.
| 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.
| 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.
| 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.
| 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 41 of file datatypes.h.
| 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 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.
| 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 and (2) set the len field and data pointer when otcrypto_word32_buf_t is used for output. The crypto library will throw an error if len doesn't match expectations.
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.
Definition at line 171 of file datatypes.h.
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.
Definition at line 245 of file datatypes.h.
| enum otcrypto_hash_mode |
Enum to define supported hashing modes.
Values are hardened.
Definition at line 431 of file datatypes.h.
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.
Definition at line 196 of file datatypes.h.
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.
Definition at line 264 of file datatypes.h.
| 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.
Definition at line 282 of file datatypes.h.
* 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.
Definition at line 354 of file datatypes.h.
| enum otcrypto_key_type |
Enum to denote the key type of the handled key.
Values are hardened.
Definition at line 148 of file datatypes.h.
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.
Definition at line 213 of file datatypes.h.
| 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.
Definition at line 373 of file datatypes.h.
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.
Definition at line 228 of file datatypes.h.
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 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 69 of file datatypes.h.