Mercurial > libervia-backend

annotate doc/libervia-cli/pubsub_secret.rst @ 4219:1b5cf2ee1d86

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