ssh_key/certificate/
builder.rs

1//! OpenSSH certificate builder.
2
3use super::{CertType, Certificate, Field, OptionsMap};
4use crate::{Result, Signature, SigningKey, public};
5use alloc::{string::String, vec::Vec};
6
7#[cfg(feature = "rand_core")]
8use rand_core::CryptoRng;
9
10#[cfg(feature = "std")]
11use {super::UnixTime, std::time::SystemTime};
12
13#[cfg(doc)]
14use crate::PrivateKey;
15
16/// OpenSSH certificate builder.
17///
18/// This type provides the core functionality of an OpenSSH certificate
19/// authority.
20///
21/// It can build and sign OpenSSH certificates.
22///
23/// ## Principals
24///
25/// Certificates are valid for a specific set of principal names:
26///
27/// - Usernames for [`CertType::User`].
28/// - Hostnames for [`CertType::Host`].
29///
30/// When building a certificate, you will either need to specify principals
31/// by calling [`Builder::valid_principal`] one or more times, or explicitly
32/// marking a certificate as valid for all principals (i.e. "golden ticket")
33/// using the [`Builder::all_principals_valid`] method.
34///
35/// ## Example
36///
37#[cfg_attr(
38    all(feature = "ed25519", feature = "getrandom", feature = "std"),
39    doc = " ```"
40)]
41#[cfg_attr(
42    not(all(feature = "ed25519", feature = "getrandom", feature = "std")),
43    doc = " ```ignore"
44)]
45/// # fn main() -> Result<(), Box<dyn std::error::Error>> {
46/// use ssh_key::{Algorithm, PrivateKey, certificate, rand_core::{TryRngCore, OsRng}};
47/// use std::time::{SystemTime, UNIX_EPOCH};
48///
49/// // Generate the certificate authority's private key
50/// let ca_key = PrivateKey::random(&mut OsRng.unwrap_err(), Algorithm::Ed25519)?;
51///
52/// // Generate a "subject" key to be signed by the certificate authority.
53/// // Normally a user or host would do this locally and give the certificate
54/// // authority the public key.
55/// let subject_private_key = PrivateKey::random(&mut OsRng.unwrap_err(), Algorithm::Ed25519)?;
56/// let subject_public_key = subject_private_key.public_key();
57///
58/// // Create certificate validity window
59/// let valid_after = SystemTime::now().duration_since(UNIX_EPOCH)?.as_secs();
60/// let valid_before = valid_after + (365 * 86400); // e.g. 1 year
61///
62/// // Initialize certificate builder
63/// let mut cert_builder = certificate::Builder::new_with_random_nonce(
64///     &mut OsRng.unwrap_err(),
65///     subject_public_key,
66///     valid_after,
67///     valid_before,
68/// )?;
69/// cert_builder.serial(42)?; // Optional: serial number chosen by the CA
70/// cert_builder.key_id("nobody-cert-02")?; // Optional: CA-specific key identifier
71/// cert_builder.cert_type(certificate::CertType::User)?; // User or host certificate
72/// cert_builder.valid_principal("nobody")?; // Unix username or hostname
73/// cert_builder.comment("nobody@example.com")?; // Comment (typically an email address)
74///
75/// // Sign and return the `Certificate` for `subject_public_key`
76/// let cert = cert_builder.sign(&ca_key)?;
77/// # Ok(())
78/// # }
79/// ```
80pub struct Builder {
81    public_key: public::KeyData,
82    nonce: Vec<u8>,
83    serial: Option<u64>,
84    cert_type: Option<CertType>,
85    key_id: Option<String>,
86    valid_principals: Option<Vec<String>>,
87    valid_after: u64,
88    valid_before: u64,
89    critical_options: OptionsMap,
90    extensions: OptionsMap,
91    comment: Option<String>,
92}
93
94impl Builder {
95    /// Recommended size for a nonce.
96    pub const RECOMMENDED_NONCE_SIZE: usize = 16;
97
98    /// Create a new certificate builder for the given subject's public key.
99    ///
100    /// Also requires a nonce (random value typically 16 or 32 bytes long) and
101    /// the validity window of the certificate as Unix seconds.
102    pub fn new(
103        nonce: impl Into<Vec<u8>>,
104        public_key: impl Into<public::KeyData>,
105        valid_after: u64,
106        valid_before: u64,
107    ) -> Result<Self> {
108        if valid_before < valid_after {
109            return Err(Field::ValidBefore.invalid_error());
110        }
111
112        Ok(Self {
113            nonce: nonce.into(),
114            public_key: public_key.into(),
115            serial: None,
116            cert_type: None,
117            key_id: None,
118            valid_principals: None,
119            valid_after,
120            valid_before,
121            critical_options: OptionsMap::new(),
122            extensions: OptionsMap::new(),
123            comment: None,
124        })
125    }
126
127    /// Create a new certificate builder with the validity window specified
128    /// using [`SystemTime`] values.
129    #[cfg(feature = "std")]
130    pub fn new_with_validity_times(
131        nonce: impl Into<Vec<u8>>,
132        public_key: impl Into<public::KeyData>,
133        valid_after: SystemTime,
134        valid_before: SystemTime,
135    ) -> Result<Self> {
136        let valid_after =
137            UnixTime::try_from(valid_after).map_err(|_| Field::ValidAfter.invalid_error())?;
138
139        let valid_before =
140            UnixTime::try_from(valid_before).map_err(|_| Field::ValidBefore.invalid_error())?;
141
142        Self::new(nonce, public_key, valid_after.into(), valid_before.into())
143    }
144
145    /// Create a new certificate builder, generating a random nonce using the
146    /// provided random number generator.
147    #[cfg(feature = "rand_core")]
148    pub fn new_with_random_nonce(
149        rng: &mut impl CryptoRng,
150        public_key: impl Into<public::KeyData>,
151        valid_after: u64,
152        valid_before: u64,
153    ) -> Result<Self> {
154        let mut nonce = vec![0u8; Self::RECOMMENDED_NONCE_SIZE];
155        rng.fill_bytes(&mut nonce);
156        Self::new(nonce, public_key, valid_after, valid_before)
157    }
158
159    /// Set certificate serial number.
160    ///
161    /// Default: `0`.
162    pub fn serial(&mut self, serial: u64) -> Result<&mut Self> {
163        if self.serial.is_some() {
164            return Err(Field::Serial.invalid_error());
165        }
166
167        self.serial = Some(serial);
168        Ok(self)
169    }
170
171    /// Set certificate type: user or host.
172    ///
173    /// Default: [`CertType::User`].
174    pub fn cert_type(&mut self, cert_type: CertType) -> Result<&mut Self> {
175        if self.cert_type.is_some() {
176            return Err(Field::Type.invalid_error());
177        }
178
179        self.cert_type = Some(cert_type);
180        Ok(self)
181    }
182
183    /// Set key ID: label to identify this particular certificate.
184    ///
185    /// Default `""`
186    pub fn key_id(&mut self, key_id: impl Into<String>) -> Result<&mut Self> {
187        if self.key_id.is_some() {
188            return Err(Field::KeyId.invalid_error());
189        }
190
191        self.key_id = Some(key_id.into());
192        Ok(self)
193    }
194
195    /// Add a principal (i.e. username or hostname) to `valid_principals`.
196    pub fn valid_principal(&mut self, principal: impl Into<String>) -> Result<&mut Self> {
197        match &mut self.valid_principals {
198            Some(principals) => principals.push(principal.into()),
199            None => self.valid_principals = Some(vec![principal.into()]),
200        }
201
202        Ok(self)
203    }
204
205    /// Mark this certificate as being valid for all principals.
206    ///
207    /// # ⚠️ Security Warning
208    ///
209    /// Use this method with care! It generates "golden ticket" certificates
210    /// which can e.g. authenticate as any user on a system, or impersonate
211    /// any host.
212    pub fn all_principals_valid(&mut self) -> Result<&mut Self> {
213        self.valid_principals = Some(Vec::new());
214        Ok(self)
215    }
216
217    /// Add a critical option to this certificate.
218    ///
219    /// Critical options must be recognized or the certificate must be rejected.
220    pub fn critical_option(
221        &mut self,
222        name: impl Into<String>,
223        data: impl Into<String>,
224    ) -> Result<&mut Self> {
225        let name = name.into();
226        let data = data.into();
227
228        if self.critical_options.contains_key(&name) {
229            return Err(Field::CriticalOptions.invalid_error());
230        }
231
232        self.critical_options.insert(name, data);
233        Ok(self)
234    }
235
236    /// Add an extension to this certificate.
237    ///
238    /// Extensions can be unrecognized without impacting the certificate.
239    pub fn extension(
240        &mut self,
241        name: impl Into<String>,
242        data: impl Into<String>,
243    ) -> Result<&mut Self> {
244        let name = name.into();
245        let data = data.into();
246
247        if self.extensions.contains_key(&name) {
248            return Err(Field::Extensions.invalid_error());
249        }
250
251        self.extensions.insert(name, data);
252        Ok(self)
253    }
254
255    /// Add a comment to this certificate.
256    ///
257    /// Default `""`
258    pub fn comment(&mut self, comment: impl Into<String>) -> Result<&mut Self> {
259        if self.comment.is_some() {
260            return Err(Field::Comment.invalid_error());
261        }
262
263        self.comment = Some(comment.into());
264        Ok(self)
265    }
266
267    /// Sign the certificate using the provided signer type.
268    ///
269    /// The [`PrivateKey`] type can be used as a signer.
270    pub fn sign<S: SigningKey>(self, signing_key: &S) -> Result<Certificate> {
271        // Empty valid principals result in a "golden ticket", so this check
272        // ensures that was explicitly configured via `all_principals_valid`.
273        let valid_principals = match self.valid_principals {
274            Some(principals) => principals,
275            None => return Err(Field::ValidPrincipals.invalid_error()),
276        };
277
278        let mut cert = Certificate {
279            nonce: self.nonce,
280            public_key: self.public_key,
281            serial: self.serial.unwrap_or_default(),
282            cert_type: self.cert_type.unwrap_or_default(),
283            key_id: self.key_id.unwrap_or_default(),
284            valid_principals,
285            valid_after: self.valid_after,
286            valid_before: self.valid_before,
287            critical_options: self.critical_options,
288            extensions: self.extensions,
289            reserved: Vec::new(),
290            comment: self.comment.unwrap_or_default(),
291            signature_key: signing_key.public_key(),
292            signature: Signature::placeholder(),
293        };
294
295        let mut tbs_cert = Vec::new();
296        cert.encode_tbs(&mut tbs_cert)?;
297        cert.signature = signing_key.try_sign(&tbs_cert)?;
298
299        #[cfg(debug_assertions)]
300        cert.validate_at(
301            cert.valid_after,
302            &[cert.signature_key.fingerprint(Default::default())],
303        )?;
304
305        Ok(cert)
306    }
307}
ssh_key/certificate/builder.rs

ssh_key/certificate/
builder.rs
