diff options
| author | Igor Scheller <igor.scheller@deutschebahn.com> | 2025-01-21 23:34:23 +0100 |
|---|---|---|
| committer | GitHub <noreply@github.com> | 2025-01-21 19:34:23 -0300 |
| commit | 136a1e89278070fd100f27d9519529be8a8a8c10 (patch) | |
| tree | a95f5ade0d132d454b1577c52c904b8fd29bc9f9 /docs/ref | |
| parent | 862b7f98a02b7973848db578ff6d24ec8500fdb4 (diff) | |
Refs 35653 -- Clarified docs for EMAIL_SSL_CERTFILE and EMAIL_SSL_KEYFILE settings.
Diffstat (limited to 'docs/ref')
| -rw-r--r-- | docs/ref/settings.txt | 25 |
1 files 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 |