1# native_huks_param.h 2 3<!--Kit: Universal Keystore Kit--> 4<!--Subsystem: Security--> 5<!--Owner: @wutiantian-gitee--> 6<!--Designer: @HighLowWorld--> 7<!--Tester: @wxy1234564846--> 8<!--Adviser: @zengyawen--> 9 10## Overview 11 12Provides APIs for constructing, using, and destroying a parameter set. 13 14**File to include**: <huks/native_huks_param.h> 15 16**Library**: libhuks_ndk.z.so 17 18**System capability**: SystemCapability.Security.Huks.Core 19 20The preceding system capability is available since API version 20. From API versions 9 to 19, the system capability is **SystemCapability.Security.Huks**. 21 22**Since**: 9 23 24**Related module**: [HuksParamSetApi](capi-huksparamsetapi.md) 25 26## Summary 27 28### Functions 29 30| Name| Description| 31| -- | -- | 32| [struct OH_Huks_Result OH_Huks_InitParamSet(struct OH_Huks_ParamSet **paramSet)](#oh_huks_initparamset) | Initializes a parameter set.| 33| [struct OH_Huks_Result OH_Huks_AddParams(struct OH_Huks_ParamSet *paramSet,const struct OH_Huks_Param *params, uint32_t paramCnt)](#oh_huks_addparams) | Adds parameters to a parameter set.| 34| [struct OH_Huks_Result OH_Huks_BuildParamSet(struct OH_Huks_ParamSet **paramSet)](#oh_huks_buildparamset) | Constructs a parameter set.| 35| [void OH_Huks_FreeParamSet(struct OH_Huks_ParamSet **paramSet)](#oh_huks_freeparamset) | Frees a parameter set.| 36| [struct OH_Huks_Result OH_Huks_CopyParamSet(const struct OH_Huks_ParamSet *fromParamSet,uint32_t fromParamSetSize, struct OH_Huks_ParamSet **paramSet)](#oh_huks_copyparamset) | Copies a parameter set (deep copy).| 37| [struct OH_Huks_Result OH_Huks_GetParam(const struct OH_Huks_ParamSet *paramSet, uint32_t tag,struct OH_Huks_Param **param)](#oh_huks_getparam) | Obtains a parameter from a parameter set.| 38| [struct OH_Huks_Result OH_Huks_FreshParamSet(struct OH_Huks_ParamSet *paramSet, bool isCopy)](#oh_huks_freshparamset) | Refreshes the [OH_Huks_Blob](capi-hukstypeapi-oh-huks-blob.md) data in the parameter set.| 39| [struct OH_Huks_Result OH_Huks_IsParamSetTagValid(const struct OH_Huks_ParamSet *paramSet)](#oh_huks_isparamsettagvalid) | Checks whether the parameters in a parameter set are valid.| 40| [struct OH_Huks_Result OH_Huks_IsParamSetValid(const struct OH_Huks_ParamSet *paramSet, uint32_t size)](#oh_huks_isparamsetvalid) | Checks whether a parameter set is of the valid size.| 41| [struct OH_Huks_Result OH_Huks_CheckParamMatch(const struct OH_Huks_Param *baseParam, const struct OH_Huks_Param *param)](#oh_huks_checkparammatch) | Checks whether two parameters are the same.| 42| [void OH_Huks_FreeKeyAliasSet(struct OH_Huks_KeyAliasSet *keyAliasSet)](#oh_huks_freekeyaliasset) | Frees a parameter set.| 43 44## Function Description 45 46### OH_Huks_InitParamSet() 47 48``` 49struct OH_Huks_Result OH_Huks_InitParamSet(struct OH_Huks_ParamSet **paramSet) 50``` 51 52**Description** 53 54Initializes a parameter set. 55 56**Since**: 9 57 58 59**Parameters** 60 61| Name| Description| 62| -- | -- | 63| [struct OH_Huks_ParamSet](capi-hukstypeapi-oh-huks-paramset.md) **paramSet | Pointer to the parameter set to initialize.| 64 65**Returns** 66 67| Type| Description| 68| -- | -- | 69| [struct OH_Huks_Result](capi-hukstypeapi-oh-huks-result.md) | Possible error codes (**errorCode**):<br> OH_HUKS_SUCCESS = 0: Initialization successful.<br> OH_HUKS_ERR_CODE_INSUFFICIENT_MEMORY = 12000014: Insufficient memory.<br> OH_HUKS_ERR_CODE_ILLEGAL_ARGUMENT = 401: **paramSet** is invalid.| 70 71### OH_Huks_AddParams() 72 73``` 74struct OH_Huks_Result OH_Huks_AddParams(struct OH_Huks_ParamSet *paramSet,const struct OH_Huks_Param *params, uint32_t paramCnt) 75``` 76 77**Description** 78 79Adds parameters to a parameter set. 80 81**Since**: 9 82 83 84**Parameters** 85 86| Name| Description| 87| -- | -- | 88| [struct OH_Huks_ParamSet](capi-hukstypeapi-oh-huks-paramset.md) *paramSet | Pointer to the parameter set to which parameters are to be added.| 89| [const struct OH_Huks_Param](capi-hukstypeapi-oh-huks-param.md) *params | Pointer to an array of parameters to add.| 90| uint32_t paramCnt | Number of parameters to add.| 91 92**Returns** 93 94| Type| Description| 95| -- | -- | 96| [struct OH_Huks_Result](capi-hukstypeapi-oh-huks-result.md) | Possible error codes (**errorCode**):<br> OH_HUKS_SUCCESS = 0: Operation successful.<br> OH_HUKS_ERR_CODE_ILLEGAL_ARGUMENT = 401: **params** is a null pointer or **paramSet** is invalid.| 97 98### OH_Huks_BuildParamSet() 99 100``` 101struct OH_Huks_Result OH_Huks_BuildParamSet(struct OH_Huks_ParamSet **paramSet) 102``` 103 104**Description** 105 106Constructs a parameter set. 107 108**Since**: 9 109 110 111**Parameters** 112 113| Name| Description| 114| -- | -- | 115| [struct OH_Huks_ParamSet](capi-hukstypeapi-oh-huks-paramset.md) **paramSet | Double pointer to the parameter set to build.| 116 117**Returns** 118 119| Type| Description| 120| -- | -- | 121| [struct OH_Huks_Result](capi-hukstypeapi-oh-huks-result.md) | Possible error codes (**errorCode**):<br> OH_HUKS_SUCCESS = 0: Operation successful.<br> OH_HUKS_ERR_CODE_ILLEGAL_ARGUMENT = 401: **paramSet** is invalid.<br> OH_HUKS_ERR_CODE_INSUFFICIENT_MEMORY = 12000014: Insufficient memory.| 122 123### OH_Huks_FreeParamSet() 124 125``` 126void OH_Huks_FreeParamSet(struct OH_Huks_ParamSet **paramSet) 127``` 128 129**Description** 130 131Frees a parameter set. 132 133**Since**: 9 134 135 136**Parameters** 137 138| Name| Description| 139| -- | -- | 140| [struct OH_Huks_ParamSet](capi-hukstypeapi-oh-huks-paramset.md) **paramSet | Pointer to the parameter set to free.| 141 142### OH_Huks_CopyParamSet() 143 144``` 145struct OH_Huks_Result OH_Huks_CopyParamSet(const struct OH_Huks_ParamSet *fromParamSet,uint32_t fromParamSetSize, struct OH_Huks_ParamSet **paramSet) 146``` 147 148**Description** 149 150Copies a parameter set (deep copy). 151 152**Since**: 9 153 154 155**Parameters** 156 157| Name| Description| 158| -- | -- | 159| [const struct OH_Huks_ParamSet](capi-hukstypeapi-oh-huks-paramset.md) *fromParamSet | Pointer to the parameter set to copy.| 160| uint32_t fromParamSetSize | Size of the memory occupied by the copied parameter set.| 161| [struct OH_Huks_ParamSet](capi-hukstypeapi-oh-huks-paramset.md) **paramSet | Double pointer to the new parameter set generated.| 162 163**Returns** 164 165| Type| Description| 166| -- | -- | 167| [struct OH_Huks_Result](capi-hukstypeapi-oh-huks-result.md) | Possible error codes (**errorCode**):<br> OH_HUKS_SUCCESS = 0: Operation successful.<br> OH_HUKS_ERR_CODE_ILLEGAL_ARGUMENT = 401: **fromParamSet**, **fromParamSetSize**, or **paramSet** is invalid.<br> OH_HUKS_ERR_CODE_INSUFFICIENT_MEMORY = 12000014: Insufficient memory.| 168 169### OH_Huks_GetParam() 170 171``` 172struct OH_Huks_Result OH_Huks_GetParam(const struct OH_Huks_ParamSet *paramSet, uint32_t tag,struct OH_Huks_Param **param) 173``` 174 175**Description** 176 177Obtains a parameter from a parameter set. 178 179**Since**: 9 180 181 182**Parameters** 183 184| Name| Description| 185| -- | -- | 186| [const struct OH_Huks_ParamSet](capi-hukstypeapi-oh-huks-paramset.md) *paramSet | Pointer to the parameter set to check.| 187| uint32_t tag | Name of the parameter to obtain.| 188| [struct OH_Huks_Param](capi-hukstypeapi-oh-huks-param.md) **param | Double pointer to the obtained parameter.| 189 190**Returns** 191 192| Type| Description| 193| -- | -- | 194| [struct OH_Huks_Result](capi-hukstypeapi-oh-huks-result.md) | Possible error codes (**errorCode**):<br> OH_HUKS_SUCCESS = 0: Operation successful.<br> OH_HUKS_ERR_CODE_ILLEGAL_ARGUMENT = 401: **paramSet** or **param** is invalid, or **param** is not in **paramSet**.| 195 196### OH_Huks_FreshParamSet() 197 198``` 199struct OH_Huks_Result OH_Huks_FreshParamSet(struct OH_Huks_ParamSet *paramSet, bool isCopy) 200``` 201 202**Description** 203 204Refreshes the [OH_Huks_Blob](capi-hukstypeapi-oh-huks-blob.md) data in the parameter set. 205 206**Since**: 9 207 208 209**Parameters** 210 211| Name| Description| 212| -- | -- | 213| [struct OH_Huks_ParamSet](capi-hukstypeapi-oh-huks-paramset.md) *paramSet | Pointer to the parameter set to check.| 214| bool isCopy | If the value is **true**, the address of the [OH_Huks_Blob](capi-hukstypeapi-oh-huks-blob.md) data is refreshed and copied to the parameter set. If the value is **false**, only the address of the [OH_Huks_Blob](capi-hukstypeapi-oh-huks-blob.md) data is refreshed.| 215 216**Returns** 217 218| Type| Description| 219| -- | -- | 220| [struct OH_Huks_Result](capi-hukstypeapi-oh-huks-result.md) | Possible error codes (**errorCode**):<br> OH_HUKS_SUCCESS = 0: Operation successful.<br> OH_HUKS_ERR_CODE_ILLEGAL_ARGUMENT = 401: **paramSet** is invalid.<br> OH_HUKS_ERR_CODE_INSUFFICIENT_MEMORY = 12000014: Insufficient memory.| 221 222### OH_Huks_IsParamSetTagValid() 223 224``` 225struct OH_Huks_Result OH_Huks_IsParamSetTagValid(const struct OH_Huks_ParamSet *paramSet) 226``` 227 228**Description** 229 230Checks whether the parameters in a parameter set are valid. 231 232**Since**: 9 233 234 235**Parameters** 236 237| Name| Description| 238| -- | -- | 239| [const struct OH_Huks_ParamSet](capi-hukstypeapi-oh-huks-paramset.md) *paramSet | Pointer to the parameter set to check.| 240 241**Returns** 242 243| Type| Description| 244| -- | -- | 245| [struct OH_Huks_Result](capi-hukstypeapi-oh-huks-result.md) | Possible error codes (**errorCode**):<br> OH_HUKS_SUCCESS = 0: All parameters in **paramSet** are valid.<br> OH_HUKS_ERR_CODE_ILLEGAL_ARGUMENT = 401: **paramSet** is invalid, or the parameter set contains invalid, duplicate, or incorrect tags.| 246 247### OH_Huks_IsParamSetValid() 248 249``` 250struct OH_Huks_Result OH_Huks_IsParamSetValid(const struct OH_Huks_ParamSet *paramSet, uint32_t size) 251``` 252 253**Description** 254 255Checks whether a parameter set is of the valid size. 256 257**Since**: 9 258 259 260**Parameters** 261 262| Name| Description| 263| -- | -- | 264| [const struct OH_Huks_ParamSet](capi-hukstypeapi-oh-huks-paramset.md) *paramSet | Pointer to the parameter set to check.| 265| uint32_t size | Memory size occupied by the parameter set.| 266 267**Returns** 268 269| Type| Description| 270| -- | -- | 271| [struct OH_Huks_Result](capi-hukstypeapi-oh-huks-result.md) | Possible error codes (**errorCode**):<br> OH_HUKS_SUCCESS = 0: The size of the parameter set is valid.<br> OH_HUKS_ERR_CODE_ILLEGAL_ARGUMENT = 401: **paramSet** is invalid.| 272 273### OH_Huks_CheckParamMatch() 274 275``` 276struct OH_Huks_Result OH_Huks_CheckParamMatch(const struct OH_Huks_Param *baseParam, const struct OH_Huks_Param *param) 277``` 278 279**Description** 280 281Checks whether two parameters are the same. 282 283**Since**: 9 284 285 286**Parameters** 287 288| Name| Description| 289| -- | -- | 290| [const struct OH_Huks_Param](capi-hukstypeapi-oh-huks-param.md) *baseParam | Pointer to the first parameter to compare.| 291| [const struct OH_Huks_Param](capi-hukstypeapi-oh-huks-param.md) *param | Pointer to the second parameter to compare.| 292 293**Returns** 294 295| Type| Description| 296| -- | -- | 297| [struct OH_Huks_Result](capi-hukstypeapi-oh-huks-result.md) | Possible error codes (**errorCode**):<br> OH_HUKS_SUCCESS = 0: The two parameters to be compared are the same.<br> OH_HUKS_ERR_CODE_ILLEGAL_ARGUMENT = 401: One of the parameter sets is invalid, the parameters do not match,<br> or there is an invalid tag internally.| 298 299### OH_Huks_FreeKeyAliasSet() 300 301``` 302void OH_Huks_FreeKeyAliasSet(struct OH_Huks_KeyAliasSet *keyAliasSet) 303``` 304 305**Description** 306 307Frees a parameter set. 308 309**Since**: 20 310 311 312**Parameters** 313 314| Name| Description| 315| -- | -- | 316| [struct OH_Huks_KeyAliasSet](capi-hukstypeapi-oh-huks-keyaliasset.md) *keyAliasSet | Pointer to the parameter set to free.| 317