==================
The Decoder Script
==================

The lidecode script decodes Lawful Interception HI records stored in files or from raw hex. It has a GUI or it can be run from command line.


The Lidecode Application
**********************************
Run the lidecode script to launch the application. Then select a file or enter a hex value:


.. image:: _static/lidecode.PNG
  :width: 400
  :alt: lidecode


Click start:


.. image:: _static/lidecode_result.PNG
  :width: 400
  :alt: lidecode_result


When entering filenames, you can select multiple or use wildcards to match multiple files. You can also select a directory from which all files inside will be decoded. More details in the command line section.


Basic Decoder Command Line Usage
********************************

Simply run with an HI ASN.1 encoded file::

 lidecode hi1.bin
 pSHeader:
   communicationIdentifier:
     deliveryCountryCode: US
     networkIdentifier:
       operatorIdentifier: OPER
   lawfulInterceptionIdentifier: '12345678'
   li-psDomainId: [0, 4, 0, 2, 2, 5, 1, 14]
   sequenceNumber: 0
   timeStamp: ['2019', '12', 08, '21', '25', '49', '691', null]
   timeStampQualifier: timeOfMediation
 payload:
 - hI1-Operation
 - - liActivated
   - communicationIdentifier:
       network-Identifier:
         operator-Identifier: OPER
     domainID: [0, 4, 0, 2, 2, 0, 1, 6]
     lawfulInterceptionIdentifier: '12345678'
     timeStamp:
     - localTime
     - generalizedTime: ['2019', '12', 08, '21', '25', '49', '691', null]
       winterSummerIndication: notProvided


You can specify multiple files::

 lidecode hi1 hi1_2 hi1_3


Use wildcards to decode all matching files::

 lidecode *
 lidecode h*


Decode all files in a directory::

 lidecode directory_name


You can also decode from raw hex::

 lidecode 307ba13b80070400020205010e81083132333435363738a30ca00680044f50455282025553840100851232303139313230383231323534392e363931880102a23ca33aa13880070400020200010681083132333435363738a208a10680044f504552a319a017801232303139313230383231323534392e363931810100
 pSHeader:
   communicationIdentifier:
     deliveryCountryCode: US
     networkIdentifier:
       operatorIdentifier: OPER
   lawfulInterceptionIdentifier: '12345678'
   li-psDomainId: [0, 4, 0, 2, 2, 5, 1, 14]
   sequenceNumber: 0
   timeStamp: ['2019', '12', 08, '21', '25', '49', '691', null]
   timeStampQualifier: timeOfMediation
 payload:
 - hI1-Operation
 - - liActivated
   - communicationIdentifier:
       network-Identifier:
         operator-Identifier: OPER
     domainID: [0, 4, 0, 2, 2, 0, 1, 6]
     lawfulInterceptionIdentifier: '12345678'
     timeStamp:
     - localTime
     - generalizedTime: ['2019', '12', 08, '21', '25', '49', '691', null]
       winterSummerIndication: notProvided


Working with different standards
********************************

There are numerous different standards for Lawful Interception, typically dealing with different technologies.
The lidecode script will by default, try to auto-detect the standard and thus, the decoder to use. It does this by searching
the data for a domain ID (OID) that matches one of the standards. To specify a specific standard, which may speed up
decoding, select the appropriate interface in the GUI or from CLI, use the -I (must be capital I) option. For ETSI TS 102 232-1::

 lidecode -I ETSI232 hi1.bin

To see the list of available standards check the help text::

 lidecode -h
 usage: lidecode [-h]
                [-I {AUTO_DETECT_HI,ETSIV3_HI1,ETSIV3_HI2,3GPP_HI1,3GPP_HI2,3GPP_HI3,3GPP,3GPPCS_HI2,3GPPEPS_HI2,3GPPEPS_HI3,3GPPIMSCONF_HI2,3GPPIMSCONF_HI3,3GPPVOIP_HI3,ETSI232}]
 ...


You can use the LIMC_INTERFACE environment variable to set the default interface to use each time the script is run.


Printing specific attributes
****************************

The default printout format is quite verbose. To print just the attributes you need, you can use the -a or -r option.

For example to print only the timestamp, liid and event_type::

 lidecode hi1.bin -a timestamp,liid,event_type
 Timestamp: 2019-12-08 21:25:49.691000
 Liid: 12345678
 Event Type: liActivated

Or as rows::

 lidecode * -r timestamp,liid,event_type
 2019-12-08 21:25:49.691000      12345678        liActivated
 2020-12-09 21:25:49.691000      12345679        liActivated

For each interface, there are default attributes which can be printed to give a summary of each message. For this, you need to specify an interface but not a list of attributes::

 lidecode -I ETSI232 -r
 2019-12-08 21:25:49.691000      OPER    12345678                0               ETSIV3_HI1      liActivated
 2019-12-09 21:25:49.691000      OPER    12345679                0               ETSIV3_HI1      liActivated

The default attributes in this case are timestamp, operator_id, liid, cin, payload_type and event_type.

To see which attributes are available for each interface, use the -l option::

 lidecode -l ETSI232
 Available attributes for interface standard ETSI232 are:
 encoded, decoded, address, authorization_country_code, byte_counter, cin, cin_or_event_type, content_type, delivery_country_code, description, direction, domain, encoded_hex, encrypted_payload_type, encrypted_payload_type_detailed, encryption_type, event_type, full_receiver, full_sender, interception_point, interface_name, interface_type, is_encrypted, is_tri, liid, network_element_identifier, operator_identifier, payload, payload_hex, payload_info, payload_len, payload_size, payload_sub_objects, payload_type, pformat, receiver, response, sender, sequence_number, sub_domain, sub_event_type, timestamp, timestamp_is_utc, timestamp_qualifier, yaml

You can use the LIMC_ATTRS environment variable to set the default attributes permanently.

These attributes will then be applied every time -a or -r option is used.

In the GUI, select an interface standard and either attributes or row option to print the default attributes for that interface.


Apply filters
*************

You can apply attribute level filters by entering an expression in the Filter section of the GUI, with the -F option (capital F) for the cli. The filter format is "attribute operator value"::

 lidecode hi1 hi1_2 -F "event_type = liActivated"
 lidecode hi1 hi2_2 -F "sequence_number < 10"

Multiple filters can be applied::

 lidecode hi1 hi1_2 -F "liid = 12345678" -F "sequence_number < 10"

There must be spaces around the operator and all options must come after the filenames. You must wrap the filter in "".


Decrypting ETSI TS 102 232-1 Containers
***************************************

The TS ETSI 102 232 standard supports encrypting payloads. To decrypt these payloads provide the decryption key in hex format in the GUI or with the -k option::

 lidecode file_containing_encrypted_data -k 77217A25432A462D4A614E645267556B58703272357538782F413F4428472B4B

Alternatively, the encryption key can be set with the LIMC_KEY environment variable which would be preferable from a security point of view.

Help for lidecode script
************************

Use the -h option to get the full list of command line options::

 lidecode -h

Or -e to see some examples usages::

 lidecode -e