ntp-keygen.texi revision 1.1.1.1
1\input texinfo @c -*-texinfo-*- 2@c %**start of header 3@setfilename ntp-keygen.info 4@settitle Ntp-keygen User's Manual 5@include ../sntp/include/version.texi 6@paragraphindent 2 7@c %**end of header 8 9@ifinfo 10This file documents the use of the NTP Project's @code{ntp-keygen} 11program, which generates various keys for @code{ntpd}, 12@end ifinfo 13 14@direntry 15* ntp-keygen: (ntp-keygen). NTP Key Generation 16@end direntry 17 18@titlepage 19@title NTP Key Generation User's Manual 20@subtitle ntp-keygen, version @value{VERSION}, @value{UPDATED} 21@c @author Max @email{foo@ntp.org} 22@end titlepage 23 24@c @page 25@c @vskip 0pt plus 1filll 26 27@shortcontents 28 29@menu 30* Description:: 31* ntp-keygen Invocation:: Invoking ntp-keygen 32* Running the Program:: 33* Random Seed File:: 34* Cryptographic Data Files:: 35@end menu 36 37@node Top, Description, (dir), (dir) 38@top NTP Key Generation Program User Manual 39 40This document describes the use of the NTP Project's @code{ntp-keygen} 41program, that generates cryptographic data files used by the NTPv4 42authentication and identity schemes. 43It can generate message digest keys used in symmetric key cryptography and, 44if the OpenSSL software 45library has been installed, it can generate host keys, sign keys, 46certificates, and identity keys and parameters used by the Autokey 47public key cryptography. 48The message digest keys file is generated in a 49format compatible with NTPv3. 50All other files are in PEM-encoded 51printable ASCII format so they can be embedded as MIME attachments in 52mail to other sites. 53 54This document applies to version @value{VERSION} of @code{ntp-keygen}. 55 56@node Description, Running the Program, Top, Top 57@comment node-name, next, previous, up 58@section Description 59 60This program generates cryptographic data files used by the NTPv4 61authentication and identity schemes. It can generate message digest 62keys used in symmetric key cryptography and, if the OpenSSL software 63library has been installed, it can generate host keys, sign keys, 64certificates, and identity keys and parameters used by the Autokey 65public key cryptography. The message digest keys file is generated in a 66format compatible with NTPv3. All other files are in PEM-encoded 67printable ASCII format so they can be embedded as MIME attachments in 68mail to other sites. 69 70When used to generate message digest keys, the program produces a file 71containing ten pseudo-random printable ASCII strings suitable for the 72MD5 message digest algorithm included in the distribution. 73If the 74OpenSSL library is installed, it produces an additional ten hex-encoded 75random bit strings suitable for the SHA1 and other message digest 76algorithms. 77The message digest keys file must be distributed and stored 78using secure means beyond the scope of NTP itself. 79Besides the keys 80used for ordinary NTP associations, additional keys can be defined as 81passwords for the ntpq and ntpdc utility programs. 82 83The remaining generated files are compatible with other OpenSSL 84applications and other Public Key Infrastructure (PKI) resources. 85Certificates generated by this program are compatible with extant 86industry practice, although some users might find the interpretation of 87X509v3 extension fields somewhat liberal. 88However, the identity keys 89are probably not compatible with anything other than Autokey. 90 91Some files used by this program are encrypted using a private password. 92The @code{-p} option specifies the password for local encrypted files and the 93@code{-q} option the password for encrypted files sent to remote sites. 94If no password is specified, the host name returned by the Unix 95@code{gethostname()} function, normally the DNS name of the host, is used. 96 97The @kbd{pw} option of the @code{crypto} configuration command 98specifies the read password for previously encrypted local files. 99This must match the local password used by this program. 100If not specified, the host name is used. 101Thus, if files are generated by this program without password, 102they can be read back by ntpd without password, but only on the same 103host. 104 105Normally, encrypted files for each host are generated by that host and 106used only by that host, although exceptions exist as noted later on 107this page. 108The symmetric keys file, normally called @code{ntp.keys}, is 109usually installed in @code{/etc}. 110Other files and links are usually installed 111in @code{/usr/local/etc}, which is normally in a shared filesystem in 112NFS-mounted networks and cannot be changed by shared clients. 113The location of the keys directory can be changed by the keysdir 114configuration command in such cases. 115Normally, this is in @code{/etc}. 116 117This program directs commentary and error messages to the standard 118error stream @code{stderr} and remote files to the standard output stream 119@code{stdout} where they can be piped to other applications or redirected to 120files. 121The names used for generated files and links all begin with the 122string @code{ntpkey} and include the file type, 123generating host and filestamp, 124as described in the @ref{Cryptographic Data Files} section below. 125 126@node Running the Program, Random Seed File, Description, Top 127@comment node-name, next, previous, up 128@section Running the Program 129 130To test and gain experience with Autokey concepts, log in as root and 131change to the keys directory, usually @code{/usr/local/etc}. 132When run for the 133first time, or if all files with names beginning @code{ntpkey}] have been 134removed, use the @code{ntp-keygen} command without arguments to generate a 135default RSA host key and matching RSA-MD5 certificate with expiration 136date one year hence. 137If run again without options, the program uses the 138existing keys and parameters and generates only a new certificate with 139new expiration date one year hence. 140 141Run the command on as many hosts as necessary. 142Designate one of them as the trusted host (TH) using @code{ntp-keygen} 143with the @code{-T} option and configure 144it to synchronize from reliable Internet servers. 145Then configure the other hosts to synchronize to the TH directly or indirectly. 146A certificate trail is created when Autokey asks the immediately 147ascendant host towards the TH to sign its certificate, which is then 148provided to the immediately descendant host on request. 149All group hosts should have acyclic certificate trails ending on the TH. 150 151The host key is used to encrypt the cookie when required and so must be 152RSA type. 153By default, the host key is also the sign key used to encrypt signatures. 154A different sign key can be assigned using the @code{-S} option 155and this can be either RSA or DSA type. 156By default, the signature 157message digest type is MD5, but any combination of sign key type and 158message digest type supported by the OpenSSL library can be specified 159using the @code{-c} option. 160 161The rules say cryptographic media should be generated with proventic 162filestamps, which means the host should already be synchronized before 163this program is run. 164This of course creates a chicken-and-egg problem 165when the host is started for the first time. 166Accordingly, the host time 167should be set by some other means, such as eyeball-and-wristwatch, at 168least so that the certificate lifetime is within the current year. 169After that and when the host is synchronized to a proventic source, the 170certificate should be re-generated. 171 172Additional information on trusted groups and identity schemes is on the 173Autokey Public-Key Authentication page. 174 175@include invoke-ntp-keygen.texi 176 177@node Random Seed File, Cryptographic Data Files, Running the Program, Top 178@comment node-name, next, previous, up 179@section Random Seed File 180 181All cryptographically sound key generation schemes must have means to 182randomize the entropy seed used to initialize the internal 183pseudo-random number generator used by the OpenSSL library routines. 184If a site supports ssh, it is very likely that means to do this are 185already available. 186The entropy seed used by the OpenSSL library is contained in a file, 187usually called @code{.rnd}, which must be available when 188starting the @code{ntp-keygen} program or @code{ntpd} daemon. 189 190The OpenSSL library looks for the file using the path specified by the 191@code{RANDFILE} environment variable in the user home directory, whether root 192or some other user. 193If the @code{RANDFILE} environment variable is not 194present, the library looks for the @code{.rnd} file in the user home 195directory. 196Since both the @code{ntp-keygen} program and @code{ntpd} daemon must run 197as root, the logical place to put this file is in @code{/.rnd} or 198@code{/root/.rnd}. 199If the file is not available or cannot be written, the program exits 200with a message to the system log. 201 202@node Cryptographic Data Files, , Random Seed File, Top 203@comment node-name, next, previous, up 204@section Cryptographic Data Files 205 206File and link names are in the @code{form ntpkey_key_name.fstamp}, 207where @code{key} is the key or parameter type, 208@code{name} is the host or group name and 209@code{fstamp} is the filestamp (NTP seconds) when the file was created). 210By convention, key names in generated file names include both upper and 211lower case characters, while key names in generated link names include 212only lower case characters. The filestamp is not used in generated link 213names. 214 215The key name is a string defining the cryptographic key type. 216Key types include public/private keys host and sign, certificate cert 217and several challenge/response key types. 218By convention, client files used for 219challenges have a par subtype, as in the IFF challenge IFFpar, while 220server files for responses have a key subtype, as in the GQ response 221GQkey. 222 223All files begin with two nonencrypted lines. The first line contains 224the file name in the format @code{ntpkey_key_host.fstamp}. 225The second line contains the datestamp in conventional Unix date format. 226Lines beginning with @code{#} are ignored. 227 228The remainder of the file contains cryptographic data encoded first 229using ASN.1 rules, then encrypted using the DES-CBC algorithm with 230given password and finally written in PEM-encoded printable ASCII text 231preceded and followed by MIME content identifier lines. 232 233The format of the symmetric keys file, ordinarily named @code{ntp.keys}, 234is somewhat different than the other files in the interest of backward 235compatibility. 236Ordinarily, the file is generated by this program, but 237it can be constructed and edited using an ordinary text editor. 238 239@example 240# ntpkey_MD5key_hms.local.3564038757 241# Sun Dec 9 02:45:57 2012 242 243 1 MD5 "]!ghT%O;3)WJ,/Nc:>I # MD5 key 244 2 MD5 lu+H^tF46BKR-6~p{V_5 # MD5 key 245 3 MD5 :lnoVsE%Y}z*avh%EtNC # MD5 key 246 4 MD5 |fdZrf0sF~@PHZ;w-i^V # MD5 key 247 5 MD5 IyAG>O"}y"LmCRS!*bHC # MD5 key 248 6 MD5 ">e\A@>hT/661ri52,,H # MD5 key 249 7 MD5 c9x=M'CfLxax9v)PV-si # MD5 key 250 8 MD5 E|=jvFVov?Bn|Ev=&aK\ # MD5 key 251 9 MD5 T!c4UT&`(m$+m+B6,`Q0 # MD5 key 25210 MD5 JVF/1=)=IFbHbJQz..Cd # MD5 key 25311 SHA1 6dea311109529e436c2b4fccae9bc753c16d1b48 # SHA1 key 25412 SHA1 7076f373d86c4848c59ff8046e49cb7d614ec394 # SHA1 key 25513 SHA1 5f48b1b60591eb01b7cf1d33b7774f08d20262d3 # SHA1 key 25614 SHA1 eed5ab9d9497319ec60cf3781d52607e76720178 # SHA1 key 25715 SHA1 f283562611a04c964da8126296f5f8e58c3f85de # SHA1 key 25816 SHA1 1930da171297dd63549af50b29449de17dcf341f # SHA1 key 25917 SHA1 fee892110358cd4382322b889869e750db8e8a8f # SHA1 key 26018 SHA1 b5520c9fadd7ad3fd8bfa061c8821b65d029bb37 # SHA1 key 26119 SHA1 8c74fb440ec80f453ec6aaa62b9baed0ab723b92 # SHA1 key 26220 SHA1 6bc05f734306a189326000970c19b3910f403795 # SHA1 key 263@end example 264 265 Figure 1. Typical Symmetric Key File 266 267Figure 1 shows a typical symmetric keys file used by the reference 268implementation. 269Each line of the file contains three fields, first an 270integer between 1 and 65534, inclusive, representing the key identifier 271used in the server and peer configuration commands. 272Next is the key type for the message digest algorithm, 273which in the absence of the 274OpenSSL library must be MD5 to designate the MD5 message digest 275algorithm. 276If the OpenSSL library is installed, the key type can be any 277message digest algorithm supported by that library. 278However, if 279compatibility with FIPS 140-2 is required, the key type must be either 280SHA or SHA1. 281The key type can be changed using an ASCII text editor. 282 283An MD5 key consists of a printable ASCII string less than or equal to 28416 characters and terminated by whitespace or a # character. 285An OpenSSL 286key consists of a hex-encoded ASCII string of 40 characters, which is 287truncated as necessary. 288 289Note that the keys used by the @code{ntpq} and @code{ntpdc} programs are 290checked against passwords requested by the programs and entered by hand, 291so it 292is generally appropriate to specify these keys in human readable ASCII 293format. 294 295The @code{ntp-keygen} program generates a MD5 symmetric keys file 296@code{ntpkey_MD5key_hostname.filestamp}. 297Since the file contains private 298shared keys, it should be visible only to root and distributed by 299secure means to other subnet hosts. 300The NTP daemon loads the file @code{ntp.keys}, so @code{ntp-keygen} 301installs a soft link from this name to the generated file. 302Subsequently, similar soft links must be installed by 303manual or automated means on the other subnet hosts. 304While this file is 305not used with the Autokey Version 2 protocol, it is needed to 306authenticate some remote configuration commands used by the @code{ntpq} and 307@code{ntpdc} utilities. 308