1 /* 2 * Copyright (c) 2022-2024 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 HuksParamSetApi 18 * @{ 19 * 20 * @brief Defines the capabilities of OpenHarmony Universal KeyStore (HUKS) parameter sets. 21 * The HUKS APIs can be used to perform parameter set lifecycle management, 22 * including initializing a parameter set, adding parameters to a parameter set, constructing 23 * a parameter set, and destroying a parameter set. 24 * They can also be used to obtain parameters, copy parameter sets, and check parameter validity. 25 * 26 * @since 9 27 * @version 1.0 28 */ 29 30 /** 31 * @file native_huks_param.h 32 * 33 * @brief Provides APIs for constructing, using, and destroying parameter sets. 34 * 35 * @library libhuks_ndk.z.so 36 * @syscap SystemCapability.Security.Huks.Core 37 * 38 * include "huks/include/native_huks_type.h" 39 * @kit UniversalKeystoreKit 40 * @since 9 41 * @version 1.0 42 */ 43 44 #ifndef NATIVE_HUKS_PARAM_H 45 #define NATIVE_HUKS_PARAM_H 46 47 #include "native_huks_type.h" 48 49 #ifdef __cplusplus 50 extern "C" { 51 #endif 52 53 /** 54 * @brief Initializes a parameter set. 55 * 56 * @param paramSet Indicates the double pointer to the parameter set to initialize. 57 * @return {@link OH_Huks_ErrCode#OH_HUKS_SUCCESS} 0 - If the initialization is successful. 58 * {@link OH_Huks_ErrCode#OH_HUKS_ERR_CODE_INSUFFICIENT_MEMORY} 12000014 - If the memory is insufficient. 59 * {@link OH_Huks_ErrCode#OH_HUKS_ERR_CODE_ILLEGAL_ARGUMENT} 401 - If the paramset is null. 60 * @since 9 61 * @version 1.0 62 */ 63 struct OH_Huks_Result OH_Huks_InitParamSet(struct OH_Huks_ParamSet **paramSet); 64 65 /** 66 * @brief Adds parameters to a parameter set. 67 * 68 * @param paramSet Indicates the pointer to the parameter set to which parameters are to be added. 69 * @param params Indicates the pointer to the array of parameters to add. 70 * @param paramCnt Indicates the number of parameters to add. 71 * @return {@link OH_Huks_ErrCode#OH_HUKS_SUCCESS} 0 - If the operation is successful. 72 * {@link OH_Huks_ErrCode#OH_HUKS_ERR_CODE_ILLEGAL_ARGUMENT} 401 - If params is null or paramSet is invalid. 73 * @since 9 74 * @version 1.0 75 */ 76 struct OH_Huks_Result OH_Huks_AddParams(struct OH_Huks_ParamSet *paramSet, 77 const struct OH_Huks_Param *params, uint32_t paramCnt); 78 79 /** 80 * @brief Constructs a parameter set. 81 * 82 * @param paramSet Indicates the double pointer to the parameter set to construct. 83 * @return {@link OH_Huks_ErrCode#OH_HUKS_SUCCESS} 0 - If the operation is successful. 84 * {@link OH_Huks_ErrCode#OH_HUKS_ERR_CODE_ILLEGAL_ARGUMENT} 401 - If paramSet is invalid. 85 * {@link OH_Huks_ErrCode#OH_HUKS_ERR_CODE_INSUFFICIENT_MEMORY} 12000014 - If the memory is insufficient. 86 * @since 9 87 * @version 1.0 88 */ 89 struct OH_Huks_Result OH_Huks_BuildParamSet(struct OH_Huks_ParamSet **paramSet); 90 91 /** 92 * @brief Destroys a parameter set. 93 * 94 * @param paramSet Indicates the double pointer to the parameter set to destroy. 95 * @since 9 96 * @version 1.0 97 */ 98 void OH_Huks_FreeParamSet(struct OH_Huks_ParamSet **paramSet); 99 100 /** 101 * @brief Copies a parameter set (deep copy). 102 * 103 * @param fromParamSet Indicates the pointer to the parameter set to copy. 104 * @param fromParamSetSize Indicates the memory size occupied by the source parameter set. 105 * @param paramSet Indicates the double pointer to the new parameter set generated. 106 * @return {@link OH_Huks_ErrCode#OH_HUKS_SUCCESS} 0 - If the operation is successful. 107 * {@link OH_Huks_ErrCode#OH_HUKS_ERR_CODE_ILLEGAL_ARGUMENT} 401 - If fromParamSet or fromParamSetSize 108 * or paramSet is invalid. 109 * {@link OH_Huks_ErrCode#OH_HUKS_ERR_CODE_INSUFFICIENT_MEMORY} 12000014 - If the memory is insufficient. 110 * @since 9 111 * @version 1.0 112 */ 113 struct OH_Huks_Result OH_Huks_CopyParamSet(const struct OH_Huks_ParamSet *fromParamSet, 114 uint32_t fromParamSetSize, struct OH_Huks_ParamSet **paramSet); 115 116 /** 117 * @brief Obtains parameters from a parameter set. 118 * 119 * @param paramSet Indicates the pointer to the target parameter set. 120 * @param tag Indicates the value of the parameter to be obtained. 121 * @param param Indicates the double pointer to the parameter obtained. 122 * @return {@link OH_Huks_ErrCode#OH_HUKS_SUCCESS} 0 - If the operation is successful, 123 * {@link OH_Huks_ErrCode#OH_HUKS_ERR_CODE_ILLEGAL_ARGUMENT} 401 - If paramSet or param is invalid, 124 * or if the param doesn't exist in the pararmset. 125 * @since 9 126 * @version 1.0 127 */ 128 struct OH_Huks_Result OH_Huks_GetParam(const struct OH_Huks_ParamSet *paramSet, uint32_t tag, 129 struct OH_Huks_Param **param); 130 131 /** 132 * @brief Refreshes data of the <b>Blob</b> type in a parameter set. 133 * 134 * @param paramSet Indicates the pointer to the target parameter set. 135 * @param isCopy Specifies whether to copy the data of the <b>Blob</b> type to the parameter set. 136 * If yes, the data of the <b>Blob</b> type will be copied to the parameter set. 137 * Otherwise, only the address of the <b>Blob</b> data will be refreshed. 138 * @return {@link OH_Huks_ErrCode#OH_HUKS_SUCCESS} 0 - If operation is successful. 139 * {@link OH_Huks_ErrCode#OH_HUKS_ERR_CODE_ILLEGAL_ARGUMENT} 401 - If paramSet is invalid. 140 * {@link OH_Huks_ErrCode#OH_HUKS_ERR_CODE_INSUFFICIENT_MEMORY} 12000014 - If the memory is insufficient. 141 * @since 9 142 * @version 1.0 143 */ 144 struct OH_Huks_Result OH_Huks_FreshParamSet(struct OH_Huks_ParamSet *paramSet, bool isCopy); 145 146 /** 147 * @brief Checks whether the parameters in a parameter set are valid. 148 * 149 * @param paramSet Indicates the pointer to the parameter set to check. 150 * @return {@link OH_Huks_ErrCode#OH_HUKS_SUCCESS} 0 - If the parameters in the parameter set are valid. 151 * {@link OH_Huks_ErrCode#OH_HUKS_ERR_CODE_ILLEGAL_ARGUMENT} 401 - If paramSet is invalid or 152 * the parameter set has invalid, duplicate, or incorrect tags. 153 * @since 9 154 * @version 1.0 155 */ 156 struct OH_Huks_Result OH_Huks_IsParamSetTagValid(const struct OH_Huks_ParamSet *paramSet); 157 158 /** 159 * @brief Checks whether a parameter set is of the valid size. 160 * 161 * @param paramSet Indicates the pointer to the parameter set to check. 162 * @param size Indicates the memory size occupied by the parameter set. 163 * @return {@link OH_Huks_ErrCode#OH_HUKS_SUCCESS} 0 - If the parameter set is of the valid size. 164 * {@link OH_Huks_ErrCode#OH_HUKS_ERR_CODE_ILLEGAL_ARGUMENT} 401 - If paramSet is invalid. 165 * @since 9 166 * @version 1.0 167 */ 168 struct OH_Huks_Result OH_Huks_IsParamSetValid(const struct OH_Huks_ParamSet *paramSet, uint32_t size); 169 170 /** 171 * @brief Checks whether two parameters are the same. 172 * 173 * @param baseParam Indicates the pointer to the first parameter. 174 * @param param Indicates the pointer to the second parameter. 175 * @return {@link OH_Huks_ErrCode#OH_HUKS_SUCCESS} 0 - If the two parameters are the same. 176 * {@link OH_Huks_ErrCode#OH_HUKS_ERR_CODE_ILLEGAL_ARGUMENT} 401 - If one of the paramSet is invalid, 177 * or if the params don't match, or if the tag inside is invalid. 178 * @since 9 179 * @version 1.0 180 */ 181 struct OH_Huks_Result OH_Huks_CheckParamMatch(const struct OH_Huks_Param *baseParam, const struct OH_Huks_Param *param); 182 183 /** 184 * @brief Destroys a parameter set. 185 * 186 * @param keyAliasSet Indicates the pointer to the parameter set to destroy. 187 * @since 20 188 * @version 1.0 189 */ 190 void OH_Huks_FreeKeyAliasSet(struct OH_Huks_KeyAliasSet *keyAliasSet); 191 192 #ifdef __cplusplus 193 } 194 #endif 195 196 /** @} */ 197 #endif /* NATIVE_HUKS_PARAM_H */ 198