ntp-keygen man page on Archlinux

Man page or keyword search:  
man Server   11224 pages
apropos Keyword Search (all sections)
Output format
Archlinux logo
[printable version]

ntp-keygen(8)							 ntp-keygen(8)

NAME
       ntp-keygen - generate public and private keys

SYNOPSIS
       ntp-keygen [ -deGHIMPT ] [ -c [RSA-MD2 | RSA-MD5 | RSA-SHA | RSA-SHA1 |
       RSA-MDC2 | RSA-RIPEMD160 | DSA-SHA | DSA-SHA1 ] ] [ -i  group  ]	 [  -m
       modulus	] [ -p passwd2 ] [ -q passwd1 ] [ -S [ RSA | DSA ] ] [ -s host
       ] [ -V nkeys ]

DESCRIPTION
       This program generates cryptographic  data  files  used	by  the	 NTPv4
       authentication  and  identity  schemes.	It can generate message digest
       keys used in symmetric key cryptography and, if	the  OpenSSL  software
       library	has been installed, it can generate host keys, sign keys, cer‐
       tificates and identity keys used by the Autokey public  key  cryptogra‐
       phy.  The  message digest keys file is generated in a format compatible
       with NTPv3. All other files are in PEM-encoded printable	 ASCII	format
       so they can be embedded as MIME attachments in mail to other sites.

       When  used to generate message digest keys, the program produces a file
       containing ten pseudo-random printable ASCII strings suitable  for  the
       MD5  message  digest  algorithm	included  in  the distribution. If the
       OpenSSL library is installed, it produces an additional ten hex-encoded
       random bit strings suitable for the SHA1 and other message digest algo‐
       rithms. Printable ASCII keys can have length from one to 20 characters,
       inclusive.  Bit	string keys have length 20 octets (40 hex characters).
       All keys are 160 bits in length.

	The file can be edited later with  purpose-chosen  passwords  for  the
       ntpq  and  ntpdc programs. Each line of the file contains three fields,
       first an integer between 1 and 65534, inclusive, representing  the  key
       identifier  used in the server and peer configuration commands. Next is
       the key type for the message digest algorithm, which in the absence  of
       the  OpenSSL library should be the string MD5 to designate the MD5 mes‐
       sage digest algorithm. If the OpenSSL library  is  installed,  the  key
       type  can  be  any  message digest algorithm supported by that library.
       However, if compatibility with FIPS 140-2 is  required,	the  key  type
       must  be	 either	 SHA  or SHA1.Finally is the key itself as a printable
       ASCII string excluding the space and # characters. If not greater  than
       20 characters in length, the string is the key itself; otherwise, it is
       interpreted as a hex-encoded bit	 string.  As  is  custom,  #  and  the
       remaining  characters  on the line are ignored. Later, this file can be
       edited to include the passwords for the ntpq and	 ntpdc	utilities.  If
       this  is the only need, run ntp-keygen with the -M option and disregard
       the remainder of this page.

       The remaining generated files are compatible with other OpenSSL	appli‐
       cations	and  other Public Key Infrastructure (PKI) resources. Certifi‐
       cates generated by this program should be compatible with extant indus‐
       try  practice,  although	 some  users  might find the interpretation of
       X509v3 extension fields somewhat liberal. However,  the	identity  keys
       are probably not compatible with anything other than Autokey.

       Most files used by this program are encrypted using a private password.
       The -p option specifies the password for local files and the -q	option
       the  password  for  files sent to remote sites. If no local password is
       specified, the host name returned by the Unix  gethostname()  function,
       normally	 the  DNS  name of the host, is used. If no remote password is
       specified, the local password is used.

       The pw option of the crypto configuration command  specifies  the  read
       password	 for  previously  encrypted  files.  This must match the local
       password used by this program. If not specified, the host name is used.
       Thus, if files are generated by this program without password, they can
       be read back by ntpd without password, but only on the same host.

       All  files  and	links  are  usually   installed	  in   the   directory
       /usr/local/etc, which is normally in a shared filesystem in NFS-mounted
       networks and cannot be changed by shared clients. The location  of  the
       keys  directory	can be changed by the keysdir configuration command in
       such cases. Normally, encrypted files for each host  are	 generated  by
       that  host  and	used  only  by that host, although exceptions exist as
       noted later on this page.

       This program directs commentary and  error  messages  to	 the  standard
       error stream stderr and remote files to the standard output stream std‐
       out where they can be piped to other applications or  redirected	 to  a
       file.  The  names used for generated files and links all begin with the
       string ntpkey and include the file type, generating host and filestamp,
       as described in the Cryptographic Data Files section below

