Server-side SSL and certificate validation, by Bill Janssen.

While cleaning up Bill's C style, I may have cleaned up some code
he didn't touch as well (in _ssl.c).

1 files changed, 12 insertions, 3 deletions

diff --git a/Doc/library/socket.rst b/Doc/library/socket.rst
index 9acd7d2..9bbe79b 100644
--- a/Doc/library/socket.rst
+++ b/Doc/library/socket.rst
@@ -774,9 +774,18 @@ SSL objects have the following methods.
 
 .. 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.
+   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()