/*
 * Copyright (c) 2023 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_0;

import ohos.hdi.huks.v1_0.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 <b>0</b> 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 <b>0</b> 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 <b>0</b> 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 <b>0</b> 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 <b>0</b> 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 <b>0</b> 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 <b>0</b> 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 <b>0</b> 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 <b>0</b> 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 <b>0</b> 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 <b>0</b> 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 <b>0</b> 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 <b>0</b> 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 <b>0</b> 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 <b>0</b> 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 <b>0</b> 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 <b>0</b> 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 <b>0</b> 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 <b>0</b> 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 <b>0</b> 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 <b>0</b> 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);
}
/** @} */