1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
//! The unvalidated public key and the hazard that makes it a type.
use crateError;
/// A public key reconstructed from a certificate, before anything has proven
/// the certificate is real.
///
/// Reconstruction always succeeds, even for a forged certificate. The name is
/// the warning: this key is unvalidated, and there is no way to validate it
/// except by using it.
///
/// The only operations that succeed on this type are ones that prove the key
/// works:
///
/// - [`verify_signature`](Self::verify_signature) verifies a signature that the
/// certificate holder claims to have produced. If it returns `Ok`, the
/// certificate was really issued by the CA public key you reconstructed
/// against, and the message is authentic. This is the only operation that
/// proves the certificate locally and immediately.
/// - [`into_public_key_unchecked`](Self::into_public_key_unchecked) hands back
/// the bare key. READ THIS BEFORE CALLING IT: using the key for key agreement
/// (e.g. ECDH) does NOT validate the certificate. A forged certificate
/// yields the wrong point, ECDH against it produces a shared secret the peer
/// does not share, and nothing fails at the ECDH call. Validation is deferred
/// to whatever authenticates the resulting channel, and if nothing does, the
/// certificate is never validated at all.
///
/// The `_unchecked` suffix is deliberate and greppable: an auditor can find
/// every place a bare key is taken out.
///
/// # Example
///
/// ```
/// # #[cfg(feature = "ecdsa")] {
/// # fn main() -> Result<(), Box<dyn std::error::Error>> {
/// use ecqv::{CertificateAuthority, CertificateRequest, UnvalidatedPublicKey};
/// use p256::ecdsa::{Signature, SigningKey, signature::Signer};
/// use rand::rng;
///
/// # let mut rng = rng();
/// # let ca = CertificateAuthority::random(&mut rng);
/// # let ca_public = ca.public_key();
/// # let request = CertificateRequest::random(b"device-7", b"", &mut rng);
/// # let issued = ca.issue_certificate(&request)?;
/// # let holder = request.finalize(&issued.certificate, &issued.private_reconstruction_value, &ca_public)?;
/// # let signing_key = SigningKey::from(&holder);
/// # let message = b"hello, road";
/// # let signature: Signature = signing_key.sign(message);
/// // A certificate arrived over the wire, and we hold the CA public key.
/// // Reconstruction ALWAYS succeeds, even for a forged certificate:
/// let unvalidated: UnvalidatedPublicKey = issued.certificate.reconstruct(&ca_public)?;
///
/// // Nothing has been proven yet. The certificate is validated exactly once,
/// // by using the key it claims: if the holder's signature verifies, the
/// // certificate was really issued by ca_public and the message is authentic.
/// unvalidated.verify_signature(message, &signature)?;
///
/// // For a non-signature use of the bare key (for example ECDH), say so
/// // explicitly. Note: using the key for key agreement does NOT validate the
/// // certificate; a forged certificate yields the wrong point, and the failure
/// // surfaces only when the channel built from the shared secret is checked.
/// let _bare_public_key = unvalidated.into_public_key_unchecked();
/// # Ok(())
/// # }
/// # }
/// ```