Commit d2b7ddc3 authored by Eric S. Raymond's avatar Eric S. Raymond

Another step in refactor config option documentation.

This time, it's authentication commands.
parent 1c7dd950
// 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
......@@ -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[]
'''''
......
......@@ -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 ===
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment