/**
 * OpenHarmony Universal KeyStore (Huks) cryptographic service interface.
 * Provides secure key generation, import, export, deletion, and cryptographic operations.
 * @namespace huks
 * @syscap SystemCapability.Security.Huks.Core
 */
declare namespace huks {

  /**
   * Generates a new cryptographic key with specified parameters.
   * 
   * @param alias - Unique identifier for the key.
   * @param config - Configuration object defining algorithm, size, purpose, and other attributes.
   * @param callback - Asynchronous callback returning operation status.
   * @throws { BusinessError } 401 - Invalid or missing input parameters.
   * @throws { BusinessError } 801 - Unsupported API version.
   * @throws { BusinessError } 12000001–12000015 - Cryptographic or system-level failures.
   * @syscap SystemCapability.Security.Huks.Core
   * @since 9
   */
  function generateKeyItem(alias: string, config: HuksOptions, callback: AsyncCallback<void>): void;

  /**
   * Generates a new cryptographic key and returns a Promise.
   * 
   * @param alias - Unique identifier for the key.
   * @param config - Configuration object defining algorithm, size, purpose, and other attributes.
   * @returns A Promise resolving on success or rejecting with a BusinessError.
   * @throws { BusinessError } 401 - Invalid or missing input parameters.
   * @throws { BusinessError } 801 - Unsupported API version.
   * @throws { BusinessError } 12000001–12000015 - Cryptographic or system-level failures.
   * @syscap SystemCapability.Security.Huks.Extension
   * @since 9
   */
  function generateKeyItem(alias: string, config: HuksOptions): Promise<void>;

  /**
   * Generates a key scoped to a specific user account.
   * Requires INTERACT_ACROSS_LOCAL_ACCOUNTS permission and system app privileges.
   * 
   * @param userId - Target user ID.
   * @param alias - Unique identifier for the key.
   * @param config - Configuration object defining algorithm, size, purpose, and other attributes.
   * @returns A Promise resolving on success or rejecting with a BusinessError.
   * @throws { BusinessError } 201 - Permission denied.
   * @throws { BusinessError } 202 - Not a system application.
   * @throws { BusinessError } 401 - Invalid or missing input parameters.
   * @throws { BusinessError } 12000001–12000015 - Cryptographic or system-level failures.
   * @syscap SystemCapability.Security.Huks.Extension
   * @systemapi
   * @since 12
   */
  function generateKeyItemAsUser(userId: number, alias: string, config: HuksOptions): Promise<void>;

  /**
   * Removes an existing key from secure storage.
   * 
   * @param alias - Unique identifier of the key to delete.
   * @param config - Configuration object (used for validation).
   * @param callback - Asynchronous callback returning operation status.
   * @throws { BusinessError } 401 - Invalid or missing input parameters.
   * @throws { BusinessError } 801 - Unsupported API version.
   * @throws { BusinessError } 12000004–12000014 - Storage, IPC, or memory failures.
   * @syscap SystemCapability.Security.Huks.Core
   * @since 9
   */
  function deleteKeyItem(alias: string, config: HuksOptions, callback: AsyncCallback<void>): void;

  /**
   * Removes an existing key and returns a Promise.
   * 
   * @param alias - Unique identifier of the key to delete.
   * @param config - Configuration object (used for validation).
   * @returns A Promise resolving on success or rejecting with a BusinessError.
   * @throws { BusinessError } 401 - Invalid or missing input parameters.
   * @throws { BusinessError } 801 - Unsupported API version.
   * @throws { BusinessError } 12000004–12000014 - Storage, IPC, or memory failures.
   * @syscap SystemCapability.Security.Huks.Extension
   * @since 9
   */
  function deleteKeyItem(alias: string, config: HuksOptions): Promise<void>;

