deltachat/
pgp.rs

1//! OpenPGP helper module using [rPGP facilities](https://github.com/rpgp/rpgp).
2
3use std::collections::{BTreeMap, HashSet};
4use std::io::{BufRead, Cursor};
5
6use anyhow::{Context as _, Result};
7use chrono::SubsecRound;
8use deltachat_contact_tools::EmailAddress;
9use pgp::armor::BlockType;
10use pgp::composed::{
11    ArmorOptions, Deserializable, KeyType as PgpKeyType, Message, MessageBuilder,
12    SecretKeyParamsBuilder, SignedPublicKey, SignedPublicSubKey, SignedSecretKey,
13    StandaloneSignature, SubkeyParamsBuilder, TheRing,
14};
15use pgp::crypto::ecc_curve::ECCCurve;
16use pgp::crypto::hash::HashAlgorithm;
17use pgp::crypto::sym::SymmetricKeyAlgorithm;
18use pgp::packet::{SignatureConfig, SignatureType, Subpacket, SubpacketData};
19use pgp::types::{CompressionAlgorithm, KeyDetails, Password, PublicKeyTrait, StringToKey};
20use rand::thread_rng;
21use tokio::runtime::Handle;
22
23use crate::key::{DcKey, Fingerprint};
24
25#[cfg(test)]
26pub(crate) const HEADER_AUTOCRYPT: &str = "autocrypt-prefer-encrypt";
27
28pub const HEADER_SETUPCODE: &str = "passphrase-begin";
29
30/// Preferred symmetric encryption algorithm.
31const SYMMETRIC_KEY_ALGORITHM: SymmetricKeyAlgorithm = SymmetricKeyAlgorithm::AES128;
32
33/// Preferred cryptographic hash.
34const HASH_ALGORITHM: HashAlgorithm = HashAlgorithm::Sha256;
35
36/// Split data from PGP Armored Data as defined in <https://tools.ietf.org/html/rfc4880#section-6.2>.
37///
38/// Returns (type, headers, base64 encoded body).
39pub fn split_armored_data(buf: &[u8]) -> Result<(BlockType, BTreeMap<String, String>, Vec<u8>)> {
40    use std::io::Read;
41
42    let cursor = Cursor::new(buf);
43    let mut dearmor = pgp::armor::Dearmor::new(cursor);
44
45    let mut bytes = Vec::with_capacity(buf.len());
46
47    dearmor.read_to_end(&mut bytes)?;
48    let typ = dearmor.typ.context("failed to parse type")?;
49
50    // normalize headers
51    let headers = dearmor
52        .headers
53        .into_iter()
54        .map(|(key, values)| {
55            (
56                key.trim().to_lowercase(),
57                values
58                    .last()
59                    .map_or_else(String::new, |s| s.trim().to_string()),
60            )
61        })
62        .collect();
63
64    Ok((typ, headers, bytes))
65}
66
67/// A PGP keypair.
68///
69/// This has it's own struct to be able to keep the public and secret
70/// keys together as they are one unit.
71#[derive(Debug, Clone, Eq, PartialEq)]
72pub struct KeyPair {
73    /// Public key.
74    pub public: SignedPublicKey,
75
76    /// Secret key.
77    pub secret: SignedSecretKey,
78}
79
80impl KeyPair {
81    /// Creates new keypair from a secret key.
82    ///
83    /// Public key is split off the secret key.
84    pub fn new(secret: SignedSecretKey) -> Result<Self> {
85        use crate::key::DcSecretKey;
86
87        let public = secret.split_public_key()?;
88        Ok(Self { public, secret })
89    }
90}
91
92/// Create a new key pair.
93///
94/// Both secret and public key consist of signing primary key and encryption subkey
95/// as [described in the Autocrypt standard](https://autocrypt.org/level1.html#openpgp-based-key-data).
96pub(crate) fn create_keypair(addr: EmailAddress) -> Result<KeyPair> {
97    let signing_key_type = PgpKeyType::Ed25519Legacy;
98    let encryption_key_type = PgpKeyType::ECDH(ECCCurve::Curve25519);
99
100    let user_id = format!("<{addr}>");
101    let key_params = SecretKeyParamsBuilder::default()
102        .key_type(signing_key_type)
103        .can_certify(true)
104        .can_sign(true)
105        .primary_user_id(user_id)
106        .passphrase(None)
107        .preferred_symmetric_algorithms(smallvec![
108            SymmetricKeyAlgorithm::AES256,
109            SymmetricKeyAlgorithm::AES192,
110            SymmetricKeyAlgorithm::AES128,
111        ])
112        .preferred_hash_algorithms(smallvec![
113            HashAlgorithm::Sha256,
114            HashAlgorithm::Sha384,
115            HashAlgorithm::Sha512,
116            HashAlgorithm::Sha224,
117        ])
118        .preferred_compression_algorithms(smallvec![
119            CompressionAlgorithm::ZLIB,
120            CompressionAlgorithm::ZIP,
121        ])
122        .subkey(
123            SubkeyParamsBuilder::default()
124                .key_type(encryption_key_type)
125                .can_encrypt(true)
126                .passphrase(None)
127                .build()
128                .context("failed to build subkey parameters")?,
129        )
130        .build()
131        .context("failed to build key parameters")?;
132
133    let mut rng = thread_rng();
134    let secret_key = key_params
135        .generate(&mut rng)
136        .context("failed to generate the key")?
137        .sign(&mut rng, &Password::empty())
138        .context("failed to sign secret key")?;
139    secret_key
140        .verify()
141        .context("invalid secret key generated")?;
142
143    let key_pair = KeyPair::new(secret_key)?;
144    key_pair
145        .public
146        .verify()
147        .context("invalid public key generated")?;
148    Ok(key_pair)
149}
150
151/// Selects a subkey of the public key to use for encryption.
152///
153/// Returns `None` if the public key cannot be used for encryption.
154///
155/// TODO: take key flags and expiration dates into account
156fn select_pk_for_encryption(key: &SignedPublicKey) -> Option<&SignedPublicSubKey> {
157    key.public_subkeys
158        .iter()
159        .find(|subkey| subkey.is_encryption_key())
160}
161
162/// Encrypts `plain` text using `public_keys_for_encryption`
163/// and signs it using `private_key_for_signing`.
164pub async fn pk_encrypt(
165    plain: Vec<u8>,
166    public_keys_for_encryption: Vec<SignedPublicKey>,
167    private_key_for_signing: Option<SignedSecretKey>,
168    compress: bool,
169) -> Result<String> {
170    Handle::current()
171        .spawn_blocking(move || {
172            let mut rng = thread_rng();
173
174            let pkeys = public_keys_for_encryption
175                .iter()
176                .filter_map(select_pk_for_encryption);
177
178            let msg = MessageBuilder::from_bytes("", plain);
179            let mut msg = msg.seipd_v1(&mut rng, SYMMETRIC_KEY_ALGORITHM);
180            for pkey in pkeys {
181                msg.encrypt_to_key(&mut rng, &pkey)?;
182            }
183
184            if let Some(ref skey) = private_key_for_signing {
185                msg.sign(&**skey, Password::empty(), HASH_ALGORITHM);
186                if compress {
187                    msg.compression(CompressionAlgorithm::ZLIB);
188                }
189            }
190
191            let encoded_msg = msg.to_armored_string(&mut rng, Default::default())?;
192
193            Ok(encoded_msg)
194        })
195        .await?
196}
197
198/// Produces a detached signature for `plain` text using `private_key_for_signing`.
199pub fn pk_calc_signature(
200    plain: Vec<u8>,
201    private_key_for_signing: &SignedSecretKey,
202) -> Result<String> {
203    let rng = thread_rng();
204
205    let mut config = SignatureConfig::from_key(
206        rng,
207        &private_key_for_signing.primary_key,
208        SignatureType::Binary,
209    )?;
210
211    config.hashed_subpackets = vec![
212        Subpacket::regular(SubpacketData::IssuerFingerprint(
213            private_key_for_signing.fingerprint(),
214        ))?,
215        Subpacket::critical(SubpacketData::SignatureCreationTime(
216            chrono::Utc::now().trunc_subsecs(0),
217        ))?,
218    ];
219    config.unhashed_subpackets = vec![Subpacket::regular(SubpacketData::Issuer(
220        private_key_for_signing.key_id(),
221    ))?];
222
223    let signature = config.sign(
224        &private_key_for_signing.primary_key,
225        &Password::empty(),
226        plain.as_slice(),
227    )?;
228
229    let sig = StandaloneSignature::new(signature);
230
231    Ok(sig.to_armored_string(ArmorOptions::default())?)
232}
233
234/// Decrypts the message with keys from the private key keyring.
235///
236/// Receiver private keys are provided in
237/// `private_keys_for_decryption`.
238pub fn pk_decrypt(
239    ctext: Vec<u8>,
240    private_keys_for_decryption: &[SignedSecretKey],
241) -> Result<pgp::composed::Message<'static>> {
242    let cursor = Cursor::new(ctext);
243    let (msg, _headers) = Message::from_armor(cursor)?;
244
245    let skeys: Vec<&SignedSecretKey> = private_keys_for_decryption.iter().collect();
246    let empty_pw = Password::empty();
247
248    let ring = TheRing {
249        secret_keys: skeys,
250        key_passwords: vec![&empty_pw],
251        message_password: vec![],
252        session_keys: vec![],
253        allow_legacy: false,
254    };
255    let (msg, ring_result) = msg.decrypt_the_ring(ring, true)?;
256    anyhow::ensure!(
257        !ring_result.secret_keys.is_empty(),
258        "decryption failed, no matching secret keys"
259    );
260
261    // remove one layer of compression
262    let msg = msg.decompress()?;
263
264    Ok(msg)
265}
266
267/// Returns fingerprints
268/// of all keys from the `public_keys_for_validation` keyring that
269/// have valid signatures there.
270///
271/// If the message is wrongly signed, HashSet will be empty.
272pub fn valid_signature_fingerprints(
273    msg: &pgp::composed::Message,
274    public_keys_for_validation: &[SignedPublicKey],
275) -> Result<HashSet<Fingerprint>> {
276    let mut ret_signature_fingerprints: HashSet<Fingerprint> = Default::default();
277    if msg.is_signed() {
278        for pkey in public_keys_for_validation {
279            if msg.verify(&pkey.primary_key).is_ok() {
280                let fp = pkey.dc_fingerprint();
281                ret_signature_fingerprints.insert(fp);
282            }
283        }
284    }
285    Ok(ret_signature_fingerprints)
286}
287
288/// Validates detached signature.
289pub fn pk_validate(
290    content: &[u8],
291    signature: &[u8],
292    public_keys_for_validation: &[SignedPublicKey],
293) -> Result<HashSet<Fingerprint>> {
294    let mut ret: HashSet<Fingerprint> = Default::default();
295
296    let standalone_signature = StandaloneSignature::from_armor_single(Cursor::new(signature))?.0;
297
298    for pkey in public_keys_for_validation {
299        if standalone_signature.verify(pkey, content).is_ok() {
300            let fp = pkey.dc_fingerprint();
301            ret.insert(fp);
302        }
303    }
304    Ok(ret)
305}
306
307/// Symmetric encryption.
308pub async fn symm_encrypt(passphrase: &str, plain: Vec<u8>) -> Result<String> {
309    let passphrase = Password::from(passphrase.to_string());
310
311    tokio::task::spawn_blocking(move || {
312        let mut rng = thread_rng();
313        let s2k = StringToKey::new_default(&mut rng);
314        let builder = MessageBuilder::from_bytes("", plain);
315        let mut builder = builder.seipd_v1(&mut rng, SYMMETRIC_KEY_ALGORITHM);
316        builder.encrypt_with_password(s2k, &passphrase)?;
317
318        let encoded_msg = builder.to_armored_string(&mut rng, Default::default())?;
319
320        Ok(encoded_msg)
321    })
322    .await?
323}
324
325/// Symmetric decryption.
326pub async fn symm_decrypt<T: BufRead + std::fmt::Debug + 'static + Send>(
327    passphrase: &str,
328    ctext: T,
329) -> Result<Vec<u8>> {
330    let passphrase = passphrase.to_string();
331    tokio::task::spawn_blocking(move || {
332        let (enc_msg, _) = Message::from_armor(ctext)?;
333        let password = Password::from(passphrase);
334
335        let msg = enc_msg.decrypt_with_password(&password)?;
336        let res = msg.decompress()?.as_data_vec()?;
337        Ok(res)
338    })
339    .await?
340}
341
342#[cfg(test)]
343mod tests {
344    use std::sync::LazyLock;
345    use tokio::sync::OnceCell;
346
347    use super::*;
348    use crate::test_utils::{alice_keypair, bob_keypair};
349
350    fn pk_decrypt_and_validate<'a>(
351        ctext: &'a [u8],
352        private_keys_for_decryption: &'a [SignedSecretKey],
353        public_keys_for_validation: &[SignedPublicKey],
354    ) -> Result<(
355        pgp::composed::Message<'static>,
356        HashSet<Fingerprint>,
357        Vec<u8>,
358    )> {
359        let mut msg = pk_decrypt(ctext.to_vec(), private_keys_for_decryption)?;
360        let content = msg.as_data_vec()?;
361        let ret_signature_fingerprints =
362            valid_signature_fingerprints(&msg, public_keys_for_validation)?;
363
364        Ok((msg, ret_signature_fingerprints, content))
365    }
366
367    #[test]
368    fn test_split_armored_data_1() {
369        let (typ, _headers, base64) = split_armored_data(
370            b"-----BEGIN PGP MESSAGE-----\nNoVal:\n\naGVsbG8gd29ybGQ=\n-----END PGP MESSAGE-----",
371        )
372        .unwrap();
373
374        assert_eq!(typ, BlockType::Message);
375        assert!(!base64.is_empty());
376        assert_eq!(
377            std::string::String::from_utf8(base64).unwrap(),
378            "hello world"
379        );
380    }
381
382    #[test]
383    fn test_split_armored_data_2() {
384        let (typ, headers, base64) = split_armored_data(
385            b"-----BEGIN PGP PRIVATE KEY BLOCK-----\nAutocrypt-Prefer-Encrypt: mutual \n\naGVsbG8gd29ybGQ=\n-----END PGP PRIVATE KEY BLOCK-----"
386        )
387            .unwrap();
388
389        assert_eq!(typ, BlockType::PrivateKey);
390        assert!(!base64.is_empty());
391        assert_eq!(headers.get(HEADER_AUTOCRYPT), Some(&"mutual".to_string()));
392    }
393
394    #[test]
395    fn test_create_keypair() {
396        let keypair0 = create_keypair(EmailAddress::new("foo@bar.de").unwrap()).unwrap();
397        let keypair1 = create_keypair(EmailAddress::new("two@zwo.de").unwrap()).unwrap();
398        assert_ne!(keypair0.public, keypair1.public);
399    }
400
401    /// [SignedSecretKey] and [SignedPublicKey] objects
402    /// to use in tests.
403    struct TestKeys {
404        alice_secret: SignedSecretKey,
405        alice_public: SignedPublicKey,
406        bob_secret: SignedSecretKey,
407        bob_public: SignedPublicKey,
408    }
409
410    impl TestKeys {
411        fn new() -> TestKeys {
412            let alice = alice_keypair();
413            let bob = bob_keypair();
414            TestKeys {
415                alice_secret: alice.secret.clone(),
416                alice_public: alice.public,
417                bob_secret: bob.secret.clone(),
418                bob_public: bob.public,
419            }
420        }
421    }
422
423    /// The original text of [CTEXT_SIGNED]
424    static CLEARTEXT: &[u8] = b"This is a test";
425
426    /// Initialised [TestKeys] for tests.
427    static KEYS: LazyLock<TestKeys> = LazyLock::new(TestKeys::new);
428
429    static CTEXT_SIGNED: OnceCell<String> = OnceCell::const_new();
430    static CTEXT_UNSIGNED: OnceCell<String> = OnceCell::const_new();
431
432    /// A ciphertext encrypted to Alice & Bob, signed by Alice.
433    async fn ctext_signed() -> &'static String {
434        CTEXT_SIGNED
435            .get_or_init(|| async {
436                let keyring = vec![KEYS.alice_public.clone(), KEYS.bob_public.clone()];
437                let compress = true;
438
439                pk_encrypt(
440                    CLEARTEXT.to_vec(),
441                    keyring,
442                    Some(KEYS.alice_secret.clone()),
443                    compress,
444                )
445                .await
446                .unwrap()
447            })
448            .await
449    }
450
451    /// A ciphertext encrypted to Alice & Bob, not signed.
452    async fn ctext_unsigned() -> &'static String {
453        CTEXT_UNSIGNED
454            .get_or_init(|| async {
455                let keyring = vec![KEYS.alice_public.clone(), KEYS.bob_public.clone()];
456                let compress = true;
457
458                pk_encrypt(CLEARTEXT.to_vec(), keyring, None, compress)
459                    .await
460                    .unwrap()
461            })
462            .await
463    }
464
465    #[tokio::test(flavor = "multi_thread", worker_threads = 2)]
466    async fn test_encrypt_signed() {
467        assert!(!ctext_signed().await.is_empty());
468        assert!(ctext_signed()
469            .await
470            .starts_with("-----BEGIN PGP MESSAGE-----"));
471    }
472
473    #[tokio::test(flavor = "multi_thread", worker_threads = 2)]
474    async fn test_encrypt_unsigned() {
475        assert!(!ctext_unsigned().await.is_empty());
476        assert!(ctext_unsigned()
477            .await
478            .starts_with("-----BEGIN PGP MESSAGE-----"));
479    }
480
481    #[tokio::test(flavor = "multi_thread", worker_threads = 2)]
482    async fn test_decrypt_singed() {
483        // Check decrypting as Alice
484        let decrypt_keyring = vec![KEYS.alice_secret.clone()];
485        let sig_check_keyring = vec![KEYS.alice_public.clone()];
486        let (_msg, valid_signatures, content) = pk_decrypt_and_validate(
487            ctext_signed().await.as_bytes(),
488            &decrypt_keyring,
489            &sig_check_keyring,
490        )
491        .unwrap();
492        assert_eq!(content, CLEARTEXT);
493        assert_eq!(valid_signatures.len(), 1);
494
495        // Check decrypting as Bob
496        let decrypt_keyring = vec![KEYS.bob_secret.clone()];
497        let sig_check_keyring = vec![KEYS.alice_public.clone()];
498        let (_msg, valid_signatures, content) = pk_decrypt_and_validate(
499            ctext_signed().await.as_bytes(),
500            &decrypt_keyring,
501            &sig_check_keyring,
502        )
503        .unwrap();
504        assert_eq!(content, CLEARTEXT);
505        assert_eq!(valid_signatures.len(), 1);
506    }
507
508    #[tokio::test(flavor = "multi_thread", worker_threads = 2)]
509    async fn test_decrypt_no_sig_check() {
510        let keyring = vec![KEYS.alice_secret.clone()];
511        let (_msg, valid_signatures, content) =
512            pk_decrypt_and_validate(ctext_signed().await.as_bytes(), &keyring, &[]).unwrap();
513        assert_eq!(content, CLEARTEXT);
514        assert_eq!(valid_signatures.len(), 0);
515    }
516
517    #[tokio::test(flavor = "multi_thread", worker_threads = 2)]
518    async fn test_decrypt_signed_no_key() {
519        // The validation does not have the public key of the signer.
520        let decrypt_keyring = vec![KEYS.bob_secret.clone()];
521        let sig_check_keyring = vec![KEYS.bob_public.clone()];
522        let (_msg, valid_signatures, content) = pk_decrypt_and_validate(
523            ctext_signed().await.as_bytes(),
524            &decrypt_keyring,
525            &sig_check_keyring,
526        )
527        .unwrap();
528        assert_eq!(content, CLEARTEXT);
529        assert_eq!(valid_signatures.len(), 0);
530    }
531
532    #[tokio::test(flavor = "multi_thread", worker_threads = 2)]
533    async fn test_decrypt_unsigned() {
534        let decrypt_keyring = vec![KEYS.bob_secret.clone()];
535        let (_msg, valid_signatures, content) =
536            pk_decrypt_and_validate(ctext_unsigned().await.as_bytes(), &decrypt_keyring, &[])
537                .unwrap();
538        assert_eq!(content, CLEARTEXT);
539        assert_eq!(valid_signatures.len(), 0);
540    }
541}