1. CMOX_CIPHER

1.1. CMOX CIPHER KEYSIZE

group CMOX_CIPHER_KEYSIZE

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.

1.2. CMOX CIPHER PUBLIC METHODS

group CMOX_CIPHER_PUBLIC_METHODS

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

1.3. CMOX CIPHER PUBLIC TYPES

group CMOX_CIPHER_PUBLIC_TYPES

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.