Wire CoreCrypto

https://github.com/wireapp/core-crypto
Admin
Wire CoreCrypto provides a unified API abstracting MLS and Proteus, with FFI bindings for various...
Tokens:13,448
Snippets:37
Trust Score:9.9
License:GPL-3.0
Update:1 year ago
Show doc for...
Tokens:
Raw
### Install core-crypto decode tool

Source: https://github.com/wireapp/core-crypto/blob/main/decode/README.md

Installs the decode tool from the core-crypto project's Git repository. This tool is used for decoding various wire formats.

```bash
cargo install --git https://github.com/wireapp/core-crypto.git[decode]
```

--------------------------------

### Install ChromeDriver on macOS

Source: https://github.com/wireapp/core-crypto/blob/main/interop/README.md

Installs ChromeDriver using Homebrew and creates a symbolic link for easy access to the chromedriver executable.

```bash
brew install --cask chromedriver &&
ln -s /usr/local/bin/chromedriver ~/.webdrivers/
```

--------------------------------

### Install GNU sed on macOS

Source: https://github.com/wireapp/core-crypto/blob/main/README.md

Installs GNU sed using Homebrew and provides instructions to create a shell alias for its usage, ensuring compatibility with build processes that rely on GNU sed.

```sh
brew install gnu-sed
alias sed=gsed
```

--------------------------------

### Run General Tests with cargo-nextest

Source: https://github.com/wireapp/core-crypto/blob/main/README.md

Executes the project's tests using `cargo-nextest`. It's recommended to install `cargo-nextest` first for potential speed improvements.

```sh
# Install cargo-nextest if you haven't done so, it yields some substantial speedup
cargo install cargo-nextest
cargo nextest run
```

--------------------------------

### Build Android CoreCrypto

Source: https://github.com/wireapp/core-crypto/blob/main/README.md

Compiles the Wire CoreCrypto project for the Android platform. This command assumes the Android SDK and NDK are installed and configured.

```sh
make android
```

--------------------------------

### Release Preparation Steps

Source: https://github.com/wireapp/core-crypto/blob/main/README.md

Detailed steps for preparing and making a new release, including version updates, changelog generation, and tagging.

```markdown
1. Make a branch based on `main` to prepare for release (`git checkout -b prepare-release/X.Y.Z`)
1. Run `sh scripts/update-versions.sh X.Y.Z` to update the versions of
    - all workspace member crates
    - `package.json`
    - `crypto-ffi/bindings/gradle.properties`
   Make sure the result of the script run is correct.
1. Generate the relevant changelog section:
   ```bash
   git cliff --bump --unreleased
   ```
   and add it to the top of `CHANGELOG.md`.
   Make sure the version number generated by `git cliff` matches the release version.
1. If there are any release highlights, add them as the first subsection below release title:
   ```markdown
   ## v1.0.2 - 2024-08-16

   ### Highlights

   - foo
   - bar
   - baz
   ```
1. In [index.md](docs/index.md), copy the commented-out table row from  the bottom of the file to the appropriate place
in the table, ordering by version number, descending. Search and replace the first 5 occurrences of `x.x.x` with `X.Y.Z`.
1. Make sure the changes look reasonable and complete; you can use the previous release as a reference
1. Push your `prepare-release/X.Y.Z` branch and create a PR for it
1. Get it reviewed, then merge it into `main` and remove the `prepare-release/X.Y.Z` branch from the remote
1. Now, pull your local `main`: `git checkout main && git pull`
1. Create the release tag: `git tag -s vX.Y.Z`
1. Push the new tag: `git push origin tag vX.Y.Z`
1. Create a new release on github, copying the relevant section from `CHANGELOG.md`
1. Voilà!
```

--------------------------------

### Git Workflow Conventions

Source: https://github.com/wireapp/core-crypto/blob/main/README.md

Guidelines for the project's Git workflow, including branch management, commit messages, and signing.

