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 * Description: km struct. 15 * 16 * Create: 2023-01-18 17 */ 18 #ifndef CRYPTO_KM_STRUCT_H 19 #define CRYPTO_KM_STRUCT_H 20 21 #include "td_type.h" 22 23 #ifdef __cplusplus 24 #if __cplusplus 25 extern "C" { 26 #endif 27 #endif /* __cplusplus */ 28 29 #define SESSION_KEY_LEN 16 30 31 typedef td_bool (*drv_kdf_wait_condition_func)(const td_void *param); 32 33 typedef td_bool (*drv_klad_wait_condition_func)(const td_void *param); 34 35 typedef td_s32 (*osal_kdf_wait_timeout_uninterruptible)(const td_void *wait, drv_kdf_wait_condition_func func, 36 const td_void *param, const td_u32 timeout_ms); 37 38 typedef td_s32 (*osal_klad_wait_timeout_uninterruptible)(const td_void *wait, drv_klad_wait_condition_func func, 39 const td_void *param, const td_u32 timeout_ms); 40 41 /** 42 * @if Eng 43 * @brief Root key selection during KDF key derivation. 44 * @else 45 * @brief KDF 密钥派生时根密钥选择。 46 * @endif 47 */ 48 typedef enum { 49 CRYPTO_KDF_OTP_KEY_MRK1 = 0, 50 CRYPTO_KDF_OTP_KEY_USK, 51 CRYPTO_KDF_OTP_KEY_RUSK, 52 CRYPTO_KDF_OTP_KEY_MAX 53 } crypto_kdf_otp_key; 54 55 /** 56 * @if Eng 57 * @brief Symmetric algorithm selection during KDF key derivation. 58 * @else 59 * @brief KDF 密钥派生时对称算法选择。 60 * @endif 61 */ 62 typedef enum { 63 CRYPTO_KDF_UPDATE_ALG_AES = 0, 64 CRYPTO_KDF_UPDATE_ALG_SM4, 65 CRYPTO_KDF_UPDATE_ALG_MAX 66 } crypto_kdf_update_alg; 67 68 /** 69 * @if Eng 70 * @brief Hash algorithm selection when the software PBKDF2 algorithm is used. 71 * @else 72 * @brief 软件PBKDF2算法时HASH算法选择。 73 * @endif 74 */ 75 typedef enum { 76 CRYPTO_KDF_SW_ALG_SHA1 = 0, 77 CRYPTO_KDF_SW_ALG_SHA256, 78 CRYPTO_KDF_SW_ALG_SHA384, 79 CRYPTO_KDF_SW_ALG_SHA512, 80 CRYPTO_KDF_SW_ALG_SM3 81 } crypto_kdf_sw_alg; 82 83 /** 84 * @if Eng 85 * @brief Select the derived key type during KDF key derivation. 86 * @else 87 * @brief KDF 密钥派生时派生key类型选择。 88 * @endif 89 */ 90 typedef enum { 91 CRYPTO_KDF_HARD_KEY_TYPE_SBRK0 = 0x03000000, 92 CRYPTO_KDF_HARD_KEY_TYPE_SBRK1, 93 CRYPTO_KDF_HARD_KEY_TYPE_SBRK2, 94 CRYPTO_KDF_HARD_KEY_TYPE_ABRK0, 95 CRYPTO_KDF_HARD_KEY_TYPE_ABRK1, 96 CRYPTO_KDF_HARD_KEY_TYPE_ABRK2, 97 CRYPTO_KDF_HARD_KEY_TYPE_DRK0, 98 CRYPTO_KDF_HARD_KEY_TYPE_DRK1, 99 CRYPTO_KDF_HARD_KEY_TYPE_RDRK0, 100 CRYPTO_KDF_HARD_KEY_TYPE_RDRK1, 101 CRYPTO_KDF_HARD_KEY_TYPE_PSK, 102 CRYPTO_KDF_HARD_KEY_TYPE_FDRK0, 103 CRYPTO_KDF_HARD_KEY_TYPE_ODRK0, 104 CRYPTO_KDF_HARD_KEY_TYPE_ODRK1, 105 CRYPTO_KDF_HARD_KEY_TYPE_OARK0, 106 CRYPTO_KDF_HARD_KEY_TYPE_MDRK0, 107 CRYPTO_KDF_HARD_KEY_TYPE_MDRK1, 108 CRYPTO_KDF_HARD_KEY_TYPE_MDRK2, 109 CRYPTO_KDF_HARD_KEY_TYPE_MDRK3, 110 111 CRYPTO_KDF_HARD_KEY_TYPE_ABRK_REE, 112 CRYPTO_KDF_HARD_KEY_TYPE_ABRK_TEE, 113 CRYPTO_KDF_HARD_KEY_TYPE_RDRK_REE, 114 CRYPTO_KDF_HARD_KEY_TYPE_RDRK_TEE, 115 } crypto_kdf_hard_key_type; 116 117 /** 118 * @if Eng 119 * @brief KDF key derivation, hash algorithm selection when the hardware PBKDF2 algorithm is used. 120 * @else 121 * @brief KDF 密钥派生，硬件PBKDF2算法时HASH算法选择。 122 * @endif 123 */ 124 typedef enum { 125 CRYPTO_KDF_HARD_ALG_SHA256 = 0, 126 CRYPTO_KDF_HARD_ALG_SM3, 127 CRYPTO_KDF_HARD_ALG_MAX 128 } crypto_kdf_hard_alg; 129 130 typedef enum { 131 CRYPTO_KDF_HARD_KEY_SIZE_128BIT = 0, 132 CRYPTO_KDF_HARD_KEY_SIZE_192BIT, 133 CRYPTO_KDF_HARD_KEY_SIZE_256BIT, 134 } crypto_kdf_hard_key_size; 135 136 typedef struct { 137 crypto_kdf_hard_key_type hard_key_type; 138 crypto_kdf_hard_alg hard_alg; 139 crypto_kdf_hard_key_size hard_key_size; 140 td_u8 *salt; 141 td_u32 salt_length; 142 td_bool is_oneway; 143 } crypto_kdf_hard_calc_param; 144 145 /** 146 * @if Eng 147 * @brief The klad target module's algorithm engine, determining the algorithm supported by the sent key. 148 * @else 149 * @brief klad 目标模块算法引擎，决定送出的 key 支持哪个算法。 150 * @endif 151 */ 152 typedef enum { 153 CRYPTO_KLAD_ENGINE_AES = 0x20, 154 CRYPTO_KLAD_ENGINE_SM4 = 0x50, 155 CRYPTO_KLAD_ENGINE_TDES = 0x70, 156 CRYPTO_KLAD_ENGINE_SHA1_HMAC = 0xA0, 157 CRYPTO_KLAD_ENGINE_SHA2_HMAC = 0xA1, 158 CRYPTO_KLAD_ENGINE_SM3_HMAC = 0xA2, 159 CRYPTO_KLAD_ENGINE_MAX 160 } crypto_klad_engine; 161 162 typedef enum { 163 CRYPTO_KLAD_SEC_DISABLE = 0, 164 CRYPTO_KLAD_SEC_ENABLE, 165 CRYPTO_KLAD_SEC_MAX, 166 CRYPTO_KLAD_SEC_INVALID = 0xffffffff, 167 } crypto_klad_sec; 168 169 /* * Key parity, valid when key length is not more than 128bit */ 170 /* * CNcomment: 密钥奇偶属性 */ 171 typedef enum { 172 CRYPTO_KLAD_KEY_EVEN = 0x0, /* *< even key */ 173 CRYPTO_KLAD_KEY_ODD = 0x1, /* *< odd key */ 174 CRYPTO_KLAD_KEY_PARITY_MAX, 175 CRYPTO_KLAD_KEY_PARITY_INVALID = 0xffffffff, 176 } crypto_klad_key_parity; 177 178 /** 179 * @if Eng 180 * @brief The klad target module，determining the module to which the key is sent. 181 * @else 182 * @brief klad 目标模块，决定 key 送给哪个模块使用。 183 * @endif 184 */ 185 typedef enum { 186 CRYPTO_KLAD_DEST_MCIPHER = 0, 187 CRYPTO_KLAD_DEST_HMAC, 188 CRYPTO_KLAD_DEST_FLASH, 189 CRYPTO_KLAD_DEST_NPU, 190 CRYPTO_KLAD_DEST_AIDSP, 191 CRYPTO_KLAD_DEST_MAX, 192 } crypto_klad_dest; 193 194 /** 195 * @if Eng 196 * @brief Flash online decryption mode, determining the mode used after the key is sent. 197 * @else 198 * @brief Flash 在线解密模式，决定送 key 后使用哪种模式 199 * @endif 200 */ 201 typedef enum { 202 CRYPTO_KLAD_FLASH_KEY_TYPE_REE_DEC = 0x00, /* REE flash online decryption key */ 203 CRYPTO_KLAD_FLASH_KEY_TYPE_TEE_DEC, /* TEE flash online decryption key */ 204 CRYPTO_KLAD_FLASH_KEY_TYPE_TEE_AUT, /* TEE flash online authentication key */ 205 CRYPTO_KLAD_FLASH_KEY_TYPE_INVALID, 206 } crypto_klad_flash_key_type; 207 208 /** 209 * @if Eng 210 * @brief Symmetric key length. Determines the length of the final working key. 211 * @else 212 * @brief 对称密钥长度。决定了最终的工作密钥的长度 213 * @endif 214 */ 215 typedef enum { 216 CRYPTO_KLAD_KEY_SIZE_128BIT, 217 CRYPTO_KLAD_KEY_SIZE_192BIT, 218 CRYPTO_KLAD_KEY_SIZE_256BIT, 219 } crypto_klad_key_size; 220 221 /** 222 * @if Eng 223 * @brief When the target engine is HMAC, determine the HAMC algorithm to be used. 224 * @else 225 * @brief 当目标引擎为HMAC时，决定具体使用的HAMC算法。 226 * @endif 227 */ 228 typedef enum { 229 CRYPTO_KLAD_HMAC_TYPE_SHA1 = 0x20, /*!< @if Eng Insecure algorithm, not recommended. 230 @else 不安全算法，不推荐使用。 @endif */ 231 CRYPTO_KLAD_HMAC_TYPE_SHA224, 232 CRYPTO_KLAD_HMAC_TYPE_SHA256, 233 CRYPTO_KLAD_HMAC_TYPE_SHA384, 234 CRYPTO_KLAD_HMAC_TYPE_SHA512, 235 CRYPTO_KLAD_HMAC_TYPE_SM3 = 0x30, 236 CRYPTO_KLAD_HMAC_TYPE_MAX, 237 CRYPTO_KLAD_HMAC_TYPE_INVALID = 0xffffffff, 238 } crypto_klad_hmac_type; 239 240 /** 241 * @if Eng 242 * @brief Determines the current derived key level during klad key derivation. 243 * @else 244 * @brief klad密钥派生时，决定当前派生的密钥层级。 245 * @endif 246 */ 247 typedef enum { 248 CRYPTO_KLAD_LEVEL_SEL_FIRST = 0, 249 CRYPTO_KLAD_LEVEL_SEL_SECOND 250 } crypto_klad_level_sel; 251 252 /** 253 * @if Eng 254 * @brief Determines the symmetric algorithm used for derivation during klad key derivation. 255 * @else 256 * @brief klad密钥派生时，决定当前派生使用的对称算法。 257 * @endif 258 */ 259 typedef enum { 260 CRYPTO_KLAD_ALG_SEL_TDES = 0, 261 CRYPTO_KLAD_ALG_SEL_AES, 262 CRYPTO_KLAD_ALG_SEL_SM4, 263 } crypto_klad_alg_sel; 264 265 /** 266 * @if Eng 267 * @brief Clear key structure when klad sends a clear key. 268 * @else 269 * @brief klad送明文key时，明文key的结构。 270 * @endif 271 */ 272 typedef struct { 273 td_u8 *key; /*!< @if Eng Clear key content. 274 @else 明文key内容。 @endif */ 275 td_u32 key_length; /*!< @if Eng Length of the clear key, in bytes. 276 For the symmetric algorithm, the value can only be 16, 24, or 32. 277 For HMAC-SH1/SHA224/SHA256/SM3, the value cannot exceed 64. 278 For HMAC-SHA384/SHA512, the value cannot exceed 128. 279 @else 明文key长度，单位为字节。 对于对称算法，只能是16/24/32； 280 对于HMAC-SH1/SHA224/SHA256/SM3，长度不超过64； 281 对于HMAC-SHA384/SHA512，长度不超过128。@endif */ 282 td_bool key_parity; /*!< @if Eng Indicates the parity attribute of a key. 283 Valid when the target is a symmetric algorithm engine and key_length is set to 16. 284 @else key的奇偶属性。当目标为对称算法引擎且key_length为16时生效。 @endif */ 285 crypto_klad_hmac_type hmac_type; /*!< @if Eng Indicates the HMAC algorithm. 286 Valid only when the target is the HMAC algorithm engine.. 287 @else hmac 算法。当目标为HMAC算法引擎时生效。 @endif */ 288 } crypto_klad_clear_key; 289 290 /** 291 * @if Eng 292 * @brief Keyladder root key type selection. 293 * @else 294 * @brief Keyladder 根密钥类型选择。 295 * @endif 296 */ 297 typedef struct { 298 crypto_kdf_hard_key_type rootkey_type; 299 } crypto_klad_config; 300 301 /** 302 * @if Eng 303 * @brief Keyladder working key attribute configuration. 304 * @else 305 * @brief Keyladder 工作密钥属性配置。 306 * @endif 307 */ 308 typedef struct { 309 crypto_klad_engine engine; /*!< @if Eng The working key can be used for which algorithm of the crypto engine. 310 @else 工作密钥可用于加密引擎的哪种算法。 @endif */ 311 td_bool decrypt_support; /*!< @if Eng The working key can be used for decrypting. 312 @else 工作密钥可用于解密。 @endif */ 313 td_bool encrypt_support; /*!< @if Eng The working key can be used for encrypting. 314 @else 工作密钥可用于加密。 @endif */ 315 } crypto_klad_key_config; 316 317 /** 318 * @if Eng 319 * @brief Security attribute of the key. 320 when cipher work mode is CBC_MAC, dest_buf_sec_support and dest_buf_non_sec_support cannot be both false 321 * @else 322 * @brief key 的安全属性。 323 当加密工作模式为CBC_MAC时，dest_buf_sec_support和dest_buf_non_sec_support不能同时为false。 324 * @endif 325 */ 326 typedef struct { 327 td_bool key_sec; /*!< @if Eng Secure key can only be used by TEE CPU and AIDSP locked cipher and hash channel. 328 @else 安全密钥只能由TEE CPU和AIDSP锁定的对称通道或哈希通道使用。 @endif */ 329 td_bool master_only_enable; /*!< @if Eng Only the cipher or hash channel which is locked by same CPU as keyladder 330 can use this key, valid only for TEE CPU and AIDSP. 331 @else 只有与Keylader相同的CPU锁定的密码或哈希通道才能使用此密钥， 332 当TEE CPU或AIDSP时生效。 @endif */ 333 td_bool dest_buf_sec_support; /*!< @if Eng The destination buffer of target engine can be secure. 334 @else 目标引擎的目标缓冲区可以是安全的。 @endif */ 335 td_bool dest_buf_non_sec_support; /*!< @if Eng The destination buffer of target engine can be secure. 336 @else 目标引擎的目标缓冲区可以是非安全的。 @endif */ 337 td_bool src_buf_sec_support; /*!< @if Eng The destination buffer of target engine can be secure. 338 @else 目标引擎的源缓冲区可以是安全的。 @endif */ 339 td_bool src_buf_non_sec_support; /*!< @if Eng The destination buffer of target engine can be secure. 340 @else 目标引擎的源缓冲区可以是非安全的。 @endif */ 341 } crypto_klad_key_secure_config; 342 343 /** 344 * @if Eng 345 * @brief Keyladder configuration attributes. 346 * @else 347 * @brief Keyladder 配置属性。 348 * @endif 349 */ 350 typedef struct { 351 crypto_klad_config klad_cfg; /*!< @if Eng The keyladder configuration, valid for harware key. 352 @else KeyLader配置，对硬件密钥有效。 @endif */ 353 crypto_klad_key_config key_cfg; /*!< @if Eng The working key configuration. 354 @else 工作密钥配置。 @endif */ 355 crypto_klad_key_secure_config key_sec_cfg; /*!< @if Eng The working key security configuration. 356 @else 工作密钥安全配置。 @endif */ 357 td_u32 rkp_sw_cfg; 358 } crypto_klad_attr; 359 360 /** 361 * @if Eng 362 * @brief Keyladder hardware key configuration attributes. 363 * @else 364 * @brief Keyladder硬件key参数配置。 365 * @endif 366 */ 367 typedef struct { 368 crypto_kdf_hard_alg kdf_hard_alg; 369 td_bool key_parity; /*!< @if Eng Indicates the parity attribute of a key. 370 Valid when the target is a symmetric algorithm engine and key_length is set to 16. 371 @else key的奇偶属性。当目标为对称算法引擎且key_length为16时生效。 @endif */ 372 crypto_klad_key_size key_size; 373 td_u8 *salt; /*!< @if Eng Salt content. Used as user input materials for key derivation. 374 The final working key varies according to the salt value. 375 @else 盐值内容。作为用户输入材料参与密钥派生，盐值不同，最终的工作密钥也不同。 @endif */ 376 td_u32 salt_length; /*!< @if Eng Salt length, in bytes. It can only be 28. 377 @else 盐值长度，单位是字节。只能为28。 @endif */ 378 td_bool oneway; /*!< @if Eng Salt length, in bytes. 379 @else 盐值长度，单位是字节。 @endif */ 380 } crypto_klad_effective_key; 381 382 /** 383 * @if Eng 384 * @brief Session key configuration attributes. 385 * @else 386 * @brief Session key参数配置。 387 * @endif 388 */ 389 typedef struct { 390 td_u8 key[SESSION_KEY_LEN]; /*!< @if Eng Session key. 391 @else 会话密钥。 @endif */ 392 td_u32 key_length; /*!< @if Eng Session key length. 393 @else 会话密钥长度。 @endif */ 394 crypto_klad_level_sel level; /*!< @if Eng Derived key hierarchy. 395 @else 派生的密钥层级。 @endif */ 396 crypto_klad_alg_sel alg; /*!< @if Eng Symmetric algorithm used in derivation. 397 @else 派生使用的对称算法。 @endif */ 398 } crypto_klad_session_key; 399 400 /** 401 * @if Eng 402 * @brief Keyslot type selection. 403 * @else 404 * @brief keyslot 类型选择。 405 * @endif 406 */ 407 typedef enum { 408 CRYPTO_KEYSLOT_TYPE_MCIPHER = 0, 409 CRYPTO_KEYSLOT_TYPE_HMAC, 410 CRYPTO_KEYSLOT_TYPE_FLASH, 411 } crypto_keyslot_type; 412 413 #ifdef __cplusplus 414 #if __cplusplus 415 } 416 #endif 417 #endif /* __cplusplus */ 418 419 #endif /* OT_KM_STRUCT_H */ 420