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

/** @cond */
interface IHavenTokenApp {
/** @endcond */

  /**
   * @addtogroup IHavenTokenApp
   * @{
   */

  /** @cond */
  //--------------------------------------------------------
  //  HavenToken
  //--------------------------------------------------------

  /**
   Security Levels to add Data Items.
   */
  const uint32 SIG_SEC_LEVEL_HW                             = 7;                        /** Pure HW, with no SW involved, not even firmware */
  const uint32 SIG_SEC_LEVEL_SEK                            = 6;                        /** Secure Element or equivalent security level. In the kernel or system SW for the secure element */
  const uint32 SIG_SEC_LEVEL_SEU                            = 5;                        /** Secure Element or equivalent security level. A downloaded or installed non-system app. */
  const uint32 SIG_SEC_LEVEL_TEEK                           = 4;                        /** TEE or equivalent security level. In the kernel or system SW for the TEE */
  const uint32 SIG_SEC_LEVEL_TEEU                           = 3;                        /** TEE or equivalent security level. A downloaded or installed non-system app. */
  const uint32 SIG_SEC_LEVEL_RICHOSK                        = 2;                        /** Rich OS or equivalent security level. In the rich OS kernel or system SW. */
  const uint32 SIG_SEC_LEVEL_RICHOSU                        = 1;                        /** Rich OS or equivalent security level. A downloaded or installed non-system app. */

  /**
   This names the attestation key used to sign the token.
   Not all keys are available on all devices and the security of the keys vary.
   */
  const uint32 KEYTYPE_NONE                                 = 0;                        /** No key selected */
  const uint32 KEYTYPE_DEMO                                 = 1;                        /** No-security key suitable for demo and test only. Available on most devices. */
  const uint32 KEYTYPE_GROUPLOW                             = 2;                        /** Low security group key. This is privacy preserving. */
  const uint32 KEYTYPE_GROUP                                = 3;                        /** A privacy-preserving. Key is shared by approximatly 100,000 devices. */
  const uint32 KEYTYPE_PERCHIP                              = 4;                        /** Key is not privacy preserving and may not be available due to Android privacy requirements or other. */
  const uint32 KEYTYPE_RESERVED_1                           = 5;                        /** Key RESERVED_1 is reserved for internal develoment purpose and not to be used by any clients. */
  const uint32 KEYTYPE_RESERVED_2                           = 6;                        /** Key RESERVED_2 is reserved for internal development purpose and not to be used by any clients. */
  const uint32 KEYTYPE_GROUPTEST                            = 7;                        /** Derived Group Key - Test Mode */
  const uint32 KEYTYPE_BEST_PRIVACY_PRESERVING_AVAILABLE    = 8;                        /** Select this key type to opt for best privacy preserving key among all available key types. */
  const uint32 KEYTYPE_QDAK                                 = 9;                        /** QDAK - Non privacy preserving and may not be available on all devices.*/
  const uint32 KEYTYPE_QDAKTEST                             = 10;                       /** QDAK - Non privacy preserving - Test Mode and may not be available on all devices.*/
  const uint32 KEYTYPE_DEMO_NPP                             = 11;                       /** Non privacy preserving key suitable for demo and test only and may not be available on all devices.*/

  /**
   Options to select
   */
  const uint64 OPT_NONE                                     = 0x0000000000000000;       /** No option selected */
  const uint64 OPT_SIMDATA                                  = 0x0000000000000001;       /** Request static simulated data */
  const uint64 OPT_APPCERT                                  = 0x0000000000000002;       /** Include the full signing cert of the calling application */
  const uint64 OPT_LOCATION                                 = 0x0000000000000004;       /** Location is optional */
  const uint64 OPT_LONGRTIC                                 = 0x0000000000000008;       /** Long RTIC Report */
  const uint64 OPT_RTIC_CURRENT                             = 0x0000000000000020;       /** Run RTIC report right now, rather than get most cached; slows down token creation */
  const uint64 OPT_NON_PRIVACY_PRESERVING                   = 0x0000000000000080;       /** This option allows to fetch non privacy preserving devcie ID and will be added to token's data and may not be available on all devices. */
    
  /*
   The cipher suite specifies the algorithms and formats used for signing and encryption.
   Some change in these over time is expected, but it is a goal to keep these to a minimum.
   A ciphersuite style is choosen rather than the ability to pick the four algorithms
   separately to keep things simpler.
   */

  /**
   Ciphersuite 1 is for CMS encryption and it is defined as:
     RSA 2048 bit encryption with OEAP padding in CMS format
     AES 256 is used with CMS

   Ciphersuite 1 is the default and will be selected if no ciphersuite option is passed.
   */
  const uint64 OPT_CIPHER_SUITE_1                           = 0x0000000000000100;
  /**
   Ciphersuite 2 is for COSE encryption and it is defined as:
     RSAES-OAEP w/ SHA-256
     AES-GCM mode w/ 256-bit key, 128-bit tag
   
   Ciphersuite 2 option should be selected if COSE encryption is required.
   */
  const uint64 OPT_CIPHER_SUITE_2                           = 0x0000000000000200;
  /** Ciphersuite 3 is yet undefined */
  const uint64 OPT_CIPHER_SUITE_3                           = 0x0000000000000400;

