# exim-encrypt-dlfunc

This library injects functions for string encryption and decryption into [exim4](https://www.exim.org/). It is basically
glue code that exports certain parts of the [libsodium library](https://github.com/jedisct1/libsodium) to exim at runtime.

## Installation

These instructions are currently only tested on Debian Linux.

1. Install development tools and libsodium development files:

```shell
apt-get build-essential exim4-dev libsodium-dev meson pkg-config openssl exim4-daemon-heavy
```

2. Clone this repository:

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

3. Build and test everything:

```shell
meson build # run only once
cd build
ninja
```

5. Copy to final destination (feel free to pick another place than `/usr/local/lib/`):

TBD…

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](https://www.exim.org/exim-html-current/doc/html/spec_html/ch-string_expansions.html)
   of the `${dlfunc{…}}` function for details. exim from the debian package `exim4-daemon-heavy` meets all the
   requirements.

## Usage

There are currently two pairs of functions:

Symmetric encryption that derives its key from an ASCII string:

* `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 that 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
`generate_encryption_keys` utility is for. Simply run it once to generate a pair. Be aware that every invocation will
overwrite the previous key pair without confirmation! Please save both parts in a safe place before proceeding.

```shell
$ ./generate_encryption_keys 
=== 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):

```shell
$ 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:

```exim
warn log_message   = Removing X-Originating-IP header
     condition     = ${if def:h_X-originating-IP: {1}{0}}
     add_header    = X-KIT-Orig-IP-PKK: ${dlfunc{/usr/local/lib/libexim-encrypt-dlfunc.so} \
                                                {sodium_crypto_box_seal} \
                                                {ktp1OEEItrgvSfpVTtu+ybyNjzuuN8OzCdfrGAJt4j8=} \
                                                {$h_X-originating-IP:}}
     add_header    = X-KIT-Orig-IP-Pass: ${dlfunc{/usr/local/lib/libexim-encrypt-dlfunc.so} \
                                                 {sodium_crypto_secretbox_encrypt_password} \
                                                 {This is a very non-secret key} \
                                                 {$h_X-originating-IP:}}
     remove_header = X-Originating-IP

```

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