sjs/vdirsyncer
1
0
Fork 0
mirror of https://github.com/samsonjs/vdirsyncer.git synced 2026-03-25 08:55:50 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions

Make the SSL stuff into a new page

Browse source
This commit is contained in:
Markus Unterwaditzer 2015-01-06 14:41:16 +01:00
parent f76aeba9bc
commit 11bd19febf
3 changed files with 58 additions and 44 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

3
docs/index.rst
View file

@ -18,8 +18,9 @@ Table of Contents
:maxdepth: 1
tutorial
config
ssl-tutorial
keyring
config
supported
problems
vdir

56
docs/ssl-tutorial.rst Normal file
View file

@ -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
<http://www.python-requests.org/en/latest/user/advanced/#ca-certificates>`_.
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/

43
docs/tutorial.rst
View file

@ -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
<http://www.python-requests.org/en/latest/user/advanced/#ca-certificates>`_.
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/