CIRCL (Cloudflare Interoperable, Reusable Cryptographic Library)

Security Disclaimer CIRCL is offered as-is without guarantees. It is intended for experimental deployment of Post-Quantum (PQ) and Elliptic Curve Cryptography (ECC) algorithms. Changes to the API and repository are expected. Use caution in production applications.

Constant-Time Caveats Not all packages in CIRCL are constant-time. The following packages contain operations known to leak timing information. Check the doc.go or main source file of these packages for specific details:

• group/
• oprf/
• blindsign/blindrsa/partiallyblindrsa/
• secretsharing/
• tss/rsa/
• zk/dl/
• zk/dleq/
• ecc/p384/

You can install the CIRCL library by fetching it using the Go toolchain:

go get -u github.com/cloudflare/circl

Alternatively, you can examine the Cloudflare Go fork to see how to integrate CIRCL natively in Go projects.

The library provides several make targets for maintaining and verifying the codebase:

• make test: Performs testing of the binary.
• make bench: Runs benchmarks.
• make cover: Produces code coverage.
• make lint: Runs a set of linters on the codebase.

The PartialObliviousServer is used when the evaluation secret should be derived from an auxiliary info byte slice rather than being the static private key. This is useful in specific OPRF modes where the secret is tied to additional context.

Key methods:

• Evaluate(req *EvaluationRequest, info []byte) (*Evaluation, error): Derives an evaluation secret from info and returns evaluations along with a DLEQ proof.
• FullEvaluate(input []byte, info []byte) (output []byte, err error): Performs the full evaluation process using the info slice to derive the secret.
• VerifyFinalize(input []byte, info []byte, expectedOutput []byte) bool: Verifies the finalized hash using the provided info context.

To initiate an Oblivious Pseudorandom Function (OPRF) protocol, use the Blind or DeterministicBlind methods on a Client (or its specialized variants like VerifiableClient or PartialObliviousClient).

• Blind(inputs [][]byte): Generates random blinds for each input and returns the necessary data to proceed with the protocol.
• DeterministicBlind(inputs [][]byte, blinds []Blind): Uses provided blinds for each input, which is useful if you need to reuse the same blinding factors.

Both methods return *FinalizeData (which stores the original inputs and blinds) and an *EvaluationRequest (which contains the blinded elements to be sent to the OPRF server).

A VerifiableServer extends the standard Server functionality by providing a Discrete Logarithm Equality (DLEQ) proof. This allows a client to verify that the server performed the evaluation correctly using the server's public key.

When calling Evaluate, the returned Evaluation object includes a proof field (using the RFC 9497 batch proof format) in addition to the evaluations.

The Server type provides a standard Oblivious Pseudorandom Function (OPRF) implementation. You can use it to process an EvaluationRequest containing multiple Blinded elements. The Evaluate method applies the server's private key to these elements and returns an Evaluation containing the resulting Evaluated elements.

Key methods:

• Evaluate(req *EvaluationRequest) (*Evaluation, error): Performs the OPRF evaluation on the provided elements.
• FullEvaluate(input []byte) (output []byte, err error): A high-level method that hashes the input, performs the evaluation, and returns a finalized hash.
• VerifyFinalize(input []byte, expectedOutput []byte) bool: Verifies that a previously computed output matches the expected value for a given input.

Once the OPRF server returns an Evaluation, use the Finalize method to unblind the results and derive the final pseudorandom outputs.

• Client.Finalize(f *FinalizeData, e *Evaluation): Standard finalization. It validates that the lengths of the blinds, requests, and evaluations match.
• VerifiableClient.Finalize(f *FinalizeData, e *Evaluation): Performs finalization with an additional security step: it verifies a batch Discrete Log Equality (DLEQ) proof using the server's public key (pkS) to ensure the server performed the operation correctly.
• PartialObliviousClient.Finalize(f *FinalizeData, e *Evaluation, info []byte): Performs finalization using an info parameter to tweak the server's key before verification, providing partial obliviousness.

A PartialObliviousClient allows the client to influence the server's key using an info byte slice. This is useful for protocols where the server's key should be tweaked by a client-provided value.

When calling PartialObliviousClient.Finalize(f, e, info), the client:

1. Derives a scalar from info.
2. Computes a tweaked key by adding a generator multiple to the server's public key.
3. Verifies the server's DLEQ proof against this tweaked key.
4. Finalizes the outputs using the info parameter.

A VerifiableClient is used when you require cryptographic proof that the OPRF server correctly applied the secret key to the blinded elements. It includes a pkS *PublicKey field representing the server's public key.

When calling VerifiableClient.Finalize, the client automatically performs a batch DLEQ verification (following RFC 9497) to validate the server's e.Proof against the server's public key and the blinded/evaluated elements. If verification fails, it returns ErrInvalidProof.