Quickstart

This guide walks you through the minimal steps to get CoreCrypto running on your platform. By the end you will have:

Opened an encrypted database.
Initialized an MLS session.
Created a conversation.
Encrypted and decrypted a message.

TypeScript / WASM
Kotlin / Android
Swift / iOS

Installation

Install the npm package

CoreCrypto is published as @wireapp/core-crypto. Install it with your package manager:

npm install @wireapp/core-crypto

The package ships two entry points:

@wireapp/core-crypto/browser — WASM binary for browsers and bundlers.
@wireapp/core-crypto/native — N-API binary for Node.js.

The browser entry point includes a .wasm binary that must be served as a static asset. See your bundler’s documentation for how to handle .wasm files.

Initialize the WASM module

Before using any CoreCrypto APIs in a browser context, initialize the WASM module once at startup:

import { initWasmModule } from "@wireapp/core-crypto/browser";

// Pass the path to the directory containing `index_bg.wasm`.
// Omit the argument if the file is served from the package root.
await initWasmModule("/assets/core-crypto/");

Open a database

CoreCrypto stores all keying material in an encrypted database. On WASM, this is backed by IndexedDB.

import {
  CoreCrypto,
  Database,
  DatabaseKey,
} from "@wireapp/core-crypto/browser";

// Generate or load a 32-byte database key.
const keyBytes = new Uint8Array(32);
crypto.getRandomValues(keyBytes);
const dbKey = new DatabaseKey(keyBytes.buffer);

// Open (or create) the database. The first argument is the database name.
const database = await Database.open("my-app-db", dbKey);

Create a CoreCrypto instance

Construct a CoreCrypto instance from the opened database:

const cc = CoreCrypto.new(database);

Initialize MLS in a transaction

All state-mutating operations run inside a transaction. Initialize MLS and register a credential within a single transaction:

import {
  ClientId,
  Credential,
  Ciphersuite,
} from "@wireapp/core-crypto/browser";

// Your MLS transport implementation — sends commits and messages
// to your delivery service.
const transport = {
  async sendCommitBundle(commitBundle) {
    // POST commitBundle to your delivery service
    return MlsTransportResponse.Success.new();
  },
  async sendMessage(message) {
    // POST message to your delivery service
    return MlsTransportResponse.Success.new();
  },
  async prepareForTransport(historySecret) {
    return historySecret.clientId.copyBytes();
  },
};

const encoder = new TextEncoder();
const clientId = new ClientId(encoder.encode("alice@device1").buffer);
const ciphersuite = Ciphersuite.Mls128Dhkemx25519Aes128gcmSha256Ed25519;

await cc.newTransaction(async (ctx) => {
  await ctx.mlsInit(clientId, transport);
  await ctx.addCredential(
    Credential.basic(ciphersuite, clientId)
  );
});

newTransaction commits all changes to the keystore if the callback returns successfully. If the callback throws, all changes are discarded.

Create a conversation

import { ConversationId } from "@wireapp/core-crypto/browser";

const conversationId = new ConversationId(
  encoder.encode("my-conversation-id").buffer
);

await cc.newTransaction(async (ctx) => {
  // Retrieve the credential registered during mlsInit.
  const [credentialRef] = await ctx.getCredentials();
  await ctx.createConversation(conversationId, credentialRef);
});

Encrypt and decrypt a message

// Encrypt a message as the conversation creator.
const plaintext = encoder.encode("Hello, MLS!");
const ciphertext = await cc.newTransaction(async (ctx) => {
  return await ctx.encryptMessage(conversationId, plaintext.buffer);
});

// On the receiving end, decrypt the message.
const decryptResult = await cc.newTransaction(async (ctx) => {
  return await ctx.decryptMessage(conversationId, ciphertext);
});

const decoder = new TextDecoder();
const decryptedText = decoder.decode(decryptResult.message);
console.log(decryptedText); // "Hello, MLS!"

