.. _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`.