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