hypervault-crypto

The open-source cryptographic core of Hypervault — an offline, zero-knowledge password manager and air-gapped crypto wallet for Android.

This library is pure Kotlin (JVM), has a single third-party dependency — Bouncy Castle — and performs no I/O and no networking. Everything here operates on byte arrays passed in by the caller.

Design principles

1. No home-grown cryptography. Every primitive (Argon2id, AES-GCM, HKDF, Ed25519, X25519, secp256k1) comes from Bouncy Castle. This library only composes primitives into higher-level formats and protocols.
2. Zero-knowledge, offline-first. No key material ever leaves the calling process; the library cannot make network calls by construction.
3. Secrets live in zeroable ByteArrays, never in Strings (see memory/SecretBytes.kt).
4. All randomness comes from SecureRandom (random/CryptoRandom.kt).
5. Versioned formats. Every serialized artifact carries a schema version; migrations are forward-only.

The normative architecture document is docs/CRYPTO_WHITEPAPER.ru.md (Russian; an English translation is planned). Any divergence between that document and the code is a bug: either the code is fixed or the document is deliberately updated.

What's inside

Package	Contents
kdf	Argon2id (Bouncy Castle engine) and HKDF-SHA-256
cipher	AES-256-GCM authenticated encryption
keys	Master key hierarchy (master password + Secret Key → MUK → KEK → DEK), Secret Key format
vault	HV1 — the encrypted vault container format
attachment	Streaming encryption codec for file attachments
pin	PIN-based key wrapping
share	HVS1 — encrypted record sharing (X25519 key agreement, Ed25519 signatures, share fingerprints)
otp	TOTP (RFC 6238) and Base32
wallet	BIP-39 mnemonics, BIP-32 / SLIP-10 derivation, Base58 / Bech32, BTC / EVM / Solana addresses, air-gapped EVM transaction signing (RLP, EIP-1559, Keccak)
memory	Zeroable secret byte containers
random	CSPRNG access point

Key hierarchy (overview)

master password          Secret Key SK (128-bit, CSPRNG,
      │                   generated at vault creation)
      │ Argon2id                │
      ▼                         │
     MUK (256-bit) ─────────────┤
                                ▼
                  KEK = HKDF-SHA-256(MUK ‖ SK)
                                │  AES-256-GCM (key wrap)
                                ▼
                               DEK ──► vault payload (AES-256-GCM)

Both the master password and the device-bound Secret Key are required to derive the KEK — a copy of the vault file alone is not brute-forceable with a password guess only.

Usage

The library is consumed as a plain JVM/Android Kotlin dependency. Until artifacts are published to Maven Central, use a Gradle included build or a git submodule.

dependencies {
    implementation("its.development.hypervault:hypervault-crypto:0.1.0")
}

Building

JDK 11+ (toolchain is resolved automatically):

./gradlew build   # compile + run all tests

Tests include vectors from the relevant RFCs and BIPs (RFC 6238, BIP-32, BIP-39, SLIP-10, EIP-155/1559 among others).

Security

Do not report vulnerabilities in public issues. See SECURITY.md for the private disclosure process.

This library has not yet undergone an independent security audit. Until it does, treat it accordingly.

Contributing

See CONTRIBUTING.md. Note the strict scope: proposals that add network I/O, new third-party dependencies, or hand-rolled primitives will be declined.

License

Apache License 2.0 © ITS Development