Secure. Portable. Pure Kotlin.
Kodium is a comprehensive, pure Kotlin Multiplatform (KMP) cryptography library. It acts as a faithful port of the renowned TweetNaCl C library, providing high-speed, high-security cryptographic primitives, advanced Double Ratchet session management, and Post-Quantum Cryptography (PQC) protocols without any native dependencies.
Write once, encrypt everywhere. Even in a post-quantum world.
- Kodium Highlights
- Release Notes
- Supported Platforms
- Features
- Installation
- Quick Start Guide
- Documentation
- Examples and Deep Dives
- Contributing
- License & Disclaimer
- Pure Kotlin: No JNI, no C interop headaches, no complex build scripts for native binaries. Just pure Kotlin code running everywhere.
- TweetNaCl Core: Built on the solid foundation of the TweetNaCl crypto suite, known for its security and simplicity.
- Post-Quantum Ready: Hybrid cryptographic primitives combining classical X25519 with FIPS 203 (ML-KEM) to protect against future quantum computers. Note that symmetric encryption (SecretBox) is naturally quantum-resistant.
- Double Ratchet: Includes a full implementation of the Double Ratchet Algorithm and X3DH for secure End-to-End Encryption (E2EE), featuring a built-in LRU policy for skipped message keys to prevent memory exhaustion.
- Multiplatform Native: First-class support for Android, iOS, JVM, JavaScript (Browser/Node), Wasm, Linux, macOS, and Windows.
- Developer Friendly: Simple, opinionated APIs for common tasks (Box, SecretBox, Signatures).
- BREAKING CHANGE: Base58 to Base64 Migration: Completely replaced the slow, custom Base58 encoding implementation with the high-performance, native Kotlin
kotlin.io.encoding.Base64. - Performance Boost: Significant reduction in encoding/decoding overhead across all platforms.
- API Updates: All
...ToEncodedStringand...FromEncodedStringmethods now use Base64 with a 4-byte checksum for integrity. Method parameters previously named...B58have been renamed to...Base64for clarity. - Native Compatibility: Leverages platform-optimized Base64 implementations where available via Kotlin's standard library.
- Signature Bug Fix: Resolved a critical issue where both classical and hybrid PQC signatures failed verification when using the default public key.
- Unified Public Keys: Updated both
KodiumPublicKeyandKodiumPqcPublicKeyto include encryption and signing keys, simplifying key management and ensuring consistent behavior. - Raw Cryptographic API: Restored and expanded raw
ByteArraymethods for signing and verification (signDetached,verifyDetached) across all namespaces. - Improved Serialization: Enhanced serialization for all keys and sessions to maintain cross-platform consistency and support the unified public key structure.
- Security & Compatibility Fix: Fixed a critical bug in the internal SHA-512 implementation that caused Ed25519 detached signatures to fail verification against external systems (e.g., standard JWT validators). Kodium signatures are now fully standard and cross-compatible.
- Optimization: Replaced manual SHA-512 and secure random byte generation logic with optimized calls to the
kotlincryptolibrary for improved performance and stability. - Testing & Reliability: Added comprehensive tests for large payload signatures (~37KB) to ensure robust block padding and boundary handling.
- Documentation: Corrected API documentation to accurately reflect the use of PBKDF2 with HMAC-SHA256 (instead of HMAC-SHA512) for symmetric key derivation.
- Advanced Key Management: Added support for raw, unprotected
ByteArrayexports and imports (exportToArray(),importFromArray()) across all private keys (KodiumPrivateKey,KodiumPqcPrivateKey) and E2EE sessions (DoubleRatchetSession,PQDoubleRatchetSession) to support apps managing their own secure storage. - High-Performance Persistence: Introduced
ByteArrayprecomputed key support for symmetric encryption and state persistence, allowing developers to bypass PBKDF2 overhead when importing/exporting keys and ratchet sessions. - Convenience API Additions: Added
Kodium.generateHighEntropyKey(),Kodium.generateRandomSalt(), andKodium.deriveKeyFromPassword()to simplify symmetric key lifecycle management.
- Ed25519 detached signature support
- Post-Quantum Cryptography: Added
Kodium.pqcnamespace with support for Hybrid ML-KEM-768 + X25519 encryption. - FIPS 203 Compliance: Integrated a pure Kotlin implementation of the ML-KEM (Kyber) standard.
- Double Ratchet Algorithm: Full implementation of the Signal-style Double Ratchet and X3DH protocols for secure End-to-End Encrypted messaging.
- Expanded HKDF: Updated secret mixing to support high-entropy hybrid keys.
- Upgraded to Kotlin 2.3.10.
- Full KDoc documentation for all public APIs.
- Improved test coverage across JVM and JS targets.
- Initial implementation of the library.
- Port of TweetNaCl (Box, SecretBox, Signatures).
- Base58Check encoding/decoding.
| Platform | Support |
|---|---|
| Android | ✅ |
| iOS (Arm64, X64, Sim) | ✅ |
| JVM (Java 17+) | ✅ |
| JavaScript (Browser/Node) | ✅ |
| Wasm (WebAssembly) | ✅ |
| macOS (Arm64, X64) | ✅ |
| Linux (X64) | ✅ |
| Windows (MinGW X64) | ✅ |
- End-to-End Encryption: Double Ratchet Algorithm & X3DH (Extended Triple Diffie-Hellman).
- Post-Quantum Hybrid Encryption: FIPS 203 (ML-KEM-768) + Curve25519 authenticated encryption.
- Public-Key Cryptography (Box): Authenticated encryption using Curve25519, XSalsa20, and Poly1305.
- Secret-Key Cryptography (SecretBox): Authenticated encryption using XSalsa20 and Poly1305.
- Digital Signatures: Ed25519 high-speed, high-security signatures.
- Key Management: Secure generation, import, and export of keys (Raw & Base58Check).
- Utils: Robust Base58Check encoding/decoding and HKDF (RFC 5869).
Add Kodium to your common module's dependencies.
Gradle (Kotlin DSL)
implementation("eu.livotov.labs:kodium:1.0.0-beta-3")Gradle (Groovy)
implementation 'eu.livotov.labs:kodium:1.0.0-beta-3'Maven
<dependency>
<groupId>eu.livotov.labs</groupId>
<artifactId>kodium</artifactId>
<version>1.0.0-beta-3</version>
</dependency>Kodium provides a complete implementation of the Double Ratchet algorithm for secure E2EE messaging.
// Alice initializes her session as the initiator
val aliceSession = DoubleRatchetSession.initializeAsInitiator(sharedSecret, responderRatchetKey)
// Encrypt a message to a Base58 string
val encrypted = aliceSession.encryptToEncodedString("Hello Bob!".encodeToByteArray()).getOrThrow()
// Bob decrypts it back
val bobSession = DoubleRatchetSession.initializeAsResponder(sharedSecret, responderRatchetKeyPair)
val decrypted = bobSession.decryptFromEncodedString(encrypted).getOrThrow()Upgrade your E2EE sessions to be resistant to quantum computer attacks using the PQDoubleRatchetSession.
// Alice initializes her PQ session using the secrets from PQXDH
val aliceSession = PQDoubleRatchetSession.initializeAsInitiator(
sharedSecret = aliceSharedSecret.masterSecret,
responderPqcPublicKey = fetchedBobBundle.pqcKey,
ourPqcPrivateKey = aliceHybridKeys
)
val encrypted = aliceSession.encryptToEncodedString("Post-Quantum Hello!".encodeToByteArray()).getOrThrow()
// Bob initializes his session using his keys and Alice's provided payload
val bobSession = PQDoubleRatchetSession.initializeAsResponder(
sharedSecret = bobSharedSecret,
ourPqcPrivateKey = bobHybridKeys,
initiatorPqcPublicKey = fetchedAlicePayload.pqcPublicKey!!
)
val decrypted = bobSession.decryptFromEncodedString(encrypted).getOrThrow()Protect your data against future quantum computer attacks using the hybrid Kodium.pqc suite.
// 1. Generate Hybrid Keys (X25519 + ML-KEM-768)
val myKeys = Kodium.pqc.generateKeyPair()
val theirPublicKey = ... // Received from peer
// 2. Encrypt
val encrypted = Kodium.pqc.encryptToEncodedString(
mySecretKey = myKeys,
theirPublicKey = theirPublicKey,
data = "Secret message".encodeToByteArray()
).getOrThrow()
// 3. Decrypt
val decrypted = Kodium.pqc.decryptFromEncodedString(
mySecretKey = myKeys,
theirPublicKey = theirPublicKey,
data = encrypted
).getOrThrow()Securely exchange messages between Alice and Bob without session management.
// 1. Generate keys
val alice = Kodium.generateKeyPair()
val bob = Kodium.generateKeyPair()
// 2. Alice encrypts a message for Bob
val message = "The eagle flies at midnight.".encodeToByteArray()
val encryptedResult = Kodium.encryptToEncodedString(
mySecretKey = alice,
theirPublicKey = bob.getPublicKey(),
data = message
)
// 3. Bob decrypts the message
encryptedResult.onSuccess { cipherText ->
Kodium.decryptFromEncodedString(
mySecretKey = bob,
theirPublicKey = alice.getPublicKey(),
data = cipherText
).onSuccess { decryptedBytes ->
println("Decrypted: ${decryptedBytes.decodeToString()}")
}
}Protect data with a shared password/secret.
val password = "CorrectHorseBatteryStaple"
val secretData = "Launch codes: 12345".encodeToByteArray()
// Encrypt
val encryptedResult = Kodium.encryptSymmetricToEncodedString(password, secretData)
// Decrypt
encryptedResult.onSuccess { cipherText ->
val decryptedResult = Kodium.decryptSymmetricFromEncodedString(password, cipherText)
println("Restored: ${decryptedResult.getOrThrow().decodeToString()}")
}Prove authenticity and integrity using detached Ed25519 digital signatures.
val myPrivateKey = Kodium.generateKeyPair()
val message = "This message is authentic".encodeToByteArray()
// Sign
val signatureB58 = Kodium.signDetachedToEncodedString(myPrivateKey, message).getOrThrow()
// Verify using the signer's Public Key
val isValid = Kodium.verifyDetachedFromEncodedString(
theirPublicKey = myPrivateKey.getPublicKey(),
data = message,
signatureB58 = signatureB58
)Easily store keys using Base58Check encoding.
val keyPair = Kodium.generateKeyPair()
// Export Public Key (Safe to share, contains both encryption and signing keys)
val pubKeyString = keyPair.getPublicKey().exportToEncodedString()
// Export Private Key (Encrypted with a password)
val privKeyString = keyPair.exportToEncryptedString("StrongPassword")
// Import later
val restoredKeyPair = KodiumPrivateKey.importFromEncryptedString(
data = privKeyString.getOrThrow(),
password = "StrongPassword"
)The complete documentation for Kodium is available online and within the repository.
👉 Online Documentation (Manual & API Reference)
The docs/ directory is structured for GitBook and contains:
- Manual: High-level guides, architectural overviews, and usage examples.
- API Reference: Detailed documentation for every package, class, and function, generated from KDocs.
For advanced usage and detailed technical explanations, refer to our deep-dive standalone guides.
Learn how to build a fully secure, asynchronous peer-to-peer chat application using the classical Double Ratchet protocol. This guide covers the complete lifecycle:
- Account creation and public key publishing.
- Asynchronous X3DH handshake.
- Session initialization and secure message exchange.
- Advanced topics like Context Binding and Session State Persistence.
👉 Read the full Double Ratchet & X3DH Guide
Future-proof your application against "Harvest Now, Decrypt Later" attacks by upgrading to Kodium's Hybrid PQC suite. This guide covers:
- The theory behind mixing X25519 with FIPS 203 (ML-KEM-768).
- Managing and persisting large Hybrid Keys.
- Establishing a Post-Quantum Double Ratchet session for next-generation E2EE security.
👉 Read the full PQC Reference Guide
We welcome contributions! If you're interested in building Kodium from source, running tests, or updating the documentation, please refer to our Developer Guide.
Kodium is licensed under the Apache 2.0 License.
The Post-Quantum ML-KEM math implementation in this project is based on the excellent KyberKotlin project by Ron Lauren Hombre.
Copyright 2026 Livotov Labs Ltd.
Disclaimer: While this library implements standard cryptographic primitives based on TweetNaCl, it has not been audited by a security expert. Users should always review security requirements for their specific use case and use at their own risk.