logo
pub struct CertBuilder<'a> { /* private fields */ }
Expand description

Simplifies the generation of OpenPGP certificates.

A builder to generate complex certificate hierarchies with multiple UserIDs, UserAttributes, and Keys.

This builder does not aim to be as flexible as creating certificates manually, but it should be sufficiently powerful to cover most use cases.

Security considerations

Expiration

There are two ways to invalidate cryptographic key material: revocation and freshness. Both variants come with their own challenges. Revocations rely on a robust channel to update certificates (and attackers may interfere with that).

On the other hand, freshness involves creating key material that expires after a certain time, then periodically extending the expiration time. Again, consumers need a way to update certificates, but should that fail (maybe because it was interfered with), the consumer errs on the side of no longer trusting that key material.

Because of the way metadata is added to OpenPGP certificates, attackers who control the certificate lookup and update mechanism may strip components like signatures from the certificate. This has implications for the robustness of relying on freshness.

If you first create a certificate that does not expire, and then change your mind and set an expiration time, an attacker can simply strip off that update, yielding the original certificate that does not expire.

Hence, to ensure robust key expiration, you must set an expiration with CertBuilder::set_validity_period when you create the certificate.

By default, the CertBuilder creates certificates that do not expire, because the expiration time is a policy decision and depends on the use case. For general purpose certificates, CertBuilder::general_purpose sets the validity period to roughly three years.

Examples

Generate a general-purpose certificate with one User ID:

use sequoia_openpgp as openpgp;
use openpgp::cert::prelude::*;

let (cert, rev) =
    CertBuilder::general_purpose(None, Some("alice@example.org"))
        .generate()?;

Implementations

Returns a new CertBuilder.

The returned builder is configured to generate a minimal OpenPGP certificate, a certificate with just a certification-capable primary key. You’ll typically want to add at least one User ID (using CertBuilder::add_userid). and some subkeys (using CertBuilder::add_signing_subkey, CertBuilder::add_transport_encryption_subkey, etc.).

By default, the generated certificate does not expire. It is recommended to set a suitable validity period using CertBuilder::set_validity_period. See this section of the type’s documentation for security considerations of key expiration.

Examples
use sequoia_openpgp as openpgp;
use openpgp::cert::prelude::*;

let (cert, rev) =
    CertBuilder::new()
        .add_userid("Alice Lovelace <alice@lovelace.name>")
        .add_signing_subkey()
        .add_transport_encryption_subkey()
        .add_storage_encryption_subkey()
        .generate()?;

Generates a general-purpose certificate.

The returned builder is set to generate a certificate with a certification-capable primary key, a signing-capable subkey, and an encryption-capable subkey. The encryption subkey is marked as being appropriate for both data in transit and data at rest.

The certificate and all subkeys are valid for approximately three years.

Examples
use sequoia_openpgp as openpgp;
use openpgp::cert::prelude::*;

let (cert, rev) =
    CertBuilder::general_purpose(None,
                                 Some("Alice Lovelace <alice@example.org>"))
        .generate()?;

Sets the creation time.

If creation_time is not None, this causes the CertBuilder to use that time when CertBuilder::generate is called. If it is None, the default, then the current time minus 60 seconds is used as creation time. Backdating the certificate by a minute has the advantage that the certificate can immediately be customized:

In order to reliably override a binding signature, the overriding binding signature must be newer than the existing signature. If, however, the existing signature is created now, any newer signature must have a future creation time, and is considered invalid by Sequoia. To avoid this, we backdate certificate creation times (and hence binding signature creation times), so that there is “space” between the creation time and now for signature updates.

Warning: this function takes a SystemTime. A SystemTime has a higher resolution, and a larger range than an OpenPGP Timestamp. Assuming the creation_time is in range, it will automatically be truncated to the nearest time that is representable by a Timestamp. If it is not in range, generate will return an error.

Examples

Generate a backdated certificate:

use std::time::{SystemTime, Duration};
use std::convert::TryFrom;

use sequoia_openpgp as openpgp;
use openpgp::cert::prelude::*;
use openpgp::types::Timestamp;

let t = SystemTime::now() - Duration::from_secs(365 * 24 * 60 * 60);
// Roundtrip the time so that the assert below works.
let t = SystemTime::from(Timestamp::try_from(t)?);

let (cert, rev) =
    CertBuilder::general_purpose(None,
                                 Some("Alice Lovelace <alice@example.org>"))
        .set_creation_time(t)
        .generate()?;
assert_eq!(cert.primary_key().self_signatures().nth(0).unwrap()
           .signature_creation_time(),
           Some(t));

Returns the configured creation time, if any.

