2. CMOX_CRYPTO

2.1. Cipher module

group CMOX_CIPHER

Defines

CMOX_CIPHER_BLOCK_SIZE

Block size, in words, of a block cipher (AES and SM4)

CMOX_SM4_EXPKEY_SIZE

Size, in words, of the expanded SM4 key

CMOX_AES128_EXPKEY_SIZE

Size, in words, of the expanded AES128 key

CMOX_AES192_EXPKEY_SIZE

Size, in words, of the expanded AES192 key

CMOX_AES256_EXPKEY_SIZE

Size, in words, of the expanded AES256 key

Typedefs

typedef const struct cmox_blockcipher_vtableStruct_st * cmox_blockcipher_vtable_t

Block cipher algorithm type.

This type is defined as a pointer to a structure that contains the functions needed for the specific algorithm, as defined internally in the library.

struct cmox_blockcipher_handle_t

#include <cmox_blockcipher.h>

Block cipher context handle.

Public Members

cmox_blockcipher_vtable_t table

Used block cipher algorithm

cmox_cipher_keyLen_t keyLen

Size, in bytes, of the block cipher’s key

uint32_t internalState

Internal state of the block cipher

uint32_t expandedKey [ CMOX_AES256_EXPKEY_SIZE ]

Buffer containing the expanded key

Typedefs

typedef const struct cmox_cbc_implStruct_st * cmox_cbc_impl_t

CBC mode implementation.

This type specifies the used block cipher for the CBC construct and if the algorithm will be used for encryption or decryption. This type is defined as a pointer to a structure, that contains the functions needed for the specific implementation, defined in the library internally

struct cmox_cbc_handle_t

#include <cmox_cbc.h>

CBC handle structure definition.

Public Members

cmox_cipher_handle_t super

General cipher handle

cmox_blockcipher_handle_t blockCipher

Block cipher handle

uint32_t iv [ CMOX_CIPHER_BLOCK_SIZE ]

Buffer containing the Initialization Vector

Variables

const cmox_cbc_impl_t CMOX_AESFAST_CBC_ENC

Implementation of CBC encryption using AES (fast implementation) (Defined internally).

const cmox_cbc_impl_t CMOX_AESFAST_CBC_DEC

Implementation of CBC decryption using AES (fast implementation) (Defined internally).

const cmox_cbc_impl_t CMOX_AESSMALL_CBC_ENC

Implementation of CBC encryption using AES (small implementation) (Defined internally).

const cmox_cbc_impl_t CMOX_AESSMALL_CBC_DEC

Implementation of CBC decryption using AES (small implementation) (Defined internally).

const cmox_cbc_impl_t CMOX_SM4_CBC_ENC

Implementation of CBC encryption using SM4 (Defined internally).

const cmox_cbc_impl_t CMOX_SM4_CBC_DEC

Implementation of CBC decryption using SM4 (Defined internally).

Variables

const cmox_cipher_algo_t CMOX_AESSMALL_CBC_ENC_ALGO

Identifier of the CBC encryption using AES (small implementation) for single-call function (Defined internally).

const cmox_cipher_algo_t CMOX_AESSMALL_CBC_DEC_ALGO

Identifier of the CBC decryption using AES (small implementation) for single-call function (Defined internally).

const cmox_cipher_algo_t CMOX_AESFAST_CBC_ENC_ALGO

Identifier of the CBC encryption using AES (fast implementation) for single-call function (Defined internally).

const cmox_cipher_algo_t CMOX_AESFAST_CBC_DEC_ALGO

Identifier of the CBC decryption using AES (fast implementation) for single-call function (Defined internally).

const cmox_cipher_algo_t CMOX_SM4_CBC_ENC_ALGO

Identifier of the CBC encryption using SM4 for single-call function (Defined internally).

const cmox_cipher_algo_t CMOX_SM4_CBC_DEC_ALGO

Identifier of the CBC decryption using SM4 for single-call function (Defined internally).

Functions

cmox_cipher_handle_t * cmox_cbc_construct ( cmox_cbc_handle_t * P_pThis , cmox_cbc_impl_t P_impl )

CBC constructor.

The function is used for specifying which block cipher algorithm to use in order to implement the CBC algorithm and if the algorithm will be used for encryption or decryption.

Parameters :

• P_pThis – Pointer to the CBC handle to initialize

• P_impl – Constant that specifies the implementation to use. This parameter can be one of the following values:

  • CMOX_AESFAST_CBC_ENC

  • CMOX_AESFAST_CBC_DEC

  • CMOX_AESSMALL_CBC_ENC

  • CMOX_AESSMALL_CBC_DEC

  • CMOX_SM4_CBC_ENC

  • CMOX_SM4_CBC_DEC

Returns :

cmox_cipher_handle_t* Pointer to a general cipher handle. This will be used by the general purpose cipher functions in order to perform the algorithm

Typedefs

typedef const struct cmox_ccm_implStruct_st * cmox_ccm_impl_t

CCM mode implementation.

This type specifies the used block cipher for the CCM construct and if the algorithm will be used for encryption or decryption. This type is defined as a pointer to a structure, that contains the functions needed for the specific implementation, defined in the library internally

struct cmox_ccm_handle_t

#include <cmox_ccm.h>

CCM handle structure.

Public Members

cmox_cipher_handle_t super

General cipher handle

cmox_blockcipher_handle_t blockCipher

Block cipher handle

uint32_t ivCtr [ 4 ]

Current IV value for encryption.

uint32_t ivCbc [ 4 ]

Current IV value for authentication.

size_t tagLen

Size of the tag to return. Possible values are values are {4,6,8,10,12,14,16}

size_t AdLen

Len of the associated data to be processed

size_t payloadLen

Size of the total payload data to be processed

size_t nonceLen

Size of the Nonce in bytes. Possible values are {7,8,9,10,11,12,13}

uint32_t tmpBuf [ 4 ]

Temporary buffer used for internal computations

uint32_t tmpBufUse

Number of bytes in use for internal computations

Variables

const cmox_ccm_impl_t CMOX_AESFAST_CCM_ENC

Implementation of CCM encryption using AES (fast implementation) (Defined internally).

const cmox_ccm_impl_t CMOX_AESFAST_CCM_DEC

Implementation of CCM decryption using AES (fast implementation) (Defined internally).

const cmox_ccm_impl_t CMOX_AESSMALL_CCM_ENC

Implementation of CCM encryption using AES (small implementation) (Defined internally).

const cmox_ccm_impl_t CMOX_AESSMALL_CCM_DEC

Implementation of CCM decryption using AES (small implementation) (Defined internally).

Variables

const cmox_aead_algo_t CMOX_AESSMALL_CCM_ENC_ALGO

Identifier of the CCM encryption using AES (small implementation) for single-call function (Defined internally).

const cmox_aead_algo_t CMOX_AESSMALL_CCM_DEC_ALGO

Identifier of the CCM decryption using AES (small implementation) for single-call function (Defined internally).

const cmox_aead_algo_t CMOX_AESFAST_CCM_ENC_ALGO

Identifier of the CCM encryption using AES (fast implementation) for single-call function (Defined internally).

const cmox_aead_algo_t CMOX_AESFAST_CCM_DEC_ALGO

Identifier of the CCM decryption using AES (fast implementation) for single-call function (Defined internally).

Functions

cmox_cipher_handle_t * cmox_ccm_construct ( cmox_ccm_handle_t * P_pThis , cmox_ccm_impl_t P_impl )

CCM constructor.

The function is used for specifying which block cipher algorithm to use in order to implement the CCM algorithm and if the algorithm will be used for encryption or decryption.

Parameters :

• P_pThis – Pointer to the CCM handle to initialize

• P_impl – Constant that specifies the implementation to use. This parameter can be one of the following values:

  • CMOX_AESFAST_CCM_ENC

  • CMOX_AESFAST_CCM_DEC

  • CMOX_AESSMALL_CCM_ENC

  • CMOX_AESSMALL_CCM_DEC

Returns :

cmox_cipher_handle_t* Pointer to a general cipher handle. This will be used by the general purpose cipher functions in order to perform the algorithm

Typedefs

typedef const struct cmox_cfb_implStruct_st * cmox_cfb_impl_t

CFB mode implementation.

This type specifies the used block cipher for the CFB construct and if the algorithm will be used for encryption or decryption. This type is defined as a pointer to a structure, that contains the functions needed for the specific implementation, defined in the library internally

struct cmox_cfb_handle_t

#include <cmox_cfb.h>

CFB handle structure definition.

Public Members

cmox_cipher_handle_t super

General cipher handle

cmox_blockcipher_handle_t blockCipher

Block cipher handle

uint32_t iv [ CMOX_CIPHER_BLOCK_SIZE ]

Buffer containing the Initialization Vector

size_t cfb_blockLen

Size of the CFB block. Currently only 16 bytes block supported

Variables

const cmox_cfb_impl_t CMOX_AESFAST_CFB_ENC

Implementation of CFB encryption using AES (fast implementation) (Defined internally).

const cmox_cfb_impl_t CMOX_AESFAST_CFB_DEC

Implementation of CFB decryption using AES (fast implementation) (Defined internally).

const cmox_cfb_impl_t CMOX_AESSMALL_CFB_ENC

Implementation of CFB encryption using AES (small implementation) (Defined internally).

const cmox_cfb_impl_t CMOX_AESSMALL_CFB_DEC

Implementation of CFB decryption using AES (small implementation) (Defined internally).

const cmox_cfb_impl_t CMOX_SM4_CFB_ENC

Implementation of CFB encryption using SM4 (Defined internally).

const cmox_cfb_impl_t CMOX_SM4_CFB_DEC

Implementation of CFB decryption using SM4 (Defined internally).

Variables

const cmox_cipher_algo_t CMOX_AESSMALL_CFB_ENC_ALGO

Identifier of the CFB encryption using AES (small implementation) for single-call function (Defined internally).

const cmox_cipher_algo_t CMOX_AESSMALL_CFB_DEC_ALGO

Identifier of the CFB decryption using AES (small implementation) for single-call function (Defined internally).

const cmox_cipher_algo_t CMOX_AESFAST_CFB_ENC_ALGO

Identifier of the CFB encryption using AES (fast implementation) for single-call function (Defined internally).

const cmox_cipher_algo_t CMOX_AESFAST_CFB_DEC_ALG

Identifier of the CFB decryption using AES (fast implementation) for single-call function (Defined internally).

const cmox_cipher_algo_t CMOX_SM4_CFB_ENC_ALGO

Identifier of the CFB encryption using SM4 for single-call function (Defined internally).

const cmox_cipher_algo_t CMOX_SM4_CFB_DEC_ALGO

Identifier of the CFB decryption using SM4 for single-call function (Defined internally).

Functions

cmox_cipher_handle_t * cmox_cfb_construct ( cmox_cfb_handle_t * P_pThis , cmox_cfb_impl_t P_impl )

CFB constructor.

The function is used for specifying which block cipher algorithm to use in order to implement the CFB algorithm and if the algorithm will be used for encryption or decryption.

Parameters :

• P_pThis – Pointer to the CFB handle to initialize

• P_impl – Constant that specifies the implementation to use. This parameter can be one of the following values:

  • CMOX_AESFAST_CFB_ENC

  • CMOX_AESFAST_CFB_DEC

  • CMOX_AESSMALL_CFB_ENC

  • CMOX_AESSMALL_CFB_DEC

  • CMOX_SM4_CFB_ENC

  • CMOX_SM4_CFB_DEC

Returns :

cmox_cipher_handle_t* Pointer to a general cipher handle. This will be used by the general purpose cipher functions in order to perform the algorithm

Variables

const cmox_aead_algo_t CMOX_CHACHAPOLY_ENC_ALGO

Identifier of the ChaCha20-Poly1305 encryption for single-call function (Defined internally).

const cmox_aead_algo_t CMOX_CHACHAPOLY_DEC_ALGO

Identifier of the ChaCha20-Poly1305 decryption for single-call function (Defined internally).

Typedefs

typedef const struct cmox_chachapoly_implStruct_st * cmox_chachapoly_impl_t

ChaCha20-Poly1305 mode implementation.

This type specifies if the algorithm will be used for encryption or decryption. This type is defined as a pointer to a structure, that contains the functions needed for the specific implementation, defined in the library internally

struct cmox_chachapoly_handle_t

#include <cmox_chachapoly.h>

ChaCha20-Poly1305 handle structure definition.

Public Members

cmox_cipher_handle_t super

General cipher handle

size_t mAadLen

Size of the processed AAD

size_t mCipherLen

Size of the processed CipherText

uint32_t rValue [ 5 ]

Internal: value of r

uint32_t hValue [ 5 ]

Internal: value of h

uint32_t pad [ 4 ]

Internal: value of Poly nonce

uint32_t internalState [ 16 ]

Internal: ChaCha Internal State

constants

Variables

const cmox_chachapoly_impl_t CMOX_CHACHAPOLY_ENC

Implementation of ChaCha20-Poly1305 encryption (Defined internally).

const cmox_chachapoly_impl_t CMOX_CHACHAPOLY_DEC

Implementation of ChaCha20-Poly1305 decryption (Defined internally).

prototypes

Functions

cmox_cipher_handle_t * cmox_chachapoly_construct ( cmox_chachapoly_handle_t * P_pThis , cmox_chachapoly_impl_t P_impl )

ChaCha20-Poly1305 constructor.

The function is used for specifying if the algorithm will be used for encryption or decryption.

Parameters :

• P_pThis – Pointer to the ChaCha20-Poly1305 handle to initialize

• P_impl – Constant that specifies the implementation to use. This parameter can be one of the following values:

  • CMOX_CHACHAPOLY_ENC

  • CMOX_CHACHAPOLY_DEC

Returns :

cmox_cipher_handle_t* Pointer to a general cipher handle. This will be used by the general purpose cipher functions in order to perform the algorithm

Defines

CMOX_CIPHER_128_BIT_KEY

Size in bytes of AES128 and SM4 keys.

CMOX_CIPHER_192_BIT_KEY

Size in bytes of AES192 keys.

CMOX_CIPHER_256_BIT_KEY

Size in bytes of AES256 keys.

Typedefs

typedef size_t cmox_cipher_keyLen_t

Type for specifying the key size for the cipher.

typedef const struct cmox_cipher_vtableStruct_st * cmox_cipher_vtable_t

Cipher Virtual Table.

This type specifies a pointer to the virtual table containing the methods for a particular algorithm (e.g. CBC or CHACHA20-POLY1305)

typedef const struct cmox_cipher_algoStruct_st * cmox_cipher_algo_t

Cipher algorithm type.

This type specifies the algorithm to use with the cipher module (e.g. CBC). The type is defined as a pointer to a structure, that contains the functions for the specific algorithm, defined in the library internally

typedef const struct cmox_aead_algoStruct_st * cmox_aead_algo_t

AEAD algorithm type.

This type specifies the AEAD algorithm to use with the cipher module (e.g. CCM or CHACHA20-POLY1305). The type is defined as a pointer to a structure, that contains the functions for the specific algorithm, defined in the library internally

struct cmox_cipher_handle_t

#include <cmox_cipher.h>

Cipher handle structure definition.

Public Members

cmox_cipher_vtable_t table

Cipher virtual table

uint32_t internalState

internal state of the cipher handle

Functions

cmox_cipher_retval_t cmox_cipher_cleanup ( cmox_cipher_handle_t * P_pThis )

Cleanup the cipher handle.

Parameters :

P_pThis – Cipher handle to cleanup

Returns :

cmox_cipher_retval_t Cipher return value

cmox_cipher_retval_t cmox_cipher_init ( cmox_cipher_handle_t * P_pThis )

Initialize the cipher handle for performing the specified algorithm.

Note

The cipher handle must be derived from an algorithm-specific handle using the correct constructor

Parameters :

P_pThis – Cipher handle to initialize

Returns :

cmox_cipher_retval_t Cipher return value

cmox_cipher_retval_t cmox_cipher_setKey ( cmox_cipher_handle_t * P_pThis , const uint8_t * P_pKey , cmox_cipher_keyLen_t P_keyLen )

Se the key to be used with the cipher algorithm.

Note

The XTS mode of operation requires a key with size double than the normal one (i.e. AES128-XTS will require a 32 bytes key, AES256-XTS will require a 64 bytes key and so on)

Parameters :

• P_pThis – Cipher handle to set

• P_pKey – Buffer of bytes containing the key

• P_keyLen – Len in bytes of the key

Returns :

cmox_cipher_retval_t Cipher return value

cmox_cipher_retval_t cmox_cipher_setIV ( cmox_cipher_handle_t * P_pThis , const uint8_t * P_pIv , size_t P_ivLen )

Set the initialization vector/nonce to be used with the cipher algorithm.

Parameters :

• P_pThis – Cipher handle to set

• P_pIv – Buffer of bytes containing the IV/nonce

• P_ivLen – Size in bytes of the key

Returns :

cmox_cipher_retval_t Cipher return value

cmox_cipher_retval_t cmox_cipher_setTagLen ( cmox_cipher_handle_t * P_pThis , size_t P_tagLen )

Set the size of the tag for AEAD cipher.

Note

This function must be used only for AEAD ciphers. If used with other cipher, it won’t have any effects

Note

For ChaCha20-Poly1305 the tag size is fixed to 16 bytes, and this function has no effects

Parameters :

• P_pThis – Cipher handle to set

• P_tagLen – Size in bytes of the tag

Returns :

cmox_cipher_retval_t Cipher return value

cmox_cipher_retval_t cmox_cipher_setPayloadLen ( cmox_cipher_handle_t * P_pThis , size_t P_totalPayloadLen )

Set the total payload size (only for CCM AEAD cipher).

Note

This function must be used for CCM ciphers. If used with other cipher, it won’t have any effects

Parameters :

• P_pThis – Cipher handle to set

• P_totalPayloadLen – Size in bytes of the total payload

Returns :

cmox_cipher_retval_t Cipher return value

cmox_cipher_retval_t cmox_cipher_setADLen ( cmox_cipher_handle_t * P_pThis , size_t P_totalADLen )

Set the total authenticated data size (only for CCM AEAD cipher).

Note

This function must be used for CCM ciphers. If used with other cipher, it won’t have any effects

Parameters :

• P_pThis – Cipher handle to set

• P_totalADLen – Size in bytes of the total authenticated data

Returns :

cmox_cipher_retval_t Cipher return value

cmox_cipher_retval_t cmox_cipher_appendAD ( cmox_cipher_handle_t * P_pThis , const uint8_t * P_pInput , size_t P_inputLen )

Append additional authenticated data to the cipher handle.

Note

This function must be used only for AEAD ciphers. If used with other cipher, it won’t have any effects

Parameters :

• P_pThis – Cipher handle where the authenticated data will be appended

• P_pInput – Buffer of bytes containing the data to append

• P_inputLen – Size in bytes of the data to append

Returns :

cmox_cipher_retval_t Cipher return value

cmox_cipher_retval_t cmox_cipher_append ( cmox_cipher_handle_t * P_pThis , const uint8_t * P_pInput , size_t P_inputLen , uint8_t * P_pOutput , size_t * P_pOutputLen )

Append part or the totality of the plaintext/ciphertext and return the corresponding ciphertext/plaintext.

Note

ECB and CFB modes of operation for AES and SM4 require that the input length for each append is multiple of the block size (i.e. 16 bytes)

Note

CBC mode of operation will apply CS2 ciphertext stealing in case the input length is greater than 16 bytes and not multiple of 16 bytes. After CS2 is applied, no more appends are allowed. Refer to NIST SP 800-38A Addendum.

Note

CTR, OFB, GCM and CCM modes of operation permits to have input not multiple of the block size (i.e. 16 bytes for AES and SM4), but after this no more further appends are allowed.

Note

For ChaCha20-Poly1305, this function can be called multiple times with P_inputLen multiple of 64 bytes. A single, last, call can be made with any value for P_inputLen.

Note

With the exception of KEYWRAP algorithm, the minimum size of P_pOutput buffer must be P_inputLen.

Note

For KEYWRAP mode, this function must be used to append the key to wrap, and must be done in a single call (no partial append of the key is supported). The P_pOutput buffer will contain the encrypted key AND the 8 bytes authentication tag. So the minimum size of this buffer must be P_inputLen + 8.

Parameters :

• P_pThis – Cipher handle to use for ciphering the data

• P_pInput – Buffer of bytes containing the data to append

• P_inputLen – Size in bytes of the data to append

• P_pOutput – Buffer of bytes where there will be stored the encrypted or decrypted data

• P_pOutputLen – Number of bytes that have been generated by the function. It is an optional parameter and can be set to NULL if not needed.

Returns :

cmox_cipher_retval_t Cipher return value

cmox_cipher_retval_t cmox_cipher_generateTag ( cmox_cipher_handle_t * P_pThis , uint8_t * P_pTag , size_t * P_pTagLen )

Generate the authenticated tag in case the AEAD operation is an encryption.

Note

This function must be used only for AEAD ciphers in encryption mode. If used with other cipher, it won’t have any effects. If used with AEAD cipher in decryption mode, it will raise an error.

Parameters :

• P_pThis – Cipher handle used for encrypting the data

• P_pTag – Buffer of bytes where there will be stored the generated tag

• P_pTagLen – Number of bytes that have been processed by the function. It is an optional parameter and can be set to NULL if not needed.

Returns :

cmox_cipher_retval_t Cipher return value

cmox_cipher_retval_t cmox_cipher_verifyTag ( cmox_cipher_handle_t * P_pThis , const uint8_t * P_pTag , uint32_t * P_pFaultCheck )

Authenticate the processed data with the given tag.

Note

This function must be used only for AEAD ciphers in decryption mode. If used with other cipher, it won’t have any effects. If used with AEAD cipher in encryption mode, it will raise an error.

Note

P_pFaultCheck value, if the parameter is provided, MUST be checked to be equal to the retval, and both MUST be equal to the successful value. P_pFaultCheck MUST be checked only if the main result is successful, and has no relevance if the main result is not successful. Every comparison (both for the return value and for P_pFaultCheck) must be done against the success value, and not comparing the value with the failure value. Indeed, in presence of faults, especially P_pFaultCheck, could be a dirty value.

Parameters :

• P_pThis – Cipher used for decrypting the data

• P_pTag – Buffer of bytes containing the tag to use for the verification

• P_pFaultCheck – Optional value to check, together with the retval, to verify if some fault happened

Returns :

cmox_cipher_retval_t Cipher return value

cmox_cipher_retval_t cmox_cipher_encrypt ( cmox_cipher_algo_t P_algo , const uint8_t * P_pInput , size_t P_inputLen , const uint8_t * P_pKey , cmox_cipher_keyLen_t P_keyLen , const uint8_t * P_pIv , size_t P_ivLen , uint8_t * P_pOutput , size_t * P_pOutputLen )

Encrypt or decrypt a message using a symmetric cipher.

Note

This single call function cannot be used for AEAD ciphers

Parameters :

