Metadata-Version: 2.3
Name: rtty-soda
Version: 0.3.5
Summary: A CLI tool for Unix-like environments to encrypt a RTTY session using NaCl
Keywords: cli,encryption,libsodium,nacl,rtty
Author: Theo Saveliev
Author-email: Theo Saveliev <89431871+theosaveliev@users.noreply.github.com>
License: MIT
Classifier: Development Status :: 4 - Beta
Classifier: Programming Language :: Python :: 3.14
Classifier: Operating System :: POSIX
Classifier: Environment :: Console
Classifier: License :: OSI Approved :: MIT License
Classifier: Topic :: Security :: Cryptography
Classifier: Topic :: Utilities
Requires-Dist: brotli>=1.2.0,<2.0.0
Requires-Dist: pynacl>=1.6.0,<2.0.0
Requires-Dist: scsu>=1.1.1,<2.0.0
Requires-Dist: click>=8.3.0,<9.0.0 ; extra == 'cli'
Requires-Dist: click-aliases>=1.0.5,<2.0.0 ; extra == 'cli'
Requires-Python: >=3.14, <4.0
Project-URL: github, https://github.com/theosaveliev/rtty-soda
Project-URL: issues, https://github.com/theosaveliev/rtty-soda/issues
Provides-Extra: cli
Description-Content-Type: text/markdown

# rtty-soda

A CLI tool for Unix-like environments to encrypt a RTTY session using NaCl.


#### Features

- Public Key encryption (Curve25519-XSalsa20-Poly1305)
- Secret Key encryption (XSalsa20-Poly1305)
- Key derivation (Argon2id-Blake2b)
- Text compression (brotli, zstd, zlib, bz2, lzma)
- Custom encodings:
  - Base26 (Latin)
  - Base31 (Cyrillic)
  - Base36 (Latin with numbers)
  - Base64 (RFC 4648)
  - Base94 (ASCII printable)
  - Binary


## Installation
#### Package manager