Examples
use std::time::SystemTime;

use sequoia_openpgp as openpgp;
use openpgp::cert::prelude::*;

let mut builder = CertBuilder::new();
assert!(builder.creation_time().is_none());

let now = std::time::SystemTime::now();
builder = builder.set_creation_time(Some(now));
assert_eq!(builder.creation_time(), Some(now));

builder = builder.set_creation_time(None);
assert!(builder.creation_time().is_none());

Sets the default asymmetric algorithms.

This method controls the set of algorithms that is used to generate the certificate’s keys.

Examples
use sequoia_openpgp as openpgp;
use openpgp::cert::prelude::*;
use openpgp::types::PublicKeyAlgorithm;

let (ecc, _) =
    CertBuilder::general_purpose(None, Some("alice@example.org"))
        .set_cipher_suite(CipherSuite::Cv25519)
        .generate()?;
assert_eq!(ecc.primary_key().pk_algo(), PublicKeyAlgorithm::EdDSA);

let (rsa, _) =
    CertBuilder::general_purpose(None, Some("alice@example.org"))
        .set_cipher_suite(CipherSuite::RSA2k)
        .generate()?;
assert_eq!(rsa.primary_key().pk_algo(), PublicKeyAlgorithm::RSAEncryptSign);

Adds a User ID.

Adds a User ID to the certificate. The first User ID that is added, whether via this interface or another interface, e.g., CertBuilder::general_purpose, will have the primary User ID flag set.

Examples
use sequoia_openpgp as openpgp;
use openpgp::cert::prelude::*;
use openpgp::packet::prelude::*;
use openpgp::policy::StandardPolicy;

let p = &StandardPolicy::new();

let (cert, rev) =
    CertBuilder::general_purpose(None,
                                 Some("Alice Lovelace <alice@example.org>"))
        .add_userid("Alice Lovelace <alice@lovelace.name>")
        .generate()?;

assert_eq!(cert.userids().count(), 2);
let mut userids = cert.with_policy(p, None)?.userids().collect::<Vec<_>>();
// Sort lexicographically.
userids.sort_by(|a, b| a.value().cmp(b.value()));
assert_eq!(userids[0].userid(),
           &UserID::from("Alice Lovelace <alice@example.org>"));
assert_eq!(userids[1].userid(),
           &UserID::from("Alice Lovelace <alice@lovelace.name>"));


assert_eq!(userids[0].binding_signature().primary_userid().unwrap_or(false), true);
assert_eq!(userids[1].binding_signature().primary_userid().unwrap_or(false), false);

Adds a User ID with a binding signature based on builder.

Adds a User ID to the certificate, creating the binding signature using builder. The builders signature type must be a certification signature (i.e. either GenericCertification, PersonaCertification, CasualCertification, or PositiveCertification).

The key generation step uses builder as a template, but tweaks it so the signature is a valid binding signature. If you need more control, consider using UserID::bind.

The following modifications are performed on builder:

  • An appropriate hash algorithm is selected.

  • The creation time is set.

  • Primary key metadata is added (key flags, key validity period).

  • Certificate metadata is added (feature flags, algorithm preferences).

  • The CertBuilder marks exactly one User ID or User Attribute as primary: The first one provided to CertBuilder::add_userid_with or CertBuilder::add_user_attribute_with (the UserID takes precedence) that is marked as primary, or the first User ID or User Attribute added to the CertBuilder.

Examples

This example very casually binds a User ID to a certificate.

let (cert, revocation_cert) =
    CertBuilder::general_purpose(
        None, Some("Alice Lovelace <alice@example.org>"))
    .add_userid_with(
        "trinity",
        SignatureBuilder::new(SignatureType::CasualCertification)
            .set_notation("rabbit@example.org", b"follow me",
                          NotationDataFlags::empty().set_human_readable(),
                          false)?)?
    .generate()?;

assert_eq!(cert.userids().count(), 2);
let mut userids = cert.with_policy(policy, None)?.userids().collect::<Vec<_>>();
// Sort lexicographically.
userids.sort_by(|a, b| a.value().cmp(b.value()));
assert_eq!(userids[0].userid(),
           &UserID::from("Alice Lovelace <alice@example.org>"));
assert_eq!(userids[1].userid(),
           &UserID::from("trinity"));

assert!(userids[0].binding_signature().primary_userid().unwrap_or(false));
assert!(! userids[1].binding_signature().primary_userid().unwrap_or(false));
assert_eq!(userids[1].binding_signature().notation("rabbit@example.org")
           .next().unwrap(), b"follow me");

Adds a new User Attribute.

