improve ssl exception text and docs

2 files changed, 56 insertions, 11 deletions

diff --git a/docs/logic.txt b/docs/logic.txt
index 00c832826..3b5fc3edd 100644
--- a/docs/logic.txt
+++ b/docs/logic.txt
@@ -161,10 +161,47 @@ of providing secure, certified downloads from PyPI.
 
 This is supported by default in all Python versions pip supports, except Python 2.5.
 
-Python 2.5 users can install https://pypi.python.org/pypi/ssl/, which provides ssl support for older pythons.
+Python 2.5 users can :ref:`install an SSL backport <SSL Backport>`, which provides ssl support for older pythons.
+Pip does not try to install this automatically because it requires a compiler, which not all systems will have.
 
-Although not recommended, Python 2.5 users who are unable to install ssl, can use the option,
-``--insecure``, to allow access to PyPI w/o attempting SSL certificate verification.
+Although not recommended, Python 2.5 users who are unable to install ssl, can use the global option,
+``--insecure``, to allow access to PyPI w/o attempting SSL certificate verification. This option will only be visible
+when ssl is not importable.  This is *not* a general option.
+
+
+.. _`SSL Backport`:
+
+Installing the SSL Backport
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. warning::
+
+    We advise against using ``pip`` itself to install the ssl backport, because it won't be secure
+    until *after* installing ssl.  Likewise, ``easy_install`` is not advised, because it
+    does not currently support ssl.
+
+
+1. Download the ssl archive:
+
+  * Using a Browser:
+
+    1. Go to `this url <https://pypi.python.org/pypi/ssl/1.15>`_.
+    2. Confirm the identity of the site is valid.
+       Most browsers provide this information to the left of the URL bar in the form of padlock icon that you can click on to confirm the site is verified.
+    3. Scroll down, and click to download ``ssl-1.15.tar.gz``.
+
+  * Using curl, which supports ssl certificate verification:
+     ::
+
+      $ curl -O https://pypi.python.org/packages/source/s/ssl/ssl-1.15.tar.gz
+
+2. Confirm the md5sum:
+   ::
+     $ md5sum ssl-1.15.tar.gz
+       81ea8a1175e437b4c769ae65b3290e0c  ssl-1.15.tar.gz
+
+3. Unpack the archive, and change into the ``ssl-1.15`` directory.
+4. Run: ``python setup.py install``.
 
 
 Hash Verification
diff --git a/pip/util.py b/pip/util.py
index 30bef7872..149a3f9c7 100644
--- a/pip/util.py
+++ b/pip/util.py
@@ -671,13 +671,21 @@ def call_subprocess(cmd, show_stdout=True,
 def raise_no_ssl_exception():
     """Raise when there's no ssl and not using '--no-ssl'"""
     raise PipError(textwrap.dedent("""
-            #############################################################
-            ##  You don't have an importable ssl module.               ##
-            ##  We can not provide ssl certified downloads.            ##
-            ##  Do one of 2 things:                                    ##
-            ##   1) Install this: https://pypi.python.org/pypi/ssl/    ##
-            ##      (It provides ssl support for older Pythons )       ##
-            ##   2) Use the --insecure option to allow insecurity      ##
-            #############################################################
+            ###################################################################
+            ##  You don't have an importable ssl module. You are most        ##
+            ##  likely using Python 2.5, which did not include ssl           ##
+            ##  support by default. In this state, we can not provide        ##
+            ##  ssl certified downloads from PyPI.                           ##
+            ##                                                               ##
+            ##  You can do one of 2 things:                                  ##
+            ##   1) Install this: https://pypi.python.org/pypi/ssl/          ##
+            ##      (It provides ssl support for older Pythons )             ##
+            ##   2) Use the --insecure option to allow this insecurity       ##
+            ##                                                               ##
+            ##  For more details, go to the  "SSL Certificate Verification"  ##
+            ##  section located here:                                        ##
+            ##     http://www.pip-installer.org/en/latest/logic.html         ##
+            ##                                                               ##
+            ###################################################################
             """))