crypto/openssh/ssh-keygen.0

   1 SSH-KEYGEN(1)              OpenBSD Reference Manual              SSH-KEYGEN(1)
   2
   3 NAME
   4      ssh-keygen - authentication key generation, management and conversion
   5
   6 SYNOPSIS
   7      ssh-keygen [-q] [-b bits] -t type [-N new_passphrase] [-C comment]
   8                 [-f output_keyfile]
   9      ssh-keygen -p [-P old_passphrase] [-N new_passphrase] [-f keyfile]
  10      ssh-keygen -i [-m key_format] [-f input_keyfile]
  11      ssh-keygen -e [-m key_format] [-f input_keyfile]
  12      ssh-keygen -y [-f input_keyfile]
  13      ssh-keygen -c [-P passphrase] [-C comment] [-f keyfile]
  14      ssh-keygen -l [-f input_keyfile]
  15      ssh-keygen -B [-f input_keyfile]
  16      ssh-keygen -D pkcs11
  17      ssh-keygen -F hostname [-f known_hosts_file] [-l]
  18      ssh-keygen -H [-f known_hosts_file]
  19      ssh-keygen -R hostname [-f known_hosts_file]
  20      ssh-keygen -r hostname [-f input_keyfile] [-g]
  21      ssh-keygen -G output_file [-v] [-b bits] [-M memory] [-S start_point]
  22      ssh-keygen -T output_file -f input_file [-v] [-a num_trials]
  23                 [-J num_lines] [-j start_line] [-K checkpt] [-W generator]
  24      ssh-keygen -s ca_key -I certificate_identity [-h] [-n principals]
  25                 [-O option] [-V validity_interval] [-z serial_number] file ...
  26      ssh-keygen -L [-f input_keyfile]
  27      ssh-keygen -A
  28      ssh-keygen -k -f krl_file [-u] [-s ca_public] [-z version_number]
  29                 file ...
  30      ssh-keygen -Q -f krl_file file ...
  31
  32 DESCRIPTION
  33      ssh-keygen generates, manages and converts authentication keys for
  34      ssh(1).  ssh-keygen can create RSA keys for use by SSH protocol version 1
  35      and DSA, ECDSA or RSA keys for use by SSH protocol version 2.  The type
  36      of key to be generated is specified with the -t option.  If invoked
  37      without any arguments, ssh-keygen will generate an RSA key for use in SSH
  38      protocol 2 connections.
  39
  40      ssh-keygen is also used to generate groups for use in Diffie-Hellman
  41      group exchange (DH-GEX).  See the MODULI GENERATION section for details.
  42
  43      Finally, ssh-keygen can be used to generate and update Key Revocation
  44      Lists, and to test whether given keys have been revoked by one.  See the
  45      KEY REVOCATION LISTS section for details.
  46
  47      Normally each user wishing to use SSH with public key authentication runs
  48      this once to create the authentication key in ~/.ssh/identity,
  49      ~/.ssh/id_ecdsa, ~/.ssh/id_dsa or ~/.ssh/id_rsa.  Additionally, the
  50      system administrator may use this to generate host keys, as seen in
  51      /etc/rc.
  52
  53      Normally this program generates the key and asks for a file in which to
  54      store the private key.  The public key is stored in a file with the same
  55      name but ``.pub'' appended.  The program also asks for a passphrase.  The
  56      passphrase may be empty to indicate no passphrase (host keys must have an
  57      empty passphrase), or it may be a string of arbitrary length.  A
  58      passphrase is similar to a password, except it can be a phrase with a
  59      series of words, punctuation, numbers, whitespace, or any string of
  60      characters you want.  Good passphrases are 10-30 characters long, are not
  61      simple sentences or otherwise easily guessable (English prose has only
  62      1-2 bits of entropy per character, and provides very bad passphrases),
  63      and contain a mix of upper and lowercase letters, numbers, and non-
  64      alphanumeric characters.  The passphrase can be changed later by using
  65      the -p option.
  66
  67      There is no way to recover a lost passphrase.  If the passphrase is lost
  68      or forgotten, a new key must be generated and the corresponding public
  69      key copied to other machines.
  70
  71      For RSA1 keys, there is also a comment field in the key file that is only
  72      for convenience to the user to help identify the key.  The comment can
  73      tell what the key is for, or whatever is useful.  The comment is
  74      initialized to ``user@host'' when the key is created, but can be changed
  75      using the -c option.
  76
  77      After a key is generated, instructions below detail where the keys should
  78      be placed to be activated.
  79
  80      The options are as follows:
  81
  82      -A      For each of the key types (rsa1, rsa, dsa and ecdsa) for which
  83              host keys do not exist, generate the host keys with the default
  84              key file path, an empty passphrase, default bits for the key
  85              type, and default comment.  This is used by /etc/rc to generate
  86              new host keys.
  87
  88      -a trials
  89              Specifies the number of primality tests to perform when screening
  90              DH-GEX candidates using the -T command.
  91
  92      -B      Show the bubblebabble digest of specified private or public key
  93              file.
  94
  95      -b bits
  96              Specifies the number of bits in the key to create.  For RSA keys,
  97              the minimum size is 768 bits and the default is 2048 bits.
  98              Generally, 2048 bits is considered sufficient.  DSA keys must be
  99              exactly 1024 bits as specified by FIPS 186-2.  For ECDSA keys,
 100              the -b flag determines the key length by selecting from one of
 101              three elliptic curve sizes: 256, 384 or 521 bits.  Attempting to
 102              use bit lengths other than these three values for ECDSA keys will
 103              fail.
 104
 105      -C comment
 106              Provides a new comment.
 107
 108      -c      Requests changing the comment in the private and public key
 109              files.  This operation is only supported for RSA1 keys.  The
 110              program will prompt for the file containing the private keys, for
 111              the passphrase if the key has one, and for the new comment.
 112
 113      -D pkcs11
 114              Download the RSA public keys provided by the PKCS#11 shared
 115              library pkcs11.  When used in combination with -s, this option
 116              indicates that a CA key resides in a PKCS#11 token (see the
 117              CERTIFICATES section for details).
 118
 119      -e      This option will read a private or public OpenSSH key file and
 120              print to stdout the key in one of the formats specified by the -m
 121              option.  The default export format is ``RFC4716''.  This option
 122              allows exporting OpenSSH keys for use by other programs,
 123              including several commercial SSH implementations.
 124
 125      -F hostname
 126              Search for the specified hostname in a known_hosts file, listing
 127              any occurrences found.  This option is useful to find hashed host
 128              names or addresses and may also be used in conjunction with the
 129              -H option to print found keys in a hashed format.
 130
 131      -f filename
 132              Specifies the filename of the key file.
 133
 134      -G output_file
 135              Generate candidate primes for DH-GEX.  These primes must be
 136              screened for safety (using the -T option) before use.
 137
 138      -g      Use generic DNS format when printing fingerprint resource records
 139              using the -r command.
 140
 141      -H      Hash a known_hosts file.  This replaces all hostnames and
 142              addresses with hashed representations within the specified file;
 143              the original content is moved to a file with a .old suffix.
 144              These hashes may be used normally by ssh and sshd, but they do
 145              not reveal identifying information should the file's contents be
 146              disclosed.  This option will not modify existing hashed hostnames
 147              and is therefore safe to use on files that mix hashed and non-
 148              hashed names.
 149
 150      -h      When signing a key, create a host certificate instead of a user
 151              certificate.  Please see the CERTIFICATES section for details.
 152
 153      -I certificate_identity
 154              Specify the key identity when signing a public key.  Please see
 155              the CERTIFICATES section for details.
 156
 157      -i      This option will read an unencrypted private (or public) key file
 158              in the format specified by the -m option and print an OpenSSH
 159              compatible private (or public) key to stdout.
 160
 161      -J num_lines
 162              Exit after screening the specified number of lines while
 163              performing DH candidate screening using the -T option.
 164
 165      -j start_line
 166              Start screening at the specified line number while performing DH
 167              candidate screening using the -T option.
 168
 169      -K checkpt
 170              Write the last line processed to the file checkpt while
 171              performing DH candidate screening using the -T option.  This will
 172              be used to skip lines in the input file that have already been
 173              processed if the job is restarted.  This option allows importing
 174              keys from other software, including several commercial SSH
 175              implementations.  The default import format is ``RFC4716''.
 176
 177      -k      Generate a KRL file.  In this mode, ssh-keygen will generate a
 178              KRL file at the location specified via the -f flag that revokes
 179              every key or certificate presented on the command line.
 180              Keys/certificates to be revoked may be specified by public key
 181              file or using the format described in the KEY REVOCATION LISTS
 182              section.
 183
 184      -L      Prints the contents of a certificate.
 185
 186      -l      Show fingerprint of specified public key file.  Private RSA1 keys
 187              are also supported.  For RSA and DSA keys ssh-keygen tries to
 188              find the matching public key file and prints its fingerprint.  If
 189              combined with -v, an ASCII art representation of the key is
 190              supplied with the fingerprint.
 191
 192      -M memory
 193              Specify the amount of memory to use (in megabytes) when
 194              generating candidate moduli for DH-GEX.
 195
 196      -m key_format
 197              Specify a key format for the -i (import) or -e (export)
 198              conversion options.  The supported key formats are: ``RFC4716''
 199              (RFC 4716/SSH2 public or private key), ``PKCS8'' (PEM PKCS8
 200              public key) or ``PEM'' (PEM public key).  The default conversion
 201              format is ``RFC4716''.
 202
 203      -N new_passphrase
 204              Provides the new passphrase.
 205
 206      -n principals
 207              Specify one or more principals (user or host names) to be
 208              included in a certificate when signing a key.  Multiple
 209              principals may be specified, separated by commas.  Please see the
 210              CERTIFICATES section for details.
 211
 212      -O option
 213              Specify a certificate option when signing a key.  This option may
 214              be specified multiple times.  Please see the CERTIFICATES section
 215              for details.  The options that are valid for user certificates
 216              are:
 217
 218              clear   Clear all enabled permissions.  This is useful for
 219                      clearing the default set of permissions so permissions
 220                      may be added individually.
 221
 222              force-command=command
 223                      Forces the execution of command instead of any shell or
 224                      command specified by the user when the certificate is
 225                      used for authentication.
 226
 227              no-agent-forwarding
 228                      Disable ssh-agent(1) forwarding (permitted by default).
 229
 230              no-port-forwarding
 231                      Disable port forwarding (permitted by default).
 232
 233              no-pty  Disable PTY allocation (permitted by default).
 234
 235              no-user-rc
 236                      Disable execution of ~/.ssh/rc by sshd(8) (permitted by
 237                      default).
 238
 239              no-x11-forwarding
 240                      Disable X11 forwarding (permitted by default).
 241
 242              permit-agent-forwarding
 243                      Allows ssh-agent(1) forwarding.
 244
 245              permit-port-forwarding
 246                      Allows port forwarding.
 247
 248              permit-pty
 249                      Allows PTY allocation.
 250
 251              permit-user-rc
 252                      Allows execution of ~/.ssh/rc by sshd(8).
 253
 254              permit-x11-forwarding
 255                      Allows X11 forwarding.
 256
 257              source-address=address_list
 258                      Restrict the source addresses from which the certificate
 259                      is considered valid.  The address_list is a comma-
 260                      separated list of one or more address/netmask pairs in
 261                      CIDR format.
 262
 263              At present, no options are valid for host keys.
 264
 265      -P passphrase
 266              Provides the (old) passphrase.
 267
 268      -p      Requests changing the passphrase of a private key file instead of
 269              creating a new private key.  The program will prompt for the file
 270              containing the private key, for the old passphrase, and twice for
 271              the new passphrase.
 272
 273      -Q      Test whether keys have been revoked in a KRL.
 274
 275      -q      Silence ssh-keygen.
 276
 277      -R hostname
 278              Removes all keys belonging to hostname from a known_hosts file.
 279              This option is useful to delete hashed hosts (see the -H option
 280              above).
 281
 282      -r hostname
 283              Print the SSHFP fingerprint resource record named hostname for
 284              the specified public key file.
 285
 286      -S start
 287              Specify start point (in hex) when generating candidate moduli for
 288              DH-GEX.
 289
 290      -s ca_key
 291              Certify (sign) a public key using the specified CA key.  Please
 292              see the CERTIFICATES section for details.
 293
 294              When generating a KRL, -s specifies a path to a CA public key
 295              file used to revoke certificates directly by key ID or serial
 296              number.  See the KEY REVOCATION LISTS section for details.
 297
 298      -T output_file
 299              Test DH group exchange candidate primes (generated using the -G
 300              option) for safety.
 301
 302      -t type
 303              Specifies the type of key to create.  The possible values are
 304              ``rsa1'' for protocol version 1 and ``dsa'', ``ecdsa'' or ``rsa''
 305              for protocol version 2.
 306
 307      -u      Update a KRL.  When specified with -k, keys listed via the
 308              command line are added to the existing KRL rather than a new KRL
 309              being created.
 310
 311      -V validity_interval
 312              Specify a validity interval when signing a certificate.  A
 313              validity interval may consist of a single time, indicating that
 314              the certificate is valid beginning now and expiring at that time,
 315              or may consist of two times separated by a colon to indicate an
 316              explicit time interval.  The start time may be specified as a
 317              date in YYYYMMDD format, a time in YYYYMMDDHHMMSS format or a
 318              relative time (to the current time) consisting of a minus sign
 319              followed by a relative time in the format described in the TIME
 320              FORMATS section of sshd_config(5).  The end time may be specified
 321              as a YYYYMMDD date, a YYYYMMDDHHMMSS time or a relative time
 322              starting with a plus character.
 323
 324              For example: ``+52w1d'' (valid from now to 52 weeks and one day
 325              from now), ``-4w:+4w'' (valid from four weeks ago to four weeks
 326              from now), ``20100101123000:20110101123000'' (valid from 12:30
 327              PM, January 1st, 2010 to 12:30 PM, January 1st, 2011),
 328              ``-1d:20110101'' (valid from yesterday to midnight, January 1st,
 329              2011).
 330
 331      -v      Verbose mode.  Causes ssh-keygen to print debugging messages
 332              about its progress.  This is helpful for debugging moduli
 333              generation.  Multiple -v options increase the verbosity.  The
 334              maximum is 3.
 335
 336      -W generator
 337              Specify desired generator when testing candidate moduli for DH-
 338              GEX.
 339
 340      -y      This option will read a private OpenSSH format file and print an
 341              OpenSSH public key to stdout.
 342
 343      -z serial_number
 344              Specifies a serial number to be embedded in the certificate to
 345              distinguish this certificate from others from the same CA.  The
 346              default serial number is zero.
 347
 348              When generating a KRL, the -z flag is used to specify a KRL
 349              version number.
 350
 351 MODULI GENERATION
 352      ssh-keygen may be used to generate groups for the Diffie-Hellman Group
 353      Exchange (DH-GEX) protocol.  Generating these groups is a two-step
 354      process: first, candidate primes are generated using a fast, but memory
 355      intensive process.  These candidate primes are then tested for
 356      suitability (a CPU-intensive process).
 357
 358      Generation of primes is performed using the -G option.  The desired
 359      length of the primes may be specified by the -b option.  For example:
 360
 361            # ssh-keygen -G moduli-2048.candidates -b 2048
 362
 363      By default, the search for primes begins at a random point in the desired
 364      length range.  This may be overridden using the -S option, which
 365      specifies a different start point (in hex).
 366
 367      Once a set of candidates have been generated, they must be screened for
 368      suitability.  This may be performed using the -T option.  In this mode
 369      ssh-keygen will read candidates from standard input (or a file specified
 370      using the -f option).  For example:
 371
 372            # ssh-keygen -T moduli-2048 -f moduli-2048.candidates
 373
 374      By default, each candidate will be subjected to 100 primality tests.
 375      This may be overridden using the -a option.  The DH generator value will
 376      be chosen automatically for the prime under consideration.  If a specific
 377      generator is desired, it may be requested using the -W option.  Valid
 378      generator values are 2, 3, and 5.
 379
 380      Screened DH groups may be installed in /etc/moduli.  It is important that
 381      this file contains moduli of a range of bit lengths and that both ends of
 382      a connection share common moduli.
 383
 384 CERTIFICATES
 385      ssh-keygen supports signing of keys to produce certificates that may be
 386      used for user or host authentication.  Certificates consist of a public
 387      key, some identity information, zero or more principal (user or host)
 388      names and a set of options that are signed by a Certification Authority
 389      (CA) key.  Clients or servers may then trust only the CA key and verify
 390      its signature on a certificate rather than trusting many user/host keys.
 391      Note that OpenSSH certificates are a different, and much simpler, format
 392      to the X.509 certificates used in ssl(8).
 393
 394      ssh-keygen supports two types of certificates: user and host.  User
 395      certificates authenticate users to servers, whereas host certificates
 396      authenticate server hosts to users.  To generate a user certificate:
 397
 398            $ ssh-keygen -s /path/to/ca_key -I key_id /path/to/user_key.pub
 399
 400      The resultant certificate will be placed in /path/to/user_key-cert.pub.
 401      A host certificate requires the -h option:
 402
 403            $ ssh-keygen -s /path/to/ca_key -I key_id -h /path/to/host_key.pub
 404
 405      The host certificate will be output to /path/to/host_key-cert.pub.
 406
 407      It is possible to sign using a CA key stored in a PKCS#11 token by
 408      providing the token library using -D and identifying the CA key by
 409      providing its public half as an argument to -s:
 410
 411            $ ssh-keygen -s ca_key.pub -D libpkcs11.so -I key_id host_key.pub
 412
 413      In all cases, key_id is a "key identifier" that is logged by the server
 414      when the certificate is used for authentication.
 415
 416      Certificates may be limited to be valid for a set of principal
 417      (user/host) names.  By default, generated certificates are valid for all
 418      users or hosts.  To generate a certificate for a specified set of
 419      principals:
 420
 421            $ ssh-keygen -s ca_key -I key_id -n user1,user2 user_key.pub
 422            $ ssh-keygen -s ca_key -I key_id -h -n host.domain user_key.pub
 423
 424      Additional limitations on the validity and use of user certificates may
 425      be specified through certificate options.  A certificate option may
 426      disable features of the SSH session, may be valid only when presented
 427      from particular source addresses or may force the use of a specific
 428      command.  For a list of valid certificate options, see the documentation
 429      for the -O option above.
 430
 431      Finally, certificates may be defined with a validity lifetime.  The -V
 432      option allows specification of certificate start and end times.  A
 433      certificate that is presented at a time outside this range will not be
 434      considered valid.  By default, certificates are valid from UNIX Epoch to
 435      the distant future.
 436
 437      For certificates to be used for user or host authentication, the CA
 438      public key must be trusted by sshd(8) or ssh(1).  Please refer to those
 439      manual pages for details.
 440
 441 KEY REVOCATION LISTS
 442      ssh-keygen is able to manage OpenSSH format Key Revocation Lists (KRLs).
 443      These binary files specify keys or certificates to be revoked using a
 444      compact format, taking as little a one bit per certificate if they are
 445      being revoked by serial number.
 446
 447      KRLs may be generated using the -k flag.  This option reads one or more
 448      files from the command line and generates a new KRL.  The files may
 449      either contain a KRL specification (see below) or public keys, listed one
 450      per line.  Plain public keys are revoked by listing their hash or
 451      contents in the KRL and certificates revoked by serial number or key ID
 452      (if the serial is zero or not available).
 453
 454      Revoking keys using a KRL specification offers explicit control over the
 455      types of record used to revoke keys and may be used to directly revoke
 456      certificates by serial number or key ID without having the complete
 457      original certificate on hand.  A KRL specification consists of lines
 458      containing one of the following directives followed by a colon and some
 459      directive-specific information.
 460
 461      serial: serial_number[-serial_number]
 462              Revokes a certificate with the specified serial number.  Serial
 463              numbers are 64-bit values, not including zero and may be
 464              expressed in decimal, hex or octal.  If two serial numbers are
 465              specified separated by a hyphen, then the range of serial numbers
 466              including and between each is revoked.  The CA key must have been
 467              specified on the ssh-keygen command line using the -s option.
 468
 469      id: key_id
 470              Revokes a certificate with the specified key ID string.  The CA
 471              key must have been specified on the ssh-keygen command line using
 472              the -s option.
 473
 474      key: public_key
 475              Revokes the specified key.  If a certificate is listed, then it
 476              is revoked as a plain public key.
 477
 478      sha1: public_key
 479              Revokes the specified key by its SHA1 hash.
 480
 481      KRLs may be updated using the -u flag in addition to -k.  When this
 482      option is specified, keys listed via the command line are merged into the
 483      KRL, adding to those already there.
 484
 485      It is also possible, given a KRL, to test whether it revokes a particular
 486      key (or keys).  The -Q flag will query an existing KRL, testing each key
 487      specified on the commandline.  If any key listed on the command line has
 488      been revoked (or an error encountered) then ssh-keygen will exit with a
 489      non-zero exit status.  A zero exit status will only be returned if no key
 490      was revoked.
 491
 492 FILES
 493      ~/.ssh/identity
 494              Contains the protocol version 1 RSA authentication identity of
 495              the user.  This file should not be readable by anyone but the
 496              user.  It is possible to specify a passphrase when generating the
 497              key; that passphrase will be used to encrypt the private part of
 498              this file using 3DES.  This file is not automatically accessed by
 499              ssh-keygen but it is offered as the default file for the private
 500              key.  ssh(1) will read this file when a login attempt is made.
 501
 502      ~/.ssh/identity.pub
 503              Contains the protocol version 1 RSA public key for
 504              authentication.  The contents of this file should be added to
 505              ~/.ssh/authorized_keys on all machines where the user wishes to
 506              log in using RSA authentication.  There is no need to keep the
 507              contents of this file secret.
 508
 509      ~/.ssh/id_dsa
 510      ~/.ssh/id_ecdsa
 511      ~/.ssh/id_rsa
 512              Contains the protocol version 2 DSA, ECDSA or RSA authentication
 513              identity of the user.  This file should not be readable by anyone
 514              but the user.  It is possible to specify a passphrase when
 515              generating the key; that passphrase will be used to encrypt the
 516              private part of this file using 128-bit AES.  This file is not
 517              automatically accessed by ssh-keygen but it is offered as the
 518              default file for the private key.  ssh(1) will read this file
 519              when a login attempt is made.
 520
 521      ~/.ssh/id_dsa.pub
 522      ~/.ssh/id_ecdsa.pub
 523      ~/.ssh/id_rsa.pub
 524              Contains the protocol version 2 DSA, ECDSA or RSA public key for
 525              authentication.  The contents of this file should be added to
 526              ~/.ssh/authorized_keys on all machines where the user wishes to
 527              log in using public key authentication.  There is no need to keep
 528              the contents of this file secret.
 529
 530      /etc/moduli
 531              Contains Diffie-Hellman groups used for DH-GEX.  The file format
 532              is described in moduli(5).
 533
 534 SEE ALSO
 535      ssh(1), ssh-add(1), ssh-agent(1), moduli(5), sshd(8)
 536
 537      The Secure Shell (SSH) Public Key File Format, RFC 4716, 2006.
 538
 539 AUTHORS
 540      OpenSSH is a derivative of the original and free ssh 1.2.12 release by
 541      Tatu Ylonen.  Aaron Campbell, Bob Beck, Markus Friedl, Niels Provos, Theo
 542      de Raadt and Dug Song removed many bugs, re-added newer features and
 543      created OpenSSH.  Markus Friedl contributed the support for SSH protocol
 544      versions 1.5 and 2.0.
 545
 546 OpenBSD 5.4                      June 27, 2013                     OpenBSD 5.4