Fix #2847 (SASL External support)

- Add two new options, keyfile and certfile, which must be both set for
  the auth to work.
- if both are set, then poezio doesn’t force-prompt a password if there
  is none specified
- add /cert_add, /cert_fetch, /cert_disable, /cert_revoke and /certs
  commands.
- add a page of documentation on the process

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