1 /* 2 * Copyright (c) 2022 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 * @since 9 40 * @version 1.0 41 */ 42 43 #include "native_huks_type.h" 44 45 #ifdef __cplusplus 46 extern "C" { 47 #endif 48 49 /** 50 * @brief Initializes a parameter set. 51 * 52 * @param paramSet Indicates the double pointer to the parameter set to initialize. 53 * @return Returns {@link OH_Huks_ErrCode#OH_HUKS_SUCCESS} if the initialization is successful; 54 * returns an error code otherwise. 55 * @since 9 56 * @version 1.0 57 */ 58 struct OH_Huks_Result OH_Huks_InitParamSet(struct OH_Huks_ParamSet **paramSet); 59 60 /** 61 * @brief Adds parameters to a parameter set. 62 * 63 * @param paramSet Indicates the pointer to the parameter set to which parameters are to be added. 64 * @param params Indicates the pointer to the array of parameters to add. 65 * @param paramCnt Indicates the number of parameters to add. 66 * @return Returns {@link OH_Huks_ErrCode#OH_HUKS_SUCCESS} if the operation is successful; 67 * returns an error code otherwise. 68 * @since 9 69 * @version 1.0 70 */ 71 struct OH_Huks_Result OH_Huks_AddParams(struct OH_Huks_ParamSet *paramSet, 72 const struct OH_Huks_Param *params, uint32_t paramCnt); 73 74 /** 75 * @brief Constructs a parameter set. 76 * 77 * @param paramSet Indicates the double pointer to the parameter set to construct. 78 * @return Returns {@link OH_Huks_ErrCode#OH_HUKS_SUCCESS} if the operation is successful; 79 * returns an error code otherwise. 80 * @since 9 81 * @version 1.0 82 */ 83 struct OH_Huks_Result OH_Huks_BuildParamSet(struct OH_Huks_ParamSet **paramSet); 84 85 /** 86 * @brief Destroys a parameter set. 87 * 88 * @param paramSet Indicates the double pointer to the parameter set to destroy. 89 * @since 9 90 * @version 1.0 91 */ 92 void OH_Huks_FreeParamSet(struct OH_Huks_ParamSet **paramSet); 93 94 /** 95 * @brief Copies a parameter set (deep copy). 96 * 97 * @param fromParamSet Indicates the pointer to the parameter set to copy. 98 * @param fromParamSetSize Indicates the memory size occupied by the source parameter set. 99 * @param paramSet Indicates the double pointer to the new parameter set generated. 100 * @return Returns {@link OH_Huks_ErrCode#OH_HUKS_SUCCESS} if the operation is successful; 101 * returns an error code otherwise. 102 * @since 9 103 * @version 1.0 104 */ 105 struct OH_Huks_Result OH_Huks_CopyParamSet(const struct OH_Huks_ParamSet *fromParamSet, 106 uint32_t fromParamSetSize, struct OH_Huks_ParamSet **paramSet); 107 108 /** 109 * @brief Obtains parameters from a parameter set. 110 * 111 * @param paramSet Indicates the pointer to the target parameter set. 112 * @param tag Indicates the value of the parameter to be obtained. 113 * @param param Indicates the double pointer to the parameter obtained. 114 * @return Returns {@link OH_Huks_ErrCode#OH_HUKS_SUCCESS} if the operation is successful, 115 * returns an error code otherwise. 116 * @since 9 117 * @version 1.0 118 */ 119 struct OH_Huks_Result OH_Huks_GetParam(const struct OH_Huks_ParamSet *paramSet, uint32_t tag, 120 struct OH_Huks_Param **param); 121 122 /** 123 * @brief Refreshes data of the <b>Blob</b> type in a parameter set. 124 * 125 * @param paramSet Indicates the pointer to the target parameter set. 126 * @param isCopy Specifies whether to copy the data of the <b>Blob</b> type to the parameter set. 127 * If yes, the data of the <b>Blob</b> type will be copied to the parameter set. 128 * Otherwise, only the address of the <b>Blob</b> data will be refreshed. 129 * @return Returns {@link OH_Huks_ErrCode#OH_HUKS_SUCCESS} if operation is successful; 130 * returns an error code otherwise. 131 * @since 9 132 * @version 1.0 133 */ 134 struct OH_Huks_Result OH_Huks_FreshParamSet(struct OH_Huks_ParamSet *paramSet, bool isCopy); 135 136 /** 137 * @brief Checks whether the parameters in a parameter set are valid. 138 * 139 * @param paramSet Indicates the pointer to the parameter set to check. 140 * @return Returns {@link OH_Huks_ErrCode#OH_HUKS_SUCCESS} if the parameters in the parameter set are valid; 141 * returns other values if the parameter set has invalid, duplicate, or incorrect parameters. 142 * @since 9 143 * @version 1.0 144 */ 145 struct OH_Huks_Result OH_Huks_IsParamSetTagValid(const struct OH_Huks_ParamSet *paramSet); 146 147 /** 148 * @brief Checks whether a parameter set is of the valid size. 149 * 150 * @param paramSet Indicates the pointer to the parameter set to check. 151 * @param size Indicates the memory size occupied by the parameter set. 152 * @return Returns {@link OH_Huks_ErrCode#OH_HUKS_SUCCESS} if the parameter set is of the valid size; 153 * returns an error code otherwise. 154 * @since 9 155 * @version 1.0 156 */ 157 struct OH_Huks_Result OH_Huks_IsParamSetValid(const struct OH_Huks_ParamSet *paramSet, uint32_t size); 158 159 /** 160 * @brief Checks whether two parameters are the same. 161 * 162 * @param baseParam Indicates the pointer to the first parameter. 163 * @param param Indicates the pointer to the second parameter. 164 * @return Returns {@link OH_Huks_ErrCode#OH_HUKS_SUCCESS} if the two parameters are the same; 165 * returns an error code otherwise. 166 * @since 9 167 * @version 1.0 168 */ 169 struct OH_Huks_Result OH_Huks_CheckParamMatch(const struct OH_Huks_Param *baseParam, const struct OH_Huks_Param *param); 170 171 #ifdef __cplusplus 172 } 173 #endif 174 175 /** @} */ 176 #endif /* NATIVE_HUKS_PARAM_H */ 177