rust

blst

The blst crate provides a rust interface to the blst BLS12-381 signature library.

Build

bindgen is used to generate FFI bindings to blst.h. Then build.rs invokes C compiler to compile everything into libblst.a within the rust target build area. On Linux it's possible to choose compiler by setting CC environment variable.

Everything can be built and run with the typical cargo commands:

cargo test
cargo bench

If the target application crashes with an "illegal instruction" exception [after copying to an older system], activate portable feature when building blst. Conversely, if you compile on an older Intel system, but will execute the binary on a newer one, consider instead activating force-adx feature. Though keep in mind that cc passes the value of CFLAGS environment variable to the C compiler, and if set to contain specific flags, it can interfere with feature selection. -D__BLST_PORTABLE__ and -D__ADX__ are the said features' equivalents.

To compile for WebAssembly, your clang has to recognize --target=wasm32. Alternatively you can build your project with CC environment variable set to emcc, the Emscripten compiler, and AR set to emar, naturally, with both commands available on your PATH.

While cargo test's dependencies happen to require at least Rust 1.65, the library by itself can be compiled with earlier compiler versions. Though in order to use Rust version prior 1.56 you would need to pinzeroize to "=1.3.0" and zeroize_derive to "=1.3.3" in your project Cargo.toml. Even cc might require pinning to "=1.0.79". And if you find yourself with Rust 1.56 through 1.64 as the only option and want to execute cargo test you'd need to pin some of [dev-dependencies] versions in this project's Cargo.toml by uncommenting following lines and commenting criterion:

byteorder = "=1.4.3"
ppv-lite86 = "=0.2.17"
rmp = "=0.8.12"

[target.'cfg(any(unix, windows))'.dev-dependencies]
#criterion = "0.3"

Usage

There are two primary modes of operation that can be chosen based on declaration path:

For minimal-pubkey-size operations:

use blst::min_pk::*;

For minimal-signature-size operations:

use blst::min_sig::*;

There are five structs with inherent implementations that provide the BLS12-381 signature functionality.

SecretKey
PublicKey
AggregatePublicKey
Signature
AggregateSignature

A simple example for generating a key, signing a message, and verifying the message:

use blst::min_pk::SecretKey;

let mut rng = rand::thread_rng();
let mut ikm = [0u8; 32];
rng.fill_bytes(&mut ikm);

let sk = SecretKey::key_gen(&ikm, &[]).unwrap();
let pk = sk.sk_to_pk();

let dst = b"BLS_SIG_BLS12381G2_XMD:SHA-256_SSWU_RO_NUL_";
let msg = b"blst is such a blast";
let sig = sk.sign(msg, dst, &[]);

let err = sig.verify(true, msg, dst, &[], &pk, true);
assert_eq!(err, blst::BLST_ERROR::BLST_SUCCESS);

See the tests in src/lib.rs and benchmarks in benches/blst_benches.rs for further examples of usage.