1.\" $OpenBSD: ssh-keygen.1,v 1.53 2002/02/16 14:53:37 stevesk 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.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.Nm ssh-keygen 80.Fl D Ar reader 81.Nm ssh-keygen 82.Fl U Ar reader 83.Op Fl f Ar input_keyfile 84.Sh DESCRIPTION 85.Nm 86generates, manages and converts authentication keys for 87.Xr ssh 1 . 88.Nm 89can create RSA keys for use by SSH protocol version 1 and RSA or DSA 90keys for use by SSH protocol version 2. The type of key to be generated 91is specified with the 92.Fl t 93option. 94.Pp 95Normally each user wishing to use SSH 96with RSA or DSA authentication runs this once to create the authentication 97key in 98.Pa $HOME/.ssh/identity , 99.Pa $HOME/.ssh/id_dsa 100or 101.Pa $HOME/.ssh/id_rsa . 102Additionally, the system administrator may use this to generate host keys, 103as seen in 104.Pa /etc/rc . 105.Pp 106Normally this program generates the key and asks for a file in which 107to store the private key. 108The public key is stored in a file with the same name but 109.Dq .pub 110appended. 111The program also asks for a passphrase. 112The passphrase may be empty to indicate no passphrase 113(host keys must have an empty passphrase), or it may be a string of 114arbitrary length. 115A passphrase is similar to a password, except it can be a phrase with a 116series of words, punctuation, numbers, whitespace, or any string of 117characters you want. 118Good passphrases are 10-30 characters long, are 119not simple sentences or otherwise easily guessable (English 120prose has only 1-2 bits of entropy per character, and provides very bad 121passphrases), and contain a mix of upper and lowercase letters, 122numbers, and non-alphanumeric characters. 123The passphrase can be changed later by using the 124.Fl p 125option. 126.Pp 127There is no way to recover a lost passphrase. 128If the passphrase is 129lost or forgotten, a new key must be generated and copied to the 130corresponding public key to other machines. 131.Pp 132For RSA1 keys, 133there is also a comment field in the key file that is only for 134convenience to the user to help identify the key. 135The comment can tell what the key is for, or whatever is useful. 136The comment is initialized to 137.Dq user@host 138when the key is created, but can be changed using the 139.Fl c 140option. 141.Pp 142After a key is generated, instructions below detail where the keys 143should be placed to be activated. 144.Pp 145The options are as follows: 146.Bl -tag -width Ds 147.It Fl b Ar bits 148Specifies the number of bits in the key to create. 149Minimum is 512 bits. 150Generally 1024 bits is considered sufficient, and key sizes 151above that no longer improve security but make things slower. 152The default is 1024 bits. 153.It Fl c 154Requests changing the comment in the private and public key files. 155This operation is only supported for RSA1 keys. 156The program will prompt for the file containing the private keys, for 157the passphrase if the key has one, and for the new comment. 158.It Fl e 159This option will read a private or public OpenSSH key file and 160print the key in a 161.Sq SECSH Public Key File Format 162to stdout. 163This option allows exporting keys for use by several commercial 164SSH implementations. 165.It Fl f Ar filename 166Specifies the filename of the key file. 167.It Fl i 168This option will read an unencrypted private (or public) key file 169in SSH2-compatible format and print an OpenSSH compatible private 170(or public) key to stdout. 171.Nm 172also reads the 173.Sq SECSH Public Key File Format . 174This option allows importing keys from several commercial 175SSH implementations. 176.It Fl l 177Show fingerprint of specified public key file. 178Private RSA1 keys are also supported. 179For RSA and DSA keys 180.Nm 181tries to find the matching public key file and prints its fingerprint. 182.It Fl p 183Requests changing the passphrase of a private key file instead of 184creating a new private key. 185The program will prompt for the file 186containing the private key, for the old passphrase, and twice for the 187new passphrase. 188.It Fl q 189Silence 190.Nm ssh-keygen . 191Used by 192.Pa /etc/rc 193when creating a new key. 194.It Fl y 195This option will read a private 196OpenSSH format file and print an OpenSSH public key to stdout. 197.It Fl t Ar type 198Specifies the type of the key to create. 199The possible values are 200.Dq rsa1 201for protocol version 1 and 202.Dq rsa 203or 204.Dq dsa 205for protocol version 2. 206.It Fl B 207Show the bubblebabble digest of specified private or public key file. 208.It Fl C Ar comment 209Provides the new comment. 210.It Fl D Ar reader 211Download the RSA public key stored in the smartcard in 212.Ar reader . 213.It Fl N Ar new_passphrase 214Provides the new passphrase. 215.It Fl P Ar passphrase 216Provides the (old) passphrase. 217.It Fl U Ar reader 218Upload an existing RSA private key into the smartcard in 219.Ar reader . 220.El 221.Sh FILES 222.Bl -tag -width Ds 223.It Pa $HOME/.ssh/identity 224Contains the protocol version 1 RSA authentication identity of the user. 225This file should not be readable by anyone but the user. 226It is possible to 227specify a passphrase when generating the key; that passphrase will be 228used to encrypt the private part of this file using 3DES. 229This file is not automatically accessed by 230.Nm 231but it is offered as the default file for the private key. 232.Xr ssh 1 233will read this file when a login attempt is made. 234.It Pa $HOME/.ssh/identity.pub 235Contains the protocol version 1 RSA public key for authentication. 236The contents of this file should be added to 237.Pa $HOME/.ssh/authorized_keys 238on all machines 239where the user wishes to log in using RSA authentication. 240There is no need to keep the contents of this file secret. 241.It Pa $HOME/.ssh/id_dsa 242Contains the protocol version 2 DSA authentication identity of the user. 243This file should not be readable by anyone but the user. 244It is possible to 245specify a passphrase when generating the key; that passphrase will be 246used to encrypt the private part of this file using 3DES. 247This file is not automatically accessed by 248.Nm 249but it is offered as the default file for the private key. 250.Xr ssh 1 251will read this file when a login attempt is made. 252.It Pa $HOME/.ssh/id_dsa.pub 253Contains the protocol version 2 DSA public key for authentication. 254The contents of this file should be added to 255.Pa $HOME/.ssh/authorized_keys 256on all machines 257where the user wishes to log in using public key authentication. 258There is no need to keep the contents of this file secret. 259.It Pa $HOME/.ssh/id_rsa 260Contains the protocol version 2 RSA authentication identity of the user. 261This file should not be readable by anyone but the user. 262It is possible to 263specify a passphrase when generating the key; that passphrase will be 264used to encrypt the private part of this file using 3DES. 265This file is not automatically accessed by 266.Nm 267but it is offered as the default file for the private key. 268.Xr ssh 1 269will read this file when a login attempt is made. 270.It Pa $HOME/.ssh/id_rsa.pub 271Contains the protocol version 2 RSA public key for authentication. 272The contents of this file should be added to 273.Pa $HOME/.ssh/authorized_keys 274on all machines 275where the user wishes to log in using public key authentication. 276There is no need to keep the contents of this file secret. 277.El 278.Sh AUTHORS 279OpenSSH is a derivative of the original and free 280ssh 1.2.12 release by Tatu Ylonen. 281Aaron Campbell, Bob Beck, Markus Friedl, Niels Provos, 282Theo de Raadt and Dug Song 283removed many bugs, re-added newer features and 284created OpenSSH. 285Markus Friedl contributed the support for SSH 286protocol versions 1.5 and 2.0. 287.Sh SEE ALSO 288.Xr ssh 1 , 289.Xr ssh-add 1 , 290.Xr ssh-agent 1 , 291.Xr sshd 8 292.Rs 293.%A J. Galbraith 294.%A R. Thayer 295.%T "SECSH Public Key File Format" 296.%N draft-ietf-secsh-publickeyfile-01.txt 297.%D March 2001 298.%O work in progress material 299.Re 300