• P_algo – Identifier of the cipher algorithm to use for the computation. This parameter can be one of the following:

  • CMOX_AESFAST_ECB_ENC_ALGO

  • CMOX_AESFAST_CBC_ENC_ALGO

  • CMOX_AESFAST_CTR_ENC_ALGO

  • CMOX_AESFAST_CFB_ENC_ALGO

  • CMOX_AESFAST_OFB_ENC_ALGO

  • CMOX_AESFAST_XTS_ENC_ALGO

  • CMOX_AESSMALL_ECB_ENC_ALGO

  • CMOX_AESSMALL_CBC_ENC_ALGO

  • CMOX_AESSMALL_CTR_ENC_ALGO

  • CMOX_AESSMALL_CFB_ENC_ALGO

  • CMOX_AESSMALL_OFB_ENC_ALGO

  • CMOX_AESSMALL_XTS_ENC_ALGO

  • CMOX_AESSMALL_KEYWRAP_ENC_ALGO

  • CMOX_SM4_ECB_ENC_ALGO

  • CMOX_SM4_CBC_ENC_ALGO

  • CMOX_SM4_CTR_ENC_ALGO

  • CMOX_SM4_CFB_ENC_ALGO

  • CMOX_SM4_OFB_ENC_ALGO

• P_pInput – Buffer of bytes containing the data to encrypt or decrypt

• P_inputLen – Length in bytes of the data to encrypt or decrypt

• P_pKey – Buffer of bytes containing the key

• P_keyLen – Length in bytes of the key

• P_pIv – Buffer of bytes containing the IV/nonce

• P_ivLen – Length in bytes of the key

• P_pOutput – Buffer of bytes where there will be stored the encrypted or decrypted data

• P_pOutputLen – Number of bytes that have been processed by the function. It is an optional parameter and can be set to NULL if not needed.

Returns :

cmox_cipher_retval_t Cipher return value

cmox_cipher_retval_t cmox_cipher_decrypt ( cmox_cipher_algo_t P_algo , const uint8_t * P_pInput , size_t P_inputLen , const uint8_t * P_pKey , cmox_cipher_keyLen_t P_keyLen , const uint8_t * P_pIv , size_t P_ivLen , uint8_t * P_pOutput , size_t * P_pOutputLen )

Decrypt a message using a symmetric cipher.

Note

This single call function cannot be used for AEAD ciphers

Parameters :

• P_algo – Identifier of the cipher algorithm to use for the computation. This parameter can be one of the following:

  • CMOX_AESFAST_ECB_DEC_ALGO

  • CMOX_AESFAST_CBC_DEC_ALGO

  • CMOX_AESFAST_CTR_DEC_ALGO

  • CMOX_AESFAST_CFB_DEC_ALGO

  • CMOX_AESFAST_OFB_DEC_ALGO

  • CMOX_AESFAST_XTS_DEC_ALGO

  • CMOX_AESFAST_KEYWRAP_DEC_ALGO

  • CMOX_AESSMALL_ECB_DEC_ALGO

  • CMOX_AESSMALL_CBC_DEC_ALGO

  • CMOX_AESSMALL_CTR_DEC_ALGO

  • CMOX_AESSMALL_CFB_DEC_ALGO

  • CMOX_AESSMALL_OFB_DEC_ALGO

  • CMOX_AESSMALL_XTS_DEC_ALGO

  • CMOX_AESSMALL_KEYWRAP_DEC_ALGO

  • CMOX_SM4_ECB_DEC_ALGO

  • CMOX_SM4_CBC_DEC_ALGO

  • CMOX_SM4_CTR_DEC_ALGO

  • CMOX_SM4_CFB_DEC_ALGO

  • CMOX_SM4_OFB_DEC_ALGO

• P_pInput – Buffer of bytes containing the data to encrypt or decrypt

• P_inputLen – Length in bytes of the data to encrypt or decrypt

• P_pKey – Buffer of bytes containing the key

• P_keyLen – Length in bytes of the key

• P_pIv – Buffer of bytes containing the IV/nonce

• P_ivLen – Length in bytes of the key

• P_pOutput – Buffer of bytes where there will be stored the decrypted data.

• P_pOutputLen – Number of bytes that have been processed by the function. It is an optional parameter and can be set to NULL if not needed.

Returns :

cmox_cipher_retval_t Cipher return value

cmox_cipher_retval_t cmox_aead_encrypt ( cmox_aead_algo_t P_algo , const uint8_t * P_pInput , size_t P_inputLen , size_t P_tagLen , const uint8_t * P_pKey , cmox_cipher_keyLen_t P_keyLen , const uint8_t * P_pIv , size_t P_ivLen , const uint8_t * P_pAddData , size_t P_addDataLen , uint8_t * P_pOutput , size_t * P_pOutputLen )

Encrypt a message using AEAD cipher.

Note

This single call function can be used for AEAD ciphers only

Parameters :

• P_algo – Identifier of the AEAD cipher algorithm to use for the computation. This parameter can be one of the following:

  • CMOX_AESFAST_GCMFAST_ENC_ALGO

  • CMOX_AESFAST_GCMSMALL_ENC_ALGO

  • CMOX_AESSMALL_GCMFAST_ENC_ALGO

  • CMOX_AESSMALL_GCMSMALL_ENC_ALGO

  • CMOX_AESFAST_CCM_ENC_ALGO

  • CMOX_AESSMALL_CCM_ENC_ALGO

  • CMOX_CHACHAPOLY_ENC_ALGO

• P_pInput – Buffer of bytes containing the data to encrypt

• P_inputLen – Length in bytes of the data to encrypt

• P_tagLen – Length in bytes of the authentication tag to append to the ciphertext

• P_pKey – Buffer of bytes containing the key

• P_keyLen – Length in bytes of the key

• P_pIv – Buffer of bytes containing the IV/nonce

• P_ivLen – Length in bytes of the key

• P_pAddData – Buffer of bytes containing the additional data to be used for authentication

• P_addDataLen – Length in bytes of the Additional data

• P_pOutput – Buffer of bytes where there will be stored the encrypted and authenticated data (i.e. ciphertext + tag)

• P_pOutputLen – Number of bytes that have been generated by the function. If correct, it will be the size of the encrypted and authenticated data (i.e. ciphertext + tag). It is an optional parameter and can be set to NULL if not needed.

Returns :

cmox_cipher_retval_t

cmox_cipher_retval_t cmox_aead_decrypt ( cmox_aead_algo_t P_algo , const uint8_t * P_pInput , size_t P_inputLen , size_t P_tagLen , const uint8_t * P_pKey , cmox_cipher_keyLen_t P_keyLen , const uint8_t * P_pIv , size_t P_ivLen , const uint8_t * P_pAddData , size_t P_addDataLen , uint8_t * P_pOutput , size_t * P_pOutputLen )

Decrypt a message using AEAD cipher.

Note

This single call function can be used for AEAD ciphers only

Parameters :

• P_algo – Identifier of the AEAD cipher algorithm to use for the computation. This parameter can be one of the following:

  • CMOX_AESFAST_GCMFAST_DEC_ALGO

  • CMOX_AESFAST_GCMSMALL_DEC_ALGO

  • CMOX_AESSMALL_GCMFAST_DEC_ALGO

  • CMOX_AESSMALL_GCMSMALL_DEC_ALGO

  • CMOX_AESFAST_CCM_DEC_ALGO

  • CMOX_AESSMALL_CCM_DEC_ALGO

  • CMOX_CHACHAPOLY_DEC_ALGO

• P_pInput – Buffer of bytes containing the authenticated and encrypted data (i.e. ciphertext + tag)

• P_inputLen – Length in bytes of the the authenticated and encrypted data (i.e. ciphertext + tag)

• P_tagLen – Length in bytes of the tag

• P_pKey – Buffer of bytes containing the key

• P_keyLen – Length in bytes of the key

• P_pIv – Buffer of bytes containing the IV/nonce

• P_ivLen – Length in bytes of the key

• P_pAddData – Buffer of bytes containing the additional data to be used for authentication

• P_addDataLen – Length in bytes of the Additional data

• P_pOutput – Buffer of bytes where there will be stored the decrypted data

• P_pOutputLen – Number of bytes that have been generated by the function. If correct, it will be the plaintext size. It is an optional parameter and can be set to NULL if not needed.

Returns :

cmox_cipher_retval_t

Defines

CMOX_CIPHER_SUCCESS

Cipher operation successfully performed.

CMOX_CIPHER_ERR_INTERNAL

Some error happens internally in the cipher module.

CMOX_CIPHER_ERR_NOT_IMPLEMENTED

The function is not implemented for the current algorithm.

CMOX_CIPHER_ERR_BAD_PARAMETER

One or more parameter has been wrongly passed to the function (e.g. pointer to NULL).

CMOX_CIPHER_ERR_BAD_OPERATION

Error on performing the operation (e.g. an operation has been called before initializing the handle).

CMOX_CIPHER_ERR_BAD_INPUT_SIZE

A buffer with a wrong size has been passed to the function.

CMOX_CIPHER_AUTH_SUCCESS

Authentication of the tag has been successful.

CMOX_CIPHER_AUTH_FAIL

Authentication of the tag failed.

Typedefs

typedef uint32_t cmox_cipher_retval_t

Cipher module return value type.

Typedefs

typedef const struct cmox_ctr_implStruct_st * cmox_ctr_impl_t

CTR mode implementation.

This type specifies the used block cipher for the CTR construct and if the algorithm will be used for encryption or decryption. This type is defined as a pointer to a structure, that contains the functions needed for the specific implementation, defined in the library internally

struct cmox_ctr_handle_t

#include <cmox_ctr.h>

CTR handle structure definition.

Public Members

cmox_cipher_handle_t super

General cipher handle

cmox_blockcipher_handle_t blockCipher

Block cipher handle

uint32_t iv [ CMOX_CIPHER_BLOCK_SIZE ]

Buffer containing the Initialization Vector

Variables

const cmox_ctr_impl_t CMOX_AESFAST_CTR_ENC

Implementation of CTR encryption using AES (fast implementation) (Defined internally).

const cmox_ctr_impl_t CMOX_AESFAST_CTR_DEC

Implementation of CTR decryption using AES (fast implementation) (Defined internally).

const cmox_ctr_impl_t CMOX_AESSMALL_CTR_ENC

Implementation of CTR encryption using AES (small implementation) (Defined internally).

const cmox_ctr_impl_t CMOX_AESSMALL_CTR_DEC

Implementation of CTR decryption using AES (small implementation) (Defined internally).

const cmox_ctr_impl_t CMOX_SM4_CTR_ENC

Implementation of CTR encryption using SM4 (Defined internally).

const cmox_ctr_impl_t CMOX_SM4_CTR_DEC

Implementation of CTR decryption using SM4 (Defined internally).

Variables

const cmox_cipher_algo_t CMOX_AESSMALL_CTR_ENC_ALGO

Identifier of the CTR encryption using AES (small implementation) for single-call function (Defined internally).

const cmox_cipher_algo_t CMOX_AESSMALL_CTR_DEC_ALGO

Identifier of the CTR decryption using AES (small implementation) for single-call function (Defined internally).

const cmox_cipher_algo_t CMOX_AESFAST_CTR_ENC_ALGO

Identifier of the CTR encryption using AES (fast implementation) for single-call function (Defined internally).

const cmox_cipher_algo_t CMOX_AESFAST_CTR_DEC_ALGO

Identifier of the CTR decryption using AES (fast implementation) for single-call function (Defined internally).

const cmox_cipher_algo_t CMOX_SM4_CTR_ENC_ALGO

Identifier of the CTR encryption using SM4 for single-call function (Defined internally).

const cmox_cipher_algo_t CMOX_SM4_CTR_DEC_ALGO

Identifier of the CTR decryption using SM4 for single-call function (Defined internally).

Functions

cmox_cipher_handle_t * cmox_ctr_construct ( cmox_ctr_handle_t * P_pThis , cmox_ctr_impl_t P_impl )

CTR constructor.

The function is used for specifying which block cipher algorithm to use in order to implement the CTR algorithm and if the algorithm will be used for encryption or decryption.

Parameters :

• P_pThis – Pointer to the CTR handle to initialize

• P_impl – Constant that specifies the implementation to use. This parameter can be one of the following values:

  • CMOX_AESFAST_CTR_ENC

  • CMOX_AESFAST_CTR_DEC

  • CMOX_AESSMALL_CTR_ENC

  • CMOX_AESSMALL_CTR_DEC

  • CMOX_SM4_CTR_ENC

  • CMOX_SM4_CTR_DEC

Returns :

cmox_cipher_handle_t* Pointer to a general cipher handle. This will be used by the general purpose cipher functions in order to perform the algorithm

Typedefs

typedef const struct cmox_ecb_implStruct_st * cmox_ecb_impl_t

ECB mode implementation.

This type specifies the used block cipher for the ECB construct and if the algorithm will be used for encryption or decryption. This type is defined as a pointer to a structure, that contains the functions needed for the specific implementation, defined in the library internally

struct cmox_ecb_handle_t

#include <cmox_ecb.h>

ECB handle structure definition.

Public Members

cmox_cipher_handle_t super

General cipher handle

cmox_blockcipher_handle_t blockCipher

Block cipher handle

Variables

const cmox_ecb_impl_t CMOX_AESFAST_ECB_ENC

Implementation of ECB encryption using AES (fast implementation) (Defined internally).

const cmox_ecb_impl_t CMOX_AESFAST_ECB_DEC

Implementation of ECB decryption using AES (fast implementation) (Defined internally).

const cmox_ecb_impl_t CMOX_AESSMALL_ECB_ENC

Implementation of ECB encryption using AES (small implementation) (Defined internally).

const cmox_ecb_impl_t CMOX_AESSMALL_ECB_DEC

Implementation of ECB decryption using AES (small implementation) (Defined internally).

const cmox_ecb_impl_t CMOX_SM4_ECB_ENC

Implementation of ECB encryption using SM4 (Defined internally).

const cmox_ecb_impl_t CMOX_SM4_ECB_DEC

Implementation of ECB decryption using SM4 (Defined internally).

Variables

const cmox_cipher_algo_t CMOX_AESSMALL_ECB_ENC_ALGO

Identifier of the ECB encryption using AES (small implementation) for single-call function (Defined internally).

const cmox_cipher_algo_t CMOX_AESSMALL_ECB_DEC_ALGO

Identifier of the ECB decryption using AES (small implementation) for single-call function (Defined internally).

const cmox_cipher_algo_t CMOX_AESFAST_ECB_ENC_ALGO

Identifier of the ECB encryption using AES (fast implementation) for single-call function (Defined internally).

const cmox_cipher_algo_t CMOX_AESFAST_ECB_DEC_ALGO

Identifier of the ECB decryption using AES (fast implementation) for single-call function (Defined internally).

const cmox_cipher_algo_t CMOX_SM4_ECB_ENC_ALGO

Identifier of the ECB encryption using SM4 for single-call function (Defined internally).

const cmox_cipher_algo_t CMOX_SM4_ECB_DEC_ALGO

Identifier of the ECB decryption using SM4 for single-call function (Defined internally).

Functions

cmox_cipher_handle_t * cmox_ecb_construct ( cmox_ecb_handle_t * P_pThis , cmox_ecb_impl_t P_impl )

ECB constructor.

The function is used for specifying which block cipher algorithm to use in order to implement the ECB algorithm and if the algorithm will be used for encryption or decryption.

Parameters :

• P_pThis – Pointer to the ECB handle to initialize

• P_impl – Constant that specifies the implementation to use. This parameter can be one of the following values:

  • CMOX_AESFAST_ECB_ENC

  • CMOX_AESFAST_ECB_DEC

  • CMOX_AESSMALL_ECB_ENC

  • CMOX_AESSMALL_ECB_DEC

  • CMOX_SM4_ECB_ENC

  • CMOX_SM4_ECB_DEC

Returns :

cmox_cipher_handle_t* Pointer to a general cipher handle. This will be used by the general purpose cipher functions in order to perform the algorithm

Typedefs

typedef const struct cmox_gcm_gfmulTable_st * cmox_gcm_gfmul_t

Type for specifying the GFMUL operation to use (internally used).

typedef const struct cmox_gcmSmall_implStruct_st * cmox_gcmSmall_impl_t

GCM SMALL mode implementation.

This type specifies the used block cipher for the GCM construct and if the algorithm will be used for encryption or decryption. This type is defined as a pointer to a structure, that contains the functions needed for the specific implementation, defined in the library internally

typedef const struct cmox_gcmFast_implStruct_st * cmox_gcmFast_impl_t

GCM FAST mode implementation.

This type specifies the used block cipher for the GCM construct and if the algorithm will be used for encryption or decryption. This type is defined as a pointer to a structure, that contains the functions needed for the specific implementation, defined in the library internally

typedef uint32_t cmox_gcm_poly_t [ 4 ]

Polynomial type used internally by GCM.

typedef cmox_gcm_poly_t cmox_gcm_table16_t [ 16 ]

Polynomial table type used by GCM SMALL implementation.

typedef cmox_gcm_poly_t cmox_gcm_table8x16_t [ 8 ] [ 16 ]

Polynomial table type used by GCM FAST implementation.

typedef cmox_gcmFast_handle_t cmox_gcm_handle_t

Default GCM handle definition.

typedef cmox_gcmFast_impl_t cmox_gcm_impl_t

Default GCM implementation definition.

struct cmox_gcm_common_t

#include <cmox_gcm.h>

Common fields for both GCM FAST and GCM SMALL handles.

Public Members

cmox_blockcipher_handle_t blockCipher

Block cipher handle

uint32_t iv [ CMOX_CIPHER_BLOCK_SIZE ]

Buffer containing the IV

size_t tagLen

Size in bytes of the authentication tag

size_t AdLen

Size in bytes of the Additional Data

size_t payloadLen

Processed payload size in bytes

cmox_gcm_poly_t partialAuth

Partial authentication value

cmox_gcm_gfmul_t gfmul

GF mul implementation

struct cmox_gcmSmall_handle_t

#include <cmox_gcm.h>

GCM SMALL handle structure definition.

Public Members

cmox_cipher_handle_t super

General cipher handle

cmox_gcm_common_t common

Common values with the GCM FAST handle type

cmox_gcm_table16_t precomputedValues

Precomputation of polynomial according to Shoup’s 4-bit table

struct cmox_gcmFast_handle_t

#include <cmox_gcm.h>

GCM fast context.

Public Members

cmox_cipher_handle_t super

General cipher handle

cmox_gcm_common_t common

Common values with the GCM SMALL handle type

cmox_gcm_table8x16_t precomputedValues

Precomputation of polynomial according to Shoup’s 8-bit table

Variables

const cmox_gcmSmall_impl_t CMOX_AESFAST_GCMSMALL_ENC

Implementation of GCMSMALL encryption using AES (fast implementation) (Defined internally).

const cmox_gcmSmall_impl_t CMOX_AESFAST_GCMSMALL_DEC

Implementation of GCMSMALL decryption using AES (fast implementation) (Defined internally).

const cmox_gcmSmall_impl_t CMOX_AESSMALL_GCMSMALL_ENC

Implementation of GCMSMALL encryption using AES (small implementation) (Defined internally).

const cmox_gcmSmall_impl_t CMOX_AESSMALL_GCMSMALL_DEC

Implementation of GCMSMALL decryption using AES (small implementation) (Defined internally).

const cmox_gcmFast_impl_t CMOX_AESFAST_GCMFAST_ENC

Implementation of GCMFAST encryption using AES (fast implementation) (Defined internally).

const cmox_gcmFast_impl_t CMOX_AESFAST_GCMFAST_DEC

Implementation of GCMFAST decryption using AES (fast implementation) (Defined internally).

const cmox_gcmFast_impl_t CMOX_AESSMALL_GCMFAST_ENC

Implementation of GCMFAST encryption using AES (small implementation) (Defined internally).

const cmox_gcmFast_impl_t CMOX_AESSMALL_GCMFAST_DEC

Implementation of GCMFAST decryption using AES (small implementation) (Defined internally).

Variables

const cmox_aead_algo_t CMOX_AESSMALL_GCMFAST_ENC_ALGO

Identifier of the GCM (fast implementation) encryption using AES (small implementation) for single-call function (Defined internally).

const cmox_aead_algo_t CMOX_AESSMALL_GCMFAST_DEC_ALGO

Identifier of the GCM (fast implementation) decryption using AES (small implementation) for single-call function (Defined internally).

const cmox_aead_algo_t CMOX_AESFAST_GCMFAST_ENC_ALGO

Identifier of the GCM (fast implementation) encryption using AES (fast implementation) for single-call function (Defined internally).

const cmox_aead_algo_t CMOX_AESFAST_GCMFAST_DEC_ALGO

Identifier of the GCM (fast implementation) decryption using AES (fast implementation) for single-call function (Defined internally).

const cmox_aead_algo_t CMOX_AESSMALL_GCMSMALL_ENC_ALGO

Identifier of the GCM (small implementation) encryption using AES (small implementation) for single-call function (Defined internally).

const cmox_aead_algo_t CMOX_AESSMALL_GCMSMALL_DEC_ALGO

Identifier of the GCM (small implementation) decryption using AES (small implementation) for single-call function (Defined internally).

const cmox_aead_algo_t CMOX_AESFAST_GCMSMALL_ENC_ALGO

Identifier of the GCM (small implementation) encryption using AES (fast implementation) for single-call function (Defined internally).

const cmox_aead_algo_t CMOX_AESFAST_GCMSMALL_DEC_ALGO

Identifier of the GCM (small implementation) decryption using AES (fast implementation) for single-call function (Defined internally).

Functions

cmox_cipher_handle_t * cmox_gcmSmall_construct ( cmox_gcmSmall_handle_t * P_pThis , cmox_gcmSmall_impl_t P_impl )

GCMSMALL constructor.

The function is used for specifying which block cipher algorithm to use in order to implement the GCM algorithm and if the algorithm will be used for encryption or decryption.

Note

If CMOX_GCM_IMPLEMENTATION macro has been set to CMOX_GCM_SMALL, this constructor can be called also through the wrapper cmox_gcm_construct

Parameters :

• P_pThis – Pointer to the GCM handle to initialize

• P_impl – Constant that specifies the implementation to use. This parameter can be one of the following values:

  • CMOX_AESFAST_GCMSMALL_ENC

  • CMOX_AESFAST_GCMSMALL_DEC

  • CMOX_AESSMALL_GCMSMALL_ENC

  • CMOX_AESSMALL_GCMSMALL_DEC

Returns :

cmox_cipher_handle_t* Pointer to a general cipher handle. This will be used by the general purpose cipher functions in order to perform the algorithm

cmox_cipher_handle_t * cmox_gcmFast_construct ( cmox_gcmFast_handle_t * P_pThis , cmox_gcmFast_impl_t P_impl )

GCMFAST constructor.

The function is used for specifying which block cipher algorithm to use in order to implement the GCM algorithm and if the algorithm will be used for encryption or decryption.

Note

If CMOX_GCM_IMPLEMENTATION macro has been set to CMOX_GCM_FAST, this constructor can be called also through the wrapper cmox_gcm_construct

Parameters :

• P_pThis – Pointer to the GCM handle to initialize

• P_impl – Constant that specifies the implementation to use. This parameter can be one of the following values:

  • CMOX_AESFAST_GCMFAST_ENC

  • CMOX_AESFAST_GCMFAST_DEC

  • CMOX_AESSMALL_GCMFAST_ENC

  • CMOX_AESSMALL_GCMFAST_DEC

Returns :

cmox_cipher_handle_t* Pointer to a general cipher handle. This will be used by the general purpose cipher functions in order to perform the algorithm

