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.

diff --git a/docs/community/faq.rst b/docs/community/faq.rst
index edbf9b70942a00adb7c2cf02136376f97d25ff1a..84c6b80a37dc11fcf2ff09ad694a2a1578f3ed12 100644 (file)
--- 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 <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 9df9f9b11a2910788fbe12f551dd7bbc89d9e0bd..80c1e6aeb07ffdb5bd85ed89d888b2d0c52a33c8 100644 (file)
--- 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
 ---------------------