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

include "IHWKeyFactory.idl"

/** @file IRkpBCC.idl */

/** @cond */

/** Struct which holds various pieces of information about the BCC. */
struct RkpBCCInfo {
  /**
   * Version of the BCC library - 0xMMMMmmmm, where 'M' is major version, and
   * 'm' is minor version
   */
  uint32  bccVersion;

  /**
   * Minimum required size of the buffer that the client should allocate for the
   * incoming BCC.
   */
  uint32  minimumBccBufferSize;
};

interface IRkpBCC {
/** @endcond */

  /**
    @addtogroup IRkpBCC
    @{
   */

  /**
    Communicate the minimum required size of the buffer needed to store the
    incoming QSEE BCC. This does NOT return the actual size of the BCC - that is
    provided by getRkpFinalBCC.

    The BCC will not be the same size from build to build, so we have computed
    a minimum and maximum size based on expected variance. This API returns the
    maximum size that might be needed for the incoming QTEE BCC, hence why the
    caller should treat this function as a minimum required buffer size for BCC.

    WARNING: This API has been deprecated - please use getRkpBCCInfo instead.

    @param[out]  bccBufferSize  minimum required buffer size for QTEE BCC.

    @return
    Object_OK on success
   */
  method getRkpBCCSize(out uint32 bccBufferSize);

  /**
    Transfer the QSEE BCC into 'bccBuffer'.
    We want to ensure that this function is only called once. If it has already
    been called, refuse to provide the final BCC again. Requirement is that BCC
    will be generated and sent to KM-TA client once only on a cold boot. Once
    KM-TA consumes this BCC it is supposed to be holding back in KM-TA memory.

    Important to note that, KM-TA must sign a very large payload using the leaf
    keypair, and the payload size exceeds the maximum size that TZ can transfer
    to TME for signing. We can circumvent this need by making the leaf keypair
    SW-based, which this IDL does automatically.

    @param[out]  bccBuffer           ptr to buffer where we should copy BCC into
    @param[out]  bccNextStageSecret  KM secret key Object

    @return
    Object_OK on success
   */
  method getRkpFinalBCC(out buffer bccBuffer, out IHWKey bccNextStageSecret);

  /**
    Provide relevant BCC information, such as size of the BCC buffer and BCC
    version.

    @param[out]  bccInfo            struct containing information on the BCC

    @return
    Object_OK on success
   */
  method getRkpBCCInfo(out RkpBCCInfo bccInfo);

  /** @} */ /* end_addtogroup IRkpBCC */
};
