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
  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 and
  54 .Ar key
  55 is the key itself.
  56 .Pp
  57 The
  58 .Ar key
  59 may be given in a format
  60 controlled by the
  61 .Ar type
  62 field.
  63 The
  64 .Ar type
  65 .Li MD5
  66 is always supported.
  67 If
  68 .Li ntpd
  69 was built with the OpenSSL library
  70 then any digest library supported by that library may be specified.
  71 However, if compliance with FIPS 140-2 is required the
  72 .Ar type
  73 must be either
  74 .Li SHA
  75 or
  76 .Li SHA1 .
  77 .Pp
  78 What follows are some key types, and corresponding formats:
  79 .Pp
  80 .Bl -tag -width RMD160 -compact
  81 .It Li MD5
  82 The key is 1 to 16 printable characters terminated by
  83 an EOL,
  84 whitespace,
  85 or
  86 a
  87 .Li #
  88 (which is the "start of comment" character).
  89 .Pp
  90 .It Li SHA
  91 .It Li SHA1
  92 .It Li RMD160
  93 The key is a hex-encoded ASCII string of 40 characters,
  94 which is truncated as necessary.
  95 .El
  96 .Pp
  97 Note that the keys used by the
  98 .Xr ntpq 8
  99 and
 100 .Xr ntpdc 8
 101 programs are checked against passwords
 102 requested by the programs and entered by hand,
 103 so it is generally appropriate to specify these keys in ASCII format.
 104         _END_PROG_MDOC_DESCRIP;
 105 };
 106
 107 doc-section     = {
 108   ds-type       = 'FILES';
 109   ds-format     = 'mdoc';
 110   ds-text       = <<- _END_MDOC_FILES
 111 .Bl -tag -width /etc/ntp.keys -compact
 112 .It Pa /etc/ntp.keys
 113 the default name of the configuration file
 114 .El
 115         _END_MDOC_FILES;
 116 };
 117
 118 doc-section     = {
 119   ds-type       = 'SEE ALSO';
 120   ds-format     = 'mdoc';
 121   ds-text       = <<- _END_MDOC_SEE_ALSO
 122 .Xr ntp.conf 5 ,
 123 .Xr ntpd 1ntpdmdoc ,
 124 .Xr ntpdate 1ntpdatemdoc ,
 125 .Xr ntpdc 1ntpdcmdoc ,
 126 .Xr sntp 1sntpmdoc
 127         _END_MDOC_SEE_ALSO;
 128 };
 129
 130 /*
 131 doc-section     = {
 132   ds-type       = 'BUGS';
 133   ds-format     = 'mdoc';
 134   ds-text       = <<- _END_MDOC_BUGS
 135 .Xr ntpd 8
 136 has gotten rather fat.
 137 While not huge, it has gotten larger than might
 138 be desirable for an elevated-priority daemon running on a workstation,
 139 particularly since many of the fancy features which consume the space
 140 were designed more with a busy primary server, rather than a high
 141 stratum workstation, in mind.
 142         _END_MDOC_BUGS;
 143 };
 144 */
 145
 146 doc-section     = {
 147   ds-type       = 'NOTES';
 148   ds-format     = 'mdoc';
 149   ds-text       = <<- _END_MDOC_NOTES
 150 This document was derived from FreeBSD.
 151         _END_MDOC_NOTES;
 152 };