contrib/ntp/ntpd/ntp.keys.def

   1 /* -*- Mode: Text -*- */
   2
   3 autogen definitions options;
   4
   5 #include copyright.def
   6 #include version.def
   7
   8 // We want the synopsis to be "/etc/ntp.keys" but we need the prog-name
   9 // to be ntp.keys - the latter is also how autogen produces the output
  10 // file name.
  11 prog-name       = "ntp.keys";
  12 file-path       = "/etc/ntp.keys";
  13 prog-title      = "NTP symmetric key file format";
  14
  15 /* explain: Additional information whenever the usage routine is invoked */
  16 explain = <<- _END_EXPLAIN
  17         _END_EXPLAIN;
  18
  19 doc-section     = {
  20   ds-type       = 'DESCRIPTION';
  21   ds-format     = 'mdoc';
  22   ds-text       = <<- _END_PROG_MDOC_DESCRIP
  23 This document describes the format of an NTP symmetric key file.
  24 For a description of the use of this type of file, see the
  25 .Qq Authentication Support
  26 section of the
  27 .Xr ntp.conf 5
  28 page.
  29 .Pp
  30 .Xr ntpd 8
  31 reads its keys from a file specified using the
  32 .Fl k
  33 command line option or the
  34 .Ic keys
  35 statement in the configuration file.
  36 While key number 0 is fixed by the NTP standard
  37 (as 56 zero bits)
  38 and may not be changed,
  39 one or more keys numbered between 1 and 65534
  40 may be arbitrarily set in the keys file.
  41 .Pp
  42 The key file uses the same comment conventions
  43 as the configuration file.
  44 Key entries use a fixed format of the form
  45 .Pp
  46 .D1 Ar keyno type key opt_IP_list
  47 .Pp
  48 where
  49 .Ar keyno
  50 is a positive integer (between 1 and 65534),
  51 .Ar type
  52 is the message digest algorithm,
  53 .Ar key
  54 is the key itself, and
  55 .Ar opt_IP_list
  56 is an optional comma-separated list of IPs
  57 where the
  58 .Ar keyno
  59 should be trusted.
  60 that are allowed to serve time.
  61 Each IP in
  62 .Ar opt_IP_list
  63 may contain an optional
  64 .Cm /subnetbits
  65 specification which identifies the number of bits for
  66 the desired subnet of trust.
  67 If
  68 .Ar opt_IP_list
  69 is empty,
  70 any properly-authenticated message will be
  71 accepted.
  72 .Pp
  73 The
  74 .Ar key
  75 may be given in a format
  76 controlled by the
  77 .Ar type
  78 field.
  79 The
  80 .Ar type
  81 .Li MD5
  82 is always supported.
  83 If
  84 .Li ntpd
  85 was built with the OpenSSL library
  86 then any digest library supported by that library may be specified.
  87 However, if compliance with FIPS 140-2 is required the
  88 .Ar type
  89 must be either
  90 .Li SHA
  91 or
  92 .Li SHA1 .
  93 .Pp
  94 What follows are some key types, and corresponding formats:
  95 .Pp
  96 .Bl -tag -width RMD160 -compact
  97 .It Li MD5
  98 The key is 1 to 16 printable characters terminated by
  99 an EOL,
 100 whitespace,
 101 or
 102 a
 103 .Li #
 104 (which is the "start of comment" character).
 105 .Pp
 106 .It Li SHA
 107 .It Li SHA1
 108 .It Li RMD160
 109 The key is a hex-encoded ASCII string of 40 characters,
 110 which is truncated as necessary.
 111 .El
 112 .Pp
 113 Note that the keys used by the
 114 .Xr ntpq 8
 115 and
 116 .Xr ntpdc 8
 117 programs are checked against passwords
 118 requested by the programs and entered by hand,
 119 so it is generally appropriate to specify these keys in ASCII format.
 120         _END_PROG_MDOC_DESCRIP;
 121 };
 122
 123 doc-section     = {
 124   ds-type       = 'FILES';
 125   ds-format     = 'mdoc';
 126   ds-text       = <<- _END_MDOC_FILES
 127 .Bl -tag -width /etc/ntp.keys -compact
 128 .It Pa /etc/ntp.keys
 129 the default name of the configuration file
 130 .El
 131         _END_MDOC_FILES;
 132 };
 133
 134 doc-section     = {
 135   ds-type       = 'SEE ALSO';
 136   ds-format     = 'mdoc';
 137   ds-text       = <<- _END_MDOC_SEE_ALSO
 138 .Xr ntp.conf 5 ,
 139 .Xr ntpd 1ntpdmdoc ,
 140 .Xr ntpdate 1ntpdatemdoc ,
 141 .Xr ntpdc 1ntpdcmdoc ,
 142 .Xr sntp 1sntpmdoc
 143         _END_MDOC_SEE_ALSO;
 144 };
 145
 146 /*
 147 doc-section     = {
 148   ds-type       = 'BUGS';
 149   ds-format     = 'mdoc';
 150   ds-text       = <<- _END_MDOC_BUGS
 151 .Xr ntpd 8
 152 has gotten rather fat.
 153 While not huge, it has gotten larger than might
 154 be desirable for an elevated-priority daemon running on a workstation,
 155 particularly since many of the fancy features which consume the space
 156 were designed more with a busy primary server, rather than a high
 157 stratum workstation, in mind.
 158         _END_MDOC_BUGS;
 159 };
 160 */
 161
 162 doc-section     = {
 163   ds-type       = 'NOTES';
 164   ds-format     = 'mdoc';
 165   ds-text       = <<- _END_MDOC_NOTES
 166 This document was derived from FreeBSD.
 167         _END_MDOC_NOTES;
 168 };