/** @file  ICipher.idl */

/* Copyright (c) 2015-2022 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_HW_KEY_OBJECT            = 25;   /**< Should be set through setParamAsObject() */
  const int32 PARAM_PIPE_STATUS              = 26;   /**< Get pipe status (paused or timed out). Pipe must first be set via PARAM_BAM_PIPE */
  const int32 PARAM_FIRST_USE                = 27;   /**< Get time of first use for pipe key. Pipe must first be set via PARAM_BAM_PIPE */
  const int32 PARAM_LAST_USE                 = 28;   /**< Get time of last use for pipe key. Pipe must first be set via PARAM_BAM_PIPE */
  const int32 PARAM_TIME_REMAINING           = 29;   /**< Get time remaining in the pipe timer. Pipe must first be set via PARAM_BAM_PIPE */
  const int32 PARAM_PAUSE_CFG                = 30;   /**< Mask of pause sources (PIPE_KEY_PAUSE_DP values) pipe should detect. Pipe must first be set via PARAM_BAM_PIPE */
  const int32 PARAM_PIPE_PAUSE               = 31;   /**< Set whether pipe should be paused or unpaused. Pipe must first be set via PARAM_BAM_PIPE */
  const int32 PARAM_XCM_TAG                  = 32;   /**< Get/set the tag when using an authenticated encryption scheme */
  const int32 PARAM_VOTE_CLK                 = 33;   /**< Suspend/resume CE Clock */
  const int32 PARAM_KEYSLOT_ID               = 34;   /**< Get the key index for the cipher handle */
  const int32 PARAM_NUM_DRM_KEYSLOTS_AVAIL   = 35;   /**< Get the number of DRM keyslots that are currently available */
  const int32 PARAM_IN_OUT_SID               = 36;   /**< Set the input and output SIDs for a keyslot, upper 16-bit = in sid, lower 16-bit = out sid */
  const int32 PARAM_SET_OP_TYPE              = 37;   /**< Set the type of operation being performed */
  const int32 PARAM_CLEAR_KEY                = 38;   /**< Clear the key installed in the key slot for this handle */
  const int32 PARAM_INVALID                  = -1;

  const int32 SID_HLOS_KERNEL = 60;     /**< CSID 0 */
  const int32 SID_HLOS_USER   = 61;     /**< CSID 1 */
  const int32 SID_TZ          = 62;     /**< CSID 2 */
  const int32 SID_CPB         = 63;     /**< CSID 3 */
  const int32 SID_INVALID     = -1;

  const int32 OP_TYPE_DRM_MULTI_OFFLOAD        = 1;      /**< Multi offload DRM     */
  const int32 OP_TYPE_DRM_TZ                   = 2;      /** TZ data path DRM      */
  const int32 OP_TYPE_DRM_LEGACY_OFFLOAD_PIPE1 = 3;      /** Legacy offload DRM    */
  const int32 OP_TYPE_DRM_LEGACY_OFFLOAD_PIPE3 = 4;      /** Legacy offload DRM    */
  const int32 OP_TYPE_DRM_LEGACY_OFFLOAD_PIPE4 = 5;      /** Legacy offload DRM    */
  const int32 OP_TYPE_DRM_LEGACY_OFFLOAD_PIPE8 = 6;      /** Legacy offload DRM    */
  const int32 OP_TYPE_DRM_LEGACY_OFFLOAD_PIPE9 = 7;      /** Legacy offload DRM    */
  const int32 OP_TYPE_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_GCM      = 6;
  const int32 MODE_GCM_STRM = 7;
  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 the actual pipe numbers. */
  /** These are used as indices to smmu_tz_ce_policy_map_t array which is defined in target specific XML file (ex:settings/kernel/smmu/config/lanai/lanai.xml) */
  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 BAM_PIPE_OFFLOAD_HLOS_CPB   = 5;  // DRM HLOS-Offload Video use case
  const int32 BAM_PIPE_OFFLOAD_HLOS_HLOS  = 6;  // DRM HLOS-Offload Audio use case
  const int32 BAM_PIPE_OFFLOAD_HLOS_CPB_1 = 7;  // HLOS-Offload Secure decrypt use case
  const int32 BAM_PIPE_OFFLOAD_HLOS_CPB_2 = 8;  // HLOS-Offload Secure decrypt use case
  const int32 BAM_PIPE_OFFLOAD_HLOS_CPB_3 = 9;  // HLOS-Offload Secure decrypt use case
  const int32 BAM_PIPE_OFFLOAD_HLOS_CPB_4 = 10;  // HLOS-Offload Secure decrypt use case
  const int32 BAM_PIPE_OFFLOAD_HLOS_HLOS_1  = 11;  // DRM HLOS-Offload Audio use case(wfd audio)
  const int32 BAM_PIPE_OFFLOAD_CPB_HLOS = 12;  // HLOS-Offload Secure encrypt use case(wfd video)

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

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

  /** Pipe pause input should be a mask of pause sources to detect */
  const int32 PIPE_KEY_PAUSE_SW  = 0x1;

  /* Bits in the output param from calling getParamAsU32() with paramID = PARAM_PIPE_STATUS */
  const uint32 PIPE_STATUS_KEY_PAUSE_DETECTED = 0x1;  /**< The pipe has been paused */
  const uint32 PIPE_STATUS_KEY_TIMER_EXPIRED  = 0x2;  /**< The pipe key has expired */

  /* Valid inputs to calling setParamAsU32() with PARAM_PIPE_PAUSE */
  const uint32 PIPE_UNPAUSE = 0; /**< Unpause the context's current pipe */
  const uint32 PIPE_PAUSE = 1;   /**< Generate a pause event */

  /* Valid inputs to calling setParamAsU32() with PARAM_VOTE_CLK */
  const uint32 VOTE_CLK_SUSPEND = 0;  /**< Suspend CE Clock */
  const uint32 VOTE_CLK_RESUME = 1;   /**< Resume CE Clock  */
  const uint32 VOTE_CLK_LOW = 2;   /**< Vote LowSVS for CE Clock  */

  /** Errors */
  error NOT_SUPPORTED;                    /** Returned when HW does not support the feature being requested */
  error HW_MAC_FAILED;                    /** Returned when the MAC value mismatched during final() for the decryption */
  error INV_DATA_UPDATE_ERR;              /** Returned when update() is called after calling final() */
  error INV_FINAL_CALL_ERR;               /** Returned when final() is called after calling final() */
  error INV_AAD_UPDATE_ERR;               /** Returned when update_aad() is called after calling update()/final() */
  error INV_ARG_ERR;                      /** Returned when the API is called with invalid arguments */
  error NO_FREE_KEYSLOTS;                 /** Returned when no more keyslots (of the required type) available */

  /** @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.
    Note: This API does not support GCM and GCM_STRM modes which need to use
          update_aad/update/final APIs.

    @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.
    Note: This API does not support GCM and GCM_STRM modes which need to use
          update_aad/update/final APIs.

    @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();

  /**
    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 setParamAsObject(in int32 paramID, in interface param);

  /**
    Encrypts/Decrypts input buffer [ibuf], saves the cipher/plain text
    to output buffer [obuf] and saves cipher context for further updates.
    The API will update output size on successful return in obuf_lenout.

    @param[in]  ibuf          Input buffer.
    @param[out] obuf          Output buffer.

    @return
    Object_OK -- Successful. \n
    Object_ERROR -- Any error encountered.
  */
  method update(in buffer ibuf, out buffer obuf);

  /**
    Encrypts/Decrypts the last segment of input buffer saved in cipher context
    and saves the cipher/plain text to output buffer [obuf]. The API will
    update output size on successful return in obuf_lenout.

    @param[out] obuf          Output buffer.

    @return
    Object_OK -- Successful. \n
    Object_ERROR -- Any error encountered.
  */
  method final(out buffer obuf);

  /**
    Updates additional authentication data when authenticated
    cipher mode (e.g CCM/GCM) is selected. It returns failure
    for other cipher modes. This API should be called before
    calling update() and final() APIs.

    @param[in]  aad          Input AAD buffer.
    @param[out] obuf         A dummy buffer for the output data.
                             The Crypto HW engine requires that for all AAD data sent to the HW, the same length of data must be read out.
                             So AAD data must be read back from the HW engine using the obuf dummy buffer. And the size of the obuf
                             should not be less than the aad length. In the case of that the user wants to use the same buffer for
                             both in/out buffer, the buffer must not be const.

    @return
    Object_OK -- Successful. \n
    Object_ERROR -- Any error encountered.
  */
  method update_aad(in buffer aad, out buffer obuf);

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