Defines

CMOX_KEYWRAP_TAG_LEN

Size in bytes of the keywrap tag.

Typedefs

typedef const struct cmox_keywrap_implStruct_st * cmox_keywrap_impl_t

KEYWRAP mode implementation.

This type specifies the used block cipher for the KEYWRAP construct and if the algorithm will be used for encryption or decryption. This type is defined as a pointer to a structure, that contains the functions needed for the specific implementation, defined in the library internally

struct cmox_keywrap_handle_t

#include <cmox_keywrap.h>

KEYWRAP handle structure definition.

Public Members

cmox_cipher_handle_t super

General cipher handle

cmox_blockcipher_handle_t blockCipher

Block cipher handle

uint32_t iv [ CMOX_CIPHER_BLOCK_SIZE ]

Buffer containing the Initialization Vector

Variables

const cmox_keywrap_impl_t CMOX_AESFAST_KEYWRAP_ENC

Implementation of KEYWRAP encryption using AES (fast implementation) (Defined internally).

const cmox_keywrap_impl_t CMOX_AESFAST_KEYWRAP_DEC

Implementation of KEYWRAP decryption using AES (fast implementation) (Defined internally).

const cmox_keywrap_impl_t CMOX_AESSMALL_KEYWRAP_ENC

Implementation of KEYWRAP encryption using AES (small implementation) (Defined internally).

const cmox_keywrap_impl_t CMOX_AESSMALL_KEYWRAP_DEC

Implementation of KEYWRAP decryption using AES (small implementation) (Defined internally).

Variables

const cmox_cipher_algo_t CMOX_AESSMALL_KEYWRAP_ENC_ALGO

Identifier of the KEYWRAP encryption using AES (small implementation) for single-call function (Defined internally).

const cmox_cipher_algo_t CMOX_AESSMALL_KEYWRAP_DEC_ALGO

Identifier of the KEYWRAP decryption using AES (small implementation) for single-call function (Defined internally).

const cmox_cipher_algo_t CMOX_AESFAST_KEYWRAP_ENC_ALGO

Identifier of the KEYWRAP encryption using AES (fast implementation) for single-call function (Defined internally).

const cmox_cipher_algo_t CMOX_AESFAST_KEYWRAP_DEC_ALGO

Identifier of the KEYWRAP decryption using AES (fast implementation) for single-call function (Defined internally).

Functions

cmox_cipher_handle_t * cmox_keywrap_construct ( cmox_keywrap_handle_t * P_pThis , cmox_keywrap_impl_t P_impl )

KEYWRAP constructor.

The function is used for specifying which block cipher algorithm to use in order to implement the KEYWRAP algorithm and if the algorithm will be used for encryption or decryption.

Parameters :

• P_pThis – Pointer to the KEYWRAP handle to initialize

• P_impl – Constant that specifies the implementation to use. This parameter can be one of the following values:

  • CMOX_AESFAST_KEYWRAP_ENC

  • CMOX_AESFAST_KEYWRAP_DEC

  • CMOX_AESSMALL_KEYWRAP_ENC

  • CMOX_AESSMALL_KEYWRAP_DEC

Returns :

cmox_cipher_handle_t* Pointer to a general cipher handle. This will be used by the general purpose cipher functions in order to perform the algorithm

Typedefs

typedef const struct cmox_ofb_implStruct_st * cmox_ofb_impl_t

OFB mode implementation.

This type specifies the used block cipher for the OFB construct and if the algorithm will be used for encryption or decryption. This type is defined as a pointer to a structure, that contains the functions needed for the specific implementation, defined in the library internally

struct cmox_ofb_handle_t

#include <cmox_ofb.h>

OFB handle structure definition.

Public Members

cmox_cipher_handle_t super

General cipher handle

cmox_blockcipher_handle_t blockCipher

Block cipher handle

uint32_t iv [ CMOX_CIPHER_BLOCK_SIZE ]

Buffer containing the Initialization Vector

Variables

const cmox_ofb_impl_t CMOX_AESFAST_OFB_ENC

Implementation of OFB encryption using AES (fast implementation) (Defined internally).

const cmox_ofb_impl_t CMOX_AESFAST_OFB_DEC

Implementation of OFB decryption using AES (fast implementation) (Defined internally).

const cmox_ofb_impl_t CMOX_AESSMALL_OFB_ENC

Implementation of OFB encryption using AES (small implementation) (Defined internally).

const cmox_ofb_impl_t CMOX_AESSMALL_OFB_DEC

Implementation of OFB decryption using AES (small implementation) (Defined internally).

const cmox_ofb_impl_t CMOX_SM4_OFB_ENC

Implementation of OFB encryption using SM4 (Defined internally).

const cmox_ofb_impl_t CMOX_SM4_OFB_DEC

Implementation of OFB decryption using SM4 (Defined internally).

Variables

const cmox_cipher_algo_t CMOX_AESSMALL_OFB_ENC_ALGO

Identifier of the OFB encryption using AES (small implementation) for single-call function (Defined internally).

const cmox_cipher_algo_t CMOX_AESSMALL_OFB_DEC_ALGO

Identifier of the OFB decryption using AES (small implementation) for single-call function (Defined internally).

const cmox_cipher_algo_t CMOX_AESFAST_OFB_ENC_ALGO

Identifier of the OFB encryption using AES (fast implementation) for single-call function (Defined internally).

const cmox_cipher_algo_t CMOX_AESFAST_OFB_DEC_ALGO

Identifier of the OFB decryption using AES (fast implementation) for single-call function (Defined internally).

const cmox_cipher_algo_t CMOX_SM4_OFB_ENC_ALGO

Identifier of the OFB encryption using SM4 for single-call function (Defined internally).

const cmox_cipher_algo_t CMOX_SM4_OFB_DEC_ALGO

Identifier of the OFB decryption using SM4 for single-call function (Defined internally).

Functions

cmox_cipher_handle_t * cmox_ofb_construct ( cmox_ofb_handle_t * P_pThis , cmox_ofb_impl_t P_impl )

OFB constructor.

The function is used for specifying which block cipher algorithm to use in order to implement the OFB algorithm and if the algorithm will be used for encryption or decryption.

Parameters :

• P_pThis – Pointer to the OFB handle to initialize

• P_impl – Constant that specifies the implementation to use. This parameter can be one of the following values:

  • CMOX_AESFAST_OFB_ENC

  • CMOX_AESFAST_OFB_DEC

  • CMOX_AESSMALL_OFB_ENC

  • CMOX_AESSMALL_OFB_DEC

  • CMOX_SM4_OFB_ENC

  • CMOX_SM4_OFB_DEC

Returns :

cmox_cipher_handle_t* Pointer to a general cipher handle. This will be used by the general purpose cipher functions in order to perform the algorithm

Typedefs

typedef const struct cmox_xts_implStruct_st * cmox_xts_impl_t

XTS mode implementation.

This type specifies the used block cipher for the XTS construct and if the algorithm will be used for encryption or decryption. This type is defined as a pointer to a structure, that contains the functions needed for the specific implementation, defined in the library internally

struct cmox_xts_handle_t

#include <cmox_xts.h>

XTS handle structure definition.

Public Members

cmox_cipher_handle_t super

General cipher handle

cmox_blockcipher_handle_t blockCipher1

Block cipher handle

cmox_blockcipher_handle_t blockCipher2

Block cipher handle

uint32_t tweak [ CMOX_CIPHER_BLOCK_SIZE ]

Temporary result/tweak

Variables

const cmox_xts_impl_t CMOX_AESFAST_XTS_ENC

Implementation of XTS encryption using AES (fast implementation) (Defined internally).

const cmox_xts_impl_t CMOX_AESFAST_XTS_DEC

Implementation of XTS decryption using AES (fast implementation) (Defined internally).

const cmox_xts_impl_t CMOX_AESSMALL_XTS_ENC

Implementation of XTS encryption using AES (small implementation) (Defined internally).

const cmox_xts_impl_t CMOX_AESSMALL_XTS_DEC

Implementation of XTS decryption using AES (small implementation) (Defined internally).

Variables

const cmox_cipher_algo_t CMOX_AESSMALL_XTS_ENC_ALGO

Identifier of the XTS encryption using AES (small implementation) for single-call function (Defined internally).

const cmox_cipher_algo_t CMOX_AESSMALL_XTS_DEC_ALGO

Identifier of the XTS decryption using AES (small implementation) for single-call function (Defined internally).

const cmox_cipher_algo_t CMOX_AESFAST_XTS_ENC_ALGO

Identifier of the XTS encryption using AES (fast implementation) for single-call function (Defined internally).

const cmox_cipher_algo_t CMOX_AESFAST_XTS_DEC_ALGO

Identifier of the XTS decryption using AES (fast implementation) for single-call function (Defined internally).

Functions

cmox_cipher_handle_t * cmox_xts_construct ( cmox_xts_handle_t * P_pThis , cmox_xts_impl_t P_impl )

XTS constructor.

The function is used for specifying which block cipher algorithm to use in order to implement the XTS algorithm and if the algorithm will be used for encryption or decryption.

Parameters :

• P_pThis – Pointer to the XTS handle to initialize

• P_impl – Constant that specifies the implementation to use. This parameter can be one of the following values:

  • CMOX_AESFAST_XTS_ENC

  • CMOX_AESFAST_XTS_DEC

  • CMOX_AESSMALL_XTS_ENC

  • CMOX_AESSMALL_XTS_DEC

Returns :

cmox_cipher_handle_t* Pointer to a general cipher handle. This will be used by the general purpose cipher functions in order to perform the algorithm

2.2. DRBG module

group CMOX_DRBG

Typedefs

typedef const struct cmox_ctr_drbg_implStruct_st * cmox_ctr_drbg_impl_t

CTR-DRBG mode implementation.

This type specifies the used block cipher for the CTR-DRBG construct. This type is defined as a pointer to a structure, that contains the functions needed for the specific implementation, defined in the library internally

struct cmox_ctr_drbg_state_t

#include <cmox_ctr_drbg.h>

Structure to store the state/context of the CTR_DRBG.

Public Members

uint32_t value [ 4 ]

V value, a 128 bit value

uint32_t key [ 8 ]

K value, contains the block cipher key

uint64_t reseed_counter

Reseed counter 32-bit of data

struct cmox_ctr_drbg_handle_t

#include <cmox_ctr_drbg.h>

CTR-DRBG handle structure definition.

Public Members

cmox_drbg_handle_t super

General DRBG handle

cmox_blockcipher_handle_t blockCipher

Block cipher handle

cmox_blockcipher_handle_t blockCipher_df

Block cipher handle for derivation function

cmox_ctr_drbg_state_t state

DRBG state

uint32_t flag

DRBG flag

cmox_cipher_keyLen_t keyLen

Length in bytes of the block cipher key

size_t expKeyLen

Length in bytes of the expanded key

size_t minEntropyLen

Minimum entropy length

size_t maxBytesPerRequest

Maximum number of random bytes per request

const uint32_t * exp_aes_0_key

Pointer to the expanded key

const uint32_t * exp_bcc_aes_key

Pointer to the expanded key for BCC

Variables

const cmox_ctr_drbg_impl_t CMOX_CTR_DRBG_AES128_SMALL

Implementation of CTR-DRBG using AES-128 (small implementation) (Defined internally).

const cmox_ctr_drbg_impl_t CMOX_CTR_DRBG_AES128_FAST

Implementation of CTR-DRBG using AES-128 (fast implementation) (Defined internally).

const cmox_ctr_drbg_impl_t CMOX_CTR_DRBG_AES256_SMALL

Implementation of CTR-DRBG using AES-256 (small implementation) (Defined internally).

const cmox_ctr_drbg_impl_t CMOX_CTR_DRBG_AES256_FAST

Implementation of CTR-DRBG using AES-256 (fast implementation) (Defined internally).

Functions

cmox_drbg_handle_t * cmox_ctr_drbg_construct ( cmox_ctr_drbg_handle_t * P_pThis , cmox_ctr_drbg_impl_t P_impl )

CTR-DRBG constructor.

The function is used for specifying which block cipher algorithm to use in order to implement the CTR-DRBG algorithm

Parameters :

• P_pThis – Pointer to the CTR-DRBG handle to initialize

• P_impl – Constant that specifies the implementation to use. This parameter can be one of the following values:

  • CMOX_CTR_DRBG_AES128_FAST

  • CMOX_CTR_DRBG_AES192_FAST

  • CMOX_CTR_DRBG_AES256_FAST

  • CMOX_CTR_DRBG_AES128_SMALL

  • CMOX_CTR_DRBG_AES192_SMALL

  • CMOX_CTR_DRBG_AES256_SMALL

Returns :

cmox_drbg_handle_t* Pointer to a general DRBG handle. This will be used by the general purpose cipher functions in order to perform the algorithm

Typedefs

typedef const struct cmox_drbg_vtableStruct_st * cmox_drbg_vtable_t

DRBG Virtual Table.

This type specifies a pointer to the virtual table containing the methods for a particular algorithm (currently the only supported is CTR-DRBG)

struct cmox_drbg_handle_t

#include <cmox_drbg.h>

DRBG handle structure definition.

Public Members

cmox_drbg_vtable_t table

DRBG virtual table

Functions

cmox_drbg_retval_t cmox_drbg_cleanup ( cmox_drbg_handle_t * P_pThis )

Cleanup the DRBG handle.

Parameters :

P_pThis – DRBG handle to cleanup

Returns :

cmox_drbg_retval_t DRBG return value

cmox_drbg_retval_t cmox_drbg_init ( cmox_drbg_handle_t * P_pThis , const uint8_t * P_pEntropy , size_t P_entropyLen , const uint8_t * P_pPersonalString , size_t P_personalStringLen , const uint8_t * P_pNonce , size_t P_nonceLen )

Initialize the DRBG engine.

Parameters :

• P_pThis – DRBG handler to initialize

• P_pEntropy – Buffer of bytes containing the entropy bytes

• P_entropyLen – Number of entropy bytes that will be used to seed the DRBG

• P_pPersonalString – Buffer of bytes containing the personalization string

• P_personalStringLen – Size in bytes of the personalization string

• P_pNonce – Buffer of bytes containing nonce data

• P_nonceLen – Size in bytes of the nonce

Returns :

cmox_drbg_retval_t DRBG return value

cmox_drbg_retval_t cmox_drbg_reseed ( cmox_drbg_handle_t * P_pThis , const uint8_t * P_pEntropy , size_t P_entropyLen , const uint8_t * P_pAdditionalInput , size_t P_additionalInputLen )

Reseed the DRBG.

Parameters :

• P_pThis – DRBG handler to initialize

• P_pEntropy – Buffer of bytes containing the entropy bytes

• P_entropyLen – Number of entropy bytes that will be used to seed the DRBG

• P_pAdditionalInput – Buffer of bytes containing additional input

• P_additionalInputLen – Size in bytes of the additional input

Returns :

cmox_drbg_retval_t DRBG return value

cmox_drbg_retval_t cmox_drbg_generate ( cmox_drbg_handle_t * P_pThis , const uint8_t * P_pAdditionalInput , size_t P_additionalInputLen , uint8_t * P_pOutput , size_t P_desiredOutputLen )

Generation of pseudorandom octets to a buffer.

Parameters :

• P_pThis – DRBG handler to initialize

• P_pAdditionalInput – Buffer of bytes containing additional input

• P_additionalInputLen – Size in bytes of the additional input

• P_pOutput – Buffer of bytes where the generated bytes will be stored

• P_desiredOutputLen – Desired number of random bytes to produce

Returns :

cmox_drbg_retval_t DRBG return value

Defines

CMOX_DRBG_SUCCESS

DRBG operation successfully performed.

CMOX_DRBG_ERR_INTERNAL

DRBG generic internal error.

CMOX_DRBG_ERR_BAD_PARAMETER

DRBG One of the expected function parameters is invalid.

CMOX_DRBG_ERR_BAD_OPERATION

DRBG Invalid operation.

CMOX_DRBG_ERR_UNINIT_STATE

DRBG has not been correctly initialized.

CMOX_DRBG_ERR_RESEED_NEEDED

DRBG Reseed is needed.

CMOX_DRBG_ERR_BAD_ENTROPY_SIZE

DRBG Check the size of the entropy string.

CMOX_DRBG_ERR_BAD_PERS_STR_LEN

DRBG Check the size of the personalization string.

CMOX_DRBG_ERR_BAD_ADD_INPUT_LEN

DRBG Check the size of the additional input string.

CMOX_DRBG_ERR_BAD_REQUEST

DRBG Check the size of the random request.

CMOX_DRBG_ERR_BAD_NONCE_SIZE

DRBG Check the size of the nonce.

Typedefs

typedef uint32_t cmox_drbg_retval_t

DRBG module return value type.

2.3. ECC module

group CMOX_ECC

Variables

const cmox_ecc_impl_t CMOX_ECC_CURVE25519

Suggested Curve25519 implementation (for X25519) for the target device

const cmox_ecc_impl_t CMOX_ECC_CURVE448

Suggested Curve448 implementation (for X448) for the target device

const cmox_ecc_impl_t CMOX_ECC_ED25519_HIGHMEM

EDWARDS Ed25519 with general Edwards functions, high RAM usage

const cmox_ecc_impl_t CMOX_ECC_ED25519_OPT_LOWMEM

EDWARDS Ed25519 with Edwards functions optimized for a = -1, low RAM usage

const cmox_ecc_impl_t CMOX_ECC_ED25519_OPT_HIGHMEM

EDWARDS Ed25519 with Edwards functions optimized for a = -1, high RAM usage

const cmox_ecc_impl_t CMOX_ECC_ED448_LOWMEM

EDWARDS Ed448 with general Edwards functions, low RAM usage

const cmox_ecc_impl_t CMOX_ECC_ED448_HIGHMEM

EDWARDS Ed448 with general Edwards functions, high RAM usage

const cmox_ecc_impl_t CMOX_ECC_SECP224R1_LOWMEM

NIST-R P-224, low RAM usage

const cmox_ecc_impl_t CMOX_ECC_SECP224R1_HIGHMEM

NIST-R P-224, high RAM usage

const cmox_ecc_impl_t CMOX_ECC_SECP256R1_LOWMEM

NIST-R P-256, low RAM usage

const cmox_ecc_impl_t CMOX_ECC_SECP256R1_HIGHMEM

NIST-R P-256, high RAM usage

const cmox_ecc_impl_t CMOX_ECC_SECP384R1_LOWMEM

NIST-R P-384, low RAM usage

const cmox_ecc_impl_t CMOX_ECC_SECP384R1_HIGHMEM

NIST-R P-384, high RAM usage

const cmox_ecc_impl_t CMOX_ECC_SECP521R1_LOWMEM

NIST-R P-521, low RAM usage

const cmox_ecc_impl_t CMOX_ECC_SECP521R1_HIGHMEM

NIST-R P-521, high RAM usage

const cmox_ecc_impl_t CMOX_ECC_SECP256K1_LOWMEM

NIST-K P-256, low RAM usage

const cmox_ecc_impl_t CMOX_ECC_SECP256K1_HIGHMEM

NIST-K P-256, high RAM usage

const cmox_ecc_impl_t CMOX_ECC_BPP160R1_LOWMEM

BRAINPOOL-R P-160, low RAM usage

const cmox_ecc_impl_t CMOX_ECC_BPP160R1_HIGHMEM

BRAINPOOL-R P-160, high RAM usage

const cmox_ecc_impl_t CMOX_ECC_BPP192R1_LOWMEM

BRAINPOOL-R P-192, low RAM usage

const cmox_ecc_impl_t CMOX_ECC_BPP192R1_HIGHMEM

BRAINPOOL-R P-192, high RAM usage

const cmox_ecc_impl_t CMOX_ECC_BPP224R1_LOWMEM

BRAINPOOL-R P-224, low RAM usage

const cmox_ecc_impl_t CMOX_ECC_BPP224R1_HIGHMEM

BRAINPOOL-R P-224, high RAM usage

const cmox_ecc_impl_t CMOX_ECC_BPP256R1_LOWMEM

BRAINPOOL-R P-256, low RAM usage

const cmox_ecc_impl_t CMOX_ECC_BPP256R1_HIGHMEM

BRAINPOOL-R P-256, high RAM usage

const cmox_ecc_impl_t CMOX_ECC_BPP320R1_LOWMEM

BRAINPOOL-R P-320, low RAM usage

const cmox_ecc_impl_t CMOX_ECC_BPP320R1_HIGHMEM

BRAINPOOL-R P-320, high RAM usage

const cmox_ecc_impl_t CMOX_ECC_BPP384R1_LOWMEM

BRAINPOOL-R P-384, low RAM usage

const cmox_ecc_impl_t CMOX_ECC_BPP384R1_HIGHMEM

BRAINPOOL-R P-384, high RAM usage

const cmox_ecc_impl_t CMOX_ECC_BPP512R1_LOWMEM

BRAINPOOL-R P-512, low RAM usage

const cmox_ecc_impl_t CMOX_ECC_BPP512R1_HIGHMEM

BRAINPOOL-R P-512, high RAM usage

const cmox_ecc_impl_t CMOX_ECC_BPP160T1_LOWMEM

BRAINPOOL-T P-160, low RAM usage

const cmox_ecc_impl_t CMOX_ECC_BPP160T1_HIGHMEM

BRAINPOOL-T P-160, high RAM usage

const cmox_ecc_impl_t CMOX_ECC_BPP192T1_LOWMEM

BRAINPOOL-T P-192, low RAM usage

const cmox_ecc_impl_t CMOX_ECC_BPP192T1_HIGHMEM

BRAINPOOL-T P-192, high RAM usage

const cmox_ecc_impl_t CMOX_ECC_BPP224T1_LOWMEM

BRAINPOOL-T P-224, low RAM usage

const cmox_ecc_impl_t CMOX_ECC_BPP224T1_HIGHMEM

BRAINPOOL-T P-224, high RAM usage

const cmox_ecc_impl_t CMOX_ECC_BPP256T1_LOWMEM

BRAINPOOL-T P-256, low RAM usage

const cmox_ecc_impl_t CMOX_ECC_BPP256T1_HIGHMEM

BRAINPOOL-T P-256, high RAM usage

const cmox_ecc_impl_t CMOX_ECC_BPP320T1_LOWMEM

BRAINPOOL-T P-320, low RAM usage

const cmox_ecc_impl_t CMOX_ECC_BPP320T1_HIGHMEM

BRAINPOOL-T P-320, high RAM usage

const cmox_ecc_impl_t CMOX_ECC_BPP384T1_LOWMEM

BRAINPOOL-T P-384, low RAM usage

const cmox_ecc_impl_t CMOX_ECC_BPP384T1_HIGHMEM

BRAINPOOL-T P-384, high RAM usage

const cmox_ecc_impl_t CMOX_ECC_BPP512T1_LOWMEM

BRAINPOOL-T P-512, low RAM usage

const cmox_ecc_impl_t CMOX_ECC_BPP512T1_HIGHMEM

BRAINPOOL-T P-512, high RAM usage

const cmox_ecc_impl_t CMOX_ECC_FRP256V1_LOWMEM

ANSSI P-256, low RAM usage

const cmox_ecc_impl_t CMOX_ECC_FRP256V1_HIGHMEM

ANSSI P-256, high RAM usage

