Struct ssh_key::certificate::Builder

pub struct Builder { /* private fields */ }

OpenSSH certificate builder.

This type provides the core functionality of an OpenSSH certificate authority.

It can build and sign OpenSSH certificates.

Principals

Certificates are valid for a specific set of principal names:

• Usernames for CertType::User.
• Hostnames for CertType::Host.

When building a certificate, you will either need to specify principals by calling Builder::valid_principal one or more times, or explicitly marking a certificate as valid for all principals (i.e. “golden ticket”) using the Builder::all_principals_valid method.

Example

use ssh_key::{Algorithm, PrivateKey, certificate, rand_core::OsRng};
use std::time::{SystemTime, UNIX_EPOCH};

// Generate the certificate authority's private key
let ca_key = PrivateKey::random(&mut OsRng, Algorithm::Ed25519)?;

// Generate a "subject" key to be signed by the certificate authority.
// Normally a user or host would do this locally and give the certificate
// authority the public key.
let subject_private_key = PrivateKey::random(&mut OsRng, Algorithm::Ed25519)?;
let subject_public_key = subject_private_key.public_key();

// Create certificate validity window
let valid_after = SystemTime::now().duration_since(UNIX_EPOCH)?.as_secs();
let valid_before = valid_after + (365 * 86400); // e.g. 1 year

// Initialize certificate builder
let mut cert_builder = certificate::Builder::new_with_random_nonce(
   &mut OsRng,
   subject_public_key,
   valid_after,
   valid_before,
);
cert_builder.serial(42)?; // Optional: serial number chosen by the CA
cert_builder.key_id("nobody-cert-02")?; // Optional: CA-specific key identifier
cert_builder.cert_type(certificate::CertType::User)?; // User or host certificate
cert_builder.valid_principal("nobody")?; // Unix username or hostname
cert_builder.comment("nobody@example.com")?; // Comment (typically an email address)

// Sign and return the `Certificate` for `subject_public_key`
let cert = cert_builder.sign(&ca_key)?;

Implementations

impl Builder

pub const RECOMMENDED_NONCE_SIZE: usize = 16usize

Recommended size for a nonce.

pub fn new( nonce: impl Into<Vec<u8>>, public_key: impl Into<KeyData>, valid_after: u64, valid_before: u64, ) -> Self

Create a new certificate builder for the given subject’s public key.

Also requires a nonce (random value typically 16 or 32 bytes long) and the validity window of the certificate as Unix seconds.

pub fn new_with_validity_times( nonce: impl Into<Vec<u8>>, public_key: impl Into<KeyData>, valid_after: SystemTime, valid_before: SystemTime, ) -> Result<Self>

Create a new certificate builder with the validity window specified using SystemTime values.

pub fn new_with_random_nonce( rng: impl CryptoRng + RngCore, public_key: impl Into<KeyData>, valid_after: u64, valid_before: u64, ) -> Self

Create a new certificate builder, generating a random nonce using the provided random number generator.

pub fn serial(&mut self, serial: u64) -> Result<&mut Self>

Set certificate serial number.

Default: 0.

pub fn cert_type(&mut self, cert_type: CertType) -> Result<&mut Self>

Set certificate type: user or host.

Default: CertType::User.

pub fn key_id(&mut self, key_id: impl Into<String>) -> Result<&mut Self>

Set key ID: label to identify this particular certificate.

Default ""

pub fn valid_principal( &mut self, principal: impl Into<String>, ) -> Result<&mut Self>

Add a principal (i.e. username or hostname) to valid_principals.

pub fn all_principals_valid(&mut self) -> Result<&mut Self>

Mark this certificate as being valid for all principals.

⚠️ Security Warning

Use this method with care! It generates “golden ticket” certificates which can e.g. authenticate as any user on a system, or impersonate any host.

pub fn critical_option( &mut self, name: impl Into<String>, data: impl Into<String>, ) -> Result<&mut Self>

Add a critical option to this certificate.

Critical options must be recognized or the certificate must be rejected.

pub fn extension( &mut self, name: impl Into<String>, data: impl Into<String>, ) -> Result<&mut Self>

Add an extension to this certificate.

Extensions can be unrecognized without impacting the certificate.

pub fn comment(&mut self, comment: impl Into<String>) -> Result<&mut Self>

Add a comment to this certificate.

Default ""

pub fn sign<S: SigningKey>(self, signing_key: &S) -> Result<Certificate>

Sign the certificate using the provided signer type.

The PrivateKey type can be used as a signer.