rtty-soda 0.1.2__py3-none-any.whl

rtty_soda/encoders/base26_encoder.py

@@ -0,0 +1,19 @@
+import string
+
+from nacl.encoding import _Encoder as EncoderABC  # pyright: ignore [reportPrivateUsage]
+
+from .functions import base_to_bytes, bytes_to_base, decode_bytes, encode_str
+
+__all__ = ["ALPHABET", "Base26Encoder"]
+
+ALPHABET = string.ascii_uppercase
+
+
+class Base26Encoder(EncoderABC):
+    @staticmethod
+    def encode(data: bytes) -> bytes:
+        return encode_str(bytes_to_base(data, ALPHABET))
+
+    @staticmethod
+    def decode(data: bytes) -> bytes:
+        return base_to_bytes(decode_bytes(data), ALPHABET)

rtty_soda/encoders/base36_encoder.py

@@ -0,0 +1,19 @@
+import string
+
+from nacl.encoding import _Encoder as EncoderABC  # pyright: ignore [reportPrivateUsage]
+
+from .functions import base_to_bytes, bytes_to_base, decode_bytes, encode_str
+
+__all__ = ["ALPHABET", "Base36Encoder"]
+
+ALPHABET = string.digits + string.ascii_uppercase
+
+
+class Base36Encoder(EncoderABC):
+    @staticmethod
+    def encode(data: bytes) -> bytes:
+        return encode_str(bytes_to_base(data, ALPHABET))
+
+    @staticmethod
+    def decode(data: bytes) -> bytes:
+        return base_to_bytes(decode_bytes(data), ALPHABET)

rtty_soda/encoders/base94_encoder.py

@@ -0,0 +1,17 @@
+from nacl.encoding import _Encoder as EncoderABC  # pyright: ignore [reportPrivateUsage]
+
+from .functions import base_to_bytes, bytes_to_base, decode_bytes, encode_str
+
+__all__ = ["ALPHABET", "Base94Encoder"]
+
+ALPHABET = "".join([chr(i) for i in range(33, 127)])
+
+
+class Base94Encoder(EncoderABC):
+    @staticmethod
+    def encode(data: bytes) -> bytes:
+        return encode_str(bytes_to_base(data, ALPHABET))
+
+    @staticmethod
+    def decode(data: bytes) -> bytes:
+        return base_to_bytes(decode_bytes(data), ALPHABET)

rtty_soda/encoders/functions.py

@@ -0,0 +1,48 @@
+__all__ = ["base_to_bytes", "bytes_to_base", "decode_bytes", "encode_str"]
+
+
+def encode_str(data: str) -> bytes:
+    return data.encode(encoding="utf-8", errors="strict")
+
+
+def decode_bytes(data: bytes) -> str:
+    return data.decode(encoding="utf-8", errors="strict")
+
+
+def int_to_base(number: int, alphabet: str) -> str:
+    result: list[str] = []
+    base = len(alphabet)
+    abs_number = abs(number)
+    while abs_number:
+        abs_number, remainder = divmod(abs_number, base)
+        result.append(alphabet[remainder])
+
+    return "".join(reversed(result))
+
+
+def base_to_int(source: str, alphabet: str) -> int:
+    number = 0
+    base = len(alphabet)
+    for index, digit in enumerate(reversed(source)):
+        number += alphabet.index(digit) * (base**index)
+
+    return number
+
+
+def bytes_to_base(source: bytes, alphabet: str) -> str:
+    number = int.from_bytes(source, byteorder="big", signed=False)
+    return int_to_base(number, alphabet)
+
+
+def int_to_bytes(number: int) -> bytes:
+    buffer = bytearray()
+    while number:
+        buffer.append(number & 0xFF)
+        number //= 256
+
+    buffer.reverse()
+    return bytes(buffer)
+
+
+def base_to_bytes(source: str, alphabet: str) -> bytes:
+    return int_to_bytes(base_to_int(source, alphabet))

rtty_soda/main.py

