Google Git
Sign in
opensecura / 3p / lowrisc / opentitan / 024e3931ac443e863da0359846122a3eb36d7cd1 / . / sw / device / lib / crypto / api.h
blob: 5ddd2e92e538835c3b81e56afd3eddfcccf739d0 [file] [log] [blame]
// Copyright lowRISC contributors.
// Licensed under the Apache License, Version 2.0, see LICENSE for details.
// SPDX-License-Identifier: Apache-2.0
#ifndef OPENTITAN_SW_DEVICE_LIB_CRYPTO_API_H_
#define OPENTITAN_SW_DEVICE_LIB_CRYPTO_API_H_
/**
* @brief OS-facing API for the OpenTitan cryptography library.
*
* NOTE: This API is a work in progress, and the code here only records the
* current state. It will continue to change until the API design is finalized.
*/
#ifdef __cplusplus
extern "C" {
#endif // __cplusplus
/**
* Enum to handle return values of the crypto API.
*
* Values are hardened.
*/
typedef enum crypto_status {
// Status is OK; no errors.
kCryptoStatusOK = 0x7d3a,
// Invalid input arguments; Wrong length or invalid type.
kCryptoIncorrectInput = 0x6b7f,
// Inconsistencies when cross-checking results, witness, checksums.
kCryptoStatusInternalError = 0x4753,
// An asynchronous operation is still in progress.
kCryptoStatusAsyncIncomplete = 0xe2b7,
} crypto_status_t;
/**
* Enum to handle return values of the verification APIs.
*
* Values are hardened.
*/
typedef enum verification_status {
// Return value for successful verification.
kVerificationStatusPass = 0x2c89,
// Return value for unsuccessful verification.
kVerificationStatusFail = 0x49d3,
} verification_status_t;
/**
* Enum for opentitan crypto modes using a key.
*
* Used to denote crypto mode for which key usage is intended. Values are
* hardened.
*/
typedef enum key_mode {
// AES ECB mode.
kKeyModeAesEcb = 0x0101,
// AES CBC mode.
kKeyModeAesCbc = 0x0102,
// AES CFB mode.
kKeyModeAesCfb = 0x0103,
// AES OFB mode.
kKeyModeAesOfb = 0x0104,
// AES CTR mode.
kKeyModeAesCtr = 0x0105,
// AES GCM mode.
kKeyModeAesGcm = 0x0106,
// AES KWP mode.
kKeyModeAesKwp = 0x0107,
// HMAC-SHA-256.
kKeyModeHmacSha256 = 0x0201,
// KMAC-256.
kKeyModeKmac256 = 0x0202,
// RSA key generation.
kKeyModeRsaKeygen = 0x0301,
// RSA digital signature.
kKeyModeRsaSign = 0x0302,
// Elliptic curve key generation.
kKeyModeEccKeygen = 0x0401,
// Elliptic curve digital signature.
kKeyModeEccSign = 0x0402,
// Elliptic curve Diffie–Hellman key exchange.
kKeyModeEccEcdh = 0x0403,
} key_mode_t;
/**
* Type of blinded keys.
*
* This type is not exposed in the API because it should not be used directly.
*/
typedef struct crypto_blinded_key crypto_blinded_key_t;
/**
* Struct to handle unmasked key type.
*/
typedef struct crypto_unblinded_key {
// Mode for which the key usage is intended.
key_mode_t key_mode;
// Key length.
uint16_t key_length;
// Implementation specific, storage provided by caller.
uint32_t *key;
// Checksum for this struct.
uint32_t checksum;
} crypto_unblinded_key_t;
/**
* Enum to define AES mode of operation.
*/
typedef enum block_cipher_mode {
// AES ECB mode (electronic codebook mode).
kBlockCipherModeEcb = 0,
// AES CBC mode (cipher block chaining mode).
kBlockCipherModeCbc = 1,
// AES CFB mode (cipher feedback mode).
kBlockCipherModeCfb = 2,
// AES OFB mode (output feedback mode).
kBlockCipherModeOfb = 3,
// AES CTR mode (counter mode).
kBlockCipherModeCtr = 4,
} block_cipher_mode_t;
/**
* Enum to define AES operation to be performed.
*/
typedef enum aes_operation {
// AES operation mode encrypt.
kAesOperationEncrypt = 0,
// AES operation mode decrypt.
kAesOperationDecrypt = 1,
} aes_operation_t;
/**
* Enum to define padding scheme for AES data.
*/
typedef enum aes_padding {
// Pads with value same as the number of padding bytes.
kAesPaddingPkcs7 = 0,
// Pads with 0x80 (10000000), followed by zero bytes.
kAesPaddingIso9797M2 = 1,
// Pads with 0x00 bytes.
kAesPaddingIso9797M1 = 2,
// Pads with random bytes, last byte is no. of padded bytes.
kAesPaddingRandom = 3,
// Pads with 0x00 bytes, last byte is no. of padded bytes.
kAesPaddingX923 = 4,
// Add no padding.
kAesPaddingNull = 5,
} aes_padding_t;
/**
* Enum to define hashing mode.
*/
typedef enum hash_mode {
// SHA2-256 mode.
kHashModeSha256 = 0,
// SHA2-384 mode.
kHashModeSha384 = 1,
// SHA2-512 mode.
kHashModeSha512 = 2,
// SHA3-224 mode.
kHashModeSha3_224 = 3,
// SHA3-256 mode.
kHashModeSha3_256 = 4,
// SHA3-384 mode.
kHashModeSha3_384 = 5,
// SHA3-512 mode.
kHashModeSha3_512 = 6,
// SHA3-Shake128 mode.
kHashModeSha3Shake128 = 7,
// SHA3-Shake256 mode.
kHashModeSha3Shake256 = 8,
// SHA3-cShake128 mode.
kHashModeSha3Cshake128 = 9,
// SHA3-cShake256 mode.
kHashModeSha3Cshake256 = 10,
} hash_mode_t;
/**
* Enum to define MAC mode.
*/
typedef enum mac_mode {
// HMAC-SHA2-256 mode.
kMacModeHmacSha256 = 0,
// KMAC-128 mode.
kMacModeKmac128 = 1,
// KMAC-256 mode.
kMacModeKmac256 = 2,
} mac_mode_t;
/**
* Enum to define padding scheme for RSA data.
*/
typedef enum rsa_padding {
// Pads input data according to the PKCS#1-OAEP scheme.
kRsaPaddingOaep = 0,
// Pads input data according to the PKCS#1 (v1.5) scheme.
kRsaPaddingPkcs = 1,
// Pads input data according to the PKCS#1-PSS scheme.
kRsaPaddingPss = 2,
// NULL padding.
kRsaPaddingNull = 3,
} rsa_padding_t;
/**
* Enum to define hash modes for RSA scheme
*
* Aligning with existing HASH modes.
*/
typedef enum rsa_hash {
// SHA2-256 hashing mode for RSA.
kRsaHashSha256 = 0,
// SHA2-384 hashing mode for RSA.
kRsaHashSha384 = 1,
// SHA2-512 hashing mode for RSA.
kRsaHashSha512 = 2,
// SHA3-384 hashing mode for RSA.
kRsaHashSha3_384 = 3,
} rsa_hash_t;
/**
* Enum to define named elliptic curves.
*/
typedef enum ecc_named_curve {
// ECC named curve NIST P256.
kEccNamedCurveNistP256 = 0,
// ECC named curve NIST P384.
kEccNamedCurveNistP384 = 1,
// ECC named curve brainpool P256r1.
kEccNamedCurveBrainpoolP256R1 = 2,
} ecc_named_curve_t;
/**
* Struct to handle ECDSA or EdDSA signature.
*/
typedef struct ecc_signature {
// Length of ECC signature R parameter, in bytes.
size_t len_r;
// ECC signature R parameter.
uint32_t *r;
// Length of ECC signature S parameter, in bytes.
size_t len_s;
// ECC signature S parameter.
uint32_t *s;
} ecc_signature_t;
/**
* Enum to define EdDSA mode for signature.
*/
typedef enum eddsa_sign_mode {
// Signature mode EdDSA.
kEddsaSignModeEdDSA = 0,
// Signature mode Hashed EdDSA.
kEddsaSignModeHashEdDSA = 1,
} eddsa_sign_mode_t;
/**
* Struct to handle ECDSA or ECDH public key type.
*
* Length of public key coordinates (x,y) follows len(p).
*/
typedef struct ecc_public_key {
// ECC public key x coordinate.
uint32_t *x;
// ECC public key y coordinate.
uint32_t *y;
} ecc_public_key_t;
/**
* Struct to handle Ed25519 public key type.
*
* Length of encoded public key for Ed25519 is 256 bits (32 bytes).
*/
typedef struct ed25519_public_key {
// Public key for Ed25519.
uint32_t *pub_key;
} eddsa_public_key_t;
/**
* Struct for domain parameters for a generic Weierstrass elliptic curve.
*/
typedef struct ecc_domain {
// Length of p.
size_t len_p;
// Value of prime p (modulus of coordinate finite field).
uint32_t *p;
// Length of coefficient a.
size_t len_a;
// Value of coefficient a.
uint32_t *a;
// Length of coefficient b.
size_t len_b;
// Value of coefficient b.
uint32_t *b;
// Value of x coordinate of G (base point). Same length as p.
uint32_t *gx;
// Value of y coordinate of G (base point). Same length as p.
uint32_t *gy;
// Length of q.
size_t len_q;
// Value of q (order of G).
uint32_t *q;
// Cofactor of the curve.
uint32_t cofactor;
// Checksum value of the parameters.
uint32_t checksum;
} ecc_domain_t;
/**
* Struct to handle crypto data buffer with pointer and length.
*/
typedef struct crypto_uint8_buf {
// Pointer to the data.
uint8_t *data;
// Length of the data in bytes.
size_t len;
} crypto_uint8_buf_t;
/**
* Performs the AES initialization operation.
*
* The `aes_mode` and `aes_operation` are selected and the `key`, `iv`
* are loaded into the register.
*
* @param key Pointer to the blinded key struct with key shares
* @param iv Initialization vector, used for CBC, CFB, OFB, CTR modes
* @param aes_mode Required aes mode of operation
* @param aes_operation Required aes operation
* @return crypto_status_t The result of the init operation
*/
crypto_status_t aes_init(const crypto_blinded_key_t *key, crypto_uint8_buf_t iv,
block_cipher_mode_t aes_mode,
aes_operation_t aes_operation);
/**
* Performs the AES cipher operation.
*
* The #aes_init function should be called before this, to initialize
* the key, aes mode and aes cipher operation to be performed.
*
* The input data in the `cipher_input` is first padded using the
* aes_padding scheme, the output is placed in the `cipher_output`.
*
* @param cipher_input Input data to be ciphered
* @param aes_padding Padding scheme to be used for the data
* @param cipher_output Output data after cipher operation
* @return crypto_status_t The result of the cipher operation
*/
crypto_status_t aes_cipher(const crypto_uint8_buf_t cipher_input,
aes_padding_t aes_padding,
crypto_uint8_buf_t *cipher_output);
/**
* Performs the AES-GCM authenticated encryption operation.
*
* This function encrypts the input data `plaintext` to produce an
* `ciphertext` output. Additionally it generates an authentication
* tag `auth_tag` on both the (confidential) input data and any
* additional non-confidential authenticated data `aad`.
*
* @param key Pointer to the blinded gcm-key struct
* @param plaintext Input data to be encrypted and authenticated
* @param iv Initialization vector for the encryption function
* @param aad Additional authenticated data
* @param ciphertext Encrypted output data, same length as input data
* @param auth_tag Authentication tag
* @return crypto_status_t The result of the encryption operation
*/
crypto_status_t aes_encrypt_gcm(const crypto_blinded_key_t *key,
const crypto_uint8_buf_t plaintext,
crypto_uint8_buf_t iv, crypto_uint8_buf_t aad,
crypto_uint8_buf_t *ciphertext,
crypto_uint8_buf_t *auth_tag);
/**
* Performs the AES-GCM authenticated decryption operation.
*
* This function first verifies if the authentication tag `auth_tag`
* matches the internally generated tag. Upon verification, the
* function decrypts the input `ciphertext` to get a `plaintext data.
*
* @param key Pointer to the blinded gcm-key struct
* @param ciphertext Input data to be decrypted
* @param iv Initialization vector for the decryption function
* @param aad Additional authenticated data
* @param auth_tag Authentication tag to be verified
* @param plaintext Decrypted plaintext data, same len as input data
* @return crypto_status_t The result of the encryption operation
*/
crypto_status_t aes_decrypt_gcm(const crypto_blinded_key_t *key,
const crypto_uint8_buf_t ciphertext,
crypto_uint8_buf_t iv, crypto_uint8_buf_t aad,
crypto_uint8_buf_t auth_tag,
crypto_uint8_buf_t *plaintext);
/**
* AES-GCM context.
*
* Representation is internal to the AES implementation; initialize with
* #aes_gcm_init.
*/
typedef struct aes_gcm_context aes_gcm_context_t;
/**
* Initializes the AES-GCM engine.
*
* Generates the GHASH subkey H and pre-counter block J0 from the
* `key` and `iv`, and stores them in the `gcm_context` struct.
*
* @param gcm_context Pointer to the GCM context struct
* @param key Pointer to the blinded GCM key struct
* @param iv Initialization vector for the GCM function
* @return crypto_status_t The result of the init operation
*/
crypto_status_t aes_gcm_init(aes_gcm_context_t *gcm_context,
const crypto_blinded_key_t *key,
crypto_uint8_buf_t iv);
/**
* Updates the AAD value for the encryption/decryption function.
*
* After copying the aad, computes GHASH value and stores the result
* in the `gcm_context` state parameter.
*
* #aes_gcm_init should be called before calling this function.
*
* @param gcm_context Pointer to the GCM context struct
* @param aad Additional authenticated data
* @return crypto_status_t The result of the aad update operation
*/
crypto_status_t aes_gcm_aad_update(aes_gcm_context_t *gcm_context,
crypto_uint8_buf_t aad);
/**
* Performs the AES-GCM authenticated encryption update operation.
*
* This function encrypts the input data in `plaintext` and produces a
* `ciphertext` data as output. The partial data bytes are stored back
* in the `gcm_context` and combined with subsequent bytes or padded to
* block length for the last block. The intermediate result is stored in
* the `gcm_context` state parameter.
*
* #aes_gcm_init and if needed #aes_gcm_aad_update should be called
* before calling this function.
*
* @param gcm_context Pointer to the GCM context struct
* @param plaintext Input data to be encrypted and authenticated
* @param ciphertext Encrypted output data, same length as input data
* @return crypto_status_t The result of the init operation
*/
crypto_status_t aes_gcm_encrypt_update(aes_gcm_context_t *gcm_context,
const crypto_uint8_buf_t plaintext,
crypto_uint8_buf_t *ciphertext);
/**
* Performs the AES-GCM authenticated encryption final operation.
*
* This function pads the remaining partial data and encrypts the
* block. Computes GHASH of the updated state after and stores the
* result back in `gcm_context` state parameter, for tag generation.
*
* #aes_gcm_encrypt_update should be called before calling this
* function.
*
* @param gcm_context Pointer to the GCM context struct
* @param ciphertext Encrypted output data, same length as input data
* @return crypto_status_t The result of the init operation
*/
crypto_status_t aes_gcm_encrypt_final(aes_gcm_context_t *gcm_context,
crypto_uint8_buf_t *ciphertext);
/**
* Performs the authentication tag generation operation.
*
* Performs GCTR on the final state value stored in the `gcm_context`
* and returns the generated `auth_tag`.
*
* #aes_gcm_encrypt_final should be called before using this API.
*
* @param gcm_context Pointer to the GCM context struct
* @param auth_tag Authentication tag
* @return crypto_status_t The result of the tag generate operation
*/
crypto_status_t aes_gcm_generate_tag(aes_gcm_context_t *gcm_context,
crypto_uint8_buf_t *auth_tag);
/**
* Performs the pre-step for AES-GCM tag verification operation.
*
* Note: Tag should be verified before decrypting ciphertext.
*
* This function computes the final state value from the `ciphertext`
* and AAD data. The partial data bytes and intermediate result are
* stored back in the `gcm_context`.
*
* #aes_gcm_init and aes_gcm_aad_update should be called before using
* this function.
*
* @param gcm_context Pointer to the GCM context struct
* @param ciphertext Encrypted input data for tag generation
* @return crypto_status_t The return status of the verify update operation
*/
crypto_status_t aes_gcm_verify_tag_update(aes_gcm_context_t *gcm_context,
const crypto_uint8_buf_t ciphertext);
/**
* Performs the AES-GCM tag verification operation.
*
* Note: Tag should be verified before decrypting ciphertext.
*
* This function pads the remaining partial data and after that
* computes the authentication tag. The generated tag is verified
* against the input `auth_tag` for correctness.
*
* #aes_gcm_verify_tag_update should be called before using this function.
*
* @param gcm_context Pointer to the GCM context struct
* @param auth_tag Authentication tag
* @param verification_result Result of the tag verification (Pass/Fail)
* @return crypto_status_t The return status of the tag verify operation
*/
crypto_status_t aes_gcm_verify_tag_final(
aes_gcm_context_t *gcm_context, crypto_uint8_buf_t auth_tag,
verification_status_t *verification_result);
/**
* Performs the AES-GCM decryption update operation.
*
* Note: Decrypt should only be used after tag verification.
*
* This function generates `plaintext` from the `ciphertext` data. The
* partial data bytes and intermediate result are stored back in the
* `gcm_context`.
*
* #aes_gcm_init and aes_gcm_aad_update should be called before using
* this function.
*
* @param gcm_context Pointer to the GCM context struct
* @param ciphertext Input data to be decrypted
* @param plaintext Decrypted plaintext data, same len as input data
* @return crypto_status_t The result of the decrypt update operation
*/
crypto_status_t aes_gcm_decrypt_update(aes_gcm_context_t *gcm_context,
const crypto_uint8_buf_t ciphertext,
crypto_uint8_buf_t *plaintext);
/**
* Performs the AES-GCM authenticated decryption final operation.
*
* This function pads the remaining partial data and decrypts the
* block to `plaintext`.
*
* #aes_gcm_decrypt_update should be called before using this function.
*
* @param gcm_context Pointer to the GCM context struct
* @param ciphertext Input data to be decrypted
* @param plaintext Decrypted plaintext data, same len as input data
* @return crypto_status_t The result of the decrypt operation
*/
crypto_status_t aes_gcm_decrypt_final(aes_gcm_context_t *gcm_context,
crypto_uint8_buf_t *plaintext);
/**
* Performs the AES-KWP authenticated encryption operation.
*
* This encrypt function takes an input key `key_to_wrap` and using
* the encryption key `key_kek` outputs a wrapped key `wrapped_key`.
*
* @param key_to_wrap Pointer to the blinded key to be wrapped
* @param key_kek Input Pointer to the blinded encryption key
* @param wrapped_key Pointer to the output wrapped key
* @return crypto_status_t The result of the aes-kwp encrypt operation
*/
crypto_status_t aes_kwp_encrypt(const crypto_blinded_key_t *key_to_wrap,
const crypto_blinded_key_t *key_kek,
crypto_uint8_buf_t *wrapped_key);
/**
* Performs the AES-KWP authenticated decryption operation.
*
* This decrypt function takes a wrapped key `wrapped_key` and using
* encryption key `key_kek` outputs a unwrapped key `unwrapped_key`.
*
* @param wrapped_key Pointer to the input wrapped key
* @param key_kek Input Pointer to the blinded encryption key
* @param unwrapped_key Pointer to the output unwrapped key struct
* @return crypto_status_t The result of the aes-kwp decrypt operation
*/
crypto_status_t aes_kwp_decrypt(const crypto_uint8_buf_t wrapped_key,
const crypto_blinded_key_t *key_kek,
crypto_blinded_key_t *unwrapped_key);
/**
* Performs the required hash function on the input data.
*
* This function hashes the `input_message` with the selected hash
* function to return a `digest`. Supported hash modes are
* kHashModeSha256,kHashModeSha384, kHashModeSha512,
* kHashModeSha3_224, kHashModeSha3_256, kHashModeSha3_384 and
* kHashModeSha3_512.
*
* @param input_message Input message to be hashed
* @param hash_mode Required hash mode for the digest
* @param digest Output digest after hashing the input data
* @return crypto_status_t The result of the hash operation
*/
crypto_status_t hash(const crypto_uint8_buf_t input_message,
hash_mode_t hash_mode, crypto_uint8_buf_t *digest);
/**
* Performs the required hash xof function on the input data.
*
* This function hashes the `input_message` with the selected hash xof
* function and returns a `digest`. Supported hash modes are
* kHashModeSha3Shake128, kHashModeSha3Shake256,
* kHashModeSha3Cshake128 and kHashModeSha3Cshake256.
*
* The customization string is passed through `customization_string`
* parameter. If no customization is desired it can be empty.
*
* The function name is used to define functions based on cSHAKE. When
* no function other than cSHAKE is desired; it can be empty.
*
* The `function_name_string` and `customization_string` are ignored
* when the `hash_mode` is set to kHashModeSha3Shake128 or
* kHashModeSha3Shake256.
*
* @param input_message Input message to be hashed
* @param hash_mode Required hash mode for the digest
* @param function_name_string NIST Function name string
* @param customization_string Customization string for kmac
* @param required_output_len Requested output length from kmac
* @param digest Output digest after hashing the input data
* @return crypto_status_t The result of the cshake operation
*/
crypto_status_t hash_xof(const crypto_uint8_buf_t input_message,
hash_mode_t hash_mode,
crypto_uint8_buf_t function_name_string,
crypto_uint8_buf_t customization_string,
size_t required_output_len,
crypto_uint8_buf_t *digest);
/**
* Generic hash context.
*
* Representation is internal to the hash implementations; initialize with
* #hash_init.
*/
typedef struct hash_context hash_context_t;
/**
* Performs the generic hash init operation.
*
* Initializes the generic hash function. Populates the init, update
* and final function pointers, and digest, block sizes, by calling
* the respective init function requested by `hash_mode` parameter.
*
* @param ctx Pointer to the generic hash context struct
* @param hash_mode Required hash mode
* @return crypto_status_t The result of the init operation
*/
crypto_status_t hash_init(const hash_context_t *ctx, hash_mode_t hash_mode);
/**
* Performs the generic hash update operation.
*
* The update operation computes the required hash on `input_meaage`
* blocks. The intermediate digest is stored in the context `ctx` in
* the state parameter. Any partial data is stored back in the context
* and combined with subsequent bytes.
*
* #hash_init should be called before calling this function.
*
* @param ctx Pointer to the generic hash context struct
* @param input_message Input message to be hashed
* @return crypto_status_t The result of the update operation
*/
crypto_status_t hash_update(const hash_context_t *ctx,
const crypto_uint8_buf_t input_message);
/**
* Performs the generic hash final operation.
*
* The final operation computes the required hash on the remaining
* partial blocks if any, and then computes the final hash and stores
* it in the `digest` parameter.
*
* #hash_update should be called before calling this function.
*
* @param ctx Pointer to the generic hash context struct
* @param digest Output digest after hashing the input blocks
* @return crypto_status_t The result of the final operation
*/
crypto_status_t hash_final(const hash_context_t *ctx,
crypto_uint8_buf_t *digest);
/**
* Performs the SHA2-256 init operation.
*
* Initializes the SHA2-256 parameters in the `ctx` context, such as the
* init, update, final functions to use and the digest, block sizes.
*
* @param ctx Pointer to the generic hash context struct
* @return crypto_status_t The result of the init operation
*/
crypto_status_t sha256_init(const hash_context_t *ctx);
/**
* Performs the SHA2-256 update operation.
*
* The update operation computes the SHA2-256 hash on the `input_message`
* blocks. The intermediate digest is stored in the context `ctx` in
* the state parameter. Any partial data is stored back in the context
* and combined with subsequent bytes.
*
* @param ctx Pointer to the generic hash context struct
* @param input_message Input message to be hashed
* @return crypto_status_t The result of the update operation
*/
crypto_status_t sha256_update(const hash_context_t *ctx,
const crypto_uint8_buf_t input_message);
/**
* Performs the SHA2-256 final operation.
*
* The final operation computes the SHA2-256 hash on the remaining
* partial blocks if any, and then computes the final hash and stores
* it in the `digest` parameter.
*
* @param ctx Pointer to the generic hash context struct
* @param digest Output digest after hashing the input blocks
* @return crypto_status_t The result of the final operation
*/
crypto_status_t sha256_final(const hash_context_t *ctx,
crypto_uint8_buf_t *digest);
/**
* Performs the SHA2-384 init operation.
*
* Initializes the SHA2-384 parameters in the `ctx` context, such as the
* init, update, final functions to use and the digest, block sizes.
*
* @param ctx Pointer to the generic hash context struct
* @return crypto_status_t The result of the init operation
*/
crypto_status_t sha384_init(const hash_context_t *ctx);
/**
* Performs the SHA2-384 update operation.
*
* The update operation computes the SHA2-384 hash on the `input_meaage`
* blocks. The intermediate digest is stored in the context `ctx` in
* the state parameter. Any partial data is stored back in the context
* and combined with subsequent bytes.
*
* @param ctx Pointer to the generic hash context struct
* @param input_message Input message to be hashed
* @return crypto_status_t The result of the update operation
*/
crypto_status_t sha384_update(const hash_context_t *ctx,
const crypto_uint8_buf_t input_message);
/**
* Performs the SHA2-384 final operation.
*
* The final operation computes the SHA2-384 hash on the remaining
* partial blocks if any, and then computes the final hash and stores
* it in the `digest` parameter.
*
* @param ctx Pointer to the generic hash context struct
* @param digest Output digest after hashing the input blocks
* @return crypto_status_t The result of the final operation
*/
crypto_status_t sha384_final(const hash_context_t *ctx,
crypto_uint8_buf_t *digest);
/**
* Performs the SHA2-512 init operation.
*
* Initializes the SHA2-512 parameters in the `ctx` context, such as the
* init, update, final functions to use and the digest, block sizes.
*
* @param ctx Pointer to the generic hash context struct
* @return crypto_status_t The result of the init operation
*/
crypto_status_t sha512_init(const hash_context_t *ctx);
/**
* Performs the SHA2-512 update operation.
*
* The update operation computes the SHA2-512 hash on the `input_meaage`
* blocks. The intermediate digest is stored in the context `ctx` in
* the state parameter. Any partial data is stored back in the context
* and combined with subsequent bytes.
*
* @param ctx Pointer to the generic hash context struct
* @param input_message Input message to be hashed
* @return crypto_status_t The result of the update operation
*/
crypto_status_t sha512_update(const hash_context_t *ctx,
const crypto_uint8_buf_t input_message);
/**
* Performs the SHA2-512 final operation.
*
* The final operation computes the SHA2-512 hash on the remaining
* partial blocks if any, and then computes the final hash and stores
* it in the `digest` parameter.
*
* @param ctx Pointer to the generic hash context struct
* @param digest Output digest after hashing the input blocks
* @return crypto_status_t The result of the final operation
*/
crypto_status_t sha512_final(const hash_context_t *ctx,
crypto_uint8_buf_t *digest);
/**
* Performs the MAC (HMAC/KMAC) hash function on the input data.
*
* Supported MAC modes are kMacModeHmacSha256, kMacModeKmac128 and
* kMacModeKmac256.
*
* HMAC: This function computes the required mac function on the
* `input_message` using the `key` and returns a `digest`.
*
* KMAC: This function computes the kmac on the `input_message` using
* the `key` and returns a `digest` of `required_output_len`. The
* customization string is passed through `customization_string`
* parameter. If no customization is desired it can be empty.
*
* The `customization_string` and `required_output_len` is only used
* for kmac modes kMacModeKmac128 and kMacModeKmac256, and is ignored
* when the required mode is set to kMacModeHmacSha256.
*
* @param key Pointer to the blinded key struct with key shares
* @param input_message Input message to be hashed
* @param mac_mode Required MAC mode for the digest (HMAC/KMAC)
* @param customization_string Customization string for kmac
* @param required_output_len Requested output length from kmac
* @param digest Output digest after hashing the input data
* @return crypto_status_t The result of the kmac128 operation
*/
crypto_status_t mac(const crypto_blinded_key_t *key,
const crypto_uint8_buf_t input_message, mac_mode_t mac_mode,
crypto_uint8_buf_t customization_string,
size_t required_output_len, crypto_uint8_buf_t *digest);
/**
* Generic HMAC context.
*
* Representation is internal to the HMAC implementations; initialize with
* #hmac_init.
*/
typedef struct hmac_context hmac_context_t;
/**
* Performs the generic HMAC init operation.
*
* Initializes the generic HMAC function. Populates the init, update
* and final function pointers, and digest, block sizes, by calling
* the respective init function as requested by `hash_mode` parameter.
*
* @param ctx Pointer to the generic HMAC context struct
* @param key Pointer to the blinded HMAC key struct
* @param hash_mode Required hash mode
* @return crypto_status_t The result of the init operation
*/
crypto_status_t hmac_init(const hash_context_t *ctx,
const crypto_blinded_key_t *key,
hash_mode_t hash_mode);
/**
* Performs the generic HMAC update operation.
*
* The update operation computes the required hash on `input_meaage`
* blocks. The intermediate digest is stored in the context `ctx`, in
* the state parameter. Any partial data is stored back in the context
* and combined with subsequent bytes after.
*
* #hmac_init should be called before calling this function.
*
* @param ctx Pointer to the generic HMAC context struct
* @param input_message Input message to be hashed
* @return crypto_status_t The result of the init operation
*/
crypto_status_t hmac_update(const hash_context_t *ctx,
const crypto_uint8_buf_t input_message);
/**
* Performs the generic HMAC final operation.
*
* The final operation computes the hash function on the remaining
* partial blocks if any, and then computes the final hash, and stores
* the result in the `digest` parameter.
*
* #hmac_update should be called before calling this function.
*
* @param ctx Pointer to the generic HMAC context struct
* @param digest Output digest after hashing the input blocks
* @return crypto_status_t The result of the final operation
*/
crypto_status_t hmac_final(const hash_context_t *ctx,
crypto_uint8_buf_t *digest);
/**
* Performs the HMAC SHA2-256 init operation.
*
* Initializes the HMAC SHA2-256 parameters in the `ctx` context, such
* as the init, update, final functions to use and respective digest,
* block sizes.
*
* @param ctx Pointer to the generic HMAC context struct
* @param key Pointer to the blinded HMAC key struct
* @return crypto_status_t The result of the init operation
*/
crypto_status_t hmac_sha256_init(const hash_context_t *ctx,
const crypto_blinded_key_t *key);
/**
* Performs the hmac-SHA2-256 update operation.
*
* The update operation computes the required hash on `input_meaage`
* blocks. The intermediate digest is stored in the context `ctx`, in
* the state parameter. Any partial data is stored back in the context
* and combined with subsequent bytes after.
*
* @param ctx Pointer to the generic HMAC context struct
* @param input_message Input message to be hashed
* @return crypto_status_t The result of the update operation
*/
crypto_status_t hmac_sha256_update(const hash_context_t *ctx,
const crypto_uint8_buf_t input_message);
/**
* Performs the hmac-SHA2-256 final operation.
*
* The final operation computes the hash function on the remaining
* partial blocks if any, and then computes the final hash, and stores
* the result in the `digest` parameter.
*
* @param ctx Pointer to the generic HMAC context struct
* @param digest Output digest after hashing the input blocks
* @return crypto_status_t The result of the final operation
*/
crypto_status_t hmac_sha256_final(const hash_context_t *ctx,
crypto_uint8_buf_t *digest);
/**
* Performs the RSA key generation.
*
* Computes RSA private key (d) and RSA public key exponent (e) and
* modulus (n). DRBG state is passed as an input parameter.
*
* @param drbg_state Pointer to the DRBG working state
* @param additional_input Pointer to the additional input for DRBG
* @param required_key_len Requested key length in bits
* @param n Pointer to un-blinded key struct with modulus
* @param e Pointer to un-blinded key struct with public exponent
* @param d Pointer to blinded key struct with private exponent
* @return crypto_status_t The result of the RSA key generation
*/
crypto_status_t rsa_keygen(drbg_state_t *drbg_state,
crypto_uint8_buf_t additional_input,
size_t required_key_len, crypto_unblinded_key_t *n,
crypto_unblinded_key_t *e, crypto_blinded_key_t *d);
/**
* Computes the digital signature on the input message data.
*
* @param n Pointer to un-blinded key struct with modulus (n)
* @param d Pointer to blinded key struct with private exponent (d)
* @param input_message Input message to be signed
* @param padding_mode Padding scheme to be used for the data
* @param hash_mode Hashing scheme to be used for the signature scheme
* @param signature Pointer to generated signature struct
* @return crypto_status_t The result of the RSA sign generation
*/
crypto_status_t rsa_sign(crypto_unblinded_key_t *n, crypto_blinded_key_t *d,
const crypto_uint8_buf_t input_message,
rsa_padding_t padding_mode, rsa_hash_t hash_mode,
crypto_uint8_buf_t *signature);
/**
* Verifies the authenticity of the input signature.
*
* The generated signature is compared against the input signature and
* PASS / FAIL is returned.
*
* @param n Pointer to un-blinded key struct with modulus (n)
* @param e Pointer to un-blinded key struct with public exponent (e)
* @param input_message Input message to be signed for verification
* @param padding_mode Padding scheme to be used for the data
* @param hash_mode Hashing scheme to be used for the signature scheme
* @param signature Pointer to the signature to be verified
* @param verification_result Returns the result of signature verification
* (Pass/Fail)
* @return crypto_status_t The return status of the RSA verify operation
*/
crypto_status_t rsa_verify(crypto_unblinded_key_t *n, crypto_unblinded_key_t *e,
const crypto_uint8_buf_t input_message,
rsa_padding_t padding_mode, rsa_hash_t hash_mode,
crypto_uint8_buf_t signature,
verification_status_t *verification_result);
/**
* Performs the RSA key generation, asynchronously.
*
* Computes RSA private key (d) and RSA public key exponent (e) and
* modulus (n). DRBG state is passed as an input parameter.
*
* @param drbg_state Pointer to the DRBG working state
* @param additional_input Pointer to the additional input for DRBG
* @param required_key_len Requested key length in bits
* @param n Pointer to un-blinded key struct with modulus (n)
* @param e Pointer to un-blinded key struct with public exponent (e)
* @param d Pointer to blinded key struct with private exponent (d)
* @return crypto_status_t The result of the RSA key generation
*/
crypto_status_t rsa_keygen_async(drbg_state_t *drbg_state,
crypto_uint8_buf_t additional_input,
size_t required_key_len,
crypto_unblinded_key_t *n,
crypto_unblinded_key_t *e,
crypto_blinded_key_t *d);
/**
* Computes the digital signature on the input message data, async.
*
* @param n Pointer to un-blinded key struct with modulus (n)
* @param d Pointer to blinded key struct with private exponent (d)
* @param input_message Input message to be signed
* @param padding_mode Padding scheme to be used for the data
* @param hash_mode Hashing scheme to be used for the signature scheme
* @param signature Pointer to generated signature struct
* @return crypto_status_t The result of the RSA sign generation
*/
crypto_status_t rsa_sign_async(crypto_unblinded_key_t *n,
crypto_blinded_key_t *d,
const crypto_uint8_buf_t input_message,
rsa_padding_t padding_mode, rsa_hash_t hash_mode,
crypto_uint8_buf_t *signature);
/**
* Verifies the authenticity of the input signature, asynchronously.
*
* The generated signature is compared against the input signature and
* PASS / FAIL is returned.
*
* @param n Pointer to un-blinded key struct with modulus (n)
* @param e Pointer to un-blinded key struct with public exponent (e)
* @param input_message Input message to be signed for verification
* @param padding_mode Padding scheme to be used for the data
* @param hash_mode Hashing scheme to be used for the signature scheme
* @param signature Pointer to the signature to be verified
* @param verification_result Returns the result of signature verification
* (Pass/Fail)
* @return crypto_status_t The return status of the RSA verify operation
*/
crypto_status_t rsa_verify_async(crypto_unblinded_key_t *n,
crypto_unblinded_key_t *e,
const crypto_uint8_buf_t input_message,
rsa_padding_t padding_mode,
rsa_hash_t hash_mode,
crypto_uint8_buf_t signature,
verification_status_t *verification_result);
/**
* Sets the domain parameters of a generic Weierstrass curve.
*
* @param domain_parameters Pointer to the ECC curve domain parameters
* @return crypto_status_t The result of the ECC set domain operation
*/
crypto_status_t ecc_set_domain(ecc_domain_t domain_parameters);
/**
* Sets the domain parameters of a named Weierstrass curve.
*
* @param named_curve Named curve to set domain parameters for
* @return crypto_status_t The result of the ECC set domain operation
*/
crypto_status_t ecc_set_domain_named(ecc_named_curve_t named_curve);
/**
* Performs ECDSA/ECDH key generation.
*
* Computes private key (d) and public key (Q). DRBG state is passed as an
* input parameter.
*
* @param drbg_state Pointer to the DRBG working state
* @param additional_input Pointer to the additional input for DRBG
* @param required_key_len Requested key length in bits
* @param private_key Pointer to the blinded private key (d) struct
* @param public_key Pointer to the unblinded public key (Q) struct
* @return crypto_status_t The result of the key generation
*/
crypto_status_t ecc_keygen(drbg_state_t *drbg_state,
crypto_uint8_buf_t additional_input,
size_t required_key_len,
crypto_blinded_key_t *private_key,
ecc_public_key_t *public_key);
/**
* Performs ECDSA digital signature generation.
*
* @param private_key Pointer to the blinded private key (d) struct
* @param input_message Input message to be signed
* @param signature Pointer to the signature struct with (r,s) values
* @return crypto_status_t Result of the signature operation
*/
crypto_status_t ecdsa_sign(crypto_blinded_key_t *private_key,
const crypto_uint8_buf_t input_message,
ecc_signature_t *signature);
/**
* Performs ECDSA digital signature verification.
*
* @param public_key Pointer to the unblinded public key (Q) struct
* @param input_message Input message to be signed for verification
* @param signature Pointer to the signature to be verified
* @param verification_result Returns the result of signature verification
* (Pass/Fail)
* @return crypto_status_t Return status of the verification operation
*/
crypto_status_t ecdsa_verify(ecc_public_key_t *public_key,
const crypto_uint8_buf_t input_message,
ecc_signature_t *signature,
verification_status_t *verification_result);
/**
* Performs Elliptic Curve Diffie Hellman shared secret generation.
*
* @param private_key Pointer to the blinded private key (d) struct
* @param public_key Pointer to the unblinded public key (Q) struct
* @param shared_secret Pointer to generated blinded shared key struct
* @return crypto_status_t Result of the ecdh operation
*/
crypto_status_t ecdh(crypto_blinded_key_t *private_key,
ecc_public_key_t *public_key,
crypto_blinded_key_t *shared_secret);
/**
* Performs the X25519 Diffie Hellman shared secret generation.
*
* @param private_key Pointer to the blinded private key (u-coordinate)
* @param public_key Pointer to the public scalar from the sender
* @param shared_secret Pointer to shared secret key (u-coordinate)
* @return crypto_status_t Result of the ecdh operation
*/
crypto_status_t x25519(crypto_blinded_key_t *private_key,
crypto_uint8_buf_t *public_key,
crypto_blinded_key_t *shared_secret);
/**
* Performs key generation for Ed25519.
*
* Computes the private exponent (d) and public key (Q) based on
* Curve25519. DRBG state is passed as an input parameter.
*
* @param drbg_state Pointer to the DRBG working state
* @param additional_input Pointer to the additional input for DRBG
* @param required_key_len Requested key len in bits (256 for Ed25519)
* @param private_key Pointer to the blinded private key struct
* @param public_key Pointer to the unblinded public key struct
* @return crypto_status_t The result of the ecdsa key generation
*/
crypto_status_t ed25519_keygen(drbg_state_t *drbg_state,
crypto_uint8_buf_t additional_input,
size_t required_key_len,
crypto_blinded_key_t *private_key,
eddsa_public_key_t *public_key);
/**
* Performs EdDSA digital signature generation for Ed25519.
*
* @param private_key Pointer to the blinded private key struct
* @param input_message Input message to be signed
* @param sign_mode Parameter for EdDSA or Hash EdDSA sign mode
* @param signature Pointer to the EdDSA signature with (r,s) values
* @return crypto_status_t Result of the EdDSA signature operation
*/
crypto_status_t ed25519_sign(crypto_blinded_key_t *private_key,
const crypto_uint8_buf_t input_message,
eddsa_sign_mode_t sign_mode,
ecc_signature_t *signature);
/**
* Performs EdDSA signature verification for Ed25519.
*
* @param public_key Pointer to the unblinded public key struct
* @param input_message Input message to be signed for verification
* @param sign_mode Parameter for EdDSA or Hash EdDSA sign mode
* @param signature Pointer to the signature to be verified
* @param verification_result Returns the result of signature verification
* (Pass/Fail)
* @return crypto_status_t Return status of the EdDSA verification operation
*/
crypto_status_t ed25519_verify(edd_public_key_t *public_key,
const crypto_uint8_buf_t input_message,
eddsa_sign_mode_t sign_mode,
ecc_signature_t *signature,
verification_status_t *verification_result);
/**
* Performs ECDSA/ECDH key generation, asynchronously.
*
* Computes private exponent (d) and public key (Q). DRBG state is
* passed as an input parameter.
*
* @param drbg_state Pointer to the DRBG working state
* @param additional_input Pointer to the additional input for DRBG
* @param required_key_len Requested key length in bits
* @param private_key Pointer to the blinded private key (d) struct
* @param public_key Pointer to the unblinded public key (Q) struct
* @return crypto_status_t The result of the ECC key generation
*/
crypto_status_t ecc_keygen_async(drbg_state_t *drbg_state,
crypto_uint8_buf_t additional_input,
size_t required_key_len,
crypto_blinded_key_t *private_key,
ecc_public_key_t *public_key);
/**
* Performs the key generation for EdDSA, asynchronously.
*
* Computes EdDSA private exponent (d) and public key (Q). DRBG
* state is passed as an input parameter.
*
* @param drbg_state Pointer to the DRBG working state
* @param additional_input Pointer to the additional input for DRBG
* @param required_key_len Requested key len in bits (256 for Ed25519)
* @param private_key Pointer to the blinded private key struct
* @param public_key Pointer to the unblinded public key struct
* @return crypto_status_t The result of the ecdsa key generation
*/
crypto_status_t eddsa_keygen_async(drbg_state_t *drbg_state,
crypto_uint8_buf_t additional_input,
size_t required_key_len,
crypto_blinded_key_t *private_key,
eddsa_public_key_t *public_key);
/**
* Performs ECDSA digital signature generation, asynchronously.
*
* @param private_key Pointer to the blinded private key (d) struct
* @param input_message Input message to be signed
* @param signature Pointer to the ECC sign struct with (r,s) values
* @return crypto_status_t Result of the ECC signature operation
*/
crypto_status_t ecdsa_sign_async(crypto_blinded_key_t *private_key,
const crypto_uint8_buf_t input_message,
ecc_signature_t *signature);
/**
* Performs ECDSA digital signature verification, asynchronously.
*
* @param public_key Pointer to the unblinded public key (Q) struct
* @param input_message Input message to be signed for verification
* @param signature Pointer to the signature to be verified
* @param verification_result Returns the result of signature verification
* (Pass/Fail)
* @return crypto_status_t Return status of the ECC verification operation
*/
crypto_status_t ecdsa_verify_async(ecc_public_key_t *public_key,
const crypto_uint8_buf_t input_message,
ecc_signature_t *signature,
verification_status_t *verification_result);
/**
* Performs the EdDSA digital signature generation for Ed25519,
* asynchronously.
*
* @param private_key Pointer to the blinded private key struct
* @param input_message Input message to be signed
* @param sign_mode Parameter for EdDSA or Hash EdDSA sign mode
* @param signature Pointer to the EdDSA signature with (r,s) values
* @return crypto_status_t Result of the EdDSA signature operation
*/
crypto_status_t ed25519_sign_async(crypto_blinded_key_t *private_key,
const crypto_uint8_buf_t input_message,
eddsa_sign_mode_t sign_mode,
ecc_signature_t *signature);
/**
* Performs the EdDSA signature verification for Ed25519,
* asynchronously.
*
* @param public_key Pointer to the unblinded public key struct
* @param input_message Input message to be signed for verification
* @param sign_mode Parameter for EdDSA or Hash EdDSA sign mode
* @param signature Pointer to the signature to be verified
* @param verification_result Returns the result of signature verification
* (Pass/Fail)
* @return crypto_status_t Return status of the EdDSA verification operation
*/
crypto_status_t ed25519_verify_async(
edd_public_key_t *public_key, const crypto_uint8_buf_t input_message,
eddsa_sign_mode_t sign_mode, ecc_signature_t *signature,
verification_status_t *verification_result);
/**
* DRBG state.
*/
typedef struct drbg_state drbg_state_t;
/**
* Initializes the DRBG.
*
* Initializes DRBG and the context parameter for DRBG. Gets the
* entropy input automatically from the entropy source.
*
* @param drbg_state Pointer to the DRBG working state
* @param nonce Pointer to the nonce bit-string
* @param personalization_string Pointer to personalization bitstring
* @return crypto_status_t Result of the DRBG instantiate operation
*/
crypto_status_t drbg_instantiate(drbg_state_t *drbg_state,
crypto_uint8_buf_t nonce,
crypto_uint8_buf_t personalization_string);
/**
* Reseeds the DRBG with fresh entropy.
*
* Reseeds the DRBG with fresh entropy automatically fetched from the
* entropy source and updates the working state parameters.
*
* @param drbg_state Pointer to the DRBG working state
* @param additional_input Pointer to the additional input for DRBG
* @return crypto_status_t Result of the DRBG reseed operation
*/
crypto_status_t drbg_reseed(drbg_state_t *drbg_state,
crypto_uint8_buf_t additional_input);
/**
* Initializes the DRBG.
*
* Initializes DRBG and the context parameter for DRBG. Gets the
* entropy input from the user through `entropy` parameter.
*
* @param drbg_state Pointer to the DRBG working state
* @param entropy Pointer to the user defined entropy value
* @param nonce Pointer to the nonce bit-string
* @param personalization_string Pointer to personalization bitstring
* @return crypto_status_t Result of the DRBG instantiate operation
*/
crypto_status_t drbg_manual_instantiate(
drbg_state_t *drbg_state, crypto_uint8_buf_t entropy,
crypto_uint8_buf_t nonce, crypto_uint8_buf_t personalization_string);
/**
* Reseeds the DRBG with fresh entropy.
*
* Reseeds the DRBG with entropy input from the user through `entropy`
* parameter and updates the working state parameters.
*
* @param drbg_state Pointer to the DRBG working state
* @param entropy Pointer to the user defined entropy value
* @param additional_input Pointer to the additional input for DRBG
* @return crypto_status_t Result of the DRBG reseed operation
*/
crypto_status_t drbg_manual_reseed(drbg_state_t *drbg_state,
crypto_uint8_buf_t entropy,
crypto_uint8_buf_t additional_input);
/**
* DRBG function for generating random bits.
*
* Used to generate pseudo random bits after DRBG instantiation or
* DRBG reseeding.
*
* @param drbg_state Pointer to the DRBG working state
* @param additional_input Pointer to the additional data
* @param drbg_output Pointer to the generated pseudo random bits
* @return crypto_status_t Result of the DRBG generate operation
*/
crypto_status_t drbg_generate(drbg_state_t *drbg_state,
crypto_uint8_buf_t additional_input,
crypto_uint8_buf_t *drbg_output);
/**
* Uninstantiates DRBG and clears the context.
*
* @param drbg_state Pointer to the DRBG working state
* @return crypto_status_t Result of the DRBG uninstantiate operation
*/
crypto_status_t drbg_uninstantiate(drbg_state_t *drbg_state);
#ifdef __cplusplus
} // extern "C"
#endif // __cplusplus
#endif // OPENTITAN_SW_DEVICE_LIB_CRYPTO_API_H_