# Features
| Feature | Description | Dependencies | Enabled by Default |
|---------|-------------|--------------|:------------------:|
| `secp256k1` | Use [`libsecp256k1`](https://github.com/bitcoin-core/secp256k1) bindings for elliptic curve math. Include trait implementations for converting to and from types in [the `secp256k1` crate][secp256k1]. This feature supercedes the `k256` feature if that one is enabled. | [`secp256k1`] | ✅ |
| `k256` | Use [the `k256` crate][k256] for elliptic curve math. This enables a pure-rust build. Include trait implementations for types from `k256`. If the `secp256k1` feature is enabled, then `k256` will still be brought in and trait implementations will be included, but the actual curve math will be done by `libsecp256k1`. | [`k256`] | ❌ |
| `serde` | Implement serialization and deserialization for types in this crate. | [`serde`](https://docs.rs/serde) | ❌ |
| `rand` | Enable support for random scalar sampling with a CSPRNG, via [the `rand` crate](https://crates.io/crates/rand) | [`rand`] | ❌ |
| `secp256k1-invert` | `libsecp256k1` doesn't expose any functionality to invert scalars modulo the curve order (i.e. to compute t<sup>-1</sup> for some scalar t, so that t(t<sup>-1</sup>) = 1 mod n). Inversion is useful for certain cryptographic operations, such as ECDSA signing, or OPRFs. <br> <br> Enable this feature if you need to invert scalars but you only have the `secp256k1` feature enabled. This feature is only useful if the `secp256k1` feature is enabled but `k256` is not, as the [`k256`] crate provides scalar inversion methods. This feature pulls in [the `crypto-bigint` crate][crypto_bigint] to perform the inversion. | [`crypto_bigint`] | ❌ |
| `num-traits` | Enable support for numeric identity traits via [the `num-traits` crate](https://crates.io/crates/num-traits). | [`num_traits`] | ❌ |
| `cli-rng` | Enable RNG features needed to compile the `secp` CLI program. **Not for public use.** | [`rand`] | ❌ |
# Usage
The `secp` crate's primary export is four types which can be used to represent elliptic curve points (e.g. public keys) and scalars (e.g. private keys).
- [`Scalar`] for non-zero scalar values.
- [`Point`] for non-infinity curve points
- [`MaybeScalar`] for possibly-zero scalars.
- [`MaybePoint`] for possibly-infinity curve points.
Depending on which features of this crate are enabled, we implement various conversion traits between these types and higher-level types such as [`secp256k1::PublicKey`] or [`k256::SecretKey`].
```rust
# #[cfg(all(feature = "secp256k1", feature = "rand"))]
# {
let seckey = secp256k1::SecretKey::new(&mut rand::rngs::OsRng);
let scalar = secp::Scalar::from(seckey);
secp256k1::SecretKey::from(scalar);
secp256k1::Scalar::from(scalar);
let point: secp::Point = scalar.base_point_mul();
secp256k1::PublicKey::from(point);
# }
# #[cfg(feature = "k256")]
# {
let seckey = k256::SecretKey::random(&mut rand::rngs::OsRng);
let scalar = secp::Scalar::from(seckey);
k256::SecretKey::from(scalar);
k256::Scalar::from(scalar);
k256::NonZeroScalar::from(scalar);
k256::Scalar::from(secp::MaybeScalar::Valid(scalar));
assert!(k256::NonZeroScalar::try_from(secp::MaybeScalar::Valid(scalar)).is_ok());
assert!(k256::NonZeroScalar::try_from(secp::MaybeScalar::Zero).is_err());
let point: secp::Point = scalar.base_point_mul();
k256::PublicKey::from(point);
k256::AffinePoint::from(point);
# }
```
# Scalars
A [`Scalar`] can represent any integers in the range `[1, n)`, while a [`MaybeScalar`] represents any integer in the range `[0, n)`, where `n` is the secp256k1 elliptic curve order (the number of possible points on the curve). As [`Scalar`] is never zero it doesn't implement [`Default`]). [`MaybeScalar::Zero`] represents the integer zero.
```rust
# use secp::Scalar;
pub enum MaybeScalar {
Zero,
Valid(Scalar),
}
```
## Arithmetic
Addition, subtract, and multiplication operators are supported by default between the two scalar types. All operations are done in the finite field modulo `n`.
```rust
use secp::{MaybeScalar, Scalar};
assert_eq!(
(Scalar::one() + Scalar::two()) * Scalar::max(),
Scalar::max() - Scalar::two()
);
// Addition or subtraction of two non-zero [`Scalar`] instances will
// output a [`MaybeScalar`], since the sum of two non-zero numbers
// could be zero in a finite field.
assert_eq!(Scalar::one() + Scalar::one(), MaybeScalar::two());
// Arithmetic works across commutatively both scalar types.
assert_eq!(
MaybeScalar::from(20) * Scalar::two() - Scalar::try_from(10).unwrap(),
MaybeScalar::from(30)
);
// Zero acts like zero.
assert_eq!(MaybeScalar::Zero + Scalar::two(), MaybeScalar::two());
assert_eq!(MaybeScalar::Zero * Scalar::two(), MaybeScalar::Zero);
```
Division is supported via [modular multiplicative inversion](https://en.wikipedia.org/wiki/Modular_multiplicative_inverse). Since libsecp256k1 does not support this out of the box, scalar inversion requires either the `k256` feature or the `secp256k1-invert` feature to be enabled.
```rust
# #[cfg(any(feature = "k256", feature = "secp256k1-invert"))]
# {
# use secp::Scalar;
let x = "0000000000000000000000000000000000000000000000000000000000000aae"
.parse::<Scalar>()
.unwrap();
assert_eq!(
x / Scalar::two(),
"0000000000000000000000000000000000000000000000000000000000000557"
.parse()
.unwrap()
);
// Since `0xAAF` is an odd number, this would be a fraction if we were
// operating in the real numbers. Since we're operating in a finite field,
// there does exist an integer solution to the equation `x * 2 = 0xAAF`
assert_eq!(
(x + Scalar::one()) / Scalar::two(),
"7fffffffffffffffffffffffffffffff5d576e7357a4501ddfe92f46681b25f8"
.parse()
.unwrap()
);
# }
```
Division by a `MaybeScalar` is not defined, since the divisor might be zero.
```compile_fail
# use secp::{MaybeScalar, Scalar};
Scalar::two() / MaybeScalar::two();
```
## Formatting
To reduce the risk of accidental exposure of private keys, signatures, or other secret scalar values, `Scalar` does not implement [`Display`][std::fmt::Display].
```compile_fail
println!("{}", Scalar::max());
```
Instead, `Scalar`s can be formatted as hex strings explicitly by using `{:x}` or `{:X}` format directives, via the [`LowerHex`][std::fmt::LowerHex] or [`UpperHex`][std::fmt::UpperHex] trait implementations on `Scalar`. Conversion to hex is done in constant-time, but we can't make any guarantees about side-channel leakage beyond that point.
```rust
# use secp::{MaybeScalar, Scalar};
let hex = "e2df7e885217c19c42a8159fd02633f0dc463fadfafc09a71af20bfa2b9036c6";
let scalar = hex.parse::<Scalar>().unwrap();
assert_eq!(format!("{:x}", scalar), hex);
assert_eq!(format!("{:X}", scalar), hex.to_uppercase());
assert_eq!(format!("{:x}", MaybeScalar::Valid(scalar)), hex);
assert_eq!(format!("{:X}", MaybeScalar::Valid(scalar)), hex.to_uppercase());
assert_eq!(
format!("{:x}", MaybeScalar::Zero),
"0000000000000000000000000000000000000000000000000000000000000000"
);
```
# Points
Valid elliptic curve points are represented by the [`Point`] type. There is a special curve point called _infinity,_ or the _identity point,_ or the _zero point,_ which we represent as [`MaybePoint::Infinity`].
```rust
# use secp::Point;
pub enum MaybePoint {
Infinity,
Valid(Point),
}
```
## Arithmetic
Points can be added and subtracted from one-another.
```rust
use secp::{MaybePoint, Point};
let P1 = "02b435092055e2dc9a1474dac777302c172dde0a40323f0879bff48d002575b685"
.parse::<Point>()
.unwrap();
let P2 = "0375663d8ea90563709204f1b1ff4822220cfb257ed5602609282314ba4e7d492c"
.parse::<Point>()
.unwrap();
let P3 = "02bc0b73e8233f4fbaa30bcfa540f76d517d385383dd8c9a13ba6dad097f8ea9db"
.parse::<Point>()
.unwrap();
// Similar to `Scalar`, adding and subtracting non-infinity points
// results in a `MaybePoint`, because point addition is cyclic just
// like scalar addition.
assert_eq!(P1 + P2, MaybePoint::Valid(P3));
assert_eq!(P3 - P2, MaybePoint::Valid(P1));
// Iterators of points can be summed like any other number-like type.
// Prefer this over manually implementing a summation reducer, as
// we offload most of the work to libsecp256k1.
assert_eq!(
[P1, P2].into_iter().sum::<MaybePoint>(),
MaybePoint::Valid(P3)
);
```
And of course, the most important operation in elliptic curve cryptography, **scalar-point multiplication** is also supported.
```rust
use secp::{MaybePoint, Point, Scalar};
let P = "02b435092055e2dc9a1474dac777302c172dde0a40323f0879bff48d002575b685"
.parse::<Point>()
.unwrap();
let d = Scalar::try_from(3).unwrap();
// Multiplying by one is a no-op.
assert_eq!(P * Scalar::one(), P);
// Multiplying by a non-zero scalar guarantees a non-zero
// point is the output.
assert_eq!(
P * d,
(P + P + P).unwrap()
);
// Multiplying by the secp256k1 base point `G` is easy.
assert_eq!(
d.base_point_mul(),
d * Point::generator()
);
// We provide a static shortcut to the generator point `G`
// which works with arithemtic operators.
use secp::G;
assert_eq!(
G * d,
(G + G + G).unwrap()
);
assert_eq!(G - G, MaybePoint::Infinity);
// Point-scalar division works if scalar inversion is enabled
// by the feature set.
# #[cfg(any(feature = "k256", feature = "secp256k1-invert"))]
assert_eq!(d * G / d, (*G));
```
## Formatting
Like the scalars, [`Point`] and [`MaybePoint`] can be formatted compressed form as hex strings explicitly using `{:x}` and `{:X}` directives. They also implement [`Display`][std::fmt::Display]. The default displayable string value of [`Point`] and [`MaybePoint`] is the compressed lower-case hex encoding. Uncompressed keys can be formatted by adding the `+` flag to the directive, i.e. by formatting as `{:+}` or `{:+x}`.
```rust
# use secp::{MaybePoint, Point};
// Compressed
let point_hex = "02bc0b73e8233f4fbaa30bcfa540f76d517d385383dd8c9a13ba6dad097f8ea9db";
let point: Point = point_hex.parse().unwrap();
assert_eq!(point.to_string(), point_hex);
assert_eq!(format!("{}", point), point_hex);
assert_eq!(format!("{:x}", point), point_hex);
assert_eq!(format!("{:X}", point), point_hex.to_uppercase());
assert_eq!(format!("{:x}", MaybePoint::Valid(point)), point_hex);
assert_eq!(format!("{:X}", MaybePoint::Valid(point)), point_hex.to_uppercase());
assert_eq!(
format!("{:x}", MaybePoint::Infinity),
"000000000000000000000000000000000000000000000000000000000000000000"
);
// Uncompressed
let point_hex_uncompressed =
"04bc0b73e8233f4fbaa30bcfa540f76d517d385383dd8c9a13ba6dad097f8ea9db\
6c11d8da7d251e5756c297147a40767bd21d3cd18a830bf79dd4d17ba26fc546";
let point: Point = point_hex_uncompressed.parse().unwrap();
assert_eq!(format!("{:+}", point), point_hex_uncompressed);
assert_eq!(format!("{:+x}", point), point_hex_uncompressed);
assert_eq!(format!("{:+X}", point), point_hex_uncompressed.to_uppercase());
assert_eq!(format!("{:+x}", MaybePoint::Valid(point)), point_hex_uncompressed);
assert_eq!(format!("{:+X}", MaybePoint::Valid(point)), point_hex_uncompressed.to_uppercase());
assert_eq!(
format!("{:+x}", MaybePoint::Infinity),
"000000000000000000000000000000000000000000000000000000000000000000\
0000000000000000000000000000000000000000000000000000000000000000"
);
```