summaryrefslogtreecommitdiffstats
path: root/Doc/library/poplib.rst
diff options
context:
space:
mode:
authorAntoine Pitrou <solipsis@pitrou.net>2014-03-22 17:19:11 (GMT)
committerAntoine Pitrou <solipsis@pitrou.net>2014-03-22 17:19:11 (GMT)
commitc5e075ff03693934ef50b1cde130ccf8dfda3843 (patch)
treeeb66c49abff1185f2f1f63f61c6aa67a18aa7f4e /Doc/library/poplib.rst
parent0bebbc33faae7ac10e7a7980b260e786f05d81bf (diff)
downloadcpython-c5e075ff03693934ef50b1cde130ccf8dfda3843.zip
cpython-c5e075ff03693934ef50b1cde130ccf8dfda3843.tar.gz
cpython-c5e075ff03693934ef50b1cde130ccf8dfda3843.tar.bz2
Issue #20913: improve the SSL security considerations to first advocate using create_default_context().
Diffstat (limited to 'Doc/library/poplib.rst')
-rw-r--r--Doc/library/poplib.rst29
1 files changed, 17 insertions, 12 deletions
diff --git a/Doc/library/poplib.rst b/Doc/library/poplib.rst
index fa1db01..bc7b3e7 100644
--- a/Doc/library/poplib.rst
+++ b/Doc/library/poplib.rst
@@ -43,20 +43,23 @@ The :mod:`poplib` module provides two classes:
This is a subclass of :class:`POP3` that connects to the server over an SSL
encrypted socket. If *port* is not specified, 995, the standard POP3-over-SSL
- port is used. *keyfile* and *certfile* are also optional - they can contain a
- PEM formatted private key and certificate chain file for the SSL connection.
- *timeout* works as in the :class:`POP3` constructor. *context* parameter is a
- :class:`ssl.SSLContext` object which allows bundling SSL configuration
- options, certificates and private keys into a single (potentially long-lived)
- structure.
+ port is used. *timeout* works as in the :class:`POP3` constructor.
+ *context* is an optional :class:`ssl.SSLContext` object which allows
+ bundling SSL configuration options, certificates and private keys into a
+ single (potentially long-lived) structure. Please read :ref:`ssl-security`
+ for best practices.
+
+ *keyfile* and *certfile* are a legacy alternative to *context* - they can
+ point to PEM-formatted private key and certificate chain files,
+ respectively, for the SSL connection.
.. versionchanged:: 3.2
*context* parameter added.
.. versionchanged:: 3.4
The class now supports hostname check with
- :attr:`SSLContext.check_hostname` and *Server Name Indicator* (see
- :data:`~ssl.HAS_SNI`).
+ :attr:`ssl.SSLContext.check_hostname` and *Server Name Indication* (see
+ :data:`ssl.HAS_SNI`).
One exception is defined as an attribute of the :mod:`poplib` module:
@@ -198,10 +201,12 @@ An :class:`POP3` instance has the following methods:
*context* parameter is a :class:`ssl.SSLContext` object which allows
bundling SSL configuration options, certificates and private keys into
- a single (potentially long-lived) structure. This method supports
- hostname checking via :attr:`SSLContext.check_hostname`
- :attr:`SSLContext.check_hostname` and *Server Name Indicator* (see
- :data:`~ssl.HAS_SNI`).
+ a single (potentially long-lived) structure. Please read :ref:`ssl-security`
+ for best practices.
+
+ This method supports hostname checking via
+ :attr:`ssl.SSLContext.check_hostname` and *Server Name Indication* (see
+ :data:`ssl.HAS_SNI`).
.. versionadded:: 3.4