Patch 10124 by Bill Janssen, docs for the new ssl code.

Doc/library/ipc.rst

@@ -19,6 +19,7 @@ The list of modules described in this chapter is:
 
    subprocess.rst
    socket.rst
+   ssl.rst
    signal.rst
    popen2.rst
    asyncore.rst

Doc/library/socket.rst

@@ -7,7 +7,7 @@
 
 
 This module provides access to the BSD *socket* interface. It is available on
-all modern Unix systems, Windows, MacOS, BeOS, OS/2, and probably additional
+all modern Unix systems, Windows, Mac OS X, BeOS, OS/2, and probably additional
 platforms.
 
 .. note::
@@ -300,17 +300,6 @@ The module :mod:`socket` exports the following constants and functions:
    omitted in that case.
 
 
-.. function:: ssl(sock[, keyfile, certfile])
-
-   Initiate a SSL connection over the socket *sock*. *keyfile* is the name of a PEM
-   formatted file that contains your private key. *certfile* is a PEM formatted
-   certificate chain file. On success, a new :class:`SSLObject` is returned.
-
-   .. warning::
-
-      This does not do any certificate verification!
-
-
 .. function:: socketpair([family[, type[, proto]]])
 
    Build a pair of connected socket objects using the given address family, socket
@@ -752,49 +741,6 @@ values given to the :class:`socket` constructor.
    .. versionadded:: 2.5
 
 
-.. _ssl-objects:
-
-SSL Objects
------------
-
-SSL objects have the following methods.
-
-
-.. method:: SSL.write(s)
-
-   Writes the string *s* to the on the object's SSL connection. The return value is
-   the number of bytes written.
-
-
-.. method:: SSL.read([n])
-
-   If *n* is provided, read *n* bytes from the SSL connection, otherwise read until
-   EOF. The return value is a string of the bytes read.
-
-
-.. method:: SSL.server()
-
-   Returns a string describing the server's certificate.  Useful for
-   debugging purposes; do not parse the content of this string because
-   its format can't be parsed unambiguously.  And don't *trust* the
-   content of this string, because certificates aren't validated if you
-   use the function :func:`ssl` to create an SSL binding.  If you need to
-   see the content of a peer certificate, you should use the
-   :func:`sslsocket` function in the :mod:`ssl` module to create the SSL
-   object, specifying the parameter `cert_req` as :const:`CERT_REQUIRED`,
-   and passing the name of a file containing a collection of certificates
-   to use to validate the peer certificate as the value of the `ca_certs`
-   parameter.  Then use the :meth:`getpeercert` method on that instance
-   to retrieve the contents of the certificate.
-
-
-.. method:: SSL.issuer()
-
-   Returns a string describing the issuer of the server's certificate. Useful for
-   debugging purposes; do not parse the content of this string because its format
-   can't be parsed unambiguously.
-
-
 .. _socket-example:
 
 Example
@@ -912,39 +858,3 @@ sends traffic to the first one connected successfully. ::
    s.close()
    print 'Received', repr(data)
 
-This example connects to an SSL server, prints the  server and issuer's
-distinguished names, sends some bytes, and reads part of the response::
-
-   import socket
-
-   s = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
-   s.connect(('www.verisign.com', 443))
-
-   ssl_sock = socket.ssl(s)
-
-   print repr(ssl_sock.server())
-   print repr(ssl_sock.issuer())
-
-   # Set a simple HTTP request -- use httplib in actual code.
-   ssl_sock.write("""GET / HTTP/1.0\r
-   Host: www.verisign.com\r\n\r\n""")
-
-   # Read a chunk of data.  Will not necessarily
-   # read all the data returned by the server.
-   data = ssl_sock.read()
-
-   # Note that you need to close the underlying socket, not the SSL object.
-   del ssl_sock
-   s.close()
-
-At this writing, this SSL example prints the following output (line breaks
-inserted for readability)::
-
-   '/C=US/ST=California/L=Mountain View/
-    O=VeriSign, Inc./OU=Production Services/
-    OU=Terms of use at www.verisign.com/rpa (c)00/
-    CN=www.verisign.com'
-   '/O=VeriSign Trust Network/OU=VeriSign, Inc./
-    OU=VeriSign International Server CA - Class 3/
-    OU=www.verisign.com/CPS Incorp.by Ref. LIABILITY LTD.(c)97 VeriSign'
-

Doc/library/urllib2.rst

@@ -69,7 +69,7 @@ The :mod:`urllib2` module defines the following functions:
    :class:`HTTPRedirectHandler`, :class:`FTPHandler`, :class:`FileHandler`,
    :class:`HTTPErrorProcessor`.
 
-   If the Python installation has SSL support (:func:`socket.ssl` exists),
+   If the Python installation has SSL support (i.e., if the :mod:`ssl` module can be imported),
    :class:`HTTPSHandler` will also be added.
 
    Beginning in Python 2.3, a :class:`BaseHandler` subclass may also change its