```markdown
* The `main` branch is used as the everyday development branch.
* No merge commits. Always rebase on top of `main`.
* Release branches are named `release/<series>`, e.g. `release/1.x`, `release/2.x`.
* Release branches contain fixes relevant to their specific release series and are never merged to `main`.
* Release branches always branch off their first major release tag. For example,
  the output of `git merge-base main release/2.x` must be a commit pointed to by tag `v2.0.0`.
* Release branches are created lazily, that is, only when the first fix needs to be applied and released
  for a specific release series.
* Use [conventional commits](https://www.conventionalcommits.org/en/v1.0.0/) -- those are picked up by the changelog generator.
* If there is a JIRA ticket related to the change, you should mention it in either the PR title or the commit(s),
  with the following format: `[TICKET_ID]`.
* Sign your [commits](https://docs.github.com/en/authentication/managing-commit-signature-verification/signing-commits)
  and [tags](https://docs.github.com/en/authentication/managing-commit-signature-verification/signing-tags).
* Remove branches from the remote once you don't need them anymore.
```

--------------------------------

### Manual NPM Publish

Source: https://github.com/wireapp/core-crypto/blob/main/README.md

Instructions for manually publishing the JS/WASM bindings to NPM. This involves logging into NPM and executing the publish command.

```bash
bun publish
```

--------------------------------

### CoreCrypto Keystore Architecture Diagram

Source: https://github.com/wireapp/core-crypto/blob/main/docs/KEYSTORE_IMPLEMENTATION.md

A Mermaid diagram illustrating the architecture of the CoreCrypto Keystore for both WASM and Generic (Native) targets, showing data flow and dependencies.

```mermaid
graph TD
    subgraph KS [Keystore]
        subgraph w [WASM]
            B(Keystore Entities)
            C{AES-256-GCM} -->|Stores| R[Rexie]
            B -.->|Encrypts| C
            C -.->|Decrypts| B
            R -.-> I[IndexedDB]
        end

        subgraph g [Generic]
            RS[Rusqlite] --> S[SQLCipher]
            SC{AES-256-CBC}
            S -.->|Encrypts| SC
            SC -.->|Decrypts| S
            SC -->|Stores| SF[File]
        end
    end
```

--------------------------------

### Execute Crypto Benches

Source: https://github.com/wireapp/core-crypto/blob/main/README.md

Runs benchmarks for crypto operations. Use `--quick` for faster execution or omit for higher accuracy. Remove `.without_plots()` to generate reporting plots.

```bash
cargo bench --bench=commit -- --quick
```

--------------------------------

### Wire CoreCrypto API Documentation

Source: https://github.com/wireapp/core-crypto/blob/main/README.md

Provides access to the official API documentation for the Wire CoreCrypto library. This link contains detailed information on the unified API abstracting MLS & Proteus.

```APIDOC
API Documentation:
  URL: https://wireapp.github.io/core-crypto/
```

--------------------------------

### Release from Release Branch Considerations

Source: https://github.com/wireapp/core-crypto/blob/main/README.md

Specific considerations when making a release from a release branch, including isolating changes and triggering documentation uploads.

```markdown
1. Isolate the changes to [index.md](docs/index.md) and `CHANGELOG.md` from the release commit itself
1. After the release is finished, cherry-pick the changes to [index.md](docs/index.md) and `CHANGELOG.md` and get them into `main`
1. For release series `4.x` and newer, docs upload happens automatically.
   If you released from the series `3.x` or older, you need to trigger docs upload manually:
    1. On GitHub, go to the [docs workflow](https://github.com/wireapp/core-crypto/actions/workflows/docs.yml)
    1. Click the `Run workflow` button
    1. In the `Use workflow from` dropdown, choose `release/5.x`, in `Tag to checkout` provide your release tag
```

--------------------------------

### Test All Ciphersuites

Source: https://github.com/wireapp/core-crypto/blob/main/README.md

Runs all project tests with the `test-all-cipher` feature enabled. This process is noted to be time-consuming.

```sh
cargo nextest run --features test-all-cipher
```

--------------------------------

### WireApp Core Crypto Documentation Links

Source: https://github.com/wireapp/core-crypto/blob/main/docs/index.md

Provides access to the documentation for the WireApp core crypto library. Links are categorized by language and version, allowing users to find specific API documentation for different releases and platforms.

```APIDOC
WireApp Core Crypto Documentation:

This documentation provides access to the WireApp core crypto library across various languages and versions.

Main Documentation:
- TypeScript: ./main/typescript/
- Kotlin: ./main/kotlin/
- Swift: ./main/swift/
- Rust: ./main/rust/core_crypto/

Versioned Documentation:

Version v8.0.3:
- TypeScript: ./v8.0.3/typescript
- Kotlin: ./v8.0.3/kotlin/
- Swift: ./v8.0.3/swift
- Rust: ./v8.0.3/rust/core_crypto

Version v8.0.2:
- TypeScript: ./v8.0.2/typescript
- Kotlin: ./v8.0.2/kotlin/
- Swift: ./v8.0.2/swift
- Rust: ./v8.0.2/rust/core_crypto

Version v8.0.1:
- TypeScript: ./v8.0.1/typescript
- Kotlin: ./v8.0.1/kotlin/
- Swift: ./v8.0.1/swift
- Rust: ./v8.0.1/rust/core_crypto

Version v8.0.0:
- TypeScript: ./v8.0.0/typescript-docs
- Kotlin: ./v8.0.0/kotlin-docs/
- Swift: ./v8.0.0/swift-docs
- Rust: ./v8.0.0/rust-docs/core_crypto

Version v6.0.1:
- TypeScript: ./v6.0.1/core_crypto_ffi/bindings/typescript
- Kotlin: ./v6.0.1/core_crypto_ffi/bindings/kotlin/html
- Swift: ./v6.0.1/core_crypto_ffi/bindings/swift
- Rust: ./v6.0.1/core_crypto

Version v6.0.0:
- TypeScript: ./v6.0.0/core_crypto_ffi/bindings/typescript
- Kotlin: ./v6.0.0/core_crypto_ffi/bindings/kotlin/html
- Swift: ./v6.0.0/core_crypto_ffi/bindings/swift
- Rust: ./v6.0.0/core_crypto

Version v5.4.0:
- TypeScript: ./v5.4.0/core_crypto_ffi/bindings/typescript
- Kotlin: ./v5.4.0/core_crypto_ffi/bindings/kotlin/html
- Swift: ./v5.4.0/core_crypto_ffi/bindings/swift
- Rust: ./v5.4.0/core_crypto

Version v5.3.0:
- TypeScript: ./v5.3.0/core_crypto_ffi/bindings/typescript
- Kotlin: ./v5.3.0/core_crypto_ffi/bindings/kotlin/html
- Swift: ./v5.3.0/core_crypto_ffi/bindings/swift
- Rust: ./v5.3.0/core_crypto

Version v5.2.0:
- TypeScript: ./v5.2.0/core_crypto_ffi/bindings/typescript
- Kotlin: ./v5.2.0/core_crypto_ffi/bindings/kotlin/html
- Swift: ./v5.2.0/core_crypto_ffi/bindings/swift
- Rust: ./v5.2.0/core_crypto

Version v5.1.0:
- TypeScript: ./v5.1.0/core_crypto_ffi/bindings/typescript
- Kotlin: ./v5.1.0/core_crypto_ffi/bindings/kotlin/html
- Swift: ./v5.1.0/core_crypto_ffi/bindings/swift
- Rust: ./v5.1.0/core_crypto

Version v5.0.0:
- TypeScript: ./v5.0.0/core_crypto_ffi/bindings/typescript
- Kotlin: ./v5.0.0/core_crypto_ffi/bindings/kotlin/html
- Swift: ./v5.0.0/core_crypto_ffi/bindings/swift
- Rust: ./v5.0.0/core_crypto

Version v4.2.3:
- TypeScript: ./v4.2.3/core_crypto_ffi/bindings/typescript
- Kotlin: ./v4.2.3/core_crypto_ffi/bindings/kotlin/html
- Swift: ./v4.2.3/core_crypto_ffi/bindings/swift
- Rust: ./v4.2.3/core_crypto

Version v4.2.2:
- TypeScript: ./v4.2.2/core_crypto_ffi/bindings/typescript
- Kotlin: ./v4.2.2/core_crypto_ffi/bindings/kotlin/html
- Swift: ./v4.2.2/core_crypto_ffi/bindings/swift
- Rust: ./v4.2.2/core_crypto

Version v4.2.1:
- TypeScript: ./v4.2.1/core_crypto_ffi/bindings/typescript
- Kotlin: ./v4.2.1/core_crypto_ffi/bindings/kotlin/html
- Swift: ./v4.2.1/core_crypto_ffi/bindings/swift
- Rust: ./v4.2.1/core_crypto

Version v4.2.0:
- TypeScript: ./v4.2.0/core_crypto_ffi/bindings/typescript
- Kotlin: ./v4.2.0/core_crypto_ffi/bindings/kotlin/html
- Swift: ./v4.2.0/core_crypto_ffi/bindings/swift
- Rust: ./v4.2.0/core_crypto

Note: The 'main' links point to the latest documentation, while versioned links provide access to historical documentation.
```

