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

/** @cond */
interface IIPProtector {
/** @endcond */

  /**
   * @addtogroup IIPProtector
   * @{
   */

  /* Error Codes */
  error OUT_OF_MEMORY_ERROR;
  error INVALID_PARAMETER_ERROR;
  error PARSE_HASH_SEGMENT_ERROR;
  error PARAM_NOT_SET_ERROR;
  error PARAM_PREVIOUSLY_SET_ERROR;
  error FEATURE_ID_MISMATCH_ERROR;
  error HASH_SEGMENT_MISMATCH_ERROR;
  error VERIFY_SEGMENT_ERROR;
  error VERIFY_SIGNATURE_ERROR;
  error HASH_ERROR;
  error KEY_ERROR;
  error DECRYPT_ERROR;
  error SEGMENT_UNENCRYPTED_ERROR;
  
  /** @cond */

  /**
   * Parameter IDs for set parameter
   */
  const uint32 FEATURE_ID = 0;
  const uint32 MODULE_SEQ_1 = 1;
  const uint32 MODULE_SEQ_2 = 2;

  /** @endcond */

  /**
    Set parameter needed for ELF decryption/verification.

    @param[in]   param   Parameter ID to set.
    @param[in]   buf     Parameter value to set.

    @detdesc
    Supported params:
    FEATURE_ID     The IP-Protection Feature ID.
                   The value is cross-checked against the
                   value present in the ELF and must be
                   set before calling decryptSegment and
                   verifySignature.

    MODULE_SEQ_1   A signed CRI sequence of maximum size 
                   512 bytes. The value must be set before
                   calling decryptSegment.

    MODULE_SEQ_2   A signed CRI sequence of maximum size 
                   512 bytes. The value must be set before
                   calling decryptSegment.

    @return
    Object_OK on success.
  */
  method setParameter(in uint32 param, in buffer buf);

  /**
    Set Hash Segment. Must be called before calling decryptSegment,
    verifySegment, and verifySignature.

    @param[in]   hashSegment    Hash Segment of ELF.
    @param[in]   numSegments    The number of segments in the ELF.
                                This must correspond to the number
                                of Program Header entries.

    @return
    Object_OK on success.
  */
  method setHashSegment(in buffer hashSegment, in uint32 numSegments);

  /**
    Decrypt segment.

    @param[in]   segmentIndex       Index of the segment in the ELF.
    @param[in]   encryptedSegment   Encrypted segment.
    @param[out]  decryptedSegment   Decrypted segment.

    @return
    Object_OK on success.
  */
  method decryptSegment(in uint32 segmentIndex,
                        in buffer encryptedSegment,
                        out buffer decryptedSegment);

  /**
    Verify unencrypted/decrypted segment against Hash Table present
    in Hash Segment provided via setHashSegment. If ELF is encrypted,
    decryptSegment must have been previously called for the segment
    corresponding to segmentIndex. The segment buffer must contain the
    unencrypted/decrypted segment.

    @param[in]   segmentIndex   Index of the segment in the ELF.
    @param[in]   segment        Unencrypted/decrypted segment to verify.

    @return
    Object_OK on success.
  */
  method verifySegment(in uint32 segmentIndex,
                       in buffer segment);

  /**
    Verify signature of ELF.

    @param[in]   hashSegment           Hash Segment of ELF.
    @param[in]   swid                  Software ID of ELF.
    @param[in]   antiRollbackVersion   Anti-Rollback Version of ELF.

    @return
    Object_OK on success.
  */
  method verifySignature(in buffer hashSegment,
                         in uint32 swid,
                         in uint32 antiRollbackVersion);

  /**
    Get the Public Key corresponding to the provided Feature ID.

    @param[out]   key   Public Key.

    @return
    Object_OK on success.
  */
  method getPublicKey(out buffer key);

  /* @} */ /* end_addtogroup IIPProtector */
};