diff --git a/README.md b/README.md index 154cacd..96322d9 100644 --- a/README.md +++ b/README.md @@ -16,16 +16,16 @@ These instructions are currently only tested on [Debian](https://www.debian.org) apt-get install -y build-essential exim4-dev libsodium-dev meson pkg-config openssl exim4-daemon-heavy ``` -`exim-encrypt-dlfunc` uses [meson](https://mesonbuild.com/) (and [ninja](https://ninja-build.org/)) 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](https://pypi.org/) via [pip](https://pypi.org/project/pip/): +This project uses [meson](https://mesonbuild.com/) (and [ninja](https://ninja-build.org/)) as build system. To ensure +all features are present (which are lacking in the packaged versions of older distributions) +you are strongly advised to install from [pypi](https://pypi.org/) via [pip](https://pypi.org/project/pip/): ```shell apt-get install -y python3-pip -pip3 install meson ninja +pip3 install -U meson ninja ``` -You may alternatively use your distribution packages: +You may alternatively try to use your distribution packages: ```shell apt-get install -y meson @@ -47,9 +47,9 @@ meson test -C build ``` The `ci_container` directory contains a [script](ci_container/build.sh) (and a [short README](ci_container/README.md)) -which creates the images used in continous integration for this project. +which creates the container images used in continuous integration for this project. -5. Copy to final destination (feel free to pick another place than `/usr/lib/x86_64-linux-gnu/`): +5. Install library and tools (defaults to `/usr/local/bin` and `/usr/local/lib/x86_64-linux-gnu`): ```shell meson install -C build @@ -71,25 +71,32 @@ exim4 --version | egrep -i --color 'Expand_dlfunc|Content_Scanning' for a preliminary test. +7. Configure exim to use the new functionality + +This highly depends on your use case. See [the example below](#xoip-example) and +[`src/test_libexim-encrypt-dlfunc.sh`](src/test_libexim-encrypt-dlfunc.sh). + ## Usage -There are currently two pairs of complementary functions: +There are currently two sets of complementary function pairs: -Symmetric encryption that derives a key from an ASCII string (aka a “password”): +### Symmetric encryption that derives the 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. +The generated key is only as strong as the provided password. Use `openssl rand --base64 48 | tr -d =` +to get a passable password. -Public key encryption that uses a key pair which needs to be created beforehand: +### 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. +The second pair needs a matching 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 in the current directory. 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! ```shell $ libexim-encrypt-dlfunc-genkeys @@ -101,11 +108,13 @@ $ libexim-encrypt-dlfunc-genkeys ``` 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): +`exim.conf` (the first line contains the key as a C code comment and can usually be ignored or 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; +# 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= ``` @@ -114,9 +123,10 @@ 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: + +This task 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 @@ -143,7 +153,7 @@ Two additional programs are included: * `libexim-encrypt-dlfunc-decrypt-sealedbox` They can decrypt strings that were encrypted by the two respective functions. Please refer to their `--help` message -(reproduced below) for usage information and to the [test](src/test_libexim-encrypt-dlfunc-decrypt-secretbox.sh) +(reproduced below) for usage information and to both [test](src/test_libexim-encrypt-dlfunc-decrypt-secretbox.sh) [scripts](src/test_libexim-encrypt-dlfunc-decrypt-sealedbox.sh) for usage examples. ```shell