diff options
Diffstat (limited to 'util/ntp-keygen.texi')
| -rw-r--r-- | util/ntp-keygen.texi | 307 |
1 files changed, 307 insertions, 0 deletions
diff --git a/util/ntp-keygen.texi b/util/ntp-keygen.texi new file mode 100644 index 0000000..92cec48 --- /dev/null +++ b/util/ntp-keygen.texi @@ -0,0 +1,307 @@ +\input texinfo @c -*-texinfo-*- +@c %**start of header +@setfilename ntp-keygen.info +@settitle Ntp-keygen User's Manual +@include ../sntp/include/version.texi +@paragraphindent 2 +@c %**end of header + +@ifinfo +This file documents the use of the NTP Project's @code{ntp-keygen} +program, which generates various keys for @code{ntpd}, +@end ifinfo + +@direntry +* ntp-keygen: (ntp-keygen). NTP Key Generation +@end direntry + +@titlepage +@title NTP Key Generation User's Manual +@subtitle ntp-keygen, version @value{VERSION}, @value{UPDATED} +@c @author Max @email{foo@ntp.org} +@end titlepage + +@c @page +@c @vskip 0pt plus 1filll + +@shortcontents + +@menu +* Description:: +* ntp-keygen Invocation:: Invoking ntp-keygen +* Running the Program:: +* Random Seed File:: +* Cryptographic Data Files:: +@end menu + +@node Top, Description, (dir), (dir) +@top NTP Key Generation Program User Manual + +This document describes the use of the NTP Project's @code{ntp-keygen} +program, that generates cryptographic data files used by the NTPv4 +authentication and identity schemes. +It can generate message digest keys used in symmetric key cryptography and, +if the OpenSSL software +library has been installed, it can generate host keys, sign keys, +certificates, and identity keys and parameters used by the Autokey +public key cryptography. +The message digest keys file is generated in a +format compatible with NTPv3. +All other files are in PEM-encoded +printable ASCII format so they can be embedded as MIME attachments in +mail to other sites. + +This document applies to version @value{VERSION} of @code{ntp-keygen}. + +@node Description, Running the Program, Top, Top +@comment node-name, next, previous, up +@section Description + +This program generates cryptographic data files used by the NTPv4 +authentication and identity schemes. It can generate message digest +keys used in symmetric key cryptography and, if the OpenSSL software +library has been installed, it can generate host keys, sign keys, +certificates, and identity keys and parameters used by the Autokey +public key cryptography. The message digest keys file is generated in a +format compatible with NTPv3. All other files are in PEM-encoded +printable ASCII format so they can be embedded as MIME attachments in +mail to other sites. + +When used to generate message digest keys, the program produces a file +containing ten pseudo-random printable ASCII strings suitable for the +MD5 message digest algorithm included in the distribution. +If the +OpenSSL library is installed, it produces an additional ten hex-encoded +random bit strings suitable for the SHA1 and other message digest +algorithms. +The message digest keys file must be distributed and stored +using secure means beyond the scope of NTP itself. +Besides the keys +used for ordinary NTP associations, additional keys can be defined as +passwords for the ntpq and ntpdc utility programs. + +The remaining generated files are compatible with other OpenSSL +applications and other Public Key Infrastructure (PKI) resources. +Certificates generated by this program are compatible with extant +industry practice, although some users might find the interpretation of +X509v3 extension fields somewhat liberal. +However, the identity keys +are probably not compatible with anything other than Autokey. + +Some files used by this program are encrypted using a private password. +The @code{-p} option specifies the password for local encrypted files and the +@code{-q} option the password for encrypted files sent to remote sites. +If no password is specified, the host name returned by the Unix +@code{gethostname()} function, normally the DNS name of the host, is used. + +The @kbd{pw} option of the @code{crypto} configuration command +specifies the read password for previously encrypted local files. +This must match the local password used by this program. +If not specified, the host name is used. +Thus, if files are generated by this program without password, +they can be read back by ntpd without password, but only on the same +host. + +Normally, encrypted files for each host are generated by that host and +used only by that host, although exceptions exist as noted later on +this page. +The symmetric keys file, normally called @code{ntp.keys}, is +usually installed in @code{/etc}. +Other files and links are usually installed +in @code{/usr/local/etc}, which is normally in a shared filesystem in +NFS-mounted networks and cannot be changed by shared clients. +The location of the keys directory can be changed by the keysdir +configuration command in such cases. +Normally, this is in @code{/etc}. + +This program directs commentary and error messages to the standard +error stream @code{stderr} and remote files to the standard output stream +@code{stdout} where they can be piped to other applications or redirected to +files. +The names used for generated files and links all begin with the +string @code{ntpkey} and include the file type, +generating host and filestamp, +as described in the @ref{Cryptographic Data Files} section below. + +@node Running the Program, Random Seed File, Description, Top +@comment node-name, next, previous, up +@section Running the Program + +To test and gain experience with Autokey concepts, log in as root and +change to the keys directory, usually @code{/usr/local/etc}. +When run for the +first time, or if all files with names beginning @code{ntpkey}] have been +removed, use the @code{ntp-keygen} command without arguments to generate a +default RSA host key and matching RSA-MD5 certificate with expiration +date one year hence. +If run again without options, the program uses the +existing keys and parameters and generates only a new certificate with +new expiration date one year hence. + +Run the command on as many hosts as necessary. +Designate one of them as the trusted host (TH) using @code{ntp-keygen} +with the @code{-T} option and configure +it to synchronize from reliable Internet servers. +Then configure the other hosts to synchronize to the TH directly or indirectly. +A certificate trail is created when Autokey asks the immediately +ascendant host towards the TH to sign its certificate, which is then +provided to the immediately descendant host on request. +All group hosts should have acyclic certificate trails ending on the TH. + +The host key is used to encrypt the cookie when required and so must be +RSA type. +By default, the host key is also the sign key used to encrypt signatures. +A different sign key can be assigned using the @code{-S} option +and this can be either RSA or DSA type. +By default, the signature +message digest type is MD5, but any combination of sign key type and +message digest type supported by the OpenSSL library can be specified +using the @code{-c} option. + +The rules say cryptographic media should be generated with proventic +filestamps, which means the host should already be synchronized before +this program is run. +This of course creates a chicken-and-egg problem +when the host is started for the first time. +Accordingly, the host time +should be set by some other means, such as eyeball-and-wristwatch, at +least so that the certificate lifetime is within the current year. +After that and when the host is synchronized to a proventic source, the +certificate should be re-generated. + +Additional information on trusted groups and identity schemes is on the +Autokey Public-Key Authentication page. + +@include invoke-ntp-keygen.texi + +@node Random Seed File, Cryptographic Data Files, Running the Program, Top +@comment node-name, next, previous, up +@section Random Seed File + +All cryptographically sound key generation schemes must have means to +randomize the entropy seed used to initialize the internal +pseudo-random number generator used by the OpenSSL library routines. +If a site supports ssh, it is very likely that means to do this are +already available. +The entropy seed used by the OpenSSL library is contained in a file, +usually called @code{.rnd}, which must be available when +starting the @code{ntp-keygen} program or @code{ntpd} daemon. + +The OpenSSL library looks for the file using the path specified by the +@code{RANDFILE} environment variable in the user home directory, whether root +or some other user. +If the @code{RANDFILE} environment variable is not +present, the library looks for the @code{.rnd} file in the user home +directory. +Since both the @code{ntp-keygen} program and @code{ntpd} daemon must run +as root, the logical place to put this file is in @code{/.rnd} or +@code{/root/.rnd}. +If the file is not available or cannot be written, the program exits +with a message to the system log. + +@node Cryptographic Data Files, , Random Seed File, Top +@comment node-name, next, previous, up +@section Cryptographic Data Files + +File and link names are in the @code{form ntpkey_key_name.fstamp}, +where @code{key} is the key or parameter type, +@code{name} is the host or group name and +@code{fstamp} is the filestamp (NTP seconds) when the file was created). +By convention, key names in generated file names include both upper and +lower case characters, while key names in generated link names include +only lower case characters. The filestamp is not used in generated link +names. + +The key name is a string defining the cryptographic key type. +Key types include public/private keys host and sign, certificate cert +and several challenge/response key types. +By convention, client files used for +challenges have a par subtype, as in the IFF challenge IFFpar, while +server files for responses have a key subtype, as in the GQ response +GQkey. + +All files begin with two nonencrypted lines. The first line contains +the file name in the format @code{ntpkey_key_host.fstamp}. +The second line contains the datestamp in conventional Unix date format. +Lines beginning with @code{#} are ignored. + +The remainder of the file contains cryptographic data encoded first +using ASN.1 rules, then encrypted using the DES-CBC algorithm with +given password and finally written in PEM-encoded printable ASCII text +preceded and followed by MIME content identifier lines. + +The format of the symmetric keys file, ordinarily named @code{ntp.keys}, +is somewhat different than the other files in the interest of backward +compatibility. +Ordinarily, the file is generated by this program, but +it can be constructed and edited using an ordinary text editor. + +@example +# ntpkey_MD5key_hms.local.3564038757 +# Sun Dec 9 02:45:57 2012 + + 1 MD5 "]!ghT%O;3)WJ,/Nc:>I # MD5 key + 2 MD5 lu+H^tF46BKR-6~p{V_5 # MD5 key + 3 MD5 :lnoVsE%Y}z*avh%EtNC # MD5 key + 4 MD5 |fdZrf0sF~@PHZ;w-i^V # MD5 key + 5 MD5 IyAG>O"}y"LmCRS!*bHC # MD5 key + 6 MD5 ">e\A@>hT/661ri52,,H # MD5 key + 7 MD5 c9x=M'CfLxax9v)PV-si # MD5 key + 8 MD5 E|=jvFVov?Bn|Ev=&aK\ # MD5 key + 9 MD5 T!c4UT&`(m$+m+B6,`Q0 # MD5 key +10 MD5 JVF/1=)=IFbHbJQz..Cd # MD5 key +11 SHA1 6dea311109529e436c2b4fccae9bc753c16d1b48 # SHA1 key +12 SHA1 7076f373d86c4848c59ff8046e49cb7d614ec394 # SHA1 key +13 SHA1 5f48b1b60591eb01b7cf1d33b7774f08d20262d3 # SHA1 key +14 SHA1 eed5ab9d9497319ec60cf3781d52607e76720178 # SHA1 key +15 SHA1 f283562611a04c964da8126296f5f8e58c3f85de # SHA1 key +16 SHA1 1930da171297dd63549af50b29449de17dcf341f # SHA1 key +17 SHA1 fee892110358cd4382322b889869e750db8e8a8f # SHA1 key +18 SHA1 b5520c9fadd7ad3fd8bfa061c8821b65d029bb37 # SHA1 key +19 SHA1 8c74fb440ec80f453ec6aaa62b9baed0ab723b92 # SHA1 key +20 SHA1 6bc05f734306a189326000970c19b3910f403795 # SHA1 key +@end example + + Figure 1. Typical Symmetric Key File + +Figure 1 shows a typical symmetric keys file used by the reference +implementation. +Each line of the file contains three fields, first an +integer between 1 and 65534, inclusive, representing the key identifier +used in the server and peer configuration commands. +Next is the key type for the message digest algorithm, +which in the absence of the +OpenSSL library must be MD5 to designate the MD5 message digest +algorithm. +If the OpenSSL library is installed, the key type can be any +message digest algorithm supported by that library. +However, if +compatibility with FIPS 140-2 is required, the key type must be either +SHA or SHA1. +The key type can be changed using an ASCII text editor. + +An MD5 key consists of a printable ASCII string less than or equal to +16 characters and terminated by whitespace or a # character. +An OpenSSL +key consists of a hex-encoded ASCII string of 40 characters, which is +truncated as necessary. + +Note that the keys used by the @code{ntpq} and @code{ntpdc} programs are +checked against passwords requested by the programs and entered by hand, +so it +is generally appropriate to specify these keys in human readable ASCII +format. + +The @code{ntp-keygen} program generates a MD5 symmetric keys file +@code{ntpkey_MD5key_hostname.filestamp}. +Since the file contains private +shared keys, it should be visible only to root and distributed by +secure means to other subnet hosts. +The NTP daemon loads the file @code{ntp.keys}, so @code{ntp-keygen} +installs a soft link from this name to the generated file. +Subsequently, similar soft links must be installed by +manual or automated means on the other subnet hosts. +While this file is +not used with the Autokey Version 2 protocol, it is needed to +authenticate some remote configuration commands used by the @code{ntpq} and +@code{ntpdc} utilities. |