Metadata-Version: 2.4
Name: kveynar
Version: 0.3.0
Summary: Kveynar - chiffre authentifie original (portage Python), par Memet Jakupi.
Author: Memet Jakupi
License: MIT
Project-URL: Homepage, https://github.com/uScyt/kveynar
Project-URL: Repository, https://github.com/uScyt/kveynar
Keywords: cipher,encryption,aead,obfuscation,kveynar
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# Kveynar — Python port

[![CI](https://github.com/uScyt/kveynar/actions/workflows/ci.yml/badge.svg)](https://github.com/uScyt/kveynar/actions/workflows/ci.yml)

**Author: Memet Jakupi** — digital forensics researcher.

A **faithful** Python port of the reference Rust implementation. It reproduces
[`../rust/vectors/kat.json`](../rust/vectors/kat.json) **byte for byte** (interoperability
test): a message encrypted by Rust decrypts in Python and vice versa.

The common specification is [`../rust/SPEC.md`](../rust/SPEC.md); the honest security analysis
is in [`../rust/DESIGN.md`](../rust/DESIGN.md).

> ## Warning
> A home-grown cipher intended for educational / obfuscation / CTF use. Hardened and tested,
> but not publicly audited. Do not use it alone against a state-level adversary.

> ## Performance note
> This port favours **readability**, not speed. The KDF is *memory-hard*: at the default
> factor (2^17 = 16 MiB) it is slow in pure Python. For quick trials, lower the memory factor
> (`--mem 12` or `with_work_factor(key, 12)`). The Rust implementation remains the performant
> version.

## Usage (library)

```python
from kveynar import Kveynar, encrypt_decoy, decrypt_decoy

kv = Kveynar.with_work_factor("my private key".encode(), 12)
c = kv.encrypt("Pershendetje, bote!".encode())
assert kv.decrypt(c).decode() == "Pershendetje, bote!"

# associated data, text armor, source obfuscation
kv.encrypt_with_ad(b"body", b"public-header")
kv.encrypt_armored(b"data")
kv.obfuscate_source("def f(): return 42")

# "bare" container (no signature) and disguised armors
kv.encrypt_bare(b"looks like random bytes")
kv.encrypt_skin(b"data", "emoji")  # or "mnemonic" / "drita"

# fortress mode (Gjarper + Bora cascade, 100% in-house)
fort = Kveynar.fortress_with_work_factor("key".encode(), 14)

# weak plausible-deniability decoy (two compartments; see ../rust/DESIGN.md section 8bis)
blob = encrypt_decoy(kv, b"real message", fort, b"decoy")
```

| Method | Description |
|---|---|
| `new(pass)` / `with_work_factor(pass, log2_mem)` | context (**memory** KDF factor) |
| `fortress(...)` / `fortress_with_work_factor(...)` / `set_cascade(bool)` | cascade mode |
| `encrypt` / `decrypt` (+ `_with_ad`) | binary `.kvy` container (AEAD) |
| `encrypt_with_params(pt, ad, kripa, fara)` | deterministic encryption (advanced/tests) |
| `encrypt_bare_with_params(pt, kripa, fara)` | deterministic bare encryption (advanced/tests) |
| `encrypt_bare` / `decrypt_bare` | headerless container, header **whitened** ⇒ byte-uniform (obfuscation only) |
| `encrypt_skin` / `decrypt_skin` | disguised armor (`mnemonic` / `emoji` / `drita`) |
| `encrypt_armored` / `decrypt_armored` | text output (Drita armor) |
| `obfuscate_source` / `deobfuscate_source` (+ `_bytes`) | code obfuscation |
| `encrypt_decoy` / `decrypt_decoy` (module functions) | **weak** plausible-deniability decoy |

## Command line

```sh
python -m kveynar enc   -k "my key" --mem 14 secret.txt -o secret.kvy
python -m kveynar enc   -k "my key" --fortress secret.txt -o secret.kvy
python -m kveynar enc   -k "my key" --bare secret.txt -o secret.kvy        # bare container
python -m kveynar dec   -k "my key" secret.kvy -o secret.txt               # mode auto-detected
python -m kveynar obf   -k "my key" --skin emoji app.py -o app.py.kvy
python -m kveynar deobf -k "my key" --skin emoji app.py.kvy -o app.py
```

Key also via `--key-file <file>` or the `KVEYNAR_KEY` environment variable.

## Tests

```sh
# from the repository root
set PYTHONPATH=python   &  python -m unittest discover -s python/tests -t python   # Windows cmd
PYTHONPATH=python python -m unittest discover -s python/tests -t python            # bash
```

`test_vectors.py` proves **byte-for-byte interoperability with Rust**.

## Structure

```
python/
  kveynar/
    __init__.py     public API (Kveynar class) + bare/skin/decoy
    _u64.py         64-bit arithmetic (mod 2^64)
    _consts.py      constants (forge, IV, RC, ODD, NUMS scalars, rotations, Drita alphabet)
    _vala.py        Vala permutation + sponge
    _kdf.py         Celesi (memory-hard KDF, Mundimi, Argon2id-like)
    _gjarper.py     invertible primary block
    _bora.py        second block (cascade mode)
    _blockutil.py   shared block helper (read4)
    _cipher.py      mode of operation + Vula MAC + container (+ bare)
    _armor.py       Drita base64 armor
    _skin.py        disguised armors (mnemonic / emoji)
    _obfuscate.py   source-obfuscation wrapper
    _rng.py         system randomness (os.urandom)
    errors.py       KveynarError exceptions
    __main__.py     CLI tool
  tools/            gen_constants.py (NUMS constant generator/verifier)
  tests/            test_vectors (KAT interop), roundtrip, tamper, nondeterminism,
                    min_mem, constants, deniable
  examples/         basic, file_encrypt, obfuscate_source
  pyproject.toml
```

## License

MIT.
