# HG changeset patch
# User Goffi <goffi@goffi.org>
# Date 1667220612 -3600
# Node ID c4418949aa3735c9674a136e112ed9bfb2f7ca94
# Parent  5e3b983ab2c65e41b1666a3704b8c698a9b8989a
doc (encryption, cli): document Pubsub Targeted Encryption:

a small section has been added to `encryption` to explain the difference with OXPS, and
the `--encrypt-for` arguments are explained.

fix 382

diff -r 5e3b983ab2c6 -r c4418949aa37 doc/conf.py
--- a/doc/conf.py	Mon Oct 31 13:48:31 2022 +0100
+++ b/doc/conf.py	Mon Oct 31 13:50:12 2022 +0100
@@ -48,6 +48,11 @@
   share secrets with :ref:`libervia-cli_pubsub_secret`. Please read
   :ref:`pubsub-encryption` for more details.
 
+.. |pte_arg| replace::
+  You can encrypt a single item to targeted entities with the ``--encrypt-for`` flag (not
+  to be confused with ``--encrypt`` which is used when a whole node is encrypted). Please
+  read :ref:`pubsub-encryption` for more details.
+
 .. |sign_arg| replace::
   To cryptographically sign an item, you can use the ``-X, --sign`` flag (a mnemonic way
   to remember the short option is to think of a cross made as a signature on a document).
diff -r 5e3b983ab2c6 -r c4418949aa37 doc/encryption.rst
--- a/doc/encryption.rst	Mon Oct 31 13:48:31 2022 +0100
+++ b/doc/encryption.rst	Mon Oct 31 13:50:12 2022 +0100
@@ -92,6 +92,26 @@
 
 .. _OpenPGP: https://en.wikipedia.org/wiki/Pretty_Good_Privacy#OpenPGP
 
+Pubsub Targeted Encryption
+==========================
+
+It is also possible to encrypt a single pubsub item for a restricted set of users. This is
+different from the pubsub encryption explained above, as if you want to encrypt for a
+different set of users, you need to re-encrypt all concerned items, so this is more
+adapted for use cases when you only want to encrypt a few items in a pubsub node.
+
+On the other hand, you have all the properties of the algorithm used (for now, only OMEMO
+2 is supported), which means that you can have `Perfect Forward Secrecy`_ for algorithms
+supporting it (it's the case for OMEMO.)
+
+.. note::
+
+   Pubsub Targeted Encryption(PTE) specification is not currently an official XEP (XMPP
+   Extension Protocol), it is about to be examinated by "XMPP council". This documentation
+   will be updated with the evolution of the situation.
+
+.. _Perfect Forward Secrecy: https://en.wikipedia.org/wiki/Forward_secrecy
+
 Pubsub Signature
 ================
 
@@ -124,4 +144,3 @@
 .. _"publisher" attribute: https://xmpp.org/extensions/xep-0060.html#publisher-publish-success-publisher
 
 .. _Pubsub Signing protoXEP: https://github.com/xsf/xeps/pull/1228
-
diff -r 5e3b983ab2c6 -r c4418949aa37 doc/libervia-cli/blog.rst
--- a/doc/libervia-cli/blog.rst	Mon Oct 31 13:48:31 2022 +0100
+++ b/doc/libervia-cli/blog.rst	Mon Oct 31 13:50:12 2022 +0100
@@ -18,6 +18,8 @@
 
 |e2e_arg|
 
+|pte_arg|
+
 |sign_arg|
 
 examples
@@ -109,6 +111,8 @@
 
 |e2e_arg|
 
+|pte_arg|
+
 |sign_arg|
 
 examples
diff -r 5e3b983ab2c6 -r c4418949aa37 doc/libervia-cli/pubsub.rst
--- a/doc/libervia-cli/pubsub.rst	Mon Oct 31 13:48:31 2022 +0100
+++ b/doc/libervia-cli/pubsub.rst	Mon Oct 31 13:50:12 2022 +0100
@@ -26,6 +26,8 @@
 
 |e2e_arg|
 
+|pte_arg|
+
 |sign_arg|
 
 .. _XEP-0060 §7.1.5: https://xmpp.org/extensions/xep-0060.html#publisher-publish-options
@@ -85,6 +87,8 @@
 
 |e2e_arg|
 
+|pte_arg|
+
 |sign_arg|
 
 example