contrib/keygone-body.adoc

   1 // This is the body of the manual page for keygone.
   2 // It's included in two places: once for the docs/ HTML
   3 // tree, and once to make an individual man page.
   4
   5 == Synopsis
   6 [verse]
   7 +keygone+ [+-hlctvx+] [+-ad+ 'ALGO' ...] [+-f+ 'FILE'] [+-s+ 'LINK'] \
   8           [+-n+ 'NUMBER'] [+-i+ 'INITIAL'] [+-g+ 'GAP']
   9
  10 == Description
  11
  12 This program generates keys that can be used in NTP's symmetric
  13 key cryptography.
  14
  15 The program produces a file containing groups of pseudo-random
  16 printable ASCII strings suitable for NTPsec symmetric authentication.
  17 The groups are 'NUMBER' entries long, their numbers seperated by
  18 'GAP' starting at 'INITIAL'. The keys may either be in hexadecimal
  19 (lowercase base 16) or printable ASCII (base 95ish).
  20
  21 The keys file must be distributed and stored using secure means
  22 beyond the scope of NTP itself. The keys can also be used as
  23 passwords for the link:ntpq.html[+ntpq+] utility program.
  24
  25 [[cmd]]
  26 == Command Line Options
  27
  28 +-h+, +--help+::
  29   show this help message and exit
  30
  31 +-L+, +--list+::
  32   List known algorithms
  33
  34 +-d+ DELETE [DELETE ...], +--delete+ DELETE [DELETE ...]::
  35   delete algorithm (repeatable) or "everything"
  36
  37 +-a+ ADD [ADD ...], +--add+ ADD [ADD ...]::
  38   delete algorithm (repeatable) or "everything"
  39
  40 +-f+ FILE, +--file+ FILE::
  41   Output to a file defaults to "ntp.keygone"
  42
  43 +-s+ LINK, +--link+ LINK::
  44   create a symlink (requires file)
  45
  46 +-c+, +--console+::
  47   also print keys to the console
  48
  49 +-n+ NUMBER, +--number+ NUMBER::
  50   number of keys per group (default 10)
  51
  52 +-i+ INITIAL, +--initial+ INITIAL::
  53   number of initial key (default 1)
  54
  55 +-g+ GAP, +--gap+ GAP::
  56   gap between subsequent groups (default 0)
  57
  58 +-t+, +--text+::
  59   generate text keys (base-92 default)
  60
  61 +-x+, +--hex+::
  62   generate hexadecimal keys (lowercase base-16)
  63
  64
  65 +-V+, +--version+::
  66   Print the version string and exit. (unimplemented)
  67
  68 [[run]]
  69 == Running the program
  70
  71 The simplest way to run the +keygone+ program is logged in directly as
  72 root. The recommended procedure is to change to the keys directory,
  73 usually +/var/lib/ntp/+, then run the program.  Then chown the output
  74 file to ntp:ntp. (typically 123:123) It should be mode 400.
  75
  76 [[access]]
  77 == Key file access and location
  78
  79 File names are suggested to begin with the prefix _ntpkey_ and end
  80 with the postfix _hostname.filestamp_, where _hostname_ is the owner
  81 name, usually the string returned by the Unix gethostname() routine,
  82 and _filestamp_ is the NTP seconds when the file was generated, in
  83 decimal digits.
  84
  85 +keygone+ can also makes a soft link from +ntp.keys+ to the generated
  86 file.  +ntp.keys+ is the normal file used in +{ntpconf}+.
  87
  88 [[random]]
  89 == Random Seed File
  90
  91 All key generation schemes must have means to randomize the
  92 entropy seed used to initialize the internal pseudo-random
  93 number generator used by the library routines.
  94
  95 It is important to understand that entropy must be evolved for each
  96 generation, for otherwise the random number sequence would be
  97 predictable. Various means dependent on external events, such as
  98 keystroke intervals can be used to do this and some systems have
  99 built-in entropy sources.
 100
 101 This implementation uses Python's secrets module..
 102
 103 [[crypto]]
 104 == Cryptographic Data Files
 105
 106 Unlike NTP Classic, this implementation can generate many key types.
 107
 108 Since the file contains private shared keys, it should be visible
 109 only to root or ntp.
 110
 111 In order to use a shared key, the line to be used must also be setup
 112 on the target server.
 113
 114 This file is also used to authenticate remote configuration
 115 commands used by the {ntpqman} utility.
 116
 117 Comments may appear in the file and are preceded with the +#+
 118 character.
 119
 120 Following any headers the keys are entered one per line in the
 121 format:
 122
 123 [options="header"]
 124 |====
 125 |Field  | Meaning
 126 |keyno  | Positive integer in the range 1-65,535
 127 |type   | Type of key (md5, sha224, aes-128 etc).
 128 |key    | the actual key, printable ASCII or hex
 129 |====
 130
 131 // end