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