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_API_H 17 #define NATIVE_HUKS_API_H 18 19 /** 20 * @addtogroup HuksKeyApi 21 * @{ 22 * 23 * @brief Describes the OpenHarmony Universal KeyStore (HUKS) capabilities, including key management and 24 * cryptography operations, provided for applications. 25 * The keys managed by HUKS can be imported by applications or generated by calling the HUKS APIs. 26 * 27 * @syscap SystemCapability.Security.Huks 28 * @since 9 29 * @version 1.0 30 */ 31 32 /** 33 * @file native_huks_api.h 34 * 35 * @brief Defines the Universal Keystore Kit APIs. 36 * 37 * include "huks/include/native_huks_type.h" 38 * @kit Universal Keystore Kit 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 Obtains the current HUKS SDK version. 51 * 52 * @param sdkVersion Indicates the pointer to the SDK version (in string format) obtained. 53 * return Returns {@link OH_Huks_ErrCode#OH_HUKS_SUCCESS} if the operation is successful; 54 * returns an error code otherwise. 55 * @since 9 56 * @version 1.0 57 */ 58 struct OH_Huks_Result OH_Huks_GetSdkVersion(struct OH_Huks_Blob *sdkVersion); 59 60 /** 61 * @brief Generates a key. 62 * 63 * @param keyAlias Indicates the pointer to the alias of the key to generate. 64 * The alias must be unique in the process of the service. Otherwise, the key will be overwritten. 65 * @param paramSetIn Indicates the pointer to the parameter set for generating the key. 66 * @param paramSetOut Indicates the pointer to a temporary key generated. If the generated key is 67 * not of a temporary type, this parameter is a null pointer. 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_GenerateKeyItem(const struct OH_Huks_Blob *keyAlias, 74 const struct OH_Huks_ParamSet *paramSetIn, struct OH_Huks_ParamSet *paramSetOut); 75 76 /** 77 * @brief Imports a key in plaintext. 78 * 79 * @param keyAlias Indicates the pointer to the alias of the key to import. 80 * The alias must be unique in the process of the service. Otherwise, the key will be overwritten. 81 * @param paramSet Indicates the pointer to the parameters of the key to import. 82 * @param key Indicates the pointer to the key to import. The key must be in the format required by the HUKS. 83 * For details, see {@link HuksTypeApi}. 84 * @return Returns {@link OH_Huks_ErrCode#OH_HUKS_SUCCESS} if the operation is successful; 85 * returns an error code otherwise. 86 * @since 9 87 * @version 1.0 88 */ 89 struct OH_Huks_Result OH_Huks_ImportKeyItem(const struct OH_Huks_Blob *keyAlias, 90 const struct OH_Huks_ParamSet *paramSet, const struct OH_Huks_Blob *key); 91 92 /** 93 * @brief Imports a wrapped key. 94 * 95 * @param keyAlias Indicates the pointer to the alias of the key to import. 96 * The alias must be unique in the process of the service. Otherwise, the key will be overwritten. 97 * @param wrappingKeyAlias Indicates the pointer to the alias of the wrapping key, 98 * which is obtained through key agreement and used to decrypt the key to import. 99 * @param paramSet Indicates the pointer to the parameters of the wrapped key to import. 100 * @param wrappedKeyData Indicates the pointer to the wrapped key to import. 101 * The key must be in the format required by the HUKS. For details, see {@link OH_Huks_AlgSuite}. 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_ImportWrappedKeyItem(const struct OH_Huks_Blob *keyAlias, 108 const struct OH_Huks_Blob *wrappingKeyAlias, const struct OH_Huks_ParamSet *paramSet, 109 const struct OH_Huks_Blob *wrappedKeyData); 110 111 /** 112 * @brief Exports a public key. 113 * 114 * @param keyAlias Indicates the pointer to the alias of the public key to export. 115 * The alias must be the same as the alias for the key generated. 116 * @param paramSet Indicates the pointer to the parameters required for exporting the public key. 117 * @param key Indicates the pointer to the public key exported. 118 * @return Returns {@link OH_Huks_ErrCode#OH_HUKS_SUCCESS} if the operation is successful; 119 * returns an error code otherwise. 120 * @since 9 121 * @version 1.0 122 */ 123 struct OH_Huks_Result OH_Huks_ExportPublicKeyItem(const struct OH_Huks_Blob *keyAlias, 124 const struct OH_Huks_ParamSet *paramSet, struct OH_Huks_Blob *key); 125 126 /** 127 * @brief Deletes a key. 128 * 129 * @param keyAlias Indicates the pointer to the alias of the key to delete. 130 * The alias must be the same as the alias for the key generated. 131 * @param paramSet Indicates the pointer to the parameters required for deleting the key. 132 * By default, this parameter is a null pointer. 133 * @return Returns {@link OH_Huks_ErrCode#OH_HUKS_SUCCESS} if the operation is successful; 134 * returns an error code otherwise. 135 * @since 9 136 * @version 1.0 137 */ 138 struct OH_Huks_Result OH_Huks_DeleteKeyItem(const struct OH_Huks_Blob *keyAlias, 139 const struct OH_Huks_ParamSet *paramSet); 140 141 /** 142 * @brief Obtains the attributes of a key. 143 * 144 * @param keyAlias Indicates the pointer to the alias of the target key. 145 * @param paramSetIn Indicates the pointer to the attribute tag required for 146 * obtaining the attributes. By default, this parameter is a null pointer. 147 * @param paramSetOut Indicates the pointer to the attributes obtained. 148 * @return Returns {@link OH_Huks_ErrCode#OH_HUKS_SUCCESS} if the operation is successful; 149 * returns an error code otherwise. 150 * @since 9 151 * @version 1.0 152 */ 153 struct OH_Huks_Result OH_Huks_GetKeyItemParamSet(const struct OH_Huks_Blob *keyAlias, 154 const struct OH_Huks_ParamSet *paramSetIn, struct OH_Huks_ParamSet *paramSetOut); 155 156 /** 157 * @brief Checks whether a key exists. 158 * 159 * @param keyAlias Indicates the pointer to the alias of the target key. 160 * @param paramSet Indicates the pointer to the attribute tag required for checking the key. 161 * By default, this parameter is a null pointer. 162 * @return Returns {@link OH_Huks_ErrCode#OH_HUKS_SUCCESS} if the key exists. 163 * @return Returns {@link OH_Huks_ErrCode#OH_HUKS_ERR_CODE_ITEM_NOT_EXIST} if the key does not exist. 164 * @return Returns any other error code for other cases. 165 * @since 9 166 * @version 1.0 167 */ 168 struct OH_Huks_Result OH_Huks_IsKeyItemExist(const struct OH_Huks_Blob *keyAlias, 169 const struct OH_Huks_ParamSet *paramSet); 170 171 /** 172 * @brief Obtain the key certificate chain. 173 * 174 * @permission ohos.permission.ATTEST_KEY 175 * @param keyAlias Indicates the pointer to the alias of the target key. 176 * @param paramSet Indicates the pointer to the parameters required for obtaining the key certificate. 177 * @param certChain Indicates the pointer to the key certificate chain obtained. 178 * @return Returns {@link OH_Huks_ErrCode#OH_HUKS_SUCCESS} if the operation is successful; 179 * returns an error code otherwise. 180 * @since 9 181 * @version 1.0 182 */ 183 struct OH_Huks_Result OH_Huks_AttestKeyItem(const struct OH_Huks_Blob *keyAlias, 184 const struct OH_Huks_ParamSet *paramSet, struct OH_Huks_CertChain *certChain); 185 186 /** 187 * @brief Obtain the key certificate chain. 188 * 189 * @param keyAlias Indicates the pointer to the alias of the target key. 190 * @param paramSet Indicates the pointer to the parameters required for obtaining the key certificate. 191 * @param certChain Indicates the pointer to the key certificate chain obtained. 192 * @return Returns {@link OH_Huks_ErrCode#OH_HUKS_SUCCESS} if the operation is successful; 193 * returns an error code otherwise. 194 * @since 11 195 * @version 1.0 196 * @note this is a networking duration interface caller need to get the certChain in asynchronous thread 197 */ 198 struct OH_Huks_Result OH_Huks_AnonAttestKeyItem(const struct OH_Huks_Blob *keyAlias, 199 const struct OH_Huks_ParamSet *paramSet, struct OH_Huks_CertChain *certChain); 200 201 /** 202 * @brief Initializes the key session interface and obtains a handle (mandatory) and challenge value (optional). 203 * 204 * @param keyAlias Indicates the pointer to the alias of the target key. 205 * @param paramSet Indicates the pointer to the parameters for the initialization operation. 206 * @param handle Indicates the pointer to the handle of the key session obtained. 207 * This handle is required for subsequent operations, including {@link OH_Huks_UpdateSession}, 208 * {@link OH_Huks_FinishSession}, and {@link OH_Huks_AbortSession}. 209 * @param challenge Indicates the pointer to the challenge value obtained. 210 * @return Returns {@link OH_Huks_ErrCode#OH_HUKS_SUCCESS} if the operation is successful; 211 * returns an error code otherwise. 212 * @since 9 213 * @version 1.0 214 * @see OH_Huks_UpdateSession 215 * @see OH_Huks_FinishSession 216 * @see OH_Huks_AbortSession 217 */ 218 struct OH_Huks_Result OH_Huks_InitSession(const struct OH_Huks_Blob *keyAlias, 219 const struct OH_Huks_ParamSet *paramSet, struct OH_Huks_Blob *handle, struct OH_Huks_Blob *token); 220 221 /** 222 * @brief Adds data by segment for the key operation, performs the related key operation, 223 * and outputs the processed data. 224 * 225 * @param handle Indicates the pointer to the key session handle, which is generated by {@link OH_Huks_InitSession}. 226 * @param paramSet Indicates the pointer to the parameters required for the key operation. 227 * @param inData Indicates the pointer to the data to be processed. 228 * This API can be called multiples time to process large data by segment. 229 * @param outData Indicates the pointer to the output data. 230 * @return Returns {@link OH_Huks_ErrCode#OH_HUKS_SUCCESS} if the operation is successful; 231 * returns an error code otherwise. 232 * @since 9 233 * @version 1.0 234 * @see OH_Huks_InitSession 235 * @see OH_Huks_FinishSession 236 * @see OH_Huks_AbortSession 237 */ 238 struct OH_Huks_Result OH_Huks_UpdateSession(const struct OH_Huks_Blob *handle, 239 const struct OH_Huks_ParamSet *paramSet, const struct OH_Huks_Blob *inData, struct OH_Huks_Blob *outData); 240 241 /** 242 * @brief Ends the key session. 243 * 244 * @param handle Indicates the pointer to the key session handle, which is generated by {@link OH_Huks_InitSession}. 245 * @param paramSet Indicates the pointer to the parameters required for the key operation. 246 * @param inData Indicates the pointer to the data to be processed. 247 * @param outData Indicates the pointer to the output data. 248 * @return Returns {@link OH_Huks_ErrCode#OH_HUKS_SUCCESS} if the operation is successful; 249 * returns an error code otherwise. 250 * @since 9 251 * @version 1.0 252 * @see OH_Huks_InitSession 253 * @see OH_Huks_UpdateSession 254 * @see OH_Huks_AbortSession 255 */ 256 struct OH_Huks_Result OH_Huks_FinishSession(const struct OH_Huks_Blob *handle, 257 const struct OH_Huks_ParamSet *paramSet, const struct OH_Huks_Blob *inData, struct OH_Huks_Blob *outData); 258 259 /** 260 * @brief Aborts a key session. 261 * 262 * @param handle Indicates the pointer to the key session handle, which is generated by {@link OH_Huks_InitSession}. 263 * @param paramSet Indicates the pointer to the parameters required for aborting the key session. 264 * By default, this parameter is a null pointer. 265 * @return Returns {@link OH_Huks_ErrCode#OH_HUKS_SUCCESS} if the operation is successful; 266 * returns an error code otherwise. 267 * @since 9 268 * @version 1.0 269 * @see OH_Huks_InitSession 270 * @see OH_Huks_UpdateSession 271 * @see OH_Huks_FinishSession 272 */ 273 struct OH_Huks_Result OH_Huks_AbortSession(const struct OH_Huks_Blob *handle, 274 const struct OH_Huks_ParamSet *paramSet); 275 276 #ifdef __cplusplus 277 } 278 #endif 279 280 /** @} */ 281 #endif /* NATIVE_HUKS_API_H */ 282