[ntpsec commit] Another step in refactor config option documentation.
Eric S. Raymond
esr at ntpsec.org
Sun Oct 11 20:02:29 UTC 2015
Module: ntpsec
Branch: master
Commit: 47607d9389c3f6e9b887a45a21eeb2fac989988a
Changeset: http://git.ntpsec.org/ntpsec/commit/?id=47607d9389c3f6e9b887a45a21eeb2fac989988a
Author: Eric S. Raymond <esr at thyrsus.com>
Date: Sun Oct 11 16:01:08 2015 -0400
Another step in refactor config option documentation.
This time, it's authentication commands.
---
docs/auth-commands.txt | 121 +++++++++++++++++++++++++++++++++++++++++++++++++
docs/authopt.txt | 93 +------------------------------------
ntpd/ntp.conf.txt | 86 +----------------------------------
3 files changed, 123 insertions(+), 177 deletions(-)
diff --git a/docs/auth-commands.txt b/docs/auth-commands.txt
new file mode 100644
index 0000000..56422c4
--- /dev/null
+++ b/docs/auth-commands.txt
@@ -0,0 +1,121 @@
+// Authentication commands - included twice
+
+//`autokey` [_logsec_]::
+// Specifies the interval between regenerations of the session key list
+// used with the Autokey protocol. Note that the size of the key list for
+// each association depends on this interval and the current poll
+// interval. The default value is 12 (4096 s or about 1.1 hours). For
+// poll intervals above the specified interval, a session key list with a
+// single entry will be regenerated for every message sent.
+//
+//`automax` ['logsec']::
+// Specifies the interval between regenerations of the session key list
+// used with the Autokey protocol, as a power of 2 in seconds. Note that
+// the size of the key list for each association depends on this interval
+// and the current poll interval. The default interval is 12 (about 1.1
+// hr). For poll intervals above the specified interval, a session key
+// list with a single entry will be regenerated for every message sent.
+// See the link:autokey.html[Autokey Public Key Authentication] page for
+// further information.
+
+`controlkey` _key_::
+ Specifies the key identifier to use with the
+ {ntpqman} utility, which uses the standard protocol defined in
+ RFC-5905. The _key_ argument is the key identifier for a trusted key,
+ where the value can be in the range 1 to 65,534, inclusive.
+
+`crypto` [`cert` _file_] [`leap` _file_] [`randfile` _file_] [`host` _file_] [`sign` _file_] [`gq` _file_] [`gqpar` _file_] [`iffpar` _file_] [`mvpar` _file_] [`pw` _password_]::
+ This command requires the OpenSSL library. It activates public key
+ cryptography, selects the message digest and signature encryption
+ scheme and loads the required private and public values described
+ above. If one or more files are left unspecified, the default names
+ are used as described above. Unless the complete path and name of the
+ file are specified, the location of a file is relative to the keys
+ directory specified in the `keysdir` command or default
+ `/usr/local/etc`. Following are the subcommands:
+
+ //NAMECHANGE
+ `cert` _file_;;
+ Specifies the location of the required host public certificate file.
+ This overrides the link _ntpkey_cert_hostname_ in the keys
+ directory.
+ `digest` 'digest';;
+ Specify the message digest algorithm, with default MD5. If the
+ OpenSSL library is installed, `digest` can be be any message digest
+ algorithm supported by the library. The current selections are:
+ `MD2`, `MD4`, `MD5,` `MDC2`, `RIPEMD160`, `SHA` and `SHA1`. All
+ participants in an Autokey subnet must use the same algorithm. The
+ Autokey message digest algorithm is separate and distinct from the
+ symmetric key message digest algorithm. Note: If compliance with
+ FIPS 140-2 is required, the algorithm must be ether `SHA` or `SHA1`.
+ `gqpar` _file_;;
+ Specifies the location of the optional GQ parameters file. This
+ overrides the link _ntpkey_gq_hostname_ in the keys directory.
+ `host` _file_;;
+ Specifies the location of the required host key file. This overrides
+ the link _ntpkey_key_hostname_ in the keys directory.
+// `ident` 'group';;
+// Specify the cryptographic media names for the identity scheme files.
+// If this option is not specified, the default name is the string
+// returned by the Unix `gethostname()` routine.
+//+
+//[red]#Note: In the latest Autokey version, this option has no effect other
+//than to change the cryptographic media file names.#
+ `iffpar` _file_;;
+ Specifies the location of the optional IFF parameters file.This
+ overrides the link _ntpkey_iff_hostname_ in the keys directory.
+ `leap` _file_;;
+ Specifies the location of the optional leapsecond file. This
+ overrides the link _ntpkey_leap_ in the keys directory.
+ `mvpar` _file_;;
+ Specifies the location of the optional MV parameters file. This
+ overrides the link _ntpkey_mv_hostname_ in the keys directory.
+ `pw` _password_;;
+ Specifies the password to decrypt files containing private keys and
+ identity parameters. This is required only if these files have been
+ encrypted.
+ `randfile` _file_;;
+ Specifies the location of the random seed file used by the OpenSSL
+ library. The defaults are described in the main text above.
+ `sign` _file_;;
+ Specifies the location of the optional sign key file. This overrides
+ the link _ntpkey_sign_hostname_ in the keys directory. If this file
+ is not found, the host key is also the sign key.
+
+//`ident` 'group'::
+// Specifies the group name for ephemeral associations mobilized by
+// broadcast and symmetric passive modes. See the
+// "Autokey Public-Key Authentication" page for further
+// information.
+
+`keys` _keyfile_::
+ Specifies the complete path and location of the MD5 key file
+ containing the keys and key identifiers used by {ntpdman},
+ and {ntpqman} when operating with symmetric-key cryptography.
+ This is the same operation as the `-k` command line option.
+
+`keysdir` _path_::
+ This command specifies the default directory path for cryptographic
+ keys, parameters and certificates. The default is `/usr/local/etc/`.
+
+`revoke` _logsec_::
+ Specifies the interval between re-randomization of certain
+ cryptographic values used by the Autokey scheme, as a power of 2 in
+ seconds. These values need to be updated frequently in order to
+ deflect brute-force attacks on the algorithms of the scheme; however,
+ updating some values is a relatively expensive operation. The default
+ interval is 16 (65,536 s or about 18 hours). For poll intervals above
+ the specified interval, the values will be updated for every message
+ sent.
+
+`trustedkey` _key..._ ::
+ Specifies the key identifiers which are trusted for the purposes of
+ authenticating peers with symmetric key cryptography, as well as keys
+ used by the {ntpqman} program. The
+ authentication procedures require that both the local and remote
+ servers share the same key and key identifier for this purpose,
+ although different keys can be used with different servers.
+ The _key_ arguments are 32-bit unsigned integers with values from 1 to
+ 65,534.
+
+// end
diff --git a/docs/authopt.txt b/docs/authopt.txt
index 3aa5a86..25f4e5c 100644
--- a/docs/authopt.txt
+++ b/docs/authopt.txt
@@ -22,98 +22,7 @@ include::includes/authopt.txt[]
Unless noted otherwise, further information about these commands is on
the link:authentic.html[Authentication Support] page.
-`automax` ['logsec']::
- Specifies the interval between regenerations of the session key list
- used with the Autokey protocol, as a power of 2 in seconds. Note that
- the size of the key list for each association depends on this interval
- and the current poll interval. The default interval is 12 (about 1.1
- hr). For poll intervals above the specified interval, a session key
- list with a single entry will be regenerated for every message sent.
- See the link:autokey.html[Autokey Public Key Authentication] page for
- further information.
-`controlkey` 'keyid'::
- Specifies the key ID for the link:ntpq.html[`{ntpq}`] utility, which
- uses the standard protocol defined in RFC-1305. The `keyid` argument
- is the key ID for a link:#trustedkey[trusted key], where the value can
- be in the range 1 to 65534, inclusive.
-`crypto` [`digest` 'digest' ] [`host` 'name'] [`ident` 'name'] [`pw` 'password'] [`randfile` 'file']::
- This command activates the Autokey public key cryptography and loads
- the required host keys and certificate. If one or more files are
- unspecified, the default names are used. Unless the complete path and
- name of the file are specified, the location of a file is relative to
- the keys directory specified in the `keysdir` configuration command
- with default `/usr/local/etc`. See the link:autokey.html[Autokey
- Public Key Authentication] page for further information. Following are
- the options.
- `digest` 'digest';;
- Specify the message digest algorithm, with default MD5. If the
- OpenSSL library is installed, `digest` can be be any message digest
- algorithm supported by the library. The current selections are:
- `MD2`, `MD4`, `MD5,` `MDC2`, `RIPEMD160`, `SHA` and `SHA1`. All
- participants in an Autokey subnet must use the same algorithm. The
- Autokey message digest algorithm is separate and distinct from the
- symmetric key message digest algorithm. Note: If compliance with
- FIPS 140-2 is required, the algorithm must be ether `SHA` or `SHA1`.
- `host` 'name';;
- Specify the cryptographic media names for the host, sign and
- certificate files. If this option is not specified, the default name
- is the string returned by the Unix `gethostname()` routine.
-+
-[red]#Note: In the latest Autokey version, this option has no effect other
-than to change the cryptographic media file names.#
-
-`ident` 'group';;
- Specify the cryptographic media names for the identity scheme files.
- If this option is not specified, the default name is the string
- returned by the Unix `gethostname()` routine.
-+
-[red]#Note: In the latest Autokey version, this option has no effect other
-than to change the cryptographic media file names.#
-
-`pw` 'password';;
- Specifies the password to decrypt files previously encrypted by the
- `{ntpkeygen}` program with the `-p` option. If this option is not
- specified, the default password is the string returned by the Unix
- `gethostname()` routine.
-`randfile` 'file';;
- Specifies the location of the random seed file used by the OpenSSL
- library. The defaults are described on the
- link:keygen.html[`{ntpkeygen}` page].
-`ident` 'group'::
- Specifies the group name for ephemeral associations mobilized by
- broadcast and symmetric passive modes. See the
- link:autokey.html[Autokey Public-Key Authentication] page for further
- information.
-`keys` 'path'::
- Specifies the complete directory path for the key file containing the
- key IDs, key types and keys used by `{ntpd}` and `{ntpq}` when
- operating with symmetric key cryptography. The format of the keyfile
- is described on the link:keygen.html[`{ntpkeygen}` page]. This is the
- same operation as the `-k` command line option. Note that the
- directory path for Autokey cryptographic media is specified by the
- `keysdir` command.
-`keysdir` 'path'::
- Specifies the complete directory path for the Autokey cryptographic
- keys, parameters and certificates. The default is `/usr/local/etc/`.
- Note that the path for the symmetric keys file is specified by the
- `keys` command.
-`revoke` ['logsec']::
- Specifies the interval between re-randomization of certain
- cryptographic values used by the Autokey scheme, as a power of 2 in
- seconds, with default 17 (36 hr). See the link:autokey.html[Autokey
- Public-Key Authentication] page for further information.
-`trustedkey` ['keyid' | ('lowid' ... 'highid')] [...]::
- Specifies the key ID(s) which are trusted for the purposes of
- authenticating peers with symmetric key cryptography. Key IDs used to
- authenticate `{ntpq}` operations must be listed here and
- additionally be enabled with link:#controlkey[controlkey] and/or
- link:#requestkey[requestkey]. The authentication procedure for time
- transfer requires that both the local and remote NTP servers employ
- the same key ID and secret for this purpose, although different keys
- IDs may be used with different servers. Ranges of trusted key IDs may
- be specified: `trustedkey (1 ... 19) 1000 (100 ... 199)` enables the
- lowest 120 key IDs which start with the digit 1. The spaces
- surrounding the ellipsis are required when specifying a range.
+include::auth-commands.txt[]
'''''
diff --git a/ntpd/ntp.conf.txt b/ntpd/ntp.conf.txt
index ffb294d..7524a10 100644
--- a/ntpd/ntp.conf.txt
+++ b/ntpd/ntp.conf.txt
@@ -94,91 +94,7 @@ include::../docs/assoc-auxcommands.txt[]
== Authentication Commands ==
-//`autokey` [_logsec_]::
-// Specifies the interval between regenerations of the session key list
-// used with the Autokey protocol. Note that the size of the key list for
-// each association depends on this interval and the current poll
-// interval. The default value is 12 (4096 s or about 1.1 hours). For
-// poll intervals above the specified interval, a session key list with a
-// single entry will be regenerated for every message sent.
-
-`controlkey` _key_::
- Specifies the key identifier to use with the
- {ntpqman} utility, which uses the standard protocol defined in
- RFC-1305. The _key_ argument is the key identifier for a trusted key,
- where the value can be in the range 1 to 65,534, inclusive.
-
-`crypto` [`cert` _file_] [`leap` _file_] [`randfile` _file_] [`host` _file_] [`sign` _file_] [`gq` _file_] [`gqpar` _file_] [`iffpar` _file_] [`mvpar` _file_] [`pw` _password_]::
- This command requires the OpenSSL library. It activates public key
- cryptography, selects the message digest and signature encryption
- scheme and loads the required private and public values described
- above. If one or more files are left unspecified, the default names
- are used as described above. Unless the complete path and name of the
- file are specified, the location of a file is relative to the keys
- directory specified in the `keysdir` command or default
- `/usr/local/etc`. Following are the subcommands:
-
- //NAMECHANGE
- `cert` _file_;;
- Specifies the location of the required host public certificate file.
- This overrides the link _ntpkey_cert_hostname_ in the keys
- directory.
- `gqpar` _file_;;
- Specifies the location of the optional GQ parameters file. This
- overrides the link _ntpkey_gq_hostname_ in the keys directory.
- `host` _file_;;
- Specifies the location of the required host key file. This overrides
- the link _ntpkey_key_hostname_ in the keys directory.
- `iffpar` _file_;;
- Specifies the location of the optional IFF parameters file.This
- overrides the link _ntpkey_iff_hostname_ in the keys directory.
- `leap` _file_;;
- Specifies the location of the optional leapsecond file. This
- overrides the link _ntpkey_leap_ in the keys directory.
- `mvpar` _file_;;
- Specifies the location of the optional MV parameters file. This
- overrides the link _ntpkey_mv_hostname_ in the keys directory.
- `pw` _password_;;
- Specifies the password to decrypt files containing private keys and
- identity parameters. This is required only if these files have been
- encrypted.
- `randfile` _file_;;
- Specifies the location of the random seed file used by the OpenSSL
- library. The defaults are described in the main text above.
- `sign` _file_;;
- Specifies the location of the optional sign key file. This overrides
- the link _ntpkey_sign_hostname_ in the keys directory. If this file
- is not found, the host key is also the sign key.
-
-`keys` _keyfile_::
- Specifies the complete path and location of the MD5 key file
- containing the keys and key identifiers used by {ntpdman},
- and {ntpqman} when operating with symmetric-key cryptography.
- This is the same operation as the `-k` command line option.
-
-`keysdir` _path_::
- This command specifies the default directory path for cryptographic
- keys, parameters and certificates. The default is `/usr/local/etc/`.
-
-`revoke` _logsec_::
- Specifies the interval between re-randomization of certain
- cryptographic values used by the Autokey scheme, as a power of 2 in
- seconds. These values need to be updated frequently in order to
- deflect brute-force attacks on the algorithms of the scheme; however,
- updating some values is a relatively expensive operation. The default
- interval is 16 (65,536 s or about 18 hours). For poll intervals above
- the specified interval, the values will be updated for every message
- sent.
-
-`trustedkey` _key..._ ::
- Specifies the key identifiers which are trusted for the purposes of
- authenticating peers with symmetric key cryptography, as well as keys
- used by the {ntpqman} program. The
- authentication procedures require that both the local and remote
- servers share the same key and key identifier for this purpose,
- although different keys can be used with different servers.
- The _key_ arguments are 32-bit unsigned integers with values from 1 to
- 65,534.
+include::../docs/auth-commands.txt[]
=== Error Codes ===
More information about the vc
mailing list