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 Declares the APIs used to access the HUKS. 36 * 37 * @since 9 38 * @version 1.0 39 */ 40 41 #include "native_huks_type.h" 42 43 #ifdef __cplusplus 44 extern "C" { 45 #endif 46 47 /** 48 * @brief Obtains the current HUKS SDK version. 49 * 50 * @param sdkVersion Indicates the pointer to the SDK version (in string format) obtained. 51 * return Returns {@link OH_Huks_ErrCode#OH_HUKS_SUCCESS} if the operation is successful; 52 * returns an error code otherwise. 53 * @since 9 54 * @version 1.0 55 */ 56 struct OH_Huks_Result OH_Huks_GetSdkVersion(struct OH_Huks_Blob *sdkVersion); 57 58 /** 59 * @brief Generates a key. 60 * 61 * @param keyAlias Indicates the pointer to the alias of the key to generate. 62 * The alias must be unique in the process of the service. Otherwise, the key will be overwritten. 63 * @param paramSetIn Indicates the pointer to the parameter set for generating the key. 64 * @param paramSetOut Indicates the pointer to a temporary key generated. If the generated key is 65 * not of a temporary type, this parameter is a null pointer. 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_GenerateKeyItem(const struct OH_Huks_Blob *keyAlias, 72 const struct OH_Huks_ParamSet *paramSetIn, struct OH_Huks_ParamSet *paramSetOut); 73 74 /** 75 * @brief Imports a key in plaintext. 76 * 77 * @param keyAlias Indicates the pointer to the alias of the key to import. 78 * The alias must be unique in the process of the service. Otherwise, the key will be overwritten. 79 * @param paramSet Indicates the pointer to the parameters of the key to import. 80 * @param key Indicates the pointer to the key to import. The key must be in the format required by the HUKS. 81 * For details, see {@link HuksTypeApi}. 82 * @return Returns {@link OH_Huks_ErrCode#OH_HUKS_SUCCESS} if the operation is successful; 83 * returns an error code otherwise. 84 * @since 9 85 * @version 1.0 86 */ 87 struct OH_Huks_Result OH_Huks_ImportKeyItem(const struct OH_Huks_Blob *keyAlias, 88 const struct OH_Huks_ParamSet *paramSet, const struct OH_Huks_Blob *key); 89 90 /** 91 * @brief Imports a wrapped key. 92 * 93 * @param keyAlias Indicates the pointer to the alias of the key to import. 94 * The alias must be unique in the process of the service. Otherwise, the key will be overwritten. 95 * @param wrappingKeyAlias Indicates the pointer to the alias of the wrapping key, 96 * which is obtained through key agreement and used to decrypt the key to import. 97 * @param paramSet Indicates the pointer to the parameters of the wrapped key to import. 98 * @param wrappedKeyData Indicates the pointer to the wrapped key to import. 99 * The key must be in the format required by the HUKS. For details, see {@link OH_Huks_AlgSuite}. 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_ImportWrappedKeyItem(const struct OH_Huks_Blob *keyAlias, 106 const struct OH_Huks_Blob *wrappingKeyAlias, const struct OH_Huks_ParamSet *paramSet, 107 const struct OH_Huks_Blob *wrappedKeyData); 108 109 /** 110 * @brief Exports a public key. 111 * 112 * @param keyAlias Indicates the pointer to the alias of the public key to export. 113 * The alias must be the same as the alias for the key generated. 114 * @param paramSet Indicates the pointer to the parameters required for exporting the public key. 115 * @param key Indicates the pointer to the public key exported. 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_ExportPublicKeyItem(const struct OH_Huks_Blob *keyAlias, 122 const struct OH_Huks_ParamSet *paramSet, struct OH_Huks_Blob *key); 123 124 /** 125 * @brief Deletes a key. 126 * 127 * @param keyAlias Indicates the pointer to the alias of the key to delete. 128 * The alias must be the same as the alias for the key generated. 129 * @param paramSet Indicates the pointer to the parameters required for deleting the key. 130 * By default, this parameter is a null pointer. 131 * @return Returns {@link OH_Huks_ErrCode#OH_HUKS_SUCCESS} if the operation is successful; 132 * returns an error code otherwise. 133 * @since 9 134 * @version 1.0 135 */ 136 struct OH_Huks_Result OH_Huks_DeleteKeyItem(const struct OH_Huks_Blob *keyAlias, 137 const struct OH_Huks_ParamSet *paramSet); 138 139 /** 140 * @brief Obtains the attributes of a key. 141 * 142 * @param keyAlias Indicates the pointer to the alias of the target key. 143 * @param paramSetIn Indicates the pointer to the attribute tag required for 144 * obtaining the attributes. By default, this parameter is a null pointer. 145 * @param paramSetOut Indicates the pointer to the attributes obtained. 146 * @return Returns {@link OH_Huks_ErrCode#OH_HUKS_SUCCESS} if the operation is successful; 147 * returns an error code otherwise. 148 * @since 9 149 * @version 1.0 150 */ 151 struct OH_Huks_Result OH_Huks_GetKeyItemParamSet(const struct OH_Huks_Blob *keyAlias, 152 const struct OH_Huks_ParamSet *paramSetIn, struct OH_Huks_ParamSet *paramSetOut); 153 154 /** 155 * @brief Checks whether a key exists. 156 * 157 * @param keyAlias Indicates the pointer to the alias of the target key. 158 * @param paramSet Indicates the pointer to the attribute tag required for checking the key. 159 * By default, this parameter is a null pointer. 160 * @return Returns {@link OH_Huks_ErrCode#OH_HUKS_SUCCESS} if the key exists. 161 * @return Returns {@link OH_Huks_ErrCode#OH_HUKS_ERR_CODE_ITEM_NOT_EXIST} if the key does not exist. 162 * @return Returns any other error code for other cases. 163 * @since 9 164 * @version 1.0 165 */ 166 struct OH_Huks_Result OH_Huks_IsKeyItemExist(const struct OH_Huks_Blob *keyAlias, 167 const struct OH_Huks_ParamSet *paramSet); 168 169 /** 170 * @brief Obtain the key certificate chain. 171 * 172 * @param keyAlias Indicates the pointer to the alias of the target key. 173 * @param paramSet Indicates the pointer to the parameters required for obtaining the key certificate. 174 * @param certChain Indicates the pointer to the key certificate chain obtained. 175 * @return Returns {@link OH_Huks_ErrCode#OH_HUKS_SUCCESS} if the operation is successful; 176 * returns an error code otherwise. 177 * @since 9 178 * @version 1.0 179 */ 180 struct OH_Huks_Result OH_Huks_AttestKeyItem(const struct OH_Huks_Blob *keyAlias, 181 const struct OH_Huks_ParamSet *paramSet, struct OH_Huks_CertChain *certChain); 182 183 /** 184 * @brief Initializes the key session interface and obtains a handle (mandatory) and challenge value (optional). 185 * 186 * @param keyAlias Indicates the pointer to the alias of the target key. 187 * @param paramSet Indicates the pointer to the parameters for the initialization operation. 188 * @param handle Indicates the pointer to the handle of the key session obtained. 189 * This handle is required for subsequent operations, including {@link OH_Huks_UpdateSession}, 190 * {@link OH_Huks_FinishSession}, and {@link OH_Huks_AbortSession}. 191 * @param challenge Indicates the pointer to the challenge value obtained. 192 * @return Returns {@link OH_Huks_ErrCode#OH_HUKS_SUCCESS} if the operation is successful; 193 * returns an error code otherwise. 194 * @since 9 195 * @version 1.0 196 * @see OH_Huks_UpdateSession 197 * @see OH_Huks_FinishSession 198 * @see OH_Huks_AbortSession 199 */ 200 struct OH_Huks_Result OH_Huks_InitSession(const struct OH_Huks_Blob *keyAlias, 201 const struct OH_Huks_ParamSet *paramSet, struct OH_Huks_Blob *handle, struct OH_Huks_Blob *challenge); 202 203 /** 204 * @brief Adds data by segment for the key operation, performs the related key operation, 205 * and outputs the processed data. 206 * 207 * @param handle Indicates the pointer to the key session handle, which is generated by {@link OH_Huks_InitSession}. 208 * @param paramSet Indicates the pointer to the parameters required for the key operation. 209 * @param inData Indicates the pointer to the data to be processed. 210 * This API can be called multiples time to process large data by segment. 211 * @param outData Indicates the pointer to the output data. 212 * @return Returns {@link OH_Huks_ErrCode#OH_HUKS_SUCCESS} if the operation is successful; 213 * returns an error code otherwise. 214 * @since 9 215 * @version 1.0 216 * @see OH_Huks_InitSession 217 * @see OH_Huks_FinishSession 218 * @see OH_Huks_AbortSession 219 */ 220 struct OH_Huks_Result OH_Huks_UpdateSession(const struct OH_Huks_Blob *handle, 221 const struct OH_Huks_ParamSet *paramSet, const struct OH_Huks_Blob *inData, struct OH_Huks_Blob *outData); 222 223 /** 224 * @brief Ends the key session. 225 * 226 * @param handle Indicates the pointer to the key session handle, which is generated by {@link OH_Huks_InitSession}. 227 * @param paramSet Indicates the pointer to the parameters required for the key operation. 228 * @param inData Indicates the pointer to the data to be processed. 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_UpdateSession 236 * @see OH_Huks_AbortSession 237 */ 238 struct OH_Huks_Result OH_Huks_FinishSession(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 Aborts a 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 aborting the key session. 246 * By default, this parameter is a null pointer. 247 * @return Returns {@link OH_Huks_ErrCode#OH_HUKS_SUCCESS} if the operation is successful; 248 * returns an error code otherwise. 249 * @since 9 250 * @version 1.0 251 * @see OH_Huks_InitSession 252 * @see OH_Huks_UpdateSession 253 * @see OH_Huks_FinishSession 254 */ 255 struct OH_Huks_Result OH_Huks_AbortSession(const struct OH_Huks_Blob *handle, 256 const struct OH_Huks_ParamSet *paramSet); 257 258 #ifdef __cplusplus 259 } 260 #endif 261 262 /** @} */ 263 #endif /* NATIVE_HUKS_API_H */ 264