# HG changeset patch
# User Goffi <goffi@goffi.org>
# Date 1740731015 -3600
# Node ID 382dc6e62b6eab5f8dc7c3f5540384e73e805040
# Parent  6a0a081485b8e35e8a8e2479308e59a5ba59bd36
doc (components, encryption): add documentation on autocrypt for client and email gateway:

fix 456

diff -r 6a0a081485b8 -r 382dc6e62b6e doc/components.rst
--- a/doc/components.rst	Fri Feb 28 09:23:35 2025 +0100
+++ b/doc/components.rst	Fri Feb 28 09:23:35 2025 +0100
@@ -977,6 +977,18 @@
 (in technical terms, it's by telling it to use MIME and OpenPGP) before sending it to the
 gateway. This only works with clients implementing this specification.
 
+Autocrypt
+~~~~~~~~~
+
+The gateway relays "Autocrypt" headers, which is a way to share public keys without
+relaying them to a key server. In layman's terms, it's a way to exchange encryption data
+to be able to encrypt messages automatically. However, while better than not using
+end-to-end encryption, this method is not as secure as proper management of encryption
+keys and authentication of the peer we're talking to.
+
+Please refer to `Wikipedia's Autocrypt page`_ for more details, in particular on its
+security model
+
 
 .. note::
 
@@ -989,4 +1001,5 @@
 .. _XEP-0106 (JID Escaping): https://xmpp.org/extensions/xep-0106.html
 .. _XEP-0131 (Stanza Headers and Internet Metadata): https://xmpp.org/extensions/xep-0131.html
 .. _XEP-0498 (Pubsub File Sharing): https://xmpp.org/extensions/xep-0498.html
+.. _Wikipedia's Autocrypt page: https://en.wikipedia.org/wiki/Autocrypt
 
diff -r 6a0a081485b8 -r 382dc6e62b6e doc/encryption.rst
--- a/doc/encryption.rst	Fri Feb 28 09:23:35 2025 +0100
+++ b/doc/encryption.rst	Fri Feb 28 09:23:35 2025 +0100
@@ -133,3 +133,13 @@
 
 .. _XEP-0476: Pubsub Signing: OpenPGP Profile: https://xmpp.org/extensions/xep-0476.html
 
+E2EE with Email Gateway
+=======================
+
+For compatible gateways, Libervia supports "Relayed" encryption, which is a method for using end-to-end encryption (E2EE). This feature is currently experimental and only works for emails.
+
+If no key is known for an email recipient, Libervia uses Autocrypt. Autocrypt automatically exchanges encryption keys to enable what's called "opportunistic" encryption. While the security isn't as robust as proper key management and peer authentication, it still offers better protection than having no E2EE at all. Autocrypt is only used when a recipient’s key is not known by other, more secure means.
+
+For more information about Autocrypt and its security model, please refer to `Wikipedia's Autocrypt page`_.
+
+.. _Wikipedia's Autocrypt page: https://en.wikipedia.org/wiki/Autocrypt