RUNNING THE PROGRAM
       To  test	 and gain experience with Autokey concepts, log in as root and
       change to the keys directory, usually /usr/local/etc. When run for  the
       first  time,  or	 if  all  files	 with names beginning ntpkey have been
       removed, use the ntp-keygen command without  arguments  to  generate  a
       default	RSA  host key and matching RSA-MD5 certificate with expiration
       date one year hence. If run again, the program uses the	existing  keys
       and parameters and generates only a new certificate with new expiration
       date one year hence; however, the certificate is not generated  if  the
       -e or -q options are present.

       Run the command on as many hosts as necessary. Designate one of them as
       the trusted host (TH) using ntp-keygen with the -T option and configure
       it  to  synchronize  from reliable Internet servers. Then configure the
       other hosts to synchronize to the TH directly or indirectly. A certifi‐
       cate  trail is created when Autokey asks the immediately ascendant host
       towards the TH to sign its certificate, which is then provided  to  the
       immediately  descendant	host  on  request. All group hosts should have
       acyclic certificate trails ending on the TH.

       The host key is used to encrypt the cookie when required and so must be
       RSA type. By default, the host key is also the sign key used to encrypt
       signatures. A different sign key can be assigned using  the  -S	option
       and  this can be either RSA or DSA type. By default, the signature mes‐
       sage digest type is MD5, but any combination of sign key type and  sign
       digest type supported by the OpenSSL library can be specified using the
       -c option. At the moment, legacy considerations require the NTP	packet
       header digest type to be MD5.

TRUSTED HOSTS AND SECURE GROUPS
       As  described  on  the Authentication Options page, an NTP secure group
       consists of one or more low-stratum THs as  the	root  from  which  all
       other  group  hosts  derive synchronization directly or indirectly. For
       authentication purposes all hosts in a group must have the  same	 group
       name  specified	by  the -i option and matching the ident option of the
       crypto configuration command. The group name is used in the subject and
       issuer  fields of trusted, self-signed certificates and when construct‐
       ing the file names for identity keys. All  hosts	 must  have  different
       host  names,  either  the  default  host name or as specified by the -s
       option and matching the host option of the  crypto  configuration  com‐
       mand.  Most  installations  need not specify the -i option nor the host
       option. Host names are used in the subject and issuer fields  of	 self-
       signed,	nontrusted  certificates  and when constructing the file names
       for host and sign keys and certificates. Host and group names are  used
       only for authentication purposes and have nothing to do with DNS names.

IDENTITY SCHEMES
       As  described  on the Authentication Options page, there are five iden‐
       tity schemes, three of which - IFF, GQ and MV - require	identity  keys
       specific	 to each scheme. There are two types of files for each scheme,
       an encrypted keys file and a nonencrypted parameters file,  which  usu‐
       ally  contains  a  subset  of  the keys file. In general, NTP secondary
       servers operating as certificate signing authorities (CSA) use the keys
       file  and  clients use the parameters file. Both files are generated by
       the TA operating as a certificate  authority  (CA)  on  behalf  of  all
       servers and clients in the group.

       The  parameters	files are public; they can be stored in a public place
       and sent in the clear. The keys files  are  encrypted  with  the	 local
       password.  To retrieve the keys file, a host can send a mail request to
       the TA including its local password. The TA encrypts the keys file with
       this  password  and returns it as an attachment. The attachment is then
       copied intact to the keys directory with name given in the  first  line
       of  the	file,  but  all	 in lower case and with the filestamp deleted.
       Alternatively, the parameters file can be retrieved from a  secure  web
       site.

       For  example,  the  TA generates default host key, IFF keys and trusted
       certificate using the command

       ntp-keygen -p local_passwd -T -I -igroup_name

       Each group host generates default host keys and nontrusted  certificate
       use  the same command line but omitting the -i option. Once these media
       have been generated, the TA can then  generate  the  public  parameters
       using the command

       ntp-keygen -p local_passwd -e >parameters_file

       where  the  -e option redirects the unencrypted parameters to the stan‐
       dard output stream for a mail application or stored locally  for	 later
       distribution.  In  a  similar  fashion  the  -q	option	redirects  the
       encrypted server keys to the standard output stream.