--------------------------------

### Native Keystore Implementation Details

Source: https://github.com/wireapp/core-crypto/blob/main/docs/KEYSTORE_IMPLEMENTATION.md

Details on the Native (iOS, Android) implementation of the CoreCrypto Keystore, focusing on SQLCipher configurations, encryption methods, and platform-specific adaptations.

```plaintext
SQLCipher's file page size by default is 4096 bytes
When using a passphrase (our case), the provided passphrase is derived using PBKDF2-HMAC-SHA512. The salt of this KDF is stored in the 16 first bytes of the file.
    Note: This cannot be kept as-is on iOS as iOS needs to be able to read the first 16-32 bytes of SQLite databases to "magically" guess they are SQLite databases and to allow reading them from the background. This is very useful in the case of background work on iOS such as encrypted data in notifications needing access to the keystore. It's also used for working with a Watch App.
Each page is encrypted or decrypted on-the-fly using AES256-CBC
    Provided by OpenSSL -v1.1.1p as of 29/06/22- in our case, but the crypto provider can be changed to NSS, LibTomCrypt or Security.framework
Each page is written with a unique, random IV (*initialization vector*). This IV is regenerated on each page write. This IV is appended at the end of each page.
Page ciphertexts are authenticated using an authentication tag using HMAC-SHA512. This tag is also appended at the each of the page.
```

--------------------------------

### Build Bindings for JVM, Android, iOS, and WASM

Source: https://github.com/wireapp/core-crypto/blob/main/README.md

A set of make commands to build bindings and targets for various platforms: JVM (macOS/Linux), Android, iOS (as XCFramework), and WASM (with TS bindings).

```sh
# builds bindings and targets for the JVM (macOS / Linux)
make jvm

# builds bindings and targets for Android
make android

# builds iOS framework
make ios-create-xcframework

# builds wasm binary & TS bindings
make ts
```

--------------------------------

### Core Crypto Bindings - v3.1.1

Source: https://github.com/wireapp/core-crypto/blob/main/docs/index.md

Provides access to the core crypto functionalities for WireApp in version 3.1.1. Includes bindings for TypeScript, Kotlin, Swift, and Rust.

```TypeScript
import { CoreCrypto } from './v3.1.1/core_crypto_ffi/bindings/typescript';
// Usage example:
// const crypto = new CoreCrypto();
// crypto.encrypt(...);
```

```Kotlin
import app.wire.corecrypto.CoreCrypto
// Usage example:
// val crypto = CoreCrypto()
// crypto.encrypt(...)
```

