tink_core/
streamingaead.rs

1// Copyright 2020 The Tink-Rust Authors
2//
3// Licensed under the Apache License, Version 2.0 (the "License");
4// you may not use this file except in compliance with the License.
5// You may obtain a copy of the License at
6//
7//      http://www.apache.org/licenses/LICENSE-2.0
8//
9// Unless required by applicable law or agreed to in writing, software
10// distributed under the License is distributed on an "AS IS" BASIS,
11// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12// See the License for the specific language governing permissions and
13// limitations under the License.
14//
15////////////////////////////////////////////////////////////////////////////////
16
17//! Streaming authenticated encryption with associated data.
18
19/// `StreamingAead` is an interface for streaming authenticated encryption with associated data.
20///
21/// Streaming encryption is typically used for encrypting large plaintexts such as large files.
22/// Tink may eventually contain multiple interfaces for streaming encryption depending on the
23/// supported properties. This interface supports a streaming interface for symmetric encryption
24/// with authentication. The underlying encryption modes are selected so that partial plaintext can
25/// be obtained fast by decrypting and authenticating just a part of the ciphertext.
26///
27/// Instances of `StreamingAead` must follow the OAE2 definition as proposed in the paper "Online
28/// Authenticated-Encryption and its Nonce-Reuse Misuse-Resistance" by [Hoang, Reyhanitabar, Rogaway
29/// and Vizár](https://eprint.iacr.org/2015/189.pdf)
30pub trait StreamingAead: StreamingAeadBoxClone {
31    /// Return a wrapper around an underlying `std::io::Write`, such that any write-operation
32    /// via the wrapper results in AEAD-encryption of the written data, using `aad`
33    /// as associated authenticated data. The associated data is not included in the ciphertext
34    /// and has to be passed in as parameter for decryption.
35    fn new_encrypting_writer(
36        &self,
37        w: Box<dyn std::io::Write>,
38        aad: &[u8],
39    ) -> Result<Box<dyn EncryptingWrite>, crate::TinkError>;
40
41    /// Return a wrapper around an underlying `std::io::Read`, such that any read-operation
42    /// via the wrapper results in AEAD-decryption of the underlying ciphertext,
43    /// using `aad` as associated authenticated data.
44    fn new_decrypting_reader(
45        &self,
46        r: Box<dyn std::io::Read>,
47        aad: &[u8],
48    ) -> Result<Box<dyn std::io::Read>, crate::TinkError>;
49}
50
51/// Trait for an object that writes encrypted data.  Users must call `close()` to finish.
52pub trait EncryptingWrite: std::io::Write {
53    /// Close the stream, writing any final buffered data.  Any operation
54    /// on the stream after this will fail.
55    fn close(&mut self) -> Result<(), crate::TinkError>;
56}
57
58/// Trait bound to indicate that primitive trait objects should support cloning
59/// themselves as trait objects.
60pub trait StreamingAeadBoxClone {
61    fn box_clone(&self) -> Box<dyn StreamingAead>;
62}
63
64/// Default implementation of the box-clone trait bound for any underlying
65/// concrete type that implements [`Clone`].
66impl<T> StreamingAeadBoxClone for T
67where
68    T: 'static + StreamingAead + Clone,
69{
70    fn box_clone(&self) -> Box<dyn StreamingAead> {
71        Box::new(self.clone())
72    }
73}
tink_core/streamingaead.rs

tink_core/
streamingaead.rs