COMMAND LINE OPTIONS
       -c [ RSA-MD2 | RSA-MD5 | RSA-SHA | RSA-SHA1 | RSA-MDC2 |	 RSA-RIPEMD160
       | DSA-SHA | DSA-SHA1 ]
	       Select  certificate  and	 message  digest/signature  encryption
	       scheme. Note that RSA schemes must be used with a RSA sign  key
	       and  DSA	 schemes must be used with a DSA sign key. The default
	       without this option is  RSA-MD5.	 If  compatibility  with  FIPS
	       140-2  is  required, either the DSA-SHA or DSA-SHA1 scheme must
	       be used.

       -d      Enable debugging. This option displays the  cryptographic  data
	       produced for eye-friendly billboards.

       -e      Extract	the  IFF  or  GQ  public parameters from the IFFkey or
	       GQkey keys file previously specified. Send the unencrypted data
	       to  the standard output stream stdout. While the IFF parameters
	       do not reveal the private group key,  the GQ parameters	should
	       be used with caution, as they include the group key. Use the -q
	       option with password instead. Note: a new  certificate  is  not
	       generated  when	this  option  is present. This allows multiple
	       commands with  this  option  but	 without  disturbing  existing
	       media.

       -G      Generate	 a new encrypted GQ key file and link for the Guillou-
	       Quisquater (GQ) identity scheme.

       -H      Generate a new encrypted RSA public/private host key  file  and
	       link.  Note  that  if the sign key is the same as the host key,
	       generating a new host key invalidates all  certificates	signed
	       with the old host key.

       -i group
	       Set  the group name to group. This is used in the identity file
	       names. It must match the group  name  specified	in  the	 ident
	       option of the crypto configuration command.

       -I      Generate	 a new encrypted IFF key file and link for the Schnorr
	       (IFF) identity scheme.

       -m modulus
	       Set the modulus for generating files to modulus bits. The modu‐
	       lus  defaults  to  512,	but can be set from 256 (32 octets) to
	       2048 (256 octets).

       -M      Generate a new MD5 key file containing 16, 128-bit  pseudo-ran‐
	       dom keys for symmetric cryptography..

       -P      Generate	 a  new	 private  certificate  used by the PC identity
	       scheme. By default, the program generates public	 certificates.
	       Note: the PC identity scheme is not recommended for new instal‐
	       lations.

       -p passwd
	       Set the password for reading and	 writing  encrypted  files  to
	       passwd. By default, the password is the host name.

       -q passwd
	       Extract	the encrypted IFF or GQ server keys from the IFFkey or
	       GQkey key file previously generated. The data are sent  to  the
	       standard output stream stdout. Set the password for writing the
	       data, which is also the password	 to  read  the	data  file  in
	       another	host. By default, the password is the host name. Note:
	       a new certificate is not generated when this option is present.
	       This allows multiple commands with this option but without dis‐
	       turbing existing media.

       -S [ RSA | DSA ]
	       Generate a new sign key of the specified type. By default,  the
	       sign  key  is the host key and has the same type. If compatibly
	       with FIPS 140-2 is required, the sign key  type	must  be  DSA.
	       Note  that  generating  a new sign key invalidates all certifi‐
	       cates signed with the old sign key.

       -s host Set the host name to host. This is used in the  host  and  sign
	       key  file  names.  It must match the host name specified in the
	       host option of the crypto configuration command.

       -T      Generate a trusted certificate. By default, the program	gener‐
	       ates nontrusted certificates.

       -V nkeys
	       Generate server parameters MV and nkeys client keys for the Mu-
	       Varadharajan (MV)  identity  scheme.  Note:  support  for  this
	       option should be considered a work in progress.

