1 SSH-KEYGEN(1) OpenBSD Reference Manual SSH-KEYGEN(1) 2 3 NAME 4 ssh-keygen - authentication key generation, management and conversion 5 6 SYNOPSIS 7 ssh-keygen [-q] [-b bits] -t type [-N new_passphrase] [-C comment] 8 [-f output_keyfile] 9 ssh-keygen -p [-P old_passphrase] [-N new_passphrase] [-f keyfile] 10 ssh-keygen -i [-m key_format] [-f input_keyfile] 11 ssh-keygen -e [-m key_format] [-f input_keyfile] 12 ssh-keygen -y [-f input_keyfile] 13 ssh-keygen -c [-P passphrase] [-C comment] [-f keyfile] 14 ssh-keygen -l [-f input_keyfile] 15 ssh-keygen -B [-f input_keyfile] 16 ssh-keygen -D pkcs11 17 ssh-keygen -F hostname [-f known_hosts_file] [-l] 18 ssh-keygen -H [-f known_hosts_file] 19 ssh-keygen -R hostname [-f known_hosts_file] 20 ssh-keygen -r hostname [-f input_keyfile] [-g] 21 ssh-keygen -G output_file [-v] [-b bits] [-M memory] [-S start_point] 22 ssh-keygen -T output_file -f input_file [-v] [-a num_trials] 23 [-W generator] 24 ssh-keygen -s ca_key -I certificate_identity [-h] [-n principals] 25 [-O option] [-V validity_interval] [-z serial_number] file ... 26 ssh-keygen -L [-f input_keyfile] 27 ssh-keygen -A 28 29 DESCRIPTION 30 ssh-keygen generates, manages and converts authentication keys for 31 ssh(1). ssh-keygen can create RSA keys for use by SSH protocol version 1 32 and DSA, ECDSA or RSA keys for use by SSH protocol version 2. The type 33 of key to be generated is specified with the -t option. If invoked 34 without any arguments, ssh-keygen will generate an RSA key for use in SSH 35 protocol 2 connections. 36 37 ssh-keygen is also used to generate groups for use in Diffie-Hellman 38 group exchange (DH-GEX). See the MODULI GENERATION section for details. 39 40 Normally each user wishing to use SSH with public key authentication runs 41 this once to create the authentication key in ~/.ssh/identity, 42 ~/.ssh/id_ecdsa, ~/.ssh/id_dsa or ~/.ssh/id_rsa. Additionally, the 43 system administrator may use this to generate host keys, as seen in 44 /etc/rc. 45 46 Normally this program generates the key and asks for a file in which to 47 store the private key. The public key is stored in a file with the same 48 name but ``.pub'' appended. The program also asks for a passphrase. The 49 passphrase may be empty to indicate no passphrase (host keys must have an 50 empty passphrase), or it may be a string of arbitrary length. A 51 passphrase is similar to a password, except it can be a phrase with a 52 series of words, punctuation, numbers, whitespace, or any string of 53 characters you want. Good passphrases are 10-30 characters long, are not 54 simple sentences or otherwise easily guessable (English prose has only 1- 55 2 bits of entropy per character, and provides very bad passphrases), and 56 contain a mix of upper and lowercase letters, numbers, and non- 57 alphanumeric characters. The passphrase can be changed later by using 58 the -p option. 59 60 There is no way to recover a lost passphrase. If the passphrase is lost 61 or forgotten, a new key must be generated and the corresponding public 62 key copied to other machines. 63 64 For RSA1 keys, there is also a comment field in the key file that is only 65 for convenience to the user to help identify the key. The comment can 66 tell what the key is for, or whatever is useful. The comment is 67 initialized to ``user@host'' when the key is created, but can be changed 68 using the -c option. 69 70 After a key is generated, instructions below detail where the keys should 71 be placed to be activated. 72 73 The options are as follows: 74 75 -A For each of the key types (rsa1, rsa, dsa and ecdsa) for which 76 host keys do not exist, generate the host keys with the default 77 key file path, an empty passphrase, default bits for the key 78 type, and default comment. This is used by /etc/rc to generate 79 new host keys. 80 81 -a trials 82 Specifies the number of primality tests to perform when screening 83 DH-GEX candidates using the -T command. 84 85 -B Show the bubblebabble digest of specified private or public key 86 file. 87 88 -b bits 89 Specifies the number of bits in the key to create. For RSA keys, 90 the minimum size is 768 bits and the default is 2048 bits. 91 Generally, 2048 bits is considered sufficient. DSA keys must be 92 exactly 1024 bits as specified by FIPS 186-2. For ECDSA keys, 93 the -b flag determines they key length by selecting from one of 94 three elliptic curve sizes: 256, 384 or 521 bits. Attempting to 95 use bit lengths other than these three values for ECDSA keys will 96 fail. 97 98 -C comment 99 Provides a new comment. 100 101 -c Requests changing the comment in the private and public key 102 files. This operation is only supported for RSA1 keys. The 103 program will prompt for the file containing the private keys, for 104 the passphrase if the key has one, and for the new comment. 105 106 -D pkcs11 107 Download the RSA public keys provided by the PKCS#11 shared 108 library pkcs11. When used in combination with -s, this option 109 indicates that a CA key resides in a PKCS#11 token (see the 110 CERTIFICATES section for details). 111 112 -e This option will read a private or public OpenSSH key file and 113 print to stdout the key in one of the formats specified by the -m 114 option. The default export format is ``RFC4716''. This option 115 allows exporting OpenSSH keys for use by other programs, 116 including several commercial SSH implementations. 117 118 -F hostname 119 Search for the specified hostname in a known_hosts file, listing 120 any occurrences found. This option is useful to find hashed host 121 names or addresses and may also be used in conjunction with the 122 -H option to print found keys in a hashed format. 123 124 -f filename 125 Specifies the filename of the key file. 126 127 -G output_file 128 Generate candidate primes for DH-GEX. These primes must be 129 screened for safety (using the -T option) before use. 130 131 -g Use generic DNS format when printing fingerprint resource records 132 using the -r command. 133 134 -H Hash a known_hosts file. This replaces all hostnames and 135 addresses with hashed representations within the specified file; 136 the original content is moved to a file with a .old suffix. 137 These hashes may be used normally by ssh and sshd, but they do 138 not reveal identifying information should the file's contents be 139 disclosed. This option will not modify existing hashed hostnames 140 and is therefore safe to use on files that mix hashed and non- 141 hashed names. 142 143 -h When signing a key, create a host certificate instead of a user 144 certificate. Please see the CERTIFICATES section for details. 145 146 -I certificate_identity 147 Specify the key identity when signing a public key. Please see 148 the CERTIFICATES section for details. 149 150 -i This option will read an unencrypted private (or public) key file 151 in the format specified by the -m option and print an OpenSSH 152 compatible private (or public) key to stdout. This option allows 153 importing keys from other software, including several commercial 154 SSH implementations. The default import format is ``RFC4716''. 155 156 -L Prints the contents of a certificate. 157 158 -l Show fingerprint of specified public key file. Private RSA1 keys 159 are also supported. For RSA and DSA keys ssh-keygen tries to 160 find the matching public key file and prints its fingerprint. If 161 combined with -v, an ASCII art representation of the key is 162 supplied with the fingerprint. 163 164 -M memory 165 Specify the amount of memory to use (in megabytes) when 166 generating candidate moduli for DH-GEX. 167 168 -m key_format 169 Specify a key format for the -i (import) or -e (export) 170 conversion options. The supported key formats are: ``RFC4716'' 171 (RFC 4716/SSH2 public or private key), ``PKCS8'' (PEM PKCS8 172 public key) or ``PEM'' (PEM public key). The default conversion 173 format is ``RFC4716''. 174 175 -N new_passphrase 176 Provides the new passphrase. 177 178 -n principals 179 Specify one or more principals (user or host names) to be 180 included in a certificate when signing a key. Multiple 181 principals may be specified, separated by commas. Please see the 182 CERTIFICATES section for details. 183 184 -O option 185 Specify a certificate option when signing a key. This option may 186 be specified multiple times. Please see the CERTIFICATES section 187 for details. The options that are valid for user certificates 188 are: 189 190 clear Clear all enabled permissions. This is useful for 191 clearing the default set of permissions so permissions 192 may be added individually. 193 194 force-command=command 195 Forces the execution of command instead of any shell or 196 command specified by the user when the certificate is 197 used for authentication. 198 199 no-agent-forwarding 200 Disable ssh-agent(1) forwarding (permitted by default). 201 202 no-port-forwarding 203 Disable port forwarding (permitted by default). 204 205 no-pty Disable PTY allocation (permitted by default). 206 207 no-user-rc 208 Disable execution of ~/.ssh/rc by sshd(8) (permitted by 209 default). 210 211 no-x11-forwarding 212 Disable X11 forwarding (permitted by default). 213 214 permit-agent-forwarding 215 Allows ssh-agent(1) forwarding. 216 217 permit-port-forwarding 218 Allows port forwarding. 219 220 permit-pty 221 Allows PTY allocation. 222 223 permit-user-rc 224 Allows execution of ~/.ssh/rc by sshd(8). 225 226 permit-x11-forwarding 227 Allows X11 forwarding. 228 229 source-address=address_list 230 Restrict the source addresses from which the certificate 231 is considered valid. The address_list is a comma- 232 separated list of one or more address/netmask pairs in 233 CIDR format. 234 235 At present, no options are valid for host keys. 236 237 -P passphrase 238 Provides the (old) passphrase. 239 240 -p Requests changing the passphrase of a private key file instead of 241 creating a new private key. The program will prompt for the file 242 containing the private key, for the old passphrase, and twice for 243 the new passphrase. 244 245 -q Silence ssh-keygen. 246 247 -R hostname 248 Removes all keys belonging to hostname from a known_hosts file. 249 This option is useful to delete hashed hosts (see the -H option 250 above). 251 252 -r hostname 253 Print the SSHFP fingerprint resource record named hostname for 254 the specified public key file. 255 256 -S start 257 Specify start point (in hex) when generating candidate moduli for 258 DH-GEX. 259 260 -s ca_key 261 Certify (sign) a public key using the specified CA key. Please 262 see the CERTIFICATES section for details. 263 264 -T output_file 265 Test DH group exchange candidate primes (generated using the -G 266 option) for safety. 267 268 -t type 269 Specifies the type of key to create. The possible values are 270 ``rsa1'' for protocol version 1 and ``dsa'', ``ecdsa'' or ``rsa'' 271 for protocol version 2. 272 273 -V validity_interval 274 Specify a validity interval when signing a certificate. A 275 validity interval may consist of a single time, indicating that 276 the certificate is valid beginning now and expiring at that time, 277 or may consist of two times separated by a colon to indicate an 278 explicit time interval. The start time may be specified as a 279 date in YYYYMMDD format, a time in YYYYMMDDHHMMSS format or a 280 relative time (to the current time) consisting of a minus sign 281 followed by a relative time in the format described in the TIME 282 FORMATS section of sshd_config(5). The end time may be specified 283 as a YYYYMMDD date, a YYYYMMDDHHMMSS time or a relative time 284 starting with a plus character. 285 286 For example: ``+52w1d'' (valid from now to 52 weeks and one day 287 from now), ``-4w:+4w'' (valid from four weeks ago to four weeks 288 from now), ``20100101123000:20110101123000'' (valid from 12:30 289 PM, January 1st, 2010 to 12:30 PM, January 1st, 2011), 290 ``-1d:20110101'' (valid from yesterday to midnight, January 1st, 291 2011). 292 293 -v Verbose mode. Causes ssh-keygen to print debugging messages 294 about its progress. This is helpful for debugging moduli 295 generation. Multiple -v options increase the verbosity. The 296 maximum is 3. 297 298 -W generator 299 Specify desired generator when testing candidate moduli for DH- 300 GEX. 301 302 -y This option will read a private OpenSSH format file and print an 303 OpenSSH public key to stdout. 304 305 -z serial_number 306 Specifies a serial number to be embedded in the certificate to 307 distinguish this certificate from others from the same CA. The 308 default serial number is zero. 309 310 MODULI GENERATION 311 ssh-keygen may be used to generate groups for the Diffie-Hellman Group 312 Exchange (DH-GEX) protocol. Generating these groups is a two-step 313 process: first, candidate primes are generated using a fast, but memory 314 intensive process. These candidate primes are then tested for 315 suitability (a CPU-intensive process). 316 317 Generation of primes is performed using the -G option. The desired 318 length of the primes may be specified by the -b option. For example: 319 320 # ssh-keygen -G moduli-2048.candidates -b 2048 321 322 By default, the search for primes begins at a random point in the desired 323 length range. This may be overridden using the -S option, which 324 specifies a different start point (in hex). 325 326 Once a set of candidates have been generated, they must be tested for 327 suitability. This may be performed using the -T option. In this mode 328 ssh-keygen will read candidates from standard input (or a file specified 329 using the -f option). For example: 330 331 # ssh-keygen -T moduli-2048 -f moduli-2048.candidates 332 333 By default, each candidate will be subjected to 100 primality tests. 334 This may be overridden using the -a option. The DH generator value will 335 be chosen automatically for the prime under consideration. If a specific 336 generator is desired, it may be requested using the -W option. Valid 337 generator values are 2, 3, and 5. 338 339 Screened DH groups may be installed in /etc/moduli. It is important that 340 this file contains moduli of a range of bit lengths and that both ends of 341 a connection share common moduli. 342 343 CERTIFICATES 344 ssh-keygen supports signing of keys to produce certificates that may be 345 used for user or host authentication. Certificates consist of a public 346 key, some identity information, zero or more principal (user or host) 347 names and a set of options that are signed by a Certification Authority 348 (CA) key. Clients or servers may then trust only the CA key and verify 349 its signature on a certificate rather than trusting many user/host keys. 350 Note that OpenSSH certificates are a different, and much simpler, format 351 to the X.509 certificates used in ssl(8). 352 353 ssh-keygen supports two types of certificates: user and host. User 354 certificates authenticate users to servers, whereas host certificates 355 authenticate server hosts to users. To generate a user certificate: 356 357 $ ssh-keygen -s /path/to/ca_key -I key_id /path/to/user_key.pub 358 359 The resultant certificate will be placed in /path/to/user_key-cert.pub. 360 A host certificate requires the -h option: 361 362 $ ssh-keygen -s /path/to/ca_key -I key_id -h /path/to/host_key.pub 363 364 The host certificate will be output to /path/to/host_key-cert.pub. 365 366 It is possible to sign using a CA key stored in a PKCS#11 token by 367 providing the token library using -D and identifying the CA key by 368 providing its public half as an argument to -s: 369 370 $ ssh-keygen -s ca_key.pub -D libpkcs11.so -I key_id host_key.pub 371 372 In all cases, key_id is a "key identifier" that is logged by the server 373 when the certificate is used for authentication. 374 375 Certificates may be limited to be valid for a set of principal 376 (user/host) names. By default, generated certificates are valid for all 377 users or hosts. To generate a certificate for a specified set of 378 principals: 379 380 $ ssh-keygen -s ca_key -I key_id -n user1,user2 user_key.pub 381 $ ssh-keygen -s ca_key -I key_id -h -n host.domain user_key.pub 382 383 Additional limitations on the validity and use of user certificates may 384 be specified through certificate options. A certificate option may 385 disable features of the SSH session, may be valid only when presented 386 from particular source addresses or may force the use of a specific 387 command. For a list of valid certificate options, see the documentation 388 for the -O option above. 389 390 Finally, certificates may be defined with a validity lifetime. The -V 391 option allows specification of certificate start and end times. A 392 certificate that is presented at a time outside this range will not be 393 considered valid. By default, certificates have a maximum validity 394 interval. 395 396 For certificates to be used for user or host authentication, the CA 397 public key must be trusted by sshd(8) or ssh(1). Please refer to those 398 manual pages for details. 399 400 FILES 401 ~/.ssh/identity 402 Contains the protocol version 1 RSA authentication identity of 403 the user. This file should not be readable by anyone but the 404 user. It is possible to specify a passphrase when generating the 405 key; that passphrase will be used to encrypt the private part of 406 this file using 3DES. This file is not automatically accessed by 407 ssh-keygen but it is offered as the default file for the private 408 key. ssh(1) will read this file when a login attempt is made. 409 410 ~/.ssh/identity.pub 411 Contains the protocol version 1 RSA public key for 412 authentication. The contents of this file should be added to 413 ~/.ssh/authorized_keys on all machines where the user wishes to 414 log in using RSA authentication. There is no need to keep the 415 contents of this file secret. 416 417 ~/.ssh/id_dsa 418 ~/.ssh/id_ecdsa 419 ~/.ssh/id_rsa 420 Contains the protocol version 2 DSA, ECDSA or RSA authentication 421 identity of the user. This file should not be readable by anyone 422 but the user. It is possible to specify a passphrase when 423 generating the key; that passphrase will be used to encrypt the 424 private part of this file using 128-bit AES. This file is not 425 automatically accessed by ssh-keygen but it is offered as the 426 default file for the private key. ssh(1) will read this file 427 when a login attempt is made. 428 429 ~/.ssh/id_dsa.pub 430 ~/.ssh/id_ecdsa.pub 431 ~/.ssh/id_rsa.pub 432 Contains the protocol version 2 DSA, ECDSA or RSA public key for 433 authentication. The contents of this file should be added to 434 ~/.ssh/authorized_keys on all machines where the user wishes to 435 log in using public key authentication. There is no need to keep 436 the contents of this file secret. 437 438 /etc/moduli 439 Contains Diffie-Hellman groups used for DH-GEX. The file format 440 is described in moduli(5). 441 442 SEE ALSO 443 ssh(1), ssh-add(1), ssh-agent(1), moduli(5), sshd(8) 444 445 The Secure Shell (SSH) Public Key File Format, RFC 4716, 2006. 446 447 AUTHORS 448 OpenSSH is a derivative of the original and free ssh 1.2.12 release by 449 Tatu Ylonen. Aaron Campbell, Bob Beck, Markus Friedl, Niels Provos, Theo 450 de Raadt and Dug Song removed many bugs, re-added newer features and 451 created OpenSSH. Markus Friedl contributed the support for SSH protocol 452 versions 1.5 and 2.0. 453 454 OpenBSD 5.0 April 13, 2011 OpenBSD 5.0 455
