# HG changeset patch
# User Goffi <goffi@goffi.org>
# Date 1667084818 -7200
# Node ID 9f85369294f3c6e17d55c8f600cca4d8408283ce
# Parent  2695dafc5c4d9fedb16fdb0871ef5c5dcd282836
doc (encryption, cli): pubsub signing documentation:

- add a `Pubsub Signature` section to `encryption` documentation
- document `-X, --sign` flag where it's used
- document `pubsub/signature` subcommands

fix 381

diff -r 2695dafc5c4d -r 9f85369294f3 doc/conf.py
--- a/doc/conf.py	Sun Oct 30 01:06:58 2022 +0200
+++ b/doc/conf.py	Sun Oct 30 01:06:58 2022 +0200
@@ -47,6 +47,13 @@
   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.
+
+.. |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).
+  Signature can then be checked with :ref:`libervia-cli_pubsub_signature`. Please read
+  :ref:`pubsub-encryption` for more details.
+
 """
 
 # If your documentation needs a minimal Sphinx version, state it here.
diff -r 2695dafc5c4d -r 9f85369294f3 doc/encryption.rst
--- a/doc/encryption.rst	Sun Oct 30 01:06:58 2022 +0200
+++ b/doc/encryption.rst	Sun Oct 30 01:06:58 2022 +0200
@@ -92,3 +92,36 @@
 
 .. _OpenPGP: https://en.wikipedia.org/wiki/Pretty_Good_Privacy#OpenPGP
 
+Pubsub Signature
+================
+
+By default, identity of the publisher of a pubsub item is difficult to authenticate: it
+may be specified by the pubsub service (using the `"publisher" attribute`_), but this
+attribute is not set by all pubsub services, and it can be spoofed by the service or the
+XMPP server.
+
+To strongly authenticate the publisher of a pubsub item, it is possible to cryptographically sign an item. This can work with any pubsub item, encrypted or not, and it can be done after the item has been published. The process use `Pubsub Signing protoXEP`_
+
+.. note::
+
+   Pubsub Signing 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.
+
+.. attention::
+
+   Signature only certifies that the signers strongly link themselves with this version of
+   the item, not that the signers are the original authors of the item. In other words, it
+   prevents somebody to say that somebody else has published something (the signature
+   would be missing or invalid), but the published data may come from anywhere. Also keep
+   in mind that a security breach (stolen encryption keys, major bug somewhere) is always
+   possible.
+
+
+To handle pubsub signatures from command line, you may use
+:ref:`libervia-cli_pubsub_signature`.
+
+.. _"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 2695dafc5c4d -r 9f85369294f3 doc/libervia-cli/blog.rst
--- a/doc/libervia-cli/blog.rst	Sun Oct 30 01:06:58 2022 +0200
+++ b/doc/libervia-cli/blog.rst	Sun Oct 30 01:06:58 2022 +0200
@@ -18,6 +18,8 @@
 
 |e2e_arg|
 
+|sign_arg|
+
 examples
 --------
 
@@ -107,6 +109,8 @@
 
 |e2e_arg|
 
+|sign_arg|
+
 examples
 --------
 
diff -r 2695dafc5c4d -r 9f85369294f3 doc/libervia-cli/pubsub.rst
--- a/doc/libervia-cli/pubsub.rst	Sun Oct 30 01:06:58 2022 +0200
+++ b/doc/libervia-cli/pubsub.rst	Sun Oct 30 01:06:58 2022 +0200
@@ -26,6 +26,8 @@
 
 |e2e_arg|
 
+|sign_arg|
+
 .. _XEP-0060 §7.1.5: https://xmpp.org/extensions/xep-0060.html#publisher-publish-options
 
 example
@@ -83,6 +85,8 @@
 
 |e2e_arg|
 
+|sign_arg|
+
 example
 -------
 
@@ -458,6 +462,11 @@
 Subcommands to add or remove data attached to pubsub items. Please check
 :ref:`libervia-cli_pubsub_attachments`.
 
+signature
+=========
+
+Subcommands to handle items signature. Please check :ref:`libervia-cli_pubsub_signature`.
+
 secret
 ======
 
diff -r 2695dafc5c4d -r 9f85369294f3 doc/libervia-cli/pubsub_signature.rst
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/libervia-cli/pubsub_signature.rst	Sun Oct 30 01:06:58 2022 +0200
@@ -0,0 +1,35 @@
+.. _libervia-cli_pubsub_signature:
+
+=================================================
+pubsub/signature: Sign and Check Items Signatures
+=================================================
+
+``signature`` group commands to handle pubsub item cryptographic signatures:
+
+You can check :ref:`pubsub-encryption` to have overview on how it works.
+
+sign
+=====
+
+Sign a pubsub item using OpenPGP keys of the profile.
+
+example
+-------
+
+Louise want to sign an item on her blog::
+
+  $ li pubsub signature sign -s louise@example.net -n urn:xmpp:microblog:0 -i about_feminism
+
+check
+=====
+
+Check validity of a signature found in attachments. For now, the attachments data JSON as
+found in attachments must be used, it is planned to make this command simpler in the close
+future.
+
+example
+-------
+
+Pierre wants to check that a blog post is really from Louise::
+
+  $ li pubsub signature check -s louise@example.net -n urn:xmpp:microblog:0 -i about_feminism '{"timestamp": 1667079677.0, "signers": ["louise@example.net"], "signature": "iQGzBAABCAAdFiEEeTqK7iUsJz97sLSEgjG1Of9Gvi0FAmNdnf0ACgkQgjG1Of9Gvi293Qv+IWe6gkaAPzGI6fis9yg9biSdFE9qf9oi+jyTiZuTR1QjjZYE7x+vsj3KewKBUMOyqxKMk1WVKmimDb3yCqfF852lEox3OQuBMP46G9UHDNII6D+oqe4VVWZhqe3s3twWYc08nrvAUH4tMI96xml4wuEk6Fv8PwBcNEEzX8zNwLYeY6tsR72XErBDn5oY06OGhZeLBn6FkUI1QZ3jT0djjH87CuH+9gOS6vEIpO+UnCqvB3aqxwhHIIOh5X9bUyEyxINb3kA6WpYumlc92vE8ROndPZGEni9OfouTjJL7+tUmcNz4RJdbEzBpETtzJ4B3r/kbJWKi5YDpZZOI1k/W/eKXFIg6Aycc0iG/THSEwvYMFGrmyQYosdC+mbjSE4DvYE1aSHOLW3ut5kNuDqLH17/kyOh+VoR4FAkRtGoa34sQN2jaRG8m/Gl+98Ha67k8OisnrHOx7FKGGcrpEp+BCUgvNP0IRFCz26xSaZ6aXK2SQkcvlbVXf6o0BkE5Hwcn"}'