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