Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

CoreCrypto

CoreCrypto is a simplified abstraction over the MLS and Proteus cryptographic protocols for end-to-end encrypted communication. In addition, it provides end-to-end identity (E2EI) support via X509 credentials.

This book describes both core concepts and some platform-specific implementation notes. For detailed API references for a given platform and release, see https://wireapp.github.io/core-crypto.

Proteus

Proteus is Wire’s implementation of the Signal Protocol: a double-ratchet scheme providing forward secrecy and break-in recovery for one-to-one encrypted sessions.

Proteus is intrinsically a direct protocol: every message is individually encrypted for each recipient. Groups in Proteus are a fiction managed collaboratively between the backend and the client; they do not exist at the protocol level. Encrypting a message for a group of n clients requires sending n individually encrypted copies. This effect is compounded by the fact that a logical user in the sense of a human is very likely to have multiple clients in terms of individual devices. This O(n²) overhead is manageable for small groups, but becomes expensive as they scale, and it was the primary motivation for adopting MLS.

Proteus remains supported for backwards compatibility, but has not received direct development work in some time. Its implementation is already feature-gated for easy removal, and is intended to be removed as soon as we can confirm that a sufficiency of clients have upgraded their conversations to MLS.

Initialization

Before any Proteus operation, the Proteus subsystem must be explicitly initialized within a transaction:

await ctx.proteusInit()

try await ctx.proteusInit()

ctx.proteusInit()

This loads the device’s Proteus identity from the keystore, creating it if it does not yet exist. All other Proteus methods will return an error if called before proteusInit() has succeeded.

Identity and Fingerprints

A Proteus identity is a long-lived Ed25519 keypair tied to the device. CoreCrypto exposes several fingerprint accessors, each returning a hex string:

proteusFingerprint() — The local device’s public key. Remains stable for the lifetime of the keystore.

proteusFingerprintLocal(sessionId) — The local public key as seen from within a specific session. Equivalent to proteusFingerprint() but scoped to a session for API symmetry.

proteusFingerprintRemote(sessionId) — The remote peer’s public key within a session. Can be used to verify the peer’s identity out-of-band.

proteusFingerprintPrekeybundle(prekey) — Extracts the public key fingerprint from a serialized prekey bundle without opening a session. Useful for verifying a peer’s identity before establishing a session.

Prekeys

Prekeys are the mechanism that allows a sender to open a Proteus session with a recipient who is offline. The recipient publishes a set of one-time prekey bundles to the delivery service in advance; the sender fetches one and uses it to bootstrap the session.

CoreCrypto provides two ways to generate prekeys:

proteusNewPrekey(id) — Generates a prekey with an explicit numeric ID (a u16). Use this when your app manages the prekey ID space itself.

proteusNewPrekeyAuto() — Generates a prekey with an automatically incremented ID and returns both the ID and the serialized bundle. Prefer this unless you have a specific reason to control IDs manually.

Both return a CBOR-serialized prekey bundle ready to upload to the delivery service.

The Last Resort Prekey

Proteus reserves prekey ID 65535 (u16::MAX) as a last resort prekey. Unlike one-time prekeys, the last resort prekey is never consumed — it stays in the keystore indefinitely so that a sender can always open a session even when all one-time prekeys have been exhausted.

const prekey = await ctx.proteusLastResortPrekey()

let prekey = try await ctx.proteusLastResortPrekey()

val prekey = ctx.proteusLastResortPrekey()

The constant proteusLastResortPrekeyId() returns 65535 and can be used to exclude this ID when generating ordinary prekeys.

Sessions

A Proteus session represents an established encrypted channel with one remote client, identified by a caller-supplied sessionId string. Session state is cached in memory and persisted to the keystore.

There are two ways to establish a new session, depending on which side initiates:

proteusSessionFromPrekey(sessionId, prekey) — Used by the sender to initiate a session. Takes the remote client’s serialized prekey bundle (fetched from the delivery service) and creates a local session ready to encrypt.

proteusSessionFromMessage(sessionId, envelope) — Used by the recipient upon receiving the first message. Decrypts the initial envelope, establishes the session, and returns the plaintext in a single step.