RANDOM SEED FILE
       All  cryptographically  sound key generation schemes must have means to
       randomize the entropy seed used to initialize the internal  pseudo-ran‐
       dom  number  generator  used by the OpenSSL library routines. If a site
       supports ssh, it is very likely that  means  to	do  this  are  already
       available. The entropy seed used by the OpenSSL library is contained in
       a file, usually called .rnd, which must be available when starting  the
       ntp-keygen program or ntpd daemon.

       The  OpenSSL library looks for the file using the path specified by the
       RANDFILE environment variable in the user home directory, whether  root
       or  some	 other	user.  If  the	RANDFILE  environment  variable is not
       present, the library looks for the .rnd file in the  user  home	direc‐
       tory.  Since  both  the	ntp-keygen program and ntpd daemon must run as
       root, the logical place to put this file is in /.rnd or /root/.rnd.  If
       the  file is not available or cannot be written, the program exits with
       a message to the system log.

       On systems that provide /dev/urandom, the  randomness  device  is  used
       instead	and the file specified by the randfile subcommand or the RAND‐
       FILE environment variable is ignored.

CRYPTOGRAPHIC DATA FILES
       File and link names are in the form ntpkey_key_name.fstamp,  where  key
       is the key or parameter type, name is the host or group name and fstamp
       is the filestamp (NTP seconds) when the file was created).  By  conven‐
       tion,  key  fields in generated file names include both upper and lower
       case alphanumeric characters, while key fields in generated link	 names
       include only lower case characters. The filestamp is not used in gener‐
       ated link names.

       The key type is a string defining the cryptographic function. Key types
       include public/private keys host and sign, certificate cert and several
       challenge/response key types. By convention, files used for  challenges
       have  a	par  subtype,  as in the IFF challenge IFFpar, while files for
       responses have a key subtype, as in the GQ response GQkey.

       All files begin with two nonencrypted lines. The	 first	line  contains
       the  file  name	in  the format ntpkey_key_host.fstamp. The second line
       contains the datestamp in conventional Unix date format.	 Lines	begin‐
       ning with # are ignored.

       The  remainder  of  the	file contains cryptographic data encoded first
       using ASN.1 rules, then encrypted using the DES-CBC algorithm and given
       password	 and  finally written in PEM-encoded printable ASCII text pre‐
       ceded and followed by MIME content identifier lines.

       The format of the symmetric keys file is somewhat  different  than  the
       other files in the interest of backward compatibility. Since DES-CBC is
       deprecated in NTPv4, the only key format of interest  is	 MD5  alphanu‐
       meric  strings.	Following the header the keys are entered one per line
       in the format

       keyno type key

       where keyno is a positive integer in the range 1-65,535,	 type  is  the
       string  MD5 defining the key format and key is the key itself, which is
       a printable ASCII string 16 characters or less in length. Each  charac‐
       ter  is	chosen	from  the  93  printable  characters in the range 0x21
       through 0x7f excluding space and the '#' character.

       Note that the keys used by the ntpq  and	 ntpdc	programs  are  checked
       against	passwords requested by the programs and entered by hand, so it
       is generally appropriate to specify these keys in human readable	 ASCII
       format.

       The  ntp-keygen	program	 generates  a  MD5  symmetric  keys  file ntp‐
       key_MD5key_hostname.filestamp. Since the file contains  private	shared
       keys, it should be visible only to root and distributed by secure means
       to other subnet hosts. The NTP daemon loads the file ntp.keys, so  ntp-
       keygen  installs a soft link from this name to the generated file. Sub‐
       sequently, similar soft links must be installed by manual or  automated
       means  on  the other subnet hosts. While this file is not used with the
       Autokey Version 2 protocol, it is needed to  authenticate  some	remote
       configuration commands used by the ntpq and ntpdc utilities.

BUGS
       It  can	take quite a while to generate some cryptographic values, from
       one to several minutes with modern architectures such as UltraSPARC and
       up to tens of minutes to an hour with older architectures such as SPARC
       IPC.

SEE ALSO
       ntpd(8), ntp_auth(5)

       The official HTML documentation.

       This file was automatically generated from HTML source.

								 ntp-keygen(8)
[top]

List of man pages available for Archlinux

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Tweet
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
....................................................................
Vote for polarhome
Free Shell Accounts :: the biggest list on the net