Merge lp:~jelmer/bzr/urllib-verifies-ssl-certs into lp:bzr

[Jelmer Vernooij]

Support verification of SSL certificates for the urllib HTTPS backend.

Add support for verifying SSL certificates when using urllib.

[Martin Pool (mbp)]

On 4 November 2011 14:03, Jelmer Vernooij <email address hidden> wrote:
> Jelmer Vernooij has proposed merging lp:~jelmer/bzr/urllib-verifies-ssl-certs into lp:bzr.
>
> Requested reviews:
>  bzr-core (bzr-core)
> Related bugs:
>  Bug #125055 in Bazaar: "defaulting to pycurl doesn't make sense anymore"
>  https://bugs.launchpad.net/bzr/+bug/125055
>  Bug #651161 in Bazaar: "bzr fails to verify ssl validity in https connections - by default --> as pycurl isn't a dep only a suggestion "
>  https://bugs.launchpad.net/bzr/+bug/651161
>
> For more details, see:
> https://code.launchpad.net/~jelmer/bzr/urllib-verifies-ssl-certs/+merge/81227
>
> Add support for verifying SSL certificates when using urllib.

That's great, thanks.

> This branch does actually work, but it's got some open ends:
>
> * The location with the CAs to trust differs per system. Rather than hardcoding
>  a list, I think we should have a configuration option that allows the user
>  to specify what CA list they want to verify against.
>
>  This option could then also be pointed at a user-specific list
>  (rather than a system wide list). And packagers can put in the default
>  for their distribution.
>
>  Where do I obtain this option from, which config stack ?

[needsfixing] I think the global stack would be a good place to start
- it would seem like a kind of contrived case to want different values
on a smaller scope. We can always change it later.

> * We probably want some way to specify that self-signed certificates are ok.
>  Probably also a new option? We should probably still warn the user
>  when a self-signed certificate is being trusted.

+1 to a new option and to always warning.

Though perhaps it would be equivalent and easier to just have an
option saying "don't do validation."

> * There are no additional tests. There probably should be some, at least for
>  e.g. the match_hostname helper.

It would be nice, if it's not too hard, to actually test against an
untrusted cert, or at least to do monkeypatching to make it look like
we got an invalid cert.

[needsfixing] I'd like a unit test for match_hostname covering the
various cases.

> * I have the feeling that I'm missing something. This was way too easy.
>  What is it?

I haven't read the rfc but it looks plausible. You could wait for a
review from vila, who has probably touched this most, or robert who is
an http nerd.

I wonder if this needs a change to Windows or Mac packaging to make
sure the certs are there. Or, possibly we can get them from the
system's keyring in some way.

[Vincent Ladeuil (vila)]

> Add support for verifying SSL certificates when using urllib.

\o/

>
> This branch does actually work, but it's got some open ends:
>
> * The location with the CAs to trust differs per system. Rather than hardcoding
> a list, I think we should have a configuration option that allows the user
> to specify what CA list they want to verify against.

pycurl already handles that for windows but getting it right in the general
case... sounds like a packaging issue :-/

>
> This option could then also be pointed at a user-specific list
> (rather than a system wide list). And packagers can put in the default
> for their distribution.
>
> Where do I obtain this option from, which config stack ?

I'd go with global to start with specifying the default value at
registration time if possible.

Arguably it's a system-wide config file that should be used, making packager
life easier.

>
> * We probably want some way to specify that self-signed certificates are ok.
> Probably also a new option? We should probably still warn the user
> when a self-signed certificate is being trusted.

authentication.conf is the right place for that and the option is even
documented but not implemented ;)

>
> * There are no additional tests. There probably should be some, at least for
> e.g. the match_hostname helper.

Yup. There are already https tests for pycurl that should be activated now
(<broken record> hey, did I mention the 'scenarios' attribute is cool for
that ? </broken record> ;)

>
> * I have the feeling that I'm missing something. This was way too easy.
> What is it?

Hehe.

The last time I worked on this area we were still supporting python-2.4/2.5
where https wasn't supported. Now, you also found the relevant code in
python-3.2 so... that certainly simplify things *a lot* :)

This wasn't a full review but as I understand it you weren't requesting one
either ;)