  /**
   * Deletes a key scoped to a specific user account.
   * Requires INTERACT_ACROSS_LOCAL_ACCOUNTS permission and system app privileges.
   * 
   * @param userId - Target user ID.
   * @param alias - Unique identifier of the key to delete.
   * @param config - Configuration object (used for validation).
   * @returns A Promise resolving on success or rejecting with a BusinessError.
   * @throws { BusinessError } 201 - Permission denied.
   * @throws { BusinessError } 202 - Not a system application.
   * @throws { BusinessError } 401 - Invalid or missing input parameters.
   * @throws { BusinessError } 12000004–12000014 - Storage, IPC, or memory failures.
   * @syscap SystemCapability.Security.Huks.Extension
   * @systemapi
   * @since 12
   */
  function deleteKeyItemAsUser(userId: number, alias: string, config: HuksOptions): Promise<void>;

  /**
   * Imports a raw key material into secure storage.
   * 
   * @param alias - Desired identifier for the imported key.
   * @param config - Configuration specifying key type, algorithm, and usage constraints.
   * @param callback - Asynchronous callback returning operation status.
   * @throws { BusinessError } 401 - Invalid or missing input parameters.
   * @throws { BusinessError } 801 - Unsupported API version.
   * @throws { BusinessError } 12000001–12000015 - Algorithm, storage, or crypto engine failures.
   * @syscap SystemCapability.Security.Huks.Extension
   * @since 9
   */
  function importKeyItem(alias: string, config: HuksOptions, callback: AsyncCallback<void>): void;

  /**
   * Imports a raw key material and returns a Promise.
   * 
   * @param alias - Desired identifier for the imported key.
   * @param config - Configuration specifying key type, algorithm, and usage constraints.
   * @returns A Promise resolving on success or rejecting with a BusinessError.
   * @throws { BusinessError } 401 - Invalid or missing input parameters.
   * @throws { BusinessError } 801 - Unsupported API version.
   * @throws { BusinessError } 12000001–12000015 - Algorithm, storage, or crypto engine failures.
   * @syscap SystemCapability.Security.Huks.Extension
   * @since 9
   */
  function importKeyItem(alias: string, config: HuksOptions): Promise<void>;

  /**
   * Imports a key wrapped by another key in the keystore.
   * 
   * @param alias - Identifier for the unwrapped key.
   * @param wrappingAlias - Identifier of the wrapping key.
   * @param config - Configuration specifying unwrap algorithm suite and constraints.
   * @param callback - Asynchronous callback returning operation status.
   * @throws { BusinessError } 401 - Invalid or missing input parameters.
   * @throws { BusinessError } 801 - Unsupported API version.
   * @throws { BusinessError } 12000001–12000015 - Algorithm, storage, or crypto engine failures.
   * @syscap SystemCapability.Security.Huks.Extension
   * @since 9
   */
  function importWrappedKeyItem(
    alias: string,
    wrappingAlias: string,
    config: HuksOptions,
    callback: AsyncCallback<void>
  ): void;

  /**
   * Exports public key material or certificate chain.
   * 
   * @param alias - Identifier of the key to export.
   * @param config - Configuration specifying export format and constraints.
   * @param callback - Asynchronous callback returning exported data or error.
   * @throws { BusinessError } 401 - Invalid or missing input parameters.
   * @throws { BusinessError } 801 - Unsupported API version.
   * @throws { BusinessError } 12000001–12000014 - Algorithm, storage, or memory failures.
   * @syscap SystemCapability.Security.Huks.Extension
   * @since 9
   */
  function exportKeyItem(alias: string, config: HuksOptions, callback: AsyncCallback<HuksReturnResult>): void;

  /**
   * Retrieves metadata associated with a stored key.
   * 
   * @param alias - Identifier of the key.
   * @param config - Configuration specifying which properties to retrieve.
   * @param callback - Asynchronous callback returning property list or error.
   * @throws { BusinessError } 401 - Invalid or missing input parameters.
   * @throws { BusinessError } 801 - Unsupported API version.
   * @throws { BusinessError } 12000001–12000014 - Algorithm, storage, or memory failures.
   * @syscap SystemCapability.Security.Huks.Extension
   * @since 9
   */
  function getKeyItemProperties(
    alias: string,
    config: HuksOptions,
    callback: AsyncCallback<HuksReturnResult>
  ): void;

