OSDN Git Service

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