As for tests, if you look at the pycurl ones you'll certainly find that most
of the needed infrastructure is there to build certificates for special
purposes (self-signed, obsolete, etc) and easily setup an https server.

99 + SSLSocket.getpeercert()) matches the *hostname*. RFC 2818 rules
100 + are mostly followed, but IP addresses are not accepted for *hostname*.

Hmm, IP addresses not accepted ? I bet our tests won't like that much.

pycurl itself was not open enough to test for these weird certificates AFAIR
but it's also a robust implementation so I wasn't concerned, but if we make
urllib the default one, we have to make sure we're making the right checks.

I'll need to dig a bit more to find back the relevant discussions about this
topic.

Also, defaulting to urllib is fine but the documentation probably needs to
be updated (created even ?) to make it clear that we're not defaulting to
pycurl. We had issues in the past (including failures to check lp
certificate) which had led to the actual defaults (urllib for http, pycurl
for https), let's make the switch crystal clear.

141 def connect_to_origin(self):
142 - ssl_sock = _ssl_wrap_socket(self.sock, self.key_file, self.cert_file)
143 + ssl_sock = ssl.wrap_socket(self.sock, self.key_file, self.cert_file,
144 + ...

[Martin Packman (gz)]

I think there's general agreement this is great, and with the reqirement of Python 2.6 something that's now acheivable and should probably get into the next bzr release.

It absolutely needs some kind of automated testing though, and likely an option for disabling checks, I've used `curl -k` and `wget --no-check-certificate` enough to know I'd be annoyed if that option wasn't there.

review: Needs Fixing

[Martin Packman (gz)]

Summarising from earlier rambling chat:

* The error shown when a certificate can't be checked because no local store is found needs to spell out the `-Ossl.cert_reqs=none` parameter for getting the old insecure behaviour, and maybe a pointer to more help.
* Perhaps the error shown when a self-signed certificate doesn't validate against the local store also wants some love.
* An entry in doc/en/whats-new/whats-new-in-2.5.txt needs adding spelling out the user-facing aspects of this change, as it's a nice improvement but some people may need to change their configuration on upgrading.

The mercurial wiki page linked earlier is a useful comparison:
<http://mercurial.selenic.com/wiki/CACertificates>

review: Needs Fixing

[Jelmer Vernooij (jelmer)]

> Summarising from earlier rambling chat:
>
> * The error shown when a certificate can't be checked because no local store
> is found needs to spell out the `-Ossl.cert_reqs=none` parameter for getting
> the old insecure behaviour, and maybe a pointer to more help.
> * Perhaps the error shown when a self-signed certificate doesn't validate
> against the local store also wants some love.
> * An entry in doc/en/whats-new/whats-new-in-2.5.txt needs adding spelling out
> the user-facing aspects of this change, as it's a nice improvement but some
> people may need to change their configuration on upgrading.

Done.

Ironically I can't actually run "bzr selftest -s bt.test_http" on my machine because pycurl triggers segfaults (not just on this branch), but the changes are mostly documentation anyway.

[Martin Packman (gz)]

Added what's new text is great, and the new logic for printing helpful messages seems good. Some of these messages could probably do with gettext() added, but that can wait for another branch when the rest of the module can be looked over too.

- if cert_reqs == "none":
+ if cert_reqs == ssl.CERT_NONE:

Seen in the interdiff for the last change, was this broken before, and did a test fail because of it?

review: Approve

[Jelmer Vernooij (jelmer)]

sent to pqm by email

[Jelmer Vernooij (jelmer)]

sent to pqm by email

[Jelmer Vernooij (jelmer)]

sent to pqm by email

[Jelmer Vernooij (jelmer)]

> Added what's new text is great, and the new logic for printing helpful
> messages seems good. Some of these messages could probably do with gettext()
> added, but that can wait for another branch when the rest of the module can be
> looked over too.
>
> - if cert_reqs == "none":
> + if cert_reqs == ssl.CERT_NONE:
>
> Seen in the interdiff for the last change, was this broken before, and did a
> test fail because of it?
Yeah, it was indeed broken - and I hadn't noticed since we don't have a test for it. There is an open bug about doing more testing with SSL certificates.

[Vincent Ladeuil (vila)]

Will look into it asap but at least the news needs to be fixed.

review: Needs Fixing

=== modified file 'bzrlib/config.py'
--- bzrlib/config.py	2012-01-05 14:10:32 +0000
+++ bzrlib/config.py	2012-01-07 00:08:23 +0000
@@ -2867,6 +2867,13 @@
     Option('submit_to',
            help='''Where submissions from this branch are mailed to.'''))
 