Once established, a session can be checked for existence with proteusSessionExists(sessionId) and explicitly removed with proteusSessionDelete(sessionId). Manual saves via proteusSessionSave(sessionId) are available but not normally required — sessions are persisted automatically when encrypting or decrypting.

Encrypting and Decrypting

With a session established, encryption and decryption are straightforward:

const ciphertext = await ctx.proteusEncrypt(sessionId, plaintext)
const plaintext  = await ctx.proteusDecrypt(sessionId, ciphertext)

let ciphertext = try await ctx.proteusEncrypt(sessionId: sessionId, plaintext: plaintext)
let plaintext  = try await ctx.proteusDecrypt(sessionId: sessionId, ciphertext: ciphertext)

val ciphertext = ctx.proteusEncrypt(sessionId, plaintext)
val plaintext  = ctx.proteusDecrypt(sessionId, ciphertext)

Batched Encryption

Because a group message in Proteus requires one encrypted copy per recipient client, CoreCrypto provides a batched variant to reduce FFI round-trips:

const map = await ctx.proteusEncryptBatched(sessionIds, plaintext)
// map: { sessionId -> ciphertext }

let map = try await ctx.proteusEncryptBatched(sessions: sessionIds, plaintext: plaintext)
// map: { sessionId -> ciphertext }

val map = ctx.proteusEncryptBatched(sessionIds, plaintext)
// map: { sessionId -> ciphertext }

This is more efficient than calling proteusEncrypt in a loop and should be preferred whenever sending to multiple sessions simultaneously.

Safe Decrypt

proteusDecryptSafe(sessionId, ciphertext) is a convenience wrapper that handles the common case where you do not know in advance whether the session already exists. It opens the session from the message envelope if necessary, then decrypts, in a single call. For high-volume decryption to an existing session, the plain proteusDecrypt call is slightly more efficient.

Error Handling

Proteus errors are surfaced as a ProteusError with the following variants:

SessionNotFound — The requested session ID does not exist in the keystore or in-memory cache.

DuplicateMessage — The ciphertext has already been decrypted. The double-ratchet discards keys after use, so replaying a message is always an error.

RemoteIdentityChanged — The remote peer’s identity key no longer matches what was recorded when the session was established. This typically indicates a device reset or, in the worst case, a key compromise.

Other { error_code } — A lower-level Proteus error that does not map to one of the above categories. The numeric error_code corresponds to the proteus-traits error table.

MLS

RFC 9420, the Messaging Layer Security standard, solves the group-scaling problem that limits Proteus. Rather than maintaining an independent session per client pair, MLS establishes a single shared group secret from which all members independently derive the same encryption keys. Membership changes are managed through a ratchet tree — a binary tree structure that lets any member compute the new shared secret after an add or remove using only O(log n) key operations rather than O(n²) messages.

The fundamental unit of time in an MLS group is the epoch. Each epoch has a distinct shared secret; when membership changes (or when keys are rotated for other reasons), the group advances to a new epoch and new keys are computed. The two-phase proposal / commit model makes this safe in asynchronous networks: proposals accumulate from multiple senders, and a single commit bundles them into an atomic epoch transition.

Cryptographic Properties

Security Guarantees

MLS provides two complementary security properties that together defend against both historical and future exposure of messages.

Forward Secrecy

Because each epoch derives a distinct shared secret and prior epoch secrets are deleted after use, compromise of the current epoch does not expose messages from any prior epoch. An attacker who obtains today’s keys learns nothing about yesterday’s conversations.

Post-Compromise Security

Forward secrecy protects the past; post-compromise security (PCS) protects the future. If an attacker obtains a member’s key material — for example by compromising a device — they gain access to the current epoch. MLS limits this exposure: once any member contributes a commit that includes a fresh path secret (an Update proposal, or any commit authored by the compromised member), new randomness is injected into the key schedule. The attacker’s copy of the old keys cannot be used to derive the new epoch’s secrets, so the group heals automatically as conversation continues.

Together, these guarantees mean that an MLS group is resilient over time: past messages remain private even after compromise, and future messages recover privacy as soon as keys are rotated.

Efficiency

While changes in the group structure require O(log n) key operations, application messages are more efficient. Because each group has a shared group state governing its current shared secret, application messages encrypt in O(1). A significant improvement over Proteus!