  /**
   * Checks whether a key with the given alias exists in secure storage.
   * 
   * @param alias - Identifier to check.
   * @param config - Configuration used for validation.
   * @param callback - Asynchronous callback returning boolean result.
   * @throws { BusinessError } 401 - Invalid or missing input parameters.
   * @throws { BusinessError } 801 - Unsupported API version.
   * @throws { BusinessError } 12000002–12000014 - Parameter, storage, or memory failures.
   * @syscap SystemCapability.Security.Huks.Core
   * @since 9
   */
  function isKeyItemExist(alias: string, config: HuksOptions, callback: AsyncCallback<boolean>): void;

  /**
   * Initializes a cryptographic session for multi-step operations (e.g., sign/verify, encrypt/decrypt).
   * 
   * @param alias - Identifier of the key to use in the session.
   * @param config - Operation-specific configuration (e.g., padding, digest).
   * @param callback - Asynchronous callback returning session handle.
   * @throws { BusinessError } 401 - Invalid or missing input parameters.
   * @throws { BusinessError } 801 - Unsupported API version.
   * @throws { BusinessError } 12000001–12000014 - Algorithm, storage, or resource limit failures.
   * @syscap SystemCapability.Security.Huks.Core
   * @since 9
   */
  function initSession(alias: string, config: HuksOptions, callback: AsyncCallback<HuksSessionHandle>): void;

  /**
   * Feeds data into an active cryptographic session.
   * 
   * @param handle - Session handle returned by initSession.
   * @param config - Update-specific options (e.g., additional authenticated data).
   * @param token - Optional authentication token for user-verified operations.
   * @param callback - Asynchronous callback returning intermediate result.
   * @throws { BusinessError } 401 - Invalid or missing input parameters.
   * @throws { BusinessError } 801 - Unsupported API version.
   * @throws { BusinessError } 12000001–12000014 - Algorithm, auth, or storage failures.
   * @syscap SystemCapability.Security.Huks.Core
   * @since 9
   */
  function updateSession(
    handle: number,
    config: HuksOptions,
    token?: Uint8Array,
    callback: AsyncCallback<HuksReturnResult>
  ): void;

  /**
   * Finalizes a cryptographic session and returns the output (e.g., signature, ciphertext).
   * 
   * @param handle - Session handle returned by initSession.
   * @param config - Finalization options.
   * @param token - Optional authentication token for user-verified operations.
   * @param callback - Asynchronous callback returning final result.
   * @throws { BusinessError } 401 - Invalid or missing input parameters.
   * @throws { BusinessError } 801 - Unsupported API version.
   * @throws { BusinessError } 12000001–12000014 - Algorithm, auth, or storage failures.
   * @syscap SystemCapability.Security.Huks.Core
   * @since 9
   */
  function finishSession(
    handle: number,
    config: HuksOptions,
    token?: Uint8Array,
    callback: AsyncCallback<HuksReturnResult>
  ): void;

  /**
   * Aborts an ongoing cryptographic session and releases resources.
   * 
   * @param handle - Session handle to abort.
   * @param config - Abort options.
   * @param callback - Asynchronous callback signaling completion.
   * @throws { BusinessError } 401 - Invalid or missing input parameters.
   * @throws { BusinessError } 801 - Unsupported API version.
   * @throws { BusinessError } 12000004–12000014 - Storage, IPC, or memory failures.
   * @syscap SystemCapability.Security.Huks.Core
   * @since 9
   */
  function abortSession(handle: number, config: HuksOptions, callback: AsyncCallback<void>): void;

  /**
   * Performs hardware-backed attestation of a key's provenance and integrity.
   * Requires ATTEST_KEY permission and system app privileges.
   * 
   * @param alias - Identifier of the key to attest.
   * @param config - Attestation options (e.g., challenge, application ID).
   * @param callback - Asynchronous callback returning attestation certificate chain.
   * @throws { BusinessError } 201 - Permission denied.
   * @throws { BusinessError } 401 - Invalid or missing input parameters.
   * @throws { BusinessError } 12000001–12000014 - Algorithm, storage, or memory failures.
   * @syscap SystemCapability.Security.Huks.Extension
   * @since 9
   */
  function attestKeyItem(alias: string, config: HuksOptions, callback: AsyncCallback<HuksReturnResult>): void;

