doc (cli): Document xid commands:

fix 477

doc/libervia-cli/xid.rst

@@ -0,0 +1,119 @@
+.. _libervia-cli_xid:
+
+===================
+xid: XID management
+===================
+
+XID (XMPP Decentralized ID) provides a way to associate a cryptographic identity with an
+XMPP account.
+
+XIDs are published via PEP so that other entities can retrieve and verify them.
+
+get
+===
+
+Retrieve XIDs published by an entity.
+
+By default, only the current XID is returned. Use ``-a, --all`` to retrieve all published
+XIDs. When no entity is specified, own XIDs are queried.
+
+Use ``-v, --verbose`` to show other metadata such as item ID, creation date, and whether
+the private key is known.
+
+example
+-------
+
+Retrieve the current XID::
+
+  $ li xid get
+
+Retrieve all XIDs published by an Louise and their metadata::
+
+  $ li xid get -av louise@example.org
+
+create
+======
+
+Create a new XID key pair and publish it via PEP.
+
+By default the new XID is published with item ID ``current``, which makes it the active
+XID. If a ``current`` XID is already published, the operation fails with a conflict error.
+``-i, --item-id`` can be used to specify a different item ID.
+
+example
+-------
+
+Create a new current XID::
+
+  $ li xid create
+
+revoke
+======
+
+Revoke a published XID.
+
+A confirmation is requested before revocation unless ``-f, --force`` is used. An optional
+human-readable reason can be provided with ``-r, --reason``.
+
+example
+-------
+
+Revoke a XID::
+
+  $ li xid revoke abcd1234@id.internal -r "compromised key"
+
+verify
+======
+
+Verify that an entity owns a XID via challenge/response.
+
+A cryptographic challenge is sent to the entity. If the entity possesses the private key
+corresponding to the XID, it signs the challenge and returns a valid response.
+
+This command requires the entity to be online and running a compatible client.
+
+example
+-------
+
+Verify that ``louise@example.org`` owns the ``abcd1234@id.internal`` XID::
+
+  $ li xid verify louise@example.org abcd1234@id.internal
+
+
+.. _li_xid_export:
+
+export
+======
+
+Generate an ``xmpp:`` URI containing the private key of a XID for export. It can then be
+transmitted (e.g., with QR Code).
+
+If no XID is specified, the current one is used.
+
+example
+-------
+
+Export the current XID::
+
+  $ li xid export
+
+import
+======
+
+Import a XID private key from an ``xmpp:`` URI.
+
+The URI must contain ``xid-private`` and ``xid-created`` parameters (as generated by
+:ref:`li_xid_export`), and the XID must be published on the profile PEP node.
+
+example
+-------
+
+Import a XID private key::
+
+  $ li xid import "xmpp:?xid-private=…&xid-created=…"
+
+signature
+=========
+
+Subcommands to sign or verify data with a XID. Please check
+:ref:`libervia-cli_xid_signature`.

doc/libervia-cli/xid_signature.rst

@@ -0,0 +1,72 @@
+.. _libervia-cli_xid_signature:
+
+=============================
+xid signature: XID signatures
+=============================
+
+Sign or verify data with a XID.
+
+sign
+====
+
+Sign a file or data with a XID private key.
+
+The data to sign can be provided in three ways:
+
+- a file path (default when the positional argument is not ``-``)
+- inline data with ``-d, --data``
+- stdin when the positional argument is ``-`` (default)
+
+The XID to use is selected with ``-x, --xid``. If omitted, the current XID is used.
+
+The signature is output as a hexadecimal string. By default it is printed to stdout, but
+``-o, --output`` can be used to write it to a file.
+
+examples
+--------
+
+Sign a file::
+
+  $ li xid signature sign document.txt
+
+Sign data from stdin::
+
+  $ echo "hello" | li xid signature sign
+
+Sign inline data::
+
+  $ li xid signature sign -d "hello"
+
+Write the signature to a file::
+
+  $ li xid signature sign document.txt -o sig.hex
+
+check
+=====
+
+Verify a signature against a XID public key.
+
+The data to verify can be provided the same way as for :ref:`sign`:
+
+- a file path (default)
+- inline data with ``-d, --data``
+- stdin when the positional argument is ``-`` (default)
+
+The signature must be provided either with ``-s, --signature`` for an inline hex-encoded
+signature, or ``-f, --signature-file`` for a file containing the signature. These two
+options are mutually exclusive.
+
+examples
+--------
+
+Verify a signature inline::
+
+  $ li xid signature check abcd1234@id.internal document.txt -s "a1b2c3…"
+
+Verify with a signature file::
+
+  $ li xid signature check abcd1234@id.internal document.txt -f sig.hex
+
+Verify data from stdin::
+
+  $ echo "hello" | li xid signature check abcd1234@id.internal -d - -s "a1b2c3…"