const cmox_ecc_impl_t CMOX_ECC_SM2_LOWMEM

OSCCA 256 bit curve, low RAM usage

const cmox_ecc_impl_t CMOX_ECC_SM2_HIGHMEM

OSCCA 256 bit curve, high RAM usage

const cmox_ecc_impl_t CMOX_ECC_SM2TEST_LOWMEM

OSCCA 256 bit test curve, low RAM usage

const cmox_ecc_impl_t CMOX_ECC_SM2TEST_HIGHMEM

OSCCA 256 bit test curve, high RAM usage

Defines

CMOX_ECC_CURVE25519_PRIVKEY_LEN

Byte length for a byte buffer containing a CURVE25519 private key

CMOX_ECC_CURVE25519_PUBKEY_LEN

Byte length for a byte buffer containing a CURVE25519 public key

CMOX_ECC_CURVE25519_SECRET_LEN

Byte length for a byte buffer containing a CURVE25519 ECDH secret

CMOX_ECC_CURVE448_PRIVKEY_LEN

Byte length for a byte buffer containing a CURVE448 private key

CMOX_ECC_CURVE448_PUBKEY_LEN

Byte length for a byte buffer containing a CURVE448 public key

CMOX_ECC_CURVE448_SECRET_LEN

Byte length for a byte buffer containing a CURVE448 ECDH secret

CMOX_ECC_ED25519_SIG_LEN

Byte length for a byte buffer containing a ED25519 signature

CMOX_ECC_ED25519_PRIVKEY_LEN

Byte length for a byte buffer containing a ED25519 private key

CMOX_ECC_ED25519_PUBKEY_LEN

Byte length for a byte buffer containing a ED25519 public key

CMOX_ECC_ED448_SIG_LEN

Byte length for a byte buffer containing a ED448 signature

CMOX_ECC_ED448_PRIVKEY_LEN

Byte length for a byte buffer containing a ED448 private key

CMOX_ECC_ED448_PUBKEY_LEN

Byte length for a byte buffer containing a ED448 public key

CMOX_ECC_SECP224R1_SIG_LEN

Byte length for a byte buffer containing a SECP224R1 signature

CMOX_ECC_SECP224R1_PRIVKEY_LEN

Byte length for a byte buffer containing a SECP224R1 private key

CMOX_ECC_SECP224R1_PUBKEY_LEN

Byte length for a byte buffer containing a SECP224R1 public key

CMOX_ECC_SECP224R1_SECRET_LEN

Byte length for a byte buffer containing a SECP224R1 ECDH secret

CMOX_ECC_SECP256R1_SIG_LEN

Byte length for a byte buffer containing a SECP256R1 signature

CMOX_ECC_SECP256R1_PRIVKEY_LEN

Byte length for a byte buffer containing a SECP256R1 private key

CMOX_ECC_SECP256R1_PUBKEY_LEN

Byte length for a byte buffer containing a SECP256R1 public key

CMOX_ECC_SECP256R1_SECRET_LEN

Byte length for a byte buffer containing a SECP256R1 ECDH secret

CMOX_ECC_SECP384R1_SIG_LEN

Byte length for a byte buffer containing a SECP384R1 signature

CMOX_ECC_SECP384R1_PRIVKEY_LEN

Byte length for a byte buffer containing a SECP384R1 private key

CMOX_ECC_SECP384R1_PUBKEY_LEN

Byte length for a byte buffer containing a SECP384R1 public key

CMOX_ECC_SECP384R1_SECRET_LEN

Byte length for a byte buffer containing a SECP384R1 ECDH secret

CMOX_ECC_SECP521R1_SIG_LEN

Byte length for a byte buffer containing a SECP521R1 signature

CMOX_ECC_SECP521R1_PRIVKEY_LEN

Byte length for a byte buffer containing a SECP521R1 private key

CMOX_ECC_SECP521R1_PUBKEY_LEN

Byte length for a byte buffer containing a SECP521R1 public key

CMOX_ECC_SECP521R1_SECRET_LEN

Byte length for a byte buffer containing a SECP521R1 ECDH secret

CMOX_ECC_SECP256K1_SIG_LEN

Byte length for a byte buffer containing a SECP256K1 signature

CMOX_ECC_SECP256K1_PRIVKEY_LEN

Byte length for a byte buffer containing a SECP256K1 private key

CMOX_ECC_SECP256K1_PUBKEY_LEN

Byte length for a byte buffer containing a SECP256K1 public key

CMOX_ECC_SECP256K1_SECRET_LEN

Byte length for a byte buffer containing a SECP256K1 ECDH secret

CMOX_ECC_BPP160R1_SIG_LEN

Byte length for a byte buffer containing a BPP160R1 signature

CMOX_ECC_BPP160R1_PRIVKEY_LEN

Byte length for a byte buffer containing a BPP160R1 private key

CMOX_ECC_BPP160R1_PUBKEY_LEN

Byte length for a byte buffer containing a BPP160R1 public key

CMOX_ECC_BPP160R1_SECRET_LEN

Byte length for a byte buffer containing a BPP160R1 ECDH secret

CMOX_ECC_BPP192R1_SIG_LEN

Byte length for a byte buffer containing a BPP192R1 signature

CMOX_ECC_BPP192R1_PRIVKEY_LEN

Byte length for a byte buffer containing a BPP192R1 private key

CMOX_ECC_BPP192R1_PUBKEY_LEN

Byte length for a byte buffer containing a BPP192R1 public key

CMOX_ECC_BPP192R1_SECRET_LEN

Byte length for a byte buffer containing a BPP192R1 ECDH secret

CMOX_ECC_BPP224R1_SIG_LEN

Byte length for a byte buffer containing a BPP224R1 signature

CMOX_ECC_BPP224R1_PRIVKEY_LEN

Byte length for a byte buffer containing a BPP224R1 private key

CMOX_ECC_BPP224R1_PUBKEY_LEN

Byte length for a byte buffer containing a BPP224R1 public key

CMOX_ECC_BPP224R1_SECRET_LEN

Byte length for a byte buffer containing a BPP224R1 ECDH secret

CMOX_ECC_BPP256R1_SIG_LEN

Byte length for a byte buffer containing a BPP256R1 signature

CMOX_ECC_BPP256R1_PRIVKEY_LEN

Byte length for a byte buffer containing a BPP256R1 private key

CMOX_ECC_BPP256R1_PUBKEY_LEN

Byte length for a byte buffer containing a BPP256R1 public key

CMOX_ECC_BPP256R1_SECRET_LEN

Byte length for a byte buffer containing a BPP256R1 ECDH secret

CMOX_ECC_BPP320R1_SIG_LEN

Byte length for a byte buffer containing a BPP320R1 signature

CMOX_ECC_BPP320R1_PRIVKEY_LEN

Byte length for a byte buffer containing a BPP320R1 private key

CMOX_ECC_BPP320R1_PUBKEY_LEN

Byte length for a byte buffer containing a BPP320R1 public key

CMOX_ECC_BPP320R1_SECRET_LEN

Byte length for a byte buffer containing a BPP320R1 ECDH secret

CMOX_ECC_BPP384R1_SIG_LEN

Byte length for a byte buffer containing a BPP384R1 signature

CMOX_ECC_BPP384R1_PRIVKEY_LEN

Byte length for a byte buffer containing a BPP384R1 private key

CMOX_ECC_BPP384R1_PUBKEY_LEN

Byte length for a byte buffer containing a BPP384R1 public key

CMOX_ECC_BPP384R1_SECRET_LEN

Byte length for a byte buffer containing a BPP384R1 ECDH secret

CMOX_ECC_BPP512R1_SIG_LEN

Byte length for a byte buffer containing a BPP512R1 signature

CMOX_ECC_BPP512R1_PRIVKEY_LEN

Byte length for a byte buffer containing a BPP512R1 private key

CMOX_ECC_BPP512R1_PUBKEY_LEN

Byte length for a byte buffer containing a BPP512R1 public key

CMOX_ECC_BPP512R1_SECRET_LEN

Byte length for a byte buffer containing a BPP512R1 ECDH secret

CMOX_ECC_BPP160T1_SIG_LEN

Byte length for a byte buffer containing a BPP160T1 signature

CMOX_ECC_BPP160T1_PRIVKEY_LEN

Byte length for a byte buffer containing a BPP160T1 private key

CMOX_ECC_BPP160T1_PUBKEY_LEN

Byte length for a byte buffer containing a BPP160T1 public key

CMOX_ECC_BPP160T1_SECRET_LEN

Byte length for a byte buffer containing a BPP160T1 ECDH secret

CMOX_ECC_BPP192T1_SIG_LEN

Byte length for a byte buffer containing a BPP192T1 signature

CMOX_ECC_BPP192T1_PRIVKEY_LEN

Byte length for a byte buffer containing a BPP192T1 private key

CMOX_ECC_BPP192T1_PUBKEY_LEN

Byte length for a byte buffer containing a BPP192T1 public key

CMOX_ECC_BPP192T1_SECRET_LEN

Byte length for a byte buffer containing a BPP192T1 ECDH secret

CMOX_ECC_BPP224T1_SIG_LEN

Byte length for a byte buffer containing a BPP224T1 signature

CMOX_ECC_BPP224T1_PRIVKEY_LEN

Byte length for a byte buffer containing a BPP224T1 private key

CMOX_ECC_BPP224T1_PUBKEY_LEN

Byte length for a byte buffer containing a BPP224T1 public key

CMOX_ECC_BPP224T1_SECRET_LEN

Byte length for a byte buffer containing a BPP224T1 ECDH secret

CMOX_ECC_BPP256T1_SIG_LEN

Byte length for a byte buffer containing a BPP256T1 signature

CMOX_ECC_BPP256T1_PRIVKEY_LEN

Byte length for a byte buffer containing a BPP256T1 private key

CMOX_ECC_BPP256T1_PUBKEY_LEN

Byte length for a byte buffer containing a BPP256T1 public key

CMOX_ECC_BPP256T1_SECRET_LEN

Byte length for a byte buffer containing a BPP256T1 ECDH secret

CMOX_ECC_BPP320T1_SIG_LEN

Byte length for a byte buffer containing a BPP320T1 signature

CMOX_ECC_BPP320T1_PRIVKEY_LEN

Byte length for a byte buffer containing a BPP320T1 private key

CMOX_ECC_BPP320T1_PUBKEY_LEN

Byte length for a byte buffer containing a BPP320T1 public key

CMOX_ECC_BPP320T1_SECRET_LEN

Byte length for a byte buffer containing a BPP320T1 ECDH secret

CMOX_ECC_BPP384T1_SIG_LEN

Byte length for a byte buffer containing a BPP384T1 signature

CMOX_ECC_BPP384T1_PRIVKEY_LEN

Byte length for a byte buffer containing a BPP384T1 private key

CMOX_ECC_BPP384T1_PUBKEY_LEN

Byte length for a byte buffer containing a BPP384T1 public key

CMOX_ECC_BPP384T1_SECRET_LEN

Byte length for a byte buffer containing a BPP384T1 ECDH secret

CMOX_ECC_BPP512T1_SIG_LEN

Byte length for a byte buffer containing a BPP512T1 signature

CMOX_ECC_BPP512T1_PRIVKEY_LEN

Byte length for a byte buffer containing a BPP512T1 private key

CMOX_ECC_BPP512T1_PUBKEY_LEN

Byte length for a byte buffer containing a BPP512T1 public key

CMOX_ECC_BPP512T1_SECRET_LEN

Byte length for a byte buffer containing a BPP512T1 ECDH secret

CMOX_ECC_FRP256V1_SIG_LEN

Byte length for a byte buffer containing a FRP256V1 signature

CMOX_ECC_FRP256V1_PRIVKEY_LEN

Byte length for a byte buffer containing a FRP256V1 private key

CMOX_ECC_FRP256V1_PUBKEY_LEN

Byte length for a byte buffer containing a FRP256V1 public key

CMOX_ECC_FRP256V1_SECRET_LEN

Byte length for a byte buffer containing a FRP256V1 ECDH secret

CMOX_ECC_SM2_SIG_LEN

Byte length for a byte buffer containing a SM2 signature

CMOX_ECC_SM2_PRIVKEY_LEN

Byte length for a byte buffer containing a SM2 private key

CMOX_ECC_SM2_PUBKEY_LEN

Byte length for a byte buffer containing a SM2 public key

CMOX_ECC_SM2_SECRET_LEN

Byte length for a byte buffer containing a SM2 ECDH secret

CMOX_ECC_SM2TEST_SIG_LEN

Byte length for a byte buffer containing a SM2TEST signature

CMOX_ECC_SM2TEST_PRIVKEY_LEN

Byte length for a byte buffer containing a SM2TEST private key

CMOX_ECC_SM2TEST_PUBKEY_LEN

Byte length for a byte buffer containing a SM2TEST public key

CMOX_ECC_SM2TEST_SECRET_LEN

Byte length for a byte buffer containing a SM2TEST ECDH secret

Functions

void cmox_ecc_construct ( cmox_ecc_handle_t * P_pEccCtx , const cmox_math_funcs_t P_Math , uint8_t * P_pBuf , size_t P_BufLen )

Mandatory function to set Low Level Mathematical Functions, and working memory buffer, for ECC.

Parameters :

• P_pEccCtx – [inout] Context for ECC operations

• P_Math – [in] Structure pointer with the Low-level Mathematical functions This parameter can be one of the following:

  • CMOX_MATH_FUNCS_SMALL

  • CMOX_MATH_FUNCS_FAST

  • CMOX_MATH_FUNCS_SUPERFAST256

• P_pBuf – [in] The preallocated static buffer that will be used

• P_BufLen – [in] The size in bytes of the P_pBuf buffer

void cmox_ecc_cleanup ( cmox_ecc_handle_t * P_pEccCtx )

Clean the ECC context and the internal temporary buffer.

Parameters :

P_pEccCtx – [inout] Context for ECC operations

Typedefs

typedef const struct cmox_ecc_customCurve_optStr_st * cmox_ecc_customCurve_opt_t

struct for speed/RAM optimizations struct ptr for speed/RAM opt

Variables

const cmox_ecc_customCurve_opt_t cmox_ecc_customCurve_opt_low

Low RAM usage (slowest).

const cmox_ecc_customCurve_opt_t cmox_ecc_customCurve_opt_mid

Mid RAM usage.

const cmox_ecc_customCurve_opt_t cmox_ecc_customCurve_opt_high

High RAM usage (fastest).

Functions

cmox_ecc_retval_t cmox_ecc_customCurveConstruct ( cmox_ecc_handle_t * P_pEccCtx , cmox_ecc_impl_t * P_pCurve , cmox_ecc_customCurve_opt_t P_OptLevel , const uint8_t * P_pP , size_t P_PLen , const uint8_t * P_pN , size_t P_NLen , const uint8_t * P_pA , size_t P_ALen , const uint8_t * P_pB , size_t P_BLen , const uint8_t * P_pGx , size_t P_GxLen , const uint8_t * P_pGy , size_t P_GyLen )

Function to create a custom Short-Weierstrass curve.

Note

All the array parameters are big-endian arrays, where the first byte is the most significant one.

Warning

This function does not check if the parameters effectively form an elliptic curve, so the user must be sure about the parameters that are passed to the function

Parameters :

• P_pEccCtx – [in] Context for ECC operations

• P_pCurve – [out] Pointer to a curve that will be built and filled

• P_OptLevel – [in] Optimization level (speed vs. RAM usage) This parameter can be one of the following:

  • cmox_ecc_customCurve_opt_low

  • cmox_ecc_customCurve_opt_mid

  • cmox_ecc_customCurve_opt_high

• P_pP – [in] Modulus of the curve

• P_PLen – [in] Byte length of the modulus

• P_pN – [in] Order of the curve

• P_NLen – [in] Byte length of the order

• P_pA – [in] Parameter A of the curve

• P_ALen – [in] Byte length of the parameter A

• P_pB – [in] Parameter B of the curve

• P_BLen – [in] Byte length of the parameter B

• P_pGx – [in] X coordinate of the Generator Point

• P_GxLen – [in] Byte length of the X coordinate

• P_pGy – [in] Y coordinate of the Generator Point

• P_GyLen – [in] Byte length of the Y coordinate

Return values :

• CMOX_ECC_SUCCESS –

• CMOX_ECC_ERR_BAD_PARAMETERS –

• CMOX_ECC_ERR_MEMORY_FAIL –

void cmox_ecc_customCurveCleanup ( cmox_ecc_handle_t * P_pEccCtx , cmox_ecc_impl_t * P_pCurve )

Destroy (and release the allocated memory) a custom curve.

Parameters :

• P_pEccCtx – [in] Context for ECC operations

• P_pCurve – [inout] Pointer to the curve to destroy

Defines

CMOX_ECC_SUCCESS

Success

CMOX_ECC_ERR_INTERNAL

Internal computat. error (e.g. hash)

CMOX_ECC_ERR_BAD_PARAMETERS

Bad input parameters

CMOX_ECC_ERR_INVALID_PUBKEY

Invalid Public Key value

CMOX_ECC_ERR_INVALID_SIGNATURE

Invalid Signature value

CMOX_ECC_ERR_WRONG_RANDOM

Random not compliant with the API (Recall with other random material)

CMOX_ECC_ERR_MEMORY_FAIL

Not enough memory

CMOX_ECC_ERR_MATHCURVE_MISMATCH

Math customization not supported by current ECC curve

CMOX_ECC_ERR_ALGOCURVE_MISMATCH

ECC curve not supported by current functionality

CMOX_ECC_AUTH_SUCCESS

ECC signature successful verification

CMOX_ECC_AUTH_FAIL

ECC signature not verified

Typedefs

typedef uint32_t cmox_ecc_retval_t

Return value type for ECC module.

Typedefs

typedef const struct cmox_ecc_implStruct_st * cmox_ecc_impl_t

Pointer type for the ECC curve function parameter.

struct cmox_ecc_handle_t

#include <cmox_ecc_types.h>

Structure for the ECC context.

Public Members

cmox_membuf_handle_st membuf_str

Memory buffer structure

cmox_math_funcs_t math_ptr

Math customization structure

uint32_t magic_num_check

Magic number for diagnostic checks

Functions

cmox_ecc_retval_t cmox_ecdh ( cmox_ecc_handle_t * P_pEccCtx , const cmox_ecc_impl_t P_CurveParams , const uint8_t * P_pPrivKey , size_t P_PrivKeyLen , const uint8_t * P_pPubKey , size_t P_PubKeyLen , uint8_t * P_pSharedSecret , size_t * P_pSharedSecretLen )

Generate a shared secret from a private key and a public key.

Parameters :

• P_pEccCtx – [in] Context for ECC operations

• P_CurveParams – [in] Curve Parameters and point functions This parameter can be one of the following:

  • CMOX_ECC_CURVE25519

  • CMOX_ECC_CURVE448

  • CMOX_ECC_SECP224R1_LOWMEM

  • CMOX_ECC_SECP224R1_HIGHMEM

  • CMOX_ECC_SECP256R1_LOWMEM

  • CMOX_ECC_SECP256R1_HIGHMEM

  • CMOX_ECC_SECP384R1_LOWMEM

  • CMOX_ECC_SECP384R1_HIGHMEM

  • CMOX_ECC_SECP521R1_LOWMEM

  • CMOX_ECC_SECP521R1_HIGHMEM

  • CMOX_ECC_SECP256K1_LOWMEM

  • CMOX_ECC_SECP256K1_HIGHMEM

  • CMOX_ECC_BPP160R1_LOWMEM

  • CMOX_ECC_BPP160R1_HIGHMEM

  • CMOX_ECC_BPP192R1_LOWMEM

  • CMOX_ECC_BPP192R1_HIGHMEM

  • CMOX_ECC_BPP224R1_LOWMEM

  • CMOX_ECC_BPP224R1_HIGHMEM

  • CMOX_ECC_BPP256R1_LOWMEM

  • CMOX_ECC_BPP256R1_HIGHMEM

  • CMOX_ECC_BPP320R1_LOWMEM

  • CMOX_ECC_BPP320R1_HIGHMEM

  • CMOX_ECC_BPP384R1_LOWMEM

  • CMOX_ECC_BPP384R1_HIGHMEM

  • CMOX_ECC_BPP512R1_LOWMEM

  • CMOX_ECC_BPP512R1_HIGHMEM

  • CMOX_ECC_BPP160T1_LOWMEM

  • CMOX_ECC_BPP160T1_HIGHMEM

  • CMOX_ECC_BPP192T1_LOWMEM

  • CMOX_ECC_BPP192T1_HIGHMEM

  • CMOX_ECC_BPP224T1_LOWMEM

  • CMOX_ECC_BPP224T1_HIGHMEM

  • CMOX_ECC_BPP256T1_LOWMEM

  • CMOX_ECC_BPP256T1_HIGHMEM

  • CMOX_ECC_BPP320T1_LOWMEM

  • CMOX_ECC_BPP320T1_HIGHMEM

  • CMOX_ECC_BPP384T1_LOWMEM

  • CMOX_ECC_BPP384T1_HIGHMEM

  • CMOX_ECC_BPP512T1_LOWMEM

  • CMOX_ECC_BPP512T1_HIGHMEM

  • CMOX_ECC_FRP256V1_LOWMEM

  • CMOX_ECC_FRP256V1_HIGHMEM

• P_pPrivKey – [in] Buffer with the private key

• P_PrivKeyLen – [in] Private key length

• P_pPubKey – [in] Buffer with the public key

• P_PubKeyLen – [in] Public key length

• P_pSharedSecret – [out] Buffer for the shared secret

• P_pSharedSecretLen – [out] Shared secret length

Return values :

• CMOX_ECC_SUCCESS – Everything OK

• CMOX_ECC_ERR_MATHCURVE_MISMATCH – Mathematical function set is not compatible with current ECC curve

• CMOX_ECC_ERR_ALGOCURVE_MISMATCH – Curve is not compatible with current functionality

• CMOX_ECC_ERR_BAD_PARAMETERS – Some NULL/wrong/empty parameter or Construct API not called

• CMOX_ECC_ERR_MEMORY_FAIL – Not enough memory

• CMOX_ECC_ERR_INVALID_PUBKEY – Public key not in a valid format

Functions

cmox_ecc_retval_t cmox_ecdsa_keyGen ( cmox_ecc_handle_t * P_pEccCtx , const cmox_ecc_impl_t P_CurveParams , const uint8_t * P_pRandom , size_t P_RandomLen , uint8_t * P_pPrivKey , size_t * P_pPrivKeyLen , uint8_t * P_pPubKey , size_t * P_pPubKeyLen )

Generate private and public keys to use with ECDSA.

Note

the private key is derived from the random in the following way:

privkey = (random >> ((WORD_NBIT - N_MSW_NBIT) & 7)) + 1

, where: random is the input random buffer (interpreted as a big-endian integer), WORD_NBIT is the bitsize of a cpu word, N_MSW_NBIT is the bitlength of the most significant word of the parameter N of the curve.

Note

If P_RandomLen is not enough, an error is returned and P_pPrivKeyLen contains the minimum number of bytes of random to provide (and is also the minimum length of P_pPrivKey), while P_pPubKeyLen contains the minimum length of P_pPubKey.

Parameters :

• P_pEccCtx – [in] Context for ECC operations

