From 32e060d88d7d9e114e1a20a4a2fa12e5376844a1 Mon Sep 17 00:00:00 2001 From: Heiko Reese Date: Sun, 12 Sep 2021 02:36:21 +0200 Subject: [PATCH] Added documentation and command help messages to decryption tools. --- README.md | 68 ++++++++++++++++++- ci_container/README.md | 2 +- ...libexim-encrypt-dlfunc-decrypt-sealedbox.c | 8 ++- ...libexim-encrypt-dlfunc-decrypt-secretbox.c | 7 +- 4 files changed, 80 insertions(+), 5 deletions(-) diff --git a/README.md b/README.md index e4dc229..a8fa8af 100644 --- a/README.md +++ b/README.md @@ -44,6 +44,9 @@ meson compile -C build 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. + 5. Copy to final destination (feel free to pick another place than `/usr/lib/x86_64-linux-gnu/`): ```shell @@ -54,9 +57,18 @@ meson install -C 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. The Debian package [`exim4-daemon-heavy`](https://packages.debian.org/exim4-daemon-heavy) + of the `${dlfunc{…}}` function for details. The Debian + package [`exim4-daemon-heavy`](https://packages.debian.org/exim4-daemon-heavy) meets these requirements. +Try + +```shell +exim4 --version | egrep -i --color 'Expand_dlfunc|Content_Scanning' +``` + +for a preliminary test. + ## Usage There are currently two pairs of complementary functions: @@ -78,7 +90,7 @@ The second pair needs a proper key pair in the correct format. This is what the overwrite the previous key pair file without confirmation! Make sure to store your production keys in a safe place. ```shell -$ ./libexim-encrypt-dlfunc-genkeys +$ libexim-encrypt-dlfunc-genkeys === Creating cryptobox key pair === Wrote »cryptobox_recipient_pk_exim.conf« Wrote »cryptobox_recipient_pk.raw« @@ -120,3 +132,55 @@ warn log_message = Removing X-Originating-IP: header ``` Pick one of the `add_header` lines depending on which kind of encryption you want. + +### Decryption Tools + +Two additional programs are included: + +* `libexim-encrypt-dlfunc-decrypt-secretbox` +* `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) +[scripts](src/test_libexim-encrypt-dlfunc-decrypt-sealedbox.sh) for usage examples. + +```shell +$ libexim-encrypt-dlfunc-decrypt-secretbox -h +Usage: libexim-encrypt-dlfunc-decrypt-secretbox [OPTIONS] [CIPHERTEXT] + +Password: + -p, --password PASSWORD Decrypt using PASSWORD + + If the environment variable LIBEXIM_PASSWORD is set the password is read from there. + Setting a password with -p/--password overwrites this mechanism. + +Select input: + -f, --infile FILE Decrypt contents of the first line of file FILE (use - for stdin) + +Output: + -n, --no-newline Do not append a newline to the output + +Password and ciphertext are expected to be base64-encoded (as produced by the library). +``` + +```shell +$ libexim-encrypt-dlfunc-decrypt-sealedbox -h +Usage: libexim-encrypt-dlfunc-decrypt-sealedbox [OPTIONS] [CIPHERTEXT] + +Secret and public key: + -s, --secret-key SECRETKEY Secret key (base64-encoded) + -p, --public-key PUBLICKEY Public key (base64-encoded) + -S, --secret-key-file FILE Read secret key (raw) from file FILE (use - for stdin) + -P, --public-key-file FILE Read public key (raw) from file FILE (use - for stdin) + +The environment variables LIBEXIM_SECRETKEY and LIBEXIM_PUBLICKEY may contain base64-encoded secret/public keys. + +Select input: + -f, --infile FILE Decrypt contents of the first line of file FILE (use - for stdin) + +Output: + -n, --no-newline Do not append a newline to the output + +Keys in arguments and environment variables are expected to be base64 encoded (as produced by the library). +Keys in files need to be raw bytes with no encoding, ciphertext should always be base64-encoded. +``` \ No newline at end of file diff --git a/ci_container/README.md b/ci_container/README.md index 6f54f9c..3782fb6 100644 --- a/ci_container/README.md +++ b/ci_container/README.md @@ -3,7 +3,7 @@ ## Prerequisites * [buildah](https://buildah.io/) -* {podman](https://podman.io/) +* [podman](https://podman.io/) ## Build and upload diff --git a/src/libexim-encrypt-dlfunc-decrypt-sealedbox.c b/src/libexim-encrypt-dlfunc-decrypt-sealedbox.c index eb72ab8..9a099ea 100644 --- a/src/libexim-encrypt-dlfunc-decrypt-sealedbox.c +++ b/src/libexim-encrypt-dlfunc-decrypt-sealedbox.c @@ -64,6 +64,7 @@ int main(int argc, char *argv[]) { } // define arguments + const char *shortargs = "s:p:S:P:f:nh"; static struct option long_options[] = { {"secret-key", required_argument, NULL, 's'}, {"public-key", required_argument, NULL, 'p'}, @@ -71,6 +72,7 @@ int main(int argc, char *argv[]) { {"public-key-file", required_argument, NULL, 'P'}, {"infile", required_argument, NULL, 'f'}, {"no-newline", required_argument, NULL, 'n'}, + {"help", no_argument, NULL, 'h'}, {0, 0, 0, 0} }; @@ -96,7 +98,7 @@ int main(int argc, char *argv[]) { // parse arguments int long_index = 0; - while ((opt = getopt_long(argc, argv, "s:p:S:P:f:n", + while ((opt = getopt_long(argc, argv, shortargs, long_options, &long_index)) != -1) { switch (opt) { case 's': @@ -128,6 +130,10 @@ int main(int argc, char *argv[]) { case 'n': add_newline = false; break; + case 'h': + print_usage(prog_basename); + exit(EXIT_SUCCESS); + break; } } diff --git a/src/libexim-encrypt-dlfunc-decrypt-secretbox.c b/src/libexim-encrypt-dlfunc-decrypt-secretbox.c index ebcc57c..28d17e5 100644 --- a/src/libexim-encrypt-dlfunc-decrypt-secretbox.c +++ b/src/libexim-encrypt-dlfunc-decrypt-secretbox.c @@ -53,11 +53,12 @@ int main(int argc, char *argv[]) { } // define arguments - const char *shortargs = "p:f:n"; + const char *shortargs = "p:f:nh"; static struct option long_options[] = { {"password", required_argument, NULL, 'p'}, {"infile", required_argument, NULL, 'f'}, {"no-newline", no_argument, NULL, 'n'}, + {"help", no_argument, NULL, 'h'}, {0, 0, 0, 0} }; @@ -87,6 +88,10 @@ int main(int argc, char *argv[]) { case 'n': add_newline = false; break; + case 'h': + print_usage(prog_basename); + exit(EXIT_SUCCESS); + break; } }