diff --git a/huks/bundle.json b/huks/bundle.json index 6e795ca296fe604befdb9e28d7d953d62966fbf9..09c443648a1b66165d073275e19afbc4c9fcd66f 100755 --- a/huks/bundle.json +++ b/huks/bundle.json @@ -29,13 +29,13 @@ }, "build": { "sub_component": [ - "//drivers/interface/huks/v1_0:huks_idl_target" + "//drivers/interface/huks/v1_1:huks_idl_target" ], "test": [ ], "inner_kits": [ { - "name": "//drivers/interface/huks/v1_0:libhuks_proxy_1.0", + "name": "//drivers/interface/huks/v1_1:libhuks_proxy_1.1", "header": { "header_files": [ ], @@ -43,7 +43,7 @@ } }, { - "name": "//drivers/interface/huks/v1_0:huks_idl_headers", + "name": "//drivers/interface/huks/v1_1:huks_idl_headers", "header": { "header_files": [ ], diff --git a/huks/v1_1/BUILD.gn b/huks/v1_1/BUILD.gn new file mode 100644 index 0000000000000000000000000000000000000000..8dc7e0fad151495636a0e106390d4d832417f753 --- /dev/null +++ b/huks/v1_1/BUILD.gn @@ -0,0 +1,26 @@ +# Copyright (c) 2024 Huawei Device Co., Ltd. +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. + +import("//build/config/components/hdi/hdi.gni") +hdi("huks") { + module_name = "drivers_peripheral_huks" + + sources = [ + "IHuks.idl", + "IHuksTypes.idl", + ] + language = "c" + subsystem_name = "hdf" + part_name = "drivers_interface_huks" + mode = "passthrough" +} diff --git a/huks/v1_1/IHuks.idl b/huks/v1_1/IHuks.idl new file mode 100644 index 0000000000000000000000000000000000000000..ca7ee8acd4c4821b15b5f61238cd529de600973e --- /dev/null +++ b/huks/v1_1/IHuks.idl @@ -0,0 +1,520 @@ +/* + * Copyright (c) 2024 Huawei Device Co., Ltd. + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +/** + * @addtogroup HdfHuks + * @{ + * + * @brief Provides standard driver APIs for OpenHarmony Universal KeyStore (HUKS). + * + * The HUKS driver APIs define standard interfaces of the HUKS Core and provide + * a unified driver interface for the HUKS service. + * You can use these APIs to implement key lifecycle management, including + * key generation, key import and export, key operations, key access control, + * and key attestation. + * + * @since 4.0 + */ + + /** + * @file IHuks.idl + * + * @brief Defines the HUKS driver interfaces for key management. + * + * @since 4.0 + */ + +package ohos.hdi.huks.v1_1; + +import ohos.hdi.huks.v1_1.IHuksTypes; + +/** + * @brief Defines the HUKS driver interfaces for key management. + * + * @since 4.0 + * @version 1.0 + */ +interface IHuks { + /** + * @brief Initializes the HUKS driver. + * + * @return Returns 0 if the initialization is successful. + * @return Returns a non-zero value otherwise. + * + * @since 4.0 + * @version 1.0 + */ + ModuleInit(); + + /** + * @brief Destroy the HUKS driver, including clear memory, temp key, etc. + * + * @return Returns 0 if the destory is successful. + * @return Returns a non-zero value otherwise. + * + * @since 4.0 + * @version 1.0 + */ + ModuleDestroy(); + + /** + * @brief Generates a key and returns the key in ciphertext. + * + * @param keyAlias Indicates the alias {@link HuksBlob} of the key + * to generate. + * @param paramSet Indicates the property set {@link HuksParamSet} of the + * key to generate. For details about the key property set struct, + * see the HUKS Device Development. + * @param keyIn Indicates the material {@link HuksBlob} of the key + * to generate. This parameter is optional. + * @param encKeyOut Indicates the key {@link HuksBlob} generated in + * ciphertext. For details about the key material struct, see the + * HUKS Device Development. + * + * @return Returns 0 if the key is generated. + * @return Returns a non-zero value otherwise. + * + * @since 4.0 + * @version 1.0 + */ + GenerateKey([in] struct HuksBlob keyAlias,[in] struct HuksParamSet paramSet, + [in] struct HuksBlob keyIn, [out] struct HuksBlob encKeyOut); + + /** + * @brief Imports a key in plaintext. + * + * @param keyAlias Indicates the alias {@link HuksBlob} of the key to import. + * @param key Indicates the material {@link HuksBlob} in plaintext of the + * key to import. For details about the key material struct, see the + * HUKS Device Development. + * @param paramSet Indicates the property set {@link HuksParamSet} of the + * key to import. For details about the key property set struct, see the + * HUKS Device Development. + * @param encKeyOut Indicates the key {@link HuksBlob} in ciphertext + * imported. For details about the key material struct, see the + * HUKS Device Development. + * + * @return Returns 0 if the key is imported. + * @return Returns a non-zero value otherwise. + * + * @since 4.0 + * @version 1.0 + */ + ImportKey([in] struct HuksBlob keyAlias, [in] struct HuksBlob key, + [in] struct HuksParamSet paramSet, [out] struct HuksBlob encKeyOut); + + /** + * @brief Imports an encrypted key. + * + * @param wrappingKeyAlias Indicates the alias of an intermediate key used + * to wrap the key to import. For details, see {@link HuksBlob}. + * @param wrappingEncKey Indicates the encrypted intermediate + * key {@link HuksBlob}. For details about the key material struct, see the + * HUKS Device Development. + * @param wrappedKeyData Indicates the encrypted key + * material {@link HuksBlob} of the key to import. For details about the + * key material struct, see the HUKS Device Development. + * @param paramSet Indicates the property set {@link HuksParamSet} of the + * key to import. For details about the key property set struct, see the + * HUKS Device Development. + * @param encKeyOut Indicates the key {@link HuksBlob} in ciphertext + * imported. For details about the key material struct, see the + * HUKS Device Development. + * + * @return Returns 0 if the key is imported. + * @return Returns a non-zero value otherwise. + * + * @since 4.0 + * @version 1.0 + */ + ImportWrappedKey([in] struct HuksBlob wrappingKeyAlias, [in] struct HuksBlob wrappingEncKey, + [in] struct HuksBlob wrappedKeyData, [in] struct HuksParamSet paramSet, [out] struct HuksBlob encKeyOut); + + /** + * @brief Exports the public key of a key pair. + * + * @param encKey Indicates the key pair material {@link HuksBlob} + * in ciphertext. For details about the key material struct, see the + * HUKS Device Development. + * @param paramSet Indicates the property set {@link HuksParamSet} of the + * key to export. For details about the key property set struct, see the + * HUKS Device Development. + * @param keyOut Indicates the public key material {@link HuksBlob} + * exported. For details about the key material struct, see the + * HUKS Device Development. + * + * @return Returns 0 if the public key is exported. + * @return Returns a non-zero value otherwise. + * + * @since 4.0 + * @version 1.0 + */ + ExportPublicKey([in] struct HuksBlob encKey, [in] struct HuksParamSet paramSet, [out] struct HuksBlob keyOut); + + /** + * @brief Initializes a key session, decrypts the key material into memory, + * and returns a handle and a token. + * + * @param encKey Indicates the key material {@link HuksBlob} in ciphertext. + * For details about the key material struct, see the HUKS Device Development. + * @param paramSet Indicates the parameter set {@link HuksParamSet} used + * for the key operation. It contains parameters for the key operation. + * @param handle Indicates the key session handle {@link HuksBlob} returned + * for subsequent key session operations. + * @param token Indicates the key session token {@link HuksBlob}, + * which is used for key access control. + * + * @see Init | Update| Finish + * + * @return Returns 0 if the session initialization is successful. + * @return Returns a non-zero value otherwise. + * + * @since 4.0 + * @version 1.0 + */ + Init([in] struct HuksBlob encKey, [in] struct HuksParamSet paramSet, [out]struct HuksBlob handle, + [out] struct HuksBlob token); + + /** + * @brief Updates (processes or passes in) data by segment based on + * the cryptographic algorithm used (for example, in key agreement). + * + * @param handle Indicates the key session handle {@link HuksBlob}, + * which is obtained by {@Init()}. + * @param paramSet Indicates the parameter set {@link HuksParamSet} + * used for the key operation. For details about the key property set + * struct, see the HUKS Device Development. + * @param inData Indicates the data segment or parameters {@link HuksBlob}. + * @param outData Indicates the output data {@link HuksBlob}. + * + * @see Init | Finish | Abort + * + * @return Returns 0 if the operation is successful. + * @return Returns a non-zero value otherwise. + * + * @since 4.0 + * @version 1.0 + */ + Update([in] struct HuksBlob handle, [in] struct HuksParamSet paramSet, + [in] struct HuksBlob inData, [out] struct HuksBlob outData); + + /** + * @brief Finishes the key session operation. + * + * @param handle Indicates the key session handle {@link HuksBlob}. + * @param paramSet Indicates the parameter set {@link HuksParamSet} used + * for the key operation. For details about the key property set struct, + * see the HUKS Device Development. + * @param inData Indicates the data segment or parameters {@link HuksBlob}. + * @param outData Indicates the output data {@link HuksBlob}. + * + * @see Init | Update | Abort + * + * @return Returns 0 if the operation is successful. + * @return Returns a non-zero value otherwise. + * + * @since 4.0 + * @version 1.0 + */ + Finish([in] struct HuksBlob handle, [in] struct HuksParamSet paramSet, + [in] struct HuksBlob inData, [out] struct HuksBlob outData); + + /** + * @brief Aborts a key session and releases the data used in the session. + * The aborted session cannot be operated. + * + * @param handle Indicates the key session handle {@link HuksBlob}. + * @param paramSet Indicates the parameter set {@link HuksParamSet} used + * for the key operation. For details about the key property set struct, + * see the HUKS Device Development. + * + * @see Init | Update | Finish + * + * @return Returns 0 if the operation is successful. + * @return Returns a non-zero value otherwise. + * + * @since 4.0 + * @version 1.0 + */ + Abort([in] struct HuksBlob handle, [in] struct HuksParamSet paramSet); + + /** + * @brief Checks the key validity (integrity of the key and its properties). + * + * @param paramSet Indicates the parameter set {@link HuksParamSet} for + * checking the key validity. For details about the key property set struct, + * see the HUKS Device Development. + * @param encKey Indicates the key material {@link HuksBlob} in ciphertext + * to check. For details about the key material struct, see + * the HUKS Device Development. + * + * @return Returns 0 if the key material is valid. + * @return Returns a non-zero value otherwise. + * + * @since 4.0 + * @version 1.0 + */ + CheckKeyValidity([in] struct HuksParamSet paramSet, [in] struct HuksBlob encKey); + + /** + * @brief Obtains the certificate chain for the given key. + * + * @param encKey Indicates the key material {@link HuksBlob} in ciphertext. + * For details about the key material struct, see the HUKS Device Development. + * @param paramSet Indicates the parameters {@link HuksParamSet} used to + * obtain the certificate chain. For details about the key property + * set struct, see the HUKS Device Development. + * @param certChain Indicates the certificate chain {@link HuksBlob} + * obtained. For details about the certificate chain struct, see the + * HUKS Device Development. + * + * @return Returns 0 if the certificate chain is obtained. + * @return Returns a non-zero value otherwise. + * + * @since 4.0 + * @version 1.0 + */ + AttestKey([in] struct HuksBlob encKey, [in] struct HuksParamSet paramSet, [out] struct HuksBlob certChain); + + /** + * @brief Generates a random number. + * + * @param paramSet Indicates the parameters {@link HuksParamSet} used to + * generate a random number. For details about the key property set struct, + * see the HUKS Device Development. + * @param random Indicates the random number {@link HuksBlob} generated. + * + * @return Returns 0 if a random number is generated. + * @return Returns a non-zero value otherwise. + * + * @since 4.0 + * @version 1.0 + */ + GenerateRandom([in] struct HuksParamSet paramSet, [out]struct HuksBlob random); + + /** + * @brief Generates a signature for data using a key. + * + * @param encKey Indicates the key material {@link HuksBlob} in ciphertext. + * For details about the key material struct, see the HUKS Device Development. + * @param paramSet Indicates the parameters {@link HuksParamSet} used for signing. + * For details about the key property set struct, see the HUKS Device Development. + * @param srcData Indicates the data {@link HuksBlob} to be signed. + * @param signature Indicates the signature {@link HuksBlob} generated. + * + * @return Returns 0 if a signature is generated. + * @return Returns a non-zero value otherwise. + * + * @since 4.0 + * @version 1.0 + */ + Sign([in] struct HuksBlob encKey, [in] struct HuksParamSet paramSet, [in] struct HuksBlob srcData, + [out]struct HuksBlob signature); + + /** + * @brief Verifies a signature. + * + * @param encKey Indicates the key material {@link HuksBlob} in ciphertext. + * For details about the key material struct, see the HUKS Device Development. + * @param paramSet Indicates the parameters {@link HuksParamSet} used for + * signature verification. For details about the key property set struct, + * see the HUKS Device Development. + * @param srcData Indicates the data {@link HuksBlob} whose signature is + * to be verified. + * @param signature Indicates the signature {@link HuksBlob} to verify. + * + * @return Returns 0 if the operation is successful. + * @return Returns a non-zero value otherwise. + * + * @since 4.0 + * @version 1.0 + */ + Verify([in] struct HuksBlob encKey, [in] struct HuksParamSet paramSet, [in] struct HuksBlob srcData, + [in] struct HuksBlob signature); + + /** + * @brief Encrypts data using a key. + * + * @param encKey Indicates the key material {@link HuksBlob} in ciphertext. + * For details about the key material struct, see the HUKS Device Development. + * @param paramSet Indicates the parameters {@link HuksParamSet} used for + * encryption. For details about the key property set struct, see the + * HUKS Device Development. + * @param plainText Indicates the data {@link HuksBlob} to encrypt. + * @param cipherText indicates the data {@link HuksBlob} in ciphertext. + * + * @return Returns 0 if the operation is successful. + * @return Returns a non-zero value otherwise. + * + * @since 4.0 + * @version 1.0 + */ + Encrypt([in] struct HuksBlob encKey, [in] struct HuksParamSet paramSet, [in] struct HuksBlob plainText, + [out] struct HuksBlob cipherText); + + /** + * @brief Decrypts data using a key. + * + * @param encKey Indicates the key material {@link HuksBlob} in ciphertext. + * For details about the key material struct, see the HUKS Device Development. + * @param paramSet Indicates the parameters {@link HuksParamSet} used for + * decryption. For details about the key property set struct, see the + * HUKS Device Development. + * @param cipherText indicates the data {@link HuksBlob} in ciphertext to decrypt. + * @param plainText Indicates the decrypted data {@link HuksBlob} in plaintext. + * + * @return Returns 0 if the operation is successful. + * @return Returns a non-zero value otherwise. + * + * @since 4.0 + * @version 1.0 + */ + Decrypt([in] struct HuksBlob encKey, [in] struct HuksParamSet paramSet, [in] struct HuksBlob cipherText, + [out] struct HuksBlob plainText); + + /** + * @brief Performs key agreement using a private key stored in the HUKS + * and the public key of the service. + * + * @param paramSet Indicates the parameters {@link HuksParamSet} used + * for key agreement. + * @param encPrivateKey Indicates the key pair material {@link HuksBlob} + * stored in the HUKS. For details about the key material struct, see the + * HUKS Device Development. + * @param peerPublicKey Indicates the public key {@link HuksBlob} used + * for key agreement. + * @param agreedKey Indicates the key {@link HuksBlob} in plaintext obtained + * after key agreement. + * + * @return Returns 0 if the operation is successful. + * @return Returns a non-zero value otherwise. + * + * @since 4.0 + * @version 1.0 + */ + AgreeKey([in] struct HuksParamSet paramSet, [in] struct HuksBlob encPrivateKey, [in] struct HuksBlob peerPublicKey, + [out] struct HuksBlob agreedKey); + + /** + * @brief Derives a key from a key stored in the HUKS. + * + * @param paramSet Indicates the parameters {@link HuksParamSet} used for + * key derivation. For details about the key property set struct, see the + * HUKS Device Development. + * @param encKdfKey Indicates the key material {@link HuksBlob} stored + * in the HUKS. For details about the key material struct, see the + * HUKS Device Development. + * @param derivedKey Indicates the derived key {@link HuksBlob} in plaintext. + * + * @return Returns 0 if the operation is successful. + * @return Returns a non-zero value otherwise. + * + * @since 4.0 + * @version 1.0 + */ + DeriveKey([in] struct HuksParamSet paramSet, [in] struct HuksBlob encKdfKey, [out] struct HuksBlob derivedKey); + + /** + * @brief Generates a message authentication code (MAC) using a key + * stored in the HUKS. + * + * @param encKey Indicates the key material {@link HuksBlob} in ciphertext. + * For details about the key material struct, see the HUKS Device Development. + * @param paramSet Indicates the parameters {@link HuksParamSet} used for + * generating a MAC. For details about the key property set struct, see the + * HUKS Device Development. + * @param srcData Indicates the data {@link HuksBlob} used to generate a MAC. + * @param mac Indicates the MAC {@link HuksBlob} generated. + * + * @return Returns 0 if the operation is successful. + * @return Returns a non-zero value otherwise. + * + * @since 4.0 + * @version 1.0 + */ + Mac([in] struct HuksBlob encKey, [in] struct HuksParamSet paramSet, [in] struct HuksBlob srcData, + [out] struct HuksBlob mac); + + /** + * @brief Upgrades a key, including its encryption mode and encryption + * material. The HUKS service triggers the upgrade when the key file version + * is earlier than the latest version. + * + * @param encOldKey Indicates the key material {@link HuksBlob} in + * ciphertext to upgrade. For details about the key material struct, see the + * HUKS Device Development. + * @param paramSet Indicates the parameters {@link HuksParamSet} used for + * the upgrade. For details about the key property set struct, see the + * HUKS Device Development. + * @param encNewKey Indicates the key material {@link HuksBlob} in + * ciphertext after the upgrade. For details about the key material struct, + * see the HUKS Device Development. + * + * @return Returns 0 if the operation is successful. + * @return Returns a non-zero value otherwise. + * + * @since 4.0 + * @version 1.0 + */ + UpgradeKey([in] struct HuksBlob encOldKey, [in] struct HuksParamSet paramSet, [out] struct HuksBlob encNewKey); + + /** + * @brief Exports the public key of a chipset key pair. + * + * @param salt Indicates the salt {@link HuksBlob} used to derive the key + * pair of the chipset. + * @param scene Indicates the expected chipset decryption + * scenario {@link HuksParamSet} of the service. For details about the + * key property set struct, see the HUKS Device Development. + * @param publicKey Indicates the public key material {@link HuksBlob} + * exported, for example, the raw data (32 bytes) of the x-axis and y-axis + * values of ECC-P256. + * + * @return Returns 0 if the operation is successful. + * @return Returns a non-zero value otherwise. + * + * @since 4.0 + * @version 1.0 + */ + ExportChipsetPlatformPublicKey([in] struct HuksBlob salt, [in] enum HuksChipsetPlatformDecryptScene scene, + [out] struct HuksBlob publicKey); + + /** + * @brief Get the detailed error information of the last called function. + * + * @param errorInfo Indicates the detailed error information {@link HuksBlob. + * + * @return Returns 0 if the operation is successful. + * @return Returns a non-zero value otherwise. + * + * @since 5.1 + * @version 1.0 + */ + GetErrorInfo([out] struct HuksBlob errorInfo); + + /** + * @brief Get the runtime statistics of driver layer of the last called function. + * + * @param statInfo Indicates the runtime statistics information {@link HuksBlob}. + * + * @return Returns 0 if the operation is successful. + * @return Returns a non-zero value otherwise. + * + * @since 5.1 + * @version 1.0 + */ + GetStatInfo([out] struct HuksBlob statInfo); +} +/** @} */ \ No newline at end of file diff --git a/huks/v1_1/IHuksTypes.idl b/huks/v1_1/IHuksTypes.idl new file mode 100755 index 0000000000000000000000000000000000000000..bab3501884ba06f376ed149280e649fab40da435 --- /dev/null +++ b/huks/v1_1/IHuksTypes.idl @@ -0,0 +1,82 @@ +/* + * Copyright (c) 2024 Huawei Device Co., Ltd. + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +/** + * @addtogroup HdfHuks + * @{ + * + * @brief Provides standard driver APIs for the OpenHarmony Universal KeyStore (HUKS). + * + * The HUKS driver APIs define standard interfaces of the HUKS Core and provide + * a unified driver interface for the HUKS service. + * You can use these APIs to implement key lifecycle management, including key + * generation, key import and export, key operations, key access control, and + * key attestation. + * + * @since 4.0 + */ + + /** + * @file IHuksTypes.idl + * + * @brief Defines the structs used in HUKS driver interfaces. + * + * @since 4.0 + */ + +package ohos.hdi.huks.v1_1; + +/** + * @brief Defines the HUKS binary data struct, which encapsulates parameters + * such as the key material and key properties. + * + * @since 4.0 + * @version 1.0 + */ +struct HuksBlob { + /** + * Binary data + */ + unsigned char[] data; +}; + +/** + * @brief Defines the struct for the parameter set of HUKS key management interfaces. + * + * @since 4.0 + * @version 1.0 + */ +struct HuksParamSet { + /** + * Serialized parameter set. For details about the property set struct, + * see the HUKS Device Development. + */ + unsigned char[] data; +}; + +/** + * @brief Enumerates the decryption scenarios using the chipset key. + * + * @since 4.0 + * @version 1.0 + */ +enum HuksChipsetPlatformDecryptScene { + /** + * Chipset key decryption for trusted applications in a Trusted Execution + * Environment (TEE). + */ + HUKS_CHIPSET_PLATFORM_DECRYPT_SCENCE_TA_TO_TA = 1, +}; +/** @} */ \ No newline at end of file