1. [Install uv](https://docs.astral.sh/uv/getting-started/installation/)
2. Install rtty-soda:
   ```
   % uv tool install "rtty-soda[cli]"
   ```
3. Remove rtty-soda:
   ```
   % uv tool uninstall rtty-soda
   ```

#### Docker

```
% docker run -it --rm -h rtty-soda -v .:/app/host nett/rtty-soda:0.3.5
% docker run -it --rm -h rtty-soda -v .:/app/host nett/rtty-soda:0.3.5-tools
```


## Getting help

All commands have `[-h | --help]` option.

```
% soda
Usage: soda [OPTIONS] COMMAND [ARGS]...

Options:
  --version   Show the version and exit.
  -h, --help  Show this message and exit.

Commands:
  decrypt-password (dp)  Decrypt Message (Password).
  decrypt-public (d)     Decrypt Message (Public).
  decrypt-secret (ds)    Decrypt Message (Secret).
  encode                 Encode File.
  encrypt-password (ep)  Encrypt Message (Password).
  encrypt-public (e)     Encrypt Message (Public).
  encrypt-secret (es)    Encrypt Message (Secret).
  genkey                 Generate Private Key.
  kdf                    Key Derivation Function.
  pubkey                 Get Public Key.
```

Some commands have aliases, so `% soda encrypt-password ...` and `% soda ep ...`
are equivalent.


## Public Key encryption
#### Key generation

```
% soda genkey | tee alice | soda pubkey - | tee alice_pub
R5xUCEhvkRRwQD+iWo2hV65fIsWucUZtiFJGKy6pTyA=

% soda genkey | tee bob | soda pubkey - | tee bob_pub
woNtqALnGLzp8VBuzJ8T13E4OZRv5YZy6kXMBpV8/mI=

% soda genkey -h
Usage: soda genkey [OPTIONS]

  Generate Private Key.

  Encoding: base26 | base31 | base36 | base64 | base94 | binary

Options:
  -e, --encoding TEXT     [default: base64]
  -o, --output-file FILE  Write output to file.
  --group-len INTEGER     [default: 0]
  --line-len INTEGER      [default: 80]
  --padding INTEGER       [default: 0]
  -v, --verbose           Show verbose output.
  -h, --help              Show this message and exit.
```

#### Encryption

Alice sends the message to Bob:

```
% cat message
A telegraph key is a specialized electrical switch used by a trained operator to
transmit text messages in Morse code in a telegraphy system.
The first telegraph key was invented by Alfred Vail, an associate of Samuel Morse.
(c) Wikipedia

% soda encrypt-public alice bob_pub message | tee encrypted | cut -c 1-80
iphDoXC+WTIqPf5I8KjZ1nGUPV/QgHR3akOStG+m1vPArrpHY5j7Q/NmFcsGq8uRxscz3IFlmSwi32PR

% soda encrypt-public -h
Usage: soda encrypt-public [OPTIONS] PRIVATE_KEY_FILE PUBLIC_KEY_FILE
                           MESSAGE_FILE

  Encrypt Message (Public).

  Encoding: base26 | base31 | base36 | base64 | base94 | binary

  Compression: brotli | zstd | zlib | bz2 | lzma | raw

Options:
  -t, --text                Treat message as text (binary if not specified).
  --key-encoding TEXT       [default: base64]
  -e, --data-encoding TEXT  [default: base64]
  -c, --compression TEXT    [default: brotli]
  -o, --output-file FILE    Write output to file.
  --group-len INTEGER       [default: 0]
  --line-len INTEGER        [default: 80]
  --padding INTEGER         [default: 0]
  -v, --verbose             Show verbose output.
  -h, --help                Show this message and exit.
```

#### Decryption

```
% soda decrypt-public bob alice_pub encrypted
A telegraph key is a specialized electrical switch used by a trained operator to
transmit text messages in Morse code in a telegraphy system.
The first telegraph key was invented by Alfred Vail, an associate of Samuel Morse.
(c) Wikipedia
```


## Secret Key encryption

Alice and Bob share a key for symmetric encryption:

```
% soda genkey > shared
% soda encrypt-secret shared message -o encrypted
% soda decrypt-secret shared encrypted -o message
```

Another day, they share a password:

```
% echo qwerty | soda encrypt-password - message -o encrypted
% echo qwerty | soda decrypt-password - encrypted -o message
```


## Key derivation

The KDF function derives the key from the password.
It accepts different profiles: interactive, moderate, and sensitive.

```
% echo qwerty | soda kdf -
jNLXU8/Ne5ZC8KuhDYqPUBg7xrxwv8J6yDJgCcFib9g=

% soda kdf -h
Usage: soda kdf [OPTIONS] PASSWORD_FILE

  Key Derivation Function.

  Encoding: base26 | base31 | base36 | base64 | base94 | binary

  Profile: interactive | moderate | sensitive

Options:
  -e, --encoding TEXT     [default: base64]
  -p, --profile TEXT      [default: sensitive]
  -o, --output-file FILE  Write output to file.
  --group-len INTEGER     [default: 0]
  --line-len INTEGER      [default: 80]
  --padding INTEGER       [default: 0]
  -v, --verbose           Show verbose output.
  -h, --help              Show this message and exit.
```


## Text compression

That works as follows:
1. The plaintext is compressed with the compression lib
2. The 16-byte MAC and 24-byte nonce are added
3. The result is encoded with Base64, which adds ~25% overhead

```
% soda es shared message -c brotli -t -v > /dev/null
Groups: 0
Plaintext: 238
Ciphertext: 216
Overhead: 0.908
% soda es shared message -c zstd -t -v > /dev/null
Groups: 0
Plaintext: 238
Ciphertext: 276
Overhead: 1.160
% soda es shared message -c zlib -t -v > /dev/null
Groups: 0
Plaintext: 238
Ciphertext: 280
Overhead: 1.176
% soda es shared message -c bz2 -t -v > /dev/null
Groups: 0
Plaintext: 238
Ciphertext: 336
Overhead: 1.412
% soda es shared message -c lzma -t -v > /dev/null
Groups: 0
Plaintext: 238
Ciphertext: 320
Overhead: 1.345
% soda es shared message -c raw -t -v > /dev/null
Groups: 0
Plaintext: 238
Ciphertext: 372
Overhead: 1.563
```

When working with Unicode messages, enabling SCSU encoding can save
up to 15-50% of space. To achieve this, pass the `--text` flag to both
encryption and decryption commands. This instructs rtty-soda to
read the message as text, applying SCSU automatically.


## Encoding

The rtty-soda supports various encodings:

```
% soda encrypt-public alice bob_pub message --data-encoding base36 --group-len 5 --text
7VOZ4 Z1X3S I8N38 TS384 ULSQB 36068 WTWDF KOZCC 25FZE 0JCZJ 32OLV 1QFJG XPFQS
BWY26 EDEYI S04UQ 14VJS I66KA OMY4O RIAXA 820HE 7AYAV CEZGB W27LU 2SYMU SGB9P
QIRK2 U62BI XO81V DZ44T BU880 VUN5A A5FV6 48IG5 NJBTI NLIH0 P13ZP 9CLDL D0RTT
SX92Z T4JYK 3MU87 VNVKU JC1H2 FGDF0 6HLH6 SOY3X VJV3Y FV2W1 NJM
```


## Environment variables

Common options can be set in the environment variables:

```
% cat ~/.soda/ru.env
TEXT=1
KEY_ENCODING=base31
DATA_ENCODING=base31
COMPRESSION=brotli
KDF_PROFILE=sensitive
GROUP_LEN=5
LINE_LEN=69
PADDING=0
VERBOSE=0
```


## Tutorial for the Underground Moscow Museum

```
% docker run -it --rm -h rtty-soda -v .:/app/host nett/rtty-soda:0.3.5-tools

% source ~/.soda/ru.env
% soda genkey | tee 173-закрытый | soda pubkey - | tee 173-публичный
ЖАЯГЭ ШЦДФР ТЮУОЮ ШМЕВР НЬИЛР ИЫФЧД БФГЫП КЮДЫЛ ОРЫКВ СБХЕЫ СУ
% soda genkey | tee 305-закрытый | soda pubkey - | tee 305-публичный
ЙОАРЫ РОЮЩЯ ШВМПФ ЛТЬТЕ ЫПКУС ДЧББЮ ЦХКХА РЖЯМС ХНТИУ ФЙСКВ ЙЛ

% cat телеграмма
Телетайп — стартстопный приёмно-передающий телеграфный аппарат с клавиатурой
как у пищущей машинки, применявшийся также в качестве терминала устройств
вычислительной техники.
Наиболее совершенные телетайпы являются полностью электронными устройствами
и используют дисплей вместо принтера.
(c) Wikipedia

% soda e 173-закрытый 305-публичный телеграмма -v
БДЭПБ КПСХЛ ЕЫБЙТ ВПФКЯ ЖЩГЦР ЦКГЭУ АУКНБ ЦЮОЩЛ РШАЮР УЩРЖФ ИЙДЙТ
ЧЕДКЙ ЫККИЮ ООУОУ КТЩГЬ ЬБЗНА ВЙРВЭ ПУТВЫ ШХМЫЬ ЗГТЗЙ БДЮЯЦ СЯОВБ
ЛЕЫЯН ДУЯЕБ ЬЖУАЬ ШЫНСЗ ЮШИФК ЙИХОС ЬЖЮВЖ ЛРЭЗК ЦШГЩЦ ПФОПЕ ФШАСЖ
ЛИЖТТ РЖЙГК ХАЖКЛ ЖЧЗЕЫ РОСЯЖ НЯПЕР ЕДЦВЗ УМЙЙГ ЗЧХЗЫ КЛАПЗ ЮЩНАЭ
УЫМЧТ ФНЬЯЮ ЕЕЭМФ МПЦЧТ ЛНЦГЭ ЦЯИФШ ШЛЬМЧ ШНЧХЧ ФЦОУЯ ККХЗС ЛОУЫЗ
ЦОЬУН ЗЬБЖК МАЖЭЗ ЮЦМЖК ЭЙЫЩЫ ЯЧЙМШ РЯФЫУ ШЦБНЛ ИЕКВЯ ОЫГЕЙ УВЖЭН
АЭЮНО ЫИЮБЮ ВДХЩВ РЗГЕБ УЦЦЙС НЯЭЬШ ЯИЕЭЙ ГЙАЕЬ ГХЦЮЯ ЖТИБК КЮЛИЯ
ЯСРУД ЕВЫАС КМЛАД ЕВЦЖЙ ИШУХЯ ФЯИЯТ ИВКД
Groups: 84
Plaintext: 302
Ciphertext: 419
Overhead: 1.387
```


## Alternative usage

- Password source
  ```
  % echo 'A line from a book or a poem' | soda kdf - -e base94
  wN/K.@3Q#]Czn4kk3(negX=R|*xvvPQmk'XW$-s
  ```

- WireGuard keyer
  ```
  % echo 'A line from a book or a poem' | soda kdf - -o privkey
  % cat privkey
  thyA4dlQgg93+rQj/evBbBymw82GTwQCh3RJ0I6GOsY=
  % soda pubkey privkey
  ruIUMqbUtyqRVSIBLSGI7AOruE2DLWgTe9o+h7Yktkw=
  % cat privkey | wg pubkey
  ruIUMqbUtyqRVSIBLSGI7AOruE2DLWgTe9o+h7Yktkw=
  ```

- Data store
  
  The `-tools` image features `steganon-cli` to support the following flow:
  
  ![Flow diagram](https://github.com/theosaveliev/rtty-soda/raw/main/diagram/soda.png)

  ```
  % docker run -it --rm -h rtty-soda -v .:/app/host nett/rtty-soda:0.3.5-tools
  % source ~/.soda/bin.env
  % echo decoy > decoy
  % echo password | soda ep - message -o encrypted
  % steganon-cli hide -i cover.png -d "decoy | encrypted" -s "seed1 | seed2" -o stego.png
  % exiftool -TagsFromFile cover.png -all:all -overwrite_original stego.png
  % steganon-cli extract -i stego.png -s "seed1 | seed2" -o "decoy | encrypted"
  % echo password | soda dp - encrypted -o message
  ```


## Compatibility

During the initial development (versions prior to 1.0.0),
I can break backwards compatibility.


## Releases

This project follows a rolling release cycle.
Each version bump represents where I completed a full test cycle.
When testing passes successfully, I commit and release - so every release is a verified stable point.