Struct Builder

pub struct Builder { /* private fields */ }

Available on crate feature alloc only.

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, ) -> Result<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>

Available on crate feature std only.

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

pub fn new_with_random_nonce( rng: &mut impl CryptoRngCore, public_key: impl Into<KeyData>, valid_after: u64, valid_before: u64, ) -> Result<Self>

Available on crate feature rand_core only.

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.