• P_CurveParams – [in] Curve Parameters and point functions This parameter can be one of the following:

  • CMOX_ECC_SECP224R1_LOWMEM

  • CMOX_ECC_SECP224R1_HIGHMEM

  • CMOX_ECC_SECP256R1_LOWMEM

  • CMOX_ECC_SECP256R1_HIGHMEM

  • CMOX_ECC_SECP384R1_LOWMEM

  • CMOX_ECC_SECP384R1_HIGHMEM

  • CMOX_ECC_SECP521R1_LOWMEM

  • CMOX_ECC_SECP521R1_HIGHMEM

  • CMOX_ECC_SECP256K1_LOWMEM

  • CMOX_ECC_SECP256K1_HIGHMEM

  • CMOX_ECC_BPP160R1_LOWMEM

  • CMOX_ECC_BPP160R1_HIGHMEM

  • CMOX_ECC_BPP192R1_LOWMEM

  • CMOX_ECC_BPP192R1_HIGHMEM

  • CMOX_ECC_BPP224R1_LOWMEM

  • CMOX_ECC_BPP224R1_HIGHMEM

  • CMOX_ECC_BPP256R1_LOWMEM

  • CMOX_ECC_BPP256R1_HIGHMEM

  • CMOX_ECC_BPP320R1_LOWMEM

  • CMOX_ECC_BPP320R1_HIGHMEM

  • CMOX_ECC_BPP384R1_LOWMEM

  • CMOX_ECC_BPP384R1_HIGHMEM

  • CMOX_ECC_BPP512R1_LOWMEM

  • CMOX_ECC_BPP512R1_HIGHMEM

  • CMOX_ECC_BPP160T1_LOWMEM

  • CMOX_ECC_BPP160T1_HIGHMEM

  • CMOX_ECC_BPP192T1_LOWMEM

  • CMOX_ECC_BPP192T1_HIGHMEM

  • CMOX_ECC_BPP224T1_LOWMEM

  • CMOX_ECC_BPP224T1_HIGHMEM

  • CMOX_ECC_BPP256T1_LOWMEM

  • CMOX_ECC_BPP256T1_HIGHMEM

  • CMOX_ECC_BPP320T1_LOWMEM

  • CMOX_ECC_BPP320T1_HIGHMEM

  • CMOX_ECC_BPP384T1_LOWMEM

  • CMOX_ECC_BPP384T1_HIGHMEM

  • CMOX_ECC_BPP512T1_LOWMEM

  • CMOX_ECC_BPP512T1_HIGHMEM

  • CMOX_ECC_FRP256V1_LOWMEM

  • CMOX_ECC_FRP256V1_HIGHMEM

• P_pRandom – [in] Buffer of random bytes

• P_RandomLen – [in] Byte length of the random buffer

• P_pPrivKey – [out] Buffer with the private key (in range [1; N - 1])

• P_pPrivKeyLen – [out] Byte length of the private key

• P_pPubKey – [out] Buffer with the public key

• P_pPubKeyLen – [out] Byte length of the public key

Return values :

• CMOX_ECC_SUCCESS – Everything OK

• CMOX_ECC_ERR_MATHCURVE_MISMATCH – Mathematical function set is not compatible with current ECC curve

• CMOX_ECC_ERR_ALGOCURVE_MISMATCH – Curve is not compatible with current functionality

• CMOX_ECC_ERR_BAD_PARAMETERS – Some NULL/wrong/empty parameter or Construct API not called

• CMOX_ECC_ERR_WRONG_RANDOM – Random material too short or not valid for the functionality

• CMOX_ECC_ERR_MEMORY_FAIL – Not enough memory

cmox_ecc_retval_t cmox_ecdsa_sign ( cmox_ecc_handle_t * P_pEccCtx , const cmox_ecc_impl_t P_CurveParams , const uint8_t * P_pRandom , size_t P_RandomLen , const uint8_t * P_pPrivKey , size_t P_PrivKeyLen , const uint8_t * P_pDigest , size_t P_DigestLen , uint8_t * P_pSignature , size_t * P_pSignatureLen )

Generate a signature, using ECDSA.

Note

the internal value k, used as scalar and multiplied by the base point, is derived from the random in the following way:

k = (random >> ((WORD_NBIT - N_MSW_NBIT) & 7)) + 1

, where: random is the input random buffer (interpreted as a big-endian integer), WORD_NBIT is the bitsize of a cpu word, N_MSW_NBIT is the bitlength of the most significant word of the parameter N of the curve.

Note

If P_RandomLen is not enough, an error is returned and P_pSignatureLen contains the minimum number of bytes of random to provide (and is also the minimum length of P_pPrivKey, and half the length of P_pSignature).

Parameters :

• P_pEccCtx – [in] Context for ECC operations

• P_CurveParams – [in] Curve Parameters and point functions This parameter can be one of the following:

  • CMOX_ECC_SECP224R1_LOWMEM

  • CMOX_ECC_SECP224R1_HIGHMEM

  • CMOX_ECC_SECP256R1_LOWMEM

  • CMOX_ECC_SECP256R1_HIGHMEM

  • CMOX_ECC_SECP384R1_LOWMEM

  • CMOX_ECC_SECP384R1_HIGHMEM

  • CMOX_ECC_SECP521R1_LOWMEM

  • CMOX_ECC_SECP521R1_HIGHMEM

  • CMOX_ECC_SECP256K1_LOWMEM

  • CMOX_ECC_SECP256K1_HIGHMEM

  • CMOX_ECC_BPP160R1_LOWMEM

  • CMOX_ECC_BPP160R1_HIGHMEM

  • CMOX_ECC_BPP192R1_LOWMEM

  • CMOX_ECC_BPP192R1_HIGHMEM

  • CMOX_ECC_BPP224R1_LOWMEM

  • CMOX_ECC_BPP224R1_HIGHMEM

  • CMOX_ECC_BPP256R1_LOWMEM

  • CMOX_ECC_BPP256R1_HIGHMEM

  • CMOX_ECC_BPP320R1_LOWMEM

  • CMOX_ECC_BPP320R1_HIGHMEM

  • CMOX_ECC_BPP384R1_LOWMEM

  • CMOX_ECC_BPP384R1_HIGHMEM

  • CMOX_ECC_BPP512R1_LOWMEM

  • CMOX_ECC_BPP512R1_HIGHMEM

  • CMOX_ECC_BPP160T1_LOWMEM

  • CMOX_ECC_BPP160T1_HIGHMEM

  • CMOX_ECC_BPP192T1_LOWMEM

  • CMOX_ECC_BPP192T1_HIGHMEM

  • CMOX_ECC_BPP224T1_LOWMEM

  • CMOX_ECC_BPP224T1_HIGHMEM

  • CMOX_ECC_BPP256T1_LOWMEM

  • CMOX_ECC_BPP256T1_HIGHMEM

  • CMOX_ECC_BPP320T1_LOWMEM

  • CMOX_ECC_BPP320T1_HIGHMEM

  • CMOX_ECC_BPP384T1_LOWMEM

  • CMOX_ECC_BPP384T1_HIGHMEM

  • CMOX_ECC_BPP512T1_LOWMEM

  • CMOX_ECC_BPP512T1_HIGHMEM

  • CMOX_ECC_FRP256V1_LOWMEM

  • CMOX_ECC_FRP256V1_HIGHMEM

• P_pRandom – [in] Buffer of random bytes

• P_RandomLen – [in] Byte length of the random buffer

• P_pPrivKey – [in] Buffer with the private key

• P_PrivKeyLen – [in] Byte length of the private key

• P_pDigest – [in] Buffer with the digest to sign

• P_DigestLen – [in] Byte length of the digest

• P_pSignature – [out] Buffer with the signature (concatenation of R and S)

• P_pSignatureLen – [out] Byte length of the signature

Return values :

• CMOX_ECC_SUCCESS – Everything OK

• CMOX_ECC_ERR_MATHCURVE_MISMATCH – Mathematical function set is not compatible with current ECC curve

• CMOX_ECC_ERR_ALGOCURVE_MISMATCH – Curve is not compatible with current functionality

• CMOX_ECC_ERR_BAD_PARAMETERS – Some NULL/wrong/empty parameter or Construct API not called

• CMOX_ECC_ERR_WRONG_RANDOM – Random material too short or not valid for the functionality

• CMOX_ECC_ERR_MEMORY_FAIL – Not enough memory

cmox_ecc_retval_t cmox_ecdsa_verify ( cmox_ecc_handle_t * P_pEccCtx , const cmox_ecc_impl_t P_CurveParams , const uint8_t * P_pPubKey , size_t P_PubKeyLen , const uint8_t * P_pDigest , size_t P_DigestLen , const uint8_t * P_pSignature , size_t P_SignatureLen , uint32_t * P_pFaultCheck )

Verify a signature, using ECDSA.

Note

P_pFaultCheck value, if the parameter is provided, MUST be checked to be equal to the retval, and both MUST be equal to the successful value. P_pFaultCheck MUST be checked only if the main result is successful, and has no relevance if the main result is not successful. Every comparison (both for the return value and for P_pFaultCheck) must be done against the success value, and not comparing the value with the failure value. Indeed, in presence of faults, especially P_pFaultCheck, could be a dirty value.

Parameters :

• P_pEccCtx – [in] Context for ECC operations

• P_CurveParams – [in] Curve Parameters and point functions This parameter can be one of the following:

  • CMOX_ECC_SECP224R1_LOWMEM

  • CMOX_ECC_SECP224R1_HIGHMEM

  • CMOX_ECC_SECP256R1_LOWMEM

  • CMOX_ECC_SECP256R1_HIGHMEM

  • CMOX_ECC_SECP384R1_LOWMEM

  • CMOX_ECC_SECP384R1_HIGHMEM

  • CMOX_ECC_SECP521R1_LOWMEM

  • CMOX_ECC_SECP521R1_HIGHMEM

  • CMOX_ECC_SECP256K1_LOWMEM

  • CMOX_ECC_SECP256K1_HIGHMEM

  • CMOX_ECC_BPP160R1_LOWMEM

  • CMOX_ECC_BPP160R1_HIGHMEM

  • CMOX_ECC_BPP192R1_LOWMEM

  • CMOX_ECC_BPP192R1_HIGHMEM

  • CMOX_ECC_BPP224R1_LOWMEM

  • CMOX_ECC_BPP224R1_HIGHMEM

  • CMOX_ECC_BPP256R1_LOWMEM

  • CMOX_ECC_BPP256R1_HIGHMEM

  • CMOX_ECC_BPP320R1_LOWMEM

  • CMOX_ECC_BPP320R1_HIGHMEM

  • CMOX_ECC_BPP384R1_LOWMEM

  • CMOX_ECC_BPP384R1_HIGHMEM

  • CMOX_ECC_BPP512R1_LOWMEM

  • CMOX_ECC_BPP512R1_HIGHMEM

  • CMOX_ECC_BPP160T1_LOWMEM

  • CMOX_ECC_BPP160T1_HIGHMEM

  • CMOX_ECC_BPP192T1_LOWMEM

  • CMOX_ECC_BPP192T1_HIGHMEM

  • CMOX_ECC_BPP224T1_LOWMEM

  • CMOX_ECC_BPP224T1_HIGHMEM

  • CMOX_ECC_BPP256T1_LOWMEM

  • CMOX_ECC_BPP256T1_HIGHMEM

  • CMOX_ECC_BPP320T1_LOWMEM

  • CMOX_ECC_BPP320T1_HIGHMEM

  • CMOX_ECC_BPP384T1_LOWMEM

  • CMOX_ECC_BPP384T1_HIGHMEM

  • CMOX_ECC_BPP512T1_LOWMEM

  • CMOX_ECC_BPP512T1_HIGHMEM

  • CMOX_ECC_FRP256V1_LOWMEM

  • CMOX_ECC_FRP256V1_HIGHMEM

• P_pPubKey – [in] Buffer with the public key

• P_PubKeyLen – [in] Byte length of the public key

• P_pDigest – [in] Buffer with the digest to sign

• P_DigestLen – [in] Byte length of the digest

• P_pSignature – [in] Buffer with the signature (concatenation of R and S)

• P_SignatureLen – [in] Byte length of the signature

• P_pFaultCheck – [out] Optional value to check, together with the retval, to verify if some fault happened

Return values :

• CMOX_ECC_AUTH_SUCCESS – Signature verified

• CMOX_ECC_AUTH_FAIL – Signature NOT verified

• CMOX_ECC_ERR_MATHCURVE_MISMATCH – Mathematical function set is not compatible with current ECC curve

• CMOX_ECC_ERR_ALGOCURVE_MISMATCH – Curve is not compatible with current functionality

• CMOX_ECC_ERR_BAD_PARAMETERS – Some NULL/wrong/empty parameter or Construct API not called

• CMOX_ECC_ERR_MEMORY_FAIL – Not enough memory

• CMOX_ECC_ERR_INVALID_SIGNATURE – Input signature corrupted or not in the expected format

• CMOX_ECC_ERR_INVALID_PUBKEY – Public key not in a valid format

Functions

cmox_ecc_retval_t cmox_eddsa_keyGen ( cmox_ecc_handle_t * P_pEccCtx , const cmox_ecc_impl_t P_CurveParams , const uint8_t * P_pRandom , size_t P_RandomLen , uint8_t * P_pPrivKey , size_t * P_pPrivKeyLen , uint8_t * P_pPubKey , size_t * P_pPubKeyLen )

Generate private and public keys to use with EDDSA.

Note

If P_RandomLen is not enough, an error is returned and P_pPrivKeyLen contains the minimum number of bytes of random to provide (and is also half the minimum length of P_pPrivKey), while P_pPubKeyLen contains the minimum length of P_pPubKey.

Parameters :

• P_pEccCtx – [in] Context for ECC operations

• P_CurveParams – [in] Curve Parameters and point functions This parameter can be one of the following:

  • CMOX_ECC_ED25519_HIGHMEM

  • CMOX_ECC_ED25519_OPT_LOWMEM

  • CMOX_ECC_ED25519_OPT_HIGHMEM

  • CMOX_ECC_ED448_LOWMEM

  • CMOX_ECC_ED448_HIGHMEM

• P_pRandom – [in] Buffer of random bytes

• P_RandomLen – [in] Byte length of the random buffer

• P_pPrivKey – [out] Buffer with the private key, whose first half will be the secret value and the second half will contain the public key

• P_pPrivKeyLen – [out] Byte length of the private key

• P_pPubKey – [out] Buffer with the public key

• P_pPubKeyLen – [out] Byte length of the public key

Return values :

• CMOX_ECC_SUCCESS – Everything OK

• CMOX_ECC_ERR_MATHCURVE_MISMATCH – Mathematical function set is not compatible with current ECC curve

• CMOX_ECC_ERR_ALGOCURVE_MISMATCH – Curve is not compatible with current functionality

• CMOX_ECC_ERR_BAD_PARAMETERS – Some NULL/wrong/empty parameter or Construct API not called

• CMOX_ECC_ERR_WRONG_RANDOM – Random material too short or not valid for the functionality

• CMOX_ECC_ERR_MEMORY_FAIL – Not enough memory

• CMOX_ECC_ERR_INTERNAL – Something went wrong during internal computations (e.g. hash)

cmox_ecc_retval_t cmox_eddsa_sign ( cmox_ecc_handle_t * P_pEccCtx , const cmox_ecc_impl_t P_CurveParams , const uint8_t * P_pPrivKey , size_t P_PrivKeyLen , const uint8_t * P_pMessage , size_t P_MessageLen , uint8_t * P_pSignature , size_t * P_pSignatureLen )

Generate a signature, using EDDSA.

Parameters :

• P_pEccCtx – [in] Context for ECC operations

• P_CurveParams – [in] Curve Parameters and point functions This parameter can be one of the following:

  • CMOX_ECC_ED25519_HIGHMEM

  • CMOX_ECC_ED25519_OPT_LOWMEM

  • CMOX_ECC_ED25519_OPT_HIGHMEM

  • CMOX_ECC_ED448_LOWMEM

  • CMOX_ECC_ED448_HIGHMEM

• P_pPrivKey – [in] Buffer with the private key, whose first half is the secret value and the second half contains the public key

• P_PrivKeyLen – [in] Byte length of the private key

• P_pMessage – [in] Buffer with the message to sign

• P_MessageLen – [in] Byte length of the message

• P_pSignature – [out] Buffer with the signature (concatenation of R and S)

• P_pSignatureLen – [out] Byte length of the signature

Return values :

• CMOX_ECC_SUCCESS – Everything OK

• CMOX_ECC_ERR_MATHCURVE_MISMATCH – Mathematical function set is not compatible with current ECC curve

• CMOX_ECC_ERR_ALGOCURVE_MISMATCH – Curve is not compatible with current functionality

• CMOX_ECC_ERR_BAD_PARAMETERS – Some NULL/wrong/empty parameter or Construct API not called

• CMOX_ECC_ERR_MEMORY_FAIL – Not enough memory

• CMOX_ECC_ERR_INTERNAL – Something went wrong during internal computations (e.g. hash)

cmox_ecc_retval_t cmox_eddsa_verify ( cmox_ecc_handle_t * P_pEccCtx , const cmox_ecc_impl_t P_CurveParams , const uint8_t * P_pPubKey , size_t P_PubKeyLen , const uint8_t * P_pMessage , size_t P_MessageLen , const uint8_t * P_pSignature , size_t P_SignatureLen , uint32_t * P_pFaultCheck )

Verify a signature, using EDDSA.

Note

P_pFaultCheck value, if the parameter is provided, MUST be checked to be equal to the retval, and both MUST be equal to the successful value. P_pFaultCheck MUST be checked only if the main result is successful, and has no relevance if the main result is not successful. Every comparison (both for the return value and for P_pFaultCheck) must be done against the success value, and not comparing the value with the failure value. Indeed, in presence of faults, especially P_pFaultCheck, could be a dirty value.

Parameters :

• P_pEccCtx – [in] Context for ECC operations

• P_CurveParams – [in] Curve Parameters and point functions This parameter can be one of the following:

  • CMOX_ECC_ED25519_HIGHMEM

  • CMOX_ECC_ED25519_OPT_LOWMEM

  • CMOX_ECC_ED25519_OPT_HIGHMEM

  • CMOX_ECC_ED448_LOWMEM

  • CMOX_ECC_ED448_HIGHMEM

• P_pPubKey – [in] Buffer with the public key

• P_PubKeyLen – [in] Byte length of the public key

• P_pMessage – [in] Buffer with the message to verify

• P_MessageLen – [in] Byte length of the message

• P_pSignature – [in] Buffer with the signature (concatenation of R and S)

• P_SignatureLen – [in] Byte length of the signature

• P_pFaultCheck – [out] Optional value to check, together with the retval, to verify if some fault happened

Return values :

• CMOX_ECC_AUTH_SUCCESS – Signature verified

• CMOX_ECC_AUTH_FAIL – Signature NOT verified

• CMOX_ECC_ERR_MATHCURVE_MISMATCH – Mathematical function set is not compatible with current ECC curve

• CMOX_ECC_ERR_ALGOCURVE_MISMATCH – Curve is not compatible with current functionality

• CMOX_ECC_ERR_BAD_PARAMETERS – Some NULL/wrong/empty parameter or Construct API not called

• CMOX_ECC_ERR_MEMORY_FAIL – Not enough memory

• CMOX_ECC_ERR_INTERNAL – Something went wrong during internal computations (e.g. hash)

• CMOX_ECC_ERR_INVALID_SIGNATURE – Input signature corrupted or not in the expected format

• CMOX_ECC_ERR_INVALID_PUBKEY – Public key not in a valid format

Functions

cmox_ecc_retval_t cmox_sm2_keyGen ( cmox_ecc_handle_t * P_pEccCtx , const cmox_ecc_impl_t P_CurveParams , const uint8_t * P_pRandom , size_t P_RandomLen , uint8_t * P_pPrivKey , size_t * P_pPrivKeyLen , uint8_t * P_pPubKey , size_t * P_pPubKeyLen )

Generate private and public keys to use with ECDSA.

Note

the private key is derived from the random in the following way:

privkey = (random >> ((WORD_NBIT - N_MSW_NBIT) & 7)) + 1

, where: random is the input random buffer (interpreted as a big-endian integer), WORD_NBIT is the bitsize of a cpu word, N_MSW_NBIT is the bitlength of the most significant word of the parameter N of the curve.

Note

If P_RandomLen is not enough, an error is returned and P_pPrivKeyLen contains the minimum number of bytes of random to provide (and is also the minimum length of P_pPrivKey), while P_pPubKeyLen contains the minimum length of P_pPubKey.

Parameters :

• P_pEccCtx – [in] Context for ECC operations

• P_CurveParams – [in] Curve Parameters and point functions This parameter can be one of the following:

  • CMOX_ECC_SM2_LOWMEM

  • CMOX_ECC_SM2_HIGHMEM

  • CMOX_ECC_SM2TEST_LOWMEM

  • CMOX_ECC_SM2TEST_HIGHMEM

• P_pRandom – [in] Buffer of random bytes

• P_RandomLen – [in] Byte length of the random buffer

• P_pPrivKey – [out] Buffer with the private key (in range [1; N - 2])

• P_pPrivKeyLen – [out] Byte length of the private key

• P_pPubKey – [out] Buffer with the public key

• P_pPubKeyLen – [out] Byte length of the public key

Return values :

• CMOX_ECC_SUCCESS – Everything OK

• CMOX_ECC_ERR_MATHCURVE_MISMATCH – Mathematical function set is not compatible with current ECC curve

• CMOX_ECC_ERR_ALGOCURVE_MISMATCH – Curve is not compatible with current functionality

• CMOX_ECC_ERR_BAD_PARAMETERS – Some NULL/wrong/empty parameter or Construct API not called

• CMOX_ECC_ERR_WRONG_RANDOM – Random material too short or not valid for the functionality

• CMOX_ECC_ERR_MEMORY_FAIL – Not enough memory

cmox_ecc_retval_t cmox_sm2_computeZA ( cmox_ecc_handle_t * P_pEccCtx , const cmox_ecc_impl_t P_CurveParams , const uint8_t * P_pIDA , uint16_t P_ENTLA , const uint8_t * P_pPubKey , size_t P_PubKeyLen , uint8_t * P_pZA , size_t * P_pZALen )

Compute ZA = HASH(ENTLA || IDA || a || b || xG || yG || xA || yA), that is the value to hash, together with the message, to obtain the digest to provide to cmox_sm2_sign and cmox_sm2_verify.

Parameters :

• P_pEccCtx – [in] Context for ECC operations

• P_CurveParams – [in] Curve Parameters and point functions This parameter can be one of the following:

  • CMOX_ECC_SM2_LOWMEM

  • CMOX_ECC_SM2_HIGHMEM

  • CMOX_ECC_SM2TEST_LOWMEM

  • CMOX_ECC_SM2TEST_HIGHMEM

• P_pIDA – [in] Buffer with ID (e.g. email “user@domain.com”) of the user

• P_ENTLA – [in] Bit length of the user ID (usually, multiple of 8)

• P_pPubKey – [in] Buffer with the public key (both X and Y)

• P_PubKeyLen – [in] Byte length of the public key

• P_pZA – [out] Buffer with ZA

• P_pZALen – [out] Byte length of ZA (optional parameter)

