'\" t
.\"     Title: ntp.keys
.\"    Author: [see the "AUTHOR(S)" section]
.\" Generator: Asciidoctor 2.0.12
.\"      Date: 2021-06-17
.\"    Manual: NTPsec
.\"    Source: NTPsec
.\"  Language: English
.\"
.TH "NTP.KEYS" "5" "2021-06-17" "NTPsec" "NTPsec"
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.ss \n[.ss] 0
.nh
.ad l
.de URL
\fI\\$2\fP <\\$1>\\$3
..
.als MTO URL
.if \n[.g] \{\
.  mso www.tmac
.  am URL
.    ad l
.  .
.  am MTO
.    ad l
.  .
.  LINKSTYLE blue R < >
.\}
.SH "NAME"
ntp.keys \- NTP symmetric key file format
.SH "DESCRIPTION"
.sp
This document describes the format of an NTP symmetric key file. For a
description of the use of this type of file, see the "Authentication
Support" page of the Web documentation.
.sp
ntpd(8) reads its keys from a file specified using the \-k command line
option or the \fIkeys\fP 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 keys numbered between 1 and 65535 may be
arbitrarily set in the keys file.
.sp
The key file uses the same comment conventions as the configuration
file. Key entries use a fixed format of the form
.sp
.if n .RS 4
.nf
.fam C
keyno type key
.fam
.fi
.if n .RE
.sp
where \f(CRkeyno\fP is a positive integer (between 1 and 65535),
\f(CRtype\fP is the message digest or cipher algorithm, and
\f(CRkey\fP is the key itself.
.sp
The file does not need to be sorted by \f(CRkeyno\fP.
.sp
\f(CRtype\fP can be the name of any digest or cipher supported by your
OpenSSL package.  Digests or CMACs longer than 20 bytes will be truncated.
.sp
You can get a list from \f(CRopenssl list \-digest\-algorithms\fP or
\f(CRopenssl list \-cipher\-algorithms\fP.
(As of Jan 2018, they lie.  Be sure to try it.  ntpd(8) will
print an error on startup if a selected type isn\(cqt supported.)
.sp
The following types are widely supported:
.sp
.if n .RS 4
.nf
.fam C
  md5, sha1, ripemd160, sha224, sha256, sha384, sha512
  aes\-128, aes\-192, aes\-256
.fam
.fi
.if n .RE
.sp
Only the \f(CR\-cbc\fP cipher modes are useful.
The \f(CR\-cbc\fP is appended to the \f(CRtype\fP internally. Do not include it in \f(CRtype\fP.
.sp
AES is an abbreviation for aes\-128.
.sp
Note that MD5 was deprecated by RFC 8573 in June of 2019.
\f(CRAES\-128\fP is currently prefered.  The code still supports
MD5 for backwards compatibility.
.sp
FIPS 140\-2, FIPS 180\-4, and/or FIPS 202 may restrict your choices.
If it matters to you, check with your lawyer.  (Let us know if you
find a good reference.)
.sp
The \f(CRkey\fP may be printable ASCII excluding "#" or hex encoded.
Keys longer than 20 characters are assumed to be hex.  The max
length of a (de\-hexified) key is 32 bytes.  If you
want to use an ASCII key longer than 20 bytes, you must hexify it.
.sp
Note that the keys used by the ntpq(1) programs are
checked against passwords entered by hand, so it is generally
appropriate to specify these keys in ASCII format.  Or you can
cut\-paste a hex string from your password manager.
.SH "USAGE"
.sp
In order to use symmetric keys, the client side configuration file needs:
.sp
.if n .RS 4
.nf
.fam C
  keys <path\-to\-client\-keys\-file>
  trustedkey <keyno>
  server ... key <keyno>
.fam
.fi
.if n .RE
.sp
The server side needs:
.sp
.if n .RS 4
.nf
.fam C
  keys <path\-to\-server\-keys\-file>
  trustedkey <keyno>
.fam
.fi
.if n .RE
.sp
Note that the client and server key files must both contain identical
copies of the line specified by keyno.
.SH "FILES"
.sp
\f(CR/etc/ntpsec/ntp.keys\fP
.RS 4
is a common location for the keys file
.RE
.sp
Reminder: You have to keep it secret.
.SH "SEE ALSO"
.sp
ntp.conf(5), ntpd(8), ntpq(1), ntpkeygen(8), ntpdig(1).