Initialization

Before any MLS operation, MLS must be explicitly initialized within a transaction:

await ctx.mlsInit(clientId, transport)

try await ctx.mlsInit(clientId: clientId, transport: transport)

ctx.mlsInit(clientId, transport)

Client Identity

ClientId is an opaque byte array. CoreCrypto treats it as an identifier and does not inspect or validate its contents. Wire’s convention is to encode the client ID as a UTF-8 string of the form userId:clientId@domain — for example alice_user_id:device1@wire.com — but this is a Wire convention, not a CoreCrypto requirement.

MlsTransport

CoreCrypto intentionally abstains from communication with the Wire backend; instead, the caller provides an implementation of this interface that CoreCrypto calls on demand.

sendCommitBundle(commitBundle) — Called whenever a commit is produced — for example when creating a conversation, adding or removing members, or rotating keys. The commitBundle contains the commit message, a welcome message for any newly added members, and the updated group info. All three should be forwarded to the delivery service in a single request.

The implementor of sendCommitBundle may throw an MlsTransportError indicating the reason for a rejected message.

prepareForTransport(historySecret) — Called before a history secret is transmitted to a new history client. The implementation should package the secret in the application’s transport format (e.g., JSON or Protobuf) and return the serialized bytes. CoreCrypto will then encrypt and send those bytes as an application message.

Observers

CoreCrypto provides two optional observer interfaces that allow the application to react to significant MLS events without polling. Both are registered on the CoreCrypto instance directly (not on a transaction) and persist for the lifetime of the session.

EpochObserver

registerEpochObserver(observer) registers a callback that fires whenever a conversation advances to a new epoch — that is, whenever a commit is merged. The callback receives the conversationId and the new epoch number.

Note

The epochChanged callback must return promptly. CoreCrypto holds internal locks while dispatching it. If your observer needs to do significant work, dispatch it to a background task rather than doing it inline.

HistoryObserver

registerHistoryObserver(observer) registers a callback that fires when a new history client has been created and accepted by the delivery service. The callback receives the conversationId and a HistorySecret — an opaque bundle of key material that the application should forward to the history client so it can decrypt past messages.

The history client feature is Wire’s mechanism for allowing newly added devices to read conversation history; the HistoryObserver is the hook through which the application participates in that handoff.

Credentials and Key Packages

Before a device can join or create MLS groups, it needs a credential — a proof of identity that other group members can verify. CoreCrypto supports two credential types:

Basic — A locally generated keypair with no external attestation. Suitable whenever end-to-end identity verification is not required. This is the default.

X509 — A certificate chain obtained through the E2EI enrollment process, binding the device’s MLS identity to a verified Wire user identity. Required for deployments with end-to-end identity enabled.

Credentials are created and stored via addCredential() on the transaction, which returns a CredentialRef — a short handle used to refer to the credential in subsequent operations.

Key packages — MLS-level advertisements of a device’s identity and capabilities. Other devices fetch a target device’s key package from the delivery service when adding it to a group. Generate them with generateKeypackage(credentialRef) inside a transaction.

Ciphersuites

An MLS ciphersuite is a composite designation which specifies the KEM, AEAD, hash, and signature algorithms. CoreCrypto formally supports any of the ciphersuites specified in the RFC, but is primarily tested on ciphersuite 1 (MLS_128_DHKEMX25519_AES128GCM_SHA256_Ed25519).

The ciphersuite is fixed per conversation at the conversation’s creation.

The Database

The Database is CoreCrypto’s keystore: the persistent store for all key material and cryptographic state, as well as some non-cryptographic internal data. It is opened before constructing a CoreCrypto instance and passed in as an argument, making the storage layer an explicit dependency rather than something CoreCrypto manages internally.

What the Database Stores

The database holds all state that must survive process restarts:

  • MLS group state — the serialized ratchet tree and secrets for every conversation the device participates in
  • Credentials and key packages — the device’s identity material and the key packages it has published to the delivery service
  • Pending messages — application messages and commits that arrived during an epoch transition and are waiting to be merged
  • Proteus identity and sessions — the device’s long-lived Proteus identity keypair and the state of every active Proteus session
  • Proteus prekeys — including the last-resort prekey
  • E2EI state — data about the ACME certificate authority, various certificates and CRLs, refresh tokens, and the like

