Metadata-Version: 2.1
Name: data-diode
Version: 0.0.4
Summary: Send and receive data over serial diode
Home-page: https://github.com/fionn/diode
Author: Fionn Fitzmaurice
Project-URL: Source Code, https://github.com/fionn/diode
Project-URL: Changelog, https://github.com/fionn/diode/tags
Project-URL: Documentation, https://github.com/fionn/diode/blob/master/README.md
Project-URL: Bug Tracker, https://github.com/fionn/diode/issues
Project-URL: PyPI, https://pypi.org/project/data-diode/
Project-URL: Download, https://github.com/fionn/diode/archive/refs/heads/master.zip
Keywords: diode,data diode
Classifier: Programming Language :: Python :: 3
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Topic :: Security
Classifier: Typing :: Typed
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Requires-Dist: pyserial
Provides-Extra: dev
Requires-Dist: pylint; extra == "dev"
Requires-Dist: mypy; extra == "dev"
Requires-Dist: coverage; extra == "dev"

# Serial Diode

Generic wire protocol and implementation for one-way data transfer over UART serial.

## Usage

### General

The serial device can be specified with `--device` and baudrate with `--baudrate`.
If device is unspecified, it will attempt to guess the correct device based on platform and name.
If baudrate is unspecified, it defaults to 115200 Hz.

See `--help` for detailed usage information.

### Send

Run `diode send <path/to/file>` to send `<file>`.

### Receive

Run `diode listen`, which will listen forever. When it receives a valid payload, it will write it to `out/<file>` where `<file>` was specified in the payload metadata.

Note that on some systems this may need to be run as root to allow access to the serial port.
It is generally preferable to add the user to the appropriate group with something similar to `usermod -a -G uucp <username>`.

## Wire format

    ┌─────┬──────────┬─────────────┬──────┬─────┬───────┐
    │ SOT │ metadata │ data_length │ data │ EXT │ crc32 │
    └─────┴──────────┴─────────────┴──────┴─────┴───────┘

Here:
* `metadata` is 32 bytes,
* `data_length` is 8 bytes,
* `data` is `data_length` bytes,
* `crc32` is 8 bytes,
* `SOT` and `EXT` are the bytes `x02`, `x03`,
* `crc32` is the value of the CRC32 function acting on `metadata || data`.

## Installation

Install in developer mode with `make install_dev && source venv/bin/activate`.

Install as user with `make install`.

Install [from PyPI](https://pypi.org/project/data-diode/) with `pip install data-diode`.

Install Bash completion with `source bash_completion/diode`.

## Testing

Run `make test`.

For ad-hoc testing, `socat -d -d pty,raw,echo=0 pty,raw,echo=0` can be useful to connect two virtual serial devices.
If a physical serial device exists, connect with `screen /dev/<device_name> [<baud_rate>]` where `<baud_rate>` is likely 115200.
