55 lines
2.3 KiB
Markdown
55 lines
2.3 KiB
Markdown
# crypto-core
|
|
|
|
Portable C99 message-encryption core for Komet clients (Flutter and Android),
|
|
built on the vendored [monocypher 4.0.2](third_party/monocypher).
|
|
|
|
* **v2** — per-installation identity keys, X25519 handshake carried as ordinary
|
|
chat messages, Double Ratchet (forward secrecy, post-compromise security),
|
|
envelopes without constant prefixes, chunked file encryption, sealed local
|
|
storage, passphrase-protected device transfer. Formats: [docs/PROTOCOL.md](docs/PROTOCOL.md).
|
|
* **legacy (v1)** — shared-passphrase scheme, kept so old history and group chats
|
|
stay readable.
|
|
|
|
The API is `include/komet_crypto.h`: stateless functions over caller-provided
|
|
buffers, `*_bound()` helpers for sizing, `kc_status` results. The core has no
|
|
RNG — every function that needs randomness takes it as an argument
|
|
(`KC_*_RANDOM_SIZE`). Session state is an opaque blob the caller stores.
|
|
|
|
## Build
|
|
|
|
```sh
|
|
make test # build and run the suite
|
|
make asan # AddressSanitizer + UBSan
|
|
make vectors # regenerate tests/vectors/v2.json
|
|
make fuzz # libFuzzer (needs clang with libFuzzer; Linux in CI)
|
|
tools/build-android.sh
|
|
cmake -S . -B build/cmake && cmake --build build/cmake && ctest --test-dir build/cmake
|
|
```
|
|
|
|
Consumers use CMake `add_subdirectory` (`komet_crypto` shared or
|
|
`komet_crypto_static`) or the Flutter plugin in `flutter/komet_crypto`.
|
|
|
|
## Using it from Komet
|
|
|
|
Komet consumes this repository as a git submodule at `native/crypto-core` and
|
|
depends on the Flutter plugin by path. After cloning Komet:
|
|
|
|
```sh
|
|
git submodule update --init --recursive
|
|
flutter pub get
|
|
```
|
|
|
|
Komet-Android points at a checkout instead, through `komet.crypto.dir` in its
|
|
`gradle.properties`, and builds the C sources with `add_subdirectory`.
|
|
|
|
## Threat model in one paragraph
|
|
|
|
The MAX server is the adversary: it stores every message, can forge, drop,
|
|
delay or replay them, and knows all metadata. This core protects message and
|
|
file contents between two Komet installations that completed a handshake, and
|
|
limits the damage of a later key compromise to the current ratchet window. It
|
|
does not hide that encryption is used, does not hide who talks to whom, cannot
|
|
prevent the server from suppressing delivery, and cannot detect an active
|
|
substitution of the very first handshake — only an out-of-band fingerprint
|
|
comparison can.
|