All entries are encrypted at rest using the DatabaseKey provided at open time.

Backing Storage

On non-browser platforms the database is backed by SQLCipher, an encrypted SQLite variant. On the browser, the database sits atop IndexedDB and uses item-level encryption managed by CoreCrypto. In both cases, data is encrypted at rest.

Future work on the database is intended to unify the backing storages, such that CoreCrypto will internally see an encrypted SQLite connection for all platforms. That work will be part of CC 11, but not CC 10. This change should be invisible to clients.

The Database Key

The DatabaseKey is a 32-byte symmetric key used to encrypt all data at rest. Construct it from a byte array:

const key = DatabaseKey.new(bytes)  // bytes must be exactly 32 bytes

let key = DatabaseKey(bytes: bytes)  // bytes must be exactly 32 bytes

val key = DatabaseKey(bytes)  // bytes must be exactly 32 bytes

CoreCrypto does not generate or store the key — that is entirely the client’s responsibility. The key should be kept in the platform’s secure credential storage.

Note

The database key is never written to disk by CoreCrypto. If the key is lost, the database contents are unrecoverable.

Opening the Database

All platforms define an async Database.open static method accepting a location and key. On platforms with an OS, the location is a filesystem path. On WASM, the location is the IndexedDB store name.

All platforms define an async static method to open a transient database in memory. On WASM, this is Database.inMemory. For Kotlin and Swift, this is an overload of Database.open.

Key Rotation

The database can be re-encrypted with a new key without closing and reopening it:

await db.updateKey(newKey)

try await db.updateKey(key: newKey)

db.updateKey(newKey)

This re-encrypts all stored data in place.

Lifetime and Closing

On browser platforms, explicitly close the database when tearing down:

await db.close()

Single-Transaction Constraint

Only one transaction may write to the database at a time. If a transaction is requested while another transaction is in flight, the call will block until the first transaction concludes.

For more detail, see Transactions → Concurrency.

Exporting a Copy

On native platforms, a fully vacuumed copy of the database can be written to a new file:

try await exportDatabaseCopy(database: db, destinationPath: destinationPath)

exportDatabaseCopy(db, destinationPath)

The copy is encrypted with the same key as the source. This is useful for backup or for migrating the database to a new location. This function is not available on browser platforms.

The Client

In MLS terminology a client is a single device acting on behalf of a user — each phone, desktop, or web session that participates in MLS groups is a distinct client with its own identity and key material. CoreCrypto maps this concept to the CoreCrypto object itself. One CoreCrypto instance, backed by one Database, represents one MLS client.

Note

The Rust library internally calls this type Session to avoid ambiguity — “client” means something different at the Wire application layer (where it refers to a registered device in the Wire backend sense) and at the MLS protocol layer. The name Session does not appear in platform bindings; from Swift, Kotlin, and TypeScript, the type is always CoreCrypto.

Sharing a CoreCrypto Instance

CoreCrypto is cheap to clone. All internal state — the database connection, the MLS session, the Proteus state — is reference-counted, so cloning the object creates a new handle to the same shared state rather than copying anything. This means CoreCrypto can be freely passed to background tasks or across threads without wrapping it in an additional mutex or reference type.

Read-Only Operations

Most MLS work happens inside a transaction (see Transactions and the TransactionContext), but a handful of read-only operations are available directly on CoreCrypto without opening one. The set of read-only operations available on CoreCrypto is intentionally kept narrow.

Any operation that might change state — creating or deleting a conversation, adding members, encrypting or decrypting a message — requires a transaction.

Lifecycle

A CoreCrypto instance is typically created once at application startup and kept alive for the life of the process. The initialization sequence is:

const db = await Database.open(path, key);       // open the keystore
const cc = CoreCrypto.new(db);                   // construct CoreCrypto
await cc.transaction(async (ctx) => {
    await ctx.mlsInit(clientId, transport);      // initialize the MLS session
});

let db = try await Database.open(location: path, key: key)  // open the keystore
let cc = CoreCrypto(database: db)                            // construct CoreCrypto
try await cc.transaction { ctx in
    try await ctx.mlsInit(clientId: clientId, transport: transport)  // initialize the MLS session
}

