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