path: root/usr.sbin/ntp/doc/ntp_auth.8

.\"
.\" $FreeBSD$
.\"
.Dd January 11, 2000
.Dt NTP_AUTH 8
.Os
.Sh NAME
.Nm ntp_auth
.Nd NTP daemon authentication options
.Sh SYNOPSIS
.Pa /etc/ntp.conf
.Sh DESCRIPTION
Authentication support allows the NTP client to verify
that the server is in fact known and trusted
and not an intruder intending accidentally
or on purpose to masquerade as that server.
The NTPv3 specification RFC 1305 defines a scheme
which provides cryptographic authentication of received NTP packets.
Originally, this was done using the Data Encryption Standard (DES)
operating in Cipher Block Chaining (CBC) mode,
commonly called DES-CBC.
Subsequently, this was augmented by the RSA Message Digest 5 (MD5)
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 this scheme and, in addition,
provides a new autokey scheme based on reverse hashing
and public key cryptography.
Authentication can be configured separately for each association
using the key or autokey subcommands on the
.Ic peer Ns ,
.Ic server Ns ,
.Ic broadcast
and
.Ic manycastclient
commands as described in the
.Xr ntp_conf 8
page.
.Pp
The authentication options specify the suite of keys,
select the key for each configured association
and manage the configuration operations,
as described below.
The auth flag which controls these functions
can be set or reset by the
.Ic enable and
.Ic disable
configuration commands and also by remote configuration commands
sent by a
.Xr ntpdc 8
program running in another machine.
If this flag is set, persistent peer associations
and remote configuration commands are effective
only if cryptographically authenticated.
If this flag is disabled,
these operations are effective
even if not cryptographic authenticated.
It should be understood that operating in the latter mode
invites a significant vulnerability
where a rogue hacker can seriously disrupt client operations.
.Pp
The auth flag affects all authentication procedures described below;
however, it operates differently
if cryptographic support is compiled in the distribution.
If this support is available and the flag is enabled,
then persistent associations are mobilized
and remote configuration commands are effective
only if successfully authenticated.
If the support is unavailable and the flag is enabled,
then it is not possible under any conditions
to mobilize persistent associations
or respond to remote configuration commands.
The auth flag normally defaults to set
if cryptographic support is available and to reset otherwise.
.Pp
With the above vulnerabilities in mind,
it is desirable to set the auth flag in all cases.
One aspect which is often confusing
is the name resolution process
which maps server names in the configuration file to IP addresses.
In order to protect against bogus name server messages,
this process is authenticated
using an internally generated key
which is normally invisible to the user.
However, if cryptographic support is unavailable
and the auth flag is enabled,
the name resolution process will fail.
This can be avoided
either by specifying IP addresses instead of host names,
which is generally inadvisable,
or by leaving the flag disabled
and enabling it once the name resolution process is complete.
.Pp
Following is a description
of the two available cryptographic authentication schemes.
.Bl -tag -width indent
.It Private Key Scheme
The original RFC 1305 specification allows any one of possibly
65,536 keys, each distinguished a 32-bit key identifier,
to authenticate an association.
The servers involved must agree on the key
and key identifier to authenticate their messages.
Keys and related information are specified in a key file,
usually called
.Pq ntp.keys
which should be exchanged and stored using secure procedures
beyond the scope of the NTP protocol itself.
Besides the keys used for ordinary NTP associations,
additional ones can be used as passwords for the
.Xr ntpq 8
and
.Xr ntpdc 8
utility programs.
.Pp
When
.Xr ntpd 8
is first started,
it reads the key file and installs the keys in the key cache.
However, the keys must be activated
before they can be used with the trusted command.
This allows, for instance,
the installation of possibly several batches of keys
and then activating or inactivating each batch remotely using
.Xr ntpdc 8 .
This also provides a revocation capability
that can be used if a key becomes compromised.
The
.Ic requestkey
command selects the key used as the password for the
.Xr ntpdc 8
utility,
while the
.Ic controlkey
command selects the key used as the password for the the
.Xr ntpq 8
utility.
.It Autokey Scheme
The original NTPv3 authentication scheme
described in RFC 1305 continues to be supported.
In NTPv4,
an additional authentication scheme called autokey is available.
It operates much like the S-KEY scheme,
in that a session key list is constructed
and the entries used in reverse order.
A description of the scheme,
along with a comprehensive security analysis,
is contained in a technical report
available from the IETF web page
.Li http://www.ietf.org/ .
.Pp
The autokey scheme is specifically designed for multicast modes,
where clients normally do not send messages to the server.
In these modes,
the server uses the scheme to generate a key list
by repeated hashing of a secret value.
The list is used in reverse order
to generate a unique session key for each message sent.
The client regenerates the session key
and verifies the hash matches the previous session key.
Each message contains the public values
binding the session key to the secret value,
but these values need to be verified
only when the server generates a new key list
or more than four server messages have been lost.
.Pp
The scheme is appropriate for client/server
and symmetric-peer modes as well.
In these modes,
the client generates a session key as in multicast modes.
The server regenerates the session key
and uses it to formulates a reply using its own public values.
The client verifies
the key identifier of the reply matches the request,
verifies the public values and validates the message.
In peer mode, each peer independently generates a key list
and operates as in the multicast mode.
.Pp
The autokey scheme requires no change to the NTP packet header format
or message authentication code (MAC), which is appended to the header;
however, if autokey is in use, an extensions field is inserted
between the header and MAC.
The extensions field contains a random public value
which is updated at intervals specified by the revoke command,
together with related cryptographic values
used in the signing algorithm.
The format of the extensions field is defined in
Internet Draft
.Li draft-NTP-auth-coexist-00.txt .
The MAC itself is constructed in the same way as NTPv3,
but using the original NTP header
and the extensions field padded to a 64-bit boundary.
Each new public value is encrypted by the host private value.
It is the intent of the design, not yet finalized,
that the public value, encrypted public value,
public key and certificate be embedded in the extensions field
where the client can decrypt as needed.
However, the relatively expensive encryption
and decryption operations are necessary
only when the public value is changed.
.Pp
Note that both the original NTPv3 authentication scheme
and the new NTPv4 autokey scheme
operate separately for each configured association,
so there may be several session key lists
operating independently at the same time.
Since all keys, including session keys,
occupy the same key cache,
provisions have been made to avoid collisions,
where some random roll happens to collide
with another already generated.
Since something like four billion different session key identifiers
are available,
the chances are small that this might happen.
If it happens during generation,
the generator terminates the current session key list.
By the time the next list is generated,
the collided key will probably have been expired or revoked.
.Pp
While permanent keys have lifetimes that expire
only when manually revoked,
random session keys have a lifetime
specified at the time of generation.
When generating a key list for an association,
the lifetime of each key is set to expire
one poll interval later than it is scheduled to be used.
The maximum lifetime of any key in the list
is specified by the
.Ic autokey
command.
Lifetime enforcement is a backup
to the normal procedure that revokes the last-used key
at the time the next key on the key list is used.
.El
.Ss Authentication Commands
The following authentication commands are available:
.Bl -tag -width indent
.It Ic keys Ar keyfile
Specifies the file name containing the encryption keys and
key identifiers used by
.Xr ntpd 8 ,
.Xr ntpq 8
and
.Xr ntpdc 8
when operating in authenticated mode.
The format of this file is described later in this document.
.It Xo Ic trustedkey
.Ar key
.Op ...
.Xc
Specifies the encryption key identifiers which are trusted
for the purposes of authenticating peers
suitable for synchronization, as well as keys used by the
.Xr ntpq 8
and
.Xr ntpdc 8
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
.Ar trustedkey
arguments are 32-bit unsigned integers
with values less than 65,536.
Note that NTP key 0 is used to indicate an invalid key
and/or key identifier,
so should not be used for any other purpose.
.It Ic requestkey Ar key
Specifies the key identifier to use with the
.Xr ntpdc 8
program,
which uses a proprietary protocol
specific to this implementation of
.Xr ntpd 8 .
This program is useful to diagnose and repair problems
that affect
.Xr ntpd 8
operation.
The
.Ar key
argument to this command is a 32-bit key identifier
for a previously defined trusted key.
If no
.Ic requestkey
command is included in
the configuration file,
or if the keys don't match,
any request to change a server variable with be denied.
.It Ic controlkey Ar key
Specifies the key identifier to use with the
.Xr ntpq 8
program,
which uses the standard protocol defined in RFC 1305.
This program is useful to diagnose and repair problems
that affect
.Xr ntpd 8
operation.
The
.Ar key
argument to this command is a 32-bit key identifier
for a trusted key in the key cache.
If no
.Ic controlkey
command is included in the configuration file,
or if the keys don't match,
any request to change a server variable with be denied.
.El
.Ss Authentication Key File Format
In the case of DES, the keys are 56 bits long with,
depending on type, a parity check on each byte.
In the case of MD5, the keys are 64 bits (8 bytes).
.Xr ntpd 8
reads its keys from a file specified using the
.Fl k
command line option or the
.Ic keys
statement in the configuration file.
While key number 0 is fixed by the NTP standard
(as 56 zero bits)
and may not be changed,
one or more of the keys numbered 1 through 15
may be arbitrarily set in the keys file.
.Pp
The key file uses the same comment conventions
as the configuration file.
Key entries use a fixed format of the form
.Pp
.Dl keyno type key
.Pp
where
.Ar keyno
is a positive integer,
.Ar type
is a single character which defines the key format,
and
.Ar key
is the key itself.
.Pp
The
.Ar key
may be given in one of three different formats,
controlled by the
.Ar type
character.
The three key types, and corresponding formats,
are listed following.
.Bl -tag -width indent
.It S
The
.Ar key
is a 64-bit hexadecimal number in the format
specified in the DES specification;
that is, the high order seven bits of each octet are used
to form the 56-bit key
while the low order bit of each octet is given a value
such that odd parity is maintained for the octet.
Leading zeroes must be specified
(i.e. the key must be exactly 16 hex digits long)
and odd parity must be maintained.
Hence a zero
.Ar key ,
in standard format, would be given as
.Li 0101010101010101 .
.It N
The
.Ar key
is a 64-bit hexadecimal number in the format
specified in the NTP standard.
This is the same as the DES format,
except the bits in each octet have been rotated one bit right
so that the parity bit is now the high order bit of the octet.
Leading zeroes must be specified and odd parity must be maintained.
A zero
.Ar key
in NTP format would be specified as
.Li 8080808080808080 .
.It A
The
.Ar key
is a 1-to-8 character ASCII string.
A key is formed from this by using the low order 7 bits
of each ASCII character in the string,
with zeroes added on the right
when necessary to form a full width 56-bit key,
in the same way that encryption keys are formed from Unix passwords.
.It M
The
.Ar key
is a 1-to-8 character ASCII string,
using the MD5 authentication scheme.
Note that both the keys and the authentication schemes (DES or MD5)
must be identical between a set of peers sharing the same key number.
.El
.Pp
Note that the keys used by the
.Xr ntpq 8
and
.Xr ntpdc 8
programs are checked against passwords
requested by the programs and entered by hand,
so it is generally appropriate to specify these keys in ASCII format.
.Sh SEE ALSO
.Xr ntp_conf 8 ,
.Xr ntpd 8 ,
.Xr ntpdc 8 ,
.Xr ntpq 8
.Rs
.%A David L. Mills
.%T Network Time Protocol (Version 3)
.%O RFC1305
.Re
.Sh HISTORY
Written by
.An Dennis Ferguson
at the University of Toronto.
Text amended by
.An David Mills
at the University of Delaware.