```Swift
import CoreCrypto
// Usage example:
// let crypto = CoreCrypto()
// crypto.encrypt(...)
```

```Rust
use core_crypto::CoreCrypto;
// Usage example:
// let crypto = CoreCrypto::new();
// crypto.encrypt(...)
```

--------------------------------

### Build WASM CoreCrypto

Source: https://github.com/wireapp/core-crypto/blob/main/README.md

Builds the Wire CoreCrypto project for the WebAssembly (WASM) target, including TypeScript bindings. Requires wasm-pack and Node.js/Bun.

```sh
make ts
```

--------------------------------

### Core Crypto Bindings - v3.1.0

Source: https://github.com/wireapp/core-crypto/blob/main/docs/index.md

Provides access to the core crypto functionalities for WireApp in version 3.1.0. Includes bindings for TypeScript, Kotlin, Swift, and Rust.

```TypeScript
import { CoreCrypto } from './v3.1.0/core_crypto_ffi/bindings/typescript';
// Usage example:
// const crypto = new CoreCrypto();
// crypto.encrypt(...);
```

```Kotlin
import app.wire.corecrypto.CoreCrypto
// Usage example:
// val crypto = CoreCrypto()
// crypto.encrypt(...)
```

```Swift
import CoreCrypto
// Usage example:
// let crypto = CoreCrypto()
// crypto.encrypt(...)
```

```Rust
use core_crypto::CoreCrypto;
// Usage example:
// let crypto = CoreCrypto::new();
// crypto.encrypt(...)
```

--------------------------------

### CoreCrypto Naming Conventions

Source: https://github.com/wireapp/core-crypto/blob/main/docs/FFI.md

This table outlines the standard naming conventions used across different languages for CoreCrypto development, including methods, variables, and classes.

```markdown
| Item                | Rust         | Swift        | Kotlin       | TypeScript   |
|---------------------|--------------|--------------|--------------|--------------|
| Methods/Functions   | `snake_case` | `camelCase`  | `camelCase`  | `camelCase`  |
| Variables/Arguments | `snake_case` | `camelCase`  | `camelCase`  | `camelCase`  |
| Classes/Interfaces  | `PascalCase` | `PascalCase` | `PascalCase` | `PascalCase` |
```

--------------------------------

### Platform-specific Tests for Kotlin/JVM

Source: https://github.com/wireapp/core-crypto/blob/main/README.md

Executes tests specifically for the Kotlin/JVM platform.

```sh
make jvm-test
```

--------------------------------

### Build iOS CoreCrypto

Source: https://github.com/wireapp/core-crypto/blob/main/README.md

Compiles the Wire CoreCrypto project for iOS. It also includes an option to export the build as an XCFramework.

```sh
make ios
# Additionally, if you want to export a .XCFramework:
make ios-create-xcframework
```

--------------------------------

### Publish Android/JVM Bindings to Local Maven Cache

Source: https://github.com/wireapp/core-crypto/blob/main/README.md

Publishes the Android and JVM bindings to a local Maven cache for testing or development.

```ignore
cd crypto-ffi/bindings/android
./gradlew :jvm:publishToMavenLocal
./gradlew :android:publishToMavenLocal
```

--------------------------------

### Decode Proteus PreKey Bundle

Source: https://github.com/wireapp/core-crypto/blob/main/decode/README.md

Demonstrates how to decode a Proteus prekey bundle using the decode tool. The output shows the structured data of the bundle, including version, prekey ID, public key, and identity key.

```bash
decode prekey-bundle pQABAQoCoQBYIJHnFfQBrfDW+f0MNoaGxi63gLbFMRfqfVGPhiLl5AWYA6EAoQBYIGOJPLc39t4CVMcwil00ri/XSvML7LF3IP2zg+YstiHuBPY=
```