@@ -0,0 +1,318 @@
+# ruff: noqa: PLR0913 - not applicable because we don't call Click Commands directly
+# ruff: noqa: ANN201 - not applicable because the Click Commands are untyped
+# mypy: disable-error-code = "no-untyped-def, misc"
+from pathlib import Path
+
+import click
+from click_aliases import ClickAliasedGroup
+from nacl.public import PrivateKey, PublicKey
+
+from rtty_soda.archivers import ARCHIVERS, UNARCHIVERS
+from rtty_soda.cli_io import (
+    print_stats,
+    read_bytes,
+    read_ciphertext_bytes,
+    read_clean_bytes,
+    read_plaintext_bytes,
+    write_output,
+)
+from rtty_soda.cryptography import public, secret
+from rtty_soda.cryptography.kdf import KDF_PROFILES, kdf
+from rtty_soda.encoders import ENCODERS, RawEncoder
+
+in_path = click.Path(
+    exists=True,
+    file_okay=True,
+    dir_okay=False,
+    readable=True,
+    allow_dash=True,
+    path_type=Path,
+)
+
+out_path = click.Path(
+    file_okay=True, dir_okay=False, writable=True, allow_dash=True, path_type=Path
+)
+
+CONTEXT_SETTINGS = {"help_option_names": ["-h", "--help"]}
+
+
+@click.group(cls=ClickAliasedGroup, context_settings=CONTEXT_SETTINGS)
+@click.version_option(package_name="rtty-soda")
+def cli():
+    pass
+
+
+@cli.command()
+@click.option("--encoding", "-e", default="base64", show_default=True)
+def genkey_cmd(encoding: str):
+    """Generate Private Key.
+
+    Encoding: base26 | base36 | base64 | base94
+    """
+    enc = ENCODERS[encoding]
+    key = PrivateKey.generate()
+    click.echo(key.encode(enc))
+
+
+@cli.command()
+@click.argument("private_key_file", type=in_path)
+@click.option("--encoding", "-e", default="base64", show_default=True)
+def pubkey_cmd(private_key_file: Path, encoding: str):
+    """Get Public Key.
+
+    Encoding: base26 | base36 | base64 | base94
+    """
+    enc = ENCODERS[encoding]
+    key = read_clean_bytes(private_key_file)
+    priv = PrivateKey(key, enc)
+    click.echo(priv.public_key.encode(enc))
+
+
+@cli.command()
+@click.argument("password_file", type=in_path)
+@click.option("--encoding", "-e", default="base64", show_default=True)
+@click.option("--profile", "-p", default="sensitive", show_default=True)
+def kdf_cmd(password_file: Path, encoding: str, profile: str):
+    """Key Derivation Function.
+
+    Encoding: base26 | base36 | base64 | base94
+
+    Profile: interactive | moderate | sensitive
+    """
+    enc = ENCODERS[encoding]
+    prof = KDF_PROFILES[profile]
+    pw = read_bytes(password_file)
+    key = kdf(pw, prof, enc)
+    click.echo(key)
+
+
+@cli.command(aliases=["e"])
+@click.argument("private_key_file", type=in_path)
+@click.argument("public_key_file", type=in_path)
+@click.argument("message_file", type=in_path)
+@click.option("--key-encoding", default="base64", show_default=True)
+@click.option("--data-encoding", "-e", default="base64", show_default=True)
+@click.option("--compression", "-c", default="zlib", show_default=True)
+@click.option("--output-file", "-o", type=out_path, help="(Optional)")
+def encrypt_public_cmd(
+    private_key_file: Path,
+    public_key_file: Path,
+    message_file: Path,
+    key_encoding: str,
+    data_encoding: str,
+    compression: str,
+    output_file: Path | None,
+):
+    """Encrypt Message (Public).
+
+    Encoding: base26 | base36 | base64 | base94 | binary
+
+    Compression: zlib | bz2 | lzma | raw
+    """
+    key_enc = ENCODERS[key_encoding]
+    data_enc = ENCODERS[data_encoding]
+    archiver = ARCHIVERS[compression]
+    priv_bytes = read_clean_bytes(private_key_file)
+    priv = PrivateKey(priv_bytes, key_enc)
+    pub_bytes = read_clean_bytes(public_key_file)
+    pub = PublicKey(pub_bytes, key_enc)
+    data = stats = read_plaintext_bytes(message_file, data_enc)
+    data = archiver(data)
+    data = public.encrypt(private=priv, public=pub, data=data, out_enc=data_enc)
+    write_output(output_file, data, data_enc)
+    print_stats(stats, data)
+
+
+@cli.command(aliases=["es"])
+@click.argument("key_file", type=in_path)
+@click.argument("message_file", type=in_path)
+@click.option("--key-encoding", default="base64", show_default=True)
+@click.option("--data-encoding", "-e", default="base64", show_default=True)
+@click.option("--compression", "-c", default="zlib", show_default=True)
+@click.option("--output-file", "-o", type=out_path, help="(Optional)")
+def encrypt_secret_cmd(
+    key_file: Path,
+    message_file: Path,
+    key_encoding: str,
+    data_encoding: str,
+    compression: str,
+    output_file: Path | None,
+):
+    """Encrypt Message (Secret).
+
+    Encoding: base26 | base36 | base64 | base94 | binary
+
+    Compression: zlib | bz2 | lzma | raw
+    """
+    key_enc = ENCODERS[key_encoding]
+    data_enc = ENCODERS[data_encoding]
+    archiver = ARCHIVERS[compression]
+    key = read_clean_bytes(key_file)
+    data = stats = read_plaintext_bytes(message_file, data_enc)
+    data = archiver(data)
+    data = secret.encrypt(key=key, data=data, key_enc=key_enc, out_enc=data_enc)
+    write_output(output_file, data, data_enc)
+    print_stats(stats, data)
+
+
+@cli.command(aliases=["ep"])
+@click.argument("password_file", type=in_path)
+@click.argument("message_file", type=in_path)
+@click.option("--kdf-profile", "-p", default="sensitive", show_default=True)
+@click.option("--data-encoding", "-e", default="base64", show_default=True)
+@click.option("--compression", "-c", default="zlib", show_default=True)
+@click.option("--output-file", "-o", type=out_path, help="(Optional)")
+def encrypt_password_cmd(
+    password_file: Path,
+    message_file: Path,
+    kdf_profile: str,
+    data_encoding: str,
+    compression: str,
+    output_file: Path | None,
+):
+    """Encrypt Message (Password).
+
+    KDF profile: interactive | moderate | sensitive
+
+    Encoding: base26 | base36 | base64 | base94 | binary
+
+    Compression: zlib | bz2 | lzma | raw
+    """
+    prof = KDF_PROFILES[kdf_profile]
+    data_enc = ENCODERS[data_encoding]
+    archiver = ARCHIVERS[compression]
+    pw = read_bytes(password_file)
+    key = kdf(pw, prof, RawEncoder)
+    data = stats = read_plaintext_bytes(message_file, data_enc)
+    data = archiver(data)
+    data = secret.encrypt(key=key, data=data, key_enc=RawEncoder, out_enc=data_enc)
+    write_output(output_file, data, data_enc)
+    print_stats(stats, data)
+
+
+@cli.command(aliases=["d"])
+@click.argument("private_key_file", type=in_path)
+@click.argument("public_key_file", type=in_path)
+@click.argument("message_file", type=in_path)
+@click.option("--key-encoding", default="base64", show_default=True)
+@click.option("--data-encoding", "-e", default="base64", show_default=True)
+@click.option("--compression", "-c", default="zlib", show_default=True)
+@click.option("--output-file", "-o", type=out_path, help="(Optional)")
+def decrypt_public_cmd(
+    private_key_file: Path,
+    public_key_file: Path,
+    message_file: Path,
+    key_encoding: str,
+    data_encoding: str,
+    compression: str,
+    output_file: Path | None,
+):
+    """Decrypt Message (Public).
+
+    Encoding: base26 | base36 | base64 | base94 | binary
+
+    Compression: zlib | bz2 | lzma | raw
+    """
+    key_enc = ENCODERS[key_encoding]
+    data_enc = ENCODERS[data_encoding]
+    unarchiver = UNARCHIVERS[compression]
+    priv_bytes = read_clean_bytes(private_key_file)
+    priv = PrivateKey(priv_bytes, key_enc)
+    pub_bytes = read_clean_bytes(public_key_file)
+    pub = PublicKey(pub_bytes, key_enc)
+    data = stats = read_ciphertext_bytes(message_file, data_enc)
+    data = public.decrypt(priv, pub, data, data_enc)
+    data = unarchiver(data)
+    write_output(output_file, data, data_enc)
+    print_stats(data, stats)
+
+
+@cli.command(aliases=["ds"])
+@click.argument("key_file", type=in_path)
+@click.argument("message_file", type=in_path)
+@click.option("--key-encoding", default="base64", show_default=True)
+@click.option("--data-encoding", "-e", default="base64", show_default=True)
+@click.option("--compression", "-c", default="zlib", show_default=True)
+@click.option("--output-file", "-o", type=out_path, help="(Optional)")
+def decrypt_secret_cmd(
+    key_file: Path,
+    message_file: Path,
+    key_encoding: str,
+    data_encoding: str,
+    compression: str,
+    output_file: Path | None,
+):
+    """Decrypt Message (Secret).
+
+    Encoding: base26 | base36 | base64 | base94 | binary
+
+    Compression: zlib | bz2 | lzma | raw
+    """
+    key_enc = ENCODERS[key_encoding]
+    data_enc = ENCODERS[data_encoding]
+    unarchiver = UNARCHIVERS[compression]
+    key = read_clean_bytes(key_file)
+    data = stats = read_ciphertext_bytes(message_file, data_enc)
+    data = secret.decrypt(key, data, key_enc, data_enc)
+    data = unarchiver(data)
+    write_output(output_file, data, data_enc)
+    print_stats(data, stats)
+
+
+@cli.command(aliases=["dp"])
+@click.argument("password_file", type=in_path)
+@click.argument("message_file", type=in_path)
+@click.option("--kdf-profile", "-p", default="sensitive", show_default=True)
+@click.option("--data-encoding", "-e", default="base64", show_default=True)
+@click.option("--compression", "-c", default="zlib", show_default=True)
+@click.option("--output-file", "-o", type=out_path, help="(Optional)")
+def decrypt_password_cmd(
+    password_file: Path,
+    message_file: Path,
+    kdf_profile: str,
+    data_encoding: str,
+    compression: str,
+    output_file: Path | None,
+):
+    """Decrypt Message (Password).
+
+    KDF profile: interactive | moderate | sensitive
+
+    Encoding: base26 | base36 | base64 | base94 | binary
+
+    Compression: zlib | bz2 | lzma | raw
+    """
+    prof = KDF_PROFILES[kdf_profile]
+    data_enc = ENCODERS[data_encoding]
+    unarchiver = UNARCHIVERS[compression]
+    pw = read_bytes(password_file)
+    key = kdf(pw, prof, RawEncoder)
+    data = stats = read_ciphertext_bytes(message_file, data_enc)
+    data = secret.decrypt(key, data, RawEncoder, data_enc)
+    data = unarchiver(data)
+    write_output(output_file, data, data_enc)
+    print_stats(data, stats)
+
+
+@cli.command()
+@click.argument("in_encoding")
+@click.argument("out_encoding")
+@click.argument("file", type=in_path)
+@click.option("--output-file", "-o", type=out_path, help="(Optional)")
+def encode_cmd(
+    in_encoding: str, out_encoding: str, file: Path, output_file: Path | None
+):
+    """Encode File.
+
+    Encoding: base26 | base36 | base64 | base94 | binary
+    """
+    in_enc = ENCODERS[in_encoding]
+    out_enc = ENCODERS[out_encoding]
+    data = read_ciphertext_bytes(file, in_enc)
+    data = in_enc.decode(data)
+    data = out_enc.encode(data)
+    write_output(output_file, data, out_enc)
+
+
+if __name__ == "__main__":
+    cli()

