Added documentation and command help messages to decryption tools.

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.
+```

ci_container/README.md

@@ -3,7 +3,7 @@
 ## Prerequisites
 
 * [buildah](https://buildah.io/)
-* {podman](https://podman.io/)
+* [podman](https://podman.io/)
 
 ## Build and upload
 

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;
         }
     }
 

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;
         }
     }