Struct CertRevocationBuilder

pub struct CertRevocationBuilder { /* private fields */ }

A builder for revocation certificates for OpenPGP certificates.

A revocation certificate for an OpenPGP certificate (as opposed to, say, a subkey) has two degrees of freedom: the certificate, and the key used to sign the revocation certificate.

Normally, the key used to sign the revocation certificate is the certificate’s primary key. However, this is not required. For instance, if Alice has marked Robert’s certificate (R) as a designated revoker for her certificate (A), then R can revoke A or parts of A. In this case, the certificate is A, and the key used to sign the revocation certificate comes from R.

Examples

Revoke cert, which was compromised yesterday:

use sequoia_openpgp as openpgp;
use openpgp::cert::prelude::*;
use openpgp::policy::StandardPolicy;
use openpgp::types::ReasonForRevocation;
use openpgp::types::RevocationStatus;
use openpgp::types::SignatureType;

let p = &StandardPolicy::new();

// Create and sign a revocation certificate.
let mut signer = cert.primary_key().key().clone()
    .parts_into_secret()?.into_keypair()?;
let sig = CertRevocationBuilder::new()
    // Don't use the current time, since the certificate was
    // actually compromised yesterday.
    .set_signature_creation_time(yesterday)?
    .set_reason_for_revocation(ReasonForRevocation::KeyCompromised,
                               b"It was the maid :/")?
    .build(&mut signer, &cert, None)?;

// Merge it into the certificate.
let cert = cert.insert_packets(sig.clone())?.0;

// Now it's revoked.
assert_eq!(RevocationStatus::Revoked(vec![&sig]),
           cert.revocation_status(p, None));

Implementations

impl CertRevocationBuilder

pub fn new() -> Self

Returns a new CertRevocationBuilder.

Examples

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

let builder = CertRevocationBuilder::new();

pub fn set_reason_for_revocation( self, code: ReasonForRevocation, reason: &[u8], ) -> Result<Self>

Sets the reason for revocation.

Examples

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

let builder = CertRevocationBuilder::new()
    .set_reason_for_revocation(ReasonForRevocation::KeyRetired,
                               b"I'm retiring this key.  \
                                 Please use my new OpenPGP certificate (FPR)");

pub fn set_signature_creation_time( self, creation_time: SystemTime, ) -> Result<Self>

Sets the revocation certificate’s creation time.

The creation time is interpreted as the time at which the certificate should be considered revoked. For a soft revocation, artifacts created prior to the revocation are still considered valid.

You’ll usually want to set this explicitly and not use the current time.

First, the creation time should reflect the time of the event that triggered the revocation. As such, if it is discovered that a certificate was compromised a week ago, then the revocation certificate should be backdated appropriately.

Second, because access to secret key material can be lost, it can be useful to create a revocation certificate in advance. Of course, such a revocation certificate will inevitably be outdated. To mitigate this problem, a number of revocation certificates can be created with different creation times. Then should a revocation certificate be needed, the most appropriate one can be used.

Examples

use std::time::{SystemTime, Duration};
use sequoia_openpgp as openpgp;
use openpgp::cert::prelude::*;

let now = SystemTime::now();
let month = Duration::from_secs(((365.24 / 12.) * 24. * 60. * 60.) as u64);

// Pre-generate revocation certificates, one for each month
// for the next 48 months.
for i in 0..48 {
    let builder = CertRevocationBuilder::new()
        .set_signature_creation_time(now + i * month);
    // ...
}

pub fn add_notation<N, V, F>( self, name: N, value: V, flags: F, critical: bool, ) -> Result<Self>

where N: AsRef<str>, V: AsRef<[u8]>, F: Into<Option<NotationDataFlags>>,

Adds a notation to the revocation certificate.

Unlike the CertRevocationBuilder::set_notation method, this function does not first remove any existing notation with the specified name.

See SignatureBuilder::add_notation for further documentation.

Examples

use sequoia_openpgp as openpgp;
use openpgp::cert::prelude::*;
use openpgp::packet::signature::subpacket::NotationDataFlags;

let builder = CertRevocationBuilder::new().add_notation(
    "revocation-policy@example.org",
    "https://policy.example.org/cert-revocation-policy",
    NotationDataFlags::empty().set_human_readable(),
    false,
);

pub fn set_notation<N, V, F>( self, name: N, value: V, flags: F, critical: bool, ) -> Result<Self>

where N: AsRef<str>, V: AsRef<[u8]>, F: Into<Option<NotationDataFlags>>,

Sets a notation to the revocation certificate.

Unlike the CertRevocationBuilder::add_notation method, this function first removes any existing notation with the specified name.

See SignatureBuilder::set_notation for further documentation.

Examples

use sequoia_openpgp as openpgp;
use openpgp::cert::prelude::*;
use openpgp::packet::signature::subpacket::NotationDataFlags;

let builder = CertRevocationBuilder::new().set_notation(
    "revocation-policy@example.org",
    "https://policy.example.org/cert-revocation-policy",
    NotationDataFlags::empty().set_human_readable(),
    false,
);

pub fn build<H>( self, signer: &mut dyn Signer, cert: &Cert, hash_algo: H, ) -> Result<Signature>

where H: Into<Option<HashAlgorithm>>,

Returns a signed revocation certificate.

A revocation certificate is generated for cert and signed using signer with the specified hash algorithm. Normally, you should pass None to select the default hash algorithm.

Examples

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

let p = &StandardPolicy::new();

// Create and sign a revocation certificate.
let mut signer = cert.primary_key().key().clone()
    .parts_into_secret()?.into_keypair()?;
let sig = CertRevocationBuilder::new()
    .set_reason_for_revocation(ReasonForRevocation::KeyRetired,
                               b"Left Foo Corp.")?
    .build(&mut signer, &cert, None)?;

Trait Implementations

impl TryFrom<SignatureBuilder> for CertRevocationBuilder

type Error = Error

The type returned in the event of a conversion error.

fn try_from(builder: SignatureBuilder) -> Result<Self>

Performs the conversion.