/** @file  ICipher.idl */

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

/** @cond */
interface ICipher {
/** @endcond */

  /**
   * @addtogroup ICipher
   * @{
   */

  /** @cond */
  const int32 PARAM_KEY = 0;
  const int32 PARAM_IV = 1;
  const int32 PARAM_MODE = 2;
  const int32 PARAM_PAD = 3;
  const int32 PARAM_NONCE = 4;
  const int32 PARAM_XTS_KEY = 5;
  const int32 PARAM_XTS_DU_SIZE = 6;
  const int32 PARAM_CCM_PAYLOAD_LEN = 7;
  const int32 PARAM_CCM_MAC_LEN = 8;
  const int32 PARAM_CCM_HDR_LEN = 9;
  const int32 PARAM_BAM_PIPE   = 10;
  const int32 PARAM_VA_IN      = 11;
  const int32 PARAM_VA_IN_LEN  = 12;
  const int32 PARAM_VA_OUT     = 13;
  const int32 PARAM_VA_OUT_LEN = 14;
  const int32 PARAM_COPY       = 15;
  const int32 PARAM_PIPE_TIMER = 16;
  const int32 PARAM_KEY_TYPE = 17;
  const int32 PARAM_PIPE_DIRECTION = 18;
  const int32 PARAM_CONFIG_PIPE = 19;
  const int32 PARAM_PATT_OFFSET = 20;
  const int32 PARAM_PATT_SIZE = 21;
  const int32 PARAM_PATT_DATA_SIZE = 22;
  const int32 PARAM_BLOCK_OFFSET = 23;
  const int32 PARAM_CTR_SZ     = 24;
  const int32 PARAM_INVALID = -1;

  const int32 MODE_ECB = 0;
  const int32 MODE_CBC = 1;
  const int32 MODE_CTR = 2;
  const int32 MODE_XTS = 3;
  const int32 MODE_CCM = 4;
  const int32 MODE_CTS = 5;
  const int32 MODE_INVALID = -1;

  const int32 PAD_ISO10126 = 0;
  const int32 PAD_PKCS7 = 1;
  const int32 PAD_NO_PAD = 2;
  const int32 PAD_INVALID = -1;

  const int32 AES_BLOCK_SZ = 0x10;

  /** this is pipe number allowed, they are abstracted to hide detailed number. */
  const int32 BAM_PIPE_GENERIC    = 0;    // generic use case
  const int32 BAM_PIPE_CPB_CPB    = 1;    // used for copy
  const int32 BAM_PIPE_HLOS_CPB   = 2;    // video use case
  const int32 BAM_PIPE_CPB_HLOS   = 3;    // HDMI use case
  const int32 BAM_PIPE_HLOS_HLOS  = 4;    // DRM Audio use case

  const int32 PIPE_ENCRYPT = 0;
  const int32 PIPE_DECRYPT = 1;

  const int32 EVEN_KEY = 0;
  const int32 ODD_KEY = 1;

  /** Returned when HW does not support the feature being requested */
  error NOT_SUPPORTED;

  /** @endcond */

  /**
    Modifies the 32-bit unsigned int parameters for a cipher context.

    @param[in] paramID     Parameter to modify.
    @param[in] param       Parameter value to set.

    @return
    Object_OK -- Successful. \n
    Object_ERROR_INVALID -- Invalid parameter encountered. \n
    Object_ERROR -- Any other error encountered.
  */
  method setParamAsU32(in int32 paramID, in uint32 param);

  /**
    Retrieves parameters from a cipher context as 32-bit unsigned int.

    @param[in]  paramID    Parameter to retrieve.
    @param[out] param      Memory location in which to store the parameter.

    @return
    Object_OK -- Successful. \n
    Object_ERROR_INVALID -- Invalid parameter encountered. \n
    Object_ERROR -- Any other error encountered.
  */
  method getParamAsU32(in int32 paramID, out uint32 param);

  /**
    Modifies parameters for a cipher context.

    @param[in] paramID     Parameter to modify.
    @param[in] param       Parameter value to set.

    @return
    Object_OK -- Successful. \n
    Object_ERROR_INVALID -- Invalid parameter encountered. \n
    Object_ERROR -- Any other error encountered.
  */
  method setParamAsData(in int32 paramID, in buffer param);

  /**
    Retrieves parameters from a cipher context.

    @param[in] paramID     Parameter to retrieve.
    @param[out] param      Memory location in which to store the parameter.

    @return
    Object_OK -- Successful. \n
    Object_ERROR_INVALID -- Invalid parameter encountered. \n
    Object_ERROR -- Any other error encountered.
  */
  method getParamAsData(in int32 paramID, out buffer param);

  /**
    Encrypts the passed plaintext message using the specified algorithm.

    @param[in]  plain          Input plaintext buffer.
    @param[out] cipher         Output ciphertext buffer.

    @detdesc
    The memory allocated for the ciphertext must be large enough to hold the
    plaintext equivalent. If a padding scheme is selected the ciphertext buffer
    length may need to be up to one block size larger than the plaintext length.
    If the output buffer is not large enough to hold the encrypted results,
    an error is returned.

    @return
    Object_OK -- Successful. \n
    Object_ERROR_INVALID -- Not multiple of block length. \n
    Object_ERROR -- Any other error encountered.
  */
  method encrypt(in buffer plain, out buffer cipher);

  /**
    Decrypts the passed ciphertext message using the specified algorithm.

    @param[in]  cipher             Input ciphertext buffer.
    @param[out] plain              Output plaintext buffer.

    @detdesc
    The memory allocated for plaintext must be large enough to hold the
    ciphertext equivalent. If a padding scheme is selected, the plaintext output
    length may be up to one block size smaller than the ciphertext length.
    If the output buffer is not large enough to hold the decrypted results,
    an error is returned.

    @return
    Object_OK -- Successful. \n
    Object_ERROR_INVALID -- Not multiple of block length. \n
    Object_ERROR -- Any other error encountered.
  */
  method decrypt(in buffer cipher, out buffer plain);

  /**
    Resets cipher context; does not reset the key.

    @return
    Object_OK -- Successful. \n
    Object_ERROR -- Any error encountered.
  */
  method reset();

  /** @} */ /* end_addtogroup ICipher */
};