1/* 2 * Copyright (c) 2023 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/** 17 * @addtogroup HdfHuks 18 * @{ 19 * 20 * @brief Provides standard driver APIs for OpenHarmony Universal KeyStore (HUKS). 21 * 22 * The HUKS driver APIs define standard interfaces of the HUKS Core and provide 23 * a unified driver interface for the HUKS service. 24 * You can use these APIs to implement key lifecycle management, including 25 * key generation, key import and export, key operations, key access control, 26 * and key attestation. 27 * 28 * @since 4.0 29 */ 30 31 /** 32 * @file IHuks.idl 33 * 34 * @brief Defines the HUKS driver interfaces for key management. 35 * 36 * @since 4.0 37 */ 38 39package ohos.hdi.huks.v1_0; 40 41import ohos.hdi.huks.v1_0.IHuksTypes; 42 43/** 44 * @brief Defines the HUKS driver interfaces for key management. 45 * 46 * @since 4.0 47 * @version 1.0 48 */ 49interface IHuks { 50 /** 51 * @brief Initializes the HUKS driver. 52 * 53 * @return Returns <b>0</b> if the initialization is successful. 54 * @return Returns a non-zero value otherwise. 55 * 56 * @since 4.0 57 * @version 1.0 58 */ 59 ModuleInit(); 60 61 /** 62 * @brief Destroy the HUKS driver, including clear memory, temp key, etc. 63 * 64 * @return Returns <b>0</b> if the destory is successful. 65 * @return Returns a non-zero value otherwise. 66 * 67 * @since 4.0 68 * @version 1.0 69 */ 70 ModuleDestroy(); 71 72 /** 73 * @brief Generates a key and returns the key in ciphertext. 74 * 75 * @param keyAlias Indicates the alias {@link HuksBlob} of the key 76 * to generate. 77 * @param paramSet Indicates the property set {@link HuksParamSet} of the 78 * key to generate. For details about the key property set struct, 79 * see the HUKS Device Development. 80 * @param keyIn Indicates the material {@link HuksBlob} of the key 81 * to generate. This parameter is optional. 82 * @param encKeyOut Indicates the key {@link HuksBlob} generated in 83 * ciphertext. For details about the key material struct, see the 84 * HUKS Device Development. 85 * 86 * @return Returns <b>0</b> if the key is generated. 87 * @return Returns a non-zero value otherwise. 88 * 89 * @since 4.0 90 * @version 1.0 91 */ 92 GenerateKey([in] struct HuksBlob keyAlias,[in] struct HuksParamSet paramSet, 93 [in] struct HuksBlob keyIn, [out] struct HuksBlob encKeyOut); 94 95 /** 96 * @brief Imports a key in plaintext. 97 * 98 * @param keyAlias Indicates the alias {@link HuksBlob} of the key to import. 99 * @param key Indicates the material {@link HuksBlob} in plaintext of the 100 * key to import. For details about the key material struct, see the 101 * HUKS Device Development. 102 * @param paramSet Indicates the property set {@link HuksParamSet} of the 103 * key to import. For details about the key property set struct, see the 104 * HUKS Device Development. 105 * @param encKeyOut Indicates the key {@link HuksBlob} in ciphertext 106 * imported. For details about the key material struct, see the 107 * HUKS Device Development. 108 * 109 * @return Returns <b>0</b> if the key is imported. 110 * @return Returns a non-zero value otherwise. 111 * 112 * @since 4.0 113 * @version 1.0 114 */ 115 ImportKey([in] struct HuksBlob keyAlias, [in] struct HuksBlob key, 116 [in] struct HuksParamSet paramSet, [out] struct HuksBlob encKeyOut); 117 118 /** 119 * @brief Imports an encrypted key. 120 * 121 * @param wrappingKeyAlias Indicates the alias of an intermediate key used 122 * to wrap the key to import. For details, see {@link HuksBlob}. 123 * @param wrappingEncKey Indicates the encrypted intermediate 124 * key {@link HuksBlob}. For details about the key material struct, see the 125 * HUKS Device Development. 126 * @param wrappedKeyData Indicates the encrypted key 127 * material {@link HuksBlob} of the key to import. For details about the 128 * key material struct, see the HUKS Device Development. 129 * @param paramSet Indicates the property set {@link HuksParamSet} of the 130 * key to import. For details about the key property set struct, see the 131 * HUKS Device Development. 132 * @param encKeyOut Indicates the key {@link HuksBlob} in ciphertext 133 * imported. For details about the key material struct, see the 134 * HUKS Device Development. 135 * 136 * @return Returns <b>0</b> if the key is imported. 137 * @return Returns a non-zero value otherwise. 138 * 139 * @since 4.0 140 * @version 1.0 141 */ 142 ImportWrappedKey([in] struct HuksBlob wrappingKeyAlias, [in] struct HuksBlob wrappingEncKey, 143 [in] struct HuksBlob wrappedKeyData, [in] struct HuksParamSet paramSet, [out] struct HuksBlob encKeyOut); 144 145 /** 146 * @brief Exports the public key of a key pair. 147 * 148 * @param encKey Indicates the key pair material {@link HuksBlob} 149 * in ciphertext. For details about the key material struct, see the 150 * HUKS Device Development. 151 * @param paramSet Indicates the property set {@link HuksParamSet} of the 152 * key to export. For details about the key property set struct, see the 153 * HUKS Device Development. 154 * @param keyOut Indicates the public key material {@link HuksBlob} 155 * exported. For details about the key material struct, see the 156 * HUKS Device Development. 157 * 158 * @return Returns <b>0</b> if the public key is exported. 159 * @return Returns a non-zero value otherwise. 160 * 161 * @since 4.0 162 * @version 1.0 163 */ 164 ExportPublicKey([in] struct HuksBlob encKey, [in] struct HuksParamSet paramSet, [out] struct HuksBlob keyOut); 165 166 /** 167 * @brief Initializes a key session, decrypts the key material into memory, 168 * and returns a handle and a token. 169 * 170 * @param encKey Indicates the key material {@link HuksBlob} in ciphertext. 171 * For details about the key material struct, see the HUKS Device Development. 172 * @param paramSet Indicates the parameter set {@link HuksParamSet} used 173 * for the key operation. It contains parameters for the key operation. 174 * @param handle Indicates the key session handle {@link HuksBlob} returned 175 * for subsequent key session operations. 176 * @param token Indicates the key session token {@link HuksBlob}, 177 * which is used for key access control. 178 * 179 * @see Init | Update| Finish 180 * 181 * @return Returns 0 if the session initialization is successful. 182 * @return Returns a non-zero value otherwise. 183 * 184 * @since 4.0 185 * @version 1.0 186 */ 187 Init([in] struct HuksBlob encKey, [in] struct HuksParamSet paramSet, [out]struct HuksBlob handle, 188 [out] struct HuksBlob token); 189 190 /** 191 * @brief Updates (processes or passes in) data by segment based on 192 * the cryptographic algorithm used (for example, in key agreement). 193 * 194 * @param handle Indicates the key session handle {@link HuksBlob}, 195 * which is obtained by {@Init()}. 196 * @param paramSet Indicates the parameter set {@link HuksParamSet} 197 * used for the key operation. For details about the key property set 198 * struct, see the HUKS Device Development. 199 * @param inData Indicates the data segment or parameters {@link HuksBlob}. 200 * @param outData Indicates the output data {@link HuksBlob}. 201 * 202 * @see Init | Finish | Abort 203 * 204 * @return Returns <b>0</b> if the operation is successful. 205 * @return Returns a non-zero value otherwise. 206 * 207 * @since 4.0 208 * @version 1.0 209 */ 210 Update([in] struct HuksBlob handle, [in] struct HuksParamSet paramSet, 211 [in] struct HuksBlob inData, [out] struct HuksBlob outData); 212 213 /** 214 * @brief Finishes the key session operation. 215 * 216 * @param handle Indicates the key session handle {@link HuksBlob}. 217 * @param paramSet Indicates the parameter set {@link HuksParamSet} used 218 * for the key operation. For details about the key property set struct, 219 * see the HUKS Device Development. 220 * @param inData Indicates the data segment or parameters {@link HuksBlob}. 221 * @param outData Indicates the output data {@link HuksBlob}. 222 * 223 * @see Init | Update | Abort 224 * 225 * @return Returns <b>0</b> if the operation is successful. 226 * @return Returns a non-zero value otherwise. 227 * 228 * @since 4.0 229 * @version 1.0 230 */ 231 Finish([in] struct HuksBlob handle, [in] struct HuksParamSet paramSet, 232 [in] struct HuksBlob inData, [out] struct HuksBlob outData); 233 234 /** 235 * @brief Aborts a key session and releases the data used in the session. 236 * The aborted session cannot be operated. 237 * 238 * @param handle Indicates the key session handle {@link HuksBlob}. 239 * @param paramSet Indicates the parameter set {@link HuksParamSet} used 240 * for the key operation. For details about the key property set struct, 241 * see the HUKS Device Development. 242 * 243 * @see Init | Update | Finish 244 * 245 * @return Returns <b>0</b> if the operation is successful. 246 * @return Returns a non-zero value otherwise. 247 * 248 * @since 4.0 249 * @version 1.0 250 */ 251 Abort([in] struct HuksBlob handle, [in] struct HuksParamSet paramSet); 252 253 /** 254 * @brief Checks the key validity (integrity of the key and its properties). 255 * 256 * @param paramSet Indicates the parameter set {@link HuksParamSet} for 257 * checking the key validity. For details about the key property set struct, 258 * see the HUKS Device Development. 259 * @param encKey Indicates the key material {@link HuksBlob} in ciphertext 260 * to check. For details about the key material struct, see 261 * the HUKS Device Development. 262 * 263 * @return Returns <b>0</b> if the key material is valid. 264 * @return Returns a non-zero value otherwise. 265 * 266 * @since 4.0 267 * @version 1.0 268 */ 269 CheckKeyValidity([in] struct HuksParamSet paramSet, [in] struct HuksBlob encKey); 270 271 /** 272 * @brief Obtains the certificate chain for the given key. 273 * 274 * @param encKey Indicates the key material {@link HuksBlob} in ciphertext. 275 * For details about the key material struct, see the HUKS Device Development. 276 * @param paramSet Indicates the parameters {@link HuksParamSet} used to 277 * obtain the certificate chain. For details about the key property 278 * set struct, see the HUKS Device Development. 279 * @param certChain Indicates the certificate chain {@link HuksBlob} 280 * obtained. For details about the certificate chain struct, see the 281 * HUKS Device Development. 282 * 283 * @return Returns <b>0</b> if the certificate chain is obtained. 284 * @return Returns a non-zero value otherwise. 285 * 286 * @since 4.0 287 * @version 1.0 288 */ 289 AttestKey([in] struct HuksBlob encKey, [in] struct HuksParamSet paramSet, [out] struct HuksBlob certChain); 290 291 /** 292 * @brief Generates a random number. 293 * 294 * @param paramSet Indicates the parameters {@link HuksParamSet} used to 295 * generate a random number. For details about the key property set struct, 296 * see the HUKS Device Development. 297 * @param random Indicates the random number {@link HuksBlob} generated. 298 * 299 * @return Returns <b>0</b> if a random number is generated. 300 * @return Returns a non-zero value otherwise. 301 * 302 * @since 4.0 303 * @version 1.0 304 */ 305 GenerateRandom([in] struct HuksParamSet paramSet, [out]struct HuksBlob random); 306 307 /** 308 * @brief Generates a signature for data using a key. 309 * 310 * @param encKey Indicates the key material {@link HuksBlob} in ciphertext. 311 * For details about the key material struct, see the HUKS Device Development. 312 * @param paramSet Indicates the parameters {@link HuksParamSet} used for signing. 313 * For details about the key property set struct, see the HUKS Device Development. 314 * @param srcData Indicates the data {@link HuksBlob} to be signed. 315 * @param signature Indicates the signature {@link HuksBlob} generated. 316 * 317 * @return Returns <b>0</b> if a signature is generated. 318 * @return Returns a non-zero value otherwise. 319 * 320 * @since 4.0 321 * @version 1.0 322 */ 323 Sign([in] struct HuksBlob encKey, [in] struct HuksParamSet paramSet, [in] struct HuksBlob srcData, 324 [out]struct HuksBlob signature); 325 326 /** 327 * @brief Verifies a signature. 328 * 329 * @param encKey Indicates the key material {@link HuksBlob} in ciphertext. 330 * For details about the key material struct, see the HUKS Device Development. 331 * @param paramSet Indicates the parameters {@link HuksParamSet} used for 332 * signature verification. For details about the key property set struct, 333 * see the HUKS Device Development. 334 * @param srcData Indicates the data {@link HuksBlob} whose signature is 335 * to be verified. 336 * @param signature Indicates the signature {@link HuksBlob} to verify. 337 * 338 * @return Returns <b>0</b> if the operation is successful. 339 * @return Returns a non-zero value otherwise. 340 * 341 * @since 4.0 342 * @version 1.0 343 */ 344 Verify([in] struct HuksBlob encKey, [in] struct HuksParamSet paramSet, [in] struct HuksBlob srcData, 345 [in] struct HuksBlob signature); 346 347 /** 348 * @brief Encrypts data using a key. 349 * 350 * @param encKey Indicates the key material {@link HuksBlob} in ciphertext. 351 * For details about the key material struct, see the HUKS Device Development. 352 * @param paramSet Indicates the parameters {@link HuksParamSet} used for 353 * encryption. For details about the key property set struct, see the 354 * HUKS Device Development. 355 * @param plainText Indicates the data {@link HuksBlob} to encrypt. 356 * @param cipherText indicates the data {@link HuksBlob} in ciphertext. 357 * 358 * @return Returns <b>0</b> if the operation is successful. 359 * @return Returns a non-zero value otherwise. 360 * 361 * @since 4.0 362 * @version 1.0 363 */ 364 Encrypt([in] struct HuksBlob encKey, [in] struct HuksParamSet paramSet, [in] struct HuksBlob plainText, 365 [out] struct HuksBlob cipherText); 366 367 /** 368 * @brief Decrypts data using a key. 369 * 370 * @param encKey Indicates the key material {@link HuksBlob} in ciphertext. 371 * For details about the key material struct, see the HUKS Device Development. 372 * @param paramSet Indicates the parameters {@link HuksParamSet} used for 373 * decryption. For details about the key property set struct, see the 374 * HUKS Device Development. 375 * @param cipherText indicates the data {@link HuksBlob} in ciphertext to decrypt. 376 * @param plainText Indicates the decrypted data {@link HuksBlob} in plaintext. 377 * 378 * @return Returns <b>0</b> if the operation is successful. 379 * @return Returns a non-zero value otherwise. 380 * 381 * @since 4.0 382 * @version 1.0 383 */ 384 Decrypt([in] struct HuksBlob encKey, [in] struct HuksParamSet paramSet, [in] struct HuksBlob cipherText, 385 [out] struct HuksBlob plainText); 386 387 /** 388 * @brief Performs key agreement using a private key stored in the HUKS 389 * and the public key of the service. 390 * 391 * @param paramSet Indicates the parameters {@link HuksParamSet} used 392 * for key agreement. 393 * @param encPrivateKey Indicates the key pair material {@link HuksBlob} 394 * stored in the HUKS. For details about the key material struct, see the 395 * HUKS Device Development. 396 * @param peerPublicKey Indicates the public key {@link HuksBlob} used 397 * for key agreement. 398 * @param agreedKey Indicates the key {@link HuksBlob} in plaintext obtained 399 * after key agreement. 400 * 401 * @return Returns <b>0</b> if the operation is successful. 402 * @return Returns a non-zero value otherwise. 403 * 404 * @since 4.0 405 * @version 1.0 406 */ 407 AgreeKey([in] struct HuksParamSet paramSet, [in] struct HuksBlob encPrivateKey, [in] struct HuksBlob peerPublicKey, 408 [out] struct HuksBlob agreedKey); 409 410 /** 411 * @brief Derives a key from a key stored in the HUKS. 412 * 413 * @param paramSet Indicates the parameters {@link HuksParamSet} used for 414 * key derivation. For details about the key property set struct, see the 415 * HUKS Device Development. 416 * @param encKdfKey Indicates the key material {@link HuksBlob} stored 417 * in the HUKS. For details about the key material struct, see the 418 * HUKS Device Development. 419 * @param derivedKey Indicates the derived key {@link HuksBlob} in plaintext. 420 * 421 * @return Returns <b>0</b> if the operation is successful. 422 * @return Returns a non-zero value otherwise. 423 * 424 * @since 4.0 425 * @version 1.0 426 */ 427 DeriveKey([in] struct HuksParamSet paramSet, [in] struct HuksBlob encKdfKey, [out] struct HuksBlob derivedKey); 428 429 /** 430 * @brief Generates a message authentication code (MAC) using a key 431 * stored in the HUKS. 432 * 433 * @param encKey Indicates the key material {@link HuksBlob} in ciphertext. 434 * For details about the key material struct, see the HUKS Device Development. 435 * @param paramSet Indicates the parameters {@link HuksParamSet} used for 436 * generating a MAC. For details about the key property set struct, see the 437 * HUKS Device Development. 438 * @param srcData Indicates the data {@link HuksBlob} used to generate a MAC. 439 * @param mac Indicates the MAC {@link HuksBlob} generated. 440 * 441 * @return Returns <b>0</b> if the operation is successful. 442 * @return Returns a non-zero value otherwise. 443 * 444 * @since 4.0 445 * @version 1.0 446 */ 447 Mac([in] struct HuksBlob encKey, [in] struct HuksParamSet paramSet, [in] struct HuksBlob srcData, 448 [out] struct HuksBlob mac); 449 450 /** 451 * @brief Upgrades a key, including its encryption mode and encryption 452 * material. The HUKS service triggers the upgrade when the key file version 453 * is earlier than the latest version. 454 * 455 * @param encOldKey Indicates the key material {@link HuksBlob} in 456 * ciphertext to upgrade. For details about the key material struct, see the 457 * HUKS Device Development. 458 * @param paramSet Indicates the parameters {@link HuksParamSet} used for 459 * the upgrade. For details about the key property set struct, see the 460 * HUKS Device Development. 461 * @param encNewKey Indicates the key material {@link HuksBlob} in 462 * ciphertext after the upgrade. For details about the key material struct, 463 * see the HUKS Device Development. 464 * 465 * @return Returns <b>0</b> if the operation is successful. 466 * @return Returns a non-zero value otherwise. 467 * 468 * @since 4.0 469 * @version 1.0 470 */ 471 UpgradeKey([in] struct HuksBlob encOldKey, [in] struct HuksParamSet paramSet, [out] struct HuksBlob encNewKey); 472 473 /** 474 * @brief Exports the public key of a chipset key pair. 475 * 476 * @param salt Indicates the salt {@link HuksBlob} used to derive the key 477 * pair of the chipset. 478 * @param scene Indicates the expected chipset decryption 479 * scenario {@link HuksParamSet} of the service. For details about the 480 * key property set struct, see the HUKS Device Development. 481 * @param publicKey Indicates the public key material {@link HuksBlob} 482 * exported, for example, the raw data (32 bytes) of the x-axis and y-axis 483 * values of ECC-P256. 484 * 485 * @return Returns <b>0</b> if the operation is successful. 486 * @return Returns a non-zero value otherwise. 487 * 488 * @since 4.0 489 * @version 1.0 490 */ 491 ExportChipsetPlatformPublicKey([in] struct HuksBlob salt, [in] enum HuksChipsetPlatformDecryptScene scene, 492 [out] struct HuksBlob publicKey); 493} 494/** @} */