diff --git a/docs/index.rst b/docs/index.rst index a90cf65..3e912d6 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -18,8 +18,9 @@ Table of Contents :maxdepth: 1 tutorial - config + ssl-tutorial keyring + config supported problems vdir diff --git a/docs/ssl-tutorial.rst b/docs/ssl-tutorial.rst new file mode 100644 index 0000000..b2d59c5 --- /dev/null +++ b/docs/ssl-tutorial.rst @@ -0,0 +1,56 @@ +.. _ssl-tutorial: + +============================== +SSL and certificate validation +============================== + +Vdirsyncer uses the requests_ library for all its HTTP and SSL interaction. + +All SSL configuration is done per-storage. Storages that have anything to do +with SSL have two parameters: ``verify`` and ``verify_fingerprint``. + +- The ``verify`` parameter determines whether to verify SSL certificates. + + 1. The default, ``true``, means that certificates will be validated against a + set of trusted CAs. See :ref:`ssl-cas`. + + 2. The value ``false`` will disable both trusted-CA-validation and the + validation of the certificate's expiration date. Unless combined with + ``verify_fingerprint``, **you should not use this value at all, because + it's a security risk**. + + 3. You can also set ``verify`` to a path of the server's certificate in PEM + format, instead of relying on the default root CAs:: + + [storage foo] + type = caldav + ... + verify = "/path/to/cert.pem" + +- The ``verify_fingerprint`` parameter can be used to compare the SSL + fingerprint to a fixed value. The value can be either a SHA1-fingerprint or + an MD5 one:: + + [storage foo] + type = caldav + ... + verify_fingerprint = "94:FD:7A:CB:50:75:A4:69:82:0A:F8:23:DF:07:FC:69:3E:CD:90:CA" + + Using it will effectively set ``verify=False``. + +.. _ssl-cas: + +Trusted CAs +----------- + +As said, vdirsyncer uses the requests_ library for such parts, which, by +default, `uses its own set of trusted CAs +`_. + +However, the actual behavior depends on how you have installed it. Some Linux +distributions, such as Debian, patch their ``python-requests`` package to use +the system certificate CAs. Normally these two stores are similar enough for +you not to care. If the behavior on your system is somehow confusing, your best +bet is explicitly setting the SSL options above. + +.. _requests: www.python-requests.org/ diff --git a/docs/tutorial.rst b/docs/tutorial.rst index f06cf24..2efaf31 100644 --- a/docs/tutorial.rst +++ b/docs/tutorial.rst @@ -143,46 +143,3 @@ it will not automatically start synchronizing those [2]_. You should run .. [2] Because collections are added rarely, and checking for this case before every synchronization isn't worth the overhead. - -.. _ssl-tutorial: - -SSL ---- - -Vdirsyncer uses the requests_ library for all its HTTP and SSL interaction. - -All SSL configuration is done per-storage. Storages that have anything to do -with SSL have two parameters: ``verify`` and ``verify_fingerprint``. - -- The ``verify`` parameter determines whether to verify SSL certificates. - - 1. The default, ``true``, means that certificates will be validated against - `requests' own set of root CAs - `_. - - 2. The value ``false`` will disable both trusted-CA-validation and the - validation of the certificate's expiration date. Unless combined with - ``verify_fingerprint``, you should not use this value at all. - - 3. You can also set ``verify`` to a path of the server's certificate in PEM - format, instead of relying on the default root CAs:: - - [storage foo] - type = caldav - ... - verify = "/path/to/cert.pem" - -- The ``verify_fingerprint`` parameter can be used to *additionally* compare - the SSL fingerprint to a fixed value. The value can be either a - SHA1-fingerprint or an MD5 one:: - - [storage foo] - type = caldav - ... - verify_fingerprint = "94:FD:7A:CB:50:75:A4:69:82:0A:F8:23:DF:07:FC:69:3E:CD:90:CA" - - Using it will *not* turn off the normal CA validation. If you use a - self-signed certificate which you want to pin down, you have to also set - ``verify = false``. - -.. _requests: www.python-requests.org/