Skip to content

Latest commit

 

History

History
211 lines (152 loc) · 7.3 KB

smime.md

File metadata and controls

211 lines (152 loc) · 7.3 KB
Raw
title up
S/MIME
../customize.md#sympa-services-optional-features

S/MIME

  • S/MIME support was initially introduced on Sympa 2.7.

Sympa supports features of S/MIME version 2. It can verify the electronic signature of incoming messages, decrypt and re-encrypt them using users' certificates.

Requirements

  • Crypt-OpenSSL-X509 and Crypt-SMIME Perl modules.

    Note

    • On Sympa prior to 6.2, openssl(1) utility was required. It is no longer required but it can be a prerequisite to install the Perl modules mentioned above.

  • CA certificate: A certificate from a certificate authority (CA). To obtain a CA certificate, consult the issuer organization.

    Note

    • Several issuers provide one or more additional certificates, so-called "intermediate CA certificate", along with the "root CA certificate". If this is the case, you have to obtain all of those certificates. Certificate files have to be in PEM format.

  • Key pair (certificate and private key) of Sympa's address. The certificate is used by users to encrypt messages bound for Sympa. Sympa's private key is used by Sympa to decrypt these incoming messages.

    You can either issue a certificate by your own, or use a certificate issued by an appropriate CA.

Setup

Sympa configuration parameters

The following parameters in sympa.conf are necessary to configure S/MIME support.

  • cafile and capath

    Paths of trusted certificate stores. cafile is the path to a file including concatenated one or more certificates in PEM format. capath is the path to the directory containing one or more certificates in PEM format, whose file names are linked by hashed name using c_rehash(1) utility.

    Note

    • Some binary distributions provide c_rehash script with openssl package. Some others provide alternative script (for example, RHEL/CentOS provides cacertdir_rehash script with authconfig package).

  • key_passwd

    Passphrase to decrypt private key by which encrypted messages are decrypted, if the key is encrypted.

  • ssl_cert_dir

    Users' S/MIME certificates are saved in this directory (by default $EXPLDIR/X509-user-certs).

Note

  • Message with decrypted format may be temporarily put into the directory specified by tmpdir (by default $SPOOLDIR/tmp). Usually it should not be changed, but you should confirm that this directory is not exposed to public.

Sympa setup

  1. Create directories for certificates (Note: Replace $capath and $ssl_cert_dir below)::

    # mkdir $capath                (if capath parameter was set)
# chmod 755 $capth             (ditto)
# mkdir $ssl_cert_dir
# chmod 755 $ssl_cert_dir
# chown sympa $ssl_cert_dir

    Note that ssl_cert_dir directory must be writable by sympa user.

  2. Add appropriate parameters described in previous section to sympa.conf.

  3. Install the CA certificate(s) (see "Requirements") into the directory and/or the file. CA certificate files must be readable (but not writable) by sympa user.

  4. Install key pair of Sympa as these names:

    • cert.pem for certificate.
    • private_key for private key.

    They may be put in one of following directories:

    Note that they have to be readable by sympa user, however, private key must not be readable by other users.

Obtaining users' certificates

User's certificate is used to verify the signature of message, or to encrypt message delivered to each user.

Sympa obtains user's certificate from the incoming message automatically. Or, you can manually install it into ssl_cert_dir directory. Its file name is one of following by its usage:

Note

  • In fact, some punctuation characters included in email@add.ress have to be escaped to avoid limitation of filesystem encoding. By historical reason, escaping scheme is slightly wierd (escape_chars() in Sympa::Tools::Text is used). This will be fixed in a future release of Sympa.

User side setup

These certificates have to be distributed to users so that users may add them to trusted certificate store in the MUA (mailer) of their own.

  • CA certificate(s).
  • Certificate of Sympa.

Note

  • Private key must never be distributed.

How it works

Verifying S/MIME signature

  1. A user sends a message signed using his/her private key.

  2. Sympa verifies the S/MIME signature of the incoming message using the certificate included within it (or, use certificates cached in ssl_cert_dir directory).

  3. If verification succeeds, smime authentication method is assigned to the message, and it is used by the corresponding scenario (see "Authorization scenarios", particularly "Authentication methods").

Sympa does not alter signed messages: Decoration (adding "header" and "footer") and personalization are not applied to messages delivered with standard reception mode (see also "Does Sympa alter messages?").

Handling encrypted message

For the first time, users who want to receive encrypted messages through Sympa have to send a message signed by their private key to Sympa's address. Sympa extracts user's certificate from this message.

Once the certificate is obtained by Sympa, message encryption becomes available for that user. The publication mechanism for encrypted messages is as follows:

  1. A user sends a message encrypted using Sympa's certificate.

  2. Sympa tries to decrypt the incoming message using its private key (if decrypted message is signed, it also verifies the signature as described in the previous section).

    If decryption fails, the encrypted message is delivered intact.

  3. If decryption succeeds, Sympa will deliver the message to every subscriber in the list, encrypting it with every recipient's certificate.

    If encryption fails (e.g. recipient's certificate is not found), Sympa will deliver a message informing about the failure instead (mail template mail_tt2/x509-user-cert-missing.tt2 is used).