Skip to main content

Crate sm2

Crate sm2 

Source
Expand description

§RustCrypto: SM2 elliptic curve

crate Docs Build Status Apache2/MIT licensed Rust Version Project Chat

Pure Rust implementation of the SM2 elliptic curve as defined in the Chinese national standard GM/T 0003-2012 as well as ISO/IEC 14888.

Documentation

§⚠️ Security Warning

The elliptic curve arithmetic contained in this crate has never been independently audited!

This crate has been designed with the goal of ensuring that secret-dependent operations are performed in constant time (using the subtle crate and constant-time formulas). However, it has not been thoroughly assessed to ensure that generated assembly is constant time on common CPU architectures.

USE AT YOUR OWN RISK!

§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 sm2 when the pkcs8 feature is enabled:

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 sm2::SecretKey;

// WARNING: Do not hardcode private keys in your source code. This is for demonstration purposes only.
let pem = r#"-----BEGIN PRIVATE KEY-----
MIGHAgEAMBMGByqGSM49AgEGCCqBHM9VAYItBG0wawIBAQQgCuPaZjuHC6ATf0yg
7QyjemLm1tjhI4n2N7FMrkAErjChRANCAASw6c/Y5GhbSCoUCrcQZztNCe0ri+Jd
Uo3tPoXlB4jHtdZgdBuMw6+OMkH3DdAEcyUkwufqJxqfK3DN2ZVuklWx
-----END PRIVATE KEY-----"#;
let secret_key = SecretKey::from_pem(pem)?;

§About SM2

ShangMi 2 (SM2) is a Weierstrass curve specified in GM/T 0003-2012: Cryptography Industry Standard of the People’s Republic of China.

The SM2 cryptosystem is composed of three distinct algorithms:

§License

All crates licensed under either of

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.

§Backends

This crate has support for two different field arithmetic backends which can be selected using cfg(sm2_backend), e.g. to select the bigint backend:

$ RUSTFLAGS='--cfg sm2_backend="bigint"' cargo test

Or it can be set through .cargo/config:

[build]
rustflags = ['--cfg', 'sm2_backend="bigint"']

The available backends are:

  • bigint: experimental backend provided by crypto-bigint. May offer better performance in some cases along with smaller code size, but might also have bugs.
  • fiat (default): formally verified implementation synthesized by fiat-crypto which should be correct for all inputs (though there’s a possibility of bugs in the code which glues to it)

Re-exports§

pub use self;
pub use elliptic_curve::pkcs8;pkcs8

Modules§

dsadsa
SM2 Digital Signature Algorithm (SM2DSA) as defined in draft-shen-sm2-ecdsa § 5.
pkepke
SM2 Encryption Algorithm (SM2) as defined in [draft-shen-sm2-ecdsa § 5].

Structs§

Scalararithmetic
Element in the SM2 scalar field modulo n.
Sm2
SM2 elliptic curve.

Type Aliases§

AffinePointarithmetic
Elliptic curve point in affine coordinates.
CompressedPoint
Compressed SEC1-encoded curve point.
FieldBytes
SM2 field element serialized as bytes.
FieldBytesSize
Size of a SM2 field element serialized as bytes.
NonZeroScalararithmetic
Non-zero scalar field element.
ProjectivePointarithmetic
Elliptic curve point in projective coordinates.
PublicKeyarithmetic
SM2 public key: wrapper type for an elliptic curve point.
Sec1Point
SEC1 encoded point.
SecretKey
SM2 secret key: wrapper point for a secret scalar.
U256
256-bit unsigned big integer.
UncompressedPoint
Uncompressed SEC1-encoded curve point.