val db = Database.open(path, key)  // open the keystore
val cc = CoreCrypto(db)            // construct CoreCrypto
cc.transaction { ctx ->
    ctx.mlsInit(clientId, transport)  // initialize the MLS session
}

After mlsInit() is committed, the instance is ready to use.

Multiple Instances

Only one CoreCrypto instance (and its clones) should be active against a given database file at a time. The iOS client has a file lock which prevents two instances of the CoreCrypto from interfering with each other. On other clients opening the same database from two independent CoreCrypto instances — whether in the same process or different processes — is not supported and will produce undefined behavior.

Transactions and the TransactionContext

Every operation in CoreCrypto that can potentially mutate state must happen inside a transaction. Transactions provide an atomicity guarantee: either all of the operations in a transaction are persisted together, or none of them are. This prevents the keystore from being left in an inconsistent state if an operation fails partway through — for example, if a commit is produced but the delivery service rejects it before the local group state is updated.

Opening a Transaction

Transactions are opened with a callback pattern. Call transaction() on the CoreCrypto instance and pass an async function; CoreCrypto calls that function with a CoreCryptoContext (the transaction handle), and commits or rolls back the transaction automatically based on whether the function succeeds or throws:

await cc.transaction(async (ctx) => {
    await ctx.mlsInit(clientId, transport);
    // more operations...
});

try await cc.transaction { ctx in
    try await ctx.mlsInit(clientId: clientId, transport: transport)
    // more operations...
}

cc.transaction { ctx ->
    ctx.mlsInit(clientId, transport)
    // more operations...
}

If the callback completes without throwing, the transaction is committed — all buffered operations are written to the keystore in a single atomic database transaction. If the callback throws, the transaction is rolled back and no changes are persisted.

There is no explicit finish() or abort() to call; both are handled automatically by transaction().

The CoreCryptoContext

The ctx parameter is the CoreCryptoContext: the object through which all mutating operations are performed. It is only valid for the lifetime of the callback — using it after the callback returns will produce an InvalidTransactionContext error.

All operations are buffered in memory inside the context. Nothing is written to the database until the callback returns successfully. This means reads within the same transaction will observe the in-memory state, not the on-disk state — if you create a conversation and immediately query it within the same transaction, the query will find it.

Concurrency

Only one transaction may be active at a time. Calling cc.transaction() while another transaction is already running will block until the first transaction finishes. This is a consequence of the single-writer constraint in the keystore; see the Database chapter for more detail.

The practical implication is that large batches of work — for example, decrypting a backlog of incoming messages — will block any concurrent attempt to encrypt and send a new message. During an initial sync, this is desirable, because there are notable performance improvements to performing a large number of operations in a single transaction. On the other hand, once a client is fully synced and active, the opposite advice applies: because they are blocking, it is advisable to structure transactions to be as short-lived as possible.

Error Handling

If an operation inside a transaction fails, it is usually best to let the error propagate out of the callback. transaction() will catch it, roll back automatically, and rethrow — the caller can then handle the error without worrying about cleanup:

try {
    await cc.transaction(async (ctx) => {
        await ctx.decryptMessage(conversationId, incomingCiphertext);
        await ctx.encryptMessage(conversationId, outgoingPlaintext);
    });
} catch (err) {
    // The transaction was rolled back. No state was changed.
}

do {
    try await cc.transaction { ctx in
        try await ctx.decryptMessage(conversationId: conversationId, payload: incomingCiphertext)
        try await ctx.encryptMessage(conversationId: conversationId, message: outgoingPlaintext)
    }
} catch {
    // The transaction was rolled back. No state was changed.
}

try {
    cc.transaction { ctx ->
        ctx.decryptMessage(conversationId, incomingCiphertext)
        ctx.encryptMessage(conversationId, outgoingPlaintext)
    }
} catch (e: Exception) {
    // The transaction was rolled back. No state was changed.
}

Retry After Delivery Failure

Some operations — those that produce a commit — invoke MlsTransport.sendCommitBundle() inside the transaction. If the delivery service returns Retry, CoreCrypto propagates this as an MlsError and the transaction is rolled back. The caller should fetch and process all pending incoming messages and then retry the operation in a new transaction.

