From 84e92f9a98a4c64f9d93c3f99f0546708416f53e Mon Sep 17 00:00:00 2001 From: Goffi Date: Sat, 6 Jun 2026 12:36:14 +0200 Subject: [PATCH] doc (cli): Document `xid` commands: fix 477 --- doc/libervia-cli/xid.rst | 119 +++++++++++++++++++++++++++++ doc/libervia-cli/xid_signature.rst | 72 +++++++++++++++++ 2 files changed, 191 insertions(+) create mode 100644 doc/libervia-cli/xid.rst create mode 100644 doc/libervia-cli/xid_signature.rst diff --git a/doc/libervia-cli/xid.rst b/doc/libervia-cli/xid.rst new file mode 100644 index 00000000..fc012156 --- /dev/null +++ b/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`. diff --git a/doc/libervia-cli/xid_signature.rst b/doc/libervia-cli/xid_signature.rst new file mode 100644 index 00000000..2ccb6d4e --- /dev/null +++ b/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…"