ssh-keygen.0 revision 239844
11541SrgrimesSSH-KEYGEN(1) OpenBSD Reference Manual SSH-KEYGEN(1) 21541Srgrimes 31541SrgrimesNAME 41541Srgrimes ssh-keygen - authentication key generation, management and conversion 51541Srgrimes 61541SrgrimesSYNOPSIS 71541Srgrimes ssh-keygen [-q] [-b bits] -t type [-N new_passphrase] [-C comment] 81541Srgrimes [-f output_keyfile] 91541Srgrimes ssh-keygen -p [-P old_passphrase] [-N new_passphrase] [-f keyfile] 101541Srgrimes ssh-keygen -i [-m key_format] [-f input_keyfile] 111541Srgrimes ssh-keygen -e [-m key_format] [-f input_keyfile] 121541Srgrimes ssh-keygen -y [-f input_keyfile] 131541Srgrimes ssh-keygen -c [-P passphrase] [-C comment] [-f keyfile] 141541Srgrimes ssh-keygen -l [-f input_keyfile] 151541Srgrimes ssh-keygen -B [-f input_keyfile] 161541Srgrimes ssh-keygen -D pkcs11 171541Srgrimes ssh-keygen -F hostname [-f known_hosts_file] [-l] 181541Srgrimes ssh-keygen -H [-f known_hosts_file] 191541Srgrimes ssh-keygen -R hostname [-f known_hosts_file] 201541Srgrimes ssh-keygen -r hostname [-f input_keyfile] [-g] 211541Srgrimes ssh-keygen -G output_file [-v] [-b bits] [-M memory] [-S start_point] 221541Srgrimes ssh-keygen -T output_file -f input_file [-v] [-a num_trials] [-K checkpt] 231541Srgrimes [-W generator] 241541Srgrimes ssh-keygen -s ca_key -I certificate_identity [-h] [-n principals] 251541Srgrimes [-O option] [-V validity_interval] [-z serial_number] file ... 261541Srgrimes ssh-keygen -L [-f input_keyfile] 271541Srgrimes ssh-keygen -A 281541Srgrimes 291541SrgrimesDESCRIPTION 301541Srgrimes ssh-keygen generates, manages and converts authentication keys for 311541Srgrimes ssh(1). ssh-keygen can create RSA keys for use by SSH protocol version 1 321541Srgrimes and DSA, ECDSA or RSA keys for use by SSH protocol version 2. The type 331541Srgrimes of key to be generated is specified with the -t option. If invoked 3450477Speter without any arguments, ssh-keygen will generate an RSA key for use in SSH 351541Srgrimes protocol 2 connections. 361541Srgrimes 372168Spaul ssh-keygen is also used to generate groups for use in Diffie-Hellman 384507Sbde group exchange (DH-GEX). See the MODULI GENERATION section for details. 392168Spaul 4097024Siedowse Normally each user wishing to use SSH with public key authentication runs 4179103Sbrooks this once to create the authentication key in ~/.ssh/identity, 4297024Siedowse ~/.ssh/id_ecdsa, ~/.ssh/id_dsa or ~/.ssh/id_rsa. Additionally, the 4379103Sbrooks system administrator may use this to generate host keys, as seen in 441541Srgrimes /etc/rc. 4534750Speter 4672093Sasmodai Normally this program generates the key and asks for a file in which to 4734750Speter store the private key. The public key is stored in a file with the same 4855205Speter name but ``.pub'' appended. The program also asks for a passphrase. The 4934750Speter passphrase may be empty to indicate no passphrase (host keys must have an 5034750Speter empty passphrase), or it may be a string of arbitrary length. A 5134750Speter passphrase is similar to a password, except it can be a phrase with a 5279103Sbrooks series of words, punctuation, numbers, whitespace, or any string of 5379103Sbrooks characters you want. Good passphrases are 10-30 characters long, are not 5434750Speter simple sentences or otherwise easily guessable (English prose has only 5579103Sbrooks 1-2 bits of entropy per character, and provides very bad passphrases), 5679103Sbrooks and contain a mix of upper and lowercase letters, numbers, and non- 5779103Sbrooks alphanumeric characters. The passphrase can be changed later by using 5879103Sbrooks the -p option. 5979103Sbrooks 6092081Smux There is no way to recover a lost passphrase. If the passphrase is lost 6179103Sbrooks or forgotten, a new key must be generated and the corresponding public 6297024Siedowse key copied to other machines. 6379103Sbrooks 6479103Sbrooks For RSA1 keys, there is also a comment field in the key file that is only 6579103Sbrooks for convenience to the user to help identify the key. The comment can 6679103Sbrooks tell what the key is for, or whatever is useful. The comment is 6779103Sbrooks initialized to ``user@host'' when the key is created, but can be changed 6879103Sbrooks using the -c option. 6979103Sbrooks 7097289Sbrooks After a key is generated, instructions below detail where the keys should 7192081Smux be placed to be activated. 7292081Smux 7392081Smux The options are as follows: 7479103Sbrooks 7592081Smux -A For each of the key types (rsa1, rsa, dsa and ecdsa) for which 7697289Sbrooks host keys do not exist, generate the host keys with the default 7779103Sbrooks key file path, an empty passphrase, default bits for the key 7879103Sbrooks type, and default comment. This is used by /etc/rc to generate 7997289Sbrooks new host keys. 8097289Sbrooks 8197024Siedowse -a trials 8279103Sbrooks Specifies the number of primality tests to perform when screening 8379103Sbrooks DH-GEX candidates using the -T command. 8479103Sbrooks 8579103Sbrooks -B Show the bubblebabble digest of specified private or public key 8679103Sbrooks file. 8779103Sbrooks 8879103Sbrooks -b bits 8979103Sbrooks Specifies the number of bits in the key to create. For RSA keys, 9079103Sbrooks the minimum size is 768 bits and the default is 2048 bits. 9179103Sbrooks Generally, 2048 bits is considered sufficient. DSA keys must be 9279103Sbrooks exactly 1024 bits as specified by FIPS 186-2. For ECDSA keys, 9379103Sbrooks the -b flag determines the key length by selecting from one of 9419079Sfenner three elliptic curve sizes: 256, 384 or 521 bits. Attempting to 9519079Sfenner use bit lengths other than these three values for ECDSA keys will 9619079Sfenner fail. 979457Sjoerg 989457Sjoerg -C comment 999457Sjoerg Provides a new comment. 1009457Sjoerg 1019457Sjoerg -c Requests changing the comment in the private and public key 1029457Sjoerg files. This operation is only supported for RSA1 keys. The 10317352Swollman program will prompt for the file containing the private keys, for 10417352Swollman the passphrase if the key has one, and for the new comment. 1059457Sjoerg 1069457Sjoerg -D pkcs11 1079457Sjoerg Download the RSA public keys provided by the PKCS#11 shared 1089457Sjoerg library pkcs11. When used in combination with -s, this option 1099457Sjoerg indicates that a CA key resides in a PKCS#11 token (see the 1109457Sjoerg CERTIFICATES section for details). 1119457Sjoerg 1129457Sjoerg -e This option will read a private or public OpenSSH key file and 1139457Sjoerg print to stdout the key in one of the formats specified by the -m 1149457Sjoerg option. The default export format is ``RFC4716''. This option 1159457Sjoerg allows exporting OpenSSH keys for use by other programs, 1169457Sjoerg including several commercial SSH implementations. 1179457Sjoerg 1189457Sjoerg -F hostname 1199457Sjoerg Search for the specified hostname in a known_hosts file, listing 12058698Sjlemon any occurrences found. This option is useful to find hashed host 12158698Sjlemon names or addresses and may also be used in conjunction with the 12216287Sgpalmer -H option to print found keys in a hashed format. 1239457Sjoerg 1249457Sjoerg -f filename 1251541Srgrimes Specifies the filename of the key file. 1261541Srgrimes 1271541Srgrimes -G output_file 1281541Srgrimes Generate candidate primes for DH-GEX. These primes must be 1291541Srgrimes screened for safety (using the -T option) before use. 13047777Sphk 1311541Srgrimes -g Use generic DNS format when printing fingerprint resource records 1321541Srgrimes using the -r command. 1331541Srgrimes 1341541Srgrimes -H Hash a known_hosts file. This replaces all hostnames and 1351541Srgrimes addresses with hashed representations within the specified file; 1361541Srgrimes the original content is moved to a file with a .old suffix. 1371541Srgrimes These hashes may be used normally by ssh and sshd, but they do 1381541Srgrimes not reveal identifying information should the file's contents be 1391541Srgrimes disclosed. This option will not modify existing hashed hostnames 1403274Swollman and is therefore safe to use on files that mix hashed and non- 1411541Srgrimes hashed names. 14287902Sluigi 143102099Ssobomax -h When signing a key, create a host certificate instead of a user 144104044Sphk certificate. Please see the CERTIFICATES section for details. 14587902Sluigi 1461541Srgrimes -I certificate_identity 1471541Srgrimes Specify the key identity when signing a public key. Please see 1481541Srgrimes the CERTIFICATES section for details. 149102526Ssobomax 150102526Ssobomax -i This option will read an unencrypted private (or public) key file 1511541Srgrimes in the format specified by the -m option and print an OpenSSH 15283624Sjlemon compatible private (or public) key to stdout. 15383636Sjlemon 15483636Sjlemon -K checkpt 15583636Sjlemon Write the last line processed to the file checkpt while 15683624Sjlemon performing DH candidate screening using the -T option. This will 15783636Sjlemon be used to skip lines in the input file that have already been 15883636Sjlemon processed if the job is restarted. This option allows importing 1591541Srgrimes keys from other software, including several commercial SSH 1601541Srgrimes implementations. The default import format is ``RFC4716''. 1611541Srgrimes 1621541Srgrimes -L Prints the contents of a certificate. 1631541Srgrimes 1641541Srgrimes -l Show fingerprint of specified public key file. Private RSA1 keys 1651541Srgrimes are also supported. For RSA and DSA keys ssh-keygen tries to 1661541Srgrimes find the matching public key file and prints its fingerprint. If 1671541Srgrimes combined with -v, an ASCII art representation of the key is 16872093Sasmodai supplied with the fingerprint. 1691541Srgrimes 1701541Srgrimes -M memory 1711541Srgrimes Specify the amount of memory to use (in megabytes) when 1721541Srgrimes generating candidate moduli for DH-GEX. 1731541Srgrimes 1741541Srgrimes -m key_format 1751541Srgrimes Specify a key format for the -i (import) or -e (export) 1761541Srgrimes conversion options. The supported key formats are: ``RFC4716'' 1771541Srgrimes (RFC 4716/SSH2 public or private key), ``PKCS8'' (PEM PKCS8 1781541Srgrimes public key) or ``PEM'' (PEM public key). The default conversion 1791541Srgrimes format is ``RFC4716''. 1801541Srgrimes 1811541Srgrimes -N new_passphrase 18272093Sasmodai Provides the new passphrase. 1831541Srgrimes 1841541Srgrimes -n principals 1851541Srgrimes Specify one or more principals (user or host names) to be 1861541Srgrimes included in a certificate when signing a key. Multiple 1871541Srgrimes principals may be specified, separated by commas. Please see the 1881541Srgrimes CERTIFICATES section for details. 1891541Srgrimes 1901541Srgrimes -O option 19121666Swollman Specify a certificate option when signing a key. This option may 19221666Swollman be specified multiple times. Please see the CERTIFICATES section 19321666Swollman for details. The options that are valid for user certificates 19421666Swollman are: 19521666Swollman 19672093Sasmodai clear Clear all enabled permissions. This is useful for 19721666Swollman clearing the default set of permissions so permissions 19821666Swollman may be added individually. 19921666Swollman 20021666Swollman force-command=command 20121666Swollman Forces the execution of command instead of any shell or 20221666Swollman command specified by the user when the certificate is 20321666Swollman used for authentication. 20489498Sru 20589498Sru no-agent-forwarding 20689498Sru Disable ssh-agent(1) forwarding (permitted by default). 20789498Sru 20889498Sru no-port-forwarding 20989498Sru Disable port forwarding (permitted by default). 21089498Sru 21189498Sru no-pty Disable PTY allocation (permitted by default). 21289498Sru 21389498Sru no-user-rc 21489498Sru Disable execution of ~/.ssh/rc by sshd(8) (permitted by 21589498Sru default). 21689498Sru 21789498Sru no-x11-forwarding 21889498Sru Disable X11 forwarding (permitted by default). 2191541Srgrimes 2201541Srgrimes permit-agent-forwarding 2211541Srgrimes Allows ssh-agent(1) forwarding. 2221541Srgrimes 2231541Srgrimes permit-port-forwarding 2241541Srgrimes Allows port forwarding. 2251541Srgrimes 2261541Srgrimes permit-pty 2271541Srgrimes Allows PTY allocation. 2281541Srgrimes 2291541Srgrimes permit-user-rc 23044144Sphk Allows execution of ~/.ssh/rc by sshd(8). 23185079Sjlemon 2321541Srgrimes permit-x11-forwarding 2331941Sdg Allows X11 forwarding. 2345184Swollman 23525434Speter source-address=address_list 2361541Srgrimes Restrict the source addresses from which the certificate 23783624Sjlemon is considered valid. The address_list is a comma- 2381541Srgrimes separated list of one or more address/netmask pairs in 2391541Srgrimes CIDR format. 2401541Srgrimes 2411541Srgrimes At present, no options are valid for host keys. 242102052Ssobomax 243102052Ssobomax -P passphrase 2441541Srgrimes Provides the (old) passphrase. 2451941Sdg 2465187Sdg -p Requests changing the passphrase of a private key file instead of 24725434Speter creating a new private key. The program will prompt for the file 2481541Srgrimes containing the private key, for the old passphrase, and twice for 24983624Sjlemon the new passphrase. 25083624Sjlemon 25185079Sjlemon -q Silence ssh-keygen. 2521541Srgrimes 2531541Srgrimes -R hostname 25432491Swollman Removes all keys belonging to hostname from a known_hosts file. 25532491Swollman This option is useful to delete hashed hosts (see the -H option 25632491Swollman above). 25732491Swollman 25832491Swollman -r hostname 2591541Srgrimes Print the SSHFP fingerprint resource record named hostname for 2601541Srgrimes the specified public key file. 2611541Srgrimes 2621541Srgrimes -S start 2631541Srgrimes Specify start point (in hex) when generating candidate moduli for 2641541Srgrimes DH-GEX. 2651541Srgrimes 26625434Speter -s ca_key 26725434Speter Certify (sign) a public key using the specified CA key. Please 26825434Speter see the CERTIFICATES section for details. 26925434Speter 27025434Speter -T output_file 27125434Speter Test DH group exchange candidate primes (generated using the -G 27225434Speter option) for safety. 27325434Speter 27425434Speter -t type 27548021Sphk Specifies the type of key to create. The possible values are 27648021Sphk ``rsa1'' for protocol version 1 and ``dsa'', ``ecdsa'' or ``rsa'' 27748021Sphk for protocol version 2. 27848589Sbde 27948021Sphk -V validity_interval 28048589Sbde Specify a validity interval when signing a certificate. A 28148021Sphk validity interval may consist of a single time, indicating that 28248021Sphk the certificate is valid beginning now and expiring at that time, 28348589Sbde or may consist of two times separated by a colon to indicate an 28448021Sphk explicit time interval. The start time may be specified as a 28548589Sbde date in YYYYMMDD format, a time in YYYYMMDDHHMMSS format or a 28648589Sbde relative time (to the current time) consisting of a minus sign 28748021Sphk followed by a relative time in the format described in the TIME 28848021Sphk FORMATS section of sshd_config(5). The end time may be specified 2891541Srgrimes as a YYYYMMDD date, a YYYYMMDDHHMMSS time or a relative time 2901541Srgrimes starting with a plus character. 2911541Srgrimes 2921541Srgrimes For example: ``+52w1d'' (valid from now to 52 weeks and one day 2931541Srgrimes from now), ``-4w:+4w'' (valid from four weeks ago to four weeks 2941541Srgrimes from now), ``20100101123000:20110101123000'' (valid from 12:30 2951541Srgrimes PM, January 1st, 2010 to 12:30 PM, January 1st, 2011), 2961541Srgrimes ``-1d:20110101'' (valid from yesterday to midnight, January 1st, 2971541Srgrimes 2011). 2981541Srgrimes 2991541Srgrimes -v Verbose mode. Causes ssh-keygen to print debugging messages 3001541Srgrimes about its progress. This is helpful for debugging moduli 3011541Srgrimes generation. Multiple -v options increase the verbosity. The 3021541Srgrimes maximum is 3. 3031541Srgrimes 3041541Srgrimes -W generator 30552904Sshin Specify desired generator when testing candidate moduli for DH- 30652904Sshin GEX. 30752904Sshin 30852904Sshin -y This option will read a private OpenSSH format file and print an 30952904Sshin OpenSSH public key to stdout. 31052904Sshin 31152904Sshin -z serial_number 31252904Sshin Specifies a serial number to be embedded in the certificate to 31352904Sshin distinguish this certificate from others from the same CA. The 31452904Sshin default serial number is zero. 31552904Sshin 31652904SshinMODULI GENERATION 31752904Sshin ssh-keygen may be used to generate groups for the Diffie-Hellman Group 31855205Speter Exchange (DH-GEX) protocol. Generating these groups is a two-step 31930354Sphk process: first, candidate primes are generated using a fast, but memory 32030354Sphk intensive process. These candidate primes are then tested for 32130354Sphk suitability (a CPU-intensive process). 32230354Sphk 32330354Sphk Generation of primes is performed using the -G option. The desired 32430354Sphk length of the primes may be specified by the -b option. For example: 32555205Speter 32652904Sshin # ssh-keygen -G moduli-2048.candidates -b 2048 32752904Sshin 32852904Sshin By default, the search for primes begins at a random point in the desired 32952904Sshin length range. This may be overridden using the -S option, which 33052904Sshin specifies a different start point (in hex). 33152904Sshin 33292725Salfred Once a set of candidates have been generated, they must be tested for 33392725Salfred suitability. This may be performed using the -T option. In this mode 33492725Salfred ssh-keygen will read candidates from standard input (or a file specified 33592725Salfred using the -f option). For example: 33652904Sshin 33752904Sshin # ssh-keygen -T moduli-2048 -f moduli-2048.candidates 33852904Sshin 33955205Speter By default, each candidate will be subjected to 100 primality tests. 34083366Sjulian This may be overridden using the -a option. The DH generator value will 34148589Sbde be chosen automatically for the prime under consideration. If a specific 34248589Sbde generator is desired, it may be requested using the -W option. Valid 34321259Swollman generator values are 2, 3, and 5. 3441541Srgrimes 3451541Srgrimes Screened DH groups may be installed in /etc/moduli. It is important that 3464507Sbde this file contains moduli of a range of bit lengths and that both ends of 347 a connection share common moduli. 348 349CERTIFICATES 350 ssh-keygen supports signing of keys to produce certificates that may be 351 used for user or host authentication. Certificates consist of a public 352 key, some identity information, zero or more principal (user or host) 353 names and a set of options that are signed by a Certification Authority 354 (CA) key. Clients or servers may then trust only the CA key and verify 355 its signature on a certificate rather than trusting many user/host keys. 356 Note that OpenSSH certificates are a different, and much simpler, format 357 to the X.509 certificates used in ssl(8). 358 359 ssh-keygen supports two types of certificates: user and host. User 360 certificates authenticate users to servers, whereas host certificates 361 authenticate server hosts to users. To generate a user certificate: 362 363 $ ssh-keygen -s /path/to/ca_key -I key_id /path/to/user_key.pub 364 365 The resultant certificate will be placed in /path/to/user_key-cert.pub. 366 A host certificate requires the -h option: 367 368 $ ssh-keygen -s /path/to/ca_key -I key_id -h /path/to/host_key.pub 369 370 The host certificate will be output to /path/to/host_key-cert.pub. 371 372 It is possible to sign using a CA key stored in a PKCS#11 token by 373 providing the token library using -D and identifying the CA key by 374 providing its public half as an argument to -s: 375 376 $ ssh-keygen -s ca_key.pub -D libpkcs11.so -I key_id host_key.pub 377 378 In all cases, key_id is a "key identifier" that is logged by the server 379 when the certificate is used for authentication. 380 381 Certificates may be limited to be valid for a set of principal 382 (user/host) names. By default, generated certificates are valid for all 383 users or hosts. To generate a certificate for a specified set of 384 principals: 385 386 $ ssh-keygen -s ca_key -I key_id -n user1,user2 user_key.pub 387 $ ssh-keygen -s ca_key -I key_id -h -n host.domain user_key.pub 388 389 Additional limitations on the validity and use of user certificates may 390 be specified through certificate options. A certificate option may 391 disable features of the SSH session, may be valid only when presented 392 from particular source addresses or may force the use of a specific 393 command. For a list of valid certificate options, see the documentation 394 for the -O option above. 395 396 Finally, certificates may be defined with a validity lifetime. The -V 397 option allows specification of certificate start and end times. A 398 certificate that is presented at a time outside this range will not be 399 considered valid. By default, certificates have a maximum validity 400 interval. 401 402 For certificates to be used for user or host authentication, the CA 403 public key must be trusted by sshd(8) or ssh(1). Please refer to those 404 manual pages for details. 405 406FILES 407 ~/.ssh/identity 408 Contains the protocol version 1 RSA authentication identity of 409 the user. This file should not be readable by anyone but the 410 user. It is possible to specify a passphrase when generating the 411 key; that passphrase will be used to encrypt the private part of 412 this file using 3DES. This file is not automatically accessed by 413 ssh-keygen but it is offered as the default file for the private 414 key. ssh(1) will read this file when a login attempt is made. 415 416 ~/.ssh/identity.pub 417 Contains the protocol version 1 RSA public key for 418 authentication. The contents of this file should be added to 419 ~/.ssh/authorized_keys on all machines where the user wishes to 420 log in using RSA authentication. There is no need to keep the 421 contents of this file secret. 422 423 ~/.ssh/id_dsa 424 ~/.ssh/id_ecdsa 425 ~/.ssh/id_rsa 426 Contains the protocol version 2 DSA, ECDSA or RSA authentication 427 identity of the user. This file should not be readable by anyone 428 but the user. It is possible to specify a passphrase when 429 generating the key; that passphrase will be used to encrypt the 430 private part of this file using 128-bit AES. This file is not 431 automatically accessed by ssh-keygen but it is offered as the 432 default file for the private key. ssh(1) will read this file 433 when a login attempt is made. 434 435 ~/.ssh/id_dsa.pub 436 ~/.ssh/id_ecdsa.pub 437 ~/.ssh/id_rsa.pub 438 Contains the protocol version 2 DSA, ECDSA or RSA public key for 439 authentication. The contents of this file should be added to 440 ~/.ssh/authorized_keys on all machines where the user wishes to 441 log in using public key authentication. There is no need to keep 442 the contents of this file secret. 443 444 /etc/moduli 445 Contains Diffie-Hellman groups used for DH-GEX. The file format 446 is described in moduli(5). 447 448SEE ALSO 449 ssh(1), ssh-add(1), ssh-agent(1), moduli(5), sshd(8) 450 451 The Secure Shell (SSH) Public Key File Format, RFC 4716, 2006. 452 453AUTHORS 454 OpenSSH is a derivative of the original and free ssh 1.2.12 release by 455 Tatu Ylonen. Aaron Campbell, Bob Beck, Markus Friedl, Niels Provos, Theo 456 de Raadt and Dug Song removed many bugs, re-added newer features and 457 created OpenSSH. Markus Friedl contributed the support for SSH protocol 458 versions 1.5 and 2.0. 459 460OpenBSD 5.0 October 16, 2011 OpenBSD 5.0 461