hreese/exim-encrypt-dlfunc
1
0
Fork 0
mirror of https://gitlab.kit.edu/kit/scc/sys/mail/exim-encrypt-dlfunc.git synced 2025-12-06 06:53:56 +01:00
Code Issues Releases Wiki Activity

Lots of small README fixes and improvements.

Browse Source
This commit is contained in:
Heiko Reese
2021-09-13 16:47:56 +02:00
parent b02f9e40ab
commit 0a5e880f32
1 changed files with 30 additions and 20 deletions
Download Patch File Download Diff File Expand all files Collapse all files

50
README.md
View File

@ -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:
<a name="xoip-example"></a>
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