Abstracts MLS and Proteus into a unified API, provides FFI bindings for various platforms, and includes an encrypted keystore using SQLCipher or AES256-GCM. Offers comprehensive build instructions and versioning guidelines.
Surfaced from shared tags and platforms — no rankings paid for.
This repository is part of the source code of Wire. You can find more information at wire.com or by contacting opensource@wire.com.
You can find the published source code at github.com/wireapp/wire.
For licensing information, see the attached LICENSE file and the list of third-party licenses at wire.com/legal/licenses/.
No license is granted to the Wire trademark and its associated logos, all of which will continue to be owned exclusively by Wire Swiss GmbH. Any use of the Wire trademark and/or its associated logos is expressly prohibited without the express prior written consent of Wire Swiss GmbH.
cargo install --locked cargo-nextestpre-commit frameworkpre-commit install to initialize the pre-commit hookscurl -s "https://get.sdkman.io" | bashsdk install java 17.0.17-temsdk install kotlinmake jvm # make the JVM target
make jvm-test # make and test the JVM target
Install Android SDK and Build-Tools for API level 30+
[!IMPORTANT] If you are building on macOS you'll need to setup
$ANDROID_SDK_ROOTpath variable manually:export ANDROID_SDK_ROOT=~/Android/Sdk
Install the Android NDK. Make sure to set the
ANDROID_NDK_HOME variable to point to the NDK installation.
Install android rust targets:
rustup target add x86_64-linux-android aarch64-linux-android armv7-linux-androideabi
Build:
make android
Install Xcode & its command-line tools: https://developer.apple.com/xcode/.
Install Sourcery
brew install sourcery
Install iOS rust targets:
rustup target add aarch64-apple-ios aarch64-apple-ios-sim
Build:
make ios
# Additionally, if you want to export a .XCFramework:
make ios-create-xcframework
Install macOS rust targets:
rustup target add aarch64-apple-darwin
[!NOTE] If cross-compiling from macOS, you'll need to install https://github.com/messense/homebrew-macos-cross-toolchains.
Install Linux targets:
rustup target add x86_64-unknown-linux-gnu
Make sure you have all prerequisites:
Build:
make ts # make the typescript target
make ts-test # make the typescript target and run tests
Build bindings for Android, JVM, iOS and WASM
# 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
cargo nextest run
[!WARNING] This takes quite a while.
cargo nextest run --features test-all-cipher
Sometimes for the Keystore it is valuable to run Rust unit/integration tests on the WASM target.
wasm-pack: cargo install wasm-pack.Then, just use wasm-pack to run the tests:
wasm-pack test --headless --chrome -- ./keystore --locked
Run tests containing the word proteus, additionally enabling the feature proteus-keystore:
wasm-pack test --headless --chrome -- ./keystore --locked --features proteus-keystore -- proteus
Unfortunately it appears that nextest doesn't work well with the wasm runner, so we're stuck with the basic test runner.
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.
make jvm-test
make android-test
Currently works on macOS only.
make ios-test
chromedrivermake interop-testSome tests require a working container runtime, so make sure to prepare one before running all tests. Platform-specific instructions follow below.
Make sure to start the Docker service if it is not already running:
systemctl start docker.service
# start socket activation, which will cause Podman to start once
# anything connects to the socket:
systemctl --user start podman.socket
# check that socket activation works
podman version
# if the above didn't work, depending on the distribution and installed packages,
# it may be necessary to configure the DOCKER_HOST variable to point to Podman's socket
export DOCKER_HOST=unix:///run/user/$UID/podman/podman.sock
Note: Docker under macOS requires Docker Desktop, which must run as a GUI application.
# install docker and docker-desktop
brew install docker docker-desktop
# start the Docker daemon by launching docker-desktop as a GUI application
# check if everything went fine
docker version
# install Podman
brew install podman
# install podman-mac-helper
sudo podman-mac-helper install
# create new VM based on machine-os:5.5; note that we're explicitly specifying
# an older image version because the newest one seems to be broken
podman machine init --image docker://quay.io/podman/machine-os:5.5
# start the machine
podman machine start
# if everything went well, this should print server version `5.5.x`
podman version
# symlink docker to podman (test scripts and code assume existence
# of the `docker` command)
ln -s /opt/homebrew/bin/podman /opt/homebrew/bin/docker
Choose the OIDC identity provider to use in tests by setting the TEST_IDP variable:
# use Keycloak
export TEST_IDP=keycloak
# or Authelia
export TEST_IDP=authelia
Simply execute the run-e2ei-tests.sh script:
bash scripts/run-e2ei-tests.sh
The script will take care of cleaning up processes and containers that are started during tests.
run-e2ei-tests.sh forwards its arguments to cargo nextest, which can be used to run a specific test, or any subset
of tests, e.g.
bash scripts/run-e2ei-tests.sh alg::p256
First, you need to start test-wire-server:
$ cargo run --locked --bin test-wire-server
[...]
127.0.0.1:20530
Note the IP and port printed by test-wire-server and export that as TEST_WIRE_SERVER_ADDR:
export TEST_WIRE_SERVER_ADDR=127.0.0.1:20530
Now that the environment is ready, you can run a specific test, or any subset of tests, e.g.
cargo nextest run --locked --ignore-default-filter -p wire-e2e-identity alg::p256
Once you are done with testing, terminate the IdP container that has been started:
# if you're using Keycloak
docker kill keycloak && docker rm keycloak
# if you're using Authelia
docker kill authelia.local && docker rm authelia.local
as well as the test-wire-server instance.
For all languages we provide make rules for formatting and checking.
make fmt
We're using swift-format to format swift files and use swiftlint for linting.
We're using ktlint to format and lint kotlin files.
We're using mdformat for consistent formatting of our markdown files. Install it with the following extensions
mdformat-gfmmdformat-frontmattermdformat-footnotemdformat-gfm-alertsmdformat-tocWe're using taplo to format .toml files.
Every night we run benchmarks on the main branch and publish the results on the
CoreCrypto Benchmarks page.
There are benchmarks for jvm, browser, and ts-native bindings run via the corresponding make rule. You can filter
Benchmarks by setting BENCH.
make jvm-bench
make ts-browser-bench
make ts-native-bench
We can attach a profiler to the JVM benchmarks. We provide configuration for async-profiler via make.
Install async-profiler
Set ASYNC_PROFILER_LIB to the .so or .dylib file of the installation, e.g. :
export ASYNC_PROFILER_LIB=<install-path>/async-profiler/4.3/lib/libasyncProfiler.dylib
You can then create flamegraphs for any jvm benchmarks using:
make jvm-bench PROFILE=1
Results are saved to core-crypto/crypto-ffi/bindings/jvm/build/reports/async.
The versioning scheme used is SemVer AKA Semantic Versioning.
Install the wasm32-unknown-unknown toolchain: rustup target add wasm32-unknown-unknown
Install node.js (recommended way is via Volta)
Install Bun (follow the instructions on Bun's website)
Install wasm-bindgen-cli:
wasm_bindgen_version="$(
cargo metadata --format-version 1 |
jq -r '.packages[] | select (.name == "wasm-bindgen") | .version'
)"
cargo install wasm-bindgen-cli --version $wasm_bindgen_version
It is important to ensure that the wasm-bindgen-cli version always precisely matches the wasm-bindgen version in
Cargo.lock (as shown by cargo info wasm-bindgen), because otherwise the wasm tests will not run.
Install chromedriver
bunx @puppeteer/browsers install --path ~/bin chrome-headless-shell
bunx @puppeteer/browsers install --path ~/bin chromedriver
Install binaryen tools:
td="$(mktemp -d)"
pushd "$td"
case "$(uname -s)" in
Linux) os=linux ;;
Darwin) os=macos ;;
MINGW*|MSYS*|CYGWIN*) os=windows ;;
*) echo "unsupported OS: $(uname -s)" >&2; exit 1 ;;
esac
case "$(uname -m)" in
x86_64|amd64) arch=x86_64 ;;
aarch64|arm64) [[ "$os" == linux ]] && arch=aarch64 || arch=arm64 ;;
*) echo "unsupported architecture: $(uname -m)" >&2; exit 1 ;;
esac
version="$(gh release view --repo WebAssembly/binaryen --json tagName --jq .tagName)"
tarball="binaryen-${version}-${arch}-${os}.tar.gz"
gh release download --repo webassembly/binaryen --pattern "$tarball" --pattern "${tarball}.sha256"
sha256sum -c "${tarball}.sha256"
tar -xzf "$tarball"
mkdir -p "$HOME/bin"
cp "binaryen-$version"/bin/* "$HOME/bin/"
popd
rm -rf "$td"
make rust-fmtmake swift-fmtmake kotlin-fmtmake ts-fmtmake check
make rust-checkmake swift-checkmake kotlin-checkmake ts-checkmain branch is used as the everyday development branch.main.release/<series>, e.g. release/1.x, release/2.x.main.git merge-base main release/2.x must be a commit pointed to by tag v2.0.0.[TICKET_ID].Make a branch based on main to prepare for release (git checkout -b prepare-release/X.Y.Z)
Adjust the release notes of the cc-book. Rename the Unreleased section to the current release title and summarize highlights of the release in the first paragraph:
### v1.0.2 - 2024-08-16
- foo
- bar
- baz
In 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.
Run sh scripts/update-versions.sh X.Y.Z to update the versions of
package.jsoncrypto-ffi/bindings/gradle.properties Make sure the result of the script run is correct.Make sure the changes look reasonable and complete; you can use the previous release as a reference
Push your prepare-release/X.Y.Z branch and create a PR for it
Get it reviewed, then merge it into main and remove the prepare-release/X.Y.Z branch from the remote
Now, pull your local main: git checkout main && git pull
Create the release tag: git tag -s vX.Y.Z
Push the new tag: git push origin tag vX.Y.Z
Create a new release on github, copying the release notes
Voilà!