secp256kFUN!   ![cratesbadge] ![actionsbadge] ![docs_badge]

A mid-level rust secp256k1 elliptic curve cryptography library that's optimized for fun! Here, fun means:

Fun does not mean (yet -- please help!):

The goal is for this library to let researchers experiment with ideas, have them work on Bitcoin and to enjoy it! I hope you can build very satisfying implementations of cryptographic schemes with this library. High-level libraries like rust-secp256k1 make it difficult to implement exotic cryptographic schemes correctly and efficiently. Low-level libraries like parity/libsecp256k1 make it possible but the resulting code is often error prone and difficult to read.

Use

toml [dependencies] secp256kfun = "0.6"

Should use?

This library is ready for production as long what you are trying to produce is fun and amusement!. If you want to engineer something solid that a lot of people's money will depend on, this library is a very very risky choice. Instead, try to use libsecp256k1 or its rust bindings rust-secp256k1. If you don't need to use secp256k1, instead consider using the wonderful ristretto group from curve25519-dalek whose APIs helped inspire this effort. This library vendors parity/libsecp256k1 into the parity_backend directory to do the elliptic curve arithmetic so most of its performance and side-channel resistance will depend on that.

Documentation

docs.rs/secp256kfun

Features

Here's the distinguishing features of this library.

The Zero Element

Both secp256k1 points and scalars have a notional zero element. Unfortunately, in things surrounding Bitcoin, the zero scalar and zero point are illegal values in most cases. The high-level rust-secp256k1 deals with zero problem by returning a Result in its API whenever the return value might be zero. This causes friction because you have an error case where you should just have zero. At worst, this can lead to a habitual use of .unwrap to ignore the errors that the engineer thinks are unreachable. A mistaken .unwrap is often a security bug if a malicious party can trigger it.

In the low-level parity/libsecp256k1, you have to manually check that things aren't the zero element when it's invalid.

secp256kfun solves these difficulties using marker types. Points and Scalars are marked with Zero or NonZero at compile time (by default, NonZero). So if you declare your function with a NonZero type, passing a Zero type will be a compile time error as shown below:

```rust,compilefail use secp256kfun::{marker::*, Scalar, Point,G,g}; // a randomly selected Scalar will never be zero (statistically unreachable) let x = Scalar::random(&mut rand::threadrng()); dbg!(&x); // Scalar<.., NonZero> // Multiplying a NonZero scalar by G (which is also NonZero) results in a NonZero point let X = g!(x * G); dbg!(&X) // Point<..,NonZero> let Y = g!(-x * G) // An addition can lead to a zero so the result is marked Zero let sum = g!(X + Y); dbg!(&sum); // Point<.., Zero> // Now let's say I naively decide to use this value as my public key... let publickey = sum.mark::(); // BOOM! This is a compile time Error! 🎉 sendpubkeytobob(&public_key);

fn sendpubkeytobob(publickey: &Point) { unimplemented!() } ```

This gives us:

shell error[E0308]: mismatched types --> src/lib.rs:77:20 | 17 | send_pubkey_to_bob(&public_key); | ^^^^^^^^^^^ expected struct `secp256kfun::marker::NonZero`, found struct `secp256kfun::marker::Zero`

To fix this, the library forces you to manually mark the value as NonZero and then deal with the case that it is Zero.

rust,compile_fail match sum.mark::<(Normal, NonZero)>() { Some(public_key) => send_pubkey_to_bob(&public_key), // it was actually NonZero None => .. // deal with the case it is Zero }

Variable time or Constant time?

If a function's execution time is not indepent of its inputs, then information about those inputs may leak to anyone that can measure its execution time. Therefore it is crucial that functions that take secret inputs run in constant time. Good low-level libraries tend to have one constant time version of an algorithm and then a faster variable time version. In high-level libraries the experts have made the choice for you. Here's a question that demonstrates the problem with this: Should a signature verification algorithm run in variable time or constant time?

Well, if you're talking about public signatures on a public blockchain then variable time is fine - it may even be crucial for performance. But what about if you're verifying a blind signature that you just received? The time it takes you to verify the signature may reveal which message you chose to get signed violating the security of the blind signature scheme!

With secp25kfun it's possible to let the caller decide whether a function argument is secret in the context of the protocol with the Secret and Public marker types. In the example below, we have a pedersen_commitment function which is called by the committing party with a secret value and by the verifying party when the secret value is finally revealed. This means that we want it to be constant time when making the commitment but variable time when checking the opening. Note that we only have to write the function once. The compiler will decide whether to use constant time or variable time operations by whether value is marked Secret or Public (note it does this through [specialization]).

```rust use secp256kfun::{marker::*, Point, Scalar, g};

/// commit to a secret value x with publicly known A and B. fn pedersen_commit( A: &Point, // Accept any kind of Point B: &Point, r: &Scalar, // Accept a Secret or Public Scalar x: &Scalar, // Allow commitment to Zero ) -> Point { // Make the commitment g!(r * A + x * B) .mark::<(Normal,NonZero)>() // If the result is zero we could easily compute the discrete // logarithm of B with respect to A. Since this is meant to be unknown // this is computionally unreachable. .expect("computationally unreachable") }

// public setup let A = secp256kfun::G; // use the standard basepoint for one of the points let B = Point::random(&mut rand::thread_rng());

// Alice commits to her secret value x with randomness r let r = Scalar::random(&mut rand::threadrng()); let x = Scalar::from(42); let commitment = pedersencommit(A, &B, &r, &x);

// Imagine Later on, Bob receives the public opening (r,x) for commitment. He // doesn't care about leaking these values via execution time so he marks them // as public. let r = r.mark::(); let x = x.mark::();

// Now he'll compute the commitment in faster variable time and check it // against the original asserteq!(commitment, pedersencommit(A, &B, &r, &x)); ```

As a bonus, this example also shows how you don't have to design the cryptographic function around the basepoint G. The pedersen_commitment takes any PointType. When you pass in G, which is a BasePoint, the compiler will specialize the call so that at runtime it uses the pre-computed multiplication tables that BasePoints have.

Note: At this stage constant-time in this library means hopefully constant time -- there's not testing being done to check this rigorously.

Other Features