variables: Document encrypt and decrypt filters

Author: cmouse

docs/core/plugins/var_expand_crypt.md

@@ -18,6 +18,9 @@ dovecotlinks:
   conditionals:
     hash: conditionals
     text: Conditionals
+  cryptography_support:
+    hash: cryptography-support
+    text: Cryptography support
 ---
 
 # Settings Variables
@@ -97,8 +100,12 @@ Bytes output type indicates that the output will be tagged as binary output. Sub
 | base64(pad=boolean, url=boolean) | Bytes | String | Base64 encode given input, defaults to pad and not url scheme. |
 | benumber | Bytes | Number | Convert big-endian encoded input into a number. |
 | concat(any, any...) | Bytes | Bytes | Concatenates input with value(s). Numbers are coerced to strings. Input is optional. |
+| decrypt(key=bytes,iv=bytes,raw=boolean,algorithm=string) | Any | Any | Decrypts given input, see [cryptography support](#cryptography-support). |
+| decrypt(key=string,salt=string,rounds=number,raw=boolean,hash=string,algorithm=string) | Any | Any | Decrypts given input, see [cryptography support](#cryptography-support). |
 | default(value) | String | String | Replace empty or missing input with value. Clears missing variable error. If no value is provided, empty string is used. |
 | domain | String | String | Provides domain part of user@domain value. |
+| encrypt(key=bytes,iv=bytes,raw=boolean,algorithm=string) | Any | Any | Encrypts given input, see [cryptography support](#cryptography-support). |
+| encrypt(key=string,salt=string,rounds=number,raw=boolean,hash=string,algorithm=string) | Any | Any | Encrypts given input, see [cryptography support](#cryptography-support). |
 | hash(method, rounds=number, salt=string) | Bytes | Bytes | Returns raw hash from input using given hash method. Rounds and salt are optional. |
 | hexlify(width) | Bytes | String | Convert bytes into hex with optional width, truncates or pads up to width. |
 | hex(width) | Number | Number | Convert base-10 number to base-16 number. If width is specified the result is truncated or padded with 0 to width. Negative width is applied after number. |
@@ -129,13 +136,6 @@ Bytes output type indicates that the output will be tagged as binary output. Sub
 | upper | String | String | Uppercases input. |
 | username | String | String | Provides user part of user@domain value. |
 
-If [[plugin,var-expand-crypt]] is loaded, these filters are registered as well.
-
-| Filter | Input | Output | Description |
-| ------ | ----- | -----  | ----------- |
-| decrypt(algorithm=string,key=string,iv=string,raw=boolean) | Bytes/String | Bytes | Decrypts input with given parameters. If raw is `0`, expects '$' separated value of IV and encrypted data. |
-| encrypt(algorithm=string,key=string,iv=string,raw=boolean) | Bytes | Bytes/String | Encrypts input with given parameters. If raw is `0`, outputs `$` separated value of IV and encrypted data. |
-
 ## Global providers
 
 Global providers that work everywhere are:
@@ -356,3 +356,45 @@ Examples:
 # If %{user} is "testuser", return "INVALID". Otherwise return %{user} uppercased.
 %{user | if ("=", "testuser, "invalid", user) | upper }
 ```
+
+## Cryptography support
+
+### Parameters
+
+| Key                | Value                                                                                                       |
+| ------------------ | ----------------------------------------------------------------------------------------------------------- |
+| key                | Encryption key, if no salt is given, must be hex encoded and match the expected length of chosen algorithm. |
+| iv                 | Initialization vector, provide if no salt is given and algorithm requires one. Must be hex encoded and match the expected length of chosen algorithm. |
+| salt               | If provided, will use hash algorithm to create cipher key and IV with PBKDF2 algorithm. |
+| hash               | Hash to use in PBKDF2. Defaults to SHA-256. |
+| rounds             | Number of rounds to use in PBKDF2. Defaults to 1000. |
+| algorithm          | Encryption algorithm. Expects OpenSSL naming. Some algorithms are not usable due to system or functional restrictions. |
+| raw                | When set to 1, will return encrypted result in binary. |
+
+### Structured output format
+
+Dovecot supports structured encrypted data. If IV is directly provided, the syntax is `iv$data$`.
+With salt based keying material generation, the format is `s=salt,r=rounds$data$`.
+
+With no IV or salt provided, salt is randomly generated and used.
+
+### Raw output format
+
+If raw is used, the raw encryption result is emitted with no salt, rounds or IV included.
+
+### Recommended usage
+
+For best resuts, you should leave salt and IV management to Dovecot.
+
+### Examples
+
+```[dovecot.conf]
+import_environment = {
+   SECRET_KEY = %{env:SECRET_KEY}
+}
+imapc_password = "%{literal('s=3-?I&-a|,r=10000$e80e6ab3c18c0da69b20bf201eaf6269$') | decrypt(key=env:SECRET_KEY)}"
+```
+
+Stores impac password securely so that it can be decrypted only if `SECRET_KEY` environment variable is provided.
+
+To easily generate an encrypted value, you can use [[doveadm,user,user -e "%{literal('value') | encrypt(key='secret')}"]].