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.
§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_stdwithalloc(the encoding layer is the only alloc consumer); verified onwasm32-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 fromDebug.
§Security notes for contributors
- Do not replace the hash-to-scalar truncation with
hash % n. SEC 4 v1.0 section 2.3 specifieseas 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% nover a 256-bit digest is biased and will fail every known-answer vector. - Do not accept a caller-supplied CA nonce outside the
test-vectorsfeature. Reusing or choosing the nonce leaks the CA private key. - Keep
#![forbid(unsafe_code)]and theno_stdguarantee 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.