tsdecrypt/FILTERING

tsdecrypt EMM filtering support
===============================
tsdecrypt have no specific knowledge about EMMs of each of the
supported CA systems. This allows tsdecrypt to work even when
the CA system is unknown. It just sends the EMM/ECM streams to the
CAMD server for processing and filtering. The lack of specific
knowledge about each of the supported CA systems is a feature.

However there are cases where limiting the number of EMMs that
reach CAMD is a must have feature. Since there is no code in
tsdecrypt to detect whether the EMM type is GLOBAL, SHARED,
UNIQUE, there is no detection of provider IDs, channel IDs or
card numbers a simpler approach to filtering was implemented.

The basic idea was implemented by Julian Gardner in his emm-buffer-mask
patches. These patches were never merged in tsdecrypt but they
inspired the current filtering implementation.

tsdecrypt's EMM filters describe whether EMM should be processed
or not based on an offset and data bytes that are compared with the
incoming EMM.

The option responsible for defining EMM filters is --emm-filter (-a)
followed by the filter definition. Up to 16 filters can be defined.

Filter definitions
==================
Filter definition contain command and command settings. The command
and the settings are separated by / (forward slash) symbol, the
settings are separated by ^ symbol.

  Command  Settings
  -------  --------
  command[/setting1=abc,setting2=xyz...]

Since filter definitions are passed as command line parameters, you must
ensure that they are enclosed in quotes if they contain spaces.

Filter commands
===============
Currently defined commands are:

   accept_all    - Set the default to allow all EMMs to reach CAMD except
                   EMMs that match "reject" command.

                   When no "accept_all" or "reject_all" commands were used it
                   is assumed that "accept_all" was the first command.

   reject_all    - Set the default to skip all EMMs except those that
                   are accepted by "accept" command.

   * Both "accept_all" and "reject_all" can be used without command settings.

   accept        - This command instructs tsdecrypt to allow EMM that matches
                   the definition to be processed.

   reject        - This command instructs tsdecrypt to skip EMM that matches
                   the definition to be processed.

   * Both commands must have at least two settings (offset and data).

Filter settings
===============
Currently defined command settings are:

 * name=X        - Sets the filter name (used when displaying filters).
                   The name can not be longer than 32 symbols.

 * offset=X      - Sets the offset at which data bytes would be checked
                   against EMM. The default offset is 0.

 * data=XX YY ZZ - Data bytes are series of hex numbers separated by
                   space " " or dot ".". When data bytes are processed 0x
                   prefix is removed from them. The maximum data bytes is 16.

Filter processing
=================
Filters are processed one by one until "accept" or "reject" filter matches.
If no "accept" or "reject" filters match, then the default match determined
by "accept_all" or "reject_all" is returned.

Example filters
===============

  Bulcrypt white list example:
    Accept all EMMs except those starting with 8a 70 b4, 8b 70 b4, 8c or 8d.

       tsdecrypt ... \
         --emm-filter accept_all \
         --emm-filter "reject/name=Bulcrypt_unknown_EMMs,offset=0,data=8a 70 b4" \
         --emm-filter "reject/name=Bulcrypt_unknown_EMMs,offset=0,data=8b 70 b4" \
         --emm-filter "reject/name=Some EMM,data=0x8c" \
         --emm-filter reject/data=0x8d \

  Bulcrypt black list example:
    Reject all EMMs that don't start with 82, 84 or 85.

      tsdecrypt ... \
        --emm-filter reject_all \
        --emm-filter accept/name=Bulcrypt_EMMs,offset=0,data=82 \
        --emm-filter accept/name=Bulcrypt_EMMs,data=84 \
        --emm-filter accept/name=Bulcrypt_EMMs,data=85 \

  Example combination that builds white/black list.
    Accept EMMs that start with 8a and 8b also accept EMMs which have
    70 b4 at offset 1, and reject everything else.

      tsdecrypt ... \
        --emm-filter accept_all \
        --emm-filter reject/name=Bulcrypt_unknown_EMMs,data=8a \
        --emm-filter reject/name=Bulcrypt_unknown_EMMs,data=8b \
        --emm-filter reject_all \
        --emm-filter "accept/name=Bulcrypt_EMMs_with_correct_size,offset=1,data=70 b4" \