Merge pull request #1897 from aliles/master

Document requirements for SNI support on Python2

docs/community/faq.rst

@@ -60,3 +60,26 @@ 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 <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) and
+you're using Python 2.6 or 2.7, a possible explanation is that you need
+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

docs/user/advanced.rst

@@ -145,6 +145,8 @@ applied, replace the call to :meth:`Request.prepare()
 
     print(resp.status_code)
 
+.. _verification:
+
 SSL Cert Verification
 ---------------------