119 lines
2.5 KiB
ReStructuredText
119 lines
2.5 KiB
ReStructuredText
.. _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`.
|