1 .\" $OpenBSD: ssh-keygen.1,v 1.101 2010/10/28 18:33:28 jmc Exp $
3 .\" Author: Tatu Ylonen <ylo@cs.hut.fi>
4 .\" Copyright (c) 1995 Tatu Ylonen <ylo@cs.hut.fi>, Espoo, Finland
5 .\" All rights reserved
7 .\" As far as I am concerned, the code I have written for this software
8 .\" can be used freely for any purpose. Any derived versions of this
9 .\" software must be clearly marked as such, and if the derived work is
10 .\" incompatible with the protocol description in the RFC file, it must be
11 .\" called by a name other than "ssh" or "Secure Shell".
14 .\" Copyright (c) 1999,2000 Markus Friedl. All rights reserved.
15 .\" Copyright (c) 1999 Aaron Campbell. All rights reserved.
16 .\" Copyright (c) 1999 Theo de Raadt. All rights reserved.
18 .\" Redistribution and use in source and binary forms, with or without
19 .\" modification, are permitted provided that the following conditions
21 .\" 1. Redistributions of source code must retain the above copyright
22 .\" notice, this list of conditions and the following disclaimer.
23 .\" 2. Redistributions in binary form must reproduce the above copyright
24 .\" notice, this list of conditions and the following disclaimer in the
25 .\" documentation and/or other materials provided with the distribution.
27 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
28 .\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
29 .\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
30 .\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
31 .\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
32 .\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
33 .\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
34 .\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
35 .\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
36 .\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
38 .Dd $Mdocdate: October 28 2010 $
43 .Nd authentication key generation, management and conversion
50 .Op Fl N Ar new_passphrase
52 .Op Fl f Ar output_keyfile
55 .Op Fl P Ar old_passphrase
56 .Op Fl N Ar new_passphrase
60 .Op Fl m Ar key_format
61 .Op Fl f Ar input_keyfile
64 .Op Fl m Ar key_format
65 .Op Fl f Ar input_keyfile
68 .Op Fl f Ar input_keyfile
71 .Op Fl P Ar passphrase
76 .Op Fl f Ar input_keyfile
79 .Op Fl f Ar input_keyfile
84 .Op Fl f Ar known_hosts_file
88 .Op Fl f Ar known_hosts_file
91 .Op Fl f Ar known_hosts_file
94 .Op Fl f Ar input_keyfile
101 .Op Fl S Ar start_point
106 .Op Fl a Ar num_trials
107 .Op Fl W Ar generator
110 .Fl I Ar certificate_identity
112 .Op Fl n Ar principals
114 .Op Fl V Ar validity_interval
115 .Op Fl z Ar serial_number
119 .Op Fl f Ar input_keyfile
123 generates, manages and converts authentication keys for
126 can create RSA keys for use by SSH protocol version 1 and DSA, ECDSA or RSA
127 keys for use by SSH protocol version 2.
128 The type of key to be generated is specified with the
131 If invoked without any arguments,
133 will generate an RSA key for use in SSH protocol 2 connections.
136 is also used to generate groups for use in Diffie-Hellman group
139 .Sx MODULI GENERATION
142 Normally each user wishing to use SSH
143 with public key authentication runs this once to create the authentication
145 .Pa ~/.ssh/identity ,
146 .Pa ~/.ssh/id_ecdsa ,
150 Additionally, the system administrator may use this to generate host keys.
152 Normally this program generates the key and asks for a file in which
153 to store the private key.
154 The public key is stored in a file with the same name but
157 The program also asks for a passphrase.
158 The passphrase may be empty to indicate no passphrase
159 (host keys must have an empty passphrase), or it may be a string of
161 A passphrase is similar to a password, except it can be a phrase with a
162 series of words, punctuation, numbers, whitespace, or any string of
164 Good passphrases are 10-30 characters long, are
165 not simple sentences or otherwise easily guessable (English
166 prose has only 1-2 bits of entropy per character, and provides very bad
167 passphrases), and contain a mix of upper and lowercase letters,
168 numbers, and non-alphanumeric characters.
169 The passphrase can be changed later by using the
173 There is no way to recover a lost passphrase.
175 lost or forgotten, a new key must be generated and copied to the
176 corresponding public key to other machines.
179 there is also a comment field in the key file that is only for
180 convenience to the user to help identify the key.
181 The comment can tell what the key is for, or whatever is useful.
182 The comment is initialized to
184 when the key is created, but can be changed using the
188 After a key is generated, instructions below detail where the keys
189 should be placed to be activated.
191 The options are as follows:
194 Specifies the number of primality tests to perform when screening DH-GEX
199 Show the bubblebabble digest of specified private or public key file.
201 Specifies the number of bits in the key to create.
202 For RSA keys, the minimum size is 768 bits and the default is 2048 bits.
203 Generally, 2048 bits is considered sufficient.
204 DSA keys must be exactly 1024 bits as specified by FIPS 186-2.
206 Provides a new comment.
208 Requests changing the comment in the private and public key files.
209 This operation is only supported for RSA1 keys.
210 The program will prompt for the file containing the private keys, for
211 the passphrase if the key has one, and for the new comment.
213 Download the RSA public keys provided by the PKCS#11 shared library
215 When used in combination with
217 this option indicates that a CA key resides in a PKCS#11 token (see the
219 section for details).
221 This option will read a private or public OpenSSH key file and
222 print to stdout the key in one of the formats specified by the
225 The default export format is
227 This option allows exporting OpenSSH keys for use by other programs, including
228 several commercial SSH implementations.
230 Search for the specified
234 file, listing any occurrences found.
235 This option is useful to find hashed host names or addresses and may also be
236 used in conjunction with the
238 option to print found keys in a hashed format.
240 Specifies the filename of the key file.
241 .It Fl G Ar output_file
242 Generate candidate primes for DH-GEX.
243 These primes must be screened for
248 Use generic DNS format when printing fingerprint resource records using the
255 This replaces all hostnames and addresses with hashed representations
256 within the specified file; the original content is moved to a file with
258 These hashes may be used normally by
262 but they do not reveal identifying information should the file's contents
264 This option will not modify existing hashed hostnames and is therefore safe
265 to use on files that mix hashed and non-hashed names.
267 When signing a key, create a host certificate instead of a user
272 .It Fl I Ar certificate_identity
273 Specify the key identity when signing a public key.
278 This option will read an unencrypted private (or public) key file
279 in the format specified by the
281 option and print an OpenSSH compatible private
282 (or public) key to stdout.
283 This option allows importing keys from other software, including several
284 commercial SSH implementations.
285 The default import format is
288 Prints the contents of a certificate.
290 Show fingerprint of specified public key file.
291 Private RSA1 keys are also supported.
294 tries to find the matching public key file and prints its fingerprint.
297 an ASCII art representation of the key is supplied with the fingerprint.
299 Specify the amount of memory to use (in megabytes) when generating
300 candidate moduli for DH-GEX.
301 .It Fl m Ar key_format
302 Specify a key format for the
306 (export) conversion options.
307 The supported key formats are:
309 (RFC 4716/SSH2 public or private key),
311 (PEM PKCS8 public key)
315 The default conversion format is
317 .It Fl N Ar new_passphrase
318 Provides the new passphrase.
319 .It Fl n Ar principals
320 Specify one or more principals (user or host names) to be included in
321 a certificate when signing a key.
322 Multiple principals may be specified, separated by commas.
327 Specify a certificate option when signing a key.
328 This option may be specified multiple times.
332 The options that are valid for user certificates are:
335 Clear all enabled permissions.
336 This is useful for clearing the default set of permissions so permissions may
337 be added individually.
338 .It Ic force-command Ns = Ns Ar command
339 Forces the execution of
341 instead of any shell or command specified by the user when
342 the certificate is used for authentication.
343 .It Ic no-agent-forwarding
346 forwarding (permitted by default).
347 .It Ic no-port-forwarding
348 Disable port forwarding (permitted by default).
350 Disable PTY allocation (permitted by default).
356 (permitted by default).
357 .It Ic no-x11-forwarding
358 Disable X11 forwarding (permitted by default).
359 .It Ic permit-agent-forwarding
363 .It Ic permit-port-forwarding
364 Allows port forwarding.
366 Allows PTY allocation.
367 .It Ic permit-user-rc
372 .It Ic permit-x11-forwarding
373 Allows X11 forwarding.
374 .It Ic source-address Ns = Ns Ar address_list
375 Restrict the source addresses from which the certificate is considered valid.
378 is a comma-separated list of one or more address/netmask pairs in CIDR
382 At present, no options are valid for host keys.
383 .It Fl P Ar passphrase
384 Provides the (old) passphrase.
386 Requests changing the passphrase of a private key file instead of
387 creating a new private key.
388 The program will prompt for the file
389 containing the private key, for the old passphrase, and twice for the
394 Used by system administration scripts when creating a new key.
396 Removes all keys belonging to
401 This option is useful to delete hashed hosts (see the
405 Print the SSHFP fingerprint resource record named
407 for the specified public key file.
409 Specify start point (in hex) when generating candidate moduli for DH-GEX.
411 Certify (sign) a public key using the specified CA key.
415 .It Fl T Ar output_file
416 Test DH group exchange candidate primes (generated using the
420 Specifies the type of key to create.
421 The possible values are
423 for protocol version 1 and
428 for protocol version 2.
429 .It Fl V Ar validity_interval
430 Specify a validity interval when signing a certificate.
431 A validity interval may consist of a single time, indicating that the
432 certificate is valid beginning now and expiring at that time, or may consist
433 of two times separated by a colon to indicate an explicit time interval.
434 The start time may be specified as a date in YYYYMMDD format, a time
435 in YYYYMMDDHHMMSS format or a relative time (to the current time) consisting
436 of a minus sign followed by a relative time in the format described in the
440 The end time may be specified as a YYYYMMDD date, a YYYYMMDDHHMMSS time or
441 a relative time starting with a plus character.
445 (valid from now to 52 weeks and one day from now),
447 (valid from four weeks ago to four weeks from now),
448 .Dq 20100101123000:20110101123000
449 (valid from 12:30 PM, January 1st, 2010 to 12:30 PM, January 1st, 2011),
451 (valid from yesterday to midnight, January 1st, 2011).
456 to print debugging messages about its progress.
457 This is helpful for debugging moduli generation.
460 options increase the verbosity.
462 .It Fl W Ar generator
463 Specify desired generator when testing candidate moduli for DH-GEX.
465 This option will read a private
466 OpenSSH format file and print an OpenSSH public key to stdout.
467 .It Fl z Ar serial_number
468 Specifies a serial number to be embedded in the certificate to distinguish
469 this certificate from others from the same CA.
470 The default serial number is zero.
472 .Sh MODULI GENERATION
474 may be used to generate groups for the Diffie-Hellman Group Exchange
476 Generating these groups is a two-step process: first, candidate
477 primes are generated using a fast, but memory intensive process.
478 These candidate primes are then tested for suitability (a CPU-intensive
481 Generation of primes is performed using the
484 The desired length of the primes may be specified by the
489 .Dl # ssh-keygen -G moduli-2048.candidates -b 2048
491 By default, the search for primes begins at a random point in the
492 desired length range.
493 This may be overridden using the
495 option, which specifies a different start point (in hex).
497 Once a set of candidates have been generated, they must be tested for
499 This may be performed using the
504 will read candidates from standard input (or a file specified using the
509 .Dl # ssh-keygen -T moduli-2048 -f moduli-2048.candidates
511 By default, each candidate will be subjected to 100 primality tests.
512 This may be overridden using the
515 The DH generator value will be chosen automatically for the
516 prime under consideration.
517 If a specific generator is desired, it may be requested using the
520 Valid generator values are 2, 3, and 5.
522 Screened DH groups may be installed in
524 It is important that this file contains moduli of a range of bit lengths and
525 that both ends of a connection share common moduli.
528 supports signing of keys to produce certificates that may be used for
529 user or host authentication.
530 Certificates consist of a public key, some identity information, zero or
531 more principal (user or host) names and a set of options that
532 are signed by a Certification Authority (CA) key.
533 Clients or servers may then trust only the CA key and verify its signature
534 on a certificate rather than trusting many user/host keys.
535 Note that OpenSSH certificates are a different, and much simpler, format to
536 the X.509 certificates used in
540 supports two types of certificates: user and host.
541 User certificates authenticate users to servers, whereas host certificates
542 authenticate server hosts to users.
543 To generate a user certificate:
545 .Dl $ ssh-keygen -s /path/to/ca_key -I key_id /path/to/user_key.pub
547 The resultant certificate will be placed in
548 .Pa /path/to/user_key-cert.pub .
549 A host certificate requires the
553 .Dl $ ssh-keygen -s /path/to/ca_key -I key_id -h /path/to/host_key.pub
555 The host certificate will be output to
556 .Pa /path/to/host_key-cert.pub .
558 It is possible to sign using a CA key stored in a PKCS#11 token by
559 providing the token library using
561 and identifying the CA key by providing its public half as an argument
565 .Dl $ ssh-keygen -s ca_key.pub -D libpkcs11.so -I key_id host_key.pub
569 is a "key identifier" that is logged by the server when the certificate
570 is used for authentication.
572 Certificates may be limited to be valid for a set of principal (user/host)
574 By default, generated certificates are valid for all users or hosts.
575 To generate a certificate for a specified set of principals:
577 .Dl $ ssh-keygen -s ca_key -I key_id -n user1,user2 user_key.pub
578 .Dl "$ ssh-keygen -s ca_key -I key_id -h -n host.domain user_key.pub"
580 Additional limitations on the validity and use of user certificates may
581 be specified through certificate options.
582 A certificate option may disable features of the SSH session, may be
583 valid only when presented from particular source addresses or may
584 force the use of a specific command.
585 For a list of valid certificate options, see the documentation for the
589 Finally, certificates may be defined with a validity lifetime.
592 option allows specification of certificate start and end times.
593 A certificate that is presented at a time outside this range will not be
595 By default, certificates have a maximum validity interval.
597 For certificates to be used for user or host authentication, the CA
598 public key must be trusted by
602 Please refer to those manual pages for details.
604 .Bl -tag -width Ds -compact
605 .It Pa ~/.ssh/identity
606 Contains the protocol version 1 RSA authentication identity of the user.
607 This file should not be readable by anyone but the user.
609 specify a passphrase when generating the key; that passphrase will be
610 used to encrypt the private part of this file using 3DES.
611 This file is not automatically accessed by
613 but it is offered as the default file for the private key.
615 will read this file when a login attempt is made.
617 .It Pa ~/.ssh/identity.pub
618 Contains the protocol version 1 RSA public key for authentication.
619 The contents of this file should be added to
620 .Pa ~/.ssh/authorized_keys
622 where the user wishes to log in using RSA authentication.
623 There is no need to keep the contents of this file secret.
626 .It Pa ~/.ssh/id_ecdsa
628 Contains the protocol version 2 DSA, ECDSA or RSA authentication identity of the user.
629 This file should not be readable by anyone but the user.
631 specify a passphrase when generating the key; that passphrase will be
632 used to encrypt the private part of this file using 128-bit AES.
633 This file is not automatically accessed by
635 but it is offered as the default file for the private key.
637 will read this file when a login attempt is made.
639 .It Pa ~/.ssh/id_dsa.pub
640 .It Pa ~/.ssh/id_ecdsa.pub
641 .It Pa ~/.ssh/id_rsa.pub
642 Contains the protocol version 2 DSA, ECDSA or RSA public key for authentication.
643 The contents of this file should be added to
644 .Pa ~/.ssh/authorized_keys
646 where the user wishes to log in using public key authentication.
647 There is no need to keep the contents of this file secret.
650 Contains Diffie-Hellman groups used for DH-GEX.
651 The file format is described in
663 .%T "The Secure Shell (SSH) Public Key File Format"
667 OpenSSH is a derivative of the original and free
668 ssh 1.2.12 release by Tatu Ylonen.
669 Aaron Campbell, Bob Beck, Markus Friedl, Niels Provos,
670 Theo de Raadt and Dug Song
671 removed many bugs, re-added newer features and
673 Markus Friedl contributed the support for SSH
674 protocol versions 1.5 and 2.0.
projects / openssh.git / blob