1 /* 2 * This file is part of the openHiTLS project. 3 * 4 * openHiTLS is licensed under the Mulan PSL v2. 5 * You can use this software according to the terms and conditions of the Mulan PSL v2. 6 * You may obtain a copy of Mulan PSL v2 at: 7 * 8 * http://license.coscl.org.cn/MulanPSL2 9 * 10 * THIS SOFTWARE IS PROVIDED ON AN "AS IS" BASIS, WITHOUT WARRANTIES OF ANY KIND, 11 * EITHER EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO NON-INFRINGEMENT, 12 * MERCHANTABILITY OR FIT FOR A PARTICULAR PURPOSE. 13 * See the Mulan PSL v2 for more details. 14 */ 15 16 /** 17 * @defgroup crypt_eal_cipher 18 * @ingroup crypt 19 * @brief cipher suites 20 */ 21 22 #ifndef CRYPT_EAL_CIPHER_H 23 #define CRYPT_EAL_CIPHER_H 24 25 #include <stdint.h> 26 #include <stdbool.h> 27 #include "crypt_algid.h" 28 #include "crypt_types.h" 29 30 #ifdef __cplusplus 31 extern "C" { 32 #endif // __cplusplus 33 34 typedef struct CryptEalCipherCtx CRYPT_EAL_CipherCtx; 35 36 /** 37 * @ingroup crypt_eal_cipher, Not supported in provider 38 * @brief Check whether the given symmetric algorithm ID is valid. 39 * 40 * @param id [IN] Symmetric algorithm ID. 41 * @retval Valid, true is returned. 42 * Invalid, false is returned. 43 */ 44 bool CRYPT_EAL_CipherIsValidAlgId(CRYPT_CIPHER_AlgId id); 45 46 /** 47 * @ingroup crypt_eal_cipher 48 * @brief Generate symmetric encryption and decryption handles. 49 * 50 * @attention If the function is called by an external user and the error stack is concerned, 51 * it is recommended that BSL_ERR_ClearError() be called before this function is called. 52 * @param id [IN] Symmetric encryption/decryption algorithm ID. 53 * @retval Success: cipher ctx. 54 * Fails: NULL. 55 */ 56 CRYPT_EAL_CipherCtx *CRYPT_EAL_CipherNewCtx(CRYPT_CIPHER_AlgId id); 57 58 /** 59 * @ingroup crypt_eal_cipher 60 * @brief Generate symmetric encryption and decryption handles in the providers 61 * 62 * @param libCtx [IN] Library context 63 * @param algId [IN] Symmetric encryption/decryption algorithm ID. 64 * @param attrName [IN] Specify expected attribute values 65 * @retval Success: cipher ctx. 66 * Fails: NULL. 67 */ 68 CRYPT_EAL_CipherCtx *CRYPT_EAL_ProviderCipherNewCtx(CRYPT_EAL_LibCtx *libCtx, int32_t algId, const char *attrName); 69 70 /** 71 * @ingroup crypt_eal_cipher 72 * @brief Release the symmetric encryption/decryption handle. Clear sensitive information before releasing the handle. 73 * 74 * @attention If the function is called by an external user and the error stack is concerned, it is recommended 75 * that BSL_ERR_ClearError() be called before this function is called. 76 * @param ctx [IN] Symmetric encryption/decryption handle. The CTX is set null by the caller. 77 */ 78 void CRYPT_EAL_CipherFreeCtx(CRYPT_EAL_CipherCtx *ctx); 79 80 /** 81 * @ingroup crypt_eal_cipher 82 * @brief Initialize the symmetric encryption/decryption handle. The key cannot be null. Except the ECB mode, 83 * other modes iv cannot be null. 84 * 85 * The length of iv must be the same as the block length (this requirement is not required in ECB mode). 86 * The block length can be obtained through CRYPT_CTRL_GET_BLOCKSIZE of CRYPT_EAL_CipherCtrl. 87 * CRYPT_EAL_CipherInit can be called repeatedly at any stage, resets the key and iv, and clears the cached data. 88 * 89 * @attention If the function is called by an external user and the error stack is concerned, 90 * you are advised to call BSL_ERR_ClearError() before calling this function. 91 * 92 * @param ctx [IN] Symmetric encryption/decryption handle 93 * @param key [IN] Key 94 * @param keyLen [IN] Key length 95 * @param iv [IN] Initialization vector 96 * @param ivLen [IN] Initialize the vector length. 97 * @param enc [IN] True: encryption; False: decryption 98 * @retval #CRYPT_SUCCESS, success. 99 * For other error codes, see crypt_errno.h. 100 */ 101 int32_t CRYPT_EAL_CipherInit(CRYPT_EAL_CipherCtx *ctx, const uint8_t *key, uint32_t keyLen, const uint8_t *iv, 102 uint32_t ivLen, bool enc); 103 104 /** 105 * @ingroup crypt_eal_cipher 106 * @brief Deinitialize the handle and restore the handle to the state, 107 * when the CRYPT_EAL_CipherNewCtx function is called. 108 * 109 * @attention If the function is called by an external user and the error stack is concerned, 110 * you are advised to call BSL_ERR_ClearError() before calling this function. 111 * @param ctx [IN] Symmetric encryption/decryption handle 112 */ 113 void CRYPT_EAL_CipherDeinit(CRYPT_EAL_CipherCtx *ctx); 114 115 /** 116 * @ingroup crypt_eal_cipher 117 * 118 * Re-initialize the handle, retain the key, reset the IV, and clear the cache and sensitive data. 119 * Except the ECB mode, other modes iv cannot be null. The setting of iv must be based on the corresponding 120 * algorithm ID. For details, see the mapping in CRYPT_EAL_CipherInit. 121 * 122 * @param ctx [IN] Symmetric encryption/decryption handle 123 * @param iv [IN] Vector 124 * @param ivlen [IN] Vector length 125 */ 126 int32_t CRYPT_EAL_CipherReinit(CRYPT_EAL_CipherCtx *ctx, uint8_t *iv, uint32_t ivLen); 127 128 /** 129 * @ingroup crypt_eal_cipher 130 * 131 * Continuously enter encrypted and decrypted data. 132 * CRYPT_EAL_CipherUpdate should be used in conjunction with CRYPT_EAL_CipherFinal, after one or more calls to 133 * CRYPT_EAL_CipherUpdate, Call CRYPT_EAL_CipherFinal. With the exception of SM4_XTS mode, multiple calls to 134 * CRYPT_EAL_CipherUpdate and CRYPT_EAL_CipherFinal are not supported. 135 * 136 * @attention If the function is called by an external user and the error stack is concerned, it is recommended 137 * that BSL_ERR_ClearError() be called before this function is called. 138 * 139 * @param ctx [IN] Symmetric encryption and decryption handle 140 * @param in [IN] Continuously input data 141 * @param inLen [IN] Length of continuously input data 142 * @param out [OUT] Output data 143 * @param outLen [IN/OUT] Input: For CBC and ECB block encryption, you are advised to set outLen > inLen + blockSize. 144 * For CTR and XTS stream encryption, you are advised to set outLen >= inLen. blockSize can be obtained by using 145 * CRYPT_CTRL_GET_BLOCKSIZE of CRYPT_EAL_CipherCtrl. 146 * Output: Length of the encrypted data. If the block encryption algorithm is used and the length of the last data 147 * to be processed is insufficient, the output value of outLen is 0. 148 * eg: CBC and ECB block encryption 149 * 1. Encrypted data is input for the first time, and inLen is less than blockSize. 150 * In this case, the output value of outLen is 0. 151 * 2. In the first input encrypted data length, inLen is an integer multiple of blockSize. 152 * In this case, outLen is equal to inLen. 153 * 3. In the first input encrypted data length, inLen > blockSize and not an integer multiple of blockSize. 154 * In this case, outLen < inLen. 155 * 4. Enter the encrypted data for multiple times. (inLen% blockSize) + cache (CTX cache data) >= blockSize. 156 * At this point outLen = (inlen / blockSize) * blockSize + blockSize 157 * CTR outLen equals inLen. 158 * In XTS mode, update reserves the last two blocks for final processing, If the total length of the input data 159 * plus the buffer is less than 32 blocks, the output is 0. 160 * 1. When data is input for the first time, outLen = (inLen / 16 - 2) * 16. 161 * 2. Enter the encrypted data for multiple times. At this time, outLen = ((inLen + cache) / 16 - 2) * 16. 162 * In SM4_XTS mode, after calling CRYPT_EAL_CipherUpdate, you need to use CRYPT_EAL_CipherInit or 163 * CRYPT_EAL_CipherReinit to reset the key or iv. 164 * @retval #CRYPT_SUCCESS, success. 165 * Other error codes see the crypt_errno.h. 166 */ 167 int32_t CRYPT_EAL_CipherUpdate(CRYPT_EAL_CipherCtx *ctx, const uint8_t *in, uint32_t inLen, uint8_t *out, 168 uint32_t *outLen); 169 170 /** 171 * @ingroup crypt_eal_cipher 172 * @brief Fill the data with the size of the block and output the encrypted data; the AEAD tag is obtained 173 * through CRYPT_EAL_CipherCtrl. 174 * For block encryption algorithms such as CBC and ECB, padding must be set, In XTS mode, final needs 175 * to be called to obtain the last two blocks. 176 * @attention If the function is called by an external user and the error stack is concerned, 177 * you are advised to call BSL_ERR_ClearError() before calling this function. 178 * 179 * @param ctx [IN] Symmetric encryption/decryption handle 180 * @param out [OUT] Output the encrypted data 181 * @param outLen [IN/OUT] Input: outLen >= blockSize 182 * Output: The output value for stream encryption is 0. 183 * If padding is set for CBC and ECB block encryption, the output value of outLen is blockSize. 184 * If the padding is not set for CBC and ECB block encryption and CTX contains cached data, an error is reported. 185 * If padding is not set for CBC and ECB block encryption, and no data is cached in the CTX, the output value of 186 * outLen is 0. 187 * @retval #CRYPT_SUCCESS, success. 188 * Other error codes see the crypt_errno.h. 189 */ 190 int32_t CRYPT_EAL_CipherFinal(CRYPT_EAL_CipherCtx *ctx, uint8_t *out, uint32_t *outLen); 191 192 /** 193 * @ingroup crypt_eal_cipher 194 * 195 * Set the mode ctx parameters in the CTX. 196 * parameter data type Length(len):number of data bytes 197 * CRYPT_CTRL_GET_IV uint8_t array The length of the IV depends on the corresponding algorithm, 198 see the mapping in CRYPT_EAL_CipherInit 199 * CRYPT_CTRL_SET_AAD uint8_t array It is used only for AEAD calculation. 200 The length is related to the corresponding AEAD algorithm. 201 * CRYPT_CTRL_GET_TAG uint8_t array It is used only for AEAD calculation. 202 The length is the tagLen value set by the user. 203 * CRYPT_CTRL_SET_TAGLEN uint32_t length(len) 4 204 * CRYPT_CTRL_SET_MSGLEN uint64_t length(len) 8 205 * CRYPT_CTRL_SET_FEEDBACKSIZE uint32_t length(len) 4 206 * CRYPT_CTRL_GET_FEEDBACKSIZE uint32_t pointer sizeof(*uint32_t) 207 * CRYPT_CTRL_GET_BLOCKSIZE uint32_t length(len) 4 208 * 209 * @attention If the function is called by an external user and the error stack is concerned, 210 * it is recommended that BSL_ERR_ClearError() be called before this function is called. 211 * @param ctx [IN] Symmetric encryption/decryption handle 212 * @param type [IN] Parameter type 213 * @param data [IN/OUT] Input and output data 214 * @param len [OUT] Data length 215 * @retval #CRYPT_SUCCESS, success. 216 * error codes see the crypt_errno.h 217 */ 218 int32_t CRYPT_EAL_CipherCtrl(CRYPT_EAL_CipherCtx *ctx, int32_t type, void *data, uint32_t len); 219 220 /** 221 * @ingroup crypt_eal_cipher 222 * @brief Set the padding mode. 223 * 224 * @param ctx Symmetric encryption/decryption handle 225 * @param type Padding type 226 * @retval #CRYPT_SUCCESS, success. 227 * Error codes see crypt_errno.h 228 */ 229 int32_t CRYPT_EAL_CipherSetPadding(CRYPT_EAL_CipherCtx *ctx, CRYPT_PaddingType type); 230 231 /** 232 * @ingroup crypt_eal_cipher 233 * @brief Obtain the padding type. 234 * 235 * @param ctx Symmetric encryption/decryption handle 236 * @retval Return mode 237 */ 238 int32_t CRYPT_EAL_CipherGetPadding(CRYPT_EAL_CipherCtx *ctx); 239 240 /** 241 * @ingroup crypt_eal_cipher 242 * @brief Obtain the type of an algorithm based on the algorithm ID. 243 * 244 * @param id [IN] Symmetric algorithm ID. 245 * @param type [IN] Attribute type to be obtained. 246 * @param infoValue [OUT] Obtained attribute data. 247 * @retval CRYPT_SUCCESS, success 248 * Other error codes see crypt_errno.h 249 */ 250 int32_t CRYPT_EAL_CipherGetInfo(CRYPT_CIPHER_AlgId id, int32_t type, uint32_t *infoValue); 251 252 #ifdef __cplusplus 253 } 254 #endif // __cplusplus 255 256 #endif // CRYPT_EAL_CIPHER_H 257