  //--------------------------------------------------------
  //  HavenLicense
  //--------------------------------------------------------

  /**
   Options to select
   */
  const uint32 LICENSE_OPT_NONE                             = 0x00000000;               /** No option selected */
  const uint32 LICENSE_OPT_NO_OEMID_CHECK                   = 0x00000001;               /** Check the OEM IDs in the cert against the OEM in fuses. Check is not made if flag is not set. */        
  const uint32 LICENSE_OPT_NO_HWVERSION_CHECK               = 0x00000002;               /** Check the HW Versions in the cert against the chip HW version. Check is not made if flag is not set. */
  const uint32 LICENSE_OPT_NO_FEATUREID_CHECK               = 0x00000004;               /** Check the feature ID of the cert against the feature ID passed in. Check is not made if flag is not set. */
  const uint32 LICENSE_OPT_NO_TIME_CHECK                    = 0x00000008;               /** Check the expiration extension of the cert against the current time. Check is not made if flag is not set. */
  const uint32 LICENSE_OPT_CLOCK_NOT_SET_OK                 = 0x00000010;               /** Check the expiration extension of the cert against the current time. Check is not made if flag is not set. */
  const uint32 LICENSE_OPT_SELECT_TEST_ROOT                 = 0x00000020;               /** Selection flag to switch between QTI commercial root or Test root */
  const uint32 LICENSE_OPT_USAGE_ENCRYPT                    = 0x00000040;               /** If this flag is set, then the Havenlicense validates the cert extension key usage value against Key Encipherment.  (2.5.29.15) */
  //--------------------------------------------------------
  //  IHavenTokenApp Error Codes
  //--------------------------------------------------------

  error ERROR_NOMEM;                                                                    /** Heap is exhausted. Cannot continue. The Haven Token data may be too large. The service creating the token in the TEE may be out of memory. */
  error ERROR_SIGNING_KEY_UNAVAIL;                                                      /** The signing key requested doesn't exist or is in accessible. */
  error ERROR_CBOR_ENCODE_ERR;                                                          /** Error creating CBOR encoding, possible due to bad raw CBOR added. */
  error ERROR_CERT_PKHASH;                                                              /** The license certificate is not valid for this PKHash (Device PKHash). */
  error ERROR_INVALID_CERT;                                                             /** The license certificate is corrupt or unparsable. */
  error ERROR_CERT_FEATUREID;                                                           /** The license certificate is not valid for the given feature ID. */
  error ERROR_CERT_EXPIRED;                                                             /** The license certificate is expired. */
  error ERROR_CERT_OEM;                                                                 /** The license certificate is not valid for this OEM (this handset vendor) */
  error ERROR_CERT_HWVERSION;                                                           /** The license certificate is not valid for this HW version (chip familiy) */
  error ERROR_CERT_ISVCERTHASH;                                                         /** The license certificate is not valid for this ISV */
  error ERROR_DATA_MARSHAL;                                                             /** Error in copying added data items to the Haven Token service in the TEE or similar. */
  error ERROR_HASH_GENERATION;                                                          /** Error during generation of hash. */ 
  error ERROR_CERT_NOT_TRUSTED;                                                         /** The root CA is not marked as trusted. */
  error ERROR_CERT_GENERAL_ERR;                                                         /** Error while verifying the cert chain. */
  error ERROR_DATA_TOO_BIG;                                                             /** The data items added are too big to be transferred to the Haven Token service in the TEE or similar. */
  error ERROR_OFFSET_TOO_LARGE;                                                         /** The data items added are too big to be transferred to the Haven Token service in the TEE or similar. */
  error ERROR_OUT_OF_ORDER;                                                             /** Tried to add data after getting the size. */
  error ERROR_NO_DATA;                                                                  /** There is no data to return. */
  error ERROR_RPMB_ERR;                                                                 /** Error while accessing RPMB partition. */
  error ERROR_ENCRYPTION;                                                               /** Error during encryption. */
  error ERROR_NOT_ALLOWED;                                                              /** One of the options selected to generate token is not allowed. Add HAVENT_OPT_SIMDATA to options to resolve this error. */
  error ERROR_LICENSE_TOO_BIG;                                                          /** Given input license certificate is too large to process. */
  error ERROR_PRIVILEGE_ERR;                                                            /** Client App is not having enough privileges for the requested Haven Options. */
  error ERROR_TOO_MUCH_APPDATA;                                                         /** Maximum of 64KB App data can be added to generate a token. Error if it crosses 64KB app data limit. */
  error ERROR_SECURITYLEVEL_NOT_SUPPORTED;                                              /** Trying to add data at a security level that is not allowed. */
  error ERROR_UNSUPPORTED_PAYLOAD_HASH;                                                 /** Requested hash algorithm is not supported. */
  error ERROR_SIGNING_ERR;                                                              /** Error during computation of signature. */
  error ERROR_DEVICE_NOT_SECURE;                                                        /** Device is not secure, SecureBoot is not enabled. */
  error ERROR_GROUPKEY_ERR;                                                             /** Error while using group key. */
  error ERROR_CERT_DEVICEID;                                                            /** The license certificate is not valid for this Device. */
  error ERROR_SFS_ERR;                                                                  /** Error while accessing SFS. */
  error ERROR_CERT_NOTYETVALID;                                                         /** The license certificate is not yet valid. */
  error ERROR_OPTS_NOT_SUPPORTED;                                                       /** One of the options selected to process the license is not supported. */
  error ERROR_KEYSEQ_NOT_SUPPORTED;                                                     /** The selected attestation key is not supported for this HW. */
  error ERROR_KEYMGR_ERR;                                                               /** Error while accessing the attestation key. */
  error ERROR_CERT_PRODUCTID;                                                           /** License is not allowed for the particular PRODUCT/MODEL ID (this Model of handset) */
  /** @endcond */