Installation

Add the Maven dependency

CoreCrypto is published to Maven Central under com.wire. Add the dependency to your build.gradle.kts:

dependencies {
    implementation("com.wire:core-crypto-android:9.0.1")
}

The library requires a minimum SDK of API 30+. Ensure compileOptions target Java 17:

android {
    compileOptions {
        sourceCompatibility = JavaVersion.VERSION_17
        targetCompatibility = JavaVersion.VERSION_17
    }
}

Open a database

CoreCrypto stores keying material in an SQLCipher-encrypted database on disk.

import com.wire.crypto.CoreCrypto
import com.wire.crypto.Database
import com.wire.crypto.DatabaseKey
import java.security.SecureRandom

// Generate a 32-byte database key.
fun genDatabaseKey(): DatabaseKey {
    val bytes = ByteArray(32)
    SecureRandom().nextBytes(bytes)
    return DatabaseKey(bytes)
}

// Open (or create) the database at the given path.
val dbPath = context.filesDir.resolve("corecrypto-keystore").absolutePath
val dbKey = genDatabaseKey()
val database = Database.open(dbPath, dbKey)

Create a CoreCrypto instance

val cc = CoreCrypto(database)

Initialize MLS in a transaction

import com.wire.crypto.ClientId
import com.wire.crypto.Credential
import com.wire.crypto.CIPHERSUITE_DEFAULT
import com.wire.crypto.MlsTransport
import com.wire.crypto.MlsTransportResponse
import com.wire.crypto.CommitBundle
import com.wire.crypto.HistorySecret
import com.wire.crypto.MlsTransportData

val transport = object : MlsTransport {
    override suspend fun sendCommitBundle(commitBundle: CommitBundle): MlsTransportResponse {
        // POST commitBundle to your delivery service
        return MlsTransportResponse.Success
    }
    override suspend fun sendMessage(mlsMessage: ByteArray): MlsTransportResponse {
        // POST mlsMessage to your delivery service
        return MlsTransportResponse.Success
    }
    override suspend fun prepareForTransport(historySecret: HistorySecret): MlsTransportData {
        return "secret".encodeToByteArray()
    }
}

val clientId = ClientId("alice@device1".toByteArray())

cc.transaction { ctx ->
    ctx.mlsInit(clientId, transport)
    ctx.addCredential(Credential.basic(CIPHERSUITE_DEFAULT, clientId))
}

transaction is a suspending function. Call it from a coroutine or runBlocking. If the block throws, all changes within the transaction are rolled back.

Create a conversation

import com.wire.crypto.ConversationId
import com.wire.crypto.CREDENTIAL_TYPE_DEFAULT

val conversationId = ConversationId("my-conversation-id".toByteArray())

cc.transaction { ctx ->
    val credentials = ctx.findCredentials(
        clientId = null,
        publicKey = null,
        ciphersuite = CIPHERSUITE_DEFAULT,
        credentialType = CREDENTIAL_TYPE_DEFAULT,
        earliestValidity = null
    )
    ctx.createConversation(conversationId, credentials.last(), null)
}

Encrypt and decrypt a message

// Encrypt a message.
val ciphertext = cc.transaction { ctx ->
    ctx.encryptMessage(conversationId, "Hello, MLS!".toByteArray())
}

// On the receiving end, decrypt the message.
val decryptResult = cc.transaction { ctx ->
    ctx.decryptMessage(conversationId, ciphertext)
}

val plaintext = decryptResult.message?.decodeToString()
println(plaintext) // "Hello, MLS!"

Clean up

Close the CoreCrypto instance when you are done to release native resources:

cc.close()

Installation

Add the XCFramework

WireCoreCrypto is distributed as an XCFramework built from the crypto-ffi crate. Add it to your Xcode project:

Download the WireCoreCrypto.xcframework artifact from the GitHub releases page.
Drag the .xcframework into your Xcode project’s Frameworks, Libraries, and Embedded Content section.
Set the embed setting to Embed & Sign.

