Vinay Sajip committed ab8d20d Draft

Routine update.

  • Participants
  • Parent commits 25baf8c

Comments (0)

Files changed (2)


   the ability to scan for dependencies and building dependency graphs.
 * The package ``distlib.index``, which implements an interface to perform
   operations on an index, such as registering a project, uploading a
-  distribution or uploading documentation.
+  distribution or uploading documentation. Support is included for verifying
+  SSL connections (with domain matching) and signing/verifying packages using
+  GnuPG.
 * The package ``distlib.metadata``, which implements distribution metadata as
   defined by :pep:`345`, :pep:`314` and :pep:`241`.
 * The package ``distlib.markers``, which implements environment markers as


     >>> index.password
+Verifying HTTPS connections
+Although Python has full support for SSL, it does not, by default, verify SSL
+connections to servers. That's because in order to do so, a set of certificates
+which certify the identity of the server needs to be provided (see `the
+relevant Python documentation
+<>`_ for details).
+Support for verifying SSL connections is provided in distlib through a handler,
+:class:`distlib.util.HTTPSHandler`. To use it, set the ``ssl_verifier``
+attribute of the index to a suitably configured instance. For example::
+    >>> from distlib.util import HTTPSHandler
+    >>> verifier = HTTPSHandler(ca_certs='/path/to/root/certs.pem')
+    >>> index.ssl_verifier = verifier
+By default, the handler will attempt to match domains, including wildcard
+matching. This means that (for example) you access ```` or
+```` which have a certificate for ``*``, the domains will
+match. If the domains don't match, the handler raises :class:`URLError`.
+Domain mismatches can, however, happen for valid reasons. Say a hosting server
+```` hosts ````, which we are trying to access using SSL. If
+the server holds a certificate for ````, it will present it to the
+client, as long as both support `Server Name Indication (SNI)
+<>`_. While ``distlib``
+supports SNI where Python supports it, Python 2.x does not include SNI support.
+For this or some other reason , you may wish to turn domain matching off. To do
+so, just set an attribute on the verifier::
+    >>> verifier.check_domain = False
+Getting hold of root certificates
+At the time of writing, you can find a file in the appropriate format on the
+`cURL website <>`_. Just download the
+``caert.pem`` file and pass the path to it when instantiating your verifier.
+.. note::
+   The main PyPI server,, currently does not have an
+   SSL certificate which is recognised by (for example) mainstream browsers.
+   That's because the server is currently certified by, whose root
+   certificate is not included in the trusted roots pre-installed into these
+   browsers. If you want to verify using the root certificate, you
+   will need to get the root certificate and ensure that it's included in
+   the file you supply to ``HTTPSHandler``.
 Saving a default configuration