Skip to content

Commit 9213226

Browse files
dbIgelnessita
authored andcommitted
[5.1.x] Refs 35653 -- Clarified docs for EMAIL_SSL_CERTFILE and EMAIL_SSL_KEYFILE settings.
Backport of 136a1e8 from main.
1 parent db56307 commit 9213226

File tree

1 file changed

+20
-5
lines changed

1 file changed

+20
-5
lines changed

docs/ref/settings.txt

Lines changed: 20 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1502,9 +1502,24 @@ exclusive, so only set one of those settings to ``True``.
15021502

15031503
Default: ``None``
15041504

1505-
If :setting:`EMAIL_USE_SSL` or :setting:`EMAIL_USE_TLS` is ``True``, you can
1506-
optionally specify the path to a PEM-formatted certificate chain file to use
1507-
for the SSL connection.
1505+
If :setting:`EMAIL_USE_SSL` or :setting:`EMAIL_USE_TLS` is ``True`` and the
1506+
secure connection to the SMTP server requires client authentication, use this
1507+
setting to specify the path to a PEM-formatted certificate chain file, which
1508+
must be used in conjunction with :setting:`EMAIL_SSL_KEYFILE`.
1509+
1510+
``EMAIL_SSL_CERTFILE`` should not be used with a self-signed server certificate
1511+
or a certificate from a private certificate authority (CA). In such cases, the
1512+
server's certificate (or the root certificate of the private CA) should be
1513+
installed into the system's CA bundle. This can be done by following
1514+
platform-specific instructions for installing a root CA certificate,
1515+
or by using OpenSSL's ``SSL_CERT_FILE`` or ``SSL_CERT_DIR`` environment
1516+
variables to specify a custom certificate bundle (if modifying the system
1517+
bundle is not possible or desired).
1518+
1519+
For more complex scenarios, the SMTP
1520+
:class:`~django.core.mail.backends.smtp.EmailBackend` can be subclassed to add
1521+
root certificates to its ``ssl_context`` using
1522+
:meth:`python:ssl.SSLContext.load_verify_locations`.
15081523

15091524
.. setting:: EMAIL_SSL_KEYFILE
15101525

@@ -1514,8 +1529,8 @@ for the SSL connection.
15141529
Default: ``None``
15151530

15161531
If :setting:`EMAIL_USE_SSL` or :setting:`EMAIL_USE_TLS` is ``True``, you can
1517-
optionally specify the path to a PEM-formatted private key file to use for the
1518-
SSL connection.
1532+
optionally specify the path to a PEM-formatted private key file for client
1533+
authentication of the SSL connection along with :setting:`EMAIL_SSL_CERTFILE`.
15191534

15201535
Note that setting :setting:`EMAIL_SSL_CERTFILE` and :setting:`EMAIL_SSL_KEYFILE`
15211536
doesn't result in any certificate checking. They're passed to the underlying SSL

0 commit comments

Comments
 (0)