1 /* 2 * Copyright (c) 2025 Huawei Device Co., Ltd. 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 16 /** 17 * @addtogroup CryptoKdfApi 18 * @{ 19 * 20 * @brief Describes the KDF algorithm interface provided to applications. 21 * 22 * @since 20 23 */ 24 25 /** 26 * @file crypto_kdf.h 27 * 28 * @brief Defines the KDF APIs. 29 * 30 * @library libohcrypto.so 31 * @kit CryptoArchitectureKit 32 * @syscap SystemCapability.Security.CryptoFramework 33 * @since 20 34 */ 35 36 #ifndef CRYPTO_KDF_H 37 #define CRYPTO_KDF_H 38 39 #include "crypto_common.h" 40 41 #ifdef __cplusplus 42 extern "C" { 43 #endif 44 45 /** 46 * @brief Defines the KDF structure. 47 * 48 * @since 20 49 */ 50 typedef struct OH_CryptoKdf OH_CryptoKdf; 51 52 /** 53 * @brief Defines the KDF params structure. 54 * 55 * @since 20 56 */ 57 typedef struct OH_CryptoKdfParams OH_CryptoKdfParams; 58 59 /** 60 * @brief Defines the KDF param type. 61 * 62 * @since 20 63 */ 64 typedef enum { 65 /** Indicates the key or password for KDF. */ 66 CRYPTO_KDF_KEY_DATABLOB = 0, 67 68 /** Indicates the salt for KDF. */ 69 CRYPTO_KDF_SALT_DATABLOB = 1, 70 71 /** Indicates the info for KDF. */ 72 CRYPTO_KDF_INFO_DATABLOB = 2, 73 74 /** Indicates the iteration count for PBKDF2. */ 75 CRYPTO_KDF_ITER_COUNT_INT = 3, 76 77 /** Indicates the n for SCRYPT KDF. */ 78 CRYPTO_KDF_SCRYPT_N_UINT64 = 4, 79 80 /** Indicates the r for SCRYPT KDF. */ 81 CRYPTO_KDF_SCRYPT_R_UINT64 = 5, 82 83 /** Indicates the p for SCRYPT KDF. */ 84 CRYPTO_KDF_SCRYPT_P_UINT64 = 6, 85 86 /** Indicates the max memory for SCRYPT KDF. */ 87 CRYPTO_KDF_SCRYPT_MAX_MEM_UINT64 = 7, 88 } CryptoKdf_ParamType; 89 90 /** 91 * @brief Creates KDF params. 92 * 93 * @param algoName Indicates the KDF algorithm name. e.g. "HKDF", "PBKDF2", "SCRYPT". 94 * @param params Indicates the KDF params. 95 * @return {@link OH_Crypto_ErrCode#CRYPTO_SUCCESS} 0 - If the operation is successful. 96 * {@link OH_Crypto_ErrCode#CRYPTO_NOT_SUPPORTED} 801 - If the operation is not supported. 97 * {@link OH_Crypto_ErrCode#CRYPTO_MEMORY_ERROR} 17620001 - If memory operation failed. 98 * {@link OH_Crypto_ErrCode#CRYPTO_PARAMETER_CHECK_FAILED} 17620003 - If parameter check failed. 99 * {@link OH_Crypto_ErrCode#CRYPTO_OPERTION_ERROR} 17630001 - If crypto operation failed. 100 * @since 20 101 */ 102 OH_Crypto_ErrCode OH_CryptoKdfParams_Create(const char *algoName, OH_CryptoKdfParams **params); 103 104 /** 105 * @brief Sets a parameter to the KDF parameters. 106 * 107 * @param params Indicates the KDF parameters. 108 * @param type Indicates the KDF parameter type. 109 * @param value Indicates the KDF parameter value. 110 * @return {@link OH_Crypto_ErrCode#CRYPTO_SUCCESS} 0 - If the operation is successful. 111 * {@link OH_Crypto_ErrCode#CRYPTO_NOT_SUPPORTED} 801 - If the operation is not supported. 112 * {@link OH_Crypto_ErrCode#CRYPTO_MEMORY_ERROR} 17620001 - If memory operation failed. 113 * {@link OH_Crypto_ErrCode#CRYPTO_PARAMETER_CHECK_FAILED} 17620003 - If parameter check failed. 114 * {@link OH_Crypto_ErrCode#CRYPTO_OPERTION_ERROR} 17630001 - If crypto operation failed. 115 * @since 20 116 */ 117 OH_Crypto_ErrCode OH_CryptoKdfParams_SetParam(OH_CryptoKdfParams *params, CryptoKdf_ParamType type, 118 Crypto_DataBlob *value); 119 120 /** 121 * @brief Destroys the KDF params. 122 * 123 * @param params Indicates the KDF parameters. 124 * @since 20 125 */ 126 void OH_CryptoKdfParams_Destroy(OH_CryptoKdfParams *params); 127 128 /** 129 * @brief Creates a KDF context. 130 * 131 * @param algoName Indicates the KDF algorithm name. e.g. "HKDF|SHA384|EXTRACT_AND_EXPAND", "PBKDF2|SHA384", "SCRYPT". 132 * @param ctx Indicates the KDF context. 133 * @return {@link OH_Crypto_ErrCode#CRYPTO_SUCCESS} 0 - If the operation is successful. 134 * {@link OH_Crypto_ErrCode#CRYPTO_NOT_SUPPORTED} 801 - If the operation is not supported. 135 * {@link OH_Crypto_ErrCode#CRYPTO_MEMORY_ERROR} 17620001 - If memory operation failed. 136 * {@link OH_Crypto_ErrCode#CRYPTO_PARAMETER_CHECK_FAILED} 17620003 - If parameter check failed. 137 * {@link OH_Crypto_ErrCode#CRYPTO_OPERTION_ERROR} 17630001 - If crypto operation failed. 138 * @since 20 139 */ 140 OH_Crypto_ErrCode OH_CryptoKdf_Create(const char *algoName, OH_CryptoKdf **ctx); 141 142 /** 143 * @brief Derives a key. 144 * 145 * @param ctx The KDF context. 146 * @param params Indicates the KDF parameters. 147 * @param keyLen Indicates the key derivation length. 148 * @param key Indicates the derived key. 149 * @return {@link OH_Crypto_ErrCode#CRYPTO_SUCCESS} 0 - If the operation is successful. 150 * {@link OH_Crypto_ErrCode#CRYPTO_NOT_SUPPORTED} 801 - If the operation is not supported. 151 * {@link OH_Crypto_ErrCode#CRYPTO_MEMORY_ERROR} 17620001 - If memory operation failed. 152 * {@link OH_Crypto_ErrCode#CRYPTO_PARAMETER_CHECK_FAILED} 17620003 - If parameter check failed. 153 * {@link OH_Crypto_ErrCode#CRYPTO_OPERTION_ERROR} 17630001 - If crypto operation failed. 154 * @since 20 155 */ 156 OH_Crypto_ErrCode OH_CryptoKdf_Derive(OH_CryptoKdf *ctx, const OH_CryptoKdfParams *params, int keyLen, 157 Crypto_DataBlob *key); 158 159 /** 160 * @brief Destroys the KDF context. 161 * 162 * @param ctx The KDF context. 163 * @since 20 164 */ 165 void OH_CryptoKdf_Destroy(OH_CryptoKdf *ctx); 166 167 168 #ifdef __cplusplus 169 } 170 #endif 171 172 #endif /* CRYPTO_KDF_H */ 173 /** @} */ 174