Skip to main content

Crate ecqv

Crate ecqv 

Source
Expand description

The crate documentation is the README, so that the front page on crates.io, docs.rs, and the repository are the same single source of truth (and so the README’s Usage example compiles and runs as a doctest).

§ecqv

SEC 4 Elliptic Curve Qu-Vanstone (ECQV) implicit certificates on P-256, built on the RustCrypto p256 and elliptic-curve crates.

ECQV certificates are small: a certificate binds identity to a public key without carrying the key or a signature, so the holder’s public key can be reconstructed from the certificate plus the issuer’s public key. This is the scheme deployed in IEEE 1609.2 (V2X) and ZigBee Smart Energy.

Status: maintained.

CI

§Validation status, read this first

  • Implements SEC 4 ECQV. The protocol core (point arithmetic, scalar algebra, hash-to-scalar) is validated against the CAMP LLC / SCMS known-answer test vectors (conz27/crypto-test-vectors), which cover all three roles separately on P-256: the CA side (certificate generation), the requester side (private key reconstruction), and any-party public key reconstruction. Every output in those vectors was independently re-derived from the raw inputs with separate P-256 arithmetic before being accepted into this repository, so the vectors are known to be correct rather than merely self-consistent with someone else’s code.
  • SEC 4 v1.0 itself publishes no test vectors. There is no SECG-issued golden set to validate against. The IEEE 1609.2 / ETSI TS 103 096 test suites carry real deployed-format certificates, but they are whole-certificate COER encodings with a different hashing structure (H(H(ToBeSigned) || H(issuer))) and cannot isolate the individual ECQV roles; using them requires a full 1609.2 certificate layer, which is out of scope here.
  • NOT independently audited. The scheme and the dependencies have not received an independent security review.
  • Implicit validation means a reconstructed public key is meaningless until successfully used. There is no verification step in ECQV. Reconstruction always succeeds; a forged certificate simply yields a useless key. See the section below.

§The implicit-validation hazard

In ECQV the “certificate is bad” signal is not an error at reconstruction time. A certificate signed by the wrong CA, or altered in transit, still produces a public key, just one that will not verify any signature or complete any key agreement that a valid certificate would. This is the defining property of the scheme, and it is the property most callers miss.

This library encodes that hazard in the API: public key reconstruction returns an UnvalidatedPublicKey, and the only operations that succeed on it are ones that prove the key actually works (verifying a signature the holder produced). The key is never handed back as a bare, trusted public key. Do not bypass this unless you understand exactly why you are doing so; the escaping operation is named into_public_key_unchecked, and using it for key agreement does NOT validate the certificate, it defers validation to whatever later authenticates the resulting channel.

§Usage

Three roles, one flow:

use ecqv::{CertificateAuthority, CertificateRequest};
use p256::ecdsa::{Signature, SigningKey, signature::Signer};
use rand::rng;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let mut rng = rng();

    // The CA, once. Every requester and relying party must hold its public key.
    let ca = CertificateAuthority::random(&mut rng);
    let ca_public = ca.public_key();

    // The requester asks for a certificate, keeping the request secret.
    let request = CertificateRequest::random(b"device-42", b"firmware=2.1", &mut rng);

    // The CA issues. No RNG involved: the per-certificate nonce is derived
    // deterministically, so d_CA cannot leak through nonce reuse.
    let issued = ca.issue_certificate(&request)?;

    // The requester finalizes. Consumes the request (k_U used exactly once)
    // and runs the SEC 4 3.6 self-check before returning a signing key.
    let secret_key = request.finalize(
        &issued.certificate,
        &issued.private_reconstruction_value,
        &ca_public,
    )?;
    let signing_key = SigningKey::from(&secret_key);

    // Any party, later: reconstruction ALWAYS succeeds, even for a forged
    // certificate. Nothing is proven until the key is used, which is what
    // verify_signature does; it is the only operation that validates the
    // certificate.
    let unvalidated = issued.certificate.reconstruct(&ca_public)?;
    let message = b"hello, road";
    let signature: Signature = signing_key.sign(message);
    unvalidated.verify_signature(message, &signature)?;

    Ok(())
}

§What this crate is not

This is a SEC 4 protocol implementation. It is NOT an IEEE 1609.2 (V2X) or ZigBee Smart Energy certificate implementation: those systems use their own certificate encodings and hashing structure over the same scheme. If you arrived here from V2X, that is the boundary to notice first.

§Scope

  • P-256 only (secp256r1). No generic-over-curve implementation; that is a deliberate scope decision, not a missing feature.
  • The protocol core takes the certificate as opaque bytes. The certificate encoding is a separate, pluggable layer with explicit length prefixes on every variable-length field, so no two distinct certificates can serialize to the same bytes (see the encoding tests).
  • Deterministic CA nonce generation (RFC 6979 style) to make nonce reuse impossible without a software bug. The CA’s issuing API never accepts a caller-supplied nonce; known-answer testing uses a feature-gated injection point (test-vectors) that a production dependency graph cannot reach.
  • no_std with alloc (the encoding layer is the only alloc consumer); verified on wasm32-unknown-unknown. #![forbid(unsafe_code)]: there is no unsafe code in this crate.
  • Secret material (d_CA, k_U, r, the derived private key) is zeroized on drop and redacted from Debug.

§Security notes for contributors

  • Do not replace the hash-to-scalar truncation with hash % n. SEC 4 v1.0 section 2.3 specifies e as the leftmost floor(log2 n) bits of the digest (for P-256 with SHA-256, the leftmost 255 bits, i.e. the digest shifted right by one). Because 2^255 < n this lands in [0, n) with no wraparound and therefore no modular bias. A naive % n over a 256-bit digest is biased and will fail every known-answer vector.
  • Do not accept a caller-supplied CA nonce outside the test-vectors feature. Reusing or choosing the nonce leaks the CA private key.
  • Keep #![forbid(unsafe_code)] and the no_std guarantee intact.

See CONTRIBUTING.md for the file layout and how to run the tests.

Re-exports§

pub use ca::CertificateAuthority;
pub use certificate::Certificate;
pub use certificate::CertificateIssue;
pub use certificate::PrivateReconstructionValue;
pub use error::Error;
pub use request::CertificateRequest;
pub use unvalidated::UnvalidatedPublicKey;

Modules§

ca
The certificate authority: the long-lived issuing key.
certificate
The certificate, its transport types, and the private key reconstruction value.
encoding
Certificate encoding layer.
error
Errors, phrased so that a caller can fix the problem from the message alone.
hash
SEC 4 v1.0 section 2.3: hashing octet strings to integers modulo n (Hn).
protocol
ECQV protocol operations.
request
The requester side: generating a certificate request and finalizing the response.
unvalidated
The unvalidated public key and the hazard that makes it a type.
vectors
Known-answer test vectors for the ECQV protocol core.