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