[Mailer] Document the S/MIME listeners alignment with PGP/MIME

mailer.rst

@@ -1675,6 +1675,20 @@
     a :ref:`MessageEvent <messageevent>` listener run after it (you need to set
     a negative priority to your listener).
 
+.. note::
+
+    When configured globally, S/MIME signing runs before S/MIME encryption, so
+    that the signature is protected by the encryption, and DKIM signing runs
+    last, on the message that is actually transmitted. Their listeners expose
+    their priorities as ``SmimeSignedMessageListener::PRIORITY`` (``-128``),
+    ``SmimeEncryptedMessageListener::PRIORITY`` (``-200``) and
+    ``DkimSignedMessageListener::PRIORITY`` (``-228``).
+
+    .. versionadded:: 8.2
+
+        These ``PRIORITY`` constants and the resulting deterministic ordering
+        were introduced in Symfony 8.2.
+
 Signing Messages
 ~~~~~~~~~~~~~~~~
 
@@ -1866,26 +1880,85 @@
             mailer:
                 smime_encrypter:
                     enabled: true
-                    repository: App\Security\LocalFileCertificateRepository
+                    # define the recipient certificates explicitly...
+                    certificates:
+                        'jane@example.com': '%kernel.project_dir%/var/certificates/jane.crt'
+                    # ...or get them from a service (you can't use both options at the same time)
+                    # repository: App\Security\LocalFileCertificateRepository
+                    on_missing_certificate: 'fail'
+                    encrypt_for_sender: false
 
     .. code-block:: php
 
         // config/packages/mailer.php
         namespace Symfony\Component\DependencyInjection\Loader\Configurator;
 
-        use App\Security\LocalFileCertificateRepository;
+        // use App\Security\LocalFileCertificateRepository;
 
         return App::config([
             'framework' => [
                 'mailer' => [
                     'smime_encrypter' => [
                         'enabled' => true,
-                        'repository' => LocalFileCertificateRepository::class,
+                        // define the recipient certificates explicitly...
+                        'certificates' => [
+                            'jane@example.com' => '%kernel.project_dir%/var/certificates/jane.crt',
+                        ],
+                        // ...or get them from a service (you can't use both options at the same time)
+                        // 'repository' => LocalFileCertificateRepository::class,
+                        'on_missing_certificate' => 'fail',
+                        'encrypt_for_sender' => false,
                     ],
                 ],
             ],
         ]);
 
+.. versionadded:: 8.2
+
+    The ``certificates``, ``on_missing_certificate`` and ``encrypt_for_sender``
+    options were introduced in Symfony 8.2.
+
+The ``on_missing_certificate`` option defines what to do when some recipient has
+no certificate:
+
+``send_unencrypted`` (default)
+    Send the message unencrypted to everyone;
+``fail``
+    Throw a :class:`Symfony\\Component\\Mailer\\Exception\\RuntimeException`
+    naming every recipient without a certificate;
+``encrypt``
+    Encrypt for the recipients that have a certificate; the others still receive
+    the message, but they can't read it;
+``skip``
+    Encrypt for the recipients that have a certificate and remove the others
+    from the envelope.
+
+Except for ``send_unencrypted``, all of them throw an exception when not a
+single recipient has a certificate, so a message is never sent unencrypted
+because of a missing certificate.
+
+.. deprecated:: 8.2
+
+    The ``send_unencrypted`` behavior is deprecated since Symfony 8.2 and will
+    throw an exception in Symfony 9.0. Set ``on_missing_certificate`` to
+    ``fail``, ``encrypt`` or ``skip`` instead.
+
+Set the value of the ``X-SMime-Encrypt`` header to ``fail``, ``encrypt`` or
+``skip`` to override the configured behavior for a single message. The header
+can't select ``send_unencrypted``, so it can never turn an encrypted message
+into a plaintext one.
+
+.. note::
+
+    The recipients dropped by the ``skip`` behavior are removed from the
+    envelope, but the ``framework.mailer.envelope.recipients`` option is applied
+    afterwards and overrides that list.
+
+Enable the ``encrypt_for_sender`` option to also encrypt the message for the
+sender, when a certificate is available for its address, so that the sender can
+read the messages it sent. It's disabled by default because it widens the number
+of people able to decrypt the message.
+
 The ``repository`` option is the ID of a service that implements
 :class:`Symfony\\Component\\Mailer\\EventListener\\SmimeCertificateRepositoryInterface`.
 This interface requires only one method: ``findCertificatePathFor()``, which must

reference/configuration/framework.rst

@@ -2887,8 +2887,61 @@ Bitwise operator options for :phpfunction:`openssl_pkcs7_sign`.
 smime_encrypter
 ...............
 
-Configures a global S/MIME encrypter that automatically encrypts all outgoing
-messages.
+Configures a global S/MIME encrypter that encrypts the outgoing messages having
+the ``X-SMime-Encrypt`` header.
+
+enabled
+"""""""
+
+**type**: ``boolean`` **default**: ``false``
+
+Whether to enable the S/MIME encrypter.
+
+certificates
+""""""""""""
+
+**type**: ``array`` **default**: ``[]``
+
+The certificates of the recipients, as a map of email address to certificate
+file path. It can't be used together with the ``repository`` option.
+
+.. versionadded:: 8.2
+
+    The ``certificates`` option was introduced in Symfony 8.2.
+
+on_missing_certificate
+""""""""""""""""""""""
+
+**type**: ``string`` **default**: ``'send_unencrypted'``
+
+The behavior when a recipient has no certificate: ``send_unencrypted`` sends the
+message unencrypted to everyone, ``fail`` throws an exception, ``encrypt``
+encrypts for the recipients that have a certificate (the others receive an
+unreadable message) and ``skip`` also drops the certificate-less recipients from
+the envelope. Except for ``send_unencrypted``, all of them throw an exception
+when not a single recipient has a certificate. It can be overridden per message
+by setting the ``X-SMime-Encrypt`` header to ``fail``, ``encrypt`` or ``skip``.
+
+.. versionadded:: 8.2
+
+    The ``on_missing_certificate`` option was introduced in Symfony 8.2.
+
+.. deprecated:: 8.2
+
+    The ``send_unencrypted`` value is deprecated since Symfony 8.2 and will
+    throw an exception in Symfony 9.0.
+
+encrypt_for_sender
+""""""""""""""""""
+
+**type**: ``boolean`` **default**: ``false``
+
+Whether to also encrypt the message for the sender, when a certificate is
+available for its address, so that the sender can read the messages it sent.
+
+.. versionadded:: 8.2
+
+    The ``encrypt_for_sender`` option was introduced in Symfony 8.2.
 
 repository
 """"""""""