Adds a User Attribute to the certificate. If there are no User IDs, the first User attribute that is added, whether via this interface or another interface, will have the primary User ID flag set.

Examples

When there are no User IDs, the first User Attribute has the primary User ID flag set:

use sequoia_openpgp as openpgp;
use openpgp::cert::prelude::*;
use openpgp::packet::prelude::*;
use openpgp::policy::StandardPolicy;

let p = &StandardPolicy::new();

let (cert, rev) =
    CertBuilder::new()
        .add_user_attribute(user_attribute)
        .generate()?;

assert_eq!(cert.userids().count(), 0);
assert_eq!(cert.user_attributes().count(), 1);
let mut uas = cert.with_policy(p, None)?.user_attributes().collect::<Vec<_>>();
assert_eq!(uas[0].binding_signature().primary_userid().unwrap_or(false), true);

Where there are User IDs, then the primary User ID flag is not set:

use sequoia_openpgp as openpgp;
use openpgp::cert::prelude::*;
use openpgp::packet::prelude::*;
use openpgp::policy::StandardPolicy;

let p = &StandardPolicy::new();

let (cert, rev) =
    CertBuilder::new()
        .add_userid("alice@example.org")
        .add_user_attribute(user_attribute)
        .generate()?;

assert_eq!(cert.userids().count(), 1);
assert_eq!(cert.user_attributes().count(), 1);
let mut uas = cert.with_policy(p, None)?.user_attributes().collect::<Vec<_>>();
assert_eq!(uas[0].binding_signature().primary_userid().unwrap_or(false), false);

Adds a User Attribute with a binding signature based on builder.

Adds a User Attribute to the certificate, creating the binding signature using builder. The builders signature type must be a certification signature (i.e. either GenericCertification, PersonaCertification, CasualCertification, or PositiveCertification).

The key generation step uses builder as a template, but tweaks it so the signature is a valid binding signature. If you need more control, consider using UserAttribute::bind.

The following modifications are performed on builder:

  • An appropriate hash algorithm is selected.

  • The creation time is set.

  • Primary key metadata is added (key flags, key validity period).

  • Certificate metadata is added (feature flags, algorithm preferences).

  • The CertBuilder marks exactly one User ID or User Attribute as primary: The first one provided to CertBuilder::add_userid_with or CertBuilder::add_user_attribute_with (the UserID takes precedence) that is marked as primary, or the first User ID or User Attribute added to the CertBuilder.

Examples

This example very casually binds a user attribute to a certificate.

let (cert, revocation_cert) =
    CertBuilder::general_purpose(
        None, Some("Alice Lovelace <alice@example.org>"))
    .add_user_attribute_with(
        user_attribute,
        SignatureBuilder::new(SignatureType::CasualCertification)
            .set_notation("rabbit@example.org", b"follow me",
                          NotationDataFlags::empty().set_human_readable(),
                          false)?)?
    .generate()?;

let uas = cert.with_policy(policy, None)?.user_attributes().collect::<Vec<_>>();
assert_eq!(uas.len(), 1);
assert!(! uas[0].binding_signature().primary_userid().unwrap_or(false));
assert_eq!(uas[0].binding_signature().notation("rabbit@example.org")
           .next().unwrap(), b"follow me");

Adds a signing-capable subkey.

The key uses the default cipher suite (see CertBuilder::set_cipher_suite), and is not set to expire. Use CertBuilder::add_subkey if you need to change these parameters.

Examples
use sequoia_openpgp as openpgp;
use openpgp::cert::prelude::*;
use openpgp::policy::StandardPolicy;
use openpgp::types::KeyFlags;

let p = &StandardPolicy::new();

let (cert, rev) =
    CertBuilder::new()
        .add_signing_subkey()
        .generate()?;

assert_eq!(cert.keys().count(), 2);
let ka = cert.with_policy(p, None)?.keys().nth(1).unwrap();
assert_eq!(ka.key_flags(),
           Some(KeyFlags::empty().set_signing()));

Adds a subkey suitable for transport encryption.

The key uses the default cipher suite (see CertBuilder::set_cipher_suite), and is not set to expire. Use CertBuilder::add_subkey if you need to change these parameters.

Examples
use sequoia_openpgp as openpgp;
use openpgp::cert::prelude::*;
use openpgp::policy::StandardPolicy;
use openpgp::types::KeyFlags;

let p = &StandardPolicy::new();

let (cert, rev) =
    CertBuilder::new()
        .add_transport_encryption_subkey()
        .generate()?;

assert_eq!(cert.keys().count(), 2);
let ka = cert.with_policy(p, None)?.keys().nth(1).unwrap();
assert_eq!(ka.key_flags(),
           Some(KeyFlags::empty().set_transport_encryption()));

