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