rtty_soda-0.1.2.dist-info/METADATA

@@ -0,0 +1,254 @@
+Metadata-Version: 2.3
+Name: rtty-soda
+Version: 0.1.2
+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
+Classifier: Operating System :: POSIX
+Classifier: Environment :: Console
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Topic :: Communications
+Classifier: Topic :: Security :: Cryptography
+Classifier: Topic :: Utilities
+Requires-Dist: click>=8.2.1,<9.0.0
+Requires-Dist: click-aliases>=1.0.5,<2.0.0
+Requires-Dist: pynacl>=1.5.0,<2.0.0
+Requires-Python: >=3.13, <4.0
+Project-URL: github, https://github.com/theosaveliev/rtty-soda
+Project-URL: issues, https://github.com/theosaveliev/rtty-soda/issues
+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)
+- Password encryption
+- Text compression (zlib, bz2, lzma)
+- Custom encodings
+
+
+## Installation
+#### Package manager
+
+1. [Install uv](https://docs.astral.sh/uv/getting-started/installation/)
+2. Install rtty-soda:
+   ```
+   % uv tool install rtty-soda
+   ```
+3. Remove rtty-soda:
+   ```
+   % uv tool uninstall rtty-soda
+   ```
+
+#### Docker
+
+```
+% docker run -it --rm -h rtty-soda -v .:/app/host nett/rtty-soda:0.1.2
+% docker run -it --rm -h rtty-soda -v .:/app/host nett/rtty-soda:0.1.2-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=
+```
+
+#### 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 --output-file encrypted
+Plaintext: 239
+Ciphertext: 280
+Overhead: 1.172
+
+% cat encrypted
+xaLTAu3qD/h7cUspHL2HP0HVASovUE84WnWBj+uHgIqNPzxVhUoObILvDlb2WBJqiXmhMHSXpdMBMSiewdXtU9m
+YlNumkJ8qq+pzsBL3Lrrjdg3jdoeMkweyR9xUY2QytR91Qi9Cga5GM5tTO+rHB6yriThUp2XGEQ1Bap358AT8u/
+dJ7dOzaAv2ei5LfgqtlGmetACfXqxG5SunrOqWvmxpi2QI3FqWUkOLUl00Rj/ZnISmZRsDjekKgJcknKit498cL
+7AVUKQA5PxFm4ZN9Q==
+```
+
+#### 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
+
+Plaintext: 239
+Ciphertext: 280
+Overhead: 1.172
+```
+
+
+## Secret Key encryption
+
+Alice and Bob share a key for symmetric encryption:
+
+```
+% soda genkey > shared
+% soda encrypt-secret shared message > encrypted
+Plaintext: 239
+Ciphertext: 280
+Overhead: 1.172
+
+% soda decrypt-secret shared encrypted -o message
+Overwrite the output file? (message) [y/N]: y
+Plaintext: 239
+Ciphertext: 280
+Overhead: 1.172
+```
+
+Another day, they share a password:
+
+```
+% echo qwerty | soda encrypt-password - message -p interactive > encrypted
+Plaintext: 239
+Ciphertext: 280
+Overhead: 1.172
+
+% echo qwerty | soda decrypt-password - encrypted -p interactive > plain
+Plaintext: 239
+Ciphertext: 280
+Overhead: 1.172
+```
+
+
+## Key derivation
+
+The KDF function derives the key from the password.
+It accepts different profiles: interactive, moderate, and sensitive.
+
+```
+% echo qwerty > password
+% time soda kdf password
+jNLXU8/Ne5ZC8KuhDYqPUBg7xrxwv8J6yDJgCcFib9g=
+real	0m7.850s
+user	0m7.386s
+sys	0m0.461s
+
+% time soda kdf password --profile interactive
+HqbvUXflAG+no3YS9njezZ3leyr8IwERAyeNoG2l41U=
+real	0m0.295s
+user	0m0.279s
+sys	0m0.014s
+```
+
+
+## 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
+
+Aside from the default zlib, there are more compression options. \
+For a short message, the raw option provides smaller output.
+For a long text, the bz2 showed the best results. \
+Overall, encrypting a letter into 1.172 letters is a working solution.
+
+```
+% soda encrypt-public alice bob_pub message --compression zlib > /dev/null
+Plaintext: 239
+Ciphertext: 280
+Overhead: 1.172
+% soda encrypt-public alice bob_pub message --compression bz2 > /dev/null
+Plaintext: 239
+Ciphertext: 344
+Overhead: 1.439
+% soda encrypt-public alice bob_pub message --compression lzma > /dev/null
+Plaintext: 239
+Ciphertext: 324
+Overhead: 1.356
+% soda encrypt-public alice bob_pub message --compression raw > /dev/null
+Plaintext: 239
+Ciphertext: 372
+Overhead: 1.556
+```
+
+
+## Encoding
+
+The rtty-soda supports various encodings:
+
+- Base26 (Latin)
+- Base36 (Latin with numbers)
+- Base64 (RFC 3548)
+- Base94 (ASCII printable)
+- Binary
+
+```
+% soda encrypt-public alice bob_pub message --data-encoding base36
+
+67EG0R6HNKWJCVWF76SXDVXBUVR2L1CZ5WNZ2O1GHVM6488OGHZGIVX6GQE19V7VMSHFWOQD09GRIOOFSUXFRVG
+M2UNVG9NN9X2113FA6JNQ8082WQ38YNQ5KUXHB82SD7HK4YHQDODYTA3O8WY93T6EG5ZX5JB9W1IETKC4D7TOHT
+K7ZROL69IYLZVT9MCIPX7V6IX259F4RGC6PRKVNTP8HRLYZZVU4B1V5Y1HZV0AFGLEIPYECEKN7WC7ZL1YVTWJQ
+458E5E9ZK4E731MCFO8USWBHJ7SM9PTK4IP5NFFB28WWS6KVWU9RBV1WL11MT
+
+Plaintext: 239
+Ciphertext: 322
+Overhead: 1.347
+```
+
+
+## Compatibility
+
+During the initial development (versions prior to 1.0.0),
+I can break backwards compatibility.