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