The end-to-end encryption & wire protocol at the heart of BIShare.
A small, dependency-light Rust crate that implements the cryptography, binary framing, and shared data models used to move files securely between devices — iPhone, Android, Mac, Windows, and Linux.
BIShare sends files directly device-to-device, end-to-end encrypted, across
every platform. This crate is the shared core that makes that safe and
interoperable: the same Rust code runs inside the native apps (via
flutter_rust_bridge), so a
byte encrypted on an iPhone decrypts correctly on a Windows PC.
It gives you three things:
- 🔒 Cryptography — X25519 key agreement, HKDF-SHA256 key derivation, and AES-256-GCM authenticated encryption, including per-chunk nonce derivation for streaming large files and content-key wrapping.
- 📦 Binary wire framing — a compact, versioned frame format (
Encoder/Decoder) for the TCP/QUIC transfer streams. - 🧩 Shared models — the
serdetypes every BIShare client agrees on: devices, file metadata, rooms, clipboard payloads, signaling envelopes, …
The crate lives in
rust/. Swift/Kotlin bindings were removed in favor of a single Rust core consumed through flutter_rust_bridge.
use bishare_protocol::crypto::Encryption;
// Two peers each generate an X25519 keypair.
let alice = Encryption::new();
let bob = Encryption::new();
// They exchange public keys (base64) over any channel, then INDEPENDENTLY
// derive the same 32-byte AES key (X25519 ECDH → HKDF-SHA256).
let key = alice.derive_shared_key(&bob.public_key_base64()).unwrap();
// AES-256-GCM seal / open. Blob layout: nonce(12) ‖ ciphertext ‖ tag(16).
let sealed = Encryption::encrypt(b"contents of secret.pdf", &key).unwrap();
let opened = Encryption::decrypt(&sealed, &key).unwrap();
assert_eq!(opened, b"contents of secret.pdf");Build & test the crate:
cd rust
cargo build
cargo test # 75 unit tests: crypto round-trips, framing, models| Module | Responsibility |
|---|---|
crypto |
X25519 ECDH · HKDF-SHA256 · AES-256-GCM · per-chunk nonce derivation · content-key wrapping · SHA-256 hashes · key fingerprints |
binary |
Versioned wire framing — MessageType, Frame, Encoder, Decoder, plus the v2 streaming frames |
models |
serde types shared across clients — DeviceInfo, FileMetadata, RoomInfo, ClipboardPayload, signaling envelopes, requests/responses |
constants |
Protocol version, default ports, chunk sizes, and per-feature version gates |
utils |
Shared helpers — room codes, filename sanitisation, and encoding utilities |
- Key agreement: X25519 ECDH between the two devices' ephemeral/identity keys.
- Key derivation: HKDF-SHA256 over the shared secret → a 32-byte AES-256 key.
- Encryption: AES-256-GCM (AEAD). Each sealed blob is
nonce(12) ‖ ciphertext ‖ tag(16). - Streaming: large files are chunked; each chunk gets a deterministic nonce
derived as
baseNonce[0..4] ‖ (baseNonce[4..12] XOR chunkIndex), so chunks are independently verifiable and never reuse a nonce. - Content-key wrapping: a per-file content key can be wrapped under a key-encryption key (KEK = the derived shared key) into a 60-byte envelope.
- Fingerprints:
SHA-256(publicKey)[0..8]rendered as hex — a short, human-comparable device identity for trust-on-first-use. - Compatibility: public keys are accepted as raw 32 bytes or as legacy 44-byte X.509 SPKI, normalised before use.
- Version: 2.4 · Edition: Rust 2024 · License: MIT
- Default ports:
58317(TCP/HTTP transfer) ·58318(UDP/QUIC endpoint) - Default chunk size: 256 KiB (64 KiB–1 MiB range)
| Repo | What it is |
|---|---|
| bishare-flutter | The native app (iOS, Android, macOS, Windows, Linux) — links this crate via flutter_rust_bridge. |
| bishare-web | The browser app + site — mirrors the AES-256-GCM scheme with WebCrypto. |
This crate builds on well-reviewed community crates — x25519-dalek, aes-gcm,
hkdf, and sha2 — and is covered by 75 unit tests including encryption
round-trips. It has not had a formal external audit. If you find a
vulnerability, please email security@billiongroup.net rather than opening a
public issue.
Released under the MIT License — free to use, modify, and distribute.
If this is useful to you, please ⭐ star the repo.