```text
ProteusPreKeyBundle {
    version: 1,
    prekey_id: 10,
    public_key: "91e715f401adf0d6f9fd0c368686c62eb780b6c53117ea7d518f8622e5e40598",
    identity_key: "63893cb737f6de0254c7308a5d34ae2fd74af30becb17720fdb383e62cb621ee",
    signature: None,
}
```

--------------------------------

### Rust Crypto Primitives

Source: https://github.com/wireapp/core-crypto/blob/main/docs/CRYPTO_DEPENDENCIES.md

Lists various cryptographic primitives and their corresponding Rust repositories. Includes information on known audits for some implementations.

```rust
// P256
// Repository: https://github.com/RustCrypto/elliptic-curves/tree/master/p256

// P384
// Repository: https://github.com/RustCrypto/elliptic-curves/tree/master/p384

// Curve25519
// Repository: https://github.com/dalek-cryptography/curve25519-dalek/tree/main/curve25519-dalek

// Ed25519
// Repository: https://github.com/dalek-cryptography/ed25519-dalek

// X25519
// Repository: https://github.com/dalek-cryptography/x25519-dalek

// SHA2
// Repository: https://github.com/RustCrypto/hashes/tree/master/sha2

// HMAC
// Repository: https://github.com/RustCrypto/MACs/tree/master/hmac

// AES-GCM
// Repository: https://github.com/RustCrypto/AEADs/tree/master/aes-gcm
// Audit: https://research.nccgroup.com/2020/02/26/public-report-rustcrypto-aes-gcm-and-chacha20poly1305-implementation-review/

// ChaCha20Poly1305
// Repository: https://github.com/RustCrypto/AEADs/tree/master/chacha20poly1305
// Audit: https://research.nccgroup.com/2020/02/26/public-report-rustcrypto-aes-gcm-and-chacha20poly1305-implementation-review/

// HKDF
// Repository: https://github.com/RustCrypto/KDFs/tree/master/hkdf

// HPKE
// Repository: https://github.com/rozbb/rust-hpke/tree/main
// Security Note: https://github.com/rozbb/rust-hpke/tree/main#warning
```

--------------------------------

### Keystore Implementation Details

Source: https://github.com/wireapp/core-crypto/blob/main/docs/ARCHITECTURE.md

Details the implementation of the keystore, which handles secure storage of keying material. It uses SQLCipher on most platforms and IndexedDB with AES256-GCM on WebAssembly.

```rust
/// On most platforms, the keystore relies on [SQLCipher](https://www.zetetic.net/sqlcipher/) to persist & encrypt data
/// On WebAssembly (TS/JS bindings for the web & electron), the keystore calls into the browser's `IndexedDB` to persist data and AES256-GCM to encrypt data (via `RustCrypto`).
```

--------------------------------

### CoreCrypto Type Equivalences

Source: https://github.com/wireapp/core-crypto/blob/main/docs/FFI.md

This table maps CoreCrypto's Rust data types to their equivalents in Swift, Kotlin, and TypeScript, facilitating cross-language development.

