ntp-keygen(template) - phpMan

ntp-keygen(8)               System Manager's Manual              ntp-keygen(8)

NAME
       ntp-keygen - generate public and private keys

SYNOPSIS
       ntp-keygen  [ -deGHIMPT ] [ -b modulus ] [ -c [RSA-MD2 | RSA-MD5 | RSA-
       SHA | RSA-SHA1 | RSA-MDC2 | RSA-RIPEMD160 | DSA-SHA | DSA-SHA1 ] ] [ -C
       cipher ] [ -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
       -b modulus
               Set the modulus for generating identity keys to  modulus  bits.
               The  modulus  defaults  to  256,  but  can  be set from 256 (32
               octets) to 2048 (256 octets). Use the larger moduli  with  cau-
               tion,  as this can consume considerable computing resources and
               increases the size of authenticated packets.
       -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.
       -C cipher
               Select the cipher which is used to encrypt the files containing
               private  keys. The default is three-key triple DES in CBC mode,
               equivalent to "-C des-ede3-cbc". The openssl tool lists ciphers
               available in "openssl -h" output.
       -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.

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 cipher selected with -C and
       given password and finally written in PEM-encoded printable ASCII  text
       preceded 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)