[Doc] Update whitelist documentation

1 files changed, 48 insertions, 15 deletions

diff --git a/doc/markdown/modules/whitelist.md b/doc/markdown/modules/whitelist.md
index ec4671e58..5b2417194 100644
--- a/doc/markdown/modules/whitelist.md
+++ b/doc/markdown/modules/whitelist.md
@@ -1,6 +1,6 @@
 # Whitelist module
 
-Whitelist module is intended to negate scores for some messages that are known to
+Whitelist module is intended to negate or increase scores for some messages that are known to
 be from the trusted sources. Due to `SMTP` protocol design flaws, it is quite easy to
 forge sender. Therefore, rspamd tries to validate sender based on the following additional
 properties:
@@ -14,15 +14,30 @@ properties:
 Whitelist configuration is quite straightforward. You can define a set of rules within
 `rules` section. Each rule **must** have `domains` attribute that specifies either
 map of domains (if specified as a string) or a direct list of domains (if specified as an array).
-The following optional parameters are allowed:
+
+### Whitelist constraints
+
+The following constraints are allowed:
 
 - `valid_spf`: require a valid SPF policy
 - `valid_dkim`: require DKIM validation
 - `valid_dmarc`: require a valid DMARC policy
 
-These options are combined using `AND` operator, therefore `valid_dkim = true` and
+### Whitelist rules modes
+
+Each whitelist rule can work in 3 modes:
+
+- `whitelist` (default): add symbol when a domain has been found and one of constraints defined is satisfied (e.g. `valid_dmarc`)
+- `blacklist`: add symbol when a domain has been found and one of constraints defined is *NOT* satisfied (e.g. `valid_dmarc`)
+- `strict`: add symbol with negative (ham) score when a domain has been found and one of constraints defined is satisfied (e.g. `valid_dmarc`) and add symbol with **POSITIVE** (spam) score when some of constraints defined has failed
+
+If you do not define any constraints, then all both `strict` and `whitelist` rules just insert result for all mail from the specified domains. For `blacklist` rules the result has normally positive score.
+
+These options are combined using `AND` operator for `whitelist` and using `OR` for `blacklist` and `strict` rules. Therefore, if `valid_dkim = true` and
 `valid_spf = true` would require both DKIM and SPF validation to whitelist domains from
-the list.
+the list. On the contrary, for blacklist and strict rules any violation would cause positive score symbol being inserted.
+
+### Optional settings
 
 You can also set the default metric settings using the ordinary attributes, such as:
 
@@ -50,34 +65,52 @@ whitelist {
             valid_spf = true;
             domains = [
                 "github.com",
-            ]
-            score = -1.0
+            ];
+            score = -1.0;
         }
-    
+
         WHITELIST_DKIM = {
             valid_dkim = true;
             domains = [
                 "github.com",
-            ]
-            score = -2.0
+            ];
+            score = -2.0;
         }
-        
+
         WHITELIST_SPF_DKIM = {
             valid_spf = true;
             valid_dkim = true;
             domains = [
                 ["github.com", 2.0],
-            ]
-            score = -3.0
+            ];
+            score = -3.0;
         }
-        
+
+        STRICT_SPF_DKIM = {
+            valid_spf = true;
+            valid_dkim = true;
+            strict = true;
+            domains = [
+                ["paypal.com", 2.0],
+            ];
+            score = -3.0; # For strict rules negative score should be defined
+        }
+
+        BLACKLIST_DKIM = {
+            valid_spf = true;
+            valid_dkim = true;
+            blacklist = true;
+            domains = "/some/file/blacklist_dkim.map";
+            score = 3.0; # Mention positive score here
+        }
+
         WHITELIST_DMARC_DKIM = {
             valid_dkim = true;
             valid_dmarc = true;
             domains = [
                 "github.com",
-            ]
-            score = -7.0
+            ];
+            score = -7.0;
         }
     }
 }