Add ARC signing caveats

diff --git a/doc/doc-txt/experimental-spec.txt b/doc/doc-txt/experimental-spec.txt
index bc5bab77d4ab7aa715d2feee2789bbc9e1d50b93..0828e9b67aeac6c589231cfee7d3848590e27597 100644 (file)
--- a/doc/doc-txt/experimental-spec.txt
+++ b/doc/doc-txt/experimental-spec.txt
@@ -805,6 +805,20 @@ is used as a basis (you must have added one on entry to the ADMD).
 Expanded as a whole; if unset, empty or forced-failure then no signing is done.
 If it is set, all three elements must be non-empty.
 
+Caveats:
+ * There must be an Authentication-Results header, presumably added by an ACL
+   while receiving the message, for the same ADMD, for arc_sign to succeed.
+   This requires careful coordination between inbound and outbound logic.
+ * If passing a message to another system, such as a mailing-list manager
+   (MLM), between receipt and sending, be wary of manipulations to headers made
+   by the MLM.
+   + For instance, Mailman with REMOVE_DKIM_HEADERS==3 might improve
+     deliverability in a pre-ARC world, but that option also renames the
+     Authentication-Results header, which breaks signing.
+ * Even if you use multiple DKIM keys for different domains, the ARC concept
+   should try to stick to one ADMD, so pick a primary domain and use that for
+   AR headers and outbound signing.
+
 
 
 --------------------------------------------------------------