# Code artifact for `sigma-rs`

This repository contains the code artifact for `sigma-rs`, a Rust
software stack for implementing protocols based on keyed-verification
anonymous credentials (KVAC).  This software stack was presented in:

   - Michele Orrù, Lindsey Tulloch, Victor Snyder-Graf, Ian Goldberg.
     "[sigma-rs: A Modular Approach for Keyed-Verification Anonymous
     Credentials](https://eprint.iacr.org/2026/794)", USENIX Security
     Symposium, 2026.

The `sigma-rs` stack consists of the following components (listed along
with the versions pinned in this artifact):

  - [`spongefish`](https://github.com/arkworks-rs/spongefish/tree/v0.6.1)
    tag `v0.6.1`
  - [`sigma-proofs`](https://github.com/sigma-rs/sigma-proofs/tree/v0.3.1)
    tag `v0.3.1`
  - [`sigma-compiler`](https://git-crysp.uwaterloo.ca/SigmaProtocol/sigma-compiler/src/0.2.2)
    tag `0.2.2`
  - [`cmz`](https://git-crysp.uwaterloo.ca/SigmaProtocol/cmz/src/0.2.1)
    tag `0.2.1`

This artifact also evaluates two sample applications using this stack,
described in the paper:

  - [`application-ooni`](https://github.com/ooni/userauth/tree/artifact-v0.4)
    tag `artifact-v0.4`
  - [`application-lox`](https://gitlab.torproject.org/onyinyang/lox/-/tree/lox-artifact)
    tag `lox-artifact`

We also include for comparison a version of `application-lox` that uses
[an update](https://gitlab.torproject.org/onyinyang/lox-zkp) of the
older [`zkp`](https://github.com/zkcrypto/zkp/tree/0.8.0) crate, instead
of our `sigma-rs` stack:

  - [`application-lox-zkp`](https://gitlab.torproject.org/onyinyang/lox/-/tree/lox-artifact-zkp)
    tag `lox-artifact-zkp`

## Artifact structure

The directories in this repository are as follows:

  - [`Scripts`](Scripts/): Useful scripts for building a docker image for this artifact, and running tests therein
  - [`patches`](patches/): Patches to the Cargo.toml file for our `sigma-rs` collection of
    crates, to force them to use the local copies of each other as
    dependencies, rather than using the published versions from crates.io.
    These patches are applied automatically by the `build-docker` script.

## Host requirements

This document will assume your host is Ubuntu 24.04, but any similar
system should be fine.  You will need installed on the host:

  - `git`
  - Either `docker` or `podman`.  The scripts will auto-detect which of
    `docker` or `podman` you have.  The _names_ of the scripts contain
    the word "`docker`", even if they end up using `podman` instead.
  - A wasm-capable web browser, which is pretty much any modern browser.
    You cannot use Tor browser, since you'll be connecting to a
    localhost web server, which you cannot do over the Tor network.
  - If your host CPU has AVX2 or AVX512 support, the runtimes will be
    noticeably faster, but the artifact will still work if you don't
    have them.

To execute the OONI iOS benchmarks (the "iOS" column in Figure 3 in the
paper), you will need a Mac host with Xcode installed, and an iOS device
on which you can install apps you compile yourself.

## Building the artifact

After downloading or cloning this repository, build a docker image with:
```bash
  ./Scripts/build-docker
```

On a recentish laptop, this image should take around 10 minutes to build.  The resulting image is about 9 GB.

## Running the unit tests

To ensure everything has built properly, you should run the unit tests within the docker with:

```bash
  Scripts/run-docker Scripts/run_all_tests
```

This should take less than 30 seconds to run.

## Running the Lox native and wasm benchmarks

To run the Lox native and wasm benchmarks (Tables 2 and 5 of the paper):

```bash
  Scripts/run-docker Scripts/run_lox_benches
```

When the wasm benchmarks are run (twice: once for the new `sigma-rs`
version of Lox, and once for the original `zkp` version), the script
will prompt you with a URL to load in a wasm-capable web browser.  Do so
when prompted each of the two times.

These benchmarks should take a couple of minutes to run.

The output of the script will end with the data tables corresponding to
Tables 2 and 5 in the paper.  The values in Table 2 are times in
milliseconds (with stddevs in parens).  The values in Table 5 are sizes
in bytes.

## Running the OONI native benchmarks

To run the OONI native benchmarks (the "native" columns in Table 3):

```bash
  Scripts/run-docker Scripts/run_ooni_benches
```

These benchmarks should take less than 30 seconds to run.

The output of the script will be the data tables corresponding to
the "native" columns of Table 3 in the paper.  The values are times in
milliseconds (means and stddevs).

## Running the OONI iOS benchmarks

To run the OONI iOS benchmarks (the "iOS" column in Table 3), build the iOS app using the instructions in [the `ios/README.md` file in the OONI repository](https://github.com/ooni/userauth/blob/artifact-v0.4/ios/README.md).
You would typically run these instructions to build the iOS app on a Mac host with Xcode installed, not in a docker.

## Using `sigma-rs` in your own code

For instructions on using the `sigma-rs` stack to implement your own
KVAC protocols, see [`README.md` in the `cmz` repository](https://git-crysp.uwaterloo.ca/SigmaProtocol/cmz/src/0.2.1/README.md).