man pages section 1M: System Administration Commands

Exit Print View

Updated: July 2014

ntp-keygen (1m)


ntp-keygen - Generate Public and Private Keys for NTP


/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  |


SunOS 5.11                                                      1

System Administration Commands                     ntp-keygen(1M)

     ntp-keygen - Generate Public and Private Keys for NTP

     /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  |

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

          Select certificate and message digest/signature encryp-
          tion  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 crypto-
          graphic data produced for eye-friendly billboards.

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

     -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 Guil-
          lou-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

SunOS 5.11                Last change:                          1

System Administration Commands                     ntp-keygen(1M)


     -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 iden-
          tity scheme. By default, the program  generates  public
          certificates.  Note: the PC identity scheme is not rec-
          ommended for new installations.

     -p passwd2, --pvt-passwd=passwd2
          Set  the  password  for  writing  encrypted  files   to
          passwd2.  By  default,  the  write password is the read

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

     -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 certificate. It must match the host name
          specified in the CRYPTO configuration command.

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

     -V nkeys, --mv-params=nkeys
          Generate server parameters MV and nkeys client keys for
          the Mu-Varadharajan (MV)  identity scheme.  Note:  sup-
          port  for  this  option  should be considered a work in

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


     -?, --help
          Print program help information.

SunOS 5.11                Last change:                          2

System Administration Commands                     ntp-keygen(1M)

     -!, --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.

     Most options may be preset by loading values from configura-
     tion 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 letters.  For example, to set the --com-
     mand option, you would set the  NTP_KEYGEN_COMMAND  environ-
     ment  variable.   The  users  home directory and the current
     directory are searched for a file named .ntprc.

     This program generates cryptographic data files used by  the
     NTPv4  authentication and identity schemes. It generates MD5
     keys  used  in  symmetric  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

     Generated  files  are compatible with other OpenSSL applica-
     tions and other Public Key Infrastructure  (PKI)  resources.
     Certificates  or  certificate  requests generated by this or
     other programs should be  compatible  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 any-
     thing other than Autokey.

     Most files written by this program  are  encrypted  using  a
     private  password. 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 speci-
     fied, the host name returned by the Unix gethostname() func-
     tion  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

SunOS 5.11                Last change:                          3

System Administration Commands                     ntp-keygen(1M)

     convenience, if the ntpd password is not specified, the host
     name returned by the Unix gethostname()  function  is  used.
     Thus,  if  files are generated by this program without pass-
     word, 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  filesys-
     tem in NFS-mounted networks. The location of the keys direc-
     tory 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 apli-
     cations or redirected to a file. The names used  for  gener-
     ated  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 command  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 certificate 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  configure it to synchronize via reliable
     paths. THs have trusted, self-signed certificates; all other
     hosts  have  nontrusted, self-signed certificates. Then con-
     figure  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 immedi-
     ately 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 certificate 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.

SunOS 5.11                Last change:                          4

System Administration Commands                     ntp-keygen(1M)

     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  mes-
     sage  digest  type  supported  by the OpenSSL library can be

  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 authentication 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  con-
     veniently  as a tar archive. This means that it doesn't mat-
     ter 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
     certificate.  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 identity 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

SunOS 5.11                Last change:                          5

System Administration Commands                     ntp-keygen(1M)

     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 attach-
     ment 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 the redirected parameters_file can be piped  to  a
     mail  application or stored locally and renamed as above for
     later distribution. The procedure for IFF files  is  similar
     with -G replaced by -I.

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

          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 generated 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 convention, key fields  in  gener-
     ated  file  names include both upper and lower case alphanu-
     meric characters, while key fields in generated  link  names
     include  only  lower  case  characters. The filestamp is not
     used in generated link names.

     The key type is a string defining  the  cryptographic  func-
     tion.  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.

SunOS 5.11                Last change:                          6

System Administration Commands                     ntp-keygen(1M)

     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 beginning 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 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 compatibil-
     ity. Since DES-CBC is deprecated in NTPv4, the only key for-
     mat  of  interest is MD5 alphanumeric 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 charac-
     ters or less in length. Each character is chosen from the 93
     printable characters in the range 0x21 through 0x7f  exclud-
     ing 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
     ntpkey_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. Subse-
     quently, 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.

     See  attributes(5)  for  descriptions   of   the   following

SunOS 5.11                Last change:                          7

System Administration Commands                     ntp-keygen(1M)

     |Availability   | service/network/ntp |
     |Stability      | Uncommitted         |
     The  documentation  available  at /usr/share/doc/ntp is pro-
     vided as is from the NTP distribution and may contain infor-
     mation that is not applicable to the software as provided in
     this partIcular distribution.

     ntpd(1M), ntprc(4), attributes(5)

     This  software  was   built   from   source   available   at    The  original
     community   source   was   downloaded    from     http://ar-

     Further  information about this software can be found on the
     open source community website at

SunOS 5.11                Last change:                          8