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