Annotation of src/usr.bin/ssh/ssh-keygen.1, Revision 1.16
1.1 deraadt 1: .\" -*- nroff -*-
2: .\"
3: .\" ssh-keygen.1
4: .\"
5: .\" Author: Tatu Ylonen <ylo@cs.hut.fi>
6: .\"
7: .\" Copyright (c) 1995 Tatu Ylonen <ylo@cs.hut.fi>, Espoo, Finland
8: .\" All rights reserved
9: .\"
10: .\" Created: Sat Apr 22 23:55:14 1995 ylo
11: .\"
1.16 ! deraadt 12: .\" $Id: ssh-keygen.1,v 1.15 2000/05/02 23:33:46 deraadt Exp $
1.1 deraadt 13: .\"
1.2 deraadt 14: .Dd September 25, 1999
15: .Dt SSH-KEYGEN 1
16: .Os
17: .Sh NAME
18: .Nm ssh-keygen
19: .Nd authentication key generation
20: .Sh SYNOPSIS
21: .Nm ssh-keygen
1.15 deraadt 22: .Op Fl dq
1.2 deraadt 23: .Op Fl b Ar bits
24: .Op Fl N Ar new_passphrase
25: .Op Fl C Ar comment
1.9 markus 26: .Op Fl f Ar keyfile
1.2 deraadt 27: .Nm ssh-keygen
28: .Fl p
29: .Op Fl P Ar old_passphrase
30: .Op Fl N Ar new_passphrase
1.9 markus 31: .Op Fl f Ar keyfile
1.2 deraadt 32: .Nm ssh-keygen
1.16 ! deraadt 33: .Fl x
! 34: .Op Fl f Ar keyfile
! 35: .Nm ssh-keygen
! 36: .Fl X
! 37: .Op Fl f Ar keyfile
! 38: .Nm ssh-keygen
1.2 deraadt 39: .Fl c
40: .Op Fl P Ar passphrase
41: .Op Fl C Ar comment
1.9 markus 42: .Op Fl f Ar keyfile
43: .Nm ssh-keygen
44: .Fl l
45: .Op Fl f Ar keyfile
1.14 deraadt 46: .Nm ssh-keygen
47: .Fl R
1.13 aaron 48: .Sh DESCRIPTION
1.2 deraadt 49: .Nm
1.13 aaron 50: generates and manages authentication keys for
1.2 deraadt 51: .Xr ssh 1 .
1.15 deraadt 52: .Nm
53: defaults to generating an RSA key for use by protocols 1.3 and 1.5;
54: specifying the
55: .Fl d
56: flag will create a DSA key instead for use by protocol 2.0.
57: .Pp
1.2 deraadt 58: Normally each user wishing to use SSH
1.15 deraadt 59: with RSA or DSA authentication runs this once to create the authentication
1.1 deraadt 60: key in
1.15 deraadt 61: .Pa $HOME/.ssh/identity
62: or
63: .Pa $HOME/.ssh/id_dsa .
64: Additionally, the system administrator may use this to generate host keys,
65: as seen in
66: .Pa /etc/rc .
1.2 deraadt 67: .Pp
1.1 deraadt 68: Normally this program generates the key and asks for a file in which
1.12 aaron 69: to store the private key.
70: The public key is stored in a file with the same name but
1.2 deraadt 71: .Dq .pub
1.12 aaron 72: appended.
73: The program also asks for a passphrase.
74: The passphrase may be empty to indicate no passphrase
1.1 deraadt 75: (host keys must have empty passphrase), or it may be a string of
1.12 aaron 76: arbitrary length.
77: Good passphrases are 10-30 characters long and are
1.1 deraadt 78: not simple sentences or otherwise easily guessable (English
79: prose has only 1-2 bits of entropy per word, and provides very bad
1.12 aaron 80: passphrases).
81: The passphrase can be changed later by using the
1.2 deraadt 82: .Fl p
1.1 deraadt 83: option.
1.2 deraadt 84: .Pp
1.12 aaron 85: There is no way to recover a lost passphrase.
86: If the passphrase is
1.1 deraadt 87: lost or forgotten, you will have to generate a new key and copy the
88: corresponding public key to other machines.
1.2 deraadt 89: .Pp
1.15 deraadt 90: For RSA, there is also a comment field in the key file that is only for
1.12 aaron 91: convenience to the user to help identify the key.
92: The comment can tell what the key is for, or whatever is useful.
93: The comment is initialized to
1.2 deraadt 94: .Dq user@host
95: when the key is created, but can be changed using the
96: .Fl c
1.1 deraadt 97: option.
1.2 deraadt 98: .Pp
1.15 deraadt 99: After a key is generated, instructions below detail where the keys
100: should be placed to be activated.
101: .Pp
1.2 deraadt 102: The options are as follows:
103: .Bl -tag -width Ds
104: .It Fl b Ar bits
1.12 aaron 105: Specifies the number of bits in the key to create.
106: Minimum is 512 bits.
107: Generally 1024 bits is considered sufficient, and key sizes
108: above that no longer improve security but make things slower.
109: The default is 1024 bits.
1.2 deraadt 110: .It Fl c
1.1 deraadt 111: Requests changing the comment in the private and public key files.
112: The program will prompt for the file containing the private keys, for
113: passphrase if the key has one, and for the new comment.
1.9 markus 114: .It Fl f
115: Specifies the filename of the key file.
116: .It Fl l
117: Show fingerprint of specified private or public key file.
1.2 deraadt 118: .It Fl p
1.1 deraadt 119: Requests changing the passphrase of a private key file instead of
1.12 aaron 120: creating a new private key.
121: The program will prompt for the file
1.1 deraadt 122: containing the private key, for the old passphrase, and twice for the
123: new passphrase.
1.5 aaron 124: .It Fl q
125: Silence
126: .Nm ssh-keygen .
127: Used by
128: .Pa /etc/rc
129: when creating a new key.
1.2 deraadt 130: .It Fl C Ar comment
1.1 deraadt 131: Provides the new comment.
1.2 deraadt 132: .It Fl N Ar new_passphrase
1.1 deraadt 133: Provides the new passphrase.
1.2 deraadt 134: .It Fl P Ar passphrase
1.1 deraadt 135: Provides the (old) passphrase.
1.14 deraadt 136: .It Fl R
137: If RSA support is functional, immediately exits with code 0. If RSA
138: support is not functional, exits with code 1. This flag will be
139: removed once the RSA patent expires.
1.16 ! deraadt 140: .It Fl x
! 141: This option will read a
! 142: OpenSSH DSA format file and prints to stdout a SSH2-compatible key.
! 143: .It Fl X
! 144: This option will read a
! 145: SSH2-compatible key file and print to stdout an OpenSSH DSA compatible key.
1.2 deraadt 146: .El
147: .Sh FILES
148: .Bl -tag -width Ds
149: .It Pa $HOME/.ssh/identity
1.12 aaron 150: Contains the RSA authentication identity of the user.
151: This file should not be readable by anyone but the user.
152: It is possible to
1.1 deraadt 153: specify a passphrase when generating the key; that passphrase will be
1.12 aaron 154: used to encrypt the private part of this file using 3DES.
155: This file is not automatically accessed by
1.2 deraadt 156: .Nm
1.1 deraadt 157: but it is offered as the default file for the private key.
1.15 deraadt 158: .Xr sshd 8
159: will read this file when a login attempt is made.
1.2 deraadt 160: .It Pa $HOME/.ssh/identity.pub
1.12 aaron 161: Contains the public key for authentication.
162: The contents of this file should be added to
1.2 deraadt 163: .Pa $HOME/.ssh/authorized_keys
164: on all machines
1.12 aaron 165: where you wish to log in using RSA authentication.
1.15 deraadt 166: There is no need to keep the contents of this file secret.
167: .It Pa $HOME/.ssh/id_dsa
168: Contains the DSA authentication identity of the user.
169: This file should not be readable by anyone but the user.
170: It is possible to
171: specify a passphrase when generating the key; that passphrase will be
172: used to encrypt the private part of this file using 3DES.
173: This file is not automatically accessed by
174: .Nm
175: but it is offered as the default file for the private key.
176: .Xr sshd 8
177: will read this file when a login attempt is made.
178: .It Pa $HOME/.ssh/id_dsa.pub
179: Contains the public key for authentication.
180: The contents of this file should be added to
181: .Pa $HOME/.ssh/authorized_keys2
182: on all machines
183: where you wish to log in using DSA authentication.
1.12 aaron 184: There is no need to keep the contents of this file secret.
1.2 deraadt 185: .Sh AUTHOR
1.1 deraadt 186: Tatu Ylonen <ylo@cs.hut.fi>
1.4 deraadt 187: .Pp
1.6 deraadt 188: OpenSSH
189: is a derivative of the original (free) ssh 1.2.12 release, but with bugs
1.12 aaron 190: removed and newer features re-added.
191: Rapidly after the 1.2.12 release,
192: newer versions bore successively more restrictive licenses.
193: This version of OpenSSH
1.6 deraadt 194: .Bl -bullet
195: .It
1.11 aaron 196: has all components of a restrictive nature (i.e., patents, see
1.6 deraadt 197: .Xr ssl 8 )
198: directly removed from the source code; any licensed or patented components
199: are chosen from
200: external libraries.
201: .It
202: has been updated to support ssh protocol 1.5.
203: .It
1.13 aaron 204: contains added support for
1.6 deraadt 205: .Xr kerberos 8
206: authentication and ticket passing.
207: .It
208: supports one-time password authentication with
209: .Xr skey 1 .
210: .El
211: .Pp
212: The libraries described in
1.4 deraadt 213: .Xr ssl 8
214: are required for proper operation.
1.2 deraadt 215: .Sh SEE ALSO
216: .Xr ssh 1 ,
217: .Xr ssh-add 1 ,
1.8 ericj 218: .Xr ssh-agent 1 ,
1.4 deraadt 219: .Xr sshd 8 ,
220: .Xr ssl 8