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

/** @cond */
interface ISecureChannelKeyExchange {
/** @endcond */

  /**
    @addtogroup ISecureChannelKeyExchange
    @{
   */

  /** @cond */

  error ERROR_RPMB;
  error ERROR_PRNG;
  error ERROR_DEVICE_PROVISION_LOCKED;
  error ERROR_KEYS_NOT_PROVISIONED;
  error ERROR_INVALID_PARAMETER_TYPE;
  error ERROR_INVALID_PARAMETER_LENGTH;

  const uint32 PARAM_BASE_KEY = 1;
  const uint32 PARAM_LOCAL_CONTEXT_KEY = 2;
  const uint32 PARAM_REMOTE_KEY = 3;

  const uint32 USECASE_IRIS = 1;

  /** @endcond */

  /**
    Generates a base key using PRNG and returns it in plaintext.

    @param [out] base_key    Output base key value.

    @return
    Object_OK on success. Any other error code on failure.
   */
  method generateBaseKey(out buffer base_key);

  /**
    Generates a nonce for use in key derivation.

    @param [out] nonce_buf    Output base key value.

    @return
    Object_OK on success
   */
  method generateNonce(out buffer nonce_buf);

  /**
    Derives a key using the base key and nonce.
    Base key value is taken from RPMB.

    @param [in]  nonce        Input nonce value.
    @param [out] key_obj      Output derived key object.

    @return
    Object_OK on success. Any other error code on failure.
   */
  method deriveContextKey(in buffer nonce, out interface key_obj);

  /**
    Commits the key buffer to persistent RPMB storage.

    @param [in] param_buf     The value of the key to be committed.
    @param [in] key_type      The type of key to be committed.
    Supported params:
    - PARAM_BASE_KEY          -- locally generated base key.
    - PARAM_REMOTE_KEY        -- key received from a remote source.

    @return
    Object_OK on success. Any other error code on failure.
   */
  method commitToRPMB(in uint32 key_type, in buffer param_buf);

  /**
    Commits the key object to persistent RPMB storage.

    @param [in] param_buf     The key object to be committed.
    @param [in] key_type      The type of key to be committed.
    Supported params:
    - PARAM_LOCAL_CONTEXT_KEY -- key derived from base key.

    @return
    Object_OK on success. Any other error code on failure.
   */
  method commitObjectToRPMB(in uint32 key_type, in interface param_obj);

  /**
    Reads the parameter value from RPMB and returns the buffer.

    @param [in] param         ID of the parameter to fetch.
    @param [out] buf          Output param value.

    Supported params:
    - PARAM_REMOTE_KEY        -- key received from a remote source.

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

  /**
    Reads the parameter value from RPMB and returns the object.

    @param [in] param         ID of the parameter to fetch.
    @param [out] key_obj      Output param value.

    Supported params:
    - PARAM_LOCAL_CONTEXT_KEY -- key derived from base key

    @return
    Object_OK on success. Any other error code on failure.
   */
  method getObjectFromRPMB(in uint32 param, out interface key_obj);

  /**
    Locks the provisioning. New keys can no longer be committed after this step.

    @return
    Object_OK on success. Any other error code on failure.
   */
  method lockProvisioning();

  /**
    Unlocks the provisioning. New keys can be committed again after this step.

    @return
    Object_OK on success. Any other error code on failure.
   */
  method unlockProvisioning();

  /**
    Sets the usecase ID in the context. This ID is used to manage RPMB partitions.

    @param [in] param         ID of the USECASE.
    Supported params:
    - USECASE_IRIS

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

  /**
    Returns whether or not the keys have been provisioned.

    @return
    Object_OK on success. Any other error code on failure.
   */
  method isProvisioningDone();

  /** @} */ /* end_addtogroup ISecureChannelKeyExchange */
};
