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