/** @file  ICrypto.idl */

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

/** @cond */
interface ICrypto {
/** @endcond */

  /**
   * @addtogroup ICrypto
   * @{
   */

  /** @cond */
  const int32 CMAC_ALGO_AES_128 = 1;
  const int32 CMAC_ALGO_AES_256 = 2;
  const int32 CMAC_ALGO_INVALID = 99;

  error ERROR_NOT_SUPPORTED;
  /** @endcond */


  /**
    Creates a cipher MAC per @xhyperref{FIPS198,FIPS PUB 198-1}, using
    the specified hash algorithm.

    @param[in]  alg    128-bit or 256-bit AES algorithm.
    @param[in]  msg    Message to be authenticated.
    @param[in]  key    Input key to CMAC algorithm.
    @param[out] digest CMAC digest.

    @return
    Object_OK -- Successful. \n
    Object_ERROR_INVALID -- Invalid parameter encountered. \n
    Object_ERROR -- Any other error encountered.
  */
  method cmac(in int32 alg, in buffer msg, in buffer key, out buffer digest);

  /**
    KDF key derivation algorithm.

    @param[in] key           Key derivation key.
    @param[in] label         Key derivation label.
    @param[in] context       Key derivation context.
    @param[out] output       Derived key.

    @detdesc
    Software is a three-level stack:
    - AES (lowest level)
    - CMAC algorithm from @xhyperref{NIST80038B, SP 800-38B}
    - Counter-based algorithm from @xhyperref{NIST800108, SP 800-108} (named KDF in the implementation)
    @par
    The inputs are a key derivation key, a label, and a context.
    The output is the derived key.
    All sensitive data is zeroized before return.

    @return
    Object_OK -- Successful. \n
    Object_ERROR_INVALID -- Invalid parameter encountered. \n
    Object_ERROR -- Any other error encountered.
  */
  method kdf(in buffer key, in buffer label, in buffer context, out buffer output);

  /**
    The KDF binding key derivation algorithm is an internally unique key-generation 
    process derived by binding user data with the Secondary Hardware Key (SHK).

    @param[in] context       Key derivation context.
    @param[out] output       Derived key.

    @detdesc
    Software is a three-level stack:
    - AES (lowest level)
    - CMAC algorithm from @xhyperref{NIST80038B, SP 800-38B}
    - Counter-based algorithm from @xhyperref{NIST800108, SP 800-108} (named KDF in the implementation)
    @par
    The input is a key derivation context.
    The output is the derived key.
    All sensitive data is zeroized before return.

    @return
    Object_OK -- Successful. \n
    Object_ERROR_INVALID -- Invalid parameter encountered. \n
    Object_ERROR -- Any other error encountered.
  */
  method device_kdf(in buffer context, out buffer output);

  /** @cond */
  const int32 HKDF_ALGO_SHA1 = 1;
  const int32 HKDF_ALGO_SHA224 = 2;
  const int32 HKDF_ALGO_SHA256 = 3;
  const int32 HKDF_ALGO_SHA384 = 4;
  const int32 HKDF_ALGO_SHA512 = 5;
  const int32 HKDF_ALGO_MD5 = 6;
  const int32 HKDF_ALGO_SM3 = 7;
  const int32 HKDF_ALGO_INVALID = 99;
  /** @endcond */
  
  /**
    HKDF key derivation algorithm.

    @param[in] hash_algo     Hash Algorithm.
    @param[in] ikm           Input Key Material.
    @param[in] salt          Salt.
    @param[in] context       Context or Info.
    @param[out] okm          Output Key Material.

    @detdesc
    Software is a two-level stack:
    - Pseudo Random Key (PRK) Derivation based on IKM and Salt
    - Derive OKM using PRK and Context
    @par
    The inputs are a IKM, a salt, and a context.
    The output is the derived key (OKM).
    All sensitive data is zeroized before return.

    @return
    Object_OK -- Successful. \n
    Object_ERROR_INVALID -- Invalid parameter encountered. \n
    Object_ERROR -- Any other error encountered.
  */
  method hkdf(in int32 hash_algo, in buffer ikm, in buffer salt, in buffer context, out buffer okm);
  
  /**
    Performs a CMAC operation using the supplied HWKey object as the key for the operation

    @param[in]  alg     128-bit or 256-bit AES algorithm.
    @param[in]  key_obj HWKey object to use for CMAC operation.
    @param[in]  msg     Message to be authenticated.
    @param[out] digest  CMAC digest.

    @return
    Object_OK -- Successful. \n
    Object_ERROR_INVALID -- Invalid parameter encountered. \n
    Object_ERROR -- Any other error encountered.
  */
  method hwkey_cmac(in int32 alg, in interface key_obj, in buffer msg, out buffer digest);
  /** @} */ /* end_addtogroup ICrypto */
};
