From 136a1e89278070fd100f27d9519529be8a8a8c10 Mon Sep 17 00:00:00 2001 From: Igor Scheller Date: Tue, 21 Jan 2025 23:34:23 +0100 Subject: [PATCH] Refs 35653 -- Clarified docs for EMAIL_SSL_CERTFILE and EMAIL_SSL_KEYFILE settings. --- docs/ref/settings.txt | 25 ++++++++++++++++++++----- 1 file changed, 20 insertions(+), 5 deletions(-) diff --git a/docs/ref/settings.txt b/docs/ref/settings.txt index 9bd5aedbed..556cbb4b1e 100644 --- a/docs/ref/settings.txt +++ b/docs/ref/settings.txt @@ -1502,9 +1502,24 @@ exclusive, so only set one of those settings to ``True``. Default: ``None`` -If :setting:`EMAIL_USE_SSL` or :setting:`EMAIL_USE_TLS` is ``True``, you can -optionally specify the path to a PEM-formatted certificate chain file to use -for the SSL connection. +If :setting:`EMAIL_USE_SSL` or :setting:`EMAIL_USE_TLS` is ``True`` and the +secure connection to the SMTP server requires client authentication, use this +setting to specify the path to a PEM-formatted certificate chain file, which +must be used in conjunction with :setting:`EMAIL_SSL_KEYFILE`. + +``EMAIL_SSL_CERTFILE`` should not be used with a self-signed server certificate +or a certificate from a private certificate authority (CA). In such cases, the +server's certificate (or the root certificate of the private CA) should be +installed into the system's CA bundle. This can be done by following +platform-specific instructions for installing a root CA certificate, +or by using OpenSSL's ``SSL_CERT_FILE`` or ``SSL_CERT_DIR`` environment +variables to specify a custom certificate bundle (if modifying the system +bundle is not possible or desired). + +For more complex scenarios, the SMTP +:class:`~django.core.mail.backends.smtp.EmailBackend` can be subclassed to add +root certificates to its ``ssl_context`` using +:meth:`python:ssl.SSLContext.load_verify_locations`. .. setting:: EMAIL_SSL_KEYFILE @@ -1514,8 +1529,8 @@ for the SSL connection. Default: ``None`` If :setting:`EMAIL_USE_SSL` or :setting:`EMAIL_USE_TLS` is ``True``, you can -optionally specify the path to a PEM-formatted private key file to use for the -SSL connection. +optionally specify the path to a PEM-formatted private key file for client +authentication of the SSL connection along with :setting:`EMAIL_SSL_CERTFILE`. Note that setting :setting:`EMAIL_SSL_CERTFILE` and :setting:`EMAIL_SSL_KEYFILE` doesn't result in any certificate checking. They're passed to the underlying SSL