longfellow-zk: zero-knowledge proofs about identity documents you already have

Proving things about credentials that already exist

The scope statement is precise and it explains why the project exists.

The library enables the construction of zero-knowledge protocols concerning legacy identity verification standards such as the ISO MDOC standard, the JWT standard and W3C Verifiable Credentials.

The word legacy is doing the work in that sentence. The point is not to invent a new credential format, it is to make the formats that are already deployed provable. A user holds an ISO MDOC document or a JWT or a verifiable credential, and the holder wants to prove a property of it to a verifier, such as that they are over a certain age or that a particular field has a particular value, without revealing the document and without the verifier learning anything else about it.

That is a harder problem than it sounds. A JWT is a signed token, and the natural way to prove a claim about one is to present the token, which discloses everything in it. A zero-knowledge proof about the same token has to convince the verifier of a statement about the signature and the payload without revealing either.

The project is named after the bridge outside the Google Cambridge office, and it carries the Apache 2.0 licence. The implementation is in C++, and the documentation site is separate from the repository, which is a sensible arrangement for a project whose real content is a specification as much as an implementation.

The described use of the library is construction rather than consumption. The expectation is that you read the papers and the draft, understand the protocol, and assemble it from the library's components for your own credential format.

Three documents define the design

The overview lists three references, and each one is a different kind of document, which is itself a signal about how to evaluate the project.

The first is the academic work, a paper titled anonymous credentials from ECDSA, hosted as an IACR eprint. The second is the IETF draft named libzk, a C++ library for zero-knowledge proofs, tracked in the datatracker. The third is the project documentation on the project's own site.

Having both a paper and an IETF draft is unusual and useful. The paper is where the cryptographic argument lives, and it is the document to read if you want to know why the construction is sound. The draft is where the API lives, and it is the document to read if you want to call the library. The project documentation is where the practical guidance is.

That ordering matters for anyone assessing the risk. This is not a library where the README is the documentation. The README is a pointer, and the substance is in three documents maintained elsewhere, two of which have a review process around them.

The repository also contains the working files for a specification of Longfellow and its components, in a docs directory, and the readme says that people interested in contributing should create an issue or a pull request, with discussions happening under issues. That is a normal way to run a specification project, and it means the specification is a living artefact rather than a frozen document.

Independent reviews, published

There is a security section, and it is short.

The project has completed several independent security reviews by panels of academic and industry experts in the field, and the reports are available on a reviews page of the project documentation.

Two things are worth noting about that sentence. The first is the word independent, which in this context is the whole point: reviews commissioned and paid for by the implementers are not worthless, but they are not the same as reviews that a panel conducts on its own terms. The second is that the reports are published rather than summarised.

For a cryptographic library, publishing the reviews is the difference between asking people to trust you and letting them check. A reader who is going to use this to prove a claim about a government identity document can read what the reviewers found, whether the concerns were addressed, and what the panel concluded.

This is also the section to read first if you are deciding whether the project is mature enough for your use. The project is at version 0.9, so it is pre-1.0 by version number, and the combination of a pre-1.0 version and published third-party review is not a contradiction: it says the protocol is settled enough to be reviewed, while the library interface is still allowed to move.

The combination of the version number, the security reviews and the published specification is the strongest signal in the repository about how carefully the work is being done.

The build is cmake with a specific dependency set

The build instructions are conventional, and the dependency list tells you what the library leans on.

The package depends on cmake, openssl, zstd, clang, googletest and googlebenchmark. That is a small list, and the two test-related dependencies are the interesting part, because they mean the test suite and the benchmark harness are part of the normal build rather than optional extras.

The per-platform instructions are given for three systems. On Ubuntu and Debian:

$ sudo apt install -y build-essential clang cmake libssl-dev libzstd-dev libgtest-dev libbenchmark-dev zlib1g-dev

On Fedora and Red Hat:

$ yum install -y clang libzstd-devel openssl-devel git cmake google-benchmark-devel gtest-devel

