wip

Author: cmouse

docs/core/plugins/var_expand_crypt.md

@@ -11,44 +11,38 @@ It requires a functional [[link,lib_dcrypt]] backend.
 
 For dovecot-auth process this plugin is automatically usable.
 
+This plugin adds `encrypt` and `decrypt` filters.
+
 ## Settings
 
 There are no `dovecot.conf` settings for this plugin.
 
-## Syntax
-
-```[dovecot.conf]
-args=encrypted_value=%{encrypt;key=value,iv=value,noiv=yes,algo=algorithm,format=base64|hex:field}
-args=decrypted_value=%{decrypt;key=value,iv=value,noiv=yes,algo=algorithm,format=base64|hex:field}
-```
-
 ### Parameters
 
-| Key | Value |
-| --- | ----- |
-| `algo` | Algorithm name (defaults to `aes-256-cbc`) |
-| `format` | Return format |
-| `iv` | hex-encoded value |
-| `key` | hex-encoded value |
-| `noiv` | Whether iv is included in return value |
-
-Decrypt expects input in base64 or hex format.
+| 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. |
 
 ::: tip
-It is usually best to leave iv management to Dovecot, and not use
-`iv` and `noiv` options at all.
+For better security, use key and salt to generate proper pseudorandom cipher key and IV.
 :::
 
-### Return Formats
+### Usage
 
-Without `noiv`, encrypt returns `iv$encrypted$`.
+To encrypt data, usually the easiest way is to do just `%{value|encrypt(key=key)}`.
+This produces output that can be decrypted with `%{encrypted_value|decrypt(key=key)`.
 
-With `noiv`, just encrypted data is returned. Field(s) are encoded using
-format.
+### Return Formats
 
-`key` and `iv` must be the length required by the given `algo`.
+If raw is zero or not used, the return value will be Dovecot specific `iv$data$` format. In case salt was used, the format is `s=salt$data$`.
 
-## Example
+###
 
 ```
 %{encrypt;key=f1f2f3f4f5f6f7f8f1f2f3f4f5f6f7f8f1f2f3f4f5f6f7f8f1f2f3f4f5f6f7f8:password} = 93736a0f910df27f89210e096e1d639a$966c2b4f3e7487f6acdb836f8d1dc3e0$