Reuse After Completion

Once transaction() returns (whether by success or failure), the CoreCryptoContext passed to the callback is permanently invalidated. Any attempt to call methods on a finished context returns InvalidTransactionContext. Always perform all work within the callback scope.

Arbitrary Data Storage

The context provides two methods for storing a single blob of arbitrary bytes in the keystore, associated with the device:

await ctx.setData(bytes)
const bytes = await ctx.getData()

try await ctx.setData(data: bytes)
let bytes = try await ctx.getData()

ctx.setData(bytes)
val bytes = ctx.getData()

These were implemented for the purpose of checkpointing during initial sync / batch decryption, but are not limited to that use.

What’s New in CC 10

New APIs

With CC10 we introduce multiple new types that provide their own new API.

Database API

  • Database.getLocation() allows getting the location of a persistent database instance. It returns null if the database is in-memory.

  • Typescript Only: Added Database.close() and removed CoreCrypto.close(). A Database should be closed if it is not used anymore. Closing a database makes any PkiEnvironment or CoreCrypto instance unusable. Calls to these instances will return a CoreCryptoError.Other. CoreCrypto instances do not need to be closed anymore.

PKI Environment API

  • Added PkiEnvironment constructed via createPkiEnvironment(database: Database, hooks: PkiEnvironmentHooks)
  • Added PkiEnvironmentHooks interface which has to be implemented by a client and will be used by CoreCrypto during e2ei flow
  • Added CoreCrypto.setPkiEnvironment() to set a PkiEnvironment on a CoreCrypto instance
  • Added CoreCrypto.getPkiEnvironment() to get the PkiEnvironment of a CoreCrypto instance

Credential API

  • Credential is a first-class type representing a cryptographic identity.
    • It can be created at any time and lives in memory.
    • There are two variants of credential: basic and x509. Basic credentials are created with Credential.basic static method. TODO DO NOT RELEASE BEFORE REWRITING THIS X509 credentials are created with TODO TODO.
  • Initializing an MLS client no longer automatically generates any credentials. Any stored credentials will be automatically loaded on MLS init.
  • To add a credential to the set MLS knows about, after initializing MLS, call addCredential on a transaction context.
    • This adds it to the working set, and stores it to the database.
    • Due to limitations inherent in the current implementation, credentials added to a client must currently be distinct on the (credential type / signature scheme / unix timestamp of creation) tuple.
      • The time resolution is limited to 1 second.
      • If you have need of multiple credentials for a given signature scheme and credential type, just wait 1 full second between adding each of them.
      • We expect this limitation to be relaxed in the future.
    • This also returns a more lightweight CredentialRef which can be used elsewhere in the credential API, uniquely referring to a single credential which has already been added to that client.
  • CredentialRef is a means of uniquely referring to a single credential without transferring the actual credential data back and forth across FFI all the time.
    • Each credential ref is aware of basic information about the credential it references:
      • client id
      • public key
      • credential type
      • signature scheme
      • earliest validity
  • To remove a credential from the set MLS knows about, call removeCredential on a transaction context, handing it the appropriate CredentialRef.
    • Ensures the credential is not currently in use by any conversation.
    • Removes all key packages generated from this credential.
    • Removes the credential from the current working set and also from the keystore.
  • Added a new method to transaction context: getCredentials, which produces a CredentialRef for each credential known by this client.
  • Added a new method to transaction context: findCredentials, which produces a CredentialRef for each credential known by this client, efficiently filtering them by the specified criteria.

Note

CC v10.0 introduces lots of changes. We provide a migration guide.

Migrating from v9.x to v10.0

This page covers breaking changes that are identical across all platforms. For platform-specific migration steps, see the sub-pages:

MLS Initialization

  1. mlsInit() was decoupled from key package creation. To create key packages after initializing MLS, call CoreCryptoContext.generateKeyPackage() in a transaction.

  2. Removed CoreCrypto.provideTransport(), added transport parameter to CoreCryptoContext.mlsInit(). Instead of providing transport separately from MLS initialization, provide it when calling mlsInit().