Adds a subkey suitable for storage encryption.

The key uses the default cipher suite (see CertBuilder::set_cipher_suite), and is not set to expire. Use CertBuilder::add_subkey if you need to change these parameters.

Examples
use sequoia_openpgp as openpgp;
use openpgp::cert::prelude::*;
use openpgp::policy::StandardPolicy;
use openpgp::types::KeyFlags;

let p = &StandardPolicy::new();

let (cert, rev) =
    CertBuilder::new()
        .add_storage_encryption_subkey()
        .generate()?;

assert_eq!(cert.keys().count(), 2);
let ka = cert.with_policy(p, None)?.keys().nth(1).unwrap();
assert_eq!(ka.key_flags(),
           Some(KeyFlags::empty().set_storage_encryption()));

Adds an certification-capable subkey.

The key uses the default cipher suite (see CertBuilder::set_cipher_suite), and is not set to expire. Use CertBuilder::add_subkey if you need to change these parameters.

Examples
use sequoia_openpgp as openpgp;
use openpgp::cert::prelude::*;
use openpgp::policy::StandardPolicy;
use openpgp::types::KeyFlags;

let p = &StandardPolicy::new();

let (cert, rev) =
    CertBuilder::new()
        .add_certification_subkey()
        .generate()?;

assert_eq!(cert.keys().count(), 2);
let ka = cert.with_policy(p, None)?.keys().nth(1).unwrap();
assert_eq!(ka.key_flags(),
           Some(KeyFlags::empty().set_certification()));

Adds an authentication-capable subkey.

The key uses the default cipher suite (see CertBuilder::set_cipher_suite), and is not set to expire. Use CertBuilder::add_subkey if you need to change these parameters.

Examples
use sequoia_openpgp as openpgp;
use openpgp::cert::prelude::*;
use openpgp::policy::StandardPolicy;
use openpgp::types::KeyFlags;

let p = &StandardPolicy::new();

let (cert, rev) =
    CertBuilder::new()
        .add_authentication_subkey()
        .generate()?;

assert_eq!(cert.keys().count(), 2);
let ka = cert.with_policy(p, None)?.keys().nth(1).unwrap();
assert_eq!(ka.key_flags(),
           Some(KeyFlags::empty().set_authentication()));

Adds a custom subkey.

If validity is None, the subkey will be valid for the same period as the primary key.

Likewise, if cs is None, the same cipher suite is used as for the primary key.

Examples

Generates a certificate with an encryption subkey that is for protecting both data in transit and data at rest, and expires at a different time from the primary key:

use sequoia_openpgp as openpgp;
use openpgp::cert::prelude::*;
use openpgp::policy::StandardPolicy;
use openpgp::types::KeyFlags;

let p = &StandardPolicy::new();

let now = std::time::SystemTime::now();
let y = std::time::Duration::new(365 * 24 * 60 * 60, 0);

// Make the certificate expire in 2 years, and the subkey
// expire in a year.
let (cert,_) = CertBuilder::new()
    .set_creation_time(now)
    .set_validity_period(2 * y)
    .add_subkey(KeyFlags::empty()
                    .set_storage_encryption()
                    .set_transport_encryption(),
                y,
                None)
    .generate()?;

assert_eq!(cert.with_policy(p, now)?.keys().alive().count(), 2);
assert_eq!(cert.with_policy(p, now + y)?.keys().alive().count(), 1);
assert_eq!(cert.with_policy(p, now + 2 * y)?.keys().alive().count(), 0);

let ka = cert.with_policy(p, None)?.keys().nth(1).unwrap();
assert_eq!(ka.key_flags(),
           Some(KeyFlags::empty()
                    .set_storage_encryption()
                    .set_transport_encryption()));

Adds a subkey with a binding signature based on builder.

Adds a subkey to the certificate, creating the binding signature using builder. The builders signature type must be SubkeyBinding.

The key generation step uses builder as a template, but adds all subpackets that the signature needs to be a valid binding signature. If you need more control, or want to adopt existing keys, consider using Key::bind.

The following modifications are performed on builder:

  • An appropriate hash algorithm is selected.

  • The creation time is set.

  • Key metadata is added (key flags, key validity period).

If validity is None, the subkey will be valid for the same period as the primary key.

Examples

This example binds a signing subkey to a certificate, restricting its use to authentication of software.

