diff --git a/doc/images/conversation.png b/doc/source/images/conversation.png similarity index 100% rename from doc/images/conversation.png rename to doc/source/images/conversation.png diff --git a/doc/images/correct.png b/doc/source/images/correct.png similarity index 100% rename from doc/images/correct.png rename to doc/source/images/correct.png diff --git a/doc/images/data_forms.png b/doc/source/images/data_forms.png similarity index 100% rename from doc/images/data_forms.png rename to doc/source/images/data_forms.png diff --git a/doc/images/layers.png b/doc/source/images/layers.png similarity index 100% rename from doc/images/layers.png rename to doc/source/images/layers.png diff --git a/doc/images/list.png b/doc/source/images/list.png similarity index 100% rename from doc/images/list.png rename to doc/source/images/list.png diff --git a/doc/images/muc.png b/doc/source/images/muc.png similarity index 100% rename from doc/images/muc.png rename to doc/source/images/muc.png diff --git a/doc/images/private.png b/doc/source/images/private.png similarity index 100% rename from doc/images/private.png rename to doc/source/images/private.png diff --git a/doc/images/roster.png b/doc/source/images/roster.png similarity index 100% rename from doc/images/roster.png rename to doc/source/images/roster.png diff --git a/doc/images/simple_notify_example.png b/doc/source/images/simple_notify_example.png similarity index 100% rename from doc/images/simple_notify_example.png rename to doc/source/images/simple_notify_example.png diff --git a/doc/images/ssl_warning.png b/doc/source/images/ssl_warning.png similarity index 100% rename from doc/images/ssl_warning.png rename to doc/source/images/ssl_warning.png diff --git a/doc/images/tab_bar.png b/doc/source/images/tab_bar.png similarity index 100% rename from doc/images/tab_bar.png rename to doc/source/images/tab_bar.png diff --git a/doc/images/theme_256_colors.png b/doc/source/images/theme_256_colors.png similarity index 100% rename from doc/images/theme_256_colors.png rename to doc/source/images/theme_256_colors.png diff --git a/doc/images/vert_tabs.png b/doc/source/images/vert_tabs.png similarity index 100% rename from doc/images/vert_tabs.png rename to doc/source/images/vert_tabs.png diff --git a/doc/source/index.rst b/doc/source/index.rst index 8ec26348..ea744b26 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -15,6 +15,7 @@ Contents: themes commands dev/index + misc/index .. configure diff --git a/doc/source/misc/index.rst b/doc/source/misc/index.rst new file mode 100644 index 00000000..bf8fcb90 --- /dev/null +++ b/doc/source/misc/index.rst @@ -0,0 +1,22 @@ +Miscellaneous topics +==================== + +Contents: + +.. toctree:: + :maxdepth: 2 + + ssl + + +.. + configure + ssl + usage + themes + keys + plugins + misc + xep + dev + diff --git a/doc/source/misc/ssl.rst b/doc/source/misc/ssl.rst new file mode 100644 index 00000000..a012ebed --- /dev/null +++ b/doc/source/misc/ssl.rst @@ -0,0 +1,60 @@ +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 `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: + +.. figure:: ../images/ssl_warning.png + :alt: 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 `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). + +.. warning:: Only do this if you know what you are doing, or you will be open + to Man in The Middle attacks! + +.. _TOFU/TUFU: https://en.wikipedia.org/wiki/User:Dotdotike/Trust_Upon_First_Use +.. _PEM format: https://tools.ietf.org/html/rfc1422.html diff --git a/doc/source/themes.rst b/doc/source/themes.rst index 92b88245..2a12d8c4 100644 --- a/doc/source/themes.rst +++ b/doc/source/themes.rst @@ -69,7 +69,7 @@ text white on black by default, a fg_color of -1 is white, and a bg_color of -1 is black). If it’s between 0 and 256 it represents one of the colors on the image: -.. figure:: ../images/theme_256_colors.png +.. figure:: ./images/theme_256_colors.png :alt: The list of all 256 colors The list of all 256 colors