  /**
   * Lists all key aliases currently stored in the keystore.
   * 
   * @param config - Options affecting listing behavior (e.g., scope).
   * @returns A Promise resolving to an object containing an array of alias strings.
   * @throws { BusinessError } 401 - Invalid or missing input parameters.
   * @throws { BusinessError } 12000004–12000014 - Storage, IPC, or memory failures.
   * @syscap SystemCapability.Security.Huks.Extension
   * @atomicservice
   * @since 12
   */
  function listAliases(config: HuksOptions): Promise<HuksListAliasesReturnResult>;

  // --- Type Definitions ---

  /**
   * Represents a single parameter in a Huks configuration.
   */
  export interface HuksParam {
    tag: HuksTag;
    value: boolean | number | bigint | Uint8Array;
  }

  /**
   * Represents a handle to an active cryptographic session.
   */
  export interface HuksSessionHandle {
    handle: number;
    challenge?: Uint8Array;
  }

  /**
   * Configuration object passed to most Huks operations.
   */
  export interface HuksOptions {
    properties?: Array<HuksParam>;
    inData?: Uint8Array;
  }

  /**
   * Result structure returned by many Huks operations.
   */
  export interface HuksReturnResult {
    outData?: Uint8Array;
    properties?: Array<HuksParam>;
    certChains?: Array<string>;
  }

  /**
   * Result structure for listAliases.
   */
  export interface HuksListAliasesReturnResult {
    keyAliases: Array<string>;
  }

  // --- Enumerations ---

  export enum HuksTag {
    HUKS_TAG_ALGORITHM = 0x10000001,
    HUKS_TAG_PURPOSE = 0x10000002,
    HUKS_TAG_KEY_SIZE = 0x10000003,
    HUKS_TAG_DIGEST = 0x10000004,
    HUKS_TAG_PADDING = 0x10000005,
    HUKS_TAG_BLOCK_MODE = 0x10000006,
    HUKS_TAG_KEY_TYPE = 0x10000007,
    HUKS_TAG_ASSOCIATED_DATA = 0x50000008,
    HUKS_TAG_NONCE = 0x50000009,
    HUKS_TAG_IV = 0x5000000A,
    HUKS_TAG_INFO = 0x5000000B,
    HUKS_TAG_SALT = 0x5000000C,
    HUKS_TAG_ITERATION = 0x1000000E,
    HUKS_TAG_KEY_ALIAS = 0x50000017,
    HUKS_TAG_IS_KEY_ALIAS = 0x40000401,
    HUKS_TAG_KEY_STORAGE_FLAG = 0x10000402
  }

  export enum HuksKeyAlg {
    HUKS_ALG_RSA = 1,
    HUKS_ALG_ECC = 2,
    HUKS_ALG_AES = 20,
    HUKS_ALG_HMAC = 50
  }

  export enum HuksKeyPurpose {
    HUKS_KEY_PURPOSE_ENCRYPT = 1,
    HUKS_KEY_PURPOSE_DECRYPT = 2,
    HUKS_KEY_PURPOSE_SIGN = 4,
    HUKS_KEY_PURPOSE_VERIFY = 8
  }

  export enum HuksKeyDigest {
    HUKS_DIGEST_SHA256 = 12,
    HUKS_DIGEST_SHA512 = 14
  }

  export enum HuksKeyPadding {
    HUKS_PADDING_NONE = 0,
    HUKS_PADDING_PKCS1_V1_5 = 3
  }

  export enum HuksCipherMode {
    HUKS_MODE_CBC = 2,
    HUKS_MODE_GCM = 32
  }

  export enum HuksKeySize {
    HUKS_RSA_KEY_SIZE_2048 = 2048,
    HUKS_ECC_KEY_SIZE_256 = 256,
    HUKS_AES_KEY_SIZE_256 = 256
  }

  export enum HuksExceptionErrCode {
    HUKS_ERR_CODE_ILLEGAL_ARGUMENT = 401,
    HUKS_ERR_CODE_ITEM_NOT_EXIST = 12000011,
    HUKS_ERR_CODE_INSUFFICIENT_MEMORY = 12000014
  }
}

export default huks;