diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/source/commands.rst | 43 | ||||
| -rw-r--r-- | doc/source/configuration.rst | 16 | ||||
| -rw-r--r-- | doc/source/misc/client_certs.rst | 43 | ||||
| -rw-r--r-- | doc/source/misc/index.rst | 1 |
4 files changed, 99 insertions, 4 deletions
diff --git a/doc/source/commands.rst b/doc/source/commands.rst index 395b396b..f8f2b5e1 100644 --- a/doc/source/commands.rst +++ b/doc/source/commands.rst @@ -312,10 +312,10 @@ MultiUserChat tab commands .. glossary:: :sorted: - /clear [RosterTab version] + /clear [MUCTab version] **Usage:** ``/clear`` - Clear the information buffer. (was /clear_infos) + Clear the messages buffer. /ignore **Usage:** ``/ignore <nickname>`` @@ -502,8 +502,8 @@ Roster tab commands Disconnect from the remote server (if connected) and then connect to it again. -.. note:: The following commands only exist if your server supports them. If it - does not, you will be notified when you start poezio. +.. note:: The following commands only exist if your server announces it + supports them. .. glossary:: :sorted: @@ -523,6 +523,41 @@ Roster tab commands /list_blocks List the blocked JIDs. + /certs + + List the remotely stored X.509 certificated allowed to connect + to your accounts. + + /cert_add + **Usage:** ``/cert_add <name> <certificate file> [management]`` + + Add a client X.509 certificate to the list of the certificates + which grand access to your account. It must have an unique name + the file must be in PEM format. ``[management]`` is true by + default and specifies if the clients connecting with this + particular certificate will be able to manage the list of + authorized certificates. + + /cert_disable + **Usage:** ``/cert_disable <name>`` + + Remove a certificate from the authorized list. Clients currently + connected with the certificate identified by ``<name>`` will + however **not** be disconnected. + + /cert_revoke + **Usage:** ``/cert_revoke <name>`` + + Remove a certificate from the authorized list. Clients currently + connected with the certificate identified by ``<name>`` **will** + be disconnected. + + /cert_fetch + **Usage:** ``/cert_fetch <name> <path>`` + + Download the public key of the authorized certificate identified by + ``name`` from the XMPP server, and store it in ``<path>``. + .. note:: The following commands do not comply with any XEP or whatever, but they can still prove useful when you are migrating to an other JID. diff --git a/doc/source/configuration.rst b/doc/source/configuration.rst index b32cbec3..b7099020 100644 --- a/doc/source/configuration.rst +++ b/doc/source/configuration.rst @@ -156,6 +156,22 @@ Options related to account configuration, nickname… your alternative nickname will be "john\_". + keyfile + + **Default value:** ``[empty]`` + + Path to a PEM private key file to use for certificate authentication + through SASL External. If set, :term:`certfile` **MUST** be set as well + in order to login. + + certfile + + **Default value:** ``[empty]`` + + Path to a PEM certificate file to use for certificate authentication + through SASL External. If set, :term:`keyfile` **MUST** be set as well + in order to login. + resource **Default value:** ``[empty]`` diff --git a/doc/source/misc/client_certs.rst b/doc/source/misc/client_certs.rst new file mode 100644 index 00000000..df09ea3c --- /dev/null +++ b/doc/source/misc/client_certs.rst @@ -0,0 +1,43 @@ +Using client certificates to login +================================== + +Passwordless authentication is possible in XMPP through the use of mecanisms +such as `SASL External`_. This mechanism has to be supported by both the client +and the server. This page does not cover the server setup, but prosody has a +`mod_client_certs`_ module which can perform this kind of authentication, and +also helps you create a self-signed certificate. + +Poezio configuration +-------------------- + +If you created a certificate using the above link, you should have at least +two files, a ``.crt`` (public key in PEM format) and a ``.key`` (private key +in PEM format). + +You only have to store the files wherever you want and set :term:`keyfile` +with the path to the private key (``.key``), and :term:`certfile` with the +path to the public key (``.crt``). + +Authorizing your keys +--------------------- + +Now your poezio is setup to try to use client certificates at each connection. +However, you still need to inform your XMPP server that you want to allow +those keys to access your account. + +This is done through :term:`/cert_add`. Once you have added your certificate, +you can try to connect without a password by commenting the option. + +.. note:: The :term:`/cert_add` command and the others are only available if + your server supports them. + +Next +---- +Now that this is setup, you might want to use :term:`/certs` to list the +keys currently known by your XMPP server, :term:`/cert_revoke` or +:term:`/cert_disable` to remove them, and :term:`/cert_fetch` to retrieve +a public key. + + +.. _SASL External: http://xmpp.org/extensions/xep-0178.html +.. _mod_client_certs: https://code.google.com/p/prosody-modules/wiki/mod_client_certs diff --git a/doc/source/misc/index.rst b/doc/source/misc/index.rst index fe8f1100..2603298e 100644 --- a/doc/source/misc/index.rst +++ b/doc/source/misc/index.rst @@ -7,6 +7,7 @@ Contents: :maxdepth: 2 carbons + client_certs correct personal_events pyenv |