serde_encrypt/traits/
serde_encrypt_public_key.rs

1use crate::encrypt::plain_message_public_key::PlainMessagePublicKey;
2use crate::serialize::TypedSerialized;
3use crate::{EncryptedMessage, Error, ReceiverCombinedKey, SenderCombinedKey};
4use serde::{de::DeserializeOwned, Deserialize, Serialize};
5use serde_encrypt_core::encrypt::plain_message_public_key::PlainMessagePublicKeyCore;
6
7/// Public-key authenticated encryption for serde-serializable types.
8///
9/// # Features
10///
11/// - Safe and bidirectional public-key exchange.
12/// - Message authentication.
13/// - Different cipher-text for the same plain-text to avoid attacks such as statistical analysis of cipher-text.
14///
15/// # Anti-features
16///
17/// - Identity authentication of sender nor receiver.
18///
19/// # Popular use cases
20///
21/// - Shared-key exchange.
22/// - Encryption for relatively small and non-frequent messages (shared-key encryption is faster than public-key).
23///
24/// # Examples
25///
26/// ## Encrypting owned data
27///
28/// See [this example](https://github.com/laysakura/serde-encrypt/blob/main/serde-encrypt/tests/example_serde_encrypt_public_key_owned_data.rs).
29///
30/// ## Encrypting struct with reference fields
31///
32/// See [this example](https://github.com/laysakura/serde-encrypt/blob/main/serde-encrypt/tests/example_serde_encrypt_public_key_struct_with_reference.rs).
33///
34/// # Algorithm
35///
36/// - Public-key exchange: X25519
37/// - Encryption: XChaCha20
38/// - Message authentication: Poly1305 MAC
39pub trait SerdeEncryptPublicKey {
40    /// Serializer implementation
41    type S: TypedSerialized<T = Self>;
42
43    /// Serialize and encrypt.
44    ///
45    /// # Failures
46    ///
47    /// - [SerializationError](serde_encrypt_core::error::ErrorKind::SerializationError) when failed to serialize message.
48    /// - [EncryptionError](serde_encrypt_core::error::ErrorKind::EncryptionError) when failed to encrypt serialized message.
49    fn encrypt(&self, combined_key: &SenderCombinedKey) -> Result<EncryptedMessage, Error>
50    where
51        Self: Serialize,
52    {
53        let serialized = Self::S::serialize(self)?;
54        let plain_msg = PlainMessagePublicKey::new(serialized.into_vec());
55        plain_msg.encrypt(combined_key)
56    }
57
58    /// Decrypt and deserialize into DeserializeOwned type.
59    ///
60    /// # Failures
61    ///
62    /// - [DecryptionError](serde_encrypt_core::error::ErrorKind::DecryptionError) when failed to decrypt message.
63    /// - [DeserializationError](serde_encrypt_core::error::ErrorKind::DeserializationError) when failed to deserialize decrypted message.
64    fn decrypt_owned(
65        encrypted_message: &EncryptedMessage,
66        combined_key: &ReceiverCombinedKey,
67    ) -> Result<Self, Error>
68    where
69        Self: DeserializeOwned,
70    {
71        let serialized = Self::decrypt_ref(encrypted_message, combined_key)?;
72        serialized.deserialize()
73    }
74
75    /// Just decrypts cipher-text. Returned data must be deserialized later.
76    /// Types implementing `serde::Deserialize<'de>` (not `serde::de::DeserializeOwned`) should use
77    /// this function to resolve lifetime.
78    ///
79    /// # Failures
80    ///
81    /// - [DecryptionError](serde_encrypt_core::error::ErrorKind::DecryptionError) when failed to decrypt message.
82    fn decrypt_ref<'de>(
83        encrypted_message: &EncryptedMessage,
84        combined_key: &ReceiverCombinedKey,
85    ) -> Result<Self::S, Error>
86    where
87        Self: Deserialize<'de>,
88    {
89        let plain_msg = PlainMessagePublicKey::decrypt(encrypted_message, combined_key)?;
90        Ok(Self::S::new(plain_msg.into_vec()))
91    }
92}
serde_encrypt/traits/serde_encrypt_public_key.rs

serde_encrypt/traits/
serde_encrypt_public_key.rs
