60 lines
2.0 KiB
Markdown
60 lines
2.0 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
|
||
|
|
|
||
|
|
**Milestone M-Cross 1 — initial scaffold.** The protocol implementation is being ported. Cross-platform test vectors in `test-vectors/` verify that Kotlin and TypeScript produce identical output for every step (identity gen → HKDF → X3DH → ratchet → fingerprint → wire format).
|
||
|
|
|
||
|
|
## 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 Android SDK 35 and JDK 17.
|
||
|
|
|
||
|
|
```bash
|
||
|
|
./gradlew :shade-android:assembleDebug
|
||
|
|
./gradlew :shade-android:test
|
||
|
|
```
|
||
|
|
|
||
|
|
## 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.
|