  //--------------------------------------------------------
  //  Interfaces - HavenToken
  //--------------------------------------------------------

  /**
    Start creating a Haven Token.

    @param[in] uKeySelect   Haven key type.
    @param[in] nOpts        Haven token option flags.
    @param[in] LicenseCert  Buffer containing license certificate.

    @detdesc The License Certificate must chain up to a Haven License root to 
             encrypt the token in a CMS Enveloped Data format.

    @return
    Object_OK if successful.
  */
  method start(in uint32 uKeySelect, in uint64 nOpts, in buffer LicenseCert);

  /**
    Adds any data item, i.e., int, string, maps, arrays.

    @param[in] DataItem  DataItem structure.
    @param[in] Label     Zero-terminated string to tag the item.
    @param[in] Data      Data to add.

    @return
    Object_OK on success.
  */
  method addDataItem(in buffer DataItem, in buffer Label, in buffer Data);

  /**
    Gets full size of the encrypted and signed token.

    @param[out] pnSize  Token size.

    @return
    Object_OK on success.
  */
  method getSize(out uint64 pnSize);

  /**
    Gets the bytes in the token.

    @param[in]  uOffset  Token offset.
    @param[out] pBuffer  Token buffer.

    @detdesc
    Typical use is to get the the size and then call this in a loop with
    a 4KB buffer incrementing the offset by the number of bytes returned
    until all the bytes have been fetched.
    @par
    The caller should keep track of the bytes fetched to know when they
    have got them all.  There is no "end of file" return code.
    @par
    A buffer larger than 4KB may be used with some implementations. If
    the buffer is too large for the underlying IPC mechanism, then an
    error will be returned.
    @par
    An error will be returned if uOffset is not in the range of 0 and the
    size of the token.
    @par
    The token is an encrypted data blob. There is no use for part of a
    token because it cannot be decrypted; therefore, the full token must 
    be fetched.

    @return
    Object_OK on success.
  */
  method getBytes(in uint64 uOffset, out buffer pBuffer);

  /**
    Deinitialize and clean up.

    @return
    Object_OK on success.
  */
  method finish();

  /** @cond */
  //--------------------------------------------------------
  //  Interfaces - HavenLicense
  //--------------------------------------------------------

  /**
    This API sets the time. Apps using Haven features do not need to call this API.

    @param[in] UTCTime UTC time value.

    @return
    Object_OK on success.
  */
  method setTime(in uint64 UTCTime);

  /**
    This API validates a Haven License Certificate. Apps using Haven features do not need to call this API.
    It is used internally by Haven features to validate the licenses automatically.

    @param[in]  LicenseCert
    @param[in]  OptFlags
    @param[in]  IntermediateCert
    @param[in]  FeatureID
    @param[in]  ISVCertHash
    @param[out] Licensee
    @param[out] Issuer
    @param[out] SerialNumber
    @param[out] PublicKey

    @return
    Object_OK on success.
  */
  method processLicense(in buffer LicenseCert, in uint32 OptFlags, in buffer IntermediateCert, in uint32 FeatureID, in buffer ISVCertHash, out buffer Licensee, out buffer Issuer, out buffer SerialNumber, out buffer PublicKey);

  /**
    This API validates a Haven License Certificate. Apps using Haven features do not need to call this API.
    It is used internally by Haven features to validate the licenses automatically.

    @param[in]  LicenseCert
    @param[in]  OptFlags
    @param[in]  IntermediateCert
    @param[in]  FeatureID
    @param[in]  ISVCertHash
    @param[out] Licensee
    @param[out] Issuer
    @param[out] SerialNumber
    @param[out] PublicKey
    @param[out] CalleeID

    @return
    Object_OK on success.
  */
  method processLicense_TEE(in buffer LicenseCert, in uint32 OptFlags, in buffer IntermediateCert, in uint32 FeatureID, in buffer ISVCertHash, out buffer Licensee, out buffer Issuer, out buffer SerialNumber, out buffer PublicKey, out uint64 CalleeID);
  /** @endcond */
  /** @} */ /* end_addtogroup IHavenTokenApp */
};
