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.

1. Kodium Highlights
2. Release Notes
3. Supported Platforms
4. Features
5. Installation
6. Quick Start Guide
7. Documentation
8. Examples and Deep Dives
9. Contributing
10. 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).

• Post-Quantum Cryptography: Added Kodium.pqc namespace 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.

• 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")

Gradle (Groovy)

implementation 'eu.livotov.labs:kodium:1.0.0'

Maven

<dependency>
    <groupId>eu.livotov.labs</groupId>
    <artifactId>kodium</artifactId>
    <version>1.0.0</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()}")
}

Easily store keys using Base58Check encoding.

val keyPair = Kodium.generateKeyPair()

// Export Public Key (Safe to share)
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.