Trait sequoia_sop::SOP

pub trait SOP<'s>: Sized {
    type Keys: Load<'s, Self> + Save + SopRef<'s, Self>;
    type Certs: Load<'s, Self> + Save + SopRef<'s, Self>;
    type Sigs: Load<'s, Self> + Save + SopRef<'s, Self>;

    // Required methods
    fn version(&'s self) -> Result<Box<dyn Version<'s> + 's>, Error>;
    fn generate_key(
        &'s self
    ) -> Result<Box<dyn GenerateKey<'s, Self, Self::Keys> + 's>, Error>;
    fn change_key_password(
        &'s self
    ) -> Result<Box<dyn ChangeKeyPassword<'s, Self, Self::Keys> + 's>, Error>;
    fn revoke_key(
        &'s self
    ) -> Result<Box<dyn RevokeKey<'s, Self, Self::Certs, Self::Keys> + 's>, Error>;
    fn extract_cert(
        &'s self
    ) -> Result<Box<dyn ExtractCert<'s, Self, Self::Certs, Self::Keys> + 's>, Error>;
    fn sign(
        &'s self
    ) -> Result<Box<dyn Sign<'s, Self, Self::Keys, Self::Sigs> + 's>, Error>;
    fn verify(
        &'s self
    ) -> Result<Box<dyn Verify<'s, Self, Self::Certs, Self::Sigs> + 's>, Error>;
    fn encrypt(
        &'s self
    ) -> Result<Box<dyn Encrypt<'s, Self, Self::Certs, Self::Keys> + 's>, Error>;
    fn decrypt(
        &'s self
    ) -> Result<Box<dyn Decrypt<'s, Self, Self::Certs, Self::Keys> + 's>, Error>;
    fn armor(&'s self) -> Result<Box<dyn Armor<'s> + 's>, Error>;
    fn dearmor(&'s self) -> Result<Box<dyn Dearmor<'s> + 's>, Error>;
    fn inline_detach(
        &'s self
    ) -> Result<Box<dyn InlineDetach<'s, Self::Sigs> + 's>, Error>;
    fn inline_verify(
        &'s self
    ) -> Result<Box<dyn InlineVerify<'s, Self, Self::Certs> + 's>, Error>;
    fn inline_sign(
        &'s self
    ) -> Result<Box<dyn InlineSign<'s, Self, Self::Keys> + 's>, Error>;

    // Provided method
    fn spec_version(&'s self) -> &'static str { ... }
}

Main entry point to the Stateless OpenPGP Interface.

Required Associated Types

type Keys: Load<'s, Self> + Save + SopRef<'s, Self>

Secret keys.

type Certs: Load<'s, Self> + Save + SopRef<'s, Self>

Public keys.

type Sigs: Load<'s, Self> + Save + SopRef<'s, Self>

Signatures.

Required Methods

fn version(&'s self) -> Result<Box<dyn Version<'s> + 's>, Error>

Gets version information.

Examples

// Prints the name of the SOP implementation.
println!("{}", sop.version()?.frontend()?);

// Prints the name of the underlying OpenPGP implementation.
println!("{}", sop.version()?.backend()?);

// Prints extended version information.
println!("{}", sop.version()?.extended()?);

fn generate_key( &'s self ) -> Result<Box<dyn GenerateKey<'s, Self, Self::Keys> + 's>, Error>

Generates a Secret Key.

Customize the operation using the builder GenerateKey.

Examples

let alice_sec = sop.generate_key()?
    .userid("Alice Lovelace <alice@openpgp.example>")
    .generate()?;

fn change_key_password( &'s self ) -> Result<Box<dyn ChangeKeyPassword<'s, Self, Self::Keys> + 's>, Error>

Updates a key’s password.

Customize the operation using the builder ChangeKeyPassword.

Examples

let alice_secret =
    Keys::from_reader(sop, &mut File::open("alice.secret")?)?;

let alice_updated_secret = sop.change_key_password()?
    .old_key_password(Password::new_unchecked(b"hunter2".to_vec()))?
    .new_key_password(Password::new(b"jaeger2".to_vec())?)?
    .keys(&alice_secret)?;

fn revoke_key( &'s self ) -> Result<Box<dyn RevokeKey<'s, Self, Self::Certs, Self::Keys> + 's>, Error>

Creates a Revocation Certificate.

Customize the operation using the builder RevokeKey.

Examples

let alice_secret =
    Keys::from_reader(sop, &mut File::open("alice.secret")?)?;

let alice_revoked = sop.revoke_key()?
    .with_key_password(Password::new_unchecked(b"hunter2".to_vec()))?
    .keys(&alice_secret)?;

fn extract_cert( &'s self ) -> Result<Box<dyn ExtractCert<'s, Self, Self::Certs, Self::Keys> + 's>, Error>

Extracts a Certificate from a Secret Key.

Customize the operation using the builder ExtractCert.

Examples

let alice_secret =
    Keys::from_reader(sop, &mut File::open("alice.secret")?)?;

let alice_public = sop.extract_cert()?
    .keys(&alice_secret)?;

fn sign( &'s self ) -> Result<Box<dyn Sign<'s, Self, Self::Keys, Self::Sigs> + 's>, Error>

Creates Detached Signatures.

Customize the operation using the builder Sign.

Examples

let alice_secret =
    Keys::from_reader(sop, &mut File::open("alice.secret")?)?;

let (_micalg, sig) = sop.sign()?
    .keys(&alice_secret)?
    .data(&mut Cursor::new(&b"Hello World :)"))?;

fn verify( &'s self ) -> Result<Box<dyn Verify<'s, Self, Self::Certs, Self::Sigs> + 's>, Error>

Verifies Detached Signatures.

Customize the operation using the builder Verify.

Examples

let alice_public =
    Certs::from_reader(sop, &mut File::open("alice.public")?)?;
let sig =
    Sigs::from_reader(sop, &mut File::open("data.asc")?)?;

let verifications = sop.verify()?
    .certs(&alice_public)?
    .signatures(&sig)?
    .data(&mut Cursor::new(&b"Hello World :)"))?;
let valid_signatures = ! verifications.is_empty();

fn encrypt( &'s self ) -> Result<Box<dyn Encrypt<'s, Self, Self::Certs, Self::Keys> + 's>, Error>

Encrypts a Message.

Customize the operation using the builder Encrypt.

Examples

Encrypts a message for Bob, and signs it using Alice’s key.

let alice_secret =
    Keys::from_reader(sop, &mut File::open("alice.secret")?)?;
let bob_public =
    Certs::from_reader(sop, &mut File::open("bob.public")?)?;

let (_session_key, ciphertext) = sop.encrypt()?
    .sign_with_keys(&alice_secret)?
    .with_certs(&bob_public)?
    .plaintext(&mut Cursor::new(&b"Hello World :)"))?
    .to_vec()?;

fn decrypt( &'s self ) -> Result<Box<dyn Decrypt<'s, Self, Self::Certs, Self::Keys> + 's>, Error>

Decrypts a Message.

Customize the operation using the builder Decrypt.

Examples

Decrypts a message encrypted for Bob, and verifies Alice’s signature on it.

let alice_public =
    Certs::from_reader(sop, &mut File::open("alice.public")?)?;
let bob_secret =
    Keys::from_reader(sop, &mut File::open("bob.secret")?)?;

let ((_session_key, verifications), plaintext) = sop.decrypt()?
    .verify_with_certs(&alice_public)?
    .with_keys(&bob_secret)?
    .ciphertext(&mut File::open("ciphertext.pgp")?)?
    .to_vec()?;
let valid_signatures = ! verifications.is_empty();

fn armor(&'s self) -> Result<Box<dyn Armor<'s> + 's>, Error>

Converts binary OpenPGP data to ASCII.

By default, SOP operations emit ASCII-Armored data. But, occasionally it can be useful to explicitly armor data.

Customize the operation using the builder Armor.

Examples

let (_, alice_secret_asc) = sop.armor()?
    .data(&mut File::open("alice.secret.bin")?)?
    .to_vec()?;
assert!(alice_secret_asc.starts_with(b"-----BEGIN PGP PRIVATE KEY BLOCK-----"));

fn dearmor(&'s self) -> Result<Box<dyn Dearmor<'s> + 's>, Error>

Converts ASCII OpenPGP data to binary.

By default, SOP operations emit ASCII-Armored data, but this behavior can be changed at export time. Nevertheless, occasionally it can be useful to explicitly dearmor data.

Customize the operation using the builder Dearmor.

Examples

let (_, alice_secret_bin) = sop.dearmor()?
    .data(&mut File::open("alice.secret.asc")?)?
    .to_vec()?;
assert!(! alice_secret_bin.starts_with(b"-----BEGIN PGP PRIVATE KEY BLOCK-----"));

fn inline_detach( &'s self ) -> Result<Box<dyn InlineDetach<'s, Self::Sigs> + 's>, Error>

Splits Signatures from an Inline-Signed Message.

Note: The signatures are not verified, this merely transforms an inline-signed message into a detached signature, which in turn can be verified using SOP::verify.

Customize the operation using the builder InlineDetach.

Examples

let (signatures, data) = sop.inline_detach()?
    .message(&mut File::open("inline-signed.pgp")?)?
    .to_vec()?;

fn inline_verify( &'s self ) -> Result<Box<dyn InlineVerify<'s, Self, Self::Certs> + 's>, Error>

Verifies an Inline-Signed Message.

Customize the operation using the builder InlineVerify.

Examples

let alice_public =
    Certs::from_reader(sop, &mut File::open("alice.public")?)?;

let (verifications, data) = sop.inline_verify()?
    .certs(&alice_public)?
    .message(&mut File::open("inline-signed.pgp")?)?
    .to_vec()?;
let valid_signatures = ! verifications.is_empty();

fn inline_sign( &'s self ) -> Result<Box<dyn InlineSign<'s, Self, Self::Keys> + 's>, Error>

Creates an Inline-Signed Message.

Customize the operation using the builder InlineSign.

Examples

let alice_secret =
    Keys::from_reader(sop, &mut File::open("alice.secret")?)?;

let (inline_signed_asc) = sop.inline_sign()?
    .keys(&alice_secret)?
    .data(&mut Cursor::new(&b"Hello World :)"))?
    .to_vec()?;

Provided Methods

fn spec_version(&'s self) -> &'static str

Gets SOP version information.

The default implementation returns the version of the spec that this framework supports. This should be fine for most implementations. However, implementations may chose to override this function to return a more nuanced response.

Object Safety

This trait is not object safe.

Implementors

impl<'s> SOP<'s> for SQOP<'s>

type Keys = Keys<'s>

type Certs = Certs<'s>

type Sigs = Sigs<'s>