blst

blst (pronounced 'blast') is a BLS12-381 signature library focused on performance and security. It is written in C and assembly.

Status
General notes on implementation
Platform and Language Compatibility
API
Introductory Tutorial
Build
- C static library
Language-specific notes
- Go
- Rust
Repository Structure
Performance
License

Status

This library is under active development

An initial audit of this library was conducted by NCC Group in January 2021 and can be found here.

Formal verification of this library by Galois is on-going and can be found here.

This library is compliant with the following IETF draft specifications:

The serialization formatting is implemented according to the ZCash definition.

General notes on implementation

The goal of the blst library is to provide a foundational component for applications and other libraries that require high performance and formally verified BLS12-381 operations. With that in mind some decisions are made to maximize the public good beyond BLS12-381. For example, the field operations are optimized for general 384-bit usage, as opposed to tuned specifically for the 381-bit BLS12-381 curve parameters. With the formal verification of these foundational components, we believe they can provide a reliable building block for other curves that would like high performance and an extra element of security.

The library deliberately abstains from dealing with memory management and multi-threading, with the rationale that these ultimately belong in language-specific bindings. Another responsibility that is left to application is random number generation. All this in the name of run-time neutrality, which makes integration into more stringent environments like Intel SGX or ARM TrustZone trivial.

Platform and Language Compatibility

This library primarily supports x86_64 and ARM64 hardware platforms, and Linux, Mac, and Windows operating systems. But it does have a portable replacement for the assembly modules, which can be compiled for a plethora of other platforms. Problem reports for these will be considered and are likely to be addressed.

This repository includes explicit bindings for:

Go
Rust

Unless deemed appropriate to implement, bindings for other languages will be provided using SWIG. Proof-of-concept scripts are available for:

API

The blst API is defined in the C header bindings/blst.h. The API can be categorized as follows, with some example operations:

Field Operations (add, sub, mul, neg, inv, to/from Montgomery)
Curve Operations (add, double, mul, to/from affine, group check)
Intermediate (hash to curve, pairing, serdes)
BLS12-381 signature (sign, verify, aggregate)

Note: there is also an auxiliary header file, bindings/blst_aux.h, that is used as a staging area for experimental interfaces that may or may not get promoted to blst.h.

Introductory Tutorial

Programming is understanding, and understanding implies mastering the lingo. So we have a pair of additive groups being mapped to multiplicative one... What does it mean? Well, this tutorial is not about explaining that, but rather about making the connection between what you're supposed to know about pairing-based cryptography and the interface provided by the library.

Public Keys and Signatures

We have two elliptic curves, E1 and E2, points on which are contained in blst_p1 and blst_p2, or blst_p1_affine and blst_p2_affine structures. Elements in the multiplicative group are held in a blst_fp12 structure. One of the curves, or more specifically, a subset of points that form a cyclic group, is chosen for public keys, and another, for signatures. The choice is denoted by the subroutines' suffixes, _pk_in_g1 or _pk_in_g2. The most common choice appears to be the former, that is, blst_p1 for public keys, and blst_p2 for signatures. But it all starts with a secret key...

The secret key is held in a 256-bit blst_scalar structure which can be instantiated with either blst_keygen, or deserialized with blst_scalar_from_bendian or blst_scalar_from_lendian from a previously serialized byte sequence. It shouldn't come as surprise that there are two uses for a secret key:

generating the associated public key, either with blst_sk_to_pk_in_g1 or blst_sk_to_pk_in_g2;
performing a sign operation, either with blst_sign_pk_in_g1 or blst_sign_pk_in_g2;

As for signing, unlike what your intuition might suggest, blst_sign_* doesn't sign a message, but rather a point on the corresponding elliptic curve. You can obtain this point from a message by calling blst_hash_to_g2 or blst_encode_to_g2 (see the IETF hash-to-curve draft for distinction). Another counter-intuitive aspect is the apparent g1 vs. g2 naming mismatch, in the sense that blst_sign_pk_in_g1 accepts output from blst_hash_to_g2, and blst_sign_pk_in_g2 accepts output from blst_hash_to_g1. This is because, as you should recall, public keys and signatures come from complementary groups.

Now that you have a public key and signature, as points on corresponding elliptic curves, you can serialize them with blst_p1_serialize/blst_p1_compress and blst_p2_serialize/blst_p2_compress and send the resulting byte sequences over the network for deserialization/uncompression and verification.

Signature Verification

Even though there are "single-shot" blst_core_verify_pk_in_g1 and blst_core_verify_pk_in_g2, you should really familiarize yourself with the more generalized pairing interface. blst_pairing is an opaque structure, and the only thing you know about it is blst_pairing_sizeof, which is how much memory you're supposed to allocate for it. In order to verify an aggregated signature for a set of public keys and messages, or just one[!], you would:

blst_pairing_init(ctx, hash_or_encode, domain_separation_tag);
blst_pairing_aggregate_pk_in_g1(ctx, PK[0], aggregated_signature, message[0]);
blst_pairing_aggregate_pk_in_g1(ctx, PK[1], NULL, message[1]);
...
blst_pairing_commit(ctx);
result = blst_pairing_finalverify(ctx, NULL);

The essential point to note is that it's the caller's responsibility to ensure that public keys are group-checked with blst_p1_affine_in_g1. This is because it's a relatively expensive operation and it's naturally assumed that the application would cache the check's outcome. Signatures are group-checked internally. Not shown in the pseudo-code snippet above, but aggregate and commit calls return BLST_ERROR denoting success or failure in performing the operation. Call to finalverify, on the other hand, returns boolean.

Another, potentially more useful usage pattern is:

blst_p2_affine_in_g2(signature);
blst_aggregated_in_g2(gtsig, signature);
blst_pairing_init(ctx, hash_or_encode, domain_separation_tag);
blst_pairing_aggregate_pk_in_g1(ctx, PK[0], NULL, message[0]);
blst_pairing_aggregate_pk_in_g1(ctx, PK[1], NULL, message[1]);
...
blst_pairing_commit(ctx);
result = blst_pairing_finalverify(ctx, gtsig);

What is useful about it is that aggregated_signature can be handled in a separate thread. And while we are at it, aggregate calls can also be executed in different threads. This naturally implies that each thread will operate on its own blst_pairing context, which will have to be combined with blst_pairing_merge as threads join.

Signature Aggregation

Aggregation is a trivial operation of performing point additions, with blst_p2_add_or_double_affine or blst_p1_add_or_double_affine. Note that the accumulator is a non-affine point.

That's about what you need to know to get started with nitty-gritty of actual function declarations.

Serialization Format

From the ZCash BLS12-381 specification

Fq elements are encoded in big-endian form. They occupy 48 bytes in this form.
Fq2 elements are encoded in big-endian form, meaning that the Fq2 element c0 + c1 * u is represented by the Fq element c1 followed by the Fq element c0. This means Fq2 elements occupy 96 bytes in this form.
The group G1 uses Fq elements for coordinates. The group G2 uses Fq2 elements for coordinates.
G1 and G2 elements can be encoded in uncompressed form (the x-coordinate followed by the y-coordinate) or in com

Blst

Install / Use

README