Then import the module in your Swift files:

import WireCoreCrypto

Open a database

CoreCrypto stores keying material in an SQLCipher-encrypted database on disk.

import WireCoreCrypto
import Security

// Generate a 32-byte database key.
func genDatabaseKey() -> DatabaseKey {
    var bytes = [UInt8](repeating: 0, count: 32)
    _ = SecRandomCopyBytes(kSecRandomDefault, bytes.count, &bytes)
    return try! DatabaseKey(key: Data(bytes))
}

let dbURL = FileManager.default
    .urls(for: .applicationSupportDirectory, in: .userDomainMask)[0]
    .appendingPathComponent("corecrypto-keystore")

let database = try await Database.open(
    location: dbURL.path,
    key: genDatabaseKey()
)

Create a CoreCrypto instance

let cc = try CoreCrypto(database: database)

Initialize MLS in a transaction

// Implement MlsTransport to connect CoreCrypto to your delivery service.
final class MyMlsTransport: MlsTransport {
    func sendCommitBundle(commitBundle: CommitBundle) async throws -> MlsTransportResponse {
        // POST commitBundle to your delivery service
        return .success
    }
    func sendMessage(mlsMessage: Data) async throws -> MlsTransportResponse {
        // POST mlsMessage to your delivery service
        return .success
    }
    func prepareForTransport(historySecret: HistorySecret) async throws -> MlsTransportData {
        return historySecret.clientId
    }
}

let transport = MyMlsTransport()
let clientId = ClientId(bytes: "alice@device1".data(using: .utf8)!)
let ciphersuite = Ciphersuite.mls128Dhkemx25519Aes128gcmSha256Ed25519

try await cc.transaction { ctx in
    try await ctx.mlsInit(clientId: clientId, transport: transport)
    _ = try await ctx.addCredential(
        credential: Credential.basic(ciphersuite: ciphersuite, clientId: clientId)
    )
}

transaction commits all changes when the closure returns without throwing. On error, all changes within the transaction are discarded.

Create a conversation

let conversationId = ConversationId(
    bytes: "my-conversation-id".data(using: .utf8)!
)

try await cc.transaction { ctx in
    let credentials = try await ctx.findCredentials(
        clientId: nil,
        publicKey: nil,
        ciphersuite: ciphersuite,
        credentialType: .basic,
        earliestValidity: nil
    )
    try await ctx.createConversation(
        conversationId: conversationId,
        credentialRef: credentials.first!,
        externalSender: nil
    )
}

Encrypt and decrypt a message

// Encrypt a message.
let ciphertext = try await cc.transaction { ctx in
    try await ctx.encryptMessage(
        conversationId: conversationId,
        message: "Hello, MLS!".data(using: .utf8)!
    )
}

// On the receiving end, decrypt the message.
let decryptResult = try await cc.transaction { ctx in
    try await ctx.decryptMessage(
        conversationId: conversationId,
        payload: ciphertext
    )
}

if let messageData = decryptResult.message {
    let plaintext = String(data: messageData, encoding: .utf8)
    print(plaintext!) // "Hello, MLS!"
}

Architecture

Understand the keystore, MLS provider, and FFI layers.

MLS protocol

Deep dive into MLS groups, epochs, and key schedules.

TypeScript guide

Full integration guide for the browser and Node.js.

API reference

Complete reference for all CoreCrypto types and methods.

Get Started

Core Concepts

Platform Guides

End-to-End Identity

Installation

Installation

Installation

What to read next

Architecture

MLS protocol

TypeScript guide

API reference

Build docs developers (and LLMs) love

Get Started

Core Concepts

Platform Guides

End-to-End Identity

​Installation

​Installation

​Installation

​What to read next

Architecture

MLS protocol

TypeScript guide

API reference

Build docs developers (and LLMs) love

Installation

Installation

Installation

What to read next