# HG changeset patch
# User Goffi <goffi@goffi.org>
# Date 1665859113 -7200
# Node ID 4b8776eb6826e26dbdad2bba35930e158707750d
# Parent  8f87ff449a3457df54c182feed5872be77e43182
doc (blog, pubsub): documentation on new e2ee arguments for pubsub, and shared secrets handling:

fix 380

diff -r 8f87ff449a34 -r 4b8776eb6826 doc/conf.py
--- a/doc/conf.py	Sat Oct 15 20:38:33 2022 +0200
+++ b/doc/conf.py	Sat Oct 15 20:38:33 2022 +0200
@@ -41,6 +41,14 @@
 
 # -- General configuration ---------------------------------------------------
 
+
+rst_prolog = """
+.. |e2e_arg| replace::
+  To publish an end-to-end encrypted item, you can use the ``-e, --encrypt`` flag, and
+  share secrets with :ref:`libervia-cli_pubsub_secret`. Please read
+  :ref:`pubsub-encryption` for more details.
+"""
+
 # If your documentation needs a minimal Sphinx version, state it here.
 #
 # needs_sphinx = '1.0'
diff -r 8f87ff449a34 -r 4b8776eb6826 doc/libervia-cli/blog.rst
--- a/doc/libervia-cli/blog.rst	Sat Oct 15 20:38:33 2022 +0200
+++ b/doc/libervia-cli/blog.rst	Sat Oct 15 20:38:33 2022 +0200
@@ -16,6 +16,8 @@
 
 ``stdin`` is used to get the body of the blog post.
 
+|e2e_arg|
+
 examples
 --------
 
@@ -103,6 +105,8 @@
    If --preview doesn't work, use ``li blog preview`` (see below) to get error messages.
    On GNU/Linux, Be sure that inotify Python module is installed correctly.
 
+|e2e_arg|
+
 examples
 --------
 
diff -r 8f87ff449a34 -r 4b8776eb6826 doc/libervia-cli/pubsub.rst
--- a/doc/libervia-cli/pubsub.rst	Sat Oct 15 20:38:33 2022 +0200
+++ b/doc/libervia-cli/pubsub.rst	Sat Oct 15 20:38:33 2022 +0200
@@ -24,6 +24,8 @@
 In the same way as for :ref:`libervia-cli_pubsub_node_create`, ``-F, --full-prefix`` can be used if
 you need to specify the full option name.
 
+|e2e_arg|
+
 .. _XEP-0060 §7.1.5: https://xmpp.org/extensions/xep-0060.html#publisher-publish-options
 
 example
@@ -40,6 +42,10 @@
 
 Retrieve items from specified node. Default output is prettified and highlighted XML.
 
+If the node is end-to-end encrypted, items will be automatically and transparently
+decrypted if the shared secrets are known. If you want to avoid this behaviour and get the
+items undecrypted, you can use the ``--no-decrypt`` flag.
+
 example
 -------
 
@@ -75,6 +81,8 @@
 
 :ref:`draft_common` commands can be used.
 
+|e2e_arg|
+
 example
 -------
 
@@ -450,6 +458,11 @@
 Subcommands to add or remove data attached to pubsub items. Please check
 :ref:`libervia-cli_pubsub_attachments`.
 
+secret
+======
+
+Subcommands for pubsub node shared secrets management. Please check :ref:`libervia-cli_pubsub_secret`.
+
 hook
 ====
 
diff -r 8f87ff449a34 -r 4b8776eb6826 doc/libervia-cli/pubsub_secret.rst
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/libervia-cli/pubsub_secret.rst	Sat Oct 15 20:38:33 2022 +0200
@@ -0,0 +1,82 @@
+.. _libervia-cli_pubsub_secret:
+
+===================================================
+pubsub/secret: share, revoke or rotate node secrets
+===================================================
+
+``secret`` group commands to handle pubsub e2ee shared secrets.
+
+You can check :ref:`pubsub-encryption` to have overview on how it works.
+
+share
+=====
+
+Share node secrets with an entity. This make the encrypted pubsub node fully accessible to
+the recipient.
+
+By default, all node secrets are shared with the recipients, this is normally the desired
+behaviour as you most of time want the recipient to have full access to the node. However,
+it may be possible to share only some keys by using ``-k ID, --key ID`` argument.
+
+example
+-------
+
+Louise want to give access to her private blog to pierre::
+
+  $ li pubsub share secret -n private_blog pierre@example.net
+
+revoke
+======
+
+Mark a shared secret as revoked, which means that no new items must be create using this
+secret. The secret is still available to decrypt older items.
+
+By default, the revocation notification is sent to all people known to have the latest
+shared secret, this is the recommended way to use this command. However, you may send the
+revocation notification only to some entities by using ``-r JID, --recipient JID`` as many
+times as necessary.
+
+It is usually better to use the rotate command below, which automatically revoke all
+existing keys and create a new one, sending suitable notifications.
+
+example
+-------
+
+Louise wants to revoke a shared secret used in her private blog::
+
+  $ li pubsub secret revoke -n private_blog k4XBRW9rkYQeGN5fiqoK4R
+
+rotate
+======
+
+Revoke all shared secrets of a node, and create a new one. Suitable revocation and secret
+sharing notifications are sent.
+
+By default, notifications are sent to all people known to have the latest shared secret.
+This is generally what is desirable, unless one or more people who previously had access
+to should now be excluded from access to the new items. In this case, you may use the ``-r
+JID, --recipient JID`` argument as many times as necessary to specify who should receive
+the notifications and new secret.
+
+example
+-------
+
+Louise wants to rotate shared secrets of her private blog::
+
+  $ li pubsub secret rotate -n private_blog
+
+list
+====
+
+List all known shared secrets of a node.
+
+By default, the private key is not returned, to prevent it from being accidentally
+displayed on the screen. If you want to see them too, increase the verbosity with the
+``--verbose, -v`` argument.
+
+example
+-------
+
+Louise wants to see all secrets used in her private blog::
+
+  $ li pubsub secret list -n private_blog