Struct sodiumoxide::crypto::secretstream::xchacha20poly1305::Stream

pub struct Stream<M: StreamMode> { /* fields omitted */ }

Stream contains the state for multi-part (streaming) computations. This allows the caller to process encryption of a sequence of multiple messages.

Methods

impl<M: StreamMode> Stream<M>

pub fn rekey(&mut self) -> Result<(), ()>

Explicit rekeying. This updates the internal state of the Stream<Pull>, and should only be called in a synchronized manner with how the corresponding Stream called it when encrypting the stream. Returns Err(()) if the stream was already finalized, else Ok(()).

pub fn is_finalized(&self) -> bool

Returns true if the stream is finalized.

pub fn is_not_finalized(&self) -> bool

Returns true if the stream is not finalized.

impl Stream<Push>

pub fn init_push(key: &Key) -> Result<(Stream<Push>, Header), ()>

Initializes an Stream using a provided key. Returns the Stream object and a Header, which is needed by the recipient to initialize a corresponding Stream<Pull>. The key will not be needed be required for any subsequent authenticated encryption operations. If you would like to securely generate a key and initialize an Stream at the same time see the new method. Network protocols can leverage the key exchange API in order to get a shared key that can be used to encrypt streams. Similarly, file encryption applications can use the password hashing API to get a key that can be used with the functions below.

pub fn push(
    &mut self,
    m: &[u8],
    ad: Option<&[u8]>,
    tag: Tag
) -> Result<Vec<u8>, ()>

All data (including optional fields) is authenticated. Encrypts a message m and its tag. Optionally includes additional data ad, which is not encrypted.

pub fn push_to_vec(
    &mut self,
    m: &[u8],
    ad: Option<&[u8]>,
    tag: Tag,
    out: &mut Vec<u8>
) -> Result<(), ()>

All data (including optional fields) is authenticated. Encrypts a message m and its tag. Optionally includes additional data ad, which is not encrypted.

The encrypted message is written to the out vector, overwriting any existing data there.

pub fn finalize(self, ad: Option<&[u8]>) -> Result<Vec<u8>, ()>

Create a ciphertext for an empty message with the TAG_FINAL added to signal the end of the stream. Since the Stream is not usable after this point, this method consumes the `Stream.

impl Stream<Pull>

pub fn init_pull(header: &Header, key: &Key) -> Result<Stream<Pull>, ()>

Initializes a Stream<Pull> given a secret Key and a Header. The key will not be required any more for subsequent operations. Err(()) is returned if the header is invalid.

pub fn pull(
    &mut self,
    c: &[u8],
    ad: Option<&[u8]>
) -> Result<(Vec<u8>, Tag), ()>

Verifies that c is a valid ciphertext with a correct authentication tag given the internal state of the Stream (ciphertext streams cannot be decrypted out of order for this reason). Also may validate the optional unencrypted additional data ad using the authentication tag attached to c. Finally decrypts the ciphertext and tag, and checks the tag validity. If any authentication fails, the stream has already been finalized, or if the tag byte for some reason does not correspond to a valid Tag, returns Err(()). Otherwise returns the plaintext and the tag. Applications will typically use a while stream.is_not_finalized() loop to authenticate and decrypt a stream of messages.

pub fn pull_to_vec(
    &mut self,
    c: &[u8],
    ad: Option<&[u8]>,
    out: &mut Vec<u8>
) -> Result<Tag, ()>

Verifies that c is a valid ciphertext with a correct authentication tag given the internal state of the Stream (ciphertext streams cannot be decrypted out of order for this reason). Also may validate the optional unencrypted additional data ad using the authentication tag attached to c. Finally decrypts the ciphertext and tag, and checks the tag validity. If any authentication fails, the stream has already been finalized, or if the tag byte for some reason does not correspond to a valid Tag, returns Err(()). Otherwise returns the plaintext and the tag. Applications will typically use a while stream.is_not_finalized() loop to authenticate and decrypt a stream of messages.

The decrypted message is written to the out vector, overwriting any existing data there.