```markdown
| Rust                    | Swift                              | Kotlin                     | TypeScript                               |
|-------------------------|------------------------------------|----------------------------|------------------------------------------|
| `bool`                  | `Bool`                             | `Boolean`                  | `boolean`                                |
| `u8`                    | `UInt8`                            | `UByte`                    | `number`                                 |
| `u16`                   | `UInt16`                           | `UShort`                   | `number`                                 |
| `u32`                   | `UInt32`                           | `UInt`                     | `number`                                 |
| `u64`                   | `UInt64`                           | `ULong`                    | `number`                                 |
| `i8`                    | `Int8`                             | `Byte`                     | `number`                                 |
| `i16`                   | `Int16`                            | `Short`                    | `number`                                 |
| `i32`                   | `Int32`                            | `Int`                      | `number`                                 |
| `i64`                   | `Int64`                            | `Long`                     | `number`                                 |
| `f32`                   | `Float`                            | `Float`                    | `number`                                 |
| `f64`                   | `Double`                           | `Double`                   | `number`                                 |
| `String` / `&str`       | `String`                           | `String`                   | `string`                                 |
| `std::time::SystemTime` | `Date`                             | `java.time.Instant`        | `Date`                                   |
| `std::time::Duration`   | `TimeInterval`                     | `java.time.Duration`       | `number` (in milliseconds)               |
| `Option<T>`             | `Optional<T>`                      | `Optional<T>`              | `T?`                                     |
| `Vec<T>`                | `Array<T>`                         | `List<T>`                  | `Array<T>`                               |
| `HashMap<String, T>`    | `Dictionary<String, T>`            | `Map<String, T>`           | `Record<string, T>`                      |
| `()`                    | `nil`                              | `null`                     | `null`                                   |
| `Result<T, E>`          | `func placeholder() throws E -> T` | `T placeholder() throws E` | `function placeholder(): T // @throws E` |
```

--------------------------------

### CoreCryptoFFI Bindings

Source: https://github.com/wireapp/core-crypto/blob/main/docs/ARCHITECTURE.md

Explains how CoreCryptoFFI enables interaction with other languages and platforms. It utilizes UniFFI for iOS/Android and wasm-bindgen/wasm-pack for WebAssembly.

```rust
// For iOS and Android, [UniFFI](https://github.com/mozilla/uniffi-rs) is used to produce the relevant Kotlin and Swift bindings
// For JS/TS, a WebAssembly binary is produced using [wasm-bindgen](https://github.com/rustwasm/wasm-bindgen) and [wasm-pack](https://rustwasm.org/wasm-pack/)
```

--------------------------------

### Update Versions Script

Source: https://github.com/wireapp/core-crypto/blob/main/README.md

Updates version numbers across multiple project files including workspace crates, package.json, and gradle.properties.

```bash
sh scripts/update-versions.sh X.Y.Z
```

--------------------------------

### Platform-specific Tests for Android

Source: https://github.com/wireapp/core-crypto/blob/main/README.md

Executes tests specifically for the Android platform.

```sh
make android-test
```

--------------------------------

### Generate Changelog Section

Source: https://github.com/wireapp/core-crypto/blob/main/README.md

Generates a changelog section based on Git commits, useful for preparing new releases.

```bash
git cliff --bump --unreleased
```

--------------------------------

### Platform-specific Tests for WASM/Web

Source: https://github.com/wireapp/core-crypto/blob/main/README.md

Executes tests specifically for the WASM/Web platform. Allows control over log verbosity using the `CC_TEST_LOG_LEVEL` environment variable.

```sh
make ts-test
# Note the CC_TEST_LOG_LEVEL environment variable. At 1 it emits browser console logs; at 2 it also emits CoreCrypto logs.
```

--------------------------------

### Test CoreCrypto Internal Tests on WASM Target

Source: https://github.com/wireapp/core-crypto/blob/main/README.md

Runs internal tests for the CoreCrypto crate targeting WASM. Requires `wasm-pack` and the `wasm32-unknown-unknown` toolchain. Supports headless testing with specific browsers like Chrome.

```sh
rustup target add wasm32-unknown-unknown
cargo install wasm-pack

# If you want to test for chrome, [get chromedriver](https://getwebdriver.com/chromedriver) or the webdriver for the
# browser you want to test for, respectively.

wasm-pack test --headless --chrome ./<crate-folder-to-test>
```

--------------------------------

### Rust CSPRNG Implementation

Source: https://github.com/wireapp/core-crypto/blob/main/docs/CRYPTO_DEPENDENCIES.md

Details the implementation of a Cryptographically Secure Pseudo-Random Number Generator (CSPRNG) using the `rand` and `rand-chacha` crates, with `getrandom` for entropy sourcing.

```rust
// CSPRNG using rand and rand-chacha
// Underlying entropy source: getrandom
// Entropy sources per platform: https://docs.rs/getrandom/latest/getrandom/#supported-targets

