From 8a0bae45c2efa8706c76d8af925d0dcd727cfc32 Mon Sep 17 00:00:00 2001 From: Aaron Iles Date: Sun, 2 Feb 2014 22:19:10 +1100 Subject: [PATCH] Move SNI documentation to FAQ Relocate documentation on Server-Name-Indication from the advanced section to the frequently asked questions. This is minus details on enabling SNI on Python2, which is instead captured by linking to Stack Overflow. --- docs/community/faq.rst | 22 ++++++++++++++++++++++ docs/user/advanced.rst | 27 ++------------------------- 2 files changed, 24 insertions(+), 25 deletions(-) diff --git a/docs/community/faq.rst b/docs/community/faq.rst index edbf9b7..84c6b80 100644 --- a/docs/community/faq.rst +++ b/docs/community/faq.rst @@ -60,3 +60,25 @@ supported: * Python 3.2 * Python 3.3 * PyPy 1.9 + +What are "hostname doesn't match" errors? +----------------------------------------- + +These errors occur when :ref:`SSL certificate verification ` +fails to match the certificate the server responds with to the hostname +Requests thinks it's contacting. If you're certain the server's SSL setup is +correct (for example, because you can visit the site with your browser) a +possible explanation is Request's is lacking Server-Name-Indication. + +`Server-Name-Indication`_, or SNI, is an official extension to SSL where the +client tells the server what hostname it is contacting. This enables `virtual +hosting`_ on SSL protected sites, the server being to able to respond with a +certificate appropriate for the hostname the client is contacting. + +Python3's SSL module includes native support for SNI. This support has not been +back ported to Python2. For information on using SNI with Requests on Python2 +refer to this `Stack Overflow answer`_. + +.. _`Server-Name-Indication`: https://en.wikipedia.org/wiki/Server_Name_Indication +.. _`virtual hosting`: https://en.wikipedia.org/wiki/Virtual_hosting +.. _`Stack Overflow answer`: https://stackoverflow.com/questions/18578439/using-requests-with-tls-doesnt-give-sni-support/18579484#18579484 diff --git a/docs/user/advanced.rst b/docs/user/advanced.rst index 9df9f9b..80c1e6a 100644 --- a/docs/user/advanced.rst +++ b/docs/user/advanced.rst @@ -145,6 +145,8 @@ applied, replace the call to :meth:`Request.prepare() print(resp.status_code) +.. _verification: + SSL Cert Verification --------------------- @@ -179,31 +181,6 @@ If you specify a wrong path or an invalid cert:: >>> requests.get('https://kennethreitz.com', cert='/wrong_path/server.pem') SSLError: [Errno 336265225] _ssl.c:347: error:140B0009:SSL routines:SSL_CTX_use_PrivateKey_file:PEM lib -Server Name Indication ----------------------- - -`Server Name Indication`_, or SNI, is an official extension to SSL where the -client tells the server what hostname it is contacting. This enables `virtual -hosting`_ on SSL protected sites. - -Python3's SSL module includes native support for SNI. This support has not been -back ported to Python2. However, Requests will enable SNI support on Python2 if -the following packages are installed: - -* `pyOpenSSL`_, a Python wrapper module around the OpenSSL library. -* `ndg-httpsclient`_, enhanced HTTPS support for httplib and urllib2. -* `pyasn1`_, ASN.1 types and codecs. - -When these packages are installed, Requests will automatically indicate to the -server what hostname is being contacted. This allows the server to return the -correct server certificate for SSL certificate verification. - -.. _`Server Name Indication`: https://en.wikipedia.org/wiki/Server_Name_Indication -.. _`virtual hosting`: https://en.wikipedia.org/wiki/Virtual_hosting -.. _`pyOpenSSL`: https://pypi.python.org/pypi/pyOpenSSL -.. _`ndg-httpsclient`: https://pypi.python.org/pypi/ndg-httpsclient -.. _`pyasn1`: https://pypi.python.org/pypi/pyasn1 - Body Content Workflow --------------------- -- 2.34.1