Merge branch '4266-document-dnssec-policy-lifetime-v9_18' into 'bind-9.18'

[9.18] Clarify BIND 9 time formats

See merge request isc-projects/bind9!8259

CHANGES

@@ -1,6 +1,8 @@
 6237.	[bug]		Address memory leaks due to not clearing OpenSSL error
 			stack. [GL #4159]
 
+6235.	[doc]		Clarify BIND 9 time formats. [GL #4266]
+
 6234.	[bug]		Restore stale-refresh-time value after flushing the
 			cache. [GL #4278]
 

doc/arm/reference.rst

@@ -314,6 +314,26 @@ file documentation:
     ``domain_name``
         A quoted string which is used as a DNS name; for example: ``my.test.domain``.
 
+    ``duration``
+        A duration in BIND 9 can be written in three ways: as single number
+        representing seconds, as a string of numbers with TTL-style
+        time-unit suffixes, or in ISO 6801 duration format.
+
+        Allowed TTL time-unit suffixes are: "W" (week), "D" (day), "H" (hour),
+        "M" (minute), and "S" (second). Examples: "1W" (1 week), "3d12h"
+        (3 days, 12 hours).
+
+        ISO 8601 duration format consists of the letter "P", followed by an
+	optional series of numbers with unit suffixes "Y" (year), "M" (month),
+        "W" (week), and "D" (day); this may optionally be followed by the
+        letter "T", and another series of numbers with unit suffixes
+        "H" (hour), "M" (minute), and "S" (second). Examples: "P3M10D"
+        (3 months, 10 days), "P2WT12H" (2 weeks, 12 hours), "pt15m"
+        (15 minutes).  For more information on ISO 8601 duration format,
+        see :rfc:`3339`, appendix A.
+
+        Both TTL-style and ISO 8601 duration formats are case-insensitive.
+
     ``fixedpoint``
         A non-negative real number that can be specified to the nearest one-hundredth. Up to five digits can be specified before a decimal point, and up to two digits after, so the maximum value is 99999.99. Acceptable values might be further limited by the contexts in which they are used.
 
@@ -6377,13 +6397,13 @@ The following options can be specified in a :any:`dnssec-policy` statement:
     DNSKEY RRset always includes a key-signing key for that algorithm.
 
     Here is an example (for illustration purposes only) of some possible
-    entries in a :any:`keys` list:
+    entries in a ``keys`` list:
 
     ::
 
         keys {
             ksk key-directory lifetime unlimited algorithm rsasha256 2048;
-            zsk lifetime P30D algorithm 8;
+            zsk lifetime 30d algorithm 8;
             csk lifetime P6MT12H3M15S algorithm ecdsa256;
         };
 
@@ -6402,7 +6422,11 @@ The following options can be specified in a :any:`dnssec-policy` statement:
     keys in hardware security modules or separate directories.
 
     The ``lifetime`` parameter specifies how long a key may be used
-    before rolling over.  In the example above, the first key has an
+    before rolling over. For convenience, TTL-style time-unit suffixes
+    can be used to specify the key lifetime. It also accepts ISO 8601
+    duration formats.
+
+    In the example above, the first key has an
     unlimited lifetime, the second key may be used for 30 days, and the
     third key has a rather peculiar lifetime of 6 months, 12 hours, 3
     minutes, and 15 seconds.  A lifetime of 0 seconds is the same as