From: Antoine Pitrou <solipsis@pitrou.net>
Date: Tue, 16 Apr 2013 18:27:17 +0000 (+0200)
Subject: Issue #17739: fix the description of SSLSocket.getpeercert(binary_form=True) for... 
X-Git-Tag: v2.7.5~58
X-Git-Url: http://git.ipfire.org/gitweb.cgi?a=commitdiff_plain;h=f12f3916aa82e8d8a3b2f51f7c31db74ee5d898c;p=thirdparty%2FPython%2Fcpython.git

Issue #17739: fix the description of SSLSocket.getpeercert(binary_form=True) for server sockets.
Thanks to David D Lowe for reporting.
---

diff --git a/Doc/library/ssl.rst b/Doc/library/ssl.rst
index 1ddc0f7b4238..01072c458bb8 100644
--- a/Doc/library/ssl.rst
+++ b/Doc/library/ssl.rst
@@ -328,7 +328,7 @@ SSL sockets also have the following additional methods and attributes:
    If there is no certificate for the peer on the other end of the connection,
    returns ``None``.
 
-   If the parameter ``binary_form`` is :const:`False`, and a certificate was
+   If the ``binary_form`` parameter is :const:`False`, and a certificate was
    received from the peer, this method returns a :class:`dict` instance.  If the
    certificate was not validated, the dict is empty.  If the certificate was
    validated, it returns a dict with the keys ``subject`` (the principal for
@@ -354,10 +354,16 @@ SSL sockets also have the following additional methods and attributes:
    If the ``binary_form`` parameter is :const:`True`, and a certificate was
    provided, this method returns the DER-encoded form of the entire certificate
    as a sequence of bytes, or :const:`None` if the peer did not provide a
-   certificate.  This return value is independent of validation; if validation
-   was required (:const:`CERT_OPTIONAL` or :const:`CERT_REQUIRED`), it will have
-   been validated, but if :const:`CERT_NONE` was used to establish the
-   connection, the certificate, if present, will not have been validated.
+   certificate.  Whether the peer provides a certificate depends on the SSL
+   socket's role:
+
+   * for a client SSL socket, the server will always provide a certificate,
+     regardless of whether validation was required;
+
+   * for a server SSL socket, the client will only provide a certificate
+     when requested by the server; therefore :meth:`getpeercert` will return
+     :const:`None` if you used :const:`CERT_NONE` (rather than
+     :const:`CERT_OPTIONAL` or :const:`CERT_REQUIRED`).
 
 .. method:: SSLSocket.cipher()