Metadata-Version: 2.1
Name: apdu-fuzzer
Version: 0.0.1
Summary: APDU fuzzer
Home-page: https://github.com/petrs/APDUFuzzer
Author: Petr Svenda
Author-email: svenda@fi.muni.cz
License: MIT
Description: # Installation
        ## Installation on Debian based Linux
        For the fuzzer to work we need https://github.com/mit-ll/LL-Smartcard and its dependencies:
        
        ```
        git clone https://github.com/mit-ll/LL-Smartcard
        cd LL-Smartcard
        ./install_dependencies.sh
        python2 setup.py install
        ```
        
        ## Installation on MacOS
        
        For the fuzzer to work we need https://github.com/mit-ll/LL-Smartcard and its dependencies:
        
        ```
        brew install swig
        brew install pcsc-lite
        pip install llsmartcard-ph4
        ```
        
        ## Experimental installation with pip
        
        ```
        # Create virtual environment
        python -m venv --upgrade venv
        cd python
        
        # Install all project dependencies
        ../venv/bin/pip install --find-links=. --no-cache .
        
        # Install AFL deps (cython required)
        # Mac:
        brew install afl-fuzz
        
        # Others:
        cd /tmp
        wget http://lcamtuf.coredump.cx/afl/releases/afl-latest.tgz
        tar -xzvf afl-latest.tgz
        cd afl-*
        make
        sudo make install
        
        # Install python dependencies
        ../venv/bin/pip install --find-links=. --no-cache .[afl]
        ```
        
        ## AFL fuzzing
        
        ```
        AFL <-> Client <-> Server <-> Card
        
        +----------------------------------+
        |  AFL                             |
        |  | |                             |                                   +-------------------+
        |  | |          +----------------+ |         +------------------+      |                   |
        |  | |   stdin  |                | |  socket |                  |      | +---+             |
        |  | +----------|     Client     |------------      Server      -------- |-|-|    Card     |
        |  |            |                | |         |                  |      | +---+             |
        |  | +------+   +--------|-------+ |         +------------------+      |                   |
        |  +-| SHM  |------------+         |                                   +-------------------+
        |    +------+                      |
        |                                  |
        +----------------------------------+
        ```
        
        (ascii by https://textik.com/)
        
        Notes:
        
        - Server is started first, connects to the card and listens on the socket for raw data to send to the card.
        Does not process input data in any way.
        
        - Server stores raw responses from the card to the data files.
        
        - Server is able to reconnect to the card if something goes wrong.
        
        - Client is started by AFL. AFL sends input data via STDIN, forking the client with each new fuzz input.
        PCSC does not like forking with AFL this server/client architecture was required.
        
        - Client is forked by the AFL after python is initialized. Socket can be opened either before fork or after the fork.
        After fork is safer as each fuzz input has a new connection but a bit slower. Opening socket before fork also works
        but special care needs to be done on broken pipe exception - reconnect logic is needed. This is not implemented now.
        
        - Client post-processes input data generated by the AFL, e.g., generates length fields, can do TLV, etc.
        
        
        Communication between server/client:
        
        - Client sends `[0, buffer]`. Buffer is raw data structure to be sent to the card. `0` is the type / status
        
        - Server responds with: `status 1B | SW1 1B | SW2 1B | timing 2B | data 0-NB`
        
        ```
        +----+----+----+--------+------------------------+
        |    |    |    |        |                        |
        | 0  | SW | SW | timing |     response data      |
        |    |  1 |  2 |        |                        |
        +----+----+----+--------+------------------------+
        ```
        
        Client then takes response from the socket, and uses modified [python-afl-ph4] to add trace to the shared memory segment
        that is later analyzed by AFL to determine whether this fuzz input lead to different execution trace than the previous one.
        
        Currently the trace bitmap is done in the following way:
        
        ```python
        afl.trace_offset(hashxx(bytes([sw1, sw2])))
        afl.trace_offset(hashxx(timing))
        afl.trace_offset(hashxx(bytes(data)))
        ```
        
        Fowler-Noll-Vo hash function used in `afl.trace_buff` is not very good with respect to the zero buffers. The timing
        was usually not affecting the bitmap so we switched to very fast hash function `hashxx` for the offset computation.
        
        ### Running
        
        Start server sitting on the card:
        
        ```
        python main_afl.py --server
        ```
        
        
        Testing if the client works:
        
        ```
        echo -n '0000' | ../venv/bin/python main_afl.py --client --output ydat.json --log ylog.txt
        cat ylog.txt
        ```
        
        AFL with forking & TCP communication with the server:
        
        ```
        ../venv/bin/py-afl-fuzz -m 500 -t 5000 -o result/ -i inputs/ -- ../venv/bin/python main_afl.py --client --output ydat.json --log ylog.txt
        ```
        
        
        [python-afl-ph4]: https://github.com/ph4r05/python-afl
        
Platform: UNKNOWN
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 2.6
Classifier: Programming Language :: Python :: 2.7
Classifier: Programming Language :: Python :: 3.5
Classifier: Programming Language :: Python :: 3.6
Classifier: Topic :: Security
Provides-Extra: afl
Provides-Extra: dev
