/**
 * Copyright (c) 2018 Qualcomm Technologies, Inc. All Rights Reserved.
 * Qualcomm Technologies Proprietary and Confidential.
 */

/** @file  IKeyManager.idl */

/**
 * @brief
 * IKey provides an interface to the key generated using IKeyManager.
 */

/** @cond */
interface IKey {
/** @endcond */

  /**
   * @addtogroup IKey
   * @{
   */

  /** @cond */

  /**
   * Error Codes
   */
  error ERROR_OP_NOT_PERMITTED;
  /**< Return this error if the client does not have privilege
       to generate and/or retrieve the private key. */

  /**
   * Param-ids for get parameter
   */
  const uint32 PRIVATE_KEY = 1;
  const uint32 PUBLIC_KEY = 2;
  const uint32 KEY_STATUS = 3;

  /**
   * KEY_STATUS values
   */
  const uint32 KEY_GENERATED_NOT_AVAILABLE_TO_SW = 1;
  const uint32 KEY_GENERATED_AVAILABLE_TO_SW = 2;
  /** @endcond */

  /**
    Gets parameter associated with the key generated by IKeyManager.
    @param [in] param   Parameter ID to get.
    @param [out] buf    param value to set.

    @detdesc
    Supported params:
    - PRIVATE_KEY - param value set in buf
    - PUBLIC_KEY  - param value set in buf
    - KEY_STATUS  - param value set in val

    @return
    Object_OK on success. Any other error code on failure.
   */
  method getParameter(in uint32 param, out buffer buf);
  /** @} */ /* end_addtogroup IKey */
};

/**
 * @brief
 * KeyManager is Qualcomm's key management service. Based on the client's request,
 * it will generate and retrieve keys from one or more key sources.
 */

/** @cond */
interface IKeyManager {
/** @endcond */

  /**
   * @addtogroup IKeyManager
   * @{
   */

  /** @cond */

  /**
   * Param-ids for set parameter
   */
  const uint32 KEY_SOURCE = 0;
  const uint32 MODULE_SEQ_1 = 1;
  const uint32 MODULE_SEQ_2 = 2;
  const uint32 KDF_SEED = 3;

  /**
   * SET_KEY_SOURCE values
   */
  const uint32 KEY_SOURCE_CRI_AND_KEY_CTRL = 1; /**< Use CryptoManager Core h/w and Key Controller h/w to generate a key seed value. Use this key seed to generate a ECC private public key pair */
  const uint32 KEY_SOURCE_CRI_SW_BUFFER = 2;    /**< Use CryptoManager Core h/w alone to generate a key seed value. Use this key seed to generate a ECC private public key pair */
  const uint32 KEY_SOURCE_TEST_SEED = 3;        /**< Generate a ECC key pair using either the default seed value in sw or based on the kdf_seed provided */
  const uint32 KEY_SOURCE_HW_FUSE_UIE = 4;      /**< Use UIE Fuse value as key seed to generate a ECC key pair  */
  /** @endcond */

  /**
    Sets a parameter for key generation. All set parameters
    are flushed upon successful completion of generateKey.
    @param [in] param   Parameter ID to set.
    @param [in] buf     param value to set.

    @detdesc
    Supported params:
    - KEY_SOURCE   -- param value set in val
    - MODULE_SEQ_1 -- param value set in buf (data a signed CRI sequence)
    - MODULE_SEQ_2 -- param value set in buf (data a signed CRI sequence)
    - KDF_SEED     -- param value set in buf (data is 256 byte random seed input from client)

    @return
    Object_OK on success. Any other error code on failure.
   */
  method setParameter(in uint32 param, in buffer buf);

  /**
    Generates key based on the parameters set. \n
    On successful completion, an IKey object will be returned to the client,
    which can be used to retrieve the keys. All parameters set prior to generate
    key are flushed out on successful completion.

    @param [out] key   Key Object containing generated key.

    @return
    Object_OK on success; otherwise, any other error code on failure.
   */
  method generateKey(out IKey key);
  /** @} */ /* end_addtogroup IKeyManager */
};