Go to main content

man pages section 8: System Administration Commands

Exit Print View

Updated: Thursday, June 13, 2019
 
 

ntp-keygen (8)

Name

ntp-keygen - Generate Public and Private Keys for NTP

Synopsis

/usr/sbin/ntp-keygen  [-deGgHIMPTv?!]  [-i issuername] [-q passwd1] [-p
passwd2] [-s subjectname] [-V nkeys] [-v mvkeys] [-c [RSA-MD2 | RSA-MD5
|  RSA-SHA | RSA=SHA1 | RSA-MDC2 | RSA-RIPEMD160 | DSA-SHA | DSA-SHA1]]
[-S [ RSA | DSA]]

Description

System Administration Commands                                   ntp-keygen(8)



NAME
       ntp-keygen - Generate Public and Private Keys for NTP

SYNOPSIS
       /usr/sbin/ntp-keygen  [-deGgHIMPTv?!]  [-i issuername] [-q passwd1] [-p
       passwd2] [-s subjectname] [-V nkeys] [-v mvkeys] [-c [RSA-MD2 | RSA-MD5
       |  RSA-SHA | RSA=SHA1 | RSA-MDC2 | RSA-RIPEMD160 | DSA-SHA | DSA-SHA1]]
       [-S [ RSA | DSA]]

OPTIONS
       -c [ RSA-MD2 | RSA-MD5 | RSA-SHA | RSA-SHA1 |
               RSA-MDC2 | RSA-RIPEMD160 | DSA-SHA | DSA-SHA1 ],  --certificate
              [...]

              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.

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

       -D debug-level, --debug-level=debug-level
              Enable debugging and set the debug level to debug-level.

       -e, --id-key
              Generate unencrypted IFF or GQ parameters file from existing key
              file IFFkey or GQkey  file, respectively. The file contents  are
              sent to the standard output.

       -G, --gq-params
              Generate  GQ  key  file  GQkey  and  link gqkey for the Guillou-
              Quisquater (GQ) identity scheme.

       -g, --gq-keys
              Update the GQ keys.

       -H, --host-key
              Generate a new public/private host keys RSAkey, and link host.

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

       -i issuername, --issuer-name=issuername
              Set  the  issuername  name  to issuername for generated identity
              files. This is useful only if the TA is not a group  member  and
              is generally considered not a good practice.

       -M, --md5key
              Generate a new MD5 key file.

       -m modulus, --modulus=modulus
              Set the modulus to modulus.

       -P, --pvt-cert
              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 passwd2, --pvt-passwd=passwd2
              Set the password for writing  encrypted  files  to  passwd2.  By
              default, the write password is the read password.

       -q passwd1, --get-pvt-passwd=passwd1
              Set  the  password  for  reading  encrypted files to passwd1. By
              default,  the read password is the host name.

       -S [ RSA | DSA ], --sign-key=[ RSA | DSA]
              Generate a new sign key of the designated type. By default,  the
              sign key is the host key.

       -s name, --subject-name=name
              Set the host name to name. This is used in the host and sign key
              file names, as well as the subject and issuer names in the  cer-
              tificate.  It  must  match the host name specified in the CRYPTO
              configuration command.

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

       -V nkeys, --mv-params=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.

       -v, --version
              Output version of program and exit.

       --mv-keys=mvkeys

       -?, --help
              Print program help information.

       -!, --more-help
              Extended usages information passed through a pager.

       -> rcfile, --save-opts=rcfile
              Save the option state to rcfile.

       -< rcfile, --load-opts=rcfile, --no-load-opts
              Load  options  from  rcfile.  The no-load-opts form will disable
              the loading of earlier RC/INI files.  --no-load-opts is  handled
              early, out of order.

   OPTION PRESETS
       Most options may be preset by loading values from configuration file(s)
       and values from environment variables named:
         NTP_KEYGEN_<option-name> or NTP_KEYGEN
       The environmental presets take precedence (are  processed  later  than)
       the  configuration files. The option-name should be in all capital let-
       ters.  For example, to set the --command  option,  you  would  set  the
       NTP_KEYGEN_COMMAND  environment variable.  The users home directory and
       the current directory are searched for a file named .ntprc.

