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 UniversalKeystoreKit
41 * @since 9
42 * @version 1.0
43 */
44
45#include "native_huks_type.h"
46
47#ifdef __cplusplus
48extern "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 */
61struct 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 */
74struct 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 */
87struct 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 */
96void 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 */
111struct 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 */
126struct 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 */
142struct 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 */
154struct 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 */
166struct 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 */
179struct OH_Huks_Result OH_Huks_CheckParamMatch(const struct OH_Huks_Param *baseParam, const struct OH_Huks_Param *param);
180
181#ifdef __cplusplus
182}
183#endif
184
185/** @} */
186#endif /* NATIVE_HUKS_PARAM_H */
187