serde_encrypt/traits/
serde_encrypt_shared_key.rs

1use crate::{
2    encrypt::plain_message_shared_key::PlainMessageSharedKey, serialize::TypedSerialized,
3    shared_key::SharedKey, EncryptedMessage, Error,
4};
5use serde::{de::DeserializeOwned, Deserialize, Serialize};
6use serde_encrypt_core::encrypt::plain_message_shared_key::PlainMessageSharedKeyCore;
7
8/// Shared-key authenticated encryption for serde-serializable types.
9///
10/// # Features
11///
12/// - Message authentication.
13/// - Different cipher-text for the same plain-text to avoid attacks such as statistical analysis of cipher-text.
14/// - Uses small (32-byte) key.
15///
16/// # Anti-features
17///
18/// - Identity authentication of sender nor receiver.
19///
20/// # Popular use cases
21///
22/// Good for both large and small message encryption / decryption.
23///
24/// ## when sender and receiver does not hold shared key yet:
25///
26/// First, message sender or receiver should generate [SharedKey](crate::shared_key::SharedKey).
27///
28/// And then sender or receiver who generated the key should give it to another using safe communication.
29/// [SerdeEncryptPublicKey](crate::traits::SerdeEncryptPublicKey) is recommended for it.
30///
31/// # Examples
32///
33/// ## Encrypting owned data with already-shared key
34///
35/// See [this example](https://github.com/laysakura/serde-encrypt/blob/main/serde-encrypt/tests/example_serde_encrypt_shared_key_owned_data.rs).
36///
37/// ## Generate and exchange shared key and encrypt struct with reference fields
38///
39/// See [this example](https://github.com/laysakura/serde-encrypt/blob/main/serde-encrypt/tests/example_serde_encrypt_shared_key_encryption_with_key_exchange.rs).
40///
41/// # Algorithm
42///
43/// - Encryption: XChaCha20
44/// - Message authentication: Poly1305 MAC
45pub trait SerdeEncryptSharedKey {
46    /// Serializer implementation
47    type S: TypedSerialized<T = Self>;
48
49    /// Serialize and encrypt.
50    ///
51    /// # Failures
52    ///
53    /// - [SerializationError](serde_encrypt_core::error::ErrorKind::SerializationError) when failed to serialize message.
54    /// - [EncryptionError](serde_encrypt_core::error::ErrorKind::EncryptionError) when failed to encrypt serialized message.
55    fn encrypt(&self, shared_key: &SharedKey) -> Result<EncryptedMessage, Error>
56    where
57        Self: Serialize,
58    {
59        let serialized = Self::S::serialize(self)?;
60        let plain_msg = PlainMessageSharedKey::new(serialized.into_vec());
61        plain_msg.encrypt(shared_key)
62    }
63
64    /// Decrypt and deserialize into DeserializeOwned type.
65    ///
66    /// # Failures
67    ///
68    /// - [DecryptionError](serde_encrypt_core::error::ErrorKind::DecryptionError) when failed to decrypt message.
69    /// - [DeserializationError](serde_encrypt_core::error::ErrorKind::DeserializationError) when failed to deserialize decrypted message.
70    fn decrypt_owned(
71        encrypted_message: &EncryptedMessage,
72        shared_key: &SharedKey,
73    ) -> Result<Self, Error>
74    where
75        Self: DeserializeOwned,
76    {
77        let serialized = Self::decrypt_ref(encrypted_message, shared_key)?;
78        serialized.deserialize()
79    }
80
81    /// Just decrypts cipher-text. Returned data must be deserialized later.
82    /// Types implementing `serde::Deserialize<'de>` (not `serde::de::DeserializeOwned`) should use
83    /// this function to resolve lifetime.
84    ///
85    /// # Failures
86    ///
87    /// - [DecryptionError](serde_encrypt_core::error::ErrorKind::DecryptionError) when failed to decrypt message.
88    fn decrypt_ref<'de>(
89        encrypted_message: &EncryptedMessage,
90        shared_key: &SharedKey,
91    ) -> Result<Self::S, Error>
92    where
93        Self: Deserialize<'de>,
94    {
95        let plain_msg = PlainMessageSharedKey::decrypt(encrypted_message, shared_key)?;
96        Ok(Self::S::new(plain_msg.into_vec()))
97    }
98}
serde_encrypt/traits/serde_encrypt_shared_key.rs

serde_encrypt/traits/
serde_encrypt_shared_key.rs
