Annotation of src/usr.bin/ssh/ssh-keygen.1, Revision 1.117
1.117 ! djm 1: .\" $OpenBSD: ssh-keygen.1,v 1.116 2013/06/27 14:05:37 jmc Exp $
1.1 deraadt 2: .\"
3: .\" Author: Tatu Ylonen <ylo@cs.hut.fi>
4: .\" Copyright (c) 1995 Tatu Ylonen <ylo@cs.hut.fi>, Espoo, Finland
5: .\" All rights reserved
6: .\"
1.22 deraadt 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".
12: .\"
13: .\"
1.33 deraadt 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.
1.22 deraadt 17: .\"
18: .\" Redistribution and use in source and binary forms, with or without
19: .\" modification, are permitted provided that the following conditions
20: .\" are met:
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.
1.1 deraadt 26: .\"
1.22 deraadt 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.
1.1 deraadt 37: .\"
1.117 ! djm 38: .Dd $Mdocdate: June 27 2013 $
1.2 deraadt 39: .Dt SSH-KEYGEN 1
40: .Os
41: .Sh NAME
42: .Nm ssh-keygen
1.37 markus 43: .Nd authentication key generation, management and conversion
1.2 deraadt 44: .Sh SYNOPSIS
1.97 schwarze 45: .Bk -words
1.2 deraadt 46: .Nm ssh-keygen
1.25 markus 47: .Op Fl q
1.2 deraadt 48: .Op Fl b Ar bits
1.53 stevesk 49: .Fl t Ar type
1.2 deraadt 50: .Op Fl N Ar new_passphrase
51: .Op Fl C Ar comment
1.20 markus 52: .Op Fl f Ar output_keyfile
1.2 deraadt 53: .Nm ssh-keygen
54: .Fl p
55: .Op Fl P Ar old_passphrase
56: .Op Fl N Ar new_passphrase
1.9 markus 57: .Op Fl f Ar keyfile
1.2 deraadt 58: .Nm ssh-keygen
1.37 markus 59: .Fl i
1.95 djm 60: .Op Fl m Ar key_format
1.20 markus 61: .Op Fl f Ar input_keyfile
1.16 deraadt 62: .Nm ssh-keygen
1.37 markus 63: .Fl e
1.95 djm 64: .Op Fl m Ar key_format
1.20 markus 65: .Op Fl f Ar input_keyfile
1.16 deraadt 66: .Nm ssh-keygen
1.17 markus 67: .Fl y
1.20 markus 68: .Op Fl f Ar input_keyfile
1.17 markus 69: .Nm ssh-keygen
1.2 deraadt 70: .Fl c
71: .Op Fl P Ar passphrase
72: .Op Fl C Ar comment
1.9 markus 73: .Op Fl f Ar keyfile
74: .Nm ssh-keygen
75: .Fl l
1.35 markus 76: .Op Fl f Ar input_keyfile
77: .Nm ssh-keygen
78: .Fl B
1.20 markus 79: .Op Fl f Ar input_keyfile
1.48 jakob 80: .Nm ssh-keygen
1.82 jmc 81: .Fl D Ar pkcs11
1.48 jakob 82: .Nm ssh-keygen
1.64 djm 83: .Fl F Ar hostname
84: .Op Fl f Ar known_hosts_file
1.79 sthen 85: .Op Fl l
1.64 djm 86: .Nm ssh-keygen
87: .Fl H
88: .Op Fl f Ar known_hosts_file
89: .Nm ssh-keygen
90: .Fl R Ar hostname
91: .Op Fl f Ar known_hosts_file
1.57 jakob 92: .Nm ssh-keygen
93: .Fl r Ar hostname
94: .Op Fl f Ar input_keyfile
95: .Op Fl g
1.60 djm 96: .Nm ssh-keygen
97: .Fl G Ar output_file
1.61 djm 98: .Op Fl v
1.60 djm 99: .Op Fl b Ar bits
100: .Op Fl M Ar memory
101: .Op Fl S Ar start_point
102: .Nm ssh-keygen
103: .Fl T Ar output_file
104: .Fl f Ar input_file
1.61 djm 105: .Op Fl v
1.117 ! djm 106: .Op Fl a Ar rounds
1.109 dtucker 107: .Op Fl J Ar num_lines
108: .Op Fl j Ar start_line
1.108 dtucker 109: .Op Fl K Ar checkpt
1.60 djm 110: .Op Fl W Ar generator
1.84 djm 111: .Nm ssh-keygen
112: .Fl s Ar ca_key
113: .Fl I Ar certificate_identity
114: .Op Fl h
115: .Op Fl n Ar principals
1.93 djm 116: .Op Fl O Ar option
1.84 djm 117: .Op Fl V Ar validity_interval
1.93 djm 118: .Op Fl z Ar serial_number
1.84 djm 119: .Ar
1.86 djm 120: .Nm ssh-keygen
121: .Fl L
122: .Op Fl f Ar input_keyfile
1.102 stevesk 123: .Nm ssh-keygen
124: .Fl A
1.111 djm 125: .Nm ssh-keygen
126: .Fl k
127: .Fl f Ar krl_file
128: .Op Fl u
1.112 jmc 129: .Op Fl s Ar ca_public
130: .Op Fl z Ar version_number
1.111 djm 131: .Ar
132: .Nm ssh-keygen
133: .Fl Q
134: .Fl f Ar krl_file
135: .Ar
1.85 jmc 136: .Ek
1.13 aaron 137: .Sh DESCRIPTION
1.2 deraadt 138: .Nm
1.37 markus 139: generates, manages and converts authentication keys for
1.2 deraadt 140: .Xr ssh 1 .
1.15 deraadt 141: .Nm
1.100 naddy 142: can create RSA keys for use by SSH protocol version 1 and DSA, ECDSA or RSA
1.58 jmc 143: keys for use by SSH protocol version 2.
144: The type of key to be generated is specified with the
1.25 markus 145: .Fl t
1.52 djm 146: option.
1.70 djm 147: If invoked without any arguments,
148: .Nm
1.71 jmc 149: will generate an RSA key for use in SSH protocol 2 connections.
1.15 deraadt 150: .Pp
1.60 djm 151: .Nm
152: is also used to generate groups for use in Diffie-Hellman group
153: exchange (DH-GEX).
154: See the
155: .Sx MODULI GENERATION
156: section for details.
157: .Pp
1.111 djm 158: Finally,
159: .Nm
160: can be used to generate and update Key Revocation Lists, and to test whether
1.112 jmc 161: given keys have been revoked by one.
162: See the
1.111 djm 163: .Sx KEY REVOCATION LISTS
164: section for details.
165: .Pp
1.2 deraadt 166: Normally each user wishing to use SSH
1.99 djm 167: with public key authentication runs this once to create the authentication
1.1 deraadt 168: key in
1.68 djm 169: .Pa ~/.ssh/identity ,
1.99 djm 170: .Pa ~/.ssh/id_ecdsa ,
1.68 djm 171: .Pa ~/.ssh/id_dsa
1.15 deraadt 172: or
1.68 djm 173: .Pa ~/.ssh/id_rsa .
1.15 deraadt 174: Additionally, the system administrator may use this to generate host keys,
175: as seen in
176: .Pa /etc/rc .
1.2 deraadt 177: .Pp
1.1 deraadt 178: Normally this program generates the key and asks for a file in which
1.12 aaron 179: to store the private key.
180: The public key is stored in a file with the same name but
1.2 deraadt 181: .Dq .pub
1.12 aaron 182: appended.
183: The program also asks for a passphrase.
184: The passphrase may be empty to indicate no passphrase
1.26 markus 185: (host keys must have an empty passphrase), or it may be a string of
1.12 aaron 186: arbitrary length.
1.51 stevesk 187: A passphrase is similar to a password, except it can be a phrase with a
188: series of words, punctuation, numbers, whitespace, or any string of
189: characters you want.
190: Good passphrases are 10-30 characters long, are
1.1 deraadt 191: not simple sentences or otherwise easily guessable (English
1.42 markus 192: prose has only 1-2 bits of entropy per character, and provides very bad
1.51 stevesk 193: passphrases), and contain a mix of upper and lowercase letters,
194: numbers, and non-alphanumeric characters.
1.12 aaron 195: The passphrase can be changed later by using the
1.2 deraadt 196: .Fl p
1.1 deraadt 197: option.
1.2 deraadt 198: .Pp
1.12 aaron 199: There is no way to recover a lost passphrase.
1.105 djm 200: If the passphrase is lost or forgotten, a new key must be generated
201: and the corresponding public key copied to other machines.
1.2 deraadt 202: .Pp
1.37 markus 203: For RSA1 keys,
204: there is also a comment field in the key file that is only for
1.12 aaron 205: convenience to the user to help identify the key.
206: The comment can tell what the key is for, or whatever is useful.
207: The comment is initialized to
1.2 deraadt 208: .Dq user@host
209: when the key is created, but can be changed using the
210: .Fl c
1.1 deraadt 211: option.
1.2 deraadt 212: .Pp
1.15 deraadt 213: After a key is generated, instructions below detail where the keys
214: should be placed to be activated.
215: .Pp
1.2 deraadt 216: The options are as follows:
217: .Bl -tag -width Ds
1.102 stevesk 218: .It Fl A
219: For each of the key types (rsa1, rsa, dsa and ecdsa) for which host keys
220: do not exist, generate the host keys with the default key file path,
221: an empty passphrase, default bits for the key type, and default comment.
1.104 jmc 222: This is used by
1.102 stevesk 223: .Pa /etc/rc
224: to generate new host keys.
1.117 ! djm 225: .It Fl a Ar rounds
! 226: When saving a new-format private key (i.e. an ed25519 key or any SSH protocol
! 227: 2 key when the
! 228: .Fl o
! 229: flag is set), this option specifies the number of KDF (key derivation function)
! 230: rounds used.
! 231: Higher numbers result in slower passphrase verification and increased
! 232: resistance to brute-force password cracking (should the keys be stolen).
! 233: .Pp
! 234: When screening DH-GEX candidates (
! 235: using the
1.60 djm 236: .Fl T
1.117 ! djm 237: command).
! 238: This option specifies the number of primality tests to perform.
1.66 jmc 239: .It Fl B
240: Show the bubblebabble digest of specified private or public key file.
1.2 deraadt 241: .It Fl b Ar bits
1.12 aaron 242: Specifies the number of bits in the key to create.
1.72 dtucker 243: For RSA keys, the minimum size is 768 bits and the default is 2048 bits.
1.69 djm 244: Generally, 2048 bits is considered sufficient.
1.72 dtucker 245: DSA keys must be exactly 1024 bits as specified by FIPS 186-2.
1.106 djm 246: For ECDSA keys, the
247: .Fl b
1.107 deraadt 248: flag determines the key length by selecting from one of three elliptic
1.106 djm 249: curve sizes: 256, 384 or 521 bits.
250: Attempting to use bit lengths other than these three values for ECDSA keys
251: will fail.
1.66 jmc 252: .It Fl C Ar comment
253: Provides a new comment.
1.2 deraadt 254: .It Fl c
1.1 deraadt 255: Requests changing the comment in the private and public key files.
1.50 markus 256: This operation is only supported for RSA1 keys.
1.1 deraadt 257: The program will prompt for the file containing the private keys, for
1.41 stevesk 258: the passphrase if the key has one, and for the new comment.
1.81 markus 259: .It Fl D Ar pkcs11
1.83 markus 260: Download the RSA public keys provided by the PKCS#11 shared library
261: .Ar pkcs11 .
1.98 djm 262: When used in combination with
263: .Fl s ,
264: this option indicates that a CA key resides in a PKCS#11 token (see the
265: .Sx CERTIFICATES
266: section for details).
1.37 markus 267: .It Fl e
1.40 markus 268: This option will read a private or public OpenSSH key file and
1.95 djm 269: print to stdout the key in one of the formats specified by the
270: .Fl m
271: option.
272: The default export format is
273: .Dq RFC4716 .
1.96 jmc 274: This option allows exporting OpenSSH keys for use by other programs, including
1.95 djm 275: several commercial SSH implementations.
1.66 jmc 276: .It Fl F Ar hostname
277: Search for the specified
278: .Ar hostname
279: in a
280: .Pa known_hosts
281: file, listing any occurrences found.
282: This option is useful to find hashed host names or addresses and may also be
283: used in conjunction with the
284: .Fl H
285: option to print found keys in a hashed format.
286: .It Fl f Ar filename
287: Specifies the filename of the key file.
288: .It Fl G Ar output_file
289: Generate candidate primes for DH-GEX.
290: These primes must be screened for
291: safety (using the
292: .Fl T
293: option) before use.
1.57 jakob 294: .It Fl g
1.62 jakob 295: Use generic DNS format when printing fingerprint resource records using the
1.63 jmc 296: .Fl r
1.62 jakob 297: command.
1.66 jmc 298: .It Fl H
299: Hash a
300: .Pa known_hosts
1.67 dtucker 301: file.
302: This replaces all hostnames and addresses with hashed representations
303: within the specified file; the original content is moved to a file with
304: a .old suffix.
1.66 jmc 305: These hashes may be used normally by
306: .Nm ssh
307: and
308: .Nm sshd ,
309: but they do not reveal identifying information should the file's contents
310: be disclosed.
311: This option will not modify existing hashed hostnames and is therefore safe
312: to use on files that mix hashed and non-hashed names.
1.84 djm 313: .It Fl h
314: When signing a key, create a host certificate instead of a user
315: certificate.
316: Please see the
317: .Sx CERTIFICATES
318: section for details.
1.85 jmc 319: .It Fl I Ar certificate_identity
1.84 djm 320: Specify the key identity when signing a public key.
321: Please see the
322: .Sx CERTIFICATES
323: section for details.
1.37 markus 324: .It Fl i
325: This option will read an unencrypted private (or public) key file
1.95 djm 326: in the format specified by the
327: .Fl m
328: option and print an OpenSSH compatible private
1.37 markus 329: (or public) key to stdout.
1.109 dtucker 330: .It Fl J Ar num_lines
331: Exit after screening the specified number of lines
332: while performing DH candidate screening using the
333: .Fl T
334: option.
335: .It Fl j Ar start_line
336: Start screening at the specified line number
337: while performing DH candidate screening using the
338: .Fl T
339: option.
1.108 dtucker 340: .It Fl K Ar checkpt
341: Write the last line processed to the file
342: .Ar checkpt
343: while performing DH candidate screening using the
344: .Fl T
345: option.
346: This will be used to skip lines in the input file that have already been
347: processed if the job is restarted.
1.95 djm 348: This option allows importing keys from other software, including several
349: commercial SSH implementations.
350: The default import format is
351: .Dq RFC4716 .
1.111 djm 352: .It Fl k
353: Generate a KRL file.
354: In this mode,
355: .Nm
356: will generate a KRL file at the location specified via the
357: .Fl f
1.114 jmc 358: flag that revokes every key or certificate presented on the command line.
1.111 djm 359: Keys/certificates to be revoked may be specified by public key file or
360: using the format described in the
361: .Sx KEY REVOCATION LISTS
362: section.
1.86 djm 363: .It Fl L
364: Prints the contents of a certificate.
1.9 markus 365: .It Fl l
1.77 grunk 366: Show fingerprint of specified public key file.
1.50 markus 367: Private RSA1 keys are also supported.
368: For RSA and DSA keys
369: .Nm
1.78 jmc 370: tries to find the matching public key file and prints its fingerprint.
371: If combined with
372: .Fl v ,
373: an ASCII art representation of the key is supplied with the fingerprint.
1.96 jmc 374: .It Fl M Ar memory
375: Specify the amount of memory to use (in megabytes) when generating
376: candidate moduli for DH-GEX.
1.95 djm 377: .It Fl m Ar key_format
378: Specify a key format for the
379: .Fl i
380: (import) or
381: .Fl e
1.96 jmc 382: (export) conversion options.
1.95 djm 383: The supported key formats are:
384: .Dq RFC4716
1.96 jmc 385: (RFC 4716/SSH2 public or private key),
1.95 djm 386: .Dq PKCS8
387: (PEM PKCS8 public key)
388: or
389: .Dq PEM
390: (PEM public key).
391: The default conversion format is
392: .Dq RFC4716 .
1.66 jmc 393: .It Fl N Ar new_passphrase
394: Provides the new passphrase.
1.84 djm 395: .It Fl n Ar principals
396: Specify one or more principals (user or host names) to be included in
397: a certificate when signing a key.
398: Multiple principals may be specified, separated by commas.
399: Please see the
400: .Sx CERTIFICATES
401: section for details.
1.93 djm 402: .It Fl O Ar option
403: Specify a certificate option when signing a key.
1.84 djm 404: This option may be specified multiple times.
405: Please see the
406: .Sx CERTIFICATES
407: section for details.
1.93 djm 408: The options that are valid for user certificates are:
1.84 djm 409: .Bl -tag -width Ds
1.89 jmc 410: .It Ic clear
411: Clear all enabled permissions.
412: This is useful for clearing the default set of permissions so permissions may
413: be added individually.
414: .It Ic force-command Ns = Ns Ar command
415: Forces the execution of
416: .Ar command
417: instead of any shell or command specified by the user when
418: the certificate is used for authentication.
1.84 djm 419: .It Ic no-agent-forwarding
420: Disable
421: .Xr ssh-agent 1
1.85 jmc 422: forwarding (permitted by default).
1.84 djm 423: .It Ic no-port-forwarding
1.85 jmc 424: Disable port forwarding (permitted by default).
1.84 djm 425: .It Ic no-pty
1.85 jmc 426: Disable PTY allocation (permitted by default).
1.84 djm 427: .It Ic no-user-rc
428: Disable execution of
429: .Pa ~/.ssh/rc
430: by
1.85 jmc 431: .Xr sshd 8
432: (permitted by default).
1.89 jmc 433: .It Ic no-x11-forwarding
434: Disable X11 forwarding (permitted by default).
1.88 djm 435: .It Ic permit-agent-forwarding
436: Allows
437: .Xr ssh-agent 1
438: forwarding.
1.84 djm 439: .It Ic permit-port-forwarding
440: Allows port forwarding.
441: .It Ic permit-pty
442: Allows PTY allocation.
443: .It Ic permit-user-rc
444: Allows execution of
445: .Pa ~/.ssh/rc
446: by
447: .Xr sshd 8 .
1.89 jmc 448: .It Ic permit-x11-forwarding
449: Allows X11 forwarding.
450: .It Ic source-address Ns = Ns Ar address_list
1.90 jmc 451: Restrict the source addresses from which the certificate is considered valid.
1.84 djm 452: The
453: .Ar address_list
454: is a comma-separated list of one or more address/netmask pairs in CIDR
455: format.
456: .El
457: .Pp
1.93 djm 458: At present, no options are valid for host keys.
1.117 ! djm 459: .It Fl o
! 460: Causes
! 461: .Nm
! 462: to save SSH protocol 2 private keys using the new OpenSSH format rather than
! 463: the more compatible PEM format.
! 464: The new format has increased resistance to brute-force password cracking
! 465: but is not supported by versions of OpenSSH prior to 6.5.
! 466: Ed25519 keys always use the new private key format.
1.66 jmc 467: .It Fl P Ar passphrase
468: Provides the (old) passphrase.
1.2 deraadt 469: .It Fl p
1.1 deraadt 470: Requests changing the passphrase of a private key file instead of
1.12 aaron 471: creating a new private key.
472: The program will prompt for the file
1.1 deraadt 473: containing the private key, for the old passphrase, and twice for the
474: new passphrase.
1.113 jmc 475: .It Fl Q
476: Test whether keys have been revoked in a KRL.
1.5 aaron 477: .It Fl q
478: Silence
479: .Nm ssh-keygen .
1.64 djm 480: .It Fl R Ar hostname
481: Removes all keys belonging to
482: .Ar hostname
1.65 jmc 483: from a
1.64 djm 484: .Pa known_hosts
485: file.
1.65 jmc 486: This option is useful to delete hashed hosts (see the
1.64 djm 487: .Fl H
488: option above).
1.66 jmc 489: .It Fl r Ar hostname
490: Print the SSHFP fingerprint resource record named
491: .Ar hostname
492: for the specified public key file.
1.60 djm 493: .It Fl S Ar start
494: Specify start point (in hex) when generating candidate moduli for DH-GEX.
1.84 djm 495: .It Fl s Ar ca_key
496: Certify (sign) a public key using the specified CA key.
497: Please see the
498: .Sx CERTIFICATES
499: section for details.
1.111 djm 500: .Pp
501: When generating a KRL,
502: .Fl s
1.112 jmc 503: specifies a path to a CA public key file used to revoke certificates directly
1.111 djm 504: by key ID or serial number.
505: See the
506: .Sx KEY REVOCATION LISTS
507: section for details.
1.60 djm 508: .It Fl T Ar output_file
509: Test DH group exchange candidate primes (generated using the
510: .Fl G
511: option) for safety.
1.66 jmc 512: .It Fl t Ar type
513: Specifies the type of key to create.
514: The possible values are
515: .Dq rsa1
516: for protocol version 1 and
1.100 naddy 517: .Dq dsa ,
518: .Dq ecdsa
519: or
1.66 jmc 520: .Dq rsa
521: for protocol version 2.
1.112 jmc 522: .It Fl u
523: Update a KRL.
524: When specified with
525: .Fl k ,
1.114 jmc 526: keys listed via the command line are added to the existing KRL rather than
1.112 jmc 527: a new KRL being created.
1.84 djm 528: .It Fl V Ar validity_interval
529: Specify a validity interval when signing a certificate.
530: A validity interval may consist of a single time, indicating that the
531: certificate is valid beginning now and expiring at that time, or may consist
532: of two times separated by a colon to indicate an explicit time interval.
533: The start time may be specified as a date in YYYYMMDD format, a time
534: in YYYYMMDDHHMMSS format or a relative time (to the current time) consisting
535: of a minus sign followed by a relative time in the format described in the
1.116 jmc 536: TIME FORMATS section of
1.90 jmc 537: .Xr sshd_config 5 .
1.84 djm 538: The end time may be specified as a YYYYMMDD date, a YYYYMMDDHHMMSS time or
539: a relative time starting with a plus character.
540: .Pp
541: For example:
542: .Dq +52w1d
543: (valid from now to 52 weeks and one day from now),
544: .Dq -4w:+4w
545: (valid from four weeks ago to four weeks from now),
546: .Dq 20100101123000:20110101123000
547: (valid from 12:30 PM, January 1st, 2010 to 12:30 PM, January 1st, 2011),
548: .Dq -1d:20110101
549: (valid from yesterday to midnight, January 1st, 2011).
1.61 djm 550: .It Fl v
551: Verbose mode.
552: Causes
553: .Nm
554: to print debugging messages about its progress.
555: This is helpful for debugging moduli generation.
556: Multiple
557: .Fl v
558: options increase the verbosity.
559: The maximum is 3.
1.66 jmc 560: .It Fl W Ar generator
561: Specify desired generator when testing candidate moduli for DH-GEX.
562: .It Fl y
563: This option will read a private
564: OpenSSH format file and print an OpenSSH public key to stdout.
1.93 djm 565: .It Fl z Ar serial_number
566: Specifies a serial number to be embedded in the certificate to distinguish
567: this certificate from others from the same CA.
568: The default serial number is zero.
1.111 djm 569: .Pp
570: When generating a KRL, the
571: .Fl z
572: flag is used to specify a KRL version number.
1.2 deraadt 573: .El
1.60 djm 574: .Sh MODULI GENERATION
575: .Nm
576: may be used to generate groups for the Diffie-Hellman Group Exchange
577: (DH-GEX) protocol.
578: Generating these groups is a two-step process: first, candidate
579: primes are generated using a fast, but memory intensive process.
580: These candidate primes are then tested for suitability (a CPU-intensive
581: process).
582: .Pp
583: Generation of primes is performed using the
584: .Fl G
585: option.
586: The desired length of the primes may be specified by the
587: .Fl b
588: option.
589: For example:
590: .Pp
1.66 jmc 591: .Dl # ssh-keygen -G moduli-2048.candidates -b 2048
1.60 djm 592: .Pp
593: By default, the search for primes begins at a random point in the
594: desired length range.
595: This may be overridden using the
596: .Fl S
597: option, which specifies a different start point (in hex).
598: .Pp
1.109 dtucker 599: Once a set of candidates have been generated, they must be screened for
1.60 djm 600: suitability.
601: This may be performed using the
602: .Fl T
603: option.
604: In this mode
605: .Nm
606: will read candidates from standard input (or a file specified using the
607: .Fl f
608: option).
609: For example:
610: .Pp
1.66 jmc 611: .Dl # ssh-keygen -T moduli-2048 -f moduli-2048.candidates
1.60 djm 612: .Pp
613: By default, each candidate will be subjected to 100 primality tests.
614: This may be overridden using the
615: .Fl a
616: option.
617: The DH generator value will be chosen automatically for the
618: prime under consideration.
619: If a specific generator is desired, it may be requested using the
620: .Fl W
621: option.
1.66 jmc 622: Valid generator values are 2, 3, and 5.
1.60 djm 623: .Pp
624: Screened DH groups may be installed in
625: .Pa /etc/moduli .
626: It is important that this file contains moduli of a range of bit lengths and
627: that both ends of a connection share common moduli.
1.84 djm 628: .Sh CERTIFICATES
629: .Nm
630: supports signing of keys to produce certificates that may be used for
631: user or host authentication.
632: Certificates consist of a public key, some identity information, zero or
1.94 jmc 633: more principal (user or host) names and a set of options that
1.84 djm 634: are signed by a Certification Authority (CA) key.
635: Clients or servers may then trust only the CA key and verify its signature
636: on a certificate rather than trusting many user/host keys.
637: Note that OpenSSH certificates are a different, and much simpler, format to
638: the X.509 certificates used in
639: .Xr ssl 8 .
640: .Pp
641: .Nm
642: supports two types of certificates: user and host.
643: User certificates authenticate users to servers, whereas host certificates
1.85 jmc 644: authenticate server hosts to users.
645: To generate a user certificate:
1.84 djm 646: .Pp
647: .Dl $ ssh-keygen -s /path/to/ca_key -I key_id /path/to/user_key.pub
648: .Pp
649: The resultant certificate will be placed in
1.91 djm 650: .Pa /path/to/user_key-cert.pub .
1.84 djm 651: A host certificate requires the
652: .Fl h
653: option:
654: .Pp
655: .Dl $ ssh-keygen -s /path/to/ca_key -I key_id -h /path/to/host_key.pub
656: .Pp
657: The host certificate will be output to
1.91 djm 658: .Pa /path/to/host_key-cert.pub .
1.98 djm 659: .Pp
660: It is possible to sign using a CA key stored in a PKCS#11 token by
661: providing the token library using
662: .Fl D
663: and identifying the CA key by providing its public half as an argument
664: to
665: .Fl s :
666: .Pp
667: .Dl $ ssh-keygen -s ca_key.pub -D libpkcs11.so -I key_id host_key.pub
668: .Pp
669: In all cases,
1.84 djm 670: .Ar key_id
671: is a "key identifier" that is logged by the server when the certificate
672: is used for authentication.
673: .Pp
674: Certificates may be limited to be valid for a set of principal (user/host)
675: names.
676: By default, generated certificates are valid for all users or hosts.
677: To generate a certificate for a specified set of principals:
678: .Pp
679: .Dl $ ssh-keygen -s ca_key -I key_id -n user1,user2 user_key.pub
1.92 jmc 680: .Dl "$ ssh-keygen -s ca_key -I key_id -h -n host.domain user_key.pub"
1.84 djm 681: .Pp
682: Additional limitations on the validity and use of user certificates may
1.94 jmc 683: be specified through certificate options.
1.93 djm 684: A certificate option may disable features of the SSH session, may be
1.84 djm 685: valid only when presented from particular source addresses or may
686: force the use of a specific command.
1.93 djm 687: For a list of valid certificate options, see the documentation for the
1.84 djm 688: .Fl O
689: option above.
690: .Pp
691: Finally, certificates may be defined with a validity lifetime.
692: The
693: .Fl V
694: option allows specification of certificate start and end times.
695: A certificate that is presented at a time outside this range will not be
696: considered valid.
1.110 jmc 697: By default, certificates are valid from
698: .Ux
699: Epoch to the distant future.
1.84 djm 700: .Pp
701: For certificates to be used for user or host authentication, the CA
702: public key must be trusted by
703: .Xr sshd 8
704: or
705: .Xr ssh 1 .
706: Please refer to those manual pages for details.
1.111 djm 707: .Sh KEY REVOCATION LISTS
708: .Nm
709: is able to manage OpenSSH format Key Revocation Lists (KRLs).
710: These binary files specify keys or certificates to be revoked using a
1.112 jmc 711: compact format, taking as little a one bit per certificate if they are being
1.111 djm 712: revoked by serial number.
713: .Pp
714: KRLs may be generated using the
715: .Fl k
716: flag.
1.114 jmc 717: This option reads one or more files from the command line and generates a new
1.111 djm 718: KRL.
719: The files may either contain a KRL specification (see below) or public keys,
720: listed one per line.
721: Plain public keys are revoked by listing their hash or contents in the KRL and
722: certificates revoked by serial number or key ID (if the serial is zero or
723: not available).
724: .Pp
725: Revoking keys using a KRL specification offers explicit control over the
726: types of record used to revoke keys and may be used to directly revoke
727: certificates by serial number or key ID without having the complete original
728: certificate on hand.
729: A KRL specification consists of lines containing one of the following directives
730: followed by a colon and some directive-specific information.
731: .Bl -tag -width Ds
1.115 jmc 732: .It Cm serial : Ar serial_number Ns Op - Ns Ar serial_number
1.111 djm 733: Revokes a certificate with the specified serial number.
1.112 jmc 734: Serial numbers are 64-bit values, not including zero and may be expressed
1.111 djm 735: in decimal, hex or octal.
736: If two serial numbers are specified separated by a hyphen, then the range
737: of serial numbers including and between each is revoked.
738: The CA key must have been specified on the
739: .Nm
1.114 jmc 740: command line using the
1.111 djm 741: .Fl s
742: option.
743: .It Cm id : Ar key_id
744: Revokes a certificate with the specified key ID string.
745: The CA key must have been specified on the
746: .Nm
1.114 jmc 747: command line using the
1.111 djm 748: .Fl s
749: option.
750: .It Cm key : Ar public_key
751: Revokes the specified key.
1.112 jmc 752: If a certificate is listed, then it is revoked as a plain public key.
1.111 djm 753: .It Cm sha1 : Ar public_key
754: Revokes the specified key by its SHA1 hash.
755: .El
756: .Pp
757: KRLs may be updated using the
758: .Fl u
759: flag in addition to
760: .Fl k .
1.114 jmc 761: When this option is specified, keys listed via the command line are merged into
1.111 djm 762: the KRL, adding to those already there.
763: .Pp
764: It is also possible, given a KRL, to test whether it revokes a particular key
765: (or keys).
766: The
767: .Fl Q
768: flag will query an existing KRL, testing each key specified on the commandline.
1.114 jmc 769: If any key listed on the command line has been revoked (or an error encountered)
1.111 djm 770: then
771: .Nm
772: will exit with a non-zero exit status.
773: A zero exit status will only be returned if no key was revoked.
1.2 deraadt 774: .Sh FILES
1.100 naddy 775: .Bl -tag -width Ds -compact
1.68 djm 776: .It Pa ~/.ssh/identity
1.36 itojun 777: Contains the protocol version 1 RSA authentication identity of the user.
1.12 aaron 778: This file should not be readable by anyone but the user.
779: It is possible to
1.1 deraadt 780: specify a passphrase when generating the key; that passphrase will be
1.100 naddy 781: used to encrypt the private part of this file using 3DES.
1.12 aaron 782: This file is not automatically accessed by
1.2 deraadt 783: .Nm
1.1 deraadt 784: but it is offered as the default file for the private key.
1.46 markus 785: .Xr ssh 1
1.15 deraadt 786: will read this file when a login attempt is made.
1.100 naddy 787: .Pp
1.68 djm 788: .It Pa ~/.ssh/identity.pub
1.36 itojun 789: Contains the protocol version 1 RSA public key for authentication.
1.12 aaron 790: The contents of this file should be added to
1.68 djm 791: .Pa ~/.ssh/authorized_keys
1.2 deraadt 792: on all machines
1.49 deraadt 793: where the user wishes to log in using RSA authentication.
1.15 deraadt 794: There is no need to keep the contents of this file secret.
1.100 naddy 795: .Pp
1.68 djm 796: .It Pa ~/.ssh/id_dsa
1.100 naddy 797: .It Pa ~/.ssh/id_ecdsa
798: .It Pa ~/.ssh/id_rsa
799: Contains the protocol version 2 DSA, ECDSA or RSA authentication identity of the user.
1.15 deraadt 800: This file should not be readable by anyone but the user.
801: It is possible to
802: specify a passphrase when generating the key; that passphrase will be
1.80 dtucker 803: used to encrypt the private part of this file using 128-bit AES.
1.15 deraadt 804: This file is not automatically accessed by
805: .Nm
806: but it is offered as the default file for the private key.
1.46 markus 807: .Xr ssh 1
1.15 deraadt 808: will read this file when a login attempt is made.
1.100 naddy 809: .Pp
1.68 djm 810: .It Pa ~/.ssh/id_dsa.pub
1.100 naddy 811: .It Pa ~/.ssh/id_ecdsa.pub
1.68 djm 812: .It Pa ~/.ssh/id_rsa.pub
1.100 naddy 813: Contains the protocol version 2 DSA, ECDSA or RSA public key for authentication.
1.15 deraadt 814: The contents of this file should be added to
1.68 djm 815: .Pa ~/.ssh/authorized_keys
1.15 deraadt 816: on all machines
1.49 deraadt 817: where the user wishes to log in using public key authentication.
1.12 aaron 818: There is no need to keep the contents of this file secret.
1.100 naddy 819: .Pp
1.60 djm 820: .It Pa /etc/moduli
821: Contains Diffie-Hellman groups used for DH-GEX.
822: The file format is described in
823: .Xr moduli 5 .
1.19 aaron 824: .El
1.2 deraadt 825: .Sh SEE ALSO
826: .Xr ssh 1 ,
827: .Xr ssh-add 1 ,
1.8 ericj 828: .Xr ssh-agent 1 ,
1.60 djm 829: .Xr moduli 5 ,
1.30 itojun 830: .Xr sshd 8
1.37 markus 831: .Rs
1.73 markus 832: .%R RFC 4716
833: .%T "The Secure Shell (SSH) Public Key File Format"
834: .%D 2006
1.37 markus 835: .Re
1.59 jmc 836: .Sh AUTHORS
837: OpenSSH is a derivative of the original and free
838: ssh 1.2.12 release by Tatu Ylonen.
839: Aaron Campbell, Bob Beck, Markus Friedl, Niels Provos,
840: Theo de Raadt and Dug Song
841: removed many bugs, re-added newer features and
842: created OpenSSH.
843: Markus Friedl contributed the support for SSH
844: protocol versions 1.5 and 2.0.
![[BACK]](/icons/back.gif){kind=icon}
Return to ssh-keygen.1 CVS log ![[TXT]](/icons/text.gif){kind=icon}
![[DIR]](/icons/dir.gif){kind=icon}
Up to [local] / src / usr.bin / ssh