The readme then notes that newer versions of Fedora seem to require an additional package, and gives the variant of the command with it added.

On macOS the requirement is that the Xcode command line tools such as clang and cmake are installed, and the additional packages come from homebrew:

$ brew install googletest google-benchmark zstd

The manual build is two steps. The cmake initialisation pins the compiler and the build type explicitly:

$ CXX=clang++ cmake -D CMAKE_BUILD_TYPE=Release -S lib -B clang-build-release --install-prefix ${PWD}/install

and then the build and the test run:

$ cd clang-build-release && make -j 16 && ctest -j 16

The library source is in a lib directory rather than at the root, which is why the source directory flag points at lib, and the install prefix is set to a directory in your working tree, so a local build never touches a system location.

Benchmarks, and a devcontainer that admits it is slower

The benchmarking section names the categories and gives commands, which tells you how the library is organised internally.

There are unit, sumcheck and zk benchmarks. The examples are an FFT test and a SHA circuit test:

$ ./algebra/fft_test --benchmark_filter='BM_*'

$ ./circuits/sha/flatsha256_circuit_test --benchmark_filter=BM_ShaZK_fp2_128

The directory names are the architecture. There is an algebra directory, which holds the field and curve arithmetic the rest is built on, and a circuits directory with a sha subdirectory, which holds the circuit implementations, including a flat SHA-256 circuit. The sumcheck category is the name of the standard protocol used to prove a computation over a field, so the naming is the technical vocabulary of the field rather than a generic test name.

The devcontainer section is the part with the most honest sentence in the README. You can test the library using the associated devcontainer, by clicking through to create a codespace on master, which creates a Docker container on a GitHub server with all the dependencies and a web based VS Code interface. You can compile and run the benchmarks there, but some of them may be slower than the reported values due to the VM.

That is a small warning, but it is the right one. The project publishes benchmark numbers, and the container that lets you reproduce them is running on shared virtual hardware, so the numbers you get there are not the numbers in the paper. Anyone reproducing the benchmarks should expect to use dedicated hardware to get comparable results, and should be careful about drawing conclusions from a codespace.

A repository that reaches beyond C++

The top level of the tree shows a project that is not only a C++ library, and the extra directories are the most telling part of it.

There is a lib directory for the implementation, a reference directory, a docs directory holding the working specification files, a formal directory, a rust directory, a devcontainer configuration, and two shell scripts at the root, one named android.sh and one named ios.sh.

The rust directory tells you there is a Rust implementation or binding alongside the C++ one, which matters for a project whose natural consumers might be written in either language. The android.sh and ios.sh scripts tell you that the library is meant to be built for mobile platforms, which fits the use case, since the holder of an identity document is usually holding it on a phone.

The formal directory is the other interesting one. In a cryptographic project, a machine checkable specification of the protocol is a strong signal, because it means the implementation can be checked against something more authoritative than a test suite. Whether that formal artefact covers the whole protocol or a part of it is not something the readme says, so the honest statement is that it exists and that its scope is worth checking.

There is also a CODEOWNERS file, a Doxyfile for the API documentation, and a licence file. The Apache 2.0 licence is a permissive one, which is the right choice for a library meant to be embedded in identity systems built by other people, where the cryptographic core needs to be auditable and reusable rather than locked away.

Editorial conclusion

longfellow-zk suits a team that has to prove something about an existing identity document without disclosing the document, and that is prepared to work from a specification and a paper rather than from a tutorial. It is a poor fit if you want a ready-made protocol for your specific credential format, since the library is a set of building blocks described in drafts rather than a finished product, and a poor fit if you cannot run a C++ toolchain with OpenSSL and the test dependencies. Before you build on it, read the security review reports, check which of the three standards your credential actually conforms to, and run the benchmarks in the devcontainer to see the code work before committing to it.

Frequently asked questions

Official sources

1. License: Apache-2.0
2. longfellow-zk/longfellow-zk on GitHub
3. Project website
4. README
5. Releases