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