usr.sbin/ntp/doc/ntp-genkeys.8

   1 .\"
   2 .\" $FreeBSD: src/usr.sbin/ntp/doc/ntp-genkeys.8,v 1.1.2.2 2003/03/11 22:31:29 trhodes Exp $
   3 .\" $DragonFly: src/usr.sbin/ntp/doc/Attic/ntp-genkeys.8,v 1.2 2003/06/17 04:29:58 dillon Exp $
   4 .\"
   5 .Dd August  2, 2001
   6 .Dt NTP_GENKEYS 8
   7 .Os
   8 .Sh NAME
   9 .Nm ntp-genkeys
  10 .Nd generate public and private keys
  11 .Sh SYNOPSIS
  12 .Nm
  13 .Op Fl dfhlnt
  14 .Op Fl c Ar conffile
  15 .Op Fl g Ar target
  16 .Op Fl k Ar keyfile
  17 .Sh DESCRIPTION
  18 The
  19 .Nm
  20 utility generates random keys used by either or both the
  21 NTPv3/NTPv4 symmetric key or the NTPv4 public key (Autokey)
  22 cryptographic authentication schemes.
  23 .Pp
  24 The following options are available:
  25 .Bl -tag -width indent
  26 .It Fl c Ar conffile
  27 Location of
  28 .Xr ntp.conf 8
  29 file.
  30 .It Fl d
  31 enable debug messages (can be used multiple times)
  32 .It Fl f
  33 force installation of generated keys.
  34 .It Fl g target
  35 Generate file or files indicated by the characters in the
  36 .Ar target
  37 string:
  38 .Bl -tag -width X
  39 .It Li d
  40 Generate D-H parameter file.
  41 .It Li m
  42 Generate MD5 key file.
  43 .It Li r
  44 Generate RSA keys.
  45 .El
  46 .It Fl h
  47 Build keys here (current directory).
  48 Implies
  49 .Fl l .
  50 .It Fl k Ar keyfile
  51 Location of key file.
  52 .It Fl l
  53 Do not make the symlinks.
  54 .It Fl n
  55 Do not actually do anything, just say what would be done.
  56 .It Fl t
  57 Trash the (old) files at the end of symlink.
  58 .El
  59 .Pp
  60 By default the program
  61 generates the
  62 .Xr ntp.keys 5
  63 file containing 16 random symmetric
  64 keys.
  65 In addition, if the
  66 rsaref20
  67 package is configured
  68 for the software build, the program generates cryptographic values
  69 used by the Autokey scheme.
  70 These values are incorporated as a set
  71 of three files,
  72 .Pa ntpkey
  73 containing the RSA private key,
  74 .Pa ntpkey_ Ns Ar host
  75 containing the RSA public key, where
  76 .Ar host
  77 is the DNS name of the generating machine, and
  78 .Pa ntpkey_dh
  79 containing the parameters for the Diffie-Hellman
  80 key-agreement algorithm.
  81 All files and are in printable ASCII
  82 format.
  83 A timestamp in NTP seconds is appended to each.
  84 Since the
  85 algorithms are seeded by the system clock, each run of this program
  86 produces a different file and file name.
  87 .Pp
  88 The
  89 .Xr ntp.keys 5
  90 file contains 16 MD5 keys.
  91 Each key
  92 consists of 16 characters randomized over the ASCII 95-character
  93 printing subset.
  94 The file is read by the daemon at the location
  95 specified by the
  96 .Ic keys
  97 configuration file command and made
  98 visible only to root.
  99 An additional key consisting of an easily
 100 remembered password should be added by hand for use with the
 101 .Xr ntpq 8
 102 and
 103 .Xr ntpdc 8
 104 programs.
 105 The file must be
 106 distributed by secure means to other servers and clients sharing
 107 the same security compartment.
 108 While the key identifiers for MD5
 109 and DES keys must be in the range 1-65534, inclusive, the
 110 .Nm
 111 utility uses only the identifiers from 1 to
 112 16.
 113 The key identifier for each association is specified as the key
 114 argument in the
 115 .Ic server
 116 or
 117 .Ic peer
 118 configuration file command.
 119 .Pp
 120 The
 121 .Pa ntpkey
 122 file contains the RSA private key.
 123 It is
 124 read by the daemon at the location specified by the
 125 .Ar privatekey
 126 argument of the
 127 .Ic crypto
 128 configuration
 129 file command and made visible only to root.
 130 This file is useful
 131 only to the machine that generated it and never shared with any
 132 other daemon or application program.
 133 .Pp
 134 The
 135 .Pa ntpkey_ Ns Ar host
 136 file contains the RSA public
 137 key, where
 138 .Ar host
 139 is the DNS name of the host that
 140 generated it.
 141 The file is read by the daemon at the location
 142 specified by the
 143 .Ar publickey
 144 argument to the
 145 .Ic server
 146 or
 147 .Ic peer
 148 configuration file command.
 149 This file can be
 150 widely distributed and stored without using secure means, since the
 151 data are public values.
 152 .Pp
 153 The
 154 .Pa ntp_dh
 155 file contains two Diffie-Hellman parameters:
 156 the prime modulus and the generator.
 157 The file is read by the daemon
 158 at the location specified by the
 159 .Ar dhparams
 160 argument of the
 161 .Ic crypto
 162 configuration file command.
 163 The file can be
 164 distributed by insecure means to other servers and clients sharing
 165 the same key agreement compartment, since the data are public
 166 values.
 167 .Pp
 168 The file formats begin with two lines, the first containing the
 169 generating system DNS name and the second the datestamp.
 170 Lines
 171 beginning with
 172 .Ql #
 173 are considered comments and ignored by
 174 the daemon.
 175 In the
 176 .Xr ntp.keys 5
 177 file, the next 16 lines
 178 contain the MD5 keys in order.
 179 If necessary, this file can be
 180 further customized by an ordinary text editor.
 181 The format is
 182 described in the following section.
 183 In the
 184 .Pa ntpkey
 185 and
 186 .Pa ntpkey_ Ns Ar host
 187 files, the next line contains the
 188 modulus length in bits followed by the key as a PEM encoded string.
 189 In the
 190 .Pa ntpkey_dh
 191 file, the next line contains the prime
 192 length in bytes followed by the prime as a PEM encoded string, and
 193 the next and final line contains the generator length in bytes
 194 followed by the generator as a PEM encoded string.
 195 .Pp
 196 Note: See the file
 197 .Pa ./source/rsaref.h
 198 in the
 199 rsaref20
 200 package for explanation of return values, if
 201 necessary.
 202 .Sh SEE ALSO
 203 .Xr ntp.keys 5 ,
 204 .Xr ntpdc 8 ,
 205 .Xr ntpq 8
 206 .Sh BUGS
 207 It can take quite a while to generate the RSA public/private key
 208 pair and Diffie-Hellman parameters, from a few seconds on a modern
 209 workstation to several minutes on older machines.