let (cert, revocation_cert) =
    CertBuilder::general_purpose(
        None, Some("Alice Lovelace <alice@example.org>"))
    .add_subkey_with(
        KeyFlags::empty().set_signing(), None, None,
        SignatureBuilder::new(SignatureType::SubkeyBinding)
            // Add a critical notation!
            .set_notation("code-signing@policy.example.org", b"",
                          NotationDataFlags::empty(), true)?)?
    .generate()?;

// Under the standard policy, the additional signing subkey
// is not bound.
let p = StandardPolicy::new();
assert_eq!(cert.with_policy(&p, None)?.keys().for_signing().count(), 1);

// However, software implementing the notation see the additional
// signing subkey.
let mut p = StandardPolicy::new();
p.good_critical_notations(&["code-signing@policy.example.org"]);
assert_eq!(cert.with_policy(&p, None)?.keys().for_signing().count(), 2);

Sets the primary key’s key flags.

By default, the primary key is set to only be certification capable. This allows the caller to set additional flags.

Examples

Makes the primary key signing-capable but not certification-capable.

use sequoia_openpgp as openpgp;
use openpgp::cert::prelude::*;
use openpgp::policy::StandardPolicy;
use openpgp::types::KeyFlags;

let p = &StandardPolicy::new();

let (cert, rev) =
    CertBuilder::general_purpose(None,
                                 Some("Alice Lovelace <alice@example.org>"))
        .set_primary_key_flags(KeyFlags::empty().set_signing())
        .generate()?;

// Observe that the primary key's certification capability is
// set implicitly.
assert_eq!(cert.with_policy(p, None)?.primary_key().key_flags(),
           Some(KeyFlags::empty().set_signing()));

Sets a password to encrypt the secret keys with.

The password is used to encrypt all secret key material.

Examples
use sequoia_openpgp as openpgp;
use openpgp::cert::prelude::*;

// Make the certificate expire in 10 minutes.
let (cert, rev) =
    CertBuilder::general_purpose(None,
                                 Some("Alice Lovelace <alice@example.org>"))
        .set_password(Some("1234".into()))
        .generate()?;

for ka in cert.keys() {
    assert!(ka.has_secret());
}

Sets the certificate’s validity period.

The determines how long the certificate is valid. That is, after the validity period, the certificate is considered to be expired.

The validity period starts with the creation time (see CertBuilder::set_creation_time).

A value of None means that the certificate never expires.

See this section of the type’s documentation for security considerations of key expiration.

Examples
use sequoia_openpgp as openpgp;
use openpgp::cert::prelude::*;
use openpgp::policy::StandardPolicy;
use openpgp::types::RevocationKey;

let p = &StandardPolicy::new();

let now = std::time::SystemTime::now();
let s = std::time::Duration::new(1, 0);

// Make the certificate expire in 10 minutes.
let (cert,_) = CertBuilder::new()
    .set_creation_time(now)
    .set_validity_period(600 * s)
    .generate()?;

assert!(cert.with_policy(p, now)?.primary_key().alive().is_ok());
assert!(cert.with_policy(p, now + 599 * s)?.primary_key().alive().is_ok());
assert!(cert.with_policy(p, now + 600 * s)?.primary_key().alive().is_err());

Sets designated revokers.

Adds designated revokers to the primary key. This allows the designated revoker to issue revocation certificates on behalf of the primary key.

Examples

Make Alice a designated revoker for Bob:

use sequoia_openpgp as openpgp;
use openpgp::cert::prelude::*;
use openpgp::policy::StandardPolicy;
use openpgp::types::RevocationKey;

let p = &StandardPolicy::new();

let (alice, _) =
    CertBuilder::general_purpose(None, Some("alice@example.org"))
        .generate()?;
let (bob, _) =
    CertBuilder::general_purpose(None, Some("bob@example.org"))
        .set_revocation_keys(vec![(&alice).into()])
        .generate()?;

// Make sure Alice is listed as a designated revoker for Bob.
assert_eq!(bob.revocation_keys(p).collect::<Vec<&RevocationKey>>(),
           vec![&(&alice).into()]);

Generates a certificate.

Examples
use sequoia_openpgp as openpgp;
use openpgp::cert::prelude::*;
use openpgp::policy::StandardPolicy;
use openpgp::types::RevocationKey;

let p = &StandardPolicy::new();

let (alice, _) =
    CertBuilder::general_purpose(None, Some("alice@example.org"))
        .generate()?;

Auto Trait Implementations

Blanket Implementations

Gets the TypeId of self. Read more

Immutably borrows from an owned value. Read more

Mutably borrows from an owned value. Read more

Returns the argument unchanged.

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

Should always be Self

The type returned in the event of a conversion error.

Performs the conversion.

The type returned in the event of a conversion error.

Performs the conversion.