Return values :

• CMOX_ECC_SUCCESS – Everything OK

• CMOX_ECC_ERR_INTERNAL – Something went wrong during internal computations (e.g. hash)

• CMOX_ECC_ERR_MATHCURVE_MISMATCH – Mathematical function set is not compatible with current ECC curve

• CMOX_ECC_ERR_ALGOCURVE_MISMATCH – Curve is not compatible with current functionality

• CMOX_ECC_ERR_BAD_PARAMETERS – Some NULL/wrong/empty parameter or Construct API not called

• CMOX_ECC_ERR_MEMORY_FAIL – Not enough memory

cmox_ecc_retval_t cmox_sm2_sign ( cmox_ecc_handle_t * P_pEccCtx , const cmox_ecc_impl_t P_CurveParams , const uint8_t * P_pRandom , size_t P_RandomLen , const uint8_t * P_pPrivKey , size_t P_PrivKeyLen , const uint8_t * P_pDigest , size_t P_DigestLen , uint8_t * P_pSignature , size_t * P_pSignatureLen )

Generate a signature, using ECDSA.

Note

the internal value k, used as scalar and multiplied by the base point, is derived from the random in the following way:

k = (random >> ((WORD_NBIT - N_MSW_NBIT) & 7)) + 1

, where: random is the input random buffer (interpreted as a big-endian integer), WORD_NBIT is the bitsize of a cpu word, N_MSW_NBIT is the bitlength of the most significant word of the parameter N of the curve.

Note

If P_RandomLen is not enough, an error is returned and P_pSignatureLen contains the minimum number of bytes of random to provide (and is also the minimum length of P_pPrivKey, and half the length of P_pSignature).

Parameters :

• P_pEccCtx – [in] Context for ECC operations

• P_CurveParams – [in] Curve Parameters and point functions This parameter can be one of the following:

  • CMOX_ECC_SM2_LOWMEM

  • CMOX_ECC_SM2_HIGHMEM

  • CMOX_ECC_SM2TEST_LOWMEM

  • CMOX_ECC_SM2TEST_HIGHMEM

• P_pRandom – [in] Buffer of random bytes

• P_RandomLen – [in] Byte length of the random buffer

• P_pPrivKey – [in] Buffer with the private key

• P_PrivKeyLen – [in] Byte length of the private key

• P_pDigest – [in] Buffer with the digest to sign

• P_DigestLen – [in] Byte length of the digest

• P_pSignature – [out] Buffer with the signature (concatenation of R and S)

• P_pSignatureLen – [out] Byte length of the signature

Return values :

• CMOX_ECC_SUCCESS – Everything OK

• CMOX_ECC_ERR_MATHCURVE_MISMATCH – Mathematical function set is not compatible with current ECC curve

• CMOX_ECC_ERR_ALGOCURVE_MISMATCH – Curve is not compatible with current functionality

• CMOX_ECC_ERR_BAD_PARAMETERS – Some NULL/wrong/empty parameter or Construct API not called

• CMOX_ECC_ERR_WRONG_RANDOM – Random material too short or not valid for the functionality

• CMOX_ECC_ERR_MEMORY_FAIL – Not enough memory

cmox_ecc_retval_t cmox_sm2_verify ( cmox_ecc_handle_t * P_pEccCtx , const cmox_ecc_impl_t P_CurveParams , const uint8_t * P_pPubKey , size_t P_PubKeyLen , const uint8_t * P_pDigest , size_t P_DigestLen , const uint8_t * P_pSignature , size_t P_SignatureLen , uint32_t * P_pFaultCheck )

Verify a signature, using ECDSA.

Note

P_pFaultCheck value, if the parameter is provided, MUST be checked to be equal to the retval, and both MUST be equal to the successful value. P_pFaultCheck MUST be checked only if the main result is successful, and has no relevance if the main result is not successful. Every comparison (both for the return value and for P_pFaultCheck) must be done against the success value, and not comparing the value with the failure value. Indeed, in presence of faults, especially P_pFaultCheck, could be a dirty value.

Parameters :

• P_pEccCtx – [in] Context for ECC operations

• P_CurveParams – [in] Curve Parameters and point functions This parameter can be one of the following:

  • CMOX_ECC_SM2_LOWMEM

  • CMOX_ECC_SM2_HIGHMEM

  • CMOX_ECC_SM2TEST_LOWMEM

  • CMOX_ECC_SM2TEST_HIGHMEM

• P_pPubKey – [in] Buffer with the public key

• P_PubKeyLen – [in] Byte length of the public key

• P_pDigest – [in] Buffer with the digest to sign

• P_DigestLen – [in] Byte length of the digest

• P_pSignature – [in] Buffer with the signature (concatenation of R and S)

• P_SignatureLen – [in] Byte length of the signature

• P_pFaultCheck – [out] Optional value to check, together with the retval, to verify if some fault happened

Return values :

• CMOX_ECC_AUTH_SUCCESS – Signature verified

• CMOX_ECC_AUTH_FAIL – Signature NOT verified

• CMOX_ECC_ERR_MATHCURVE_MISMATCH – Mathematical function set is not compatible with current ECC curve

• CMOX_ECC_ERR_ALGOCURVE_MISMATCH – Curve is not compatible with current functionality

• CMOX_ECC_ERR_BAD_PARAMETERS – Some NULL/wrong/empty parameter or Construct API not called

• CMOX_ECC_ERR_MEMORY_FAIL – Not enough memory

• CMOX_ECC_ERR_INVALID_SIGNATURE – Input signature corrupted or not in the expected format

• CMOX_ECC_ERR_INVALID_PUBKEY – Public key not in a valid format

2.4. Hash module

group CMOX_HASH

Typedefs

typedef const struct cmox_hash_vtableStruct_st * cmox_hash_vtable_t

Hash Virtual Table.

This type specifies a pointer to the virtual table containing the methods for a particular algorithm (e.g. SHA256 or SM3)

typedef const struct cmox_hash_algoStruct_st * cmox_hash_algo_t

Hash algorithm type.

This type specifies the algorithm to use with the hash module (e.g. SHA256). The type is defined as a pointer to a structure, that contains the functions for the specific algorithm, defined in the library internally

struct cmox_hash_handle_t

#include <cmox_hash.h>

Hash handle structure definition.

Public Members

cmox_hash_vtable_t table

Hash virtual table

size_t tagLen

Size in bytes of the digest

Variables

const cmox_hash_algo_t CMOX_SHA1_ALGO

Identifier of the SHA1 hash function for single-call function (Defined internally).

const cmox_hash_algo_t CMOX_SHA224_ALGO

Identifier of the SHA224 hash function for single-call function (Defined internally).

const cmox_hash_algo_t CMOX_SHA256_ALGO

Identifier of the SHA256 hash function for single-call function (Defined internally).

const cmox_hash_algo_t CMOX_SHA384_ALGO

Identifier of the SHA384 hash function for single-call function (Defined internally).

const cmox_hash_algo_t CMOX_SHA512_ALGO

Identifier of the SHA512 hash function for single-call function (Defined internally).

const cmox_hash_algo_t CMOX_SHA512_224_ALGO

Identifier of the SHA512/224 hash function for single-call function (Defined internally).

const cmox_hash_algo_t CMOX_SHA512_256_ALGO

Identifier of the SHA512/256 hash function for single-call function (Defined internally).

const cmox_hash_algo_t CMOX_SHA3_224_ALGO

Identifier of the SHA3-224 hash function for single-call function (Defined internally).

const cmox_hash_algo_t CMOX_SHA3_256_ALGO

Identifier of the SHA3-256 hash function for single-call function (Defined internally).

const cmox_hash_algo_t CMOX_SHA3_384_ALGO

Identifier of the SHA3-384 hash function for single-call function (Defined internally).

const cmox_hash_algo_t CMOX_SHA3_512_ALGO

Identifier of the SHA3-512 hash function for single-call function (Defined internally).

const cmox_hash_algo_t CMOX_SHAKE128_ALGO

Identifier of the SHAKE128 hash function for single-call function (Defined internally).

const cmox_hash_algo_t CMOX_SHAKE256_ALGO

Identifier of the SHAKE256 hash function for single-call function (Defined internally).

const cmox_hash_algo_t CMOX_SM3_ALGO

Identifier of the SM3 hash function for single-call function (Defined internally).

Functions

cmox_hash_retval_t cmox_hash_cleanup ( cmox_hash_handle_t * P_pThis )

Cleanup the hash handler.

Parameters :

P_pThis – Hash handler to cleanup

Returns :

cmox_hash_retval_t Hash return value

cmox_hash_retval_t cmox_hash_init ( cmox_hash_handle_t * P_pThis )

Initialize the hash handle based on the selected algorithm.

Note

The hash handle must be derived from an algorithm-specific handle using the correct construct

Parameters :

P_pThis – Hash handle to initialize

Returns :

cmox_hash_retval_t Hash return value

cmox_hash_retval_t cmox_hash_setTagLen ( cmox_hash_handle_t * P_pThis , size_t P_tagLen )

Set the size of the digest.

Parameters :

• P_pThis – Hash handle to set

• P_tagLen – Size in bytes of the tag

Returns :

cmox_hash_retval_t Hash return value

cmox_hash_retval_t cmox_hash_append ( cmox_hash_handle_t * P_pThis , const uint8_t * P_pInput , size_t P_inputLen )

Append part or the totality of the plaintext to the hash handle.

Parameters :

• P_pThis – Hash handle to use for hashing the data

• P_pInput – Buffer of bytes containing the data to hash

• P_inputLen – Size in bytes of the data to hash

Returns :

cmox_hash_retval_t Hash return value

cmox_hash_retval_t cmox_hash_generateTag ( cmox_hash_handle_t * P_pThis , uint8_t * P_pDigest , size_t * P_pDigestLen )

Generate the digest of the already appended data.

Parameters :

• P_pThis – Hash handle used for appending the data to hash

• P_pDigest – Buffer of bytes where the digest will be stored

• P_pDigestLen – Number of bytes generated by the function. It is an optional parameter and can be set to NULL if not needed.

Returns :

cmox_hash_retval_t Hash return value

cmox_hash_retval_t cmox_hash_compute ( cmox_hash_algo_t P_algo , const uint8_t * P_pPlaintext , size_t P_plaintextLen , uint8_t * P_pDigest , const size_t P_expectedDigestLen , size_t * P_pComputedDigestLen )

Compute the digest of a message using a hash algorithm.

Parameters :

• P_algo – Identifier of the hash algorithm to use for the computation. This parameter can be one of the following:

  • CMOX_SHA1_ALGO

  • CMOX_SHA224_ALGO

  • CMOX_SHA256_ALGO

  • CMOX_SHA384_ALGO

  • CMOX_SHA512_ALGO

  • CMOX_SHA512_224_ALGO

  • CMOX_SHA512_256_ALGO

  • CMOX_SHA3_224_ALGO

  • CMOX_SHA3_256_ALGO

  • CMOX_SHA3_384_ALGO

  • CMOX_SHA3_512_ALGO

  • CMOX_SHAKE128_ALGO

  • CMOX_SHAKE256_ALGO

  • CMOX_SM3_ALGO

• P_pPlaintext – Buffer of bytes containing the message to hash

• P_plaintextLen – Size in bytes of the message to hash

• P_pDigest – Buffer of bytes that will contain the computed digest

• P_expectedDigestLen – Desired size in bytes of the digest to compute

• P_pComputedDigestLen – Number of bytes generated by the function. It is an optional parameter and can be set to NULL if not needed.

Returns :

cmox_hash_retval_t

Defines

CMOX_HASH_SUCCESS

Hash operation successfully performed.

CMOX_HASH_ERR_INTERNAL

Some error happens internally in the hash module.

CMOX_HASH_ERR_BAD_PARAMETER

One or more parameter has been wrongly passed to the function (e.g. pointer to NULL).

CMOX_HASH_ERR_BAD_OPERATION

Error on performing the operation (e.g. an operation has been called before initializing the handle).

CMOX_HASH_ERR_BAD_TAG_SIZE

The desired digest size is not supported by the hash algorithm.

Typedefs

typedef uint32_t cmox_hash_retval_t

Hash module return value type.

Typedefs

typedef const struct cmox_md_vtableStruct_st * cmox_md_vtable_t

MD Virtual Table.

This type specifies a pointer to the virtual table containing the methods for the particular MD algorithm

struct cmox_md_engineCommon_t

#include <cmox_md.h>

MD engine common structure definition.

Public Members

cmox_md_vtable_t table

MD virtual table

uint32_t flags

32 bit flags, used to perform keyschedule

size_t tagLen

Size of the required Digest

size_t blockLen

Internal: Size of processed blocks

size_t labelLen

Internal: Size of the final label of the MD padding scheme

uint32_t bitCount [ 2 ]

Internal: Keeps the count of processed bits

struct cmox_mdSmall_engine_t

#include <cmox_md.h>

MD small engine structure definition (Used by SHA1, SHA224, SHA256, SM3).

Public Members

cmox_md_engineCommon_t engine

Engine of the MD function

uint8_t internalBuffer [ 64 ]

Internal: It’s a buffer with the data to be hashed

uint32_t internalState [ 8 ]

Internal: Keeps the internal state

struct cmox_mdLarge_engine_t

#include <cmox_md.h>

MD large engine structure definition (Used by SHA384, SHA512).

Public Members

cmox_md_engineCommon_t engine

Engine of the MD function

uint8_t internalBuffer [ 128 ]

Internal: It’s a buffer with the data to be hashed

uint64_t internalState [ 8 ]

Internal: Keeps the internal state

struct cmox_mdSmall_handle_t

#include <cmox_md.h>

Generic MD small handle structure.

Public Members

cmox_hash_handle_t super

General hash module

cmox_mdSmall_engine_t md

MD small engine

struct cmox_mdLarge_handle_t

#include <cmox_md.h>

Generic MD large handle structure.

Public Members

cmox_hash_handle_t super

General hash module

cmox_mdLarge_engine_t md

MD large engine

Defines

CMOX_SHA1_SIZE

Maximum size in bytes of a SHA1 digest

Typedefs

typedef cmox_mdSmall_handle_t cmox_sha1_handle_t

SHA1 handle type definition.

Functions

cmox_hash_handle_t * cmox_sha1_construct ( cmox_sha1_handle_t * P_pThis )

SHA1 constructor.

Parameters :

P_pThis – Pointer to the SHA1 handle to initialize

Returns :

cmox_hash_handle_t* Pointer to a general hash handle. This will be used by the general purpose hash functions in order to perform the algorithm

Defines

CMOX_SHA224_SIZE

Maximum size in bytes of a SHA224 digest

Typedefs

typedef cmox_mdSmall_handle_t cmox_sha224_handle_t

SHA224 handle type definition.

Functions

cmox_hash_handle_t * cmox_sha224_construct ( cmox_sha224_handle_t * P_pThis )

SHA224 constructor.

Parameters :

P_pThis – Pointer to the SHA224 handle to initialize

Returns :

cmox_hash_handle_t* Pointer to a general hash handle. This will be used by the general purpose hash functions in order to perform the algorithm

Defines

CMOX_SHA256_SIZE

Maximum size in bytes of a SHA256 digest

Typedefs

typedef cmox_mdSmall_handle_t cmox_sha256_handle_t

SHA256 handle type definition.

Functions

cmox_hash_handle_t * cmox_sha256_construct ( cmox_sha256_handle_t * P_pThis )

SHA256 constructor.

Parameters :

P_pThis – Pointer to the SHA256 handle to initialize

Returns :

cmox_hash_handle_t* Pointer to a general hash handle. This will be used by the general purpose hash functions in order to perform the algorithm

Defines

CMOX_SHA384_SIZE

Maximum size in bytes of a SHA384 digest

Typedefs

typedef cmox_mdLarge_handle_t cmox_sha384_handle_t

SHA384 handle type definition.

Functions

cmox_hash_handle_t * cmox_sha384_construct ( cmox_sha384_handle_t * P_pThis )

SHA384 constructor.

Parameters :

P_pThis – Pointer to the SHA384 handle to initialize

Returns :

cmox_hash_handle_t* Pointer to a general hash handle. This will be used by the general purpose hash functions in order to perform the algorithm

Defines

CMOX_SHA512_SIZE

Maximum size in bytes of a SHA512 digest

CMOX_SHA512_224_SIZE

Maximum size in bytes of a SHA512/224 digest

CMOX_SHA512_256_SIZE

Maximum size in bytes of a SHA512/256 digest

Typedefs

typedef cmox_mdLarge_handle_t cmox_sha512_handle_t

SHA512 handle type definition.

Functions

cmox_hash_handle_t * cmox_sha512_construct ( cmox_sha512_handle_t * P_pThis )

SHA512 constructor.

Parameters :

P_pThis – Pointer to the SHA512 handle to initialize

Returns :

cmox_hash_handle_t* Pointer to a general hash handle. This will be used by the general purpose hash functions in order to perform the algorithm

cmox_hash_handle_t * cmox_sha512_224_construct ( cmox_sha512_handle_t * P_pThis )

SHA512/224 constructor.

Parameters :

P_pThis – Pointer to the SHA512 handle to initialize

Returns :

cmox_hash_handle_t* Pointer to a general hash handle. This will be used by the general purpose hash functions in order to perform the algorithm

cmox_hash_handle_t * cmox_sha512_256_construct ( cmox_sha512_handle_t * P_pThis )

SHA512/256 constructor.

Parameters :

P_pThis – Pointer to the SHA512 handle to initialize

Returns :

cmox_hash_handle_t* Pointer to a general hash handle. This will be used by the general purpose hash functions in order to perform the algorithm

Defines

CMOX_SM3_SIZE

Maximum size in bytes of a SM3 digest

Typedefs

typedef cmox_mdSmall_handle_t cmox_sm3_handle_t

SM3 handle type definition.

Functions

cmox_hash_handle_t * cmox_sm3_construct ( cmox_sm3_handle_t * P_pThis )

SM3 constructor.

Parameters :

P_pThis – Pointer to the SM3 handle to initialize

Returns :

cmox_hash_handle_t* Pointer to a general hash handle. This will be used by the general purpose hash functions in order to perform the algorithm

Defines

CMOX_SHA3_224_SIZE

Number of bytes (uint8_t) to store a SHA3-224 digest.

CMOX_SHA3_256_SIZE

Number of bytes (uint8_t) to store a SHA3-256 digest.

CMOX_SHA3_384_SIZE

Number of bytes (uint8_t) to store a SHA3-384 digest.

CMOX_SHA3_512_SIZE

Number of bytes (uint8_t) to store a SHA3-512 digest.

struct cmox_sha3_handle_t

#include <cmox_sha3.h>

SHA3 handle type definition.

Public Members

cmox_hash_handle_t super

General hash module

uint32_t flags

Internal flag

cmox_sponge_handle_t keccak

Keccak P-1600 handler

Functions

cmox_hash_handle_t * cmox_sha3_224_construct ( cmox_sha3_handle_t * P_pThis )

SHA3-224 constructor.

Parameters :

P_pThis – Pointer to the SHA3 handle to initialize

Returns :

cmox_hash_handle_t* Pointer to a general hash handle. This will be used by the general purpose hash functions in order to perform the algorithm

cmox_hash_handle_t * cmox_sha3_256_construct ( cmox_sha3_handle_t * P_pThis )

SHA3-256 constructor.

Parameters :

P_pThis – Pointer to the SHA3 handle to initialize

Returns :

cmox_hash_handle_t* Pointer to a general hash handle. This will be used by the general purpose hash functions in order to perform the algorithm

cmox_hash_handle_t * cmox_sha3_384_construct ( cmox_sha3_handle_t * P_pThis )

SHA3-384 constructor.

Parameters :

P_pThis – Pointer to the SHA3 handle to initialize

Returns :

cmox_hash_handle_t* Pointer to a general hash handle. This will be used by the general purpose hash functions in order to perform the algorithm

cmox_hash_handle_t * cmox_sha3_512_construct ( cmox_sha3_handle_t * P_pThis )

SHA3-512 constructor.

Parameters :

P_pThis – Pointer to the SHA3 handle to initialize

Returns :

cmox_hash_handle_t* Pointer to a general hash handle. This will be used by the general purpose hash functions in order to perform the algorithm

cmox_hash_handle_t * cmox_shake128_construct ( cmox_sha3_handle_t * P_pThis )

SHAKE128 constructor.

Parameters :

P_pThis – Pointer to the SHA3 handle to initialize

Returns :

cmox_hash_handle_t* Pointer to a general hash handle. This will be used by the general purpose hash functions in order to perform the algorithm

cmox_hash_handle_t * cmox_shake256_construct ( cmox_sha3_handle_t * P_pThis )

SHAKE256 constructor.

Parameters :

P_pThis – Pointer to the SHA3 handle to initialize

Returns :

cmox_hash_handle_t* Pointer to a general hash handle. This will be used by the general purpose hash functions in order to perform the algorithm

Defines

CMOX_SHA3_STATE_SIZE

Keccak-P 1600 state size in bytes

struct cmox_sponge_handle_t

#include <cmox_sponge.h>

Structure for Keccak-P 1600 sponge.

Public Members

uint8_t state [ CMOX_SHA3_STATE_SIZE ]

Internal state for Keccak P-1600

uint32_t rate

Rate

uint32_t byteIOIndex

Index for the IO bytes

uint32_t squeezing

flag identifying if the operation is a squeezing

2.5. Information module

group CMOX_INFO

Functions

void cmox_getInfos ( cmox_info_st * pInfo )

Get library information.

Parameters :

pInfo – Library information

Return values :

None –

struct cmox_info_st

#include <cmox_info.h>

Structure to store information.

Public Members

uint32_t version

Library version

uint32_t build [ 7 ]

Build info

2.6. Initialization module

group CMOX_INIT

Defines

CMOX_INIT_TARGET_AUTO

Let the cryptographic library auto-detect running STM32 target Series

CMOX_INIT_TARGET_F0

Select a STM32F0 Series target

CMOX_INIT_TARGET_F1

Select a STM32F1 Series target

CMOX_INIT_TARGET_F2

Select a STM32F2 Series target

CMOX_INIT_TARGET_F3

Select a STM32F3 Series target

CMOX_INIT_TARGET_F4

Select a STM32F4 Series target

CMOX_INIT_TARGET_F7

Select a STM32F7 Series target

CMOX_INIT_TARGET_H5

Select a STM32H5 Series target

CMOX_INIT_TARGET_H7

Select a STM32H72x/STM32H73x/STM32H74x/STM32H75x Series target

CMOX_INIT_TARGET_H7AB

Select a STM32H7Ax/STM32H7Bx Series target

CMOX_INIT_TARGET_H7RS

Select a STM32H7Rx/STM32H7Sx Series target

CMOX_INIT_TARGET_G0

Select a STM32G0 Series target

CMOX_INIT_TARGET_G4

Select a STM32G4 Series target

CMOX_INIT_TARGET_L0

Select a STM32L0 Series target

CMOX_INIT_TARGET_L1

Select a STM32L1 Series target

CMOX_INIT_TARGET_L4

Select a STM32L4/4+ Series target

CMOX_INIT_TARGET_L5

Select a STM32L5 Series target

CMOX_INIT_TARGET_U0

Select a STM32U0 Series target

CMOX_INIT_TARGET_U3