DESCRIPTION
       This program generates cryptographic  data  files  used  by  the  NTPv4
       authentication and identity schemes. It generates MD5 keys used in sym-
       metric key cryptography and generates encryption keys, certificates and
       identity  keys  used  in the Autokey public key cryptography. All files
       are in PEM-encoded printable ASCII format so they can  be  embedded  as
       MIME attachments in mail to other sites and certificate authorities.

       Generated  files  are  compatible  with  other OpenSSL applications and
       other Public Key Infrastructure (PKI) resources. Certificates  or  cer-
       tificate requests generated by this or other programs should be compat-
       ible with extant industry practice, although some users might find  the
       interpretation  of  X509v3  extension fields somewhat liberal. However,
       the identity keys files are probably not compatible with anything other
       than Autokey.

       Most  files written by this program are encrypted using a private pass-
       word. The -p passwd2 option specifies the write  password  and  the  -q
       passwd2  option the read password for previously encrypted files. If no
       read password is specified, the host name returned by the Unix gethost-
       name()  function  is  used. If no write password is specified, the read
       password is used as the write password.

       The ntpd configuration command crypto  pw  passwd  specifies  the  read
       password  for  previously  encrypted  files.  This must match the write
       password used by this program. For convenience, if the ntpd password is
       not  specified,  the host name returned by the Unix gethostname() func-
       tion 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 installed by  default  in  the  keys  directory
       /etc/inet, which is normally in a shared filesystem in NFS-mounted net-
       works. The location of the keys directory can be changed by the keysdir
       configuration  command.  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 some files to the standard output stream stdout
       where  they  can be piped to other aplications 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
       The safest way to run this program is log in as root and change to  the
       keys directory, /etc/inet. When run for the first time, or if all files
       with names beginning ntpkey have been removed, use the ntp-keygen  com-
       mand  without  arguments  to  generate  a default RSA host key file and
       matching RSA-MD5 certificate file. The file names and password  default
       to the host name as described above. If run again with the same command
       line, the program uses the same host key file, but generates a new cer-
       tificate file.

       Run the command on as many hosts as necessary. Designate one of them as
       the trusted host (TH) using the -T option on the command line and  con-
       figure  it  to  synchronize via reliable paths. THs have trusted, self-
       signed certificates; all other hosts have nontrusted, self-signed  cer-
       tificates. Then configure the nontrusted hosts to synchronize to the TH
       directly or indirectly. A certificate trail is created  by  asking  the
       immediately  ascendant  host  towards the root 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.

       By default the name used in the subject and issuer fields in  the  cer-
       tificate  is  the host name. A different name can be assigned using the
       -s host option on the command line, but the name must  match  the  host
       name specified by the crypto configuration command.

       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 file name can be assigned using the -S
       option and this can be either RSA or DSA type. By default, the  message
       digest  type  is  MD5, but any combination of sign key type and message
       digest type supported by the OpenSSL library can be specified.

   Trusted Hosts and Secure Groups
       As   described   on    the    "Authentication    Options"    page    at
       file:///usr/share/doc/ntp/authopt.html, 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 THs in a group must have the same host and group name; all
       other  hosts  have  the  same group name, but different host names. The
       host name and group name must match the names specified by  the  crypto
       configuratrion  command. Host and group names are used only for authen-
       tication purposes and have nothing to do with DNS names.

       It is convenient to nominate a single TH acting as a trusted  authority
       (TA)  to  generate a set of files and links that are then copied intact
       to all other THs in the group, most conveniently as a tar archive. This
       means  that it doesn't matter which certificate trail ends at which TH,
       since the cryptographic media are the same.

       To generate and install cryptographic media files, The TA uses the

              ntp-keygen -q passwd1 -s host -T

       command to specify the password, host/group name and  trusted  certifi-
       cate.  For THs the host and group names are the same and must match the
       host and group names specified on the crypto configuration command.  If
       run  again  with  the same command line, the program uses the same host
       key file, but generates a new trusted  certificate  file.  Group  hosts
       other than the THs use the same command line, but with a different host
       name and without the -T option. On these hosts if the -s host option is
       missing, the host name is the default described above.

   Identity Schemes
       As described on the "Authentication Options" page, there are five iden-
       tity schemes, three of which - IFF, GQ and MV - require files  specific
       to  each  scheme  and  group.  There  are two files for each scheme, an
       encrypted keys file and a nonencrypted parameters file. THs  need  only
       the  keys  file;  all  the others need the parameters file. Other hosts
       expecting to support a client population also need the keys file; hosts
       acting  only  as  clients need only the parameters file. Both files are
       generated by the TA 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 host read
       password. To retrieve the keys file, a host sends a mail request to the
       TA  including  its private read 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..

       The  TA  can  generate  GQ keys, certificate and identity files for all
       TH's using the command

              ntp-keygen -q passwd1 -s host -T -G -e >parameters_file

       where the redirected parameters_file can be piped to a mail application
       or stored locally and renamed as above for later distribution. The pro-
       cedure for IFF files is similar with -G replaced by -I.

       The TA can generate an encrypted GQ keys file copy using the command

              ntp-keygen -q passwd1 -p passwd2 -s host >keys_file

       where passwd1 is the read password for the  TA,  passwd2  is  the  read
       password  for  the  requesting  host and keys_file is sent or stored as
       above. The program uses the keys and parameters of whatever scheme gen-
       erated the keys file.

   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 program are checked against pass-
       words requested by the program 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 utility.


ATTRIBUTES
       See attributes(7) for descriptions of the following attributes:


       +---------------+---------------------+
       |ATTRIBUTE TYPE |  ATTRIBUTE VALUE    |
       +---------------+---------------------+
       |Availability   | service/network/ntp |
       +---------------+---------------------+
       |Stability      | Uncommitted         |
       +---------------+---------------------+
NOTES
       The  documentation  available  at  /usr/share/doc/ntp is provided as is
       from the NTP distribution and  may  contain  information  that  is  not
       applicable to the software as provided in this partIcular distribution.

SEE ALSO
       ntpd(8), ntprc(5), attributes(7)


       This     software     was    built    from    source    available    at
       https://github.com/oracle/solaris-userland.   The  original   community
       source          was         downloaded         from          http://ar-
       chive.ntp.org/ntp4/ntp-4.2/ntp-4.2.8p13.tar.gz

       Further information about this software can be found on the open source
       community website at http://www.ntp.org/.



                                                                 ntp-keygen(8)