exim-encrypt-dlfunc

This library injects functions for string encryption and decryption into exim4. It is basically glue code that exports certain parts of the libsodium library to exim at runtime.

Installation

These instructions are currently only tested on Debian and Ubuntu.

1. Install development tools and libsodium development files:

apt-get install -y build-essential exim4-dev libsodium-dev meson pkg-config openssl exim4-daemon-heavy

exim-encrypt-dlfunc uses meson (and ninja) as build system. To ensure all features are present (which are lacking in the version packages in older distributions) it is advised to install from pypi via pip:

apt-get install -y python3-pip
pip3 install meson ninja

You may alternatively use your distribution packages:

apt-get install -y meson

2. Clone this repository:

git clone https://git.scc.kit.edu/mail/exim-encrypt-dlfunc.git
cd exim-encrypt-dlfunc

3. Build and test everything:

meson build # run only once
meson compile -C build
meson test -C build

5. Copy to final destination (feel free to pick another place than /usr/lib/x86_64-linux-gnu/):

meson install -C build

6. Ensure you have the correct exim build:

   Not every build of exim is able to load libraries at runtime. Please refer to the documentation of the ${dlfunc{…}} function for details. The Debian package exim4-daemon-heavy meets these requirements.

Usage

There are currently two pairs of complementary functions:

Symmetric encryption that derives a key from an ASCII string (aka a “password”):

• sodium_crypto_secretbox_encrypt_password(password, cleartext) → ciphertext
• sodium_crypto_secretbox_decrypt_password(password, ciphertext) → cleartext

The generated key is only as strong as the provided password.

Public key encryption that uses a key pair which needs to be created beforehand:

• sodium_crypto_box_seal(public key, cleartext) → ciphertext
• sodium_crypto_box_seal_open(private key, public key, ciphertext) → cleartext

The second pair needs a proper key pair in the correct format. This is what the libexim-encrypt-dlfunc-genkeys utility is for. Simply run it once to generate a pair. Be aware that every invocation will overwrite the previous key pair file without confirmation! Make sure to store your production keys in a safe place.

$ ./libexim-encrypt-dlfunc-genkeys 
=== Creating cryptobox key pair ===
  Wrote »cryptobox_recipient_pk_exim.conf«
  Wrote »cryptobox_recipient_pk.raw«
  Wrote »cryptobox_recipient_sk_exim.conf«
  Wrote »cryptobox_recipient_sk.raw

The *_exim.conf files contain the keys in a format that can simply be used in exim.conf (the first line contains the key as a C code comment and can usually be discarded):

$ cat cryptobox_recipient_pk_exim.conf
# const unsigned char cryptobox_recipient_pk[32] = { 0xda, 0x46, 0xc8, 0x75, 0x2b, 0x31, 0xd9, 0x0c, 0x83, 0x54, 0x2d, 0x18, 0xda, 0xdc, 0xe5, 0x2d, 0x0e, 0x10, 0xe8, 0x0c, 0x39, 0xde, 0xaf, 0x30, 0x7e, 0xab, 0xca, 0x4d, 0xed, 0x26, 0x4d, 0x6e }; const unsigned int cryptobox_recipient_pk_length = 32;
CRYPTOBOX_RECIPIENT_PK=2kbIdSsx2QyDVC0Y2tzlLQ4Q6Aw53q8wfqvKTe0mTW4=

The *.raw files contain the same key without any formatting; these files are not needed for usage with exim but are generated as convenience when writing your own tools.

Example: remove X-Originating-IP: header

This example's use case was the initial reason to develop this library: remove the X-Originating-IP header to preserve our user's privacy but also keep the information in the final e-mail to enable response to complaints and abuse (the original header is usually provided in these cases). Add this snippet to your DATA ACL section in exim:

warn log_message   = Removing X-Originating-IP: header
     condition     = ${if def:h_X-originating-IP: {1}{0}}
     add_header    = X-Orig-IP-PKK: ${dlfunc{/usr/lib/x86_64-linux-gnu/libexim-encrypt-dlfunc.so} \
                                                {sodium_crypto_box_seal} \
                                                {ktp1OEEItrgvSfpVTtu+ybyNjzuuN8OzCdfrGAJt4j8=} \
                                                {$h_X-originating-IP:}}
     add_header    = X-Orig-IP-Pass: ${dlfunc{/usr/lib/x86_64-linux-gnu/libexim-encrypt-dlfunc.so} \
                                                 {sodium_crypto_secretbox_encrypt_password} \
                                                 {Insert your password here} \
                                                 {$h_X-originating-IP:}}
     remove_header = X-Originating-IP

Pick one of the add_header lines depending on which kind of encryption you want.