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