Document the certificate handling

- Show the various options
- Optimize the documentation images

12 files changed, 63 insertions, 0 deletions

diff --git a/doc/en/index.txt b/doc/en/index.txt
index beb80d69..3c000cdd 100644
--- a/doc/en/index.txt
+++ b/doc/en/index.txt
@@ -9,6 +9,7 @@ Available pages
 
 * link:install.html[Installation]
 * link:configure.html[Configuration]
+* link:ssl.html[SSL Management]
 * link:usage.html[Usage]
 * link:themes.html[Theming]
 * link:keys.html[Keys]
diff --git a/doc/en/ssl.txt b/doc/en/ssl.txt
new file mode 100644
index 00000000..ef7af349
--- /dev/null
+++ b/doc/en/ssl.txt
@@ -0,0 +1,62 @@
+SSL Management
+==============
+
+Starting from version 0.7.5, poezio offers some options to check the validity
+of a X.509 certificate.
+
+TOFU
+----
+
+The default handling method is the
+link:https://en.wikipedia.org/wiki/User:Dotdotike/Trust_Upon_First_Use[TOFU/TUFU]
+method. At your first connection, poezio will save the hash of the certificate
+received, and will compare the received one and the first one for the next
+connections.
+
+
+If you are paranoid (or run poezio for the first time in an unsafe
+environment), you can set the _certificate_ value of your config file yourself
+(the hash, not colon-separated).
+
+
+If the certificate is not the same, poezio will show an error message and wait
+for confirmation:
+
+image:../images/ssl_warning.png["Warning message", title="Warning message"]
+
+If you press y, the change is validated an poezio will match the next certs
+with the accepted one.
+
+If you press n, you will get the confirmation that the change has been
+refused, and you will be disconnected.
+
+CA-Based
+--------
+
+If you are connecting to a large server that has several front-facing
+endpoints, you might be bothered by having to validate the change each time,
+and you may want to check only if it the same authority delivered the
+certificate.
+
+You can then set the _ca_cert_path_ option to the path of a file containing
+the validation chain in link:https://tools.ietf.org/html/rfc1422.html[PEM
+format] ; those certificates are usually in /usr/share/ca-certificates/ but it
+may vary depending of your distribution.
+
+If the authority does not match when connecting, you should be disconnected.
+
+None
+----
+
+If you do not want to bother with certificate validation at all (which can be
+the case when you run poezio on the same computer as your jabber server), you
+can set the _ignore_certificate_ value to true, and let the _ca_cert_path_
+option empty (or even remove it).
+
+
+
+
+
+
+
+
diff --git a/doc/images/conversation.png b/doc/images/conversation.png
index f5347178..0940a3a4 100644
--- a/doc/images/conversation.png
+++ b/doc/images/conversation.png
diff --git a/doc/images/data_forms.png b/doc/images/data_forms.png
index d6e53cd9..0afb3e03 100644
--- a/doc/images/data_forms.png
+++ b/doc/images/data_forms.png
diff --git a/doc/images/list.png b/doc/images/list.png
index 768ca41f..a2fc2315 100644
--- a/doc/images/list.png
+++ b/doc/images/list.png
diff --git a/doc/images/private.png b/doc/images/private.png
index 7d604dc2..19492e2b 100644
--- a/doc/images/private.png
+++ b/doc/images/private.png
diff --git a/doc/images/roster.png b/doc/images/roster.png
index d853c1cb..d1a8f9f4 100644
--- a/doc/images/roster.png
+++ b/doc/images/roster.png
diff --git a/doc/images/simple_notify_example.png b/doc/images/simple_notify_example.png
index e9a54399..2e9c617c 100644
--- a/doc/images/simple_notify_example.png
+++ b/doc/images/simple_notify_example.png
diff --git a/doc/images/ssl_warning.png b/doc/images/ssl_warning.png
new file mode 100644
index 00000000..348a81a4
--- /dev/null
+++ b/doc/images/ssl_warning.png
diff --git a/doc/images/tab_bar.png b/doc/images/tab_bar.png
index fc482ffd..9c5c74eb 100644
--- a/doc/images/tab_bar.png
+++ b/doc/images/tab_bar.png
diff --git a/doc/images/theme_256_colors.png b/doc/images/theme_256_colors.png
index 00e6c51d..395f3d39 100644
--- a/doc/images/theme_256_colors.png
+++ b/doc/images/theme_256_colors.png
diff --git a/doc/images/vert_tabs.png b/doc/images/vert_tabs.png
index 8393c4cf..a48a8051 100644
--- a/doc/images/vert_tabs.png
+++ b/doc/images/vert_tabs.png