1.\" $OpenBSD: ssh-keygen.1,v 1.40 2001/04/23 21:57:07 markus Exp $ 2.\" 3.\" -*- nroff -*- 4.\" 5.\" Author: Tatu Ylonen <ylo@cs.hut.fi> 6.\" Copyright (c) 1995 Tatu Ylonen <ylo@cs.hut.fi>, Espoo, Finland 7.\" All rights reserved 8.\" 9.\" As far as I am concerned, the code I have written for this software 10.\" can be used freely for any purpose. Any derived versions of this 11.\" software must be clearly marked as such, and if the derived work is 12.\" incompatible with the protocol description in the RFC file, it must be 13.\" called by a name other than "ssh" or "Secure Shell". 14.\" 15.\" 16.\" Copyright (c) 1999,2000 Markus Friedl. All rights reserved. 17.\" Copyright (c) 1999 Aaron Campbell. All rights reserved. 18.\" Copyright (c) 1999 Theo de Raadt. All rights reserved. 19.\" 20.\" Redistribution and use in source and binary forms, with or without 21.\" modification, are permitted provided that the following conditions 22.\" are met: 23.\" 1. Redistributions of source code must retain the above copyright 24.\" notice, this list of conditions and the following disclaimer. 25.\" 2. Redistributions in binary form must reproduce the above copyright 26.\" notice, this list of conditions and the following disclaimer in the 27.\" documentation and/or other materials provided with the distribution. 28.\" 29.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR 30.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES 31.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. 32.\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, 33.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT 34.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, 35.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY 36.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT 37.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF 38.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 39.\" 40.Dd September 25, 1999 41.Dt SSH-KEYGEN 1 42.Os 43.Sh NAME 44.Nm ssh-keygen 45.Nd authentication key generation, management and conversion 46.Sh SYNOPSIS 47.Nm ssh-keygen 48.Op Fl q 49.Op Fl b Ar bits 50.Op Fl t Ar type 51.Op Fl N Ar new_passphrase 52.Op Fl C Ar comment 53.Op Fl f Ar output_keyfile 54.Nm ssh-keygen 55.Fl p 56.Op Fl P Ar old_passphrase 57.Op Fl N Ar new_passphrase 58.Op Fl f Ar keyfile 59.Nm ssh-keygen 60.Fl i 61.Op Fl f Ar input_keyfile 62.Nm ssh-keygen 63.Fl e 64.Op Fl f Ar input_keyfile 65.Nm ssh-keygen 66.Fl y 67.Op Fl f Ar input_keyfile 68.Nm ssh-keygen 69.Fl c 70.Op Fl P Ar passphrase 71.Op Fl C Ar comment 72.Op Fl f Ar keyfile 73.Nm ssh-keygen 74.Fl l 75.Op Fl f Ar input_keyfile 76.Nm ssh-keygen 77.Fl B 78.Op Fl f Ar input_keyfile 79.Sh DESCRIPTION 80.Nm 81generates, manages and converts authentication keys for 82.Xr ssh 1 . 83.Nm 84defaults to generating a RSA1 key for use by SSH protocol version 1. 85specifying the 86.Fl t 87option allows you to create a key for use by SSH protocol version 2. 88.Pp 89Normally each user wishing to use SSH 90with RSA or DSA authentication runs this once to create the authentication 91key in 92.Pa $HOME/.ssh/identity , 93.Pa $HOME/.ssh/id_dsa 94or 95.Pa $HOME/.ssh/id_rsa . 96Additionally, the system administrator may use this to generate host keys, 97as seen in 98.Pa /etc/rc . 99.Pp 100Normally this program generates the key and asks for a file in which 101to store the private key. 102The public key is stored in a file with the same name but 103.Dq .pub 104appended. 105The program also asks for a passphrase. 106The passphrase may be empty to indicate no passphrase 107(host keys must have an empty passphrase), or it may be a string of 108arbitrary length. 109Good passphrases are 10-30 characters long and are 110not simple sentences or otherwise easily guessable (English 111prose has only 1-2 bits of entropy per word, and provides very bad 112passphrases). 113The passphrase can be changed later by using the 114.Fl p 115option. 116.Pp 117There is no way to recover a lost passphrase. 118If the passphrase is 119lost or forgotten, you will have to generate a new key and copy the 120corresponding public key to other machines. 121.Pp 122For RSA1 keys, 123there is also a comment field in the key file that is only for 124convenience to the user to help identify the key. 125The comment can tell what the key is for, or whatever is useful. 126The comment is initialized to 127.Dq user@host 128when the key is created, but can be changed using the 129.Fl c 130option. 131.Pp 132After a key is generated, instructions below detail where the keys 133should be placed to be activated. 134.Pp 135The options are as follows: 136.Bl -tag -width Ds 137.It Fl b Ar bits 138Specifies the number of bits in the key to create. 139Minimum is 512 bits. 140Generally 1024 bits is considered sufficient, and key sizes 141above that no longer improve security but make things slower. 142The default is 1024 bits. 143.It Fl c 144Requests changing the comment in the private and public key files. 145The program will prompt for the file containing the private keys, for 146passphrase if the key has one, and for the new comment. 147.It Fl e 148This option will read a private or public OpenSSH key file and 149print the key in a 150.Sq SECSH Public Key File Format 151to stdout. 152This option allows exporting keys for use by several commercial 153SSH implementations. 154.It Fl f 155Specifies the filename of the key file. 156.It Fl i 157This option will read an unencrypted private (or public) key file 158in SSH2-compatible format and print an OpenSSH compatible private 159(or public) key to stdout. 160.Nm 161also reads the 162.Sq SECSH Public Key File Format . 163This option allows importing keys from several commercial 164SSH implementations. 165.It Fl l 166Show fingerprint of specified private or public key file. 167.It Fl p 168Requests changing the passphrase of a private key file instead of 169creating a new private key. 170The program will prompt for the file 171containing the private key, for the old passphrase, and twice for the 172new passphrase. 173.It Fl q 174Silence 175.Nm ssh-keygen . 176Used by 177.Pa /etc/rc 178when creating a new key. 179.It Fl y 180This option will read a private 181OpenSSH format file and print an OpenSSH public key to stdout. 182.It Fl t Ar type 183Specifies the type of the key to create. 184The possible values are 185.Dq rsa1 186for protocol version 1 and 187.Dq rsa 188or 189.Dq dsa 190for protocol version 2. 191The default is 192.Dq rsa1 . 193.It Fl B 194Show the bubblebabble digest of specified private or public key file. 195.It Fl C Ar comment 196Provides the new comment. 197.It Fl N Ar new_passphrase 198Provides the new passphrase. 199.It Fl P Ar passphrase 200Provides the (old) passphrase. 201.El 202.Sh FILES 203.Bl -tag -width Ds 204.It Pa $HOME/.ssh/identity 205Contains the protocol version 1 RSA authentication identity of the user. 206This file should not be readable by anyone but the user. 207It is possible to 208specify a passphrase when generating the key; that passphrase will be 209used to encrypt the private part of this file using 3DES. 210This file is not automatically accessed by 211.Nm 212but it is offered as the default file for the private key. 213.Xr sshd 8 214will read this file when a login attempt is made. 215.It Pa $HOME/.ssh/identity.pub 216Contains the protocol version 1 RSA public key for authentication. 217The contents of this file should be added to 218.Pa $HOME/.ssh/authorized_keys 219on all machines 220where you wish to log in using RSA authentication. 221There is no need to keep the contents of this file secret. 222.It Pa $HOME/.ssh/id_dsa 223Contains the protocol version 2 DSA authentication identity of the user. 224This file should not be readable by anyone but the user. 225It is possible to 226specify a passphrase when generating the key; that passphrase will be 227used to encrypt the private part of this file using 3DES. 228This file is not automatically accessed by 229.Nm 230but it is offered as the default file for the private key. 231.Xr sshd 8 232will read this file when a login attempt is made. 233.It Pa $HOME/.ssh/id_dsa.pub 234Contains the protocol version 2 DSA public key for authentication. 235The contents of this file should be added to 236.Pa $HOME/.ssh/authorized_keys2 237on all machines 238where you wish to log in using public key authentication. 239There is no need to keep the contents of this file secret. 240.It Pa $HOME/.ssh/id_rsa 241Contains the protocol version 2 RSA authentication identity of the user. 242This file should not be readable by anyone but the user. 243It is possible to 244specify a passphrase when generating the key; that passphrase will be 245used to encrypt the private part of this file using 3DES. 246This file is not automatically accessed by 247.Nm 248but it is offered as the default file for the private key. 249.Xr sshd 8 250will read this file when a login attempt is made. 251.It Pa $HOME/.ssh/id_rsa.pub 252Contains the protocol version 2 RSA public key for authentication. 253The contents of this file should be added to 254.Pa $HOME/.ssh/authorized_keys2 255on all machines 256where you wish to log in using public key authentication. 257There is no need to keep the contents of this file secret. 258.El 259.Sh AUTHORS 260OpenSSH is a derivative of the original and free 261ssh 1.2.12 release by Tatu Ylonen. 262Aaron Campbell, Bob Beck, Markus Friedl, Niels Provos, 263Theo de Raadt and Dug Song 264removed many bugs, re-added newer features and 265created OpenSSH. 266Markus Friedl contributed the support for SSH 267protocol versions 1.5 and 2.0. 268.Sh SEE ALSO 269.Xr ssh 1 , 270.Xr ssh-add 1 , 271.Xr ssh-agent 1 , 272.Xr sshd 8 273.Rs 274.%A J. Galbraith 275.%A R. Thayer 276.%T "SECSH Public Key File Format" 277.%N draft-ietf-secsh-publickeyfile-01.txt 278.%D March 2001 279.%O work in progress material 280.Re 281