Select a STM32U3 Series target

CMOX_INIT_TARGET_WB

Select a STM32WB Series target

CMOX_INIT_TARGET_WBA

Select a STM32WBA Series target

CMOX_INIT_TARGET_WL

Select a STM32WL Series target

CMOX_INIT_SUCCESS

Init operation successfully performed

CMOX_INIT_FAIL

Init operation failed

Typedefs

typedef uint32_t cmox_init_target_t

Initialization target type.

typedef uint32_t cmox_init_retval_t

Return value type for Initialization module.

Initialization return value type

Functions

cmox_init_retval_t cmox_initialize ( cmox_init_arg_t * pInitArg )

Initialize CMOX library.

Note

pInitArg can be set to NULL: is equivalent to pInitArg->target = CMOX_INIT_TARGET_AUTO pInitArg->pArg = NULL

Parameters :

pInitArg – Initialization parameter see cmox_init_arg_t

Return values :

Initialization – status: CMOX_INIT_SUCCESS / CMOX_INIT_FAIL

cmox_init_retval_t cmox_finalize ( void * pArg )

Finalize CMOX library.

Parameters :

pArg – User defined parameter that is transmitted to Low Level services

Return values :

Finalization – status: CMOX_INIT_SUCCESS / CMOX_INIT_FAIL

cmox_init_retval_t cmox_ll_init ( void * pArg )

CMOX library low level initialization.

Note

Implements low level initialization required by cryptographic library to operate properly

Parameters :

pArg – User defined parameter that is transmitted from Initialize service

Return values :

Initialization – status: CMOX_INIT_SUCCESS / CMOX_INIT_FAIL

cmox_init_retval_t cmox_ll_deInit ( void * pArg )

CMOX library low level de-initialization.

Parameters :

pArg – User defined parameter that is transmitted from Finalize service

Return values :

De-initialization – status: CMOX_INIT_SUCCESS / CMOX_INIT_FAIL

struct cmox_init_arg_t

#include <cmox_init.h>

Initialization structure.

Public Members

cmox_init_target_t target

User target specification

void * pArg

User defined parameter that is transmitted to Low Level services

2.7. MAC module

group CMOX_MAC

Typedefs

typedef const struct cmox_cmac_implStruct_st * cmox_cmac_impl_t

CMAC implementation.

This type specifies the used block cipher for the CMAC construct. This type is defined as a pointer to a structure, that contains the functions needed for the specific implementation, defined in the library internally

struct cmox_cmac_handle_t

#include <cmox_cmac.h>

CMAC handle structure definition.

Public Members

cmox_mac_handle_t super

General MAC handle

cmox_blockcipher_handle_t blockCipher

Block cipher handle

uint32_t iv [ CMOX_CIPHER_BLOCK_SIZE ]

Buffer containing the Initialization Vector

uint8_t temp_buffer [ 16 ]

Temporary buffer to storing unprocessed data

uint32_t unprocessed_bytes

Number of bytes in the temporary buffer

Variables

const cmox_cmac_impl_t CMOX_CMAC_AESSMALL

Implementation of CMAC using AES (small implementation) (Defined internally).

const cmox_cmac_impl_t CMOX_CMAC_AESFAST

Implementation of CMAC using AES (fast implementation) (Defined internally).

Variables

const cmox_mac_algo_t CMOX_CMAC_AESFAST_ALGO

Identifier of the CMAC using AES (fast implementation) for single-call function (Defined internally).

const cmox_mac_algo_t CMOX_CMAC_AESSMALL_ALGO

Identifier of the CMAC using AES (small implementation) for single-call function (Defined internally).

Functions

cmox_mac_handle_t * cmox_cmac_construct ( cmox_cmac_handle_t * P_pThis , cmox_cmac_impl_t P_impl )

CMAC constructor.

The function is used for specifying which block cipher algorithm to use in order to implement the CMAC algorithm.

Parameters :

• P_pThis – Pointer to the CMAC handle to initialize

• P_impl – Constant that specifies the implementation to use. This parameter must be set with the following value:

  • CMOX_CMAC_AESFAST

  • CMOX_CMAC_AESSMALL

Returns :

cmox_mac_handle_t* Pointer to a general MAC handle. This will be used by the general purpose MAC functions in order to perform the algorithm

Typedefs

typedef const struct cmox_hmac_implStruct_st * cmox_hmac_impl_t

HMAC implementation.

This type specifies the used hash function for the HMAC construct. This type is defined as a pointer to a structure, that contains the functions needed for the specific implementation, defined in the library internally

typedef const struct cmox_hmac_supportStruct_st * cmox_hmac_support_t

HMAC internal support functions.

This type specifies some functions used internally by the HMAC in order to correctly compute the MAC. The structure pointed by the type is defined in the library internally

struct cmox_hmac_handle_t

#include <cmox_hmac.h>

HMAC handle structure definition.

Public Members

cmox_mac_handle_t super

General MAC handle

cmox_mdSmall_handle_t md_small

Handle for SHA-224, SHA-256, SM3

cmox_mdLarge_handle_t md_large

Handle for SHA-384, SHA-512

union cmox_hmac_handle_t hash_context

Hash function handle.

Depending on the chosen hash function, one of the two fields of the union will be used.

cmox_hash_handle_t * hash

Pointer to general hash handle

uint8_t key [ 128 ]

Buffer of bytes containing the derivated key

cmox_hmac_support_t support

Support functions for HMAC computation

Variables

const cmox_hmac_impl_t CMOX_HMAC_SHA1

Implementation of HMAC using SHA-1 (Defined internally).

const cmox_hmac_impl_t CMOX_HMAC_SHA224

Implementation of HMAC using SHA-224 (Defined internally).

const cmox_hmac_impl_t CMOX_HMAC_SHA256

Implementation of HMAC using SHA-256 (Defined internally).

const cmox_hmac_impl_t CMOX_HMAC_SHA384

Implementation of HMAC using SHA-384 (Defined internally).

const cmox_hmac_impl_t CMOX_HMAC_SHA512

Implementation of HMAC using SHA-512 (Defined internally).

const cmox_hmac_impl_t CMOX_HMAC_SHA512_224

Implementation of HMAC using SHA-512/224 (Defined internally).

const cmox_hmac_impl_t CMOX_HMAC_SHA512_256

Implementation of HMAC using SHA-512/256 (Defined internally).

const cmox_hmac_impl_t CMOX_HMAC_SM3

Implementation of HMAC using SM3 (Defined internally).

Variables

const cmox_mac_algo_t CMOX_HMAC_SHA1_ALGO

Identifier of the HMAC-SHA1 mac algorithm for single-call function (Defined internally).

const cmox_mac_algo_t CMOX_HMAC_SHA224_ALGO

Identifier of the HMAC-SHA224 mac algorithm for single-call function (Defined internally).

const cmox_mac_algo_t CMOX_HMAC_SHA256_ALGO

Identifier of the HMAC-SHA256 mac algorithm for single-call function (Defined internally).

const cmox_mac_algo_t CMOX_HMAC_SHA384_ALGO

Identifier of the HMAC-SHA384 mac algorithm for single-call function (Defined internally).

const cmox_mac_algo_t CMOX_HMAC_SHA512_ALGO

Identifier of the HMAC-SHA512 mac algorithm for single-call function (Defined internally).

const cmox_mac_algo_t CMOX_HMAC_SHA512_224_ALGO

Identifier of the HMAC-SHA512/224 mac algorithm for single-call function (Defined internally).

const cmox_mac_algo_t CMOX_HMAC_SHA512_256_ALGO

Identifier of the HMAC-SHA512/256 mac algorithm for single-call function (Defined internally).

const cmox_mac_algo_t CMOX_HMAC_SM3_ALGO

Identifier of the HMAC-SM3 mac algorithm for single-call function (Defined internally).

Functions

cmox_mac_handle_t * cmox_hmac_construct ( cmox_hmac_handle_t * P_pThis , cmox_hmac_impl_t P_impl )

HMAC constructor.

The function is used for specifying which hash function to use in order to implement the HMAC algorithm.

Parameters :

• P_pThis – Pointer to the HMAC handle to initialize

• P_impl – Constant that specifies the implementation to use. This parameter can be one of the following values:

  • CMOX_HMAC_SHA1

  • CMOX_HMAC_SHA224

  • CMOX_HMAC_SHA256

  • CMOX_HMAC_SHA384

  • CMOX_HMAC_SHA512

  • CMOX_HMAC_SHA512_224

  • CMOX_HMAC_SHA512_256

  • CMOX_HMAC_SM3

Returns :

cmox_mac_handle_t* Pointer to a general MAC handle. This will be used by the general purpose MAC functions in order to perform the algorithm

Typedefs

typedef const struct cmox_kmac_implStruct_st * cmox_kmac_impl_t

KMAC implementation.

This type specifies the implementation to use for the KMAC construct. This type is defined as a pointer to a structure, that contains the functions needed for the specific implementation, defined in the library internally

typedef uint32_t cmox_keccak_phase_t

Keccak-P phases.

struct cmox_cshake_handle_t

#include <cmox_kmac.h>

Structure defining the cSHAKE context.

Public Members

cmox_sponge_handle_t sponge

Sponge context

uint32_t fixedOutputLength

Fixed output length in bits

uint32_t lastByteBitLen

Last byte bit length

uint8_t lastByteValue

Last byte value

cmox_keccak_phase_t phase

Phase

struct cmox_kmac_inner_t

#include <cmox_kmac.h>

Structure defining the KMAC inner context.

Public Members

cmox_cshake_handle_t csi

cSHAKE context

size_t outputBitLen

Output length in bits

struct cmox_kmac_handle_t

#include <cmox_kmac.h>

KMAC handle structure definition.

Public Members

cmox_mac_handle_t super

General MAC handle

const uint8_t * custom_data

Pointer to buffer containing custom data

size_t customDataLen

Size in bytes of the custom data

cmox_kmac_inner_t internal_ctx

Internal handle for KMAC

cmox_kmac_impl_t impl

Implementation of KMAC

Variables

const cmox_kmac_impl_t CMOX_KMAC_128

Implementation of KMAC-128 algorithm (Defined internally).

const cmox_kmac_impl_t CMOX_KMAC_256

Implementation of KMAC-256 algorithm (Defined internally).

Variables

const cmox_mac_algo_t CMOX_KMAC_128_ALGO

Identifier of the KMAC-128 mac algorithm for single-call function (Defined internally).

const cmox_mac_algo_t CMOX_KMAC_256_ALGO

Identifier of the KMAC-256 mac algorithm for single-call function (Defined internally).

Functions

cmox_mac_handle_t * cmox_kmac_construct ( cmox_kmac_handle_t * P_pThis , cmox_kmac_impl_t P_impl )

KMAC constructor.

The function is used for specifying which KMAC implementation to use in order to implement the MAC algorithm.

Parameters :

• P_pThis – Pointer to the KMAC handle to initialize

• P_impl – Constant that specifies the implementation to use. This parameter can be one of the following values:

  • CMOX_KMAC_128

  • CMOX_KMAC_256

Returns :

cmox_mac_handle_t* Pointer to a general MAC handle. This will be used by the general purpose MAC functions in order to perform the algorithm

Typedefs

typedef const struct cmox_mac_vtableStruct_st * cmox_mac_vtable_t

MAC Virtual Table.

This type specifies a pointer to the virtual table containing the methods for a particular algorithm (e.g. HMAC-256 or CMAC)

typedef const struct cmox_mac_algoStruct_st * cmox_mac_algo_t

MAC algorithm type.

This type specifies the algorithm to use with the MAC module (e.g. HMAC-SHA256). The type is defined as a pointer to a structure, that contains the functions for the specific algorithm, defined in the library internally

struct cmox_mac_handle_t

#include <cmox_mac.h>

MAC handle structure definition.

Public Members

cmox_mac_vtable_t table

MAC virtual table

size_t tagLen

Size in bytes of the authenticated tag

uint32_t internalState

MAC internal state

Functions

cmox_mac_retval_t cmox_mac_cleanup ( cmox_mac_handle_t * P_pThis )

Cleanup the MAC handler.

Parameters :

P_pThis – MAC handler to cleanup

Returns :

cmox_mac_retval_t MAC return value

cmox_mac_retval_t cmox_mac_init ( cmox_mac_handle_t * P_pThis )

Initialize the MAC handle based on the selected algorithm.

Note

The MAC handle must be derived from an algorithm-specific handle using the correct construct

Parameters :

P_pThis – MAC handle to initialize

Returns :

cmox_mac_retval_t Hash return value

cmox_mac_retval_t cmox_mac_setTagLen ( cmox_mac_handle_t * P_pThis , size_t P_tagLen )

Set the size of the tag.

Note

This function is optional when used for HMAC or CMAC algorithms. If not called, the tag length will be set as the default specified by the algorithm (e.g. 16 bytes for CMAC) during the initialization phase.

Note

With KMAC algorithm, this function is mandatory and must be called before the cmox_mac_setKey function

Parameters :

• P_pThis – MAC handle to set

• P_tagLen – Size in bytes of the tag

Returns :

cmox_mac_retval_t MAC return value

cmox_mac_retval_t cmox_mac_setCustomData ( cmox_mac_handle_t * P_pThis , const uint8_t * P_pCustomData , size_t P_customDataLen )

Set the custom data to be combined with the plaintext for the MAC computation.

Note

This function is useful only for KMAC algorithm. It can be called for other algorithms but will not produce any results

Note

If the KMAC to compute doesn’t need any custom data, this function can be skipped.

Parameters :

• P_pThis – MAC handle to use for computing the authenticated tag

• P_pCustomData – Buffer of bytes containing the custom data

• P_customDataLen – Size in bytes of the custom data

Returns :

cmox_mac_retval_t MAC return value

cmox_mac_retval_t cmox_mac_setKey ( cmox_mac_handle_t * P_pThis , const uint8_t * P_pKey , size_t P_keyLen )

Set the key to be used for computing the authenticated tag.

Note

The KMAC algorithm is specified to be used even without key. However, this function is mandatory to be called with the parameter P_keyLen set to 0.

Parameters :

• P_pThis – MAC handle to use for computing the authenticated tag

• P_pKey – Buffer of bytes containing the key

• P_keyLen – Size in bytes of the key

Returns :

cmox_mac_retval_t MAC return value

cmox_mac_retval_t cmox_mac_append ( cmox_mac_handle_t * P_pThis , const uint8_t * P_pInput , size_t P_inputLen )

Append part or the totality of the plaintext to the MAC handle.

Parameters :

• P_pThis – MAC handle to use for computing the authenticated tag

• P_pInput – Buffer of bytes containing the data to append

• P_inputLen – Size in bytes of the data to append

Returns :

cmox_hash_retval_t MAC return value

cmox_mac_retval_t cmox_mac_generateTag ( cmox_mac_handle_t * P_pThis , uint8_t * P_pTag , size_t * P_pTagLen )

Compute the authenticated tag of the already appended data.

Parameters :

• P_pThis – MAC handle where the data has been appended

• P_pTag – Buffer of bytes where the authenticated tag will be stored

• P_pTagLen – Number of bytes generated by the function. It is an optional parameter and can be set to NULL if not needed.

Returns :

cmox_mac_retval_t MAC return value

cmox_mac_retval_t cmox_mac_verifyTag ( cmox_mac_handle_t * P_pThis , const uint8_t * P_pTag , uint32_t * P_pFaultCheck )

Verify the already appended data with the reference tag.

Note

P_pFaultCheck value, if the parameter is provided, MUST be checked to be equal to the retval, and both MUST be equal to the successful value. P_pFaultCheck MUST be checked only if the main result is successful, and has no relevance if the main result is not successful. Every comparison (both for the return value and for P_pFaultCheck) must be done against the success value, and not comparing the value with the failure value. Indeed, in presence of faults, especially P_pFaultCheck, could be a dirty value.

Parameters :

• P_pThis – MAC handle where the data has been appended

• P_pTag – Buffer of bytes containing the reference tag

• P_pFaultCheck – Optional value to check, together with the retval, to verify if some fault happened

Returns :

cmox_mac_retval_t

cmox_mac_retval_t cmox_mac_compute ( cmox_mac_algo_t P_algo , const uint8_t * P_pInput , size_t P_inputLen , const uint8_t * P_pKey , size_t P_keyLen , const uint8_t * P_pCustomData , size_t P_customDataLen , uint8_t * P_pTag , size_t P_expectedTagLen , size_t * P_pComputedTagLen )

Compute the authenticated tag of a message using a MAC algorithm.

Parameters :

• P_algo – Identifier of the hash algorithm to use for the computation. This parameter can be one of the following:

  • CMOX_CMAC_AES_ALGO

  • CMOX_HMAC_SHA1_ALGO

  • CMOX_HMAC_SHA224_ALGO

  • CMOX_HMAC_SHA256_ALGO

  • CMOX_HMAC_SHA384_ALGO

  • CMOX_HMAC_SHA512_ALGO

  • CMOX_HMAC_SHA512_224_ALGO

  • CMOX_HMAC_SHA512_256_ALGO

  • CMOX_HMAC_SM3_ALGO

  • CMOX_KMAC_128_ALGO

  • CMOX_KMAC_256_ALGO

• P_pInput – Buffer of bytes containing the message to process

• P_inputLen – Size in bytes of the message to process

• P_pKey – Buffer of bytes containing the key

• P_keyLen – Size in bytes of the key

• P_pCustomData – Buffer of bytes containing the custom data

• P_customDataLen – Size in bytes of the custom data

• P_pTag – Buffer of bytes where the authenticated tag will be stored

• P_expectedTagLen – Size in bytes of the tag to compute

• P_pComputedTagLen – Number of bytes generated by the function. It is an optional parameter and can be set to NULL if not needed.

Returns :

cmox_mac_retval_t

cmox_mac_retval_t cmox_mac_verify ( cmox_mac_algo_t P_algo , const uint8_t * P_pInput , size_t P_inputLen , const uint8_t * P_pKey , size_t P_keyLen , const uint8_t * P_pCustomData , size_t P_customDataLen , const uint8_t * P_pReceivedTag , size_t P_receivedTagLen )

Verify the authenticity of a message using a MAC algorithm.

Parameters :

• P_algo – Identifier of the hash algorithm to use for the computation. This parameter can be one of the following:

  • CMOX_CMAC_AES_ALGO

  • CMOX_HMAC_SHA1_ALGO

  • CMOX_HMAC_SHA224_ALGO

  • CMOX_HMAC_SHA256_ALGO

  • CMOX_HMAC_SHA384_ALGO

  • CMOX_HMAC_SHA512_ALGO

  • CMOX_HMAC_SHA512_224_ALGO

  • CMOX_HMAC_SHA512_256_ALGO

  • CMOX_HMAC_SM3_ALGO

  • CMOX_KMAC_128_ALGO

  • CMOX_KMAC_256_ALGO

• P_pInput – Buffer of bytes containing the message to process

• P_inputLen – Size in bytes of the message to process

• P_pKey – Buffer of bytes containing the key

• P_keyLen – Size in bytes of the key

• P_pCustomData – Buffer of bytes containing the custom data

• P_customDataLen – Size in bytes of the custom data

• P_pReceivedTag – Buffer of bytes containing the received tag

• P_receivedTagLen – Size in bytes of the received tag

Returns :

cmox_mac_retval_t

Defines

CMOX_MAC_SUCCESS

MAC operation successfully performed.

CMOX_MAC_ERR_INTERNAL

Some error happens internally in the MAC module.

CMOX_MAC_ERR_BAD_PARAMETER

One or more parameter has been wrongly passed to the function (e.g. pointer to NULL).

CMOX_MAC_ERR_BAD_OPERATION

Error on performing the operation (e.g. an operation has been called before initializing the handle).

CMOX_MAC_AUTH_SUCCESS

Authentication of the tag has been successful.

CMOX_MAC_AUTH_FAIL

Authentication of the tag failed.

Typedefs

typedef uint32_t cmox_mac_retval_t

MAC module return value type.

2.8. RSA module

group CMOX_RSA

Functions

void cmox_rsa_construct ( cmox_rsa_handle_t * P_pRsaCtx , const cmox_math_funcs_t P_Math , const cmox_modexp_func_t P_Modexp , uint8_t * P_pBuf , size_t P_BufLen )

Mandatory function to set Low Level Mathematical Functions, and working memory buffer, for RSA.

Parameters :

• P_pRsaCtx – [inout] Context for RSA operations

• P_Math – [in] Structure pointer with the Low-level Mathematical functions This parameter can be one of the following:

  • CMOX_MATH_FUNCS_SMALL

  • CMOX_MATH_FUNCS_FAST

• P_Modexp – [in] Structure pointer with the Modular Exponentiation function This parameter can be one of the following:

  • CMOX_MODEXP_PUBLIC

  • CMOX_MODEXP_PRIVATE_LOWMEM

  • CMOX_MODEXP_PRIVATE_MIDMEM

  • CMOX_MODEXP_PRIVATE_HIGHMEM

• P_pBuf – [in] The preallocated static buffer that will be used

• P_BufLen – [in] The size in bytes of the P_pBuf buffer

void cmox_rsa_cleanup ( cmox_rsa_handle_t * P_pRsaCtx )

Clean the RSA context and the internal temporary buffer.

Parameters :

P_pRsaCtx – [inout] Context for RSA operations

cmox_rsa_retval_t cmox_rsa_setKey ( cmox_rsa_key_t * P_pKey , const uint8_t * P_pModulus , size_t P_ModulusLen , const uint8_t * P_pExp , size_t P_ExpLen )

Set the key (public or private) in the key structure.

Parameters :

• P_pKey – [out] Key to set

• P_pModulus – [in] Modulus

• P_ModulusLen – [in] Modulus Length (in Bytes)

• P_pExp – [in] Exponent (private or public)

• P_ExpLen – [in] Exponent Length (in Bytes)

Return values :

• CMOX_RSA_SUCCESS –

• CMOX_RSA_ERR_BAD_PARAMETER –

cmox_rsa_retval_t cmox_rsa_setKeyCRT ( cmox_rsa_key_t * P_pPrivKey , size_t P_ModulusBitLen , const uint8_t * P_pExpP , size_t P_ExpPLen , const uint8_t * P_pExpQ , size_t P_ExpQLen , const uint8_t * P_pP , size_t P_PLen , const uint8_t * P_pQ , size_t P_QLen , const uint8_t * P_pIq , size_t P_IqLen )

Set the private CRT key in the key structure.

Parameters :

• P_pPrivKey – [out] Private Key to set

• P_ModulusBitLen – [in] Modulus Length (in bits)

• P_pExpP – [in] Secret exponent (mod P) dP

• P_ExpPLen – [in] dP Length (in Bytes)

• P_pExpQ – [in] Secret exponent (mod Q) dQ

• P_ExpQLen – [in] dQ Length (in Bytes)

• P_pP – [in] First secret prime P

• P_PLen – [in] P Length (in Bytes)

• P_pQ – [in] Second secret prime Q

• P_QLen – [in] Q Length (in Bytes)

• P_pIq – [in] Inverse of Q (mod P) invQ

• P_IqLen – [in] invQ Length (in Bytes)

Return values :

• CMOX_RSA_SUCCESS –

• CMOX_RSA_ERR_BAD_PARAMETER –

