ssh-keygen.1

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