1 /*--------------------------------------------------------------------------*/ 2 /* Copyright 2020-2021 NXP */ 3 /* */ 4 /* NXP Confidential. This software is owned or controlled by NXP and may */ 5 /* only be used strictly in accordance with the applicable license terms. */ 6 /* By expressly accepting such terms or by downloading, installing, */ 7 /* activating and/or otherwise using the software, you are agreeing that */ 8 /* you have read, and that you agree to comply with and are bound by, such */ 9 /* license terms. If you do not agree to be bound by the applicable license */ 10 /* terms, then you may not retain, install, activate or otherwise use the */ 11 /* software. */ 12 /*--------------------------------------------------------------------------*/ 13 14 /** 15 * @file mcuxClCss_Cipher.h 16 * @brief CSSv2 header for symmetric ciphers. 17 * 18 * This header exposes functions that enable using the CSSv2 for symmetric encryption/decryption. 19 * The cipher algorithm supported by CSSv2 is AES in the following modes: 20 * - Electronic Code Book (ECB) mode, 21 * - Cipher Block Chaining (CBC) mode, and 22 * - Counter (CTR) mode. 23 * Supported key sizes are 128, 192, and 256 bits. 24 */ 25 26 /** 27 * @defgroup mcuxClCss_Cipher mcuxClCss_Cipher 28 * @brief This part of the @ref mcuxClCss driver supports functionality for symmetric ciphers 29 * @ingroup mcuxClCss 30 * @{ 31 */ 32 33 #ifndef MCUXCLCSS_CIPHER_H_ 34 #define MCUXCLCSS_CIPHER_H_ 35 36 #include <mcuxClCss_Common.h> // Common functionality 37 38 /********************************************** 39 * CONSTANTS 40 **********************************************/ 41 /** 42 * @defgroup mcuxClCss_Cipher_Macros mcuxClCss_Cipher_Macros 43 * @brief Defines all macros of @ref mcuxClCss_Cipher 44 * @ingroup mcuxClCss_Cipher 45 * @{ 46 */ 47 48 /** 49 * @defgroup MCUXCLCSS_CIPHER_ MCUXCLCSS_CIPHER_ 50 * @brief Defines valid options to be used by #mcuxClCss_CipherOption_t 51 * @ingroup mcuxClCss_Cipher_Macros 52 * 53 * Valid AES key sizes in bytes 54 * @{ 55 */ 56 57 #define MCUXCLCSS_CIPHER_ENCRYPT 0U ///< Set this option at #mcuxClCss_CipherOption_t.dcrpt to perform an encryption 58 #define MCUXCLCSS_CIPHER_DECRYPT 1U ///< Set this option at #mcuxClCss_CipherOption_t.dcrpt to perform a decryption 59 60 #define MCUXCLCSS_CIPHER_STATE_OUT_ENABLE 1U ///< Set this option at #mcuxClCss_CipherOption_t.cphsoe to export the internal CSS state to @p pIV 61 #define MCUXCLCSS_CIPHER_STATE_OUT_DISABLE 0U ///< Set this option at #mcuxClCss_CipherOption_t.cphsoe to not export the internal CSS state 62 63 #define MCUXCLCSS_CIPHER_STATE_IN_ENABLE 1U ///< Set this option at #mcuxClCss_CipherOption_t.cphsie to import an external CSS state from @p pIV 64 #define MCUXCLCSS_CIPHER_STATE_IN_DISABLE 0U ///< Set this option at #mcuxClCss_CipherOption_t.cphsie to not import an external CSS state 65 66 #define MCUXCLCSS_CIPHER_EXTERNAL_KEY 1U ///< Set this option at #mcuxClCss_CipherOption_t.extkey to use a key located in CPU memory provided by @p pKey 67 #define MCUXCLCSS_CIPHER_INTERNAL_KEY 0U ///< Set this option at #mcuxClCss_CipherOption_t.extkey to use a key located in CSS keystore privded by @p keyIdx 68 69 #define MCUXCLCSS_CIPHERPARAM_ALGORITHM_AES_ECB 0x00U ///< Set this option at #mcuxClCss_CipherOption_t.cphmde to use AES engine in Electornic Code Book (ECB) mode 70 #define MCUXCLCSS_CIPHERPARAM_ALGORITHM_AES_CBC 0x01U ///< Set this option at #mcuxClCss_CipherOption_t.cphmde to use AES engine in Cipher Block Chaining (CBC) mode 71 #define MCUXCLCSS_CIPHERPARAM_ALGORITHM_AES_CTR 0x02U ///< Set this option at #mcuxClCss_CipherOption_t.cphmde to use AES engine in Counter (CTR) mode 72 /** 73 * @} 74 */ 75 76 77 /** 78 * @ingroup mcuxClCss_Cipher_Macros 79 */ 80 #define MCUXCLCSS_CIPHER_BLOCK_SIZE_AES ((size_t) 16U) ///< Size of an AES input block: 128 bit (16 bytes) 81 82 /** 83 * @defgroup MCUXCLCSS_CIPHER_KEY_SIZE_AES_ MCUXCLCSS_CIPHER_KEY_SIZE_AES_ 84 * @brief Defines valid AES key sizes in bytes 85 * @ingroup mcuxClCss_Cipher_Macros 86 * @{ 87 */ 88 89 #define MCUXCLCSS_CIPHER_KEY_SIZE_AES_128 ((size_t) 16U) ///< Size of an AES128 key: 128 bit (16 bytes) 90 #define MCUXCLCSS_CIPHER_KEY_SIZE_AES_192 ((size_t) 24U) ///< Size of an AES192 key: 192 bit (24 bytes) 91 #define MCUXCLCSS_CIPHER_KEY_SIZE_AES_256 ((size_t) 32U) ///< Size of an AES192 key: 256 bit (32 bytes) 92 /** 93 * @} 94 * 95 * @} 96 */ 97 98 /********************************************** 99 * TYPEDEFS 100 **********************************************/ 101 /** 102 * @defgroup mcuxClCss_Cipher_Types mcuxClCss_Cipher_Types 103 * @brief Defines all types of @ref mcuxClCss_Cipher 104 * @ingroup mcuxClCss_Cipher 105 * @{ 106 */ 107 108 /** 109 * @brief Command option bit field for #mcuxClCss_Cipher_Async 110 * 111 * Bit field to configure #mcuxClCss_Cipher_Async. See @ref MCUXCLCSS_CIPHER_ for possible options. 112 */ 113 typedef union 114 { 115 struct 116 { 117 uint32_t value; ///< Accesses the bit field as a full word 118 } word; ///< Access #mcuxClCss_CipherOption_t word-wise 119 struct 120 { 121 uint32_t :1; ///< RFU 122 uint32_t dcrpt :1; ///< Define operation mode 123 uint32_t cphmde :2; ///< Define cipher mode 124 uint32_t cphsoe :1; ///< Define whether the CSSv2 internal cipher state should be extracted to external memory or kept internally 125 uint32_t cphsie :1; ///< Define whether an external provided cipher state should be imported from external memory 126 uint32_t :7; ///< RFU 127 uint32_t extkey :1; ///< Define whether an external key from memory or CSSv2 internal key should be used 128 uint32_t :18; ///< RFU 129 } bits; ///< Access #mcuxClCss_CipherOption_t bit-wise 130 } mcuxClCss_CipherOption_t; 131 /** 132 * @} 133 */ 134 135 /********************************************** 136 * FUNCTIONS 137 **********************************************/ 138 /** 139 * @defgroup mcuxClCss_Cipher_Functions mcuxClCss_Cipher_Functions 140 * @brief Defines all functions of @ref mcuxClCss_Cipher 141 * @ingroup mcuxClCss_Cipher 142 * @{ 143 */ 144 145 /** 146 * @brief Performs AES encryption/decryption. 147 * 148 * 149 * Performs an AES encryption/decryption. Call #mcuxClCss_WaitForOperation to complete the operation. 150 * @param[in] options Encryption/decryption command options. For detailed information, see #mcuxClCss_CipherOption_t. 151 * @param[in] keyIdx Index of the key inside the CSSv2 keystore. See parameter properties section in function description. 152 * @param[in] pKey Memory area that contains the key. See parameter properties section in function description. 153 * @param[in] keyLength Size of @p pKey in bytes. Must be a valid key size of @ref MCUXCLCSS_CIPHER_KEY_SIZE_AES_. See parameter properties section in function description. 154 * @param[in] pInput Pointer to the input data to be encrypted/decrypted. Padding must be already applied. 155 * @param[in] inputLength Size of @p pInput in bytes, must be a multiple of the block size. 156 * @param[in, out] pIV A pointer to the memory location which contains/receives the IV/state of cipher. See parameter properties section in function description. 157 * @param[out] pOutput Pointer to the output buffer to store encrypted/decrypted data. 158 * 159 * The properties of some parameters change with respect to selected options. 160 * 161 * <dl> 162 * <dt>Parameter properties</dt> 163 * 164 * <dd><dl> 165 * <dt>@p options.cphmde == #MCUXCLCSS_CIPHERPARAM_ALGORITHM_AES_ECB</dt> 166 * <dd>@p pIV is ignored. 167 * 168 * <dt>@p options.cphmde == #MCUXCLCSS_CIPHERPARAM_ALGORITHM_AES_CBC</dt> 169 * <dd>@p pIV must be set to the IV (when encrypting the first block) or to the last block of the ciphertext of the previous operation. 170 * CSSv2 will always read and write to this location. 171 * 172 * 173 * @p options.cphsoe is ignored.</dd> 174 * 175 * <dt>@p options.cphmde == #MCUXCLCSS_CIPHERPARAM_ALGORITHM_AES_CTR</dt> 176 * <dd>@p pIV must be set to the IV (when encrypting the first block) or to the state output of the previous 177 * encryption/decryption operation. CSSv2 will write to this location if @p options.cphsoe == #MCUXCLCSS_CIPHER_STATE_OUT_ENABLE.</dd> 178 * 179 * <dt>@p options.extkey == #MCUXCLCSS_CIPHER_EXTERNAL_KEY</dt> 180 * <dd>@p keyIdx is ignored.</dd> 181 * 182 * <dt>@p options.extkey == #MCUXCLCSS_CIPHER_INTERNAL_KEY</dt> 183 * <dd>@p pKey is ignored. 184 * 185 * @p keyLength is ignored.</dd> 186 * 187 * </dl></dd> 188 * </dl> 189 * 190 * @return A code-flow protected error code (see @ref mcuxCsslFlowProtection). The error code can be any error code in @ref MCUXCLCSS_STATUS_, see individual documentation for more information 191 * @retval #MCUXCLCSS_STATUS_SW_INVALID_PARAM if invalid parameters were specified 192 * @retval #MCUXCLCSS_STATUS_SW_CANNOT_INTERRUPT if a running operation prevented the request 193 * @retval #MCUXCLCSS_STATUS_OK_WAIT on successful request 194 */ 195 MCUX_CSSL_FP_FUNCTION_DECL(mcuxClCss_Cipher_Async) 196 MCUXCLCSS_API mcuxClCss_Status_Protected_t mcuxClCss_Cipher_Async( 197 mcuxClCss_CipherOption_t options, 198 mcuxClCss_KeyIndex_t keyIdx, 199 uint8_t const * pKey, 200 size_t keyLength, 201 uint8_t const * pInput, 202 size_t inputLength, 203 uint8_t * pIV, 204 uint8_t * pOutput 205 ); 206 207 /** 208 * @} 209 */ 210 #endif /* MCUXCLCSS_CIPHER_H_ */ 211 212 /** 213 * @} 214 */ 215
