Crate k256 

RustCrypto: secp256k1 (K-256) elliptic curve

secp256k1 (a.k.a. K-256) elliptic curve library written in pure Rust with support for ECDSA signing/verification/public-key recovery, Taproot Schnorr signatures as defined in BIP340, Elliptic Curve Diffie-Hellman (ECDH), and general-purpose secp256k1 elliptic curve group operations which can be used to implement arbitrary group-based protocols.

Uses traits and base types from the elliptic-curve crate.

Optionally includes a secp256k1 arithmetic feature providing scalar and point types (projective/affine) with support for constant-time scalar multiplication. Additionally, implements traits from the group crate which can be used to generically construct group-based protocols.

Documentation

Security Notes

This crate has been audited by NCC Group, which found a high severity issue in the ECDSA/secp256k1 implementation and another high severity issue in the Schnorr/secp256k1 signature implementation, both of which have since been corrected. We would like to thank Entropy for funding the audit.

This crate has been designed with the goal of ensuring that secret-dependent secp256k1 operations are performed in constant time (using the subtle crate and constant-time formulas). However, it is not suitable for use on processors with a variable-time multiplication operation (e.g. short circuit on multiply-by-zero / multiply-by-one, such as certain 32-bit PowerPC CPUs and some non-ARM microcontrollers).

USE AT YOUR OWN RISK!

Supported Algorithms

• Elliptic Curve Diffie-Hellman (ECDH): gated under the ecdh feature. Note that this is technically ephemeral secp256k1 Diffie-Hellman (a.k.a. ECDHE)
• Elliptic Curve Digital Signature Algorithm (ECDSA): gated under the ecdsa feature. Support for ECDSA/secp256k1 signing and verification, applying low-S normalization (BIP 0062) as used in consensus-critical applications, and additionally supports secp256k1 public-key recovery from ECDSA signatures (as used by e.g. Ethereum)
• Taproot Schnorr signatures (as defined in BIP0340): next-generation signature algorithm based on group operations enabling elegant higher-level constructions like multisignatures.

PKCS#8 Key Encoding

PKCS#8 is a private key format with support for multiple algorithms. It can be encoded as binary DER or text PEM.

You can recognize PEM encoded PKCS#8 private keys because they do not have an algorithm name in the type label, e.g.:

-----BEGIN PRIVATE KEY-----

PKCS#8 support is gated under the pkcs8 feature. The pem feature, which is enabled by default, adds PEM decoding and also enables pkcs8.

The same pattern is used by the other curve crates in this repository which re-export pkcs8.

The following traits can be used to decode/encode secret and public keys as PKCS#8/SPKI. Note that pkcs8 is re-exported from k256 when the pkcs8 feature is enabled:

• pkcs8::DecodePrivateKey: decode private keys from PKCS#8
• pkcs8::EncodePrivateKey: encode private keys to PKCS#8
• pkcs8::DecodePublicKey: decode public keys from SPKI
• pkcs8::EncodePublicKey: encode public keys to SPKI

For private keys, SecretKey::from_der and [SecretKey::from_pem] provide convenience methods which can decode PKCS#8 keys. Use the trait methods above when the input is expected to be specifically PKCS#8.

Example

use k256::SecretKey;

// WARNING: Do not hardcode private keys in your source code. This is for demonstration purposes only.
let pem = r#"-----BEGIN PRIVATE KEY-----
MIGEAgEAMBAGByqGSM49AgEGBSuBBAAKBG0wawIBAQQg5gaqCR3sHPJeQHw2qXBM
45LTkX+ek6P3OYLcSkrwK2KhRANCAATvt+fomKwK3lN/EyTIgA4OzmlGj0xQuU0w
T9scCLkqYa+pYyw+hfpE80apG3HucI2DhwPK8ozPg+TMwQqUmwN6
-----END PRIVATE KEY-----"#;
let secret_key = SecretKey::from_pem(pem)?;

About secp256k1 (K-256)

secp256k1 is a Koblitz curve commonly used in cryptocurrency applications. The “K-256” name follows NIST notation where P = prime fields, B = binary fields, and K = Koblitz curves.

The curve is specified as secp256k1 by Certicom’s SECG in “SEC 2: Recommended Elliptic Curve Domain Parameters”:

https://www.secg.org/sec2-v2.pdf

secp256k1 is primarily notable for usage in Bitcoin and other cryptocurrencies, particularly in conjunction with the Elliptic Curve Digital Signature Algorithm (ECDSA). Owing to its wide deployment in these applications, secp256k1 is one of the most popular and commonly used elliptic curves.

License

All crates licensed under either of

• Apache License, Version 2.0
• MIT license

at your option.

Contribution

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.

serde support

When the serde feature of this crate is enabled, Serialize and Deserialize are impl’d for the following types:

• AffinePoint
• Scalar
• ecdsa::VerifyingKey

Please see type-specific documentation for more information.

Re-exports

pub use elliptic_curve;

pub use elliptic_curve::pkcs8;pkcs8

pub use sha2;sha2

Modules

ecdhecdh

Elliptic Curve Diffie-Hellman (Ephemeral) Support.

ecdsaecdsa-core

Elliptic Curve Digital Signature Algorithm (ECDSA).

schnorrschnorr

Taproot Schnorr signatures as defined in BIP340.

Structs

AffinePointarithmetic

secp256k1 curve point expressed in affine coordinates.

ProjectivePointarithmetic

A point on the secp256k1 curve in projective coordinates.

Scalararithmetic

Scalars are elements in the finite field modulo n.

Secp256k1

secp256k1 (K-256) elliptic curve.

Type Aliases

CompressedPoint

Compressed SEC1-encoded secp256k1 (K-256) curve point.

FieldBytes

secp256k1 (K-256) field element serialized as bytes.

NonZeroScalararithmetic

Non-zero secp256k1 (K-256) scalar field element.

PublicKeyarithmetic

secp256k1 (K-256) public key.

Sec1Point

SEC1-encoded secp256k1 (K-256) curve point.

SecretKey

secp256k1 (K-256) secret key.

U256

256-bit unsigned big integer.

WideBytes

Bytes used by a wide reduction: twice the width of FieldBytes.