Struct sequoia_openpgp::parse::stream::Decryptor

source ·
pub struct Decryptor<'a, H: VerificationHelper + DecryptionHelper> { /* private fields */ }
Expand description

Decrypts and verifies an encrypted and optionally signed OpenPGP message.

To create a Decryptor, create a DecryptorBuilder using Parse, and customize it to your needs.

Signature verification and detection of ciphertext tampering requires processing the whole message first. Therefore, OpenPGP implementations supporting streaming operations necessarily must output unverified data. This has been a source of problems in the past. To alleviate this, we buffer the message first (up to 25 megabytes of net message data by default, see DEFAULT_BUFFER_SIZE), and verify the signatures if the message fits into our buffer. Nevertheless it is important to treat the data as unverified and untrustworthy until you have seen a positive verification. See Decryptor::message_processed for more information.

See GoodChecksum for what it means for a signature to be considered valid.

§Examples

use std::io::Read;
use sequoia_openpgp as openpgp;
use openpgp::crypto::SessionKey;
use openpgp::types::SymmetricAlgorithm;
use openpgp::{KeyID, Cert, Result, packet::{Key, PKESK, SKESK}};
use openpgp::parse::{Parse, stream::*};
use sequoia_openpgp::policy::StandardPolicy;

let p = &StandardPolicy::new();

// This fetches keys and computes the validity of the verification.
struct Helper {};
impl VerificationHelper for Helper {
    fn get_certs(&mut self, _ids: &[openpgp::KeyHandle]) -> Result<Vec<Cert>> {
        Ok(Vec::new()) // Feed the Certs to the verifier here...
    }
    fn check(&mut self, structure: MessageStructure) -> Result<()> {
        Ok(()) // Implement your verification policy here.
    }
}
impl DecryptionHelper for Helper {
    fn decrypt<D>(&mut self, _: &[PKESK], skesks: &[SKESK],
                  _sym_algo: Option<SymmetricAlgorithm>,
                  mut decrypt: D) -> Result<Option<openpgp::Fingerprint>>
        where D: FnMut(SymmetricAlgorithm, &SessionKey) -> bool
    {
        skesks[0].decrypt(&"streng geheim".into())
            .map(|(algo, session_key)| decrypt(algo, &session_key));
        Ok(None)
    }
}

let message =
   b"-----BEGIN PGP MESSAGE-----

     wy4ECQMIY5Zs8RerVcXp85UgoUKjKkevNPX3WfcS5eb7rkT9I6kw6N2eEc5PJUDh
     0j0B9mnPKeIwhp2kBHpLX/en6RfNqYauX9eSeia7aqsd/AOLbO9WMCLZS5d2LTxN
     rwwb8Aggyukj13Mi0FF5
     =OB/8
     -----END PGP MESSAGE-----";

let h = Helper {};
let mut v = DecryptorBuilder::from_bytes(&message[..])?
    .with_policy(p, None, h)?;

let mut content = Vec::new();
v.read_to_end(&mut content)?;
assert_eq!(content, b"Hello World!");

Implementations§

source§

impl<'a, H: VerificationHelper + DecryptionHelper> Decryptor<'a, H>

source

pub fn helper_ref(&self) -> &H

Returns a reference to the helper.

source

pub fn helper_mut(&mut self) -> &mut H

Returns a mutable reference to the helper.

source

pub fn into_helper(self) -> H

Recovers the helper.

source

pub fn message_processed(&self) -> bool

Returns true if the whole message has been processed and authenticated.

If the function returns true, the whole message has been processed, the signatures are verified, and the message structure has been passed to VerificationHelper::check. Data read from this Verifier using io::Read has been authenticated.

If the function returns false, the message did not fit into the internal buffer, and therefore data read from this Verifier using io::Read has not yet been authenticated. It is important to treat this data as attacker controlled and not use it until it has been authenticated.

§Examples

This example demonstrates how to verify a message in a streaming fashion, writing the data to a temporary file and only commit the result once the data is authenticated.

use std::io::{Read, Seek, SeekFrom};
use sequoia_openpgp as openpgp;
use openpgp::{KeyHandle, Cert, Result};
use openpgp::parse::{Parse, stream::*};
use openpgp::policy::StandardPolicy;

let p = &StandardPolicy::new();

