From dd434fbf1f9fdc2243ec1ab48cd9915e6efc5c16 Mon Sep 17 00:00:00 2001 From: Goffi Date: Mon, 31 Oct 2022 13:50:12 +0100 Subject: [PATCH] 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 --- doc/conf.py | 5 +++++ doc/encryption.rst | 21 ++++++++++++++++++++- doc/libervia-cli/blog.rst | 4 ++++ doc/libervia-cli/pubsub.rst | 4 ++++ 4 files changed, 33 insertions(+), 1 deletion(-) diff --git a/doc/conf.py b/doc/conf.py index 5c6bc111..34158adb 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -48,6 +48,11 @@ rst_prolog = """ 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 --git a/doc/encryption.rst b/doc/encryption.rst index 9dc54908..0862a223 100644 --- a/doc/encryption.rst +++ b/doc/encryption.rst @@ -92,6 +92,26 @@ To handle encrypted pubsub node shared secrets from command line, you may use .. _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 @@ To handle pubsub signatures from command line, you may use .. _"publisher" attribute: https://xmpp.org/extensions/xep-0060.html#publisher-publish-success-publisher .. _Pubsub Signing protoXEP: https://github.com/xsf/xeps/pull/1228 - diff --git a/doc/libervia-cli/blog.rst b/doc/libervia-cli/blog.rst index 538f4ac4..e657bd0a 100644 --- a/doc/libervia-cli/blog.rst +++ b/doc/libervia-cli/blog.rst @@ -18,6 +18,8 @@ publish a blog item. |e2e_arg| +|pte_arg| + |sign_arg| examples @@ -109,6 +111,8 @@ configuration `_ below to see how to do. |e2e_arg| +|pte_arg| + |sign_arg| examples diff --git a/doc/libervia-cli/pubsub.rst b/doc/libervia-cli/pubsub.rst index 55bab2f6..f731fdac 100644 --- a/doc/libervia-cli/pubsub.rst +++ b/doc/libervia-cli/pubsub.rst @@ -26,6 +26,8 @@ you need to specify the full option name. |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 @@ If you don't change anything or publish an empty blog post, the edition will be |e2e_arg| +|pte_arg| + |sign_arg| example