Mercurial > libervia-backend

comparison doc/libervia-cli/pubsub_secret.rst @ 3951:4b8776eb6826

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
doc (blog, pubsub): documentation on new e2ee arguments for pubsub, and shared secrets handling: fix 380
author Goffi <goffi@goffi.org>
date Sat, 15 Oct 2022 20:38:33 +0200
parents
children
comparison
equal deleted inserted replaced
3950:8f87ff449a34 3951:4b8776eb6826
1 .. _libervia-cli_pubsub_secret:
2
3 ===================================================
4 pubsub/secret: share, revoke or rotate node secrets
5 ===================================================
6
7 ``secret`` group commands to handle pubsub e2ee shared secrets.
8
9 You can check :ref:`pubsub-encryption` to have overview on how it works.
10
11 share
12 =====
13
14 Share node secrets with an entity. This make the encrypted pubsub node fully accessible to
15 the recipient.
16
17 By default, all node secrets are shared with the recipients, this is normally the desired
18 behaviour as you most of time want the recipient to have full access to the node. However,
19 it may be possible to share only some keys by using ``-k ID, --key ID`` argument.
20
21 example
22 -------
23
24 Louise want to give access to her private blog to pierre::
25
26 $ li pubsub share secret -n private_blog pierre@example.net
27
28 revoke
29 ======
30
31 Mark a shared secret as revoked, which means that no new items must be create using this
32 secret. The secret is still available to decrypt older items.
33
34 By default, the revocation notification is sent to all people known to have the latest
35 shared secret, this is the recommended way to use this command. However, you may send the
36 revocation notification only to some entities by using ``-r JID, --recipient JID`` as many
37 times as necessary.
38
39 It is usually better to use the rotate command below, which automatically revoke all
40 existing keys and create a new one, sending suitable notifications.
41
42 example
43 -------
44
45 Louise wants to revoke a shared secret used in her private blog::
46
47 $ li pubsub secret revoke -n private_blog k4XBRW9rkYQeGN5fiqoK4R
48
49 rotate
50 ======
51
52 Revoke all shared secrets of a node, and create a new one. Suitable revocation and secret
53 sharing notifications are sent.
54
55 By default, notifications are sent to all people known to have the latest shared secret.
56 This is generally what is desirable, unless one or more people who previously had access
57 to should now be excluded from access to the new items. In this case, you may use the ``-r
58 JID, --recipient JID`` argument as many times as necessary to specify who should receive
59 the notifications and new secret.
60
61 example
62 -------
63
64 Louise wants to rotate shared secrets of her private blog::
65
66 $ li pubsub secret rotate -n private_blog
67
68 list
69 ====
70
71 List all known shared secrets of a node.
72
73 By default, the private key is not returned, to prevent it from being accidentally
74 displayed on the screen. If you want to see them too, increase the verbosity with the
75 ``--verbose, -v`` argument.
76
77 example
78 -------
79
80 Louise wants to see all secrets used in her private blog::
81
82 $ li pubsub secret list -n private_blog