// This fetches keys and computes the validity of the verification.
struct Helper {};
impl VerificationHelper for Helper {
    // ...
}

let mut source =
   // ...

fn consume(r: &mut dyn Read) -> Result<()> {
   // ...
}

let h = Helper {};
let mut v = VerifierBuilder::from_reader(&mut source)?
    .with_policy(p, None, h)?;

if v.message_processed() {
    // The data has been authenticated.
    consume(&mut v)?;
} else {
    let mut tmp = tempfile::tempfile()?;
    std::io::copy(&mut v, &mut tmp)?;

    // If the copy succeeds, the message has been fully
    // processed and the data has been authenticated.
    assert!(v.message_processed());

    // Rewind and consume.
    tmp.seek(SeekFrom::Start(0))?;
    consume(&mut tmp)?;
}

Trait Implementations§

source§

impl<'a, H: VerificationHelper + DecryptionHelper> Read for Decryptor<'a, H>

source§

fn read(&mut self, buf: &mut [u8]) -> Result<usize>

Pull some bytes from this source into the specified buffer, returning how many bytes were read. Read more
1.36.0 · source§

fn read_vectored(&mut self, bufs: &mut [IoSliceMut<'_>]) -> Result<usize, Error>

Like read, except that it reads into a slice of buffers. Read more
source§

fn is_read_vectored(&self) -> bool

🔬This is a nightly-only experimental API. (can_vector)
Determines if this Reader has an efficient read_vectored implementation. Read more
1.0.0 · source§

fn read_to_end(&mut self, buf: &mut Vec<u8>) -> Result<usize, Error>

Read all bytes until EOF in this source, placing them into buf. Read more
1.0.0 · source§

fn read_to_string(&mut self, buf: &mut String) -> Result<usize, Error>

Read all bytes until EOF in this source, appending them to buf. Read more
1.6.0 · source§

fn read_exact(&mut self, buf: &mut [u8]) -> Result<(), Error>

Read the exact number of bytes required to fill buf. Read more
source§

fn read_buf(&mut self, buf: BorrowedCursor<'_>) -> Result<(), Error>

🔬This is a nightly-only experimental API. (read_buf)
Pull some bytes from this source into the specified buffer. Read more
source§

fn read_buf_exact(&mut self, cursor: BorrowedCursor<'_>) -> Result<(), Error>

🔬This is a nightly-only experimental API. (read_buf)
Read the exact number of bytes required to fill cursor. Read more
1.0.0 · source§

fn by_ref(&mut self) -> &mut Self
where Self: Sized,

Creates a “by reference” adaptor for this instance of Read. Read more
1.0.0 · source§

fn bytes(self) -> Bytes<Self>
where Self: Sized,

Transforms this Read instance to an Iterator over its bytes. Read more
1.0.0 · source§

fn chain<R>(self, next: R) -> Chain<Self, R>
where R: Read, Self: Sized,

Creates an adapter which will chain this stream with another. Read more
1.0.0 · source§

fn take(self, limit: u64) -> Take<Self>
where Self: Sized,

Creates an adapter which will read at most limit bytes from it. Read more

Auto Trait Implementations§

§

impl<'a, H> !Freeze for Decryptor<'a, H>

§

impl<'a, H> !RefUnwindSafe for Decryptor<'a, H>

§

impl<'a, H> Send for Decryptor<'a, H>
where H: Send,

§

impl<'a, H> Sync for Decryptor<'a, H>
where H: Sync,

§

impl<'a, H> Unpin for Decryptor<'a, H>
where H: Unpin,

§

impl<'a, H> !UnwindSafe for Decryptor<'a, H>

Blanket Implementations§

source§

impl<T> Any for T
where T: 'static + ?Sized,

source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
source§

impl<T> Borrow<T> for T
where T: ?Sized,

source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
source§

impl<T> BorrowMut<T> for T
where T: ?Sized,

source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
source§

impl<T> From<T> for T

source§

fn from(t: T) -> T

Returns the argument unchanged.

source§

impl<T, U> Into<U> for T
where U: From<T>,

source§

fn into(self) -> U

Calls U::from(self).

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

source§

impl<T> Same for T

§

type Output = T

Should always be Self
source§

impl<T, U> TryFrom<U> for T
where U: Into<T>,

§

type Error = Infallible

The type returned in the event of a conversion error.
source§

fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>

Performs the conversion.
source§

impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.