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