// Note: No formal audits are known for this specific combination, but it relies on widely-used ecosystem crates.
```

--------------------------------

### Decode MLS Message

Source: https://github.com/wireapp/core-crypto/blob/main/decode/README.md

Shows how to decode an MLS (Messaging Layer Security) message. The output provides a detailed breakdown of the message structure, including version, group ID, epoch, sender, and signature.

```bash
decode mls-message AAEAATQAAQAA0T+Dx7aERkqm8jl1oWIAQgpjb25mZXJlbmNlAAAAAHN0YWdpbmcuemluZnJhLmlvAAAAAAAAAEMCAAAAAAACAAMAAAAHQEgwRgIhAOrk4aL0X6mJwCJWyNzKHIr5qXt05gx5FyP4rmcgviyYAiEAmUwSh7zTqTJAifMn/UnAVNjZKR19DukHS6iVkIP64Oo=
```

```text
MlsMessageIn {
    version: Mls10,
    body: PublicMessage(
        PublicMessageIn {
            content: FramedContentIn {
                group_id: GroupId {
                    value: VLBytes { 0x00010000d13f83c7b684464aa6f23975a16200420a636f6e666572656e63650000000073746167696e672e7a696e6672612e696f },
                },
                epoch: GroupEpoch(
                    67,
                ),
                sender: External(
                    SenderExtensionIndex(
                        0,
                    ),
                ),
                authenticated_data: VLBytes { b"" },
                body: Proposal(
                    Remove(
                        RemoveProposal {
                            removed: LeafNodeIndex(
                                7,
                            ),
                        },
                    ),
                ),
            },
            auth: FramedContentAuthData {
                signature: Signature {
                    value: VLBytes { 0x3046022100eae4e1a2f45fa989c02256c8dcca1c8af9a97b74e60c791723f8ae6720be2c98022100994c1287bcd3a9324089f327fd49c054d8d9291d7d0ee9074ba8959083fae0ea },
                },
                confirmation_tag: None,
            },
            membership_tag: None,
        },
    ),
}
```

--------------------------------

### WASM Keystore Value-Level Encryption

Source: https://github.com/wireapp/core-crypto/blob/main/docs/KEYSTORE_IMPLEMENTATION.md

Explanation of the value-level encryption mechanism used in the WASM implementation of the CoreCrypto Keystore, detailing the process of encrypting and decrypting fields using AES256-GCM.

```plaintext
Consumers of the library are required to provide 32 bytes, generated by a CSPRNG or a hardware RNG, to be used as an AES-256 key
Entities (i.e. Models in an ORM environment) dictate which fields are encrypted and with which AAD through their implementation of the `Entity` trait.
By default, the AAD is the primary ID of the IndexedDB collection (i.e Table in a SQL database environment)
AES256-GCM is used to encrypt the aforementioned fields
    A random 96-bit (12 bytes) Nonce is generated
    The AAD is fetched through `Entity::aad()`
    Together they are fed to [`aes-gcm`](https://crates.io/crates/aes-gcm) to create a ciphertext with embedded authentication tag
The ciphertext is then stored along with its nonce with the following data layout:
    Cleartext: A buffer of N bytes (`[u8; N]`)
    Ciphertext: `[12 bytes of nonce..., ...ciphertext]`
When decrypting, the stored nonce is picked apart from the ciphertext, the AAD is also fetched, then the cleartext is decrypted and returned
Note: All the fields from all entities are zeroed on drop for security reasons
```

--------------------------------

### Dump Keystore Data

Source: https://github.com/wireapp/core-crypto/blob/main/keystore-dump/README.md

Exports the content of an encrypted keystore database file to JSON format. This is useful for development and troubleshooting when direct introspection of encrypted data is needed. Requires the encryption key and the path to the database file. Note: This functionality is not available for WASM.

```shell
# Example usage (assuming a command 'keystore-dump' exists):
# keystore-dump --key <encryption_key> --db-path <path_to_database_file> --output <output_json_file>
```
Tokens:
Raw