+option_registry.register_lazy('ssl.ca_certs',
+    'bzrlib.transport.http._urllib2_wrappers', 'opt_ssl_ca_certs')
+
+option_registry.register_lazy('ssl.cert_reqs',
+    'bzrlib.transport.http._urllib2_wrappers', 'opt_ssl_cert_reqs')
+
+
 
 class Section(object):
     """A section defines a dict of option name => value.

=== modified file 'bzrlib/errors.py'
--- bzrlib/errors.py	2011-12-22 15:33:16 +0000
+++ bzrlib/errors.py	2012-01-07 00:08:23 +0000
@@ -1667,6 +1667,14 @@
         TransportError.__init__(self, msg, orig_error=orig_error)
 
 
+class CertificateError(TransportError):
+
+    _fmt = "Certificate error: %(error)s"
+
+    def __init__(self, error):
+        self.error = error
+
+
 class InvalidHttpRange(InvalidHttpResponse):
 
     _fmt = "Invalid http range %(range)r for %(path)s: %(msg)s"

=== modified file 'bzrlib/tests/__init__.py'
--- bzrlib/tests/__init__.py	2011-12-24 10:10:59 +0000
+++ bzrlib/tests/__init__.py	2012-01-07 00:08:23 +0000
@@ -4002,6 +4002,7 @@
         'bzrlib.tests.test_http',
         'bzrlib.tests.test_http_response',
         'bzrlib.tests.test_https_ca_bundle',
+        'bzrlib.tests.test_https_urllib',
         'bzrlib.tests.test_i18n',
         'bzrlib.tests.test_identitymap',
         'bzrlib.tests.test_ignores',

=== modified file 'bzrlib/tests/test_http.py'
--- bzrlib/tests/test_http.py	2011-10-12 16:00:13 +0000
+++ bzrlib/tests/test_http.py	2012-01-07 00:08:23 +0000
@@ -32,7 +32,6 @@
 import bzrlib
 from bzrlib import (
     bzrdir,
-    cethread,
     config,
     debug,
     errors,

=== added file 'bzrlib/tests/test_https_urllib.py'
--- bzrlib/tests/test_https_urllib.py	1970-01-01 00:00:00 +0000
+++ bzrlib/tests/test_https_urllib.py	2012-01-07 00:08:23 +0000
@@ -0,0 +1,109 @@
+# Copyright (C) 2011 Canonical Ltd
+#
+# This program is free software; you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation; either version 2 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program; if not, write to the Free Software
+# Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
+
+"""Tests for the SSL support in the urllib HTTP transport.
+
+"""
+
+import ssl
+
+from bzrlib import trace
+from bzrlib.errors import (
+    CertificateError,
+    ConfigOptionValueError,
+    )
+from bzrlib.config import (
+    IniFileStore,
+    Stack,
+    )
+import os
+from bzrlib.tests import (
+    TestCase,
+    TestCaseInTempDir,
+    )
+from bzrlib.transport.http import _urllib2_wrappers
+
+
+def stack_from_string(text):
+    store = IniFileStore()
+    store._load_from_string(text)
+    return Stack([store.get_sections])
+
+
+class CaCertsConfigTests(TestCaseInTempDir):
+
+    def test_default_raises_value_error(self):
+        stack = stack_from_string("")
+        self.overrideAttr(_urllib2_wrappers, "DEFAULT_CA_PATH",
+                "/i-do-not-exist")
+        self.assertRaises(ValueError, stack.get, 'ssl.ca_certs')
+
+    def test_default_exists(self):
+        self.build_tree(['cacerts.pem'])
+        stack = stack_from_string("")
+        path = os.path.join(self.test_dir, "cacerts.pem")
+        self.overrideAttr(_urllib2_wrappers, "DEFAULT_CA_PATH", path)
+        self.assertEquals(path, stack.get('ssl.ca_certs'))
+
+    def test_specified(self):
+        self.build_tree(['cacerts.pem'])
+        path = os.path.join(self.test_dir, "cacerts.pem")
+        stack = stack_from_string("ssl.ca_certs = %s\n" % path)
+        self.assertEquals(path, stack.get('ssl.ca_certs'))
+
+    def test_specified_doesnt_exist(self):
+        path = os.path.join(self.test_dir, "nonexisting.pem")
+        stack = stack_from_string("ssl.ca_certs = %s\n" % path)
+        self.warnings = []
+        def warning(*args):
+            self.warnings.append(args[0] % args[1:])
+        self.overrideAttr(trace, 'warning', warning)
+        self.assertEquals(_urllib2_wrappers.DEFAULT_CA_PATH, stack.get('ssl.ca_certs'))
+        self.assertLength(1, self.warnings)
+        self.assertContainsRe(self.warnings[0], "is not valid for \"ssl.ca_certs\"")
+
+
+class CertReqsConfigTests(TestCaseInTempDir):
+
+    def test_default(self):
+        stack = stack_from_string("")
+        self.assertEquals(ssl.CERT_REQUIRED, stack.get("ssl.cert_reqs"))
+
+    def test_from_string(self):
+        stack = stack_from_string("ssl.cert_reqs = none\n")
+        self.assertEquals(ssl.CERT_NONE, stack.get("ssl.cert_reqs"))
+        stack = stack_from_string("ssl.cert_reqs = optional\n")
+        self.assertEquals(ssl.CERT_OPTIONAL, stack.get("ssl.cert_reqs"))
+        stack = stack_from_string("ssl.cert_reqs = required\n")
+        self.assertEquals(ssl.CERT_REQUIRED, stack.get("ssl.cert_reqs"))
+        stack = stack_from_string("ssl.cert_reqs = invalid\n")
+        self.assertRaises(ConfigOptionValueError, stack.get, "ssl.cert_reqs")
+
+
+class MatchHostnameTests(TestCase):
+
+    def test_no_certificate(self):
+        self.assertRaises(ValueError, _urllib2_wrappers.match_hostname({}))
+
+    def test_no_valid_attributes(self):
+        self.assertRaises(CertificateError,
+            _urllib2_wrappers.match_hostname({"Problem": "Solved"}))
+
+    def test_common_name(self):
+        cert = {'subject': ((('commonName', 'example.com'),),)}
+        self.assertIs(None, _urllib2_wrappers.match_hostname(cert, "example.com"))
+        self.assertRaises(CertificateError, _urllib2_wrappers.match_hostname,
+                cert, "example.org")

=== modified file 'bzrlib/transport/__init__.py'
--- bzrlib/transport/__init__.py	2011-12-24 10:10:59 +0000
+++ bzrlib/transport/__init__.py	2012-01-07 00:08:23 +0000
@@ -1782,15 +1782,15 @@
                  help="Read-only access of branches exported on the web.")
 register_transport_proto('https://',
             help="Read-only access of branches exported on the web using SSL.")
-# The default http implementation is urllib, but https is pycurl if available
+# The default http implementation is urllib
 register_lazy_transport('http://', 'bzrlib.transport.http._pycurl',
                         'PyCurlTransport')
+register_lazy_transport('https://', 'bzrlib.transport.http._pycurl',
+                        'PyCurlTransport')
 register_lazy_transport('http://', 'bzrlib.transport.http._urllib',
                         'HttpTransport_urllib')
 register_lazy_transport('https://', 'bzrlib.transport.http._urllib',
                         'HttpTransport_urllib')
-register_lazy_transport('https://', 'bzrlib.transport.http._pycurl',
-                        'PyCurlTransport')
 
 register_transport_proto('ftp://', help="Access using passive FTP.")
 register_lazy_transport('ftp://', 'bzrlib.transport.ftp', 'FtpTransport')

=== modified file 'bzrlib/transport/http/_urllib2_wrappers.py'
--- bzrlib/transport/http/_urllib2_wrappers.py	2011-12-19 13:23:58 +0000
+++ bzrlib/transport/http/_urllib2_wrappers.py	2012-01-07 00:08:23 +0000
@@ -14,7 +14,7 @@
 # along with this program; if not, write to the Free Software
 # Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
 
-"""Implementaion of urllib2 tailored to bzr needs
+"""Implementation of urllib2 tailored to bzr needs
 
 This file complements the urllib2 class hierarchy with custom classes.
 
@@ -50,6 +50,7 @@
 
 import errno
 import httplib
+import os
 import socket
 import urllib
 import urllib2
@@ -63,12 +64,68 @@
     config,
     debug,
     errors,
+    lazy_import,
     osutils,
     trace,
     transport,
     urlutils,
     )
-
+lazy_import.lazy_import(globals(), """
+import ssl
+""")
+
+DEFAULT_CA_PATH = u"/etc/ssl/certs/ca-certificates.crt"
+
+
+def default_ca_certs():
+    if not os.path.exists(DEFAULT_CA_PATH):
+        raise ValueError("default ca certs path %s does not exist" %
+            DEFAULT_CA_PATH)
+    return DEFAULT_CA_PATH
+
+
+def ca_certs_from_store(path):
+    if not os.path.exists(path):
+        raise ValueError("ca certs path %s does not exist" % path)
+    return path
+
+
+def default_cert_reqs():
+    return u"required"
+
+
+def cert_reqs_from_store(unicode_str):
+    import ssl
+    try:
+        return {
+            "required": ssl.CERT_REQUIRED,
+            "optional": ssl.CERT_OPTIONAL,
+            "none": ssl.CERT_NONE
+            }[unicode_str]
+    except KeyError:
+        raise ValueError("invalid value %s" % unicode_str)
+
+
+opt_ssl_ca_certs = config.Option('ssl.ca_certs',
+        from_unicode=ca_certs_from_store,
+        default=default_ca_certs,
+        invalid='warning',
+        help="""\
+Path to certification authority certificates to trust.
+""")
+
+opt_ssl_cert_reqs = config.Option('ssl.cert_reqs',
+        default=default_cert_reqs,
+        from_unicode=cert_reqs_from_store,
+        invalid='error',
+        help="""\
+Whether to require a certificate from the remote side. (default:required)
+
+Possible values:
+ * none: certificates ignored
+ * optional: Certificates not required, but validated if provided
+ * required: Certificates required, and validated
+""")
 
 checked_kerberos = False
 kerberos = None
@@ -312,17 +369,60 @@
         self._wrap_socket_for_reporting(self.sock)
 
 
-# Build the appropriate socket wrapper for ssl
-try:
-    # python 2.6 introduced a better ssl package
-    import ssl
-    _ssl_wrap_socket = ssl.wrap_socket
-except ImportError:
-    # python versions prior to 2.6 don't have ssl and ssl.wrap_socket instead
-    # they use httplib.FakeSocket
-    def _ssl_wrap_socket(sock, key_file, cert_file):
-        ssl_sock = socket.ssl(sock, key_file, cert_file)
-        return httplib.FakeSocket(sock, ssl_sock)
+# These two methods were imported from Python 3.2's ssl module
+
+def _dnsname_to_pat(dn):
+    pats = []
+    for frag in dn.split(r'.'):
+        if frag == '*':
+            # When '*' is a fragment by itself, it matches a non-empty dotless
+            # fragment.
+            pats.append('[^.]+')
+        else:
+            # Otherwise, '*' matches any dotless fragment.
+            frag = re.escape(frag)
+            pats.append(frag.replace(r'\*', '[^.]*'))
+    return re.compile(r'\A' + r'\.'.join(pats) + r'\Z', re.IGNORECASE)
+
+
+def match_hostname(cert, hostname):
+    """Verify that *cert* (in decoded format as returned by
+    SSLSocket.getpeercert()) matches the *hostname*.  RFC 2818 rules
+    are mostly followed, but IP addresses are not accepted for *hostname*.
+
+    CertificateError is raised on failure. On success, the function
+    returns nothing.
+    """
+    if not cert:
+        raise ValueError("empty or no certificate")
+    dnsnames = []
+    san = cert.get('subjectAltName', ())
+    for key, value in san:
+        if key == 'DNS':
+            if _dnsname_to_pat(value).match(hostname):
+                return
+            dnsnames.append(value)
+    if not san:
+        # The subject is only checked when subjectAltName is empty
+        for sub in cert.get('subject', ()):
+            for key, value in sub:
+                # XXX according to RFC 2818, the most specific Common Name
+                # must be used.
+                if key == 'commonName':
+                    if _dnsname_to_pat(value).match(hostname):
+                        return
+                    dnsnames.append(value)
+    if len(dnsnames) > 1:
+        raise errors.CertificateError("hostname %r "
+            "doesn't match either of %s"
+            % (hostname, ', '.join(map(repr, dnsnames))))
+    elif len(dnsnames) == 1:
+        raise errors.CertificateError("hostname %r "
+            "doesn't match %r"
+            % (hostname, dnsnames[0]))
+    else:
+        raise errors.CertificateError("no appropriate commonName or "
+            "subjectAltName fields were found")
 
 
 class HTTPSConnection(AbstractHTTPConnection, httplib.HTTPSConnection):
@@ -345,7 +445,35 @@
             self.connect_to_origin()
 
     def connect_to_origin(self):
-        ssl_sock = _ssl_wrap_socket(self.sock, self.key_file, self.cert_file)
+        # FIXME JRV 2011-12-18: Use location config here?
+        config_stack = config.GlobalStack()
+        ca_certs = config_stack.get('ssl.ca_certs')
+        cert_reqs = config_stack.get('ssl.cert_reqs')
+        if cert_reqs == ssl.CERT_NONE:
+            trace.warning("not checking SSL certificates for %s: %d",
+                self.host, self.port)
+        else:
+            if ca_certs is None:
+                trace.warning(
+                    "no valid trusted SSL CA certificates file set. See "
+                    "'bzr help ssl.ca_certs' for more information on setting "
+                    "trusted CA's.")
+        try:
+            ssl_sock = ssl.wrap_socket(self.sock, self.key_file, self.cert_file,
+                cert_reqs=cert_reqs, ca_certs=ca_certs)
+        except ssl.SSLError, e:
+            if e.errno != ssl.SSL_ERROR_SSL:
+                raise
+            trace.note(
+                "To disable SSL certificate verification, use "
+                "-Ossl.cert_reqs=none. See ``bzr help ssl.ca_certs`` for "
+                "more information on specifying trusted CA certificates.")
+            raise
+        peer_cert = ssl_sock.getpeercert()
+        if (cert_reqs == ssl.CERT_REQUIRED or
+            (cert_reqs == ssl.CERT_OPTIONAL and peer_cert)):
+            match_hostname(peer_cert, self.host)
+
         # Wrap the ssl socket before anybody use it
         self._wrap_socket_for_reporting(ssl_sock)
 

=== modified file 'doc/en/release-notes/bzr-2.5.txt'
--- doc/en/release-notes/bzr-2.5.txt	2012-01-06 14:09:04 +0000
+++ doc/en/release-notes/bzr-2.5.txt	2012-01-07 00:08:23 +0000
@@ -479,6 +479,12 @@
   to 'line-based'. This replace the previous shelf UI only patch using
   ``INSIDE_EMACS``. (Benoît Pierre)
 
+* urllib-based HTTPS client connections now verify the server certificate
+  as well as the hostname. (Jelmer Vernooij)
+
+* urllib-based HTTPS connections are now the default.
+  (Jelmer Vernooij, #125055, #651161)
+
 Bug Fixes
 *********
 

=== modified file 'doc/en/whats-new/whats-new-in-2.5.txt'
--- doc/en/whats-new/whats-new-in-2.5.txt	2012-01-03 16:28:43 +0000
+++ doc/en/whats-new/whats-new-in-2.5.txt	2012-01-07 00:08:23 +0000
@@ -36,6 +36,23 @@
 encoding for interacting with the filesystem. This makes creating a working
 tree and commiting to it possible for such branches in most environments.
 
+SSL Certificate Verification Support in urllib HTTPS backend
+************************************************************
+
+In previous versions of Bazaar, only one of the two supported HTTPS
+backends, pycurl, supported verification of SSL certificates. This version
+also introduces this support for the urllib backend.
+
+Along with this support two new options have been introduced to control
+which CA's are trusted and to what degree server certificates should be
+verified. See ``bzr help ssl.ca_certs`` and ``bzr help ssl.cert_reqs``
+for more information
+
+Users who have previously used the urllib HTTPS backend with servers
+with invalid or untrusted certificates can continue to do so by
+adding the required certificates to the trusted CA certificate file
+(recommended) or by setting the ``ssl.cert_reqs`` option to ``none``.
+
 Faster smart server
 *******************