/**
 * Copyright (c) 2018, 2020, 2021 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;
  const uint32 HW_KEY = 4;
  const uint32 KEY_SIZE = 5;
  

  /**
   * 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  */
  const uint32 KEY_SOURCE_HWKM = 5;             /**< Use Hardware Key Manager to generate the key seed */
  /** @endcond */

  /**
   * SET_KEY_SIZE values
   */
  const uint32 KEY_SIZE_256 = 1;    /**< Use key size256 */
  const uint32 KEY_SIZE_384 = 2;    /**< Use key size384 */ 

  /**
    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 \link IKey \endlink 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);

  /**
    Sets the HW Key object parameter for key generation. All set parameters
    are flushed upon successful completion of generateKey.
    @param [in] param   Parameter ID to set.
    @param [in] obj     HWKey object to be set.

    @detdesc
    Supported params:
    - HW_KEY       -- HW Key object

    @return
    Object_OK on success. Any other error code on failure.
   */
  method setParameterAsObject(in uint32 param, in interface obj);
  /** @} */ /* end_addtogroup IKeyManager */
};

/**
 * @brief
 * ILegacyHWAttestation is an interface to call into the HW attestion block, which is 
 * used to prove the identity and the security state of the device, without any reliance
 * on SW security. Based on the client's request, it will generate an HMAC for the
 * QFPROM region(s) supplied. It uses the HW_ATTESTATION_* registers of the Security
 * Control Core to communicate with the HW attestation block.
 */

/** @cond */
interface ILegacyHWAttestation {
/** @endcond */

  /** @cond */
  
  /**
   * Key options
   */
  const uint8  TEST_KEY                     = 1;
  const uint8  PRODUCTION_KEY               = 2;
  
  /**
   * QFPROM regions supported for HMAC calculation, OR the required ones
   */
  const uint64 QFPROM_REGION_MRC               = 0x001;
  const uint64 QFPROM_REGION_READ_PERMISSIONS  = 0x002;
  const uint64 QFPROM_REGION_WRITE_PERMISSIONS = 0x004;
  const uint64 QFPROM_REGION_FEC_ENABLES       = 0x008;
  const uint64 QFPROM_REGION_OEM_CONFIG        = 0x010;
  const uint64 QFPROM_REGION_ANTI_ROLLBACK     = 0x020;
  const uint64 QFPROM_REGION_PK_HASH           = 0x040;
  const uint64 QFPROM_REGION_OEM_SECURE_BOOT   = 0x080;
  const uint64 QFPROM_REGION_BOOT_ROM_PATCH    = 0x100;
  
  /**
   * All the above QFPROM regions
   */
  const uint64 QFPROM_REGION_ALL               = 0x1FF;
  

  /** @endcond */

  /**
   * @addtogroup ILegacyHWAttestation
   * @{
   */
   
  /**
    Performs HW attestation on the supplied QFPROM region(s) based on the
    supplied parameters. 

    @param[in]  keyId          Key to base the derivation on.
    @param[in]  context        Key context.
    @param[in]  nonce          Nonce value.
    @param[in]  regions        QFPROM region(s) of interest. If multiple QFPROM 
                               regions' HMACs are desired, OR them and send in 
                               this variable.
    @param[out] output         256-bit SHA HASH MAC value.

    @return
    Object_OK on success. Any other error code on failure.
  */
  method getHardwareAttestation(in uint8 keyId, in uint16 context, in uint32 nonce, in uint64 regions, out buffer output);
  
  /** @} */ /* end_addtogroup ILegacyHWAttestation */
};