tink_core/
hybrid_encrypt.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//! Hybrid encryption.
18
19/// `HybridEncrypt` is the interface for hybrid encryption.
20///
21/// Hybrid Encryption combines the efficiency of symmetric encryption with the convenience of
22/// public-key encryption: to encrypt a message a fresh symmetric key is generated and used to
23/// encrypt the actual plaintext data, while the recipient’s public key is used to encrypt the
24/// symmetric key only, and the final ciphertext consists of the symmetric ciphertext and the
25/// encrypted symmetric key.
26///
27/// ## WARNING
28///
29/// Hybrid Encryption does not provide authenticity, that is the recipient of an encrypted message
30/// does not know the identity of the sender. Similar to general public-key encryption schemes the
31/// security goal of Hybrid Encryption is to provide privacy only. In other words, Hybrid Encryption
32/// is secure if and only if the recipient can accept anonymous messages or can rely on other
33/// mechanisms to authenticate the sender.
34///
35/// ## Security guarantees
36///
37/// The functionality of Hybrid Encryption is represented as a pair of primitives (traits):
38/// `HybridEncrypt` for encryption of data, and [`crate::HybridDecrypt`] for decryption.
39/// Implementations of these traits are secure against adaptive chosen ciphertext attacks. In
40/// addition to plaintext the encryption takes an extra parameter `context_info`, which
41/// usually is public data implicit from the context, but should be bound to the resulting
42/// ciphertext, i.e. the ciphertext allows for checking the integrity of `context_info` (but
43/// there are no guarantees wrt. the secrecy or authenticity of `context_info`).
44///
45/// `context_info` can be empty, but to ensure the correct decryption of a ciphertext
46/// the same value must be provided for the decryption operation as was used during encryption (cf.
47/// [`crate::HybridDecrypt`]).
48///
49/// A concrete implementation of this trait can implement the binding of contextInfo to
50/// the ciphertext in various ways, for example:
51///
52/// - use `context_info` as "associated data"-input for the employed AEAD symmetric encryption (cf.
53///   [RFC 5116](ttps://tools.ietf.org/html/rfc5116)).
54/// - use `context_info` as "CtxInfo"-input for HKDF (if the implementation uses HKDF as key
55///   derivation function, cf. [RFC 5869](https://tools.ietf.org/html/rfc5869)).
56pub trait HybridEncrypt: HybridEncryptBoxClone {
57    /// Encrypt `plaintext` binding `context_info` to the resulting
58    /// ciphertext. Returns resulting ciphertext.
59    fn encrypt(&self, plaintext: &[u8], context_info: &[u8]) -> Result<Vec<u8>, crate::TinkError>;
60}
61
62/// Trait bound to indicate that primitive trait objects should support cloning
63/// themselves as trait objects.
64pub trait HybridEncryptBoxClone {
65    fn box_clone(&self) -> Box<dyn HybridEncrypt>;
66}
67
68/// Default implementation of the box-clone trait bound for any underlying
69/// concrete type that implements [`Clone`].
70impl<T> HybridEncryptBoxClone for T
71where
72    T: 'static + HybridEncrypt + Clone,
73{
74    fn box_clone(&self) -> Box<dyn HybridEncrypt> {
75        Box::new(self.clone())
76    }
77}
tink_core/hybrid_encrypt.rs

tink_core/
hybrid_encrypt.rs
