ntp_auth
ntp_auth(5) ntp_auth(5)
NAME
ntp_auth - Authentication Options
AUTHENTICATION SUPPORT
Authentication support allows the NTP client to verify that the server
is in fact known and trusted and not an intruder intending acciden-
tally or on purpose to masquerade as that server. The NTPv3 specifica-
tion RFC-1305 defines a scheme which provides cryptographic authenti-
cation of received NTP packets. Originally, this was done using the
Data Encryption Standard (DES) algorithm operating in Cipher Block
Chaining (CBC) mode, commonly called DES-CBC. Subsequently, this was
replaced by the RSA Message Digest 5 (MD5) algorithm using a private
key, commonly called keyed-MD5. Either algorithm computes a message
digest, or one-way hash, which can be used to verify the server has
the correct private key and key identifier.
NTPv4 retains the NTPv3 scheme, properly described as symmetric key
cryptography and, in addition, provides a new Autokey scheme based on
public key cryptography. Public key cryptography is generally consid-
ered more secure than symmetric key cryptography, since the security
is based on a private value which is generated by each server and
never revealed. With Autokey all key distribution and management func-
tions involve only public values, which considerably simplifies key
distribution and storage. Public key management is based on X.509 cer-
tificates, which can be provided by commercial services or produced by
utility programs in the OpenSSL software library or the NTPv4 distri-
bution.
While the algorithms for symmetric key cryptography are included in
the NTPv4 distribution, public key cryptography requires the OpenSSL
software library to be installed before building the NTP distribution.
Directions for doing that are on the Building and Installing the Dis-
tribution page.
Authentication is configured separately for each association using the
key or autokey subcommand on the peer, server, broadcast and manycast-
client configuration commands as described in the Configuration
Options page. The authentication options described below specify the
locations of the key files, if other than default, which symmetric
keys are trusted and the interval between various operations, if other
than default.
Authentication is always enabled, although ineffective if not config-
ured as described below. If a NTP packet arrives including a message
authentication code (MAC), it is accepted only if it passes all cryp-
tographic checks. The checks require correct key ID, key value and
message digest. If the packet has been modified in any way or replayed
by an intruder, it will fail one or more of these checks and be dis-
carded. Furthermore, the Autokey scheme requires a preliminary proto-
col exchange to obtain the server certificate, verify its credentials
and initialize the protocol
The auth flag controls whether new associations or remote configura-
tion commands require cryptographic authentication. This flag can be
set or reset by the enable and disable commands and also by remote
configuration commands sent by a ntpdc program running on another
machine. If this flag is enabled, which is the default case, new
broadcast/manycast client and symmetric passive associations and
remote configuration commands must be cryptographically authenticated
using either symmetric key or public key cryptography. If this flag is
disabled, these operations are effective even if not cryptographic
authenticated. It should be understood that operating with the auth
flag disabled invites a significant vulnerability where a rogue hacker
can masquerade as a falseticker and seriously disrupt system timekeep-
ing. It is important to note that this flag has no purpose other than
to allow or disallow a new association in response to new broadcast
and symmetric active messages and remote configuration commands and,
in particular, the flag has no effect on the authentication process
itself.
An attractive alternative where multicast support is available is
manycast mode, in which clients periodically troll for servers as
described in the Automatic NTP Configuration Options page. Either sym-
metric key or public key cryptographic authentication can be used in
this mode. The principle advantage of manycast mode is that potential
servers need not be configured in advance, since the client finds them
during regular operation, and the configuration files for all clients
can be identical.
The security model and protocol schemes for both symmetric key and
public key cryptography are summarized below; further details are in
the briefings, papers and reports at the NTP project page linked from
www.ntp.org.
SYMMETRIC KEY CRYPTOGRAPHY
The original RFC-1305 specification allows any one of possibly 65,534
keys, each distinguished by a 32-bit key identifier, to authenticate
an association. The servers and clients involved must agree on the key
and key identifier to authenticate NTP packets. Keys and related
information are specified in a key file, usually called ntp.keys,
which must be distributed and stored using secure means beyond the
scope of the NTP protocol itself. Besides the keys used for ordinary
NTP associations, additional keys can be used as passwords for the
ntpq and ntpdc utility programs. When ntpd is first started, it reads
the key file specified in the keys configuration command and installs
the keys in the key cache. However, individual keys must be activated
with the trusted command before use. This allows, for instance, the
installation of possibly several batches of keys and then activating
or deactivating each batch remotely using ntpdc. This also provides a
revocation capability that can be used if a key becomes compromised.
The requestkey command selects the key used as the password for the
ntpdc utility, while the controlkey command selects the key used as
the password for the ntpq utility.
PUBLIC KEY CRYPTOGRAPHY
NTPv4 supports the original NTPv3 symmetric key scheme described in
RFC-1305 and in addition the Autokey protocol, which is based on pub-
lic key cryptography. The Autokey Version 2 protocol described on the
Autokey Protocol page verifies packet integrity using MD5 message
digests and verifies the source with digital signatures and any of
several digest/signature schemes. Optional identity schemes described
on the Identity Schemes page and based on cryptographic chal-
lenge/response algorithms are also available. Using all of these
schemes provides strong security against replay with or without modi-
fication, spoofing, masquerade and most forms of clogging attacks.
The cryptographic means necessary for all Autokey operations is pro-
vided by the OpenSSL software library. This library is available from
http://www.openssl.org and can be installed using the procedures out-
lined in the Building and Installing the Distribution page. Once
installed, the configure and build process automatically detects the
library and links the library routines required.
The Autokey protocol has several modes of operation corresponding to
the various NTP modes supported. Most modes use a special cookie which
can be computed independently by the client and server, but encrypted
in transmission. All modes use in addition a variant of the S-KEY
scheme, in which a pseudo-random key list is generated and used in
reverse order. These schemes are described along with an executive
summary, current status, briefing slides and reading list on the
Autonomous Authentication page.
The specific cryptographic environment used by Autokey servers and
clients is determined by a set of files and soft links generated by
the ntp-keygen program. This includes a required host key file,
required certificate file and optional sign key file, leapsecond file
and identity scheme files. The digest/signature scheme is specified in
the X.509 certificate along with the matching sign key. There are sev-
eral schemes available in the OpenSSL software library, each identi-
fied by a specific string such as md5WithRSAEncryption, which stands
for the MD5 message digest with RSA encryption scheme. The current NTP
distribution supports all the schemes in the OpenSSL library, includ-
ing those based on RSA and DSA digital signatures.
NTP secure groups can be used to define cryptographic compartments and
security hierarchies. It is important that every host in the group be
able to construct a certificate trail to one or more trusted hosts in
the same group. Each group host runs the Autokey protocol to obtain
the certificates for all hosts along the trail to one or more trusted
hosts. This requires the configuration file in all hosts to be engi-
neered so that, even under anticipated failure conditions, the NTP
subnet will form such that every group host can find a trail to at
least one trusted host.
NAMING AND ADDRESSING
It is important to note that Autokey does not use DNS to resolve
addresses, since DNS can’t be completely trusted until the name
servers have synchronized clocks. The cryptographic name used by
Autokey to bind the host identity credentials and cryptographic values
must be independent of interface, network and any other naming conven-
tion. The name appears in the host certificate in either or both the
subject and issuer fields, so protection against DNS compromise is
essential.
By convention, the name of an Autokey host is the name returned by the
Unix gethostname() system call or equivalent in other systems. By the
system design model, there are no provisions to allow alternate names
or aliases. However, this is not to say that DNS aliases, different
names for each interface, etc., are constrained in any way.
It is also important to note that Autokey verifies authenticity using
the host name, network address and public keys, all of which are bound
together by the protocol specifically to deflect masquerade attacks.
For this reason Autokey includes the source and destinatino IP
addresses in message digest computations and so the same addresses
must be available at both the server and client. For this reason oper-
ation with network address translation schemes is not possible. This
reflects the intended robust security model where government and cor-
porate NTP servers are operated outside firewall perimeters.
OPERATION
A specific combination of authentication scheme (none, symmetric key,
public key) and identity scheme is called a cryptotype, although not
all combinations are compatible. There may be management configura-
tions where the clients, servers and peers may not all support the
same cryptotypes. A secure NTPv4 subnet can be configured in many ways
while keeping in mind the principles explained above and in this sec-
tion. Note however that some cryptotype combinations may successfully
interoperate with each other, but may not represent good security
practice.
The cryptotype of an association is determined at the time of mobi-
lization, either at configuration time or some time later when a mes-
sage of appropriate cryptotype arrives. When mobilized by a server or
peer configuration command and no key or autokey subcommands are
present, the association is not authenticated; if the key subcommand
is present, the association is authenticated using the symmetric key
ID specified; if the autokey subcommand is present, the association is
authenticated using Autokey.
When multiple identity schemes are supported in the Autokey protocol,
the first message exchange determines which one is used. The client
request message contains bits corresponding to which schemes it has
available. The server response message contains bits corresponding to
which schemes it has available. Both server and client match the
received bits with their own and select a common scheme.
Following the principle that time is a public value, a server responds
to any client packet that matches its cryptotype capabilities. Thus, a
server receiving an unauthenticated packet will respond with an unau-
thenticated packet, while the same server receiving a packet of a
cryptotype it supports will respond with packets of that cryptotype.
However, unconfigured broadcast or manycast client associations or
symmetric passive associations will not be mobilized unless the server
supports a cryptotype compatible with the first packet received. By
default, unauthenticated associations will not be mobilized unless
overridden in a decidedly dangerous way.
Some examples may help to reduce confusion. Client Alice has no spe-
cific cryptotype selected. Server Bob has both a symmetric key file
and minimal Autokey files. Alice’s unauthenticated messages arrive at
Bob, who replies with unauthenticated messages. Cathy has a copy of
Bob’s symmetric key file and has selected key ID 4 in messages to Bob.
Bob verifies the message with his key ID 4. If it’s the same key and
the message is verified, Bob sends Cathy a reply authenticated with
that key. If verification fails, Bob sends Cathy a thing called a
crypto-NAK, which tells her something broke. She can see the evidence
using the ntpq program.
Denise has rolled her own host key and certificate. She also uses one
of the identity schemes as Bob. She sends the first Autokey message to
Bob and they both dance the protocol authentication and identity
steps. If all comes out okay, Denise and Bob continue as described
above.
It should be clear from the above that Bob can support all the girls
at the same time, as long as he has compatible authentication and
identity credentials. Now, Bob can act just like the girls in his own
choice of servers; he can run multiple configured associations with
multiple different servers (or the same server, although that might
not be useful). But, wise security policy might preclude some crypto-
type combinations; for instance, running an identity scheme with one
server and no authentication with another might not be wise.
KEY MANAGEMENT
The cryptographic values used by the Autokey protocol are incorporated
as a set of files generated by the ntp-keygen utility program, includ-
ing symmetric key, host key and public certificate files, as well as
sign key, identity parameters and leapseconds files. Alternatively,
host and sign keys and certificate files can be generated by the
OpenSSL utilities and certificates can be imported from public cer-
tificate authorities. Note that symmetric keys are necessary for the
ntpq and ntpdc utility programs. The remaining files are necessary
only for the Autokey protocol.
Certificates imported from OpenSSL or public certificate authorities
have certian limitations. The certificate should be in ASN.1 syntax,
X.509 Version 3 format and encoded in PEM, which is the same format
used by OpenSSL. The overall length of the certificate encoded in
ASN.1 must not exceed 1024 bytes. The subject distinguished name field
(CN) is the fully qualified name of the host on which it is used; the
remaining subject fields are ignored. The certificate extension fields
must not contain either a subject key identifier or a issuer key iden-
tifier field; however, an extended key usage field for a trusted host
must contain the value trustRoot;. Other extension fields are ignored.
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 ntpq 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 unspeci-
fied, 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 /etc/ntp. Following are the
subcommands:
cert file
Specifies the location of the required host public
certificate file. This overrides the link ntp-
key_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 ntpd, ntpq and
ntpdc 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 crypto-
graphic keys, parameters and certificates. The default is
/etc/ntp.
requestkey key
Specifies the key identifier to use with the ntpdc utility
program, which uses a proprietary protocol specific to this
implementation of ntpd. The key argument is a key identifier
for the trusted key, where the value can be in the range 1 to
65,534, inclusive.
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 expen-
sive 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 pur-
poses of authenticating peers with symmetric key cryptography,
as well as keys used by the ntpq and ntpdc programs. 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.
ERROR CODES
The following error codes are reported via the NTP control and moni-
toring protocol trap mechanism.
101 (bad field format or length)
The packet has invalid version, length or format.
102 (bad timestamp)
The packet timestamp is the same or older than the most recent
received. This could be due to a replay or a server clock time
step.
103 (bad filestamp)
The packet filestamp is the same or older than the most recent
received. This could be due to a replay or a key file genera-
tion error.
104 (bad or missing public key)
The public key is missing, has incorrect format or is an
unsupported type.
105 (unsupported digest type)
The server requires an unsupported digest/signature scheme.
106 (mismatched digest types)
Not used.
107 (bad signature length)
The signature length does not match the current public key.
108 (signature not verified)
The message fails the signature check. It could be bogus or
signed by a different private key.
109 (certificate not verified)
The certificate is invalid or signed with the wrong key.
110 (certificate not verified)
The certificate is not yet valid or has expired or the signa-
ture could not be verified.
111 (bad or missing cookie)
The cookie is missing, corrupted or bogus.
112 (bad or missing leapseconds table)
The leapseconds table is missing, corrupted or bogus.
113 (bad or missing certificate)
The certificate is missing, corrupted or bogus.
114 (bad or missing identity)
The identity key is missing, corrupt or bogus.
FILES
See the ntp-keygen page.
LEAPSECONDS TABLE
The NIST provides a file documenting the epoch for all historic occa-
sions of leap second insertion since 1972. The leapsecond table shows
each epoch of insertion along with the offset of International Atomic
Time (TAI) with respect to Coordinated Universal Time (UTC), as dis-
seminated by NTP. The table can be obtained directly from NIST
national time servers using ftp as the ASCII file pub/leap-seconds.
While not strictly a security function, the Autokey protocol provides
means to securely retrieve the leapsecond table from a server or peer.
Servers load the leapsecond table directly from the file specified in
the crypto command, with default ntpkey_leap, while clients can obtain
the table indirectly from the servers using the Autokey protocol. Once
loaded, the table can be provided on request to other clients and
servers.
SEE ALSO
ntp.conf(5), ntpd(8)
Primary source of documentation: /usr/share/doc/ntp-*
This file was automatically generated from HTML source.
ntp_auth(5)
