ecqv 0.1.0

SEC 4 ECQV implicit certificates on P-256: reconstruct a public key from a certificate and the issuer's key, with no signature to carry
Documentation

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.