Sterister
188c3db56a
Pure-JVM additions to shade-android (no Android SDK needed): - V4.9 blob primitives: BlobKdf (HKDF deriveBlobSlotId/Key/SigningSeed), BlobAead (nonce||ct||tag with shade-profile-aad-v1:<slot> AAD), BlobClient (java.net.http with hand-written canonical JSON signing matching TS signPayload output), Profile high-level namespace. - V4.10 approval helpers: CanonicalProfileBlob schema with denormalized trustedApproverFingerprints, build/sign/verify proxy approvals via length-prefixed u16 BE UTF-8 canonical signing payload. - Password KDFs: scrypt + argon2id via Bouncy Castle, NFKC-normalized. - SessionStateJson at-rest serializer for persistence layer. Cross-platform vectors (test-vectors/blob.json, approval.json) gate byte-identical output between TS and Kotlin, including a TS-signed Ed25519 signature the Kotlin port verifies and reproduces (Ed25519 is deterministic). New shade-android-keystore sibling Gradle module (Android-specific): - KeystoreMasterKey: hardware-backed AES-256-GCM with BIOMETRIC_STRONG gating, StrongBox-backed when available, invalidated on enrollment. - BiometricUnlock: coroutine wrapper around BiometricPrompt with tagged cancellation/failure exceptions. - KeystoreStorage: StorageProvider over biometric-gated AES-encrypted SharedPreferences with AAD-bound row keys. All 25 SDK packages typecheck clean; 104 SDK tests + 24 new Kotlin tests + 11 cross-platform vector tests all green. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
77 lines
3.6 KiB
Markdown
77 lines
3.6 KiB
Markdown
# shade-android
|
|
|
|
Kotlin implementation of the Shade E2EE protocol for Android apps. Byte-for-byte compatible with `@shade/core` (TypeScript), so messages encrypted on a TS backend can be decrypted on Android and vice versa.
|
|
|
|
## Status
|
|
|
|
**M-Cross 1 ✅** — keys + HKDF + X3DH + fingerprint.
|
|
**M-Cross 2 ✅** — full ratchet step (encrypt + decrypt roundtrip) + wire 0x02 (RatchetMessage and PreKeyMessage with/without OTPK).
|
|
**M-Cross 3 ✅** — streams 0x11 (KDF labels with embedded NULs, deterministic chunk nonce/AAD, wire 0x11 encode/decode).
|
|
**M-Cross 4 ✅** — backup-key HKDF + AES-GCM, group sender-key step (`kdfChainKey` + Ed25519 sign over `aad ‖ ct`), storage HKDF (storageKey/fieldKey/rowNonce).
|
|
**M-Cross 5 ✅** — V4.9 blob KDF + AEAD (`deriveBlobSlotId / deriveBlobKey / deriveBlobSigningSeed`, AAD-bound seal/open), `BlobClient` HTTP, `Profile` namespace. Cross-platform vectors in `blob.json`.
|
|
**M-Cross 6 ✅** — V4.10 cross-host approval routing: canonical profile-blob schema (`hosts[]` / `clients[]` / `trustedApproverFingerprints[]`), build/sign/verify proxy approvals via `canonicalApprovalSigningBytes` (length-prefixed u16 BE UTF-8). Cross-platform vectors in `approval.json`, including a TS-signed Ed25519 signature that the Kotlin port verifies.
|
|
**M-Cross 7 ✅** — scrypt + argon2id password-KDF wrappers (Bouncy Castle), NFKC-normalized inputs.
|
|
**M-Cross 8 ✅** — `:shade-android-keystore` sibling module: `KeystoreMasterKey` (StrongBox-backed AES-256-GCM, BIOMETRIC_STRONG-gated, invalidated on biometric enrollment), `BiometricUnlock`, `KeystoreStorage` (`StorageProvider` over biometric-gated AES-encrypted SharedPreferences).
|
|
|
|
Cross-platform test vectors in `/test-vectors/` are loaded by both the TS
|
|
and Kotlin test suites; any byte-divergence fails CI within 60 s. See
|
|
`ROADMAP-ANDROID.md` for the parity-checkpoint matrix and
|
|
`/docs/cross-platform.md` for how to add a new vector.
|
|
|
|
## Usage (target API)
|
|
|
|
```kotlin
|
|
import no.zyon.shade.ShadeSessionManager
|
|
import no.zyon.shade.crypto.TinkProvider
|
|
import no.zyon.shade.storage.KeystoreStorage
|
|
|
|
val crypto = TinkProvider()
|
|
val storage = KeystoreStorage(context)
|
|
val manager = ShadeSessionManager(crypto, storage)
|
|
manager.initialize()
|
|
|
|
// Establish a session with a peer
|
|
val bundle = fetchBundleFromServer("bob@example.com")
|
|
manager.initSessionFromBundle("bob@example.com", bundle)
|
|
|
|
// Encrypt
|
|
val envelope = manager.encrypt("bob@example.com", "hello")
|
|
|
|
// Decrypt
|
|
val plaintext = manager.decrypt("alice@example.com", incomingEnvelope)
|
|
```
|
|
|
|
## Crypto primitives
|
|
|
|
Backed by Google Tink:
|
|
- X25519 for Diffie-Hellman (via `X25519.generatePrivateKey()` / `computeSharedSecret`)
|
|
- Ed25519 for signing (via `Ed25519Sign` / `Ed25519Verify`)
|
|
- AES-256-GCM (via `AesGcmJce`)
|
|
- HKDF-SHA256 (via `Hkdf.computeHkdf`)
|
|
- HMAC-SHA256 (via `MacFactory`)
|
|
|
|
## Building
|
|
|
|
Requires JDK 17. The module compiles as a pure-JVM Kotlin library so the
|
|
parity gate runs without an Android SDK install. The Android-specific
|
|
storage adapter (Keystore + EncryptedSharedPreferences) will land as a
|
|
sibling Gradle module in M-Cross 4.
|
|
|
|
```bash
|
|
cd android
|
|
./gradlew :shade-android:test
|
|
```
|
|
|
|
The Gradle wrapper downloads Gradle 8.10.2 on first run.
|
|
|
|
## Compatibility
|
|
|
|
The Kotlin implementation must produce byte-identical output to `@shade/core` for:
|
|
- KDF chain derivations (root key ratchet, chain key ratchet)
|
|
- X3DH shared secrets
|
|
- Ratchet message keys and ciphertext (given the same keys)
|
|
- Fingerprints (safety numbers)
|
|
- Binary wire format (`@shade/proto`)
|
|
|
|
Shared test vectors in `test-vectors/` are loaded by both the TS and Kotlin test suites. Any divergence fails the CI immediately.
|