1 /** 2 * Copyright (c) 2020 HiSilicon (Shanghai) Technologies CO., LIMITED. 3 * Licensed under the Apache License, Version 2.0 (the "License"); 4 * you may not use this file except in compliance with the License. 5 * You may obtain a copy of the License at 6 * 7 * http://www.apache.org/licenses/LICENSE-2.0 8 * 9 * Unless required by applicable law or agreed to in writing, software 10 * distributed under the License is distributed on an "AS IS" BASIS, 11 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 * See the License for the specific language governing permissions and 13 * limitations under the License. 14 * 15 * Description: Provides cipher aead driver header \n 16 * 17 * History: \n 18 * 2023-03-14, Create file. \n 19 */ 20 #ifndef CIPHER_AEAD_H 21 #define CIPHER_AEAD_H 22 23 #include <stdint.h> 24 #include <stdbool.h> 25 #include "errcode.h" 26 27 #ifdef __cplusplus 28 #if __cplusplus 29 extern "C" { 30 #endif 31 #endif 32 33 /** 34 * @defgroup security_unified_cipher_aead Cipher AEAD 35 * @ingroup drivers_driver_security_unified 36 * @{ 37 */ 38 39 /** 40 * @if Eng 41 * @brief gcm encrypt and compute tag. 42 * @param [in] key Encryption key. 43 * @param [in] key_len Encryption key length in byte. Only support 16,24,32. 44 * @param [in] keyslot_handle The keyslot handle which store the encryption key. 45 * @param [in] iv The initial vector. 46 * @param [in] iv_len The initial vector lenght in byte. 47 * @param [in] aad The additional authentication message. NULL is support. 48 * @param [in] aad_len The additional authentication message length in byte. 49 * @param [in] plain_text Input plain text. 50 * @param [out] cipher_text Output cipher text. 51 * @param [in] data_len data length in byte. 52 * @param [out] tag Output tag. 53 * @param [in] tag_len The expected tag length in byte. 54 * @retval ERRCODE_SUCC Success. 55 * @retval Other Failure. For details, see @ref errcode_t 56 * @note There are two methods to set the key: 57 1）Using key/key_len, in which case, the keyslot_handle is set to 0. 58 2) Calling keyslot api to create one keyslot_handle and set it, in which case, 59 the key is set to NULL and key_len is 0. 60 When keyslot is supported, you must use method 2, otherwise you should use method 1. 61 * @else 62 * @brief GCM 加密并计算 tag. 63 * @param [in] key 加密密钥. 64 * @param [in] key_len 加密密钥长度，单位是 Byte. 只支持 16,24,32. 65 * @param [in] keyslot_handle 保存加密密钥的 keyslot 句柄. 66 * @param [in] iv 初始向量 67 * @param [in] iv_len 初始向量长度，单位是 Byte. 68 * @param [in] aad 附加认证信息，支持传入为 NULL 69 * @param [in] aad_len 附加认证信息，单位是 Byte. 70 * @param [in] plain_text 输入的明文. 71 * @param [out] cipher_text 输出的密文. 72 * @param [in] data_len 数据长度，单位是 Byte. 73 * @param [out] tag 输出的 tag 74 * @param [in] tag_len 期望的 tag 长度，单位是 Byte. 75 * @retval ERRCODE_SUCC 成功。 76 * @retval Other 失败，参考 @ref errcode_t 。 77 * @note 有两种方法设置密钥: 78 1）使用 key/key_len 组合，在这种情况下，keyslot_handle 传入 0. 79 2）使用 keyslot 接口创建 keyslot 句柄传入，在这种情况下，key 传入为 NULL，key_len 传入为 0. 80 若支持 keyslot，则必须使用方法2，否则只能使用方法1. 81 * @endif 82 */ 83 errcode_t uapi_drv_cipher_symc_gcm_encrypt( 84 uint8_t *key, uint32_t key_len, uint32_t keyslot_handle, 85 const uint8_t *iv, uint32_t iv_len, 86 const uint8_t *aad, uint32_t aad_len, 87 const uint8_t *plain_text, uint8_t *cipher_text, uint32_t data_len, 88 uint8_t *tag, uint32_t tag_len 89 ); 90 91 /** 92 * @if Eng 93 * @brief gcm decrypt and verify tag. 94 * @param [in] key Decryption key. 95 * @param [in] key_len Decryption key length in byte. Only support 16,24,32. 96 * @param [in] keyslot_handle The keyslot handle which store the decryption key. 97 * @param [in] iv The initial vector. 98 * @param [in] iv_len The initial vector lenght in byte. 99 * @param [in] aad The additional authentication message. NULL is support. 100 * @param [in] aad_len The additional authentication message length in byte. 101 * @param [in] cipher_text Input cipher text. 102 * @param [out] plain_text Output plain text. 103 * @param [in] data_len data length in byte. 104 * @param [in] tag Input tag to be verified. 105 * @param [in] tag_len The tag length in byte. 106 * @retval ERRCODE_SUCC Success. 107 * @retval Other Failure. For details, see @ref errcode_t 108 * @note There are two methods to set the key: 109 1）Using key/key_len, in which case, the keyslot_handle is set to 0. 110 2) Calling keyslot api to create one keyslot_handle and set it, in which case, 111 the key is set to NULL and key_len is 0. 112 When keyslot is supported, you must use method 2, otherwise you should use method 1. 113 * @else 114 * @brief GCM 解密并校验 tag. 115 * @param [in] key 解密密钥. 116 * @param [in] key_len 解密密钥长度，单位是 Byte. 只支持 16,24,32. 117 * @param [in] keyslot_handle 保存解密密钥的 keyslot 句柄. 118 * @param [in] iv 初始向量 119 * @param [in] iv_len 初始向量长度，单位是 Byte. 120 * @param [in] aad 附加认证信息，支持传入为 NULL 121 * @param [in] aad_len 附加认证信息，单位是 Byte. 122 * @param [in] cipher_text 输入的密文. 123 * @param [out] plain_text 输出的明文. 124 * @param [in] data_len 数据长度，单位是 Byte. 125 * @param [out] tag 待校验的 tag. 126 * @param [in] tag_len tag 长度，单位是 Byte. 127 * @retval ERRCODE_SUCC 成功。 128 * @retval Other 失败，参考 @ref errcode_t 。 129 * @note 有两种方法设置密钥: 130 1）使用 key/key_len 组合，在这种情况下，keyslot_handle 传入 0. 131 2）使用 keyslot 接口创建 keyslot 句柄传入，在这种情况下，key 传入为 NULL，key_len 传入为 0. 132 若支持 keyslot，则必须使用方法2，否则只能使用方法1. 133 * @endif 134 */ 135 errcode_t uapi_drv_cipher_symc_gcm_decrypt_verify( 136 uint8_t *key, uint32_t key_len, uint32_t keyslot_handle, 137 const uint8_t *iv, uint32_t iv_len, 138 const uint8_t *aad, uint32_t aad_len, 139 const uint8_t *cipher_text, uint8_t *plain_text, uint32_t data_len, 140 const uint8_t *tag, uint32_t tag_len 141 ); 142 143 /** 144 * @if Eng 145 * @brief GCM create channel handle. 146 * @param [out] handle Pointer to the created channel handle. 147 * @param [in] key Encryption/Decryption key. 148 * @param [in] key_len Encryption/Decryption key length in byte. Only support 16,24,32. 149 * @param [in] keyslot_handle The keyslot handle which store the encryption/decryption key. 150 * @param [in] iv The initial vector. 151 * @param [in] iv_len The initial vector lenght in byte. 152 * @param [in] aad The additional authentication message. NULL is support. 153 * @param [in] aad_len The additional authentication message length in byte. 154 * @param [in] tag_len The expected tag length in byte. 155 * @retval ERRCODE_SUCC Success. 156 * @retval Other Failure. For details, see @ref errcode_t 157 * @note There are two methods to set the key: 158 1）Using key/key_len, in which case, the keyslot_handle is set to 0. 159 2) Calling keyslot api to create one keyslot_handle and set it, in which case, 160 the key is set to NULL and key_len is 0. 161 When keyslot is supported, you must use method 2, otherwise you should use method 1. 162 * @else 163 * @brief GCM 创建通道句柄. 164 * @param [out] handle 指向创建的通道句柄的指针. 165 * @param [in] key 加解密密钥. 166 * @param [in] key_len 加解密密钥长度，单位是 Byte. 只支持 16,24,32. 167 * @param [in] keyslot_handle 保存加解密密钥的 keyslot 句柄. 168 * @param [in] iv 初始向量 169 * @param [in] iv_len 初始向量长度，单位是 Byte. 170 * @param [in] aad 附加认证信息，支持传入为 NULL 171 * @param [in] aad_len 附加认证信息，单位是 Byte. 172 * @param [in] tag_len 期望的 tag 长度，单位是 Byte. 173 * @retval ERRCODE_SUCC 成功。 174 * @retval Other 失败，参考 @ref errcode_t 。 175 * @note 有两种方法设置密钥: 176 1）使用 key/key_len 组合，在这种情况下，keyslot_handle 传入 0. 177 2）使用 keyslot 接口创建 keyslot 句柄传入，在这种情况下，key 传入为 NULL，key_len 传入为 0. 178 若支持 keyslot，则必须使用方法2，否则只能使用方法1. 179 * @endif 180 */ 181 errcode_t uapi_drv_cipher_symc_gcm_create(uint32_t *handle, 182 uint8_t *key, uint32_t key_len, uint32_t keyslot_handle, 183 const uint8_t *iv, uint32_t iv_len, 184 const uint8_t *aad, uint32_t aad_len, 185 uint32_t tag_len 186 ); 187 188 /** 189 * @if Eng 190 * @brief GCM destroy channel handle. 191 * @param [out] handle Channel handle to be destroyed. 192 * @retval ERRCODE_SUCC Success. 193 * @retval Other Failure. For details, see @ref errcode_t 194 * @else 195 * @brief GCM 销毁通道句柄. 196 * @param [in] handle 待销毁的通道句柄. 197 * @retval ERRCODE_SUCC 成功。 198 * @retval Other 失败，参考 @ref errcode_t 。 199 * @endif 200 */ 201 errcode_t uapi_drv_cipher_symc_gcm_destroy(uint32_t handle); 202 203 /** 204 * @if Eng 205 * @brief GCM encrypt. 206 * @param [in] handle The created channel handle. 207 * @param [in] plain_text Input plain text. 208 * @param [out] cipher_text Output cipher text. 209 * @param [in] data_len data length in byte. 210 * @retval ERRCODE_SUCC Success. 211 * @retval Other Failure. For details, see @ref errcode_t 212 * @note User can call this function more than one times to process data in fragments. 213 * @else 214 * @brief GCM 加密. 215 * @param [in] handle 已创建的通道句柄. 216 * @param [in] plain_text 输入的明文. 217 * @param [out] cipher_text 输出的密文. 218 * @param [in] data_len 数据长度，单位是 Byte. 219 * @retval ERRCODE_SUCC 成功。 220 * @retval Other 失败，参考 @ref errcode_t 。 221 * @note 用户可以调用该函数多次来处理分段的数据. 222 * @endif 223 */ 224 errcode_t uapi_drv_cipher_symc_gcm_encrypt_update(uint32_t handle, 225 const uint8_t *plain_text, uint8_t *cipher_text, uint32_t data_len 226 ); 227 228 /** 229 * @if Eng 230 * @brief GCM get tag after encryption. 231 * @param [in] handle The created channel handle. 232 * @param [out] tag Output tag. 233 * @param [in] tag_len The expected tag length in byte. The value must be the same as that of the 234 uapi_drv_cipher_symc_gcm_create interface. 235 * @retval ERRCODE_SUCC Success. 236 * @retval Other Failure. For details, see @ref errcode_t 237 * @else 238 * @brief GCM 加密完获取 tag. 239 * @param [in] handle 已创建的通道句柄. 240 * @param [out] tag 输出的 tag 241 * @param [in] tag_len 期望的 tag 长度，单位是 Byte. 必须和传入 uapi_drv_cipher_symc_gcm_create 接口的值一致. 242 * @retval ERRCODE_SUCC 成功。 243 * @retval Other 失败，参考 @ref errcode_t 。 244 * @endif 245 */ 246 errcode_t uapi_drv_cipher_symc_gcm_encrypt_get_tag(uint32_t handle, 247 uint8_t *tag, uint32_t tag_len 248 ); 249 250 /** 251 * @if Eng 252 * @brief GCM set tag before verify. 253 * @param [in] handle The created channel handle. 254 * @param [in] tag Input tag to be verified. 255 * @param [in] tag_len The tag length in byte. 256 * @retval ERRCODE_SUCC Success. 257 * @retval Other Failure. For details, see @ref errcode_t 258 * @else 259 * @brief GCM 校验前设置 tag. 260 * @param [in] handle 已创建的通道句柄. 261 * @param [out] tag 待校验的 tag. 262 * @param [in] tag_len tag 长度，单位是 Byte. 263 * @retval ERRCODE_SUCC 成功。 264 * @retval Other 失败，参考 @ref errcode_t 。 265 * @endif 266 */ 267 errcode_t uapi_drv_cipher_symc_gcm_decrypt_set_tag(uint32_t handle, 268 const uint8_t *tag, uint32_t tag_len 269 ); 270 271 /** 272 * @if Eng 273 * @brief GCM decrypt. 274 * @param [in] handle The created channel handle. 275 * @param [in] cipher_text Input cipher text. 276 * @param [out] plain_text Output plain text. 277 * @param [in] data_len data length in byte. 278 * @retval ERRCODE_SUCC Success. 279 * @retval Other Failure. For details, see @ref errcode_t 280 * @note User can call this function more than one times to process data in fragments. 281 * @else 282 * @brief GCM 解密. 283 * @param [in] handle 已创建的通道句柄. 284 * @param [in] cipher_text 输入的密文. 285 * @param [out] plain_text 输出的明文. 286 * @param [in] data_len 数据长度，单位是 Byte. 287 * @retval ERRCODE_SUCC 成功。 288 * @retval Other 失败，参考 @ref errcode_t 。 289 * @note 用户可以调用该函数多次来处理分段的数据. 290 * @endif 291 */ 292 errcode_t uapi_drv_cipher_symc_gcm_decrypt_update(uint32_t handle, 293 const uint8_t *cipher_text, uint8_t *plain_text, uint32_t data_len 294 ); 295 296 /** 297 * @if Eng 298 * @brief GCM verify tag after decrypt. 299 * @param [in] handle The created channel handle. 300 * @retval ERRCODE_SUCC Success. 301 * @retval Other Failure. For details, see @ref errcode_t 302 * @note Before invoking this interface, you must invoke uapi_drv_cipher_symc_gcm_decrypt_set_tag. 303 * @else 304 * @brief GCM 解密完校验 tag. 305 * @param [in] handle 已创建的通道句柄. 306 * @retval ERRCODE_SUCC 成功。 307 * @retval Other 失败，参考 @ref errcode_t 。 308 * @note 调用该接口前必须先调用 uapi_drv_cipher_symc_gcm_decrypt_set_tag. 309 * @endif 310 */ 311 errcode_t uapi_drv_cipher_symc_gcm_decrypt_verify_tag(uint32_t handle); 312 313 /** 314 * @} 315 */ 316 317 #ifdef __cplusplus 318 #if __cplusplus 319 } 320 #endif 321 #endif 322 323 #endif 324