1 use crate::error::TLSError;
2 use crate::key;
3 use crate::msgs::enums::{SignatureAlgorithm, SignatureScheme};
4
5 use ring::{
6 self,
7 signature::{self, EcdsaKeyPair, Ed25519KeyPair, RsaKeyPair},
8 };
9 use webpki;
10
11 use std::mem;
12 use std::sync::Arc;
13
14 /// An abstract signing key.
15 pub trait SigningKey: Send + Sync {
16 /// Choose a `SignatureScheme` from those offered.
17 ///
18 /// Expresses the choice by returning something that implements `Signer`,
19 /// using the chosen scheme.
choose_scheme(&self, offered: &[SignatureScheme]) -> Option<Box<dyn Signer>>20 fn choose_scheme(&self, offered: &[SignatureScheme]) -> Option<Box<dyn Signer>>;
21
22 /// What kind of key we have.
algorithm(&self) -> SignatureAlgorithm23 fn algorithm(&self) -> SignatureAlgorithm;
24 }
25
26 /// A thing that can sign a message.
27 pub trait Signer: Send + Sync {
28 /// Signs `message` using the selected scheme.
sign(&self, message: &[u8]) -> Result<Vec<u8>, TLSError>29 fn sign(&self, message: &[u8]) -> Result<Vec<u8>, TLSError>;
30
31 /// Reveals which scheme will be used when you call `sign()`.
get_scheme(&self) -> SignatureScheme32 fn get_scheme(&self) -> SignatureScheme;
33 }
34
35 /// A packaged-together certificate chain, matching `SigningKey` and
36 /// optional stapled OCSP response and/or SCT list.
37 #[derive(Clone)]
38 pub struct CertifiedKey {
39 /// The certificate chain.
40 pub cert: Vec<key::Certificate>,
41
42 /// The certified key.
43 pub key: Arc<Box<dyn SigningKey>>,
44
45 /// An optional OCSP response from the certificate issuer,
46 /// attesting to its continued validity.
47 pub ocsp: Option<Vec<u8>>,
48
49 /// An optional collection of SCTs from CT logs, proving the
50 /// certificate is included on those logs. This must be
51 /// a `SignedCertificateTimestampList` encoding; see RFC6962.
52 pub sct_list: Option<Vec<u8>>,
53 }
54
55 impl CertifiedKey {
56 /// Make a new CertifiedKey, with the given chain and key.
57 ///
58 /// The cert chain must not be empty. The first certificate in the chain
59 /// must be the end-entity certificate.
new(cert: Vec<key::Certificate>, key: Arc<Box<dyn SigningKey>>) -> CertifiedKey60 pub fn new(cert: Vec<key::Certificate>, key: Arc<Box<dyn SigningKey>>) -> CertifiedKey {
61 CertifiedKey {
62 cert,
63 key,
64 ocsp: None,
65 sct_list: None,
66 }
67 }
68
69 /// The end-entity certificate.
end_entity_cert(&self) -> Result<&key::Certificate, ()>70 pub fn end_entity_cert(&self) -> Result<&key::Certificate, ()> {
71 self.cert.get(0).ok_or(())
72 }
73
74 /// Steal ownership of the certificate chain.
take_cert(&mut self) -> Vec<key::Certificate>75 pub fn take_cert(&mut self) -> Vec<key::Certificate> {
76 mem::replace(&mut self.cert, Vec::new())
77 }
78
79 /// Return true if there's an OCSP response.
has_ocsp(&self) -> bool80 pub fn has_ocsp(&self) -> bool {
81 self.ocsp.is_some()
82 }
83
84 /// Steal ownership of the OCSP response.
take_ocsp(&mut self) -> Option<Vec<u8>>85 pub fn take_ocsp(&mut self) -> Option<Vec<u8>> {
86 mem::replace(&mut self.ocsp, None)
87 }
88
89 /// Return true if there's an SCT list.
has_sct_list(&self) -> bool90 pub fn has_sct_list(&self) -> bool {
91 self.sct_list.is_some()
92 }
93
94 /// Steal ownership of the SCT list.
take_sct_list(&mut self) -> Option<Vec<u8>>95 pub fn take_sct_list(&mut self) -> Option<Vec<u8>> {
96 mem::replace(&mut self.sct_list, None)
97 }
98
99 /// Check the certificate chain for validity:
100 /// - it should be non-empty list
101 /// - the first certificate should be parsable as a x509v3,
102 /// - the first certificate should quote the given server name
103 /// (if provided)
104 ///
105 /// These checks are not security-sensitive. They are the
106 /// *server* attempting to detect accidental misconfiguration.
cross_check_end_entity_cert( &self, name: Option<webpki::DNSNameRef>, ) -> Result<(), TLSError>107 pub fn cross_check_end_entity_cert(
108 &self,
109 name: Option<webpki::DNSNameRef>,
110 ) -> Result<(), TLSError> {
111 // Always reject an empty certificate chain.
112 let end_entity_cert = self.end_entity_cert().map_err(|()| {
113 TLSError::General("No end-entity certificate in certificate chain".to_string())
114 })?;
115
116 // Reject syntactically-invalid end-entity certificates.
117 let end_entity_cert =
118 webpki::EndEntityCert::from(end_entity_cert.as_ref()).map_err(|_| {
119 TLSError::General(
120 "End-entity certificate in certificate \
121 chain is syntactically invalid"
122 .to_string(),
123 )
124 })?;
125
126 if let Some(name) = name {
127 // If SNI was offered then the certificate must be valid for
128 // that hostname. Note that this doesn't fully validate that the
129 // certificate is valid; it only validates that the name is one
130 // that the certificate is valid for, if the certificate is
131 // valid.
132 if end_entity_cert
133 .verify_is_valid_for_dns_name(name)
134 .is_err()
135 {
136 return Err(TLSError::General(
137 "The server certificate is not \
138 valid for the given name"
139 .to_string(),
140 ));
141 }
142 }
143
144 Ok(())
145 }
146 }
147
148 /// Parse `der` as any supported key encoding/type, returning
149 /// the first which works.
any_supported_type(der: &key::PrivateKey) -> Result<Box<dyn SigningKey>, ()>150 pub fn any_supported_type(der: &key::PrivateKey) -> Result<Box<dyn SigningKey>, ()> {
151 if let Ok(rsa) = RSASigningKey::new(der) {
152 Ok(Box::new(rsa))
153 } else if let Ok(ecdsa) = any_ecdsa_type(der) {
154 Ok(ecdsa)
155 } else {
156 any_eddsa_type(der)
157 }
158 }
159
160 /// Parse `der` as any ECDSA key type, returning the first which works.
any_ecdsa_type(der: &key::PrivateKey) -> Result<Box<dyn SigningKey>, ()>161 pub fn any_ecdsa_type(der: &key::PrivateKey) -> Result<Box<dyn SigningKey>, ()> {
162 if let Ok(ecdsa_p256) = ECDSASigningKey::new(
163 der,
164 SignatureScheme::ECDSA_NISTP256_SHA256,
165 &signature::ECDSA_P256_SHA256_ASN1_SIGNING,
166 ) {
167 return Ok(Box::new(ecdsa_p256));
168 }
169
170 if let Ok(ecdsa_p384) = ECDSASigningKey::new(
171 der,
172 SignatureScheme::ECDSA_NISTP384_SHA384,
173 &signature::ECDSA_P384_SHA384_ASN1_SIGNING,
174 ) {
175 return Ok(Box::new(ecdsa_p384));
176 }
177
178 Err(())
179 }
180
181 /// Parse `der` as any EdDSA key type, returning the first which works.
any_eddsa_type(der: &key::PrivateKey) -> Result<Box<dyn SigningKey>, ()>182 pub fn any_eddsa_type(der: &key::PrivateKey) -> Result<Box<dyn SigningKey>, ()> {
183 if let Ok(ed25519) = Ed25519SigningKey::new(der, SignatureScheme::ED25519) {
184 return Ok(Box::new(ed25519));
185 }
186
187 // TODO: Add support for Ed448
188
189 Err(())
190 }
191
192 /// A `SigningKey` for RSA-PKCS1 or RSA-PSS
193 pub struct RSASigningKey {
194 key: Arc<RsaKeyPair>,
195 }
196
197 static ALL_RSA_SCHEMES: &[SignatureScheme] = &[
198 SignatureScheme::RSA_PSS_SHA512,
199 SignatureScheme::RSA_PSS_SHA384,
200 SignatureScheme::RSA_PSS_SHA256,
201 SignatureScheme::RSA_PKCS1_SHA512,
202 SignatureScheme::RSA_PKCS1_SHA384,
203 SignatureScheme::RSA_PKCS1_SHA256,
204 ];
205
206 impl RSASigningKey {
207 /// Make a new `RSASigningKey` from a DER encoding, in either
208 /// PKCS#1 or PKCS#8 format.
new(der: &key::PrivateKey) -> Result<RSASigningKey, ()>209 pub fn new(der: &key::PrivateKey) -> Result<RSASigningKey, ()> {
210 RsaKeyPair::from_der(&der.0)
211 .or_else(|_| RsaKeyPair::from_pkcs8(&der.0))
212 .map(|s| RSASigningKey { key: Arc::new(s) })
213 .map_err(|_| ())
214 }
215 }
216
217 impl SigningKey for RSASigningKey {
choose_scheme(&self, offered: &[SignatureScheme]) -> Option<Box<dyn Signer>>218 fn choose_scheme(&self, offered: &[SignatureScheme]) -> Option<Box<dyn Signer>> {
219 ALL_RSA_SCHEMES
220 .iter()
221 .filter(|scheme| offered.contains(scheme))
222 .nth(0)
223 .map(|scheme| RSASigner::new(self.key.clone(), *scheme))
224 }
225
algorithm(&self) -> SignatureAlgorithm226 fn algorithm(&self) -> SignatureAlgorithm {
227 SignatureAlgorithm::RSA
228 }
229 }
230
231 struct RSASigner {
232 key: Arc<RsaKeyPair>,
233 scheme: SignatureScheme,
234 encoding: &'static dyn signature::RsaEncoding,
235 }
236
237 impl RSASigner {
new(key: Arc<RsaKeyPair>, scheme: SignatureScheme) -> Box<dyn Signer>238 fn new(key: Arc<RsaKeyPair>, scheme: SignatureScheme) -> Box<dyn Signer> {
239 let encoding: &dyn signature::RsaEncoding = match scheme {
240 SignatureScheme::RSA_PKCS1_SHA256 => &signature::RSA_PKCS1_SHA256,
241 SignatureScheme::RSA_PKCS1_SHA384 => &signature::RSA_PKCS1_SHA384,
242 SignatureScheme::RSA_PKCS1_SHA512 => &signature::RSA_PKCS1_SHA512,
243 SignatureScheme::RSA_PSS_SHA256 => &signature::RSA_PSS_SHA256,
244 SignatureScheme::RSA_PSS_SHA384 => &signature::RSA_PSS_SHA384,
245 SignatureScheme::RSA_PSS_SHA512 => &signature::RSA_PSS_SHA512,
246 _ => unreachable!(),
247 };
248
249 Box::new(RSASigner {
250 key,
251 scheme,
252 encoding,
253 })
254 }
255 }
256
257 impl Signer for RSASigner {
sign(&self, message: &[u8]) -> Result<Vec<u8>, TLSError>258 fn sign(&self, message: &[u8]) -> Result<Vec<u8>, TLSError> {
259 let mut sig = vec![0; self.key.public_modulus_len()];
260
261 let rng = ring::rand::SystemRandom::new();
262 self.key
263 .sign(self.encoding, &rng, message, &mut sig)
264 .map(|_| sig)
265 .map_err(|_| TLSError::General("signing failed".to_string()))
266 }
267
get_scheme(&self) -> SignatureScheme268 fn get_scheme(&self) -> SignatureScheme {
269 self.scheme
270 }
271 }
272
273 /// A SigningKey that uses exactly one TLS-level SignatureScheme
274 /// and one ring-level signature::SigningAlgorithm.
275 ///
276 /// Compare this to RSASigningKey, which for a particular key is
277 /// willing to sign with several algorithms. This is quite poor
278 /// cryptography practice, but is necessary because a given RSA key
279 /// is expected to work in TLS1.2 (PKCS#1 signatures) and TLS1.3
280 /// (PSS signatures) -- nobody is willing to obtain certificates for
281 /// different protocol versions.
282 ///
283 /// Currently this is only implemented for ECDSA keys.
284 struct ECDSASigningKey {
285 key: Arc<EcdsaKeyPair>,
286 scheme: SignatureScheme,
287 }
288
289 impl ECDSASigningKey {
290 /// Make a new `ECDSASigningKey` from a DER encoding in PKCS#8 format,
291 /// expecting a key usable with precisely the given signature scheme.
new( der: &key::PrivateKey, scheme: SignatureScheme, sigalg: &'static signature::EcdsaSigningAlgorithm, ) -> Result<ECDSASigningKey, ()>292 pub fn new(
293 der: &key::PrivateKey,
294 scheme: SignatureScheme,
295 sigalg: &'static signature::EcdsaSigningAlgorithm,
296 ) -> Result<ECDSASigningKey, ()> {
297 EcdsaKeyPair::from_pkcs8(sigalg, &der.0)
298 .map(|kp| ECDSASigningKey {
299 key: Arc::new(kp),
300 scheme,
301 })
302 .map_err(|_| ())
303 }
304 }
305
306 impl SigningKey for ECDSASigningKey {
choose_scheme(&self, offered: &[SignatureScheme]) -> Option<Box<dyn Signer>>307 fn choose_scheme(&self, offered: &[SignatureScheme]) -> Option<Box<dyn Signer>> {
308 if offered.contains(&self.scheme) {
309 Some(Box::new(ECDSASigner {
310 key: self.key.clone(),
311 scheme: self.scheme,
312 }))
313 } else {
314 None
315 }
316 }
317
algorithm(&self) -> SignatureAlgorithm318 fn algorithm(&self) -> SignatureAlgorithm {
319 use crate::msgs::handshake::DecomposedSignatureScheme;
320 self.scheme.sign()
321 }
322 }
323
324 struct ECDSASigner {
325 key: Arc<EcdsaKeyPair>,
326 scheme: SignatureScheme,
327 }
328
329 impl Signer for ECDSASigner {
sign(&self, message: &[u8]) -> Result<Vec<u8>, TLSError>330 fn sign(&self, message: &[u8]) -> Result<Vec<u8>, TLSError> {
331 let rng = ring::rand::SystemRandom::new();
332 self.key
333 .sign(&rng, message)
334 .map_err(|_| TLSError::General("signing failed".into()))
335 .map(|sig| sig.as_ref().into())
336 }
337
get_scheme(&self) -> SignatureScheme338 fn get_scheme(&self) -> SignatureScheme {
339 self.scheme
340 }
341 }
342
343 /// A SigningKey that uses exactly one TLS-level SignatureScheme
344 /// and one ring-level signature::SigningAlgorithm.
345 ///
346 /// Compare this to RSASigningKey, which for a particular key is
347 /// willing to sign with several algorithms. This is quite poor
348 /// cryptography practice, but is necessary because a given RSA key
349 /// is expected to work in TLS1.2 (PKCS#1 signatures) and TLS1.3
350 /// (PSS signatures) -- nobody is willing to obtain certificates for
351 /// different protocol versions.
352 ///
353 /// Currently this is only implemented for Ed25519 keys.
354 struct Ed25519SigningKey {
355 key: Arc<Ed25519KeyPair>,
356 scheme: SignatureScheme,
357 }
358
359 impl Ed25519SigningKey {
360 /// Make a new `Ed25519SigningKey` from a DER encoding in PKCS#8 format,
361 /// expecting a key usable with precisely the given signature scheme.
new(der: &key::PrivateKey, scheme: SignatureScheme) -> Result<Ed25519SigningKey, ()>362 pub fn new(der: &key::PrivateKey, scheme: SignatureScheme) -> Result<Ed25519SigningKey, ()> {
363 Ed25519KeyPair::from_pkcs8_maybe_unchecked(&der.0)
364 .map(|kp| Ed25519SigningKey {
365 key: Arc::new(kp),
366 scheme,
367 })
368 .map_err(|_| ())
369 }
370 }
371
372 impl SigningKey for Ed25519SigningKey {
choose_scheme(&self, offered: &[SignatureScheme]) -> Option<Box<dyn Signer>>373 fn choose_scheme(&self, offered: &[SignatureScheme]) -> Option<Box<dyn Signer>> {
374 if offered.contains(&self.scheme) {
375 Some(Box::new(Ed25519Signer {
376 key: self.key.clone(),
377 scheme: self.scheme,
378 }))
379 } else {
380 None
381 }
382 }
383
algorithm(&self) -> SignatureAlgorithm384 fn algorithm(&self) -> SignatureAlgorithm {
385 use crate::msgs::handshake::DecomposedSignatureScheme;
386 self.scheme.sign()
387 }
388 }
389
390 struct Ed25519Signer {
391 key: Arc<Ed25519KeyPair>,
392 scheme: SignatureScheme,
393 }
394
395 impl Signer for Ed25519Signer {
sign(&self, message: &[u8]) -> Result<Vec<u8>, TLSError>396 fn sign(&self, message: &[u8]) -> Result<Vec<u8>, TLSError> {
397 Ok(self.key.sign(message).as_ref().into())
398 }
399
get_scheme(&self) -> SignatureScheme400 fn get_scheme(&self) -> SignatureScheme {
401 self.scheme
402 }
403 }
404
405 /// The set of schemes we support for signatures and
406 /// that are allowed for TLS1.3.
supported_sign_tls13() -> &'static [SignatureScheme]407 pub fn supported_sign_tls13() -> &'static [SignatureScheme] {
408 &[
409 SignatureScheme::ECDSA_NISTP384_SHA384,
410 SignatureScheme::ECDSA_NISTP256_SHA256,
411 SignatureScheme::RSA_PSS_SHA512,
412 SignatureScheme::RSA_PSS_SHA384,
413 SignatureScheme::RSA_PSS_SHA256,
414 SignatureScheme::ED25519,
415 ]
416 }
417