cmox_rsa_retval_t cmox_rsa_setKeyCRTwithFACM ( cmox_rsa_key_t * P_pPrivKey , size_t P_ModulusBitLen , const uint8_t * P_pExpP , size_t P_ExpPLen , const uint8_t * P_pExpQ , size_t P_ExpQLen , const uint8_t * P_pP , size_t P_PLen , const uint8_t * P_pQ , size_t P_QLen , const uint8_t * P_pIq , size_t P_IqLen , const uint8_t * P_pPubKey , size_t P_PubKeyLen )

Set the private CRT key in the key structure, enabling the Fault Attacks Countermeasure.

Note

This function enables the protection against the Bellcore attack for RSA-CRT computation. This countermeasure is useful to protect RSA-CRT using PKCS#1 v1.5 for Signature Creation. Indeed, PKCS#1 v2.2 Signature Creation is not vulnerable because of the presence of an input random, and Decryption processes (both for PKCS#1 v1.5 and v2.2) are not vulnerable because the plaintext is not returned if not correct (therefore not exploitable by an attacker).

Parameters :

• P_pPrivKey – [out] Private Key to set

• P_ModulusBitLen – [in] Modulus Length (in bits)

• P_pExpP – [in] Secret exponent (mod P) dP

• P_ExpPLen – [in] dP Length (in Bytes)

• P_pExpQ – [in] Secret exponent (mod Q) dQ

• P_ExpQLen – [in] dQ Length (in Bytes)

• P_pP – [in] First secret prime P

• P_PLen – [in] P Length (in Bytes)

• P_pQ – [in] Second secret prime Q

• P_QLen – [in] Q Length (in Bytes)

• P_pIq – [in] Inverse of Q (mod P) invQ

• P_IqLen – [in] invQ Length (in Bytes)

• P_pPubKey – [in] Public Key

• P_PubKeyLen – [in] Public Key Length (in Bytes)

Return values :

• CMOX_RSA_SUCCESS –

• CMOX_RSA_ERR_BAD_PARAMETER –

Hash algorithms to use with RSA PKCS#1 API.

Variables

const cmox_rsa_pkcs1v15_hash_t CMOX_RSA_PKCS1V15_HASH_SHA1

SHA1 Hash structure for the RSA PKCS#1 v1.5 functions.

const cmox_rsa_pkcs1v15_hash_t CMOX_RSA_PKCS1V15_HASH_SHA224

SHA224 Hash structure for the RSA PKCS#1 v1.5 functions.

const cmox_rsa_pkcs1v15_hash_t CMOX_RSA_PKCS1V15_HASH_SHA256

SHA256 Hash structure for the RSA PKCS#1 v1.5 functions.

const cmox_rsa_pkcs1v15_hash_t CMOX_RSA_PKCS1V15_HASH_SHA384

SHA384 Hash structure for the RSA PKCS#1 v1.5 functions.

const cmox_rsa_pkcs1v15_hash_t CMOX_RSA_PKCS1V15_HASH_SHA512

SHA512 Hash structure for the RSA PKCS#1 v1.5 functions.

const cmox_rsa_pkcs1v15_hash_t CMOX_RSA_PKCS1V15_HASH_SHA512_224

SHA512/224 Hash structure for the RSA PKCS#1 v1.5 functions.

const cmox_rsa_pkcs1v15_hash_t CMOX_RSA_PKCS1V15_HASH_SHA512_256

SHA512/256 Hash structure for the RSA PKCS#1 v1.5 functions.

Functions

cmox_rsa_retval_t cmox_rsa_pkcs1v15_sign ( cmox_rsa_handle_t * P_pRsaCtx , const cmox_rsa_key_t * P_pPrivKey , const uint8_t * P_pDigest , const cmox_rsa_pkcs1v15_hash_t P_HashId , uint8_t * P_pSignature , size_t * P_pSignatureLen )

Sign a message using PKCS#1 v1.5.

Parameters :

• P_pRsaCtx – [in] Context for RSA operations

• P_pPrivKey – [in] Private Key (standard or CRT)

• P_pDigest – [in] Message to sign

• P_HashId – [in] Hash to use

• P_pSignature – [out] Output signature

• P_pSignatureLen – [out] Output signature Length (in Bytes)

Return values :

• CMOX_RSA_SUCCESS – Everything OK

• CMOX_RSA_ERR_MATH_ALGO_MISMATCH – Mathematical function set is incompatible with current functionality

• CMOX_RSA_ERR_MEXP_ALGO_MISMATCH – Modexp function set is not compatible with current functionality

• CMOX_RSA_ERR_BAD_PARAMETER – Some NULL/wrong/empty parameter

• CMOX_RSA_ERR_MEMORY_FAIL – Not enough memory

• CMOX_RSA_ERR_MODULUS_TOO_SHORT – Modulus too short for the message to sign

cmox_rsa_retval_t cmox_rsa_pkcs1v15_verify ( cmox_rsa_handle_t * P_pRsaCtx , const cmox_rsa_key_t * P_pPubKey , const uint8_t * P_pDigest , const cmox_rsa_pkcs1v15_hash_t P_HashId , const uint8_t * P_pSignature , size_t P_SignatureLen , uint32_t * P_pFaultCheck )

Verify a message signed with PKCS#1 v1.5.

Note

P_pFaultCheck value, if the parameter is provided, MUST be checked to be equal to the retval, and both MUST be equal to the successful value. P_pFaultCheck MUST be checked only if the main result is successful, and has no relevance if the main result is not successful. Every comparison (both for the return value and for P_pFaultCheck) must be done against the success value, and not comparing the value with the failure value. Indeed, in presence of faults, especially P_pFaultCheck, could be a dirty value.

Parameters :

• P_pRsaCtx – [in] Context for RSA operations

• P_pPubKey – [in] Public Key

• P_pDigest – [in] Message to verify

• P_HashId – [in] Hash to use

• P_pSignature – [in] Signature

• P_SignatureLen – [in] Signature Length (in Bytes)

• P_pFaultCheck – [out] Optional value to check, together with the retval, to verify if some fault happened

Return values :

• CMOX_RSA_AUTH_SUCCESS – Signature verified

• CMOX_RSA_AUTH_FAIL – Signature NOT verified

• CMOX_RSA_ERR_MATH_ALGO_MISMATCH – Mathematical function set is incompatible with current functionality

• CMOX_RSA_ERR_MEXP_ALGO_MISMATCH – Modexp function set is not compatible with current functionality

• CMOX_RSA_ERR_BAD_PARAMETER – Some NULL/wrong/empty parameter

• CMOX_RSA_ERR_INVALID_SIGNATURE – Input signature corrupted or not in the expected format

• CMOX_RSA_ERR_MEMORY_FAIL – Not enough memory

• CMOX_RSA_ERR_MODULUS_TOO_SHORT – Modulus too short for the message to verify

cmox_rsa_retval_t cmox_rsa_pkcs1v15_encrypt ( cmox_rsa_handle_t * P_pRsaCtx , const cmox_rsa_key_t * P_pPubKey , const uint8_t * P_pInput , size_t P_InputLen , const uint8_t * P_pRandom , size_t P_RandomLen , uint8_t * P_pOutput , size_t * P_pOutputLen )

Encrypt a message using PKCS#1 v1.5.

Parameters :

• P_pRsaCtx – [in] Context for RSA operations

• P_pPubKey – [in] Public Key

• P_pInput – [in] Message to encrypt

• P_InputLen – [in] Message Length (in Bytes)

• P_pRandom – [in] Random buffer

• P_RandomLen – [in] Random Length (in Bytes)

• P_pOutput – [out] Output encrypted buffer

• P_pOutputLen – [out] Output Length (in Bytes)

Return values :

• CMOX_RSA_SUCCESS – Everything OK

• CMOX_RSA_ERR_MATH_ALGO_MISMATCH – Mathematical function set is incompatible with current functionality

• CMOX_RSA_ERR_MEXP_ALGO_MISMATCH – Modexp function set is not compatible with current functionality

• CMOX_RSA_ERR_BAD_PARAMETER – Some NULL/wrong/empty parameter

• CMOX_RSA_ERR_MODULUS_TOO_SHORT – Modulus too short for the message to encrypt

• CMOX_RSA_ERR_MEMORY_FAIL – Not enough memory

• CMOX_RSA_ERR_WRONG_RANDOM – Random material too short or not valid for the functionality

cmox_rsa_retval_t cmox_rsa_pkcs1v15_decrypt ( cmox_rsa_handle_t * P_pRsaCtx , const cmox_rsa_key_t * P_pPrivKey , const uint8_t * P_pInput , size_t P_InputLen , uint8_t * P_pOutput , size_t * P_pOutputLen )

Decrypt a message using PKCS#1 v1.5.

Parameters :

• P_pRsaCtx – [in] Context for RSA operations

• P_pPrivKey – [in] Private Key (standard or CRT)

• P_pInput – [in] Message to decrypt

• P_InputLen – [in] Message Length (in Bytes)

• P_pOutput – [out] Output decrypted buffer

• P_pOutputLen – [out] Output Length (in Bytes)

Return values :

• CMOX_RSA_SUCCESS – Everything OK

• CMOX_RSA_ERR_MATH_ALGO_MISMATCH – Mathematical function set is incompatible with current functionality

• CMOX_RSA_ERR_MEXP_ALGO_MISMATCH – Modexp function set is not compatible with current functionality

• CMOX_RSA_ERR_BAD_PARAMETER – Some NULL/wrong/empty parameter

• CMOX_RSA_ERR_MEMORY_FAIL – Not enough memory

• CMOX_RSA_ERR_WRONG_DECRYPTION – Decryption failed, probably due to a wrong private key

Hash algorithms to use with RSA PKCS#1 API.

Variables

const cmox_rsa_pkcs1v22_hash_t CMOX_RSA_PKCS1V22_HASH_SHA1

SHA1 Hash structure for the RSA PKCS#1 v2.2 functions.

const cmox_rsa_pkcs1v22_hash_t CMOX_RSA_PKCS1V22_HASH_SHA224

SHA224 Hash structure for the RSA PKCS#1 v2.2 functions.

const cmox_rsa_pkcs1v22_hash_t CMOX_RSA_PKCS1V22_HASH_SHA256

SHA256 Hash structure for the RSA PKCS#1 v2.2 functions.

const cmox_rsa_pkcs1v22_hash_t CMOX_RSA_PKCS1V22_HASH_SHA384

SHA384 Hash structure for the RSA PKCS#1 v2.2 functions.

const cmox_rsa_pkcs1v22_hash_t CMOX_RSA_PKCS1V22_HASH_SHA512

SHA512 Hash structure for the RSA PKCS#1 v2.2 functions.

const cmox_rsa_pkcs1v22_hash_t CMOX_RSA_PKCS1V22_HASH_SHA512_224

SHA512/224 Hash structure for the RSA PKCS#1 v2.2 functions.

const cmox_rsa_pkcs1v22_hash_t CMOX_RSA_PKCS1V22_HASH_SHA512_256

SHA512/256 Hash structure for the RSA PKCS#1 v2.2 functions.

Functions

cmox_rsa_retval_t cmox_rsa_pkcs1v22_sign ( cmox_rsa_handle_t * P_pRsaCtx , const cmox_rsa_key_t * P_pPrivKey , const uint8_t * P_pDigest , const cmox_rsa_pkcs1v22_hash_t P_HashId , const uint8_t * P_pRandom , size_t P_RandomLen , uint8_t * P_pSignature , size_t * P_pSignatureLen )

Sign a message using PKCS#1 v2.2.

Parameters :

• P_pRsaCtx – [in] Context for RSA operations

• P_pPrivKey – [in] Private Key (standard or CRT)

• P_pDigest – [in] Message to sign

• P_HashId – [in] Hash to use

• P_pRandom – [in] Random buffer

• P_RandomLen – [in] Random Length (in Bytes)

• P_pSignature – [out] Output signature

• P_pSignatureLen – [out] Output signature Length (in Bytes)

Return values :

• CMOX_RSA_SUCCESS – Everything OK

• CMOX_RSA_ERR_MATH_ALGO_MISMATCH – Mathematical function set is incompatible with current functionality

• CMOX_RSA_ERR_MEXP_ALGO_MISMATCH – Modexp function set is not compatible with current functionality

• CMOX_RSA_ERR_BAD_PARAMETER – Some NULL/wrong/empty parameter

• CMOX_RSA_ERR_MEMORY_FAIL – Not enough memory

• CMOX_RSA_ERR_MODULUS_TOO_SHORT – Modulus too short for the message to sign

cmox_rsa_retval_t cmox_rsa_pkcs1v22_verify ( cmox_rsa_handle_t * P_pRsaCtx , const cmox_rsa_key_t * P_pPubKey , const uint8_t * P_pDigest , const cmox_rsa_pkcs1v22_hash_t P_HashId , size_t P_RandomLen , const uint8_t * P_pSignature , size_t P_SignatureLen , uint32_t * P_pFaultCheck )

Verify a message signed with PKCS#1 v2.2.

Note

P_pFaultCheck value, if the parameter is provided, MUST be checked to be equal to the retval, and both MUST be equal to the successful value. P_pFaultCheck MUST be checked only if the main result is successful, and has no relevance if the main result is not successful. Every comparison (both for the return value and for P_pFaultCheck) must be done against the success value, and not comparing the value with the failure value. Indeed, in presence of faults, especially P_pFaultCheck, could be a dirty value.

Parameters :

• P_pRsaCtx – [in] Context for RSA operations

• P_pPubKey – [in] Public Key

• P_pDigest – [in] Message to verify

• P_HashId – [in] Hash to use

• P_RandomLen – [in] Random Length (in Bytes)

• P_pSignature – [in] Signature

• P_SignatureLen – [in] Signature Length (in Bytes)

• P_pFaultCheck – [out] Optional value to check, together with the retval, to verify if some fault happened

Return values :

• CMOX_RSA_AUTH_SUCCESS – Signature verified

• CMOX_RSA_AUTH_FAIL – Signature NOT verified

• CMOX_RSA_ERR_MATH_ALGO_MISMATCH – Mathematical function set is incompatible with current functionality

• CMOX_RSA_ERR_MEXP_ALGO_MISMATCH – Modexp function set is not compatible with current functionality

• CMOX_RSA_ERR_BAD_PARAMETER – Some NULL/wrong/empty parameter

• CMOX_RSA_ERR_INVALID_SIGNATURE – Input signature corrupted or not in the expected format

• CMOX_RSA_ERR_MEMORY_FAIL – Not enough memory

• CMOX_RSA_ERR_INTERNAL – Something went wrong during internal computations (e.g. hash)

cmox_rsa_retval_t cmox_rsa_pkcs1v22_encrypt ( cmox_rsa_handle_t * P_pRsaCtx , const cmox_rsa_key_t * P_pPubKey , const uint8_t * P_pInput , size_t P_InputLen , const cmox_rsa_pkcs1v22_hash_t P_HashId , const uint8_t * P_pRandom , size_t P_RandomLen , const uint8_t * P_pLabel , size_t P_LabelLen , uint8_t * P_pOutput , size_t * P_pOutputLen )

Encrypt a message using PKCS#1 v2.2.

Parameters :

• P_pRsaCtx – [in] Context for RSA operations

• P_pPubKey – [in] Public Key

• P_pInput – [in] Message to encrypt

• P_InputLen – [in] Message Length (in Bytes)

• P_HashId – [in] Hash to use

• P_pRandom – [in] Random buffer

• P_RandomLen – [in] Random Length (in Bytes)

• P_pLabel – [in] Label (Optional)

• P_LabelLen – [in] Label Length (in Bytes)

• P_pOutput – [out] Output encrypted buffer

• P_pOutputLen – [out] Output Length (in Bytes)

Return values :

• CMOX_RSA_SUCCESS – Everything OK

• CMOX_RSA_ERR_MATH_ALGO_MISMATCH – Mathematical function set is incompatible with current functionality

• CMOX_RSA_ERR_MEXP_ALGO_MISMATCH – Modexp function set is not compatible with current functionality

• CMOX_RSA_ERR_BAD_PARAMETER – Some NULL/wrong/empty parameter

• CMOX_RSA_ERR_MODULUS_TOO_SHORT – Modulus too short for the message to encrypt

• CMOX_RSA_ERR_MEMORY_FAIL – Not enough memory

• CMOX_RSA_ERR_INTERNAL – Something went wrong during internal computations (e.g. hash)

cmox_rsa_retval_t cmox_rsa_pkcs1v22_decrypt ( cmox_rsa_handle_t * P_pRsaCtx , const cmox_rsa_key_t * P_pPrivKey , const uint8_t * P_pInput , size_t P_InputLen , const cmox_rsa_pkcs1v22_hash_t P_HashId , const uint8_t * P_pLabel , size_t P_LabelLen , uint8_t * P_pOutput , size_t * P_pOutputLen )

Decrypt a message using PKCS#1 v2.2.

Parameters :

• P_pRsaCtx – [in] Context for RSA operations

• P_pPrivKey – [in] Private Key (standard or CRT)

• P_pInput – [in] Message to decrypt

• P_InputLen – [in] Message Length (in Bytes)

• P_HashId – [in] Hash to use

• P_pLabel – [in] Label (Optional)

• P_LabelLen – [in] Label Length (in Bytes)

• P_pOutput – [out] Output decrypted buffer

• P_pOutputLen – [out] Output Length (in Bytes)

Return values :

• CMOX_RSA_SUCCESS – Everything OK

• CMOX_RSA_ERR_MATH_ALGO_MISMATCH – Mathematical function set is incompatible with current functionality

• CMOX_RSA_ERR_MEXP_ALGO_MISMATCH – Modexp function set is not compatible with current functionality

• CMOX_RSA_ERR_BAD_PARAMETER – Some NULL/wrong/empty parameter

• CMOX_RSA_ERR_MEMORY_FAIL – Not enough memory

• CMOX_RSA_ERR_INTERNAL – Something went wrong during internal computations (e.g. hash)

• CMOX_RSA_ERR_WRONG_DECRYPTION – Decryption failed, probably due to a wrong private key

• CMOX_RSA_ERR_MODULUS_TOO_SHORT – Modulus too short for the message to decrypt

Defines

CMOX_RSA_SUCCESS

RSA operation successfully performed

CMOX_RSA_ERR_INTERNAL

Internal computat. error (e.g. hash)

CMOX_RSA_ERR_BAD_PARAMETER

One of the expected parameter is invalid

CMOX_RSA_ERR_MODULUS_TOO_SHORT

Input too long for the current modulus

CMOX_RSA_ERR_INVALID_SIGNATURE

RSA invalid signature value

CMOX_RSA_ERR_WRONG_DECRYPTION

RSA invalid decryption, due to mismatch between private key and input

CMOX_RSA_ERR_WRONG_RANDOM

Random not compliant with the API (Recall with other random material)

CMOX_RSA_ERR_MEMORY_FAIL

Not enough memory

CMOX_RSA_ERR_MATH_ALGO_MISMATCH

Math customization not supported by current functionality

CMOX_RSA_ERR_MEXP_ALGO_MISMATCH

Modexp function not supported by current functionality

CMOX_RSA_AUTH_SUCCESS

RSA signature successful verification

CMOX_RSA_AUTH_FAIL

RSA signature not verified

Typedefs

typedef uint32_t cmox_rsa_retval_t

Return value type for RSA module.

Types used within the RSA module.

Typedefs

typedef struct cmox_rsa_intfuncStruct_t * cmox_rsa_intfunc_t

Public pointer type for the RSA modular exponentiation function.

typedef const struct cmox_rsa_facmStruct_t * cmox_rsa_facm_t

Public pointer type for the Fault Attacks countermeasure.

typedef const struct cmox_rsa_pkcs1v15_hash_st * cmox_rsa_pkcs1v15_hash_t

Pointer type linked to the structure to hold Hash information for PKCS#1 v1.5.

typedef const struct cmox_rsa_pkcs1v22_hash_st * cmox_rsa_pkcs1v22_hash_t

Pointer type linked to the structure to hold Hash information for PKCS#1 v2.2.

struct cmox_rsa_handle_t

#include <cmox_rsa_types.h>

Structure for the RSA context.

Public Members

cmox_membuf_handle_st membuf_str

Memory buffer structure

cmox_modexp_func_t modexp_ptr

Modexp customization structure

cmox_math_funcs_t math_ptr

Math customization structure

uint32_t magic_num_check

Magic number for diagnostic checks

struct cmox_rsa_key_t

#include <cmox_rsa_types.h>

Structure to hold public or private key parameters.

Public Members

cmox_rsa_intfunc_t f

Function executing CRT/standard modexp

size_t mod_bitlen

Length (in bytes) of Modulus

const uint8_t * mod

Modulus

const uint8_t * exp

Public/secret Exponent

size_t exp_len

Length (in bytes) of Exponent

const uint8_t * p

Parameter P (in case of CRT) or normal modulus

size_t p_len

Length (in bytes) of P/Modulus

const uint8_t * q

Parameter Q

size_t q_len

Length (in bytes) of Q

const uint8_t * dp

Secret exponent (mod P) (in case of CRT), or normal secret exponent

size_t dp_len

Length (in bytes) of dP/Exponent

const uint8_t * dq

Secret exponent (mod Q)

size_t dq_len

Length (in bytes) of dQ

const uint8_t * iq

Q^(-1) (mod P)

size_t iq_len

Length (in bytes) of iQ

const uint8_t * pub_exp

public exponent

size_t pub_exp_len

Length (in bytes) of the public exponent

cmox_rsa_facm_t facm_flag

Parameter to enable/disable the countermeasure to the Fault Attacks

union cmox_rsa_key_t fields

Union for STD or CRT key structure

2.9. Utils module

group CMOX_UTILS

Public comparison function and related utilities.

Functions

cmox_utils_retval_t cmox_utils_compare ( const uint8_t * P_pBuf1 , uint32_t P_Len1 , const uint8_t * P_pBuf2 , uint32_t P_Len2 , uint32_t * P_pFaultCheck )

Compares two buffers in a fault-secure way.

Note

P_pFaultCheck value, if the parameter is provided, MUST be checked to be equal to the retval, and both MUST be equal to the successful value. P_pFaultCheck MUST be checked only if the main result is successful, and has no relevance if the main result is not successful. Every comparison (both for the return value and for P_pFaultCheck) must be done against the success value, and not comparing the value with the failure value. Indeed, in presence of faults, especially P_pFaultCheck, could be a dirty value.

Warning

If it’s necessary to be protected against fault attacks, it’s very important that P_Len1 and P_Len2 are different memory locations (or registers), otherwise a single fault could be fatal.

Parameters :

• P_pBuf1 – [in] First buffer

• P_Len1 – [in] Length of the first input buffer

• P_pBuf2 – [in] Second buffer

• P_Len2 – [in] Length of the second input buffer

• P_pFaultCheck – [out] Optional value to check, together with the retval, to verify if some fault happened

Return values :

• CMOX_UTILS_AUTH_SUCCESS – The two buffers are equal

• CMOX_UTILS_AUTH_FAIL – The two buffers are different

Defines

CMOX_UTILS_AUTH_SUCCESS

UTILS operation successfully performed

CMOX_UTILS_AUTH_FAIL

Input buffers are different

Typedefs

typedef uint32_t cmox_utils_retval_t

Return value type for the UTILS module