Investigating Automatic Code Generation for Network Packet Parsing
==================================================================

The data and code contained in this directory has been deposited in support of
the following paper:

    Investigating Automatic Code Generation for Network Packet Parsing
    Stephen McQuistin, Vivian Band, Dejice Jacob, and Colin Perkins
    Proceedings of the 20th International IFIP TC6 Networking Conference,
    Networking 2021, Espoo, Finland, June 21-24, 2021

    IFIP DL: http://dl.ifip.org/db/conf/networking/networking2021/1570702659.pdf

The directory contains three codebases:
    * The Network Protocol Tool (npt)
    * smoltcp-generated, a fork of smoltcp (0.6.0)
    * smoltcp (0.6.0)

The Network Protocol Tool (npt) code is a snapshot (commit
`06b491466bc59b7817795b0e5e652d83a200d4e5`) of an ongoing project hosted at
https://github.com/glasgow-ipl/ips-protodesc-code, where future updates will
also be found. While the code included in this snapshot is functional, and
supports the architecture described in the paper, it is a work-in-progress.
Issues and pull requests opened on the GitHub project will be considered.

The following dependencies are required to run the Network Protocol Tool (npt)
and build the Rust output that it generates:
    * Python 3.7
    * pipenv (tested with version 2020.11.15)
    * rustc (tested with version 1.53.0)
    * cargo (tested with version 1.53.0)

A number of example drafts, which can be successfully parsed by the npt, are
included in the `examples` directory. Instructions for using the npt are
included in the TOOLING-README.md file. The Network Protocol Tool (npt) is
subject to the licence contained in the `LICENCE FILE`.

`smoltcp-generated` contains a fork of smoltcp that has been modified to use
the parser generated by running the Network Protocol Tool on
draft-mcquistin-augmented-tcp-example-01. In addition, we have added a small
utility script for parsing packet captures.

The provided Makefile will typecheck and test the Network Protocol Tool,
generate the packet captures described in the paper, and parse these using
smoltcp-generated.

To begin, run:

    `pipenv install --dev -e .`

This will create a Python virtual environment with the appropriate packages.

Next, run:

    `pipenv shell make`

The output will show the results of the typechecking and tests, including the
output from parsing the generated packet captures.

`smoltcp` is an unmodified copy of smoltcp, included for reference.

smoltcp is released under the zero-clause BSD licence, given in the
LICENCE-0BSD.txt file contained in the `smoltcp` and `smoltcp-generated`
directories.

To allow the output to be more readable, the Makefile suppresses Rust compiler
warnings when building `smoltcp-generated`. This means that
`invalid_doc_attributes` warnings are not shown when compiling with recent
versions of Rust. These warnings are likely to become hard errors in future
versions of Rust, and `smoltcp-generated` (and the included `smoltcp`) may not
build beyond the versions listed in this document.

## Acknowledgements

This work is funded by the UK Engineering and Physical Sciences Research
Council, under grant EP/R04144X/1. See [more information about the
project](FUNDING.md).