Key Packages

  1. We removed CoreCryptoContext.clientKeypackages(). To generate a desired amount of key packages, make repeated calls to CoreCryptoContext.generateKeyPackage().

  2. We removed CoreCryptoContext.clientValidKeypackagesCount(). To count remaining key packages, call CoreCryptoContext.getKeyPackages(), filter the results as desired, and count the remaining items.

  3. We aligned key package spelling to KeyPackage:

    • renamed Keypackage → KeyPackage
    • renamed KeypackageRef → KeyPackageRef
    • renamed generateKeypackage → generateKeyPackage
    • renamed getKeypackages → getKeyPackages
    • renamed removeKeypackage → removeKeyPackage
    • renamed removeKeypackagesFor → removeKeyPackagesFor

  4. We aligned cipher suite spelling to CipherSuite:

    • renamed Ciphersuite -> CipherSuite

Higher-Level Newtypes

  1. GroupInfo.new() and Welcome.new() are now fallible constructors. Previously, both accepted any byte sequence unconditionally. They now validate the input as a TLS-encoded MLS structure at construction time and throw if the bytes are malformed.

  2. We removed GroupInfo.copyBytes() and Welcome.copyBytes(). The underlying types no longer store raw bytes and cannot be round-tripped back to a byte array.

  3. Added Welcome::serialize(). We had test functions which required the serialized bytes given a Welcome instance, so we added the ability to recreate those bytes.

  4. GroupInfo and Welcome no longer support equality comparisons, hashing, or hex string display in generated bindings.

  5. exportSecretKey() now returns a SecretKey object instead of a byte array. To access the raw bytes, call secretKey.copyBytes().

MlsTransport Interface

Instead of returning an MlsTransportResponse to communicate the reason why a message was rejected by the DS, throw an MlsTransportError instead. MlsTransportResponse was removed.

No More Buffering of Unmerged Changes While Decrypting

During decryption, CoreCrypto would previously automatically replay previously executed but unmerged (i.e., not yet accepted by the delivery service) operations. This behavior has changed: the responsibility of replaying any unmerged operations is delegated to the consumer.

Other Changes

  1. CoreCrypto.e2eiIsEnvSetup() can’t throw anymore and will always return a boolean.

  2. removed .proteusFingerprintPrekeybundle() and .proteusLastResortPrekeyId() from CoreCryptoContext. Both are available as static methods on CoreCrypto.

Migrating to CC 10: TypeScript

See the common migration guide for changes that apply to all platforms.

Browser Module Location

We want to prepare the ground for a native module, which runs on node or bun. Therefore, the browser module is now exported as @wireapp/core-crypto/browser. Update your imports:

// before
import { ... } from "@wireapp/core-crypto";

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

CoreCrypto Instantiation

  1. The CoreCrypto constructor now takes a Database instance instead of a DatabaseKey and a path. To instantiate a database, call openDatabase().

  2. Deferred init is now the only way to instantiate CoreCrypto. We replaced CoreCrypto.init(database: Database) with the static function CoreCrypto.new(database: Database). Instead of calling CoreCrypto.deferredInit(), call CoreCrypto.new(). As before, call mlsInit() in a transaction to initialize MLS.

Logging

  1. We removed CoreCrypto.setLogger(logger: CoreCryptoLogger, level: CoreCryptoLogLevel) and CoreCrypto.setMaxLogLevel(level: CoreCryptoLogLevel), as logging is configured globally and not tied to a CoreCrypto instance. To set the log level, use the free function setMaxLogLevel(level: CoreCryptoLogLevel).

  2. We renamed setLoggerOnly(logger: CoreCryptoLogger) to setLogger(logger: CoreCryptoLogger).

Errors

Error Structure

We adjusted the TypeScript error structure. Whenever matching on errors using version >= 9.1.0 type guards, update their usage as shown in the examples below.

Note

For more info, see the corresponding section of the ubrn docs

Extracting the abort reason given via throwing an MlsTransportError:

import { CoreCryptoError, MlsError } from "core-crypto";

try {
    // send a commit that is rejected by the DS
} catch (err) {
  if (CoreCryptoError.Mls.instanceOf(err) &&
      MlsError.MessageRejected.instanceOf(err.inner.mlsError)) {
    const rejectReason = err.inner.mlsError.inner.reason;
    // other things you want to do with this error...
  } else {
      // log error
  }
}

Optional: use switch to handle multiple errors in one go:

import { CoreCryptoError, MlsError, MlsError_Tags } from "core-crypto";

try {
    // send a commit that is rejected by the DS
} catch (err) {
    if (CoreCryptoError.Mls.instanceOf(err)) {
        switch (err.inner.mlsError.tag) {
            case MlsError_Tags.MessageRejected: {
                const rejectedReason = err.inner.mlsError.inner.reason;
                // other things you want to do with this error...
                break;
            }

            // handle other mls errors
        }
    }
}

Catch a proteus error:

import { CoreCryptoError, ProteusError } from "core-crypto";

try {
    // look for a proteus session that doesn't exist
} catch (err) {
  if (CoreCryptoError.Proteus.instanceOf(err) &&
      ProteusError.SessionNotFound.instanceOf(err.inner.exception)) {
     let message = err.inner.exception.message;
     // other things you want to do with this error...
  } else {
      // log error
  }
}

Proteus Error Codes

The proteusErrorCode field was removed from the root error type. There is a deterministic mapping from error code to error type. If you were using the error code, use the error type instead (see above). See the proteus-traits error table for the mapping.

Other

  1. CoreCryptoContext.generateKeyPackage() now returns a KeyPackage instance instead of an Uint8Array. If you need the underlying Uint8Array, call the serialize property on the KeyPackage.

  2. CustomConfiguration.keyRotationSpan now defines milliseconds instead of seconds.

Migrating to CC 10: Swift

See the common migration guide for changes that apply to all platforms.

CoreCrypto Instantiation

  1. The CoreCrypto constructor now takes a Database instance instead of a DatabaseKey and a path. To instantiate a database, call the Database.new() static method.

  2. Deferred init is now the only way to instantiate CoreCrypto. Instead of calling deferredInit(), call the CoreCrypto constructor. As before, call mlsInit() in a transaction to initialize MLS.

Higher-Level Newtypes

CoreCryptoContext.getExternalSender() now returns an ExternalSenderKey object instead of a byte array. To access the raw bytes, call externalSenderKey.copyBytes().

Logging

  1. We removed CoreCrypto.setLogger(logger: CoreCryptoLogger, level: CoreCryptoLogLevel) and CoreCrypto.setMaxLogLevel(level: CoreCryptoLogLevel), as logging is configured globally and not tied to a CoreCrypto instance. To set the log level, use the free function setMaxLogLevel(level: CoreCryptoLogLevel).

  2. We renamed setLoggerOnly(logger: CoreCryptoLogger) to setLogger(logger: CoreCryptoLogger).

Other

  1. Removed CoreCryptoFfi.reseedRng() and CoreCryptoFfi.randomBytes().

  2. Removed the following static methods from CoreCrypto that were globally available:

    • version()
    • buildMetadata()

Migrating to CC 10: Kotlin

See the common migration guide for changes that apply to all platforms.

Renames and Moves

  1. CoreCryptoClient has been renamed to CoreCrypto.

  2. historyClient(historySecret: HistorySecret) has been moved into CoreCrypto Companion functions.

  3. The entire read-only API is now exposed on the CoreCrypto type, allowing data to be read without opening a transaction.

CoreCrypto Instantiation

  1. The CoreCrypto constructor now takes a Database instance instead of a DatabaseKey and a path. To instantiate a database, call the Database.new() static method.

  2. Deferred init is now the only way to instantiate CoreCrypto. Instead of calling deferredInit(), call the CoreCrypto constructor. As before, call mlsInit() in a transaction to initialize MLS.

Higher-Level Newtypes

CoreCryptoContext.getExternalSender() now returns an ExternalSenderKey object instead of a byte array. To access the raw bytes, call externalSenderKey.copyBytes().

Logging

  1. We removed CoreCrypto.setLogger(logger: CoreCryptoLogger, level: CoreCryptoLogLevel), as logging is configured globally and not tied to a CoreCrypto instance. To set the log level, use the free function setMaxLogLevel(level: CoreCryptoLogLevel).

  2. We renamed setLoggerOnly(logger: CoreCryptoLogger) to setLogger(logger: CoreCryptoLogger).

Other

  1. Removed CoreCryptoFfi.reseedRng() and CoreCryptoFfi.randomBytes().