/*===================================================================================
 Copyright (c) 2020, 2021 Qualcomm Technologies, Inc.
 All Rights Reserved.
 Confidential and Proprietary - Qualcomm Technologies, Inc.
 ===================================================================================*/

/**
   Must add these values to Java SDK under "CellularSecurityValues.java" class
   file. These constants are key for passing information back and forth from
   CCS task in modem
**/
interface CellularValues {
    const uint32 THREAT_CATEGORY_UNKNOWN = 1;       /** Unknown threat */
    const uint32 THREAT_CATEGORY_IMSI_LEAK = 2;     /** IMSI(SIM) leak */
    const uint32 THREAT_CATEGORY_IMPRISONER = 3;    /** Imprisoner attack */
    const uint32 THREAT_CATEGORY_DOS = 4;           /** Denial of service */
    const uint32 THREAT_CATEGORY_DOWNGRADE = 5;     /** Downgrade attack */
    const uint32 THREAT_CATEGORY_LOC_TRACKER = 6;   /** Location tracking */
    const uint32 THREAT_CATEGORY_ATTRACTIVE = 7;    /** Attractive attack */
    const uint32 THREAT_CATEGORY_AUTH_PASSED = 8;   /** Passed authentication */

    const uint32 FEATUREID_LEVEL_1     = 605; /** Cellular threat indications */
    const uint32 FEATUREID_LEVEL_0     = 606; /** Cellular Summary Report */
    const uint32 FEATUREID_LEVEL_2     = 607; /** Cellular threat control */
    const uint32 FEATUREID_EFS_CONTROL = 610; /** Cellular EFS POLICY Management */
    const uint32 FEATUREID_NUM_LEVELS  = 4;   /** Max feature IDs */

    const uint32 TOWER_2G = 0; /** Threat applicable to 2G Towers */
    const uint32 TOWER_3G = 1; /** Threat applicable to 3G Towers */
    const uint32 TOWER_4G = 2; /** Threat applicable to 4G Towers */
    const uint32 TOWER_5G = 3; /** Threat applicable to 5G Towers */

    const uint32 REPORT_TYPE_SUMMARY = 0; /** Summary report */

};

/**
   User-defined callback object that receives data from modem. These functions
   cannot be blocked! They must return instantly, so any processing should be
   passed into a handler
*/
interface ICellularSDKListener {

    /**
       Success indication that acts as a receipt of any request; the nonce
       should be used as an identifier of which original request

       @param nonce[in]     The return nonce that is associated with the sent
                            nonce
    */
    method onSuccess(in uint32 nonce);

    /**
       Error indication that indicates any error from any asynchronous point
       throughout the secure channel. Secure Channel is asynchronous and can
       work on different threads, so this is used to get any error down the line
       that may not be indicated on the original thread; the nonce should be
       used as an identifier of which original request.

       @param[in]  nonce   The return nonce that is associated with the sent
                           nonce
       @param[in]  error   Asynchronous error code of secure channel failure
    */
    method onError(in uint32 nonce, in uint32 error);
};

/**
   User defined callback object that receives asynchronous Trusted Location
   data. This object with one function definition is passed into all TLOC
   requests and gives the user up-to-date Trusted Location information.
*/
interface ITLOCListener {

    /**
       Success indication of a successful Trusted Location query that gives a
       currently generated up-to-date Trusted Location report.

       @param[in]   tloc_data   Trusted Location data in EAT encoded format
    */
    method onTrustedLocationSuccess(in buffer tloc_data);
};

/**
   Connection Security is service-based solution for wireless security. This
   particular service in Trustzone allows for secure communication between
   the HLOS client and the modem task, which controls cellular security measures
   and receives indications and reports. Clients can use this pathway in order
   to have an encrypted, secure channel to talk with modem, verifying with
   integrity that the messages have not been modified or read by anything else.
*/
interface IConnSec {

    /**
       Errors start at 10! Various errors communicating failure points in
       Connection Security
    */

    /** Error attempting to encode */
    error ENCODER_ERROR;

    /* No license features available in certificate at all */
    error LICENSE_FEATURE_NOT_AVAILABLE_ERROR;

    /* Secure Channel is not available for modem communication */
    error TZSC_NOT_AVAILABLE_ERROR;

    /* Invalid argument passed in */
    error INVALID_ARGUMENT_ERROR;

    /* Unable to allocate to heap */
    error HEAP_ALLOCATION_ERROR;

    /* Trusted Location unavailable */
    error TLOC_UNAVAILABLE_ERROR;

   /**
      Initial Connection Pathway. connect() must be called before any other
      method can be called, otherwise other methods will throw an error.

      @param nonce[in]          Nonce for connect() packet
      @param licenseCert[in]    License passed in for feature verification
      @param handler[in]        Callback object defined by HLOS service to
                                receive packets asynchronously from Trustzone
      @param featureList[out]   Enabled FeatureID list in bitmask form:
                                Example: FeatureList[0] = 607
                                         FeatureList[1] = 608

      @return Object_OK (0) or IConnSec specific error code
    */
    method connect(in uint32 nonce, in buffer licenseCert,
                   in ICellularSDKListener handler, out uint32[] featureList);

    /**
       Disable Countermeasures on modem

       @param nonce[in]             Nonce for disableCounterMeasures() packet
       @param cellType[in]          Type of cell generation age (ie 2, 3, 4, 5G)
       @param threats[in]           List of threats to disable specifically;
       @param threat_intensity[in]  Intensity of threats to disable to;
                                    0 for completely disabled

       @return Object_OK (0) or IConnSec specific error code
    */
    method disableCounterMeasures(in uint32 nonce,
                                  in uint32 cellType,
                                  in uint8[] threats,
                                  in uint8[] threatIntensity);

    /**
       Disable Legacy Countermeasures on modem

       @param nonce[in]     Nonce for setLegacyCounterMeasures() packet
       @param features[in]  Features to disable

       @return Object_OK (0) or IConnSec specific error code
    */
    method setLegacyCounterMeasures(in uint32 nonce, in uint8[] features);

    /**
      Reset countermeasures to modem default

      @param nonce[in]      Nonce for resetToDefault() packet

      @return Object_OK (0) or IConnSec specific error code
    */
    method resetToDefault(in uint32 nonce);

    /**
      Generates a report of a particular type to save in Connection Security
      cache

      @param nonce[in]      Nonce for generateReport() packet
      @param reportType[in] Type of report to generate and save in cache

      @return Object_OK (0) or IConnSec specific error code
    */
    method generateReport(in uint32 nonce, in uint32 reportType);

    /**
      Pulls the generated report from the IConnSec cache

      @param handler[in]    Replacement handler for any future report
                            notifications
      @param reportType[in] CellularValues defined report type to pull from
                            cache
      @param report[out]    Buffer data of report, stored in standardized EAT
                            format
      @param status[out]    Status of report when generated from modem. Could
                            have CellularValues error code.

      @return Object_OK (0) or IConnSec specific error code

    */
    method getReport(in ICellularSDKListener handler,
                     in uint32 reportType,
                     out buffer report,
                     out int32 status);

    /**
      Requests Trusted Location data in licensed pathway. This method does not
      require a connect() call, and it is unusable by non-Trusted Apps.

      @param tlocListener[in]   Trusted Location Listener object that must be
                                user-defined to receive TLOC indications. A null
                                object is not valid.
      @param timer_seconds[in]  Number of seconds to wait for TLOC request to
                                timeout. On timeout, if available, it will
                                return cached location.
      @param license[in]        License to check to see if TLOC feature ID is
                                enabled.
    */
    method generateTrustedLocation(in ITLOCListener tlocListener,
                                   in uint8 timer_seconds,
                                   in buffer license);

    /**
      Sets the Modem Celluar Connection Security EFS Int value
      @param nonce[in]        Nonce for ssgccsSetPolicyMgmtInt() packet
      @param subopcode[in]    Modem subopcode data
      @param subscriber[in]   Modem subscriber ID
      @param val[in]          Modem EFS configuration value

      @return Object_OK (0) or IConnSec specific error code

    */
    method ssgccsSetPolicyMgmtInt(in uint32 nonce,
                                  in uint16 subopcode,
                                  in uint8 subscriber,
                                  in int32 val);
    /**
      Sets the Modem Celluar Connection Security EFS string configuration
      @param nonce[in]        Nonce for ssgccsSetPolicyMgmtStr() packet
      @param subopcode[in]    Modem subopcode data
      @param subscriber[in]   Modem subscriber ID
      @param val[in]          Modem EFS configuration value

      @return Object_OK (0) or IConnSec specific error code

    */
    method ssgccsSetPolicyMgmtStr(in uint32 nonce,
                                  in uint16 subopcode,
                                  in uint8 subscriber,
                                  in uint8[] val);
};
