// This is the body of the manual page for keygone.
// It's included in two places: once for the docs/ HTML
// tree, and once to make an individual man page.

== Synopsis
[verse]
+keygone+ [+-hlctvx+] [+-ad+ 'ALGO' ...] [+-f+ 'FILE'] [+-s+ 'LINK'] \
          [+-n+ 'NUMBER'] [+-i+ 'INITIAL'] [+-g+ 'GAP'] 

== Description

This program generates keys that can be used in NTP's symmetric
key cryptography.

The program produces a file containing groups of pseudo-random
printable ASCII strings suitable for NTPsec symmetric authentication.
The groups are 'NUMBER' entries long, their numbers seperated by
'GAP' starting at 'INITIAL'. The keys may either be in hexadecimal
(lowercase base 16) or printable ASCII (base 95ish).

The keys file must be distributed and stored using secure means
beyond the scope of NTP itself. The keys can also be used as
passwords for the link:ntpq.html[+ntpq+] utility program.

[[cmd]]
== Command Line Options

+-h+, +--help+::
  show this help message and exit

+-L+, +--list+::
  List known algorithms

+-d+ DELETE [DELETE ...], +--delete+ DELETE [DELETE ...]::
  delete algorithm (repeatable) or "everything"

+-a+ ADD [ADD ...], +--add+ ADD [ADD ...]::
  delete algorithm (repeatable) or "everything"

+-f+ FILE, +--file+ FILE::
  Output to a file defaults to "ntp.keygone"

+-s+ LINK, +--link+ LINK::
  create a symlink (requires file)

+-c+, +--console+::
  also print keys to the console

+-n+ NUMBER, +--number+ NUMBER::
  number of keys per group (default 10)

+-i+ INITIAL, +--initial+ INITIAL::
  number of initial key (default 1)

+-g+ GAP, +--gap+ GAP::
  gap between subsequent groups (default 0)

+-t+, +--text+::
  generate text keys (base-92 default)

+-x+, +--hex+::
  generate hexadecimal keys (lowercase base-16)


+-V+, +--version+::
  Print the version string and exit. (unimplemented)

[[run]]
== Running the program

The simplest way to run the +keygone+ program is logged in directly as
root. The recommended procedure is to change to the keys directory,
usually +/var/lib/ntp/+, then run the program.  Then chown the output
file to ntp:ntp. (typically 123:123) It should be mode 400.

[[access]]
== Key file access and location

File names are suggested to begin with the prefix _ntpkey_ and end
with the postfix _hostname.filestamp_, where _hostname_ is the owner
name, usually the string returned by the Unix gethostname() routine,
and _filestamp_ is the NTP seconds when the file was generated, in
decimal digits.

+keygone+ can also makes a soft link from +ntp.keys+ to the generated
file.  +ntp.keys+ is the normal file used in +{ntpconf}+.

[[random]]
== Random Seed File

All key generation schemes must have means to randomize the
entropy seed used to initialize the internal pseudo-random
number generator used by the library routines.

It is important to understand that entropy must be evolved for each
generation, for otherwise the random number sequence would be
predictable. Various means dependent on external events, such as
keystroke intervals can be used to do this and some systems have
built-in entropy sources.

This implementation uses Python's secrets module..

[[crypto]]
== Cryptographic Data Files

Unlike NTP Classic, this implementation can generate many key types.

Since the file contains private shared keys, it should be visible
only to root or ntp.

In order to use a shared key, the line to be used must also be setup
on the target server.

This file is also used to authenticate remote configuration
commands used by the {ntpqman} utility.

Comments may appear in the file and are preceded with the +#+
character.

Following any headers the keys are entered one per line in the
format:

[options="header"]
|====
|Field	| Meaning
|keyno	| Positive integer in the range 1-65,535
|type	| Type of key (md5, sha224, aes-128 etc).
|key	| the actual key, printable ASCII or hex
|====

// end
