Make signer optional for encrypt

Signed-off-by: Wiktor Kwapisiewicz <[email protected]>

NEXT.md

@@ -3,12 +3,16 @@
 v0.1.23
 
 New:
+  - `decrypt` accepts a function for supplying certificates for signature verification ([#22])
+  - the result of `decrypt` and `verify` exposes `valid_sigs` for retrieving a list of valid signatures ([#22])
 
 Changed:
-  - `verify` now accepts a callback for supplying signing certificates ([#20])
+  - `verify` accepts a callback for supplying signing certificates ([#20])
+  - `encrypt` does not require the `signer` argument ([#22])
 
 Removed:
   - `Store` and the Cert-D has been removed ([#20]) due to confusing semantics
 
 [#20]: https://github.com/wiktor-k/pysequoia/pull/20
+[#22]: https://github.com/wiktor-k/pysequoia/pull/22
 ### git tag --edit -s -F NEXT.md v...

README.md

@@ -102,6 +102,7 @@ signing_key = Cert.from_file("signing-key.asc")
 signed = sign(s.secrets.signer(), "data to be signed".encode("utf8"))
 
 def get_certs(key_ids):
+  # key_ids is an array of required signing keys
   print(f"For verification, we need these keys: {key_ids}")
   return [signing_key]
 
@@ -114,6 +115,10 @@ assert result.valid_sigs[0].certificate == "afcf5405e8f49dbcd5dc548a86375b854b86
 assert result.valid_sigs[0].signing_key == "afcf5405e8f49dbcd5dc548a86375b854b86acf9"
 ```
 
+The function that returns certificates (here `get_certs`) may return more certificates than necessary.
+
+`verify` succeeds if *at least one* signature is correct. If you need more advanced policies they can be implemented by inspecting the `valid_sigs` property.
+
 ### encrypt
 
 Signs and encrypts a string to one or more recipients:
@@ -128,9 +133,31 @@ encrypted = encrypt(signer = s.secrets.signer("hunter22"), recipients = [r], byt
 print(f"Encrypted data: {encrypted}")
 ```
 
+The `signer` argument is optional and when omitted the function will return an unsigned (but encrypted) message.
+
 ### decrypt
 
-Decrypts data:
+Decrypts plain data:
+
+```python
+from pysequoia import decrypt
+
+sender = Cert.from_file("no-passwd.pgp")
+receiver = Cert.from_file("passwd.pgp")
+
+content = "Red Green Blue"
+
+encrypted = encrypt(recipients = [receiver], bytes = content.encode("utf8"))
+
+decrypted = decrypt(decryptor = receiver.secrets.decryptor("hunter22"), bytes = encrypted)
+
+assert content == decrypted.bytes.decode("utf8");
+
+# this message did not contain any valid signatures
+assert len(decrypted.valid_sigs) == 0
+```
+
+Decrypt can also verify signatures while decrypting:
 
 ```python
 from pysequoia import decrypt
@@ -149,12 +176,14 @@ def get_certs(key_ids):
 decrypted = decrypt(decryptor = receiver.secrets.decryptor("hunter22"), bytes = encrypted, store = get_certs)
 
 assert content == decrypted.bytes.decode("utf8");
-print(decrypted.valid_sigs)
+
 # let's check the valid signature's certificate and signing subkey fingerprints
 assert decrypted.valid_sigs[0].certificate == sender.fingerprint
 assert decrypted.valid_sigs[0].signing_key == sender.fingerprint
 ```
 
+Here, the same remarks as to [`verify`](#verify) also apply.
+
 ## Certificates
 
 The `Cert` class represents one OpenPGP certificate (commonly called a

src/encrypt.rs

@@ -13,9 +13,9 @@ use crate::signer::PySigner;
 
 #[pyfunction]
 pub fn encrypt(
-    signer: PySigner,
     recipients: Vec<PyRef<Cert>>,
     bytes: &[u8],
+    signer: Option<PySigner>,
 ) -> PyResult<Cow<'static, [u8]>> {
     let mode = KeyFlags::empty()
         .set_storage_encryption()
@@ -66,7 +66,7 @@ pub fn encrypt(
 
     let message = Armorer::new(message).build()?;
 
-    let message = Encryptor::for_recipients(
+    let mut message = Encryptor::for_recipients(
         message,
         recipient_keys
             .iter()
@@ -75,8 +75,9 @@ pub fn encrypt(
     .build()
     .context("Failed to create encryptor")?;
 
-    let message = Signer::new(message, signer).build()?;
-
+    if let Some(signer) = signer {
+        message = Signer::new(message, signer).build()?;
+    }
     let mut message = LiteralWriter::new(message)
         .build()
         .context("Failed to create literal writer")?;