diff options
Diffstat (limited to 'ssh-keygen.0')
-rw-r--r-- | ssh-keygen.0 | 790 |
1 files changed, 790 insertions, 0 deletions
diff --git a/ssh-keygen.0 b/ssh-keygen.0 new file mode 100644 index 000000000..c388cdf7a --- /dev/null +++ b/ssh-keygen.0 | |||
@@ -0,0 +1,790 @@ | |||
1 | SSH-KEYGEN(1) General Commands Manual SSH-KEYGEN(1) | ||
2 | |||
3 | NAME | ||
4 | ssh-keygen M-bM-^@M-^S OpenSSH authentication key utility | ||
5 | |||
6 | SYNOPSIS | ||
7 | ssh-keygen [-q] [-b bits] [-C comment] [-f output_keyfile] [-m format] | ||
8 | [-t dsa | ecdsa | ecdsa-sk | ed25519 | ed25519-sk | rsa] | ||
9 | [-N new_passphrase] [-O option] [-w provider] | ||
10 | ssh-keygen -p [-f keyfile] [-m format] [-N new_passphrase] | ||
11 | [-P old_passphrase] | ||
12 | ssh-keygen -i [-f input_keyfile] [-m key_format] | ||
13 | ssh-keygen -e [-f input_keyfile] [-m key_format] | ||
14 | ssh-keygen -y [-f input_keyfile] | ||
15 | ssh-keygen -c [-C comment] [-f keyfile] [-P passphrase] | ||
16 | ssh-keygen -l [-v] [-E fingerprint_hash] [-f input_keyfile] | ||
17 | ssh-keygen -B [-f input_keyfile] | ||
18 | ssh-keygen -D pkcs11 | ||
19 | ssh-keygen -F hostname [-lv] [-f known_hosts_file] | ||
20 | ssh-keygen -H [-f known_hosts_file] | ||
21 | ssh-keygen -K [-w provider] | ||
22 | ssh-keygen -R hostname [-f known_hosts_file] | ||
23 | ssh-keygen -r hostname [-g] [-f input_keyfile] | ||
24 | ssh-keygen -M generate [-O option] output_file | ||
25 | ssh-keygen -M screen [-f input_file] [-O option] output_file | ||
26 | ssh-keygen -I certificate_identity -s ca_key [-hU] [-D pkcs11_provider] | ||
27 | [-n principals] [-O option] [-V validity_interval] | ||
28 | [-z serial_number] file ... | ||
29 | ssh-keygen -L [-f input_keyfile] | ||
30 | ssh-keygen -A [-f prefix_path] | ||
31 | ssh-keygen -k -f krl_file [-u] [-s ca_public] [-z version_number] | ||
32 | file ... | ||
33 | ssh-keygen -Q [-l] -f krl_file file ... | ||
34 | ssh-keygen -Y find-principals -s signature_file -f allowed_signers_file | ||
35 | ssh-keygen -Y check-novalidate -n namespace -s signature_file | ||
36 | ssh-keygen -Y sign -f key_file -n namespace file ... | ||
37 | ssh-keygen -Y verify -f allowed_signers_file -I signer_identity | ||
38 | -n namespace -s signature_file [-r revocation_file] | ||
39 | |||
40 | DESCRIPTION | ||
41 | ssh-keygen generates, manages and converts authentication keys for | ||
42 | ssh(1). ssh-keygen can create keys for use by SSH protocol version 2. | ||
43 | |||
44 | The type of key to be generated is specified with the -t option. If | ||
45 | invoked without any arguments, ssh-keygen will generate an RSA key. | ||
46 | |||
47 | ssh-keygen is also used to generate groups for use in Diffie-Hellman | ||
48 | group exchange (DH-GEX). See the MODULI GENERATION section for details. | ||
49 | |||
50 | Finally, ssh-keygen can be used to generate and update Key Revocation | ||
51 | Lists, and to test whether given keys have been revoked by one. See the | ||
52 | KEY REVOCATION LISTS section for details. | ||
53 | |||
54 | Normally each user wishing to use SSH with public key authentication runs | ||
55 | this once to create the authentication key in ~/.ssh/id_dsa, | ||
56 | ~/.ssh/id_ecdsa, ~/.ssh/id_ecdsa_sk, ~/.ssh/id_ed25519, | ||
57 | ~/.ssh/id_ed25519_sk or ~/.ssh/id_rsa. Additionally, the system | ||
58 | administrator may use this to generate host keys, as seen in /etc/rc. | ||
59 | |||
60 | Normally this program generates the key and asks for a file in which to | ||
61 | store the private key. The public key is stored in a file with the same | ||
62 | name but M-bM-^@M-^\.pubM-bM-^@M-^] appended. The program also asks for a passphrase. The | ||
63 | passphrase may be empty to indicate no passphrase (host keys must have an | ||
64 | empty passphrase), or it may be a string of arbitrary length. A | ||
65 | passphrase is similar to a password, except it can be a phrase with a | ||
66 | series of words, punctuation, numbers, whitespace, or any string of | ||
67 | characters you want. Good passphrases are 10-30 characters long, are not | ||
68 | simple sentences or otherwise easily guessable (English prose has only | ||
69 | 1-2 bits of entropy per character, and provides very bad passphrases), | ||
70 | and contain a mix of upper and lowercase letters, numbers, and non- | ||
71 | alphanumeric characters. The passphrase can be changed later by using | ||
72 | the -p option. | ||
73 | |||
74 | There is no way to recover a lost passphrase. If the passphrase is lost | ||
75 | or forgotten, a new key must be generated and the corresponding public | ||
76 | key copied to other machines. | ||
77 | |||
78 | ssh-keygen will by default write keys in an OpenSSH-specific format. | ||
79 | This format is preferred as it offers better protection for keys at rest | ||
80 | as well as allowing storage of key comments within the private key file | ||
81 | itself. The key comment may be useful to help identify the key. The | ||
82 | comment is initialized to M-bM-^@M-^\user@hostM-bM-^@M-^] when the key is created, but can be | ||
83 | changed using the -c option. | ||
84 | |||
85 | It is still possible for ssh-keygen to write the previously-used PEM | ||
86 | format private keys using the -m flag. This may be used when generating | ||
87 | new keys, and existing new-format keys may be converted using this option | ||
88 | in conjunction with the -p (change passphrase) flag. | ||
89 | |||
90 | After a key is generated, instructions below detail where the keys should | ||
91 | be placed to be activated. | ||
92 | |||
93 | The options are as follows: | ||
94 | |||
95 | -A For each of the key types (rsa, dsa, ecdsa and ed25519) for which | ||
96 | host keys do not exist, generate the host keys with the default | ||
97 | key file path, an empty passphrase, default bits for the key | ||
98 | type, and default comment. If -f has also been specified, its | ||
99 | argument is used as a prefix to the default path for the | ||
100 | resulting host key files. This is used by /etc/rc to generate | ||
101 | new host keys. | ||
102 | |||
103 | -a rounds | ||
104 | When saving a private key, this option specifies the number of | ||
105 | KDF (key derivation function) rounds used. Higher numbers result | ||
106 | in slower passphrase verification and increased resistance to | ||
107 | brute-force password cracking (should the keys be stolen). | ||
108 | |||
109 | -B Show the bubblebabble digest of specified private or public key | ||
110 | file. | ||
111 | |||
112 | -b bits | ||
113 | Specifies the number of bits in the key to create. For RSA keys, | ||
114 | the minimum size is 1024 bits and the default is 3072 bits. | ||
115 | Generally, 3072 bits is considered sufficient. DSA keys must be | ||
116 | exactly 1024 bits as specified by FIPS 186-2. For ECDSA keys, | ||
117 | the -b flag determines the key length by selecting from one of | ||
118 | three elliptic curve sizes: 256, 384 or 521 bits. Attempting to | ||
119 | use bit lengths other than these three values for ECDSA keys will | ||
120 | fail. ECDSA-SK, Ed25519 and Ed25519-SK keys have a fixed length | ||
121 | and the -b flag will be ignored. | ||
122 | |||
123 | -C comment | ||
124 | Provides a new comment. | ||
125 | |||
126 | -c Requests changing the comment in the private and public key | ||
127 | files. The program will prompt for the file containing the | ||
128 | private keys, for the passphrase if the key has one, and for the | ||
129 | new comment. | ||
130 | |||
131 | -D pkcs11 | ||
132 | Download the public keys provided by the PKCS#11 shared library | ||
133 | pkcs11. When used in combination with -s, this option indicates | ||
134 | that a CA key resides in a PKCS#11 token (see the CERTIFICATES | ||
135 | section for details). | ||
136 | |||
137 | -E fingerprint_hash | ||
138 | Specifies the hash algorithm used when displaying key | ||
139 | fingerprints. Valid options are: M-bM-^@M-^\md5M-bM-^@M-^] and M-bM-^@M-^\sha256M-bM-^@M-^]. The | ||
140 | default is M-bM-^@M-^\sha256M-bM-^@M-^]. | ||
141 | |||
142 | -e This option will read a private or public OpenSSH key file and | ||
143 | print to stdout a public key in one of the formats specified by | ||
144 | the -m option. The default export format is M-bM-^@M-^\RFC4716M-bM-^@M-^]. This | ||
145 | option allows exporting OpenSSH keys for use by other programs, | ||
146 | including several commercial SSH implementations. | ||
147 | |||
148 | -F hostname | [hostname]:port | ||
149 | Search for the specified hostname (with optional port number) in | ||
150 | a known_hosts file, listing any occurrences found. This option | ||
151 | is useful to find hashed host names or addresses and may also be | ||
152 | used in conjunction with the -H option to print found keys in a | ||
153 | hashed format. | ||
154 | |||
155 | -f filename | ||
156 | Specifies the filename of the key file. | ||
157 | |||
158 | -g Use generic DNS format when printing fingerprint resource records | ||
159 | using the -r command. | ||
160 | |||
161 | -H Hash a known_hosts file. This replaces all hostnames and | ||
162 | addresses with hashed representations within the specified file; | ||
163 | the original content is moved to a file with a .old suffix. | ||
164 | These hashes may be used normally by ssh and sshd, but they do | ||
165 | not reveal identifying information should the file's contents be | ||
166 | disclosed. This option will not modify existing hashed hostnames | ||
167 | and is therefore safe to use on files that mix hashed and non- | ||
168 | hashed names. | ||
169 | |||
170 | -h When signing a key, create a host certificate instead of a user | ||
171 | certificate. Please see the CERTIFICATES section for details. | ||
172 | |||
173 | -I certificate_identity | ||
174 | Specify the key identity when signing a public key. Please see | ||
175 | the CERTIFICATES section for details. | ||
176 | |||
177 | -i This option will read an unencrypted private (or public) key file | ||
178 | in the format specified by the -m option and print an OpenSSH | ||
179 | compatible private (or public) key to stdout. This option allows | ||
180 | importing keys from other software, including several commercial | ||
181 | SSH implementations. The default import format is M-bM-^@M-^\RFC4716M-bM-^@M-^]. | ||
182 | |||
183 | -K Download resident keys from a FIDO authenticator. Public and | ||
184 | private key files will be written to the current directory for | ||
185 | each downloaded key. | ||
186 | |||
187 | -k Generate a KRL file. In this mode, ssh-keygen will generate a | ||
188 | KRL file at the location specified via the -f flag that revokes | ||
189 | every key or certificate presented on the command line. | ||
190 | Keys/certificates to be revoked may be specified by public key | ||
191 | file or using the format described in the KEY REVOCATION LISTS | ||
192 | section. | ||
193 | |||
194 | -L Prints the contents of one or more certificates. | ||
195 | |||
196 | -l Show fingerprint of specified public key file. For RSA and DSA | ||
197 | keys ssh-keygen tries to find the matching public key file and | ||
198 | prints its fingerprint. If combined with -v, a visual ASCII art | ||
199 | representation of the key is supplied with the fingerprint. | ||
200 | |||
201 | -M generate | ||
202 | Generate candidate Diffie-Hellman Group Exchange (DH-GEX) | ||
203 | parameters for eventual use by the | ||
204 | M-bM-^@M-^Xdiffie-hellman-group-exchange-*M-bM-^@M-^Y key exchange methods. The | ||
205 | numbers generated by this operation must be further screened | ||
206 | before use. See the MODULI GENERATION section for more | ||
207 | information. | ||
208 | |||
209 | -M screen | ||
210 | Screen candidate parameters for Diffie-Hellman Group Exchange. | ||
211 | This will accept a list of candidate numbers and test that they | ||
212 | are safe (Sophie Germain) primes with acceptable group | ||
213 | generators. The results of this operation may be added to the | ||
214 | /etc/moduli file. See the MODULI GENERATION section for more | ||
215 | information. | ||
216 | |||
217 | -m key_format | ||
218 | Specify a key format for key generation, the -i (import), -e | ||
219 | (export) conversion options, and the -p change passphrase | ||
220 | operation. The latter may be used to convert between OpenSSH | ||
221 | private key and PEM private key formats. The supported key | ||
222 | formats are: M-bM-^@M-^\RFC4716M-bM-^@M-^] (RFC 4716/SSH2 public or private key), | ||
223 | M-bM-^@M-^\PKCS8M-bM-^@M-^] (PKCS8 public or private key) or M-bM-^@M-^\PEMM-bM-^@M-^] (PEM public key). | ||
224 | By default OpenSSH will write newly-generated private keys in its | ||
225 | own format, but when converting public keys for export the | ||
226 | default format is M-bM-^@M-^\RFC4716M-bM-^@M-^]. Setting a format of M-bM-^@M-^\PEMM-bM-^@M-^] when | ||
227 | generating or updating a supported private key type will cause | ||
228 | the key to be stored in the legacy PEM private key format. | ||
229 | |||
230 | -N new_passphrase | ||
231 | Provides the new passphrase. | ||
232 | |||
233 | -n principals | ||
234 | Specify one or more principals (user or host names) to be | ||
235 | included in a certificate when signing a key. Multiple | ||
236 | principals may be specified, separated by commas. Please see the | ||
237 | CERTIFICATES section for details. | ||
238 | |||
239 | -O option | ||
240 | Specify a key/value option. These are specific to the operation | ||
241 | that ssh-keygen has been requested to perform. | ||
242 | |||
243 | When signing certificates, one of the options listed in the | ||
244 | CERTIFICATES section may be specified here. | ||
245 | |||
246 | When performing moduli generation or screening, one of the | ||
247 | options listed in the MODULI GENERATION section may be specified. | ||
248 | |||
249 | When generating a key that will be hosted on a FIDO | ||
250 | authenticator, this flag may be used to specify key-specific | ||
251 | options. Those supported at present are: | ||
252 | |||
253 | application | ||
254 | Override the default FIDO application/origin string of | ||
255 | M-bM-^@M-^\ssh:M-bM-^@M-^]. This may be useful when generating host or | ||
256 | domain-specific resident keys. The specified application | ||
257 | string must begin with M-bM-^@M-^\ssh:M-bM-^@M-^]. | ||
258 | |||
259 | challenge=path | ||
260 | Specifies a path to a challenge string that will be | ||
261 | passed to the FIDO token during key generation. The | ||
262 | challenge string may be used as part of an out-of-band | ||
263 | protocol for key enrollment (a random challenge is used | ||
264 | by default). | ||
265 | |||
266 | device Explicitly specify a fido(4) device to use, rather than | ||
267 | letting the token middleware select one. | ||
268 | |||
269 | no-touch-required | ||
270 | Indicate that the generated private key should not | ||
271 | require touch events (user presence) when making | ||
272 | signatures. Note that sshd(8) will refuse such | ||
273 | signatures by default, unless overridden via an | ||
274 | authorized_keys option. | ||
275 | |||
276 | resident | ||
277 | Indicate that the key should be stored on the FIDO | ||
278 | authenticator itself. Resident keys may be supported on | ||
279 | FIDO2 tokens and typically require that a PIN be set on | ||
280 | the token prior to generation. Resident keys may be | ||
281 | loaded off the token using ssh-add(1). | ||
282 | |||
283 | user A username to be associated with a resident key, | ||
284 | overriding the empty default username. Specifying a | ||
285 | username may be useful when generating multiple resident | ||
286 | keys for the same application name. | ||
287 | |||
288 | write-attestation=path | ||
289 | May be used at key generation time to record the | ||
290 | attestation certificate returned from FIDO tokens during | ||
291 | key generation. By default this information is | ||
292 | discarded. | ||
293 | |||
294 | The -O option may be specified multiple times. | ||
295 | |||
296 | -P passphrase | ||
297 | Provides the (old) passphrase. | ||
298 | |||
299 | -p Requests changing the passphrase of a private key file instead of | ||
300 | creating a new private key. The program will prompt for the file | ||
301 | containing the private key, for the old passphrase, and twice for | ||
302 | the new passphrase. | ||
303 | |||
304 | -Q Test whether keys have been revoked in a KRL. If the -l option | ||
305 | is also specified then the contents of the KRL will be printed. | ||
306 | |||
307 | -q Silence ssh-keygen. | ||
308 | |||
309 | -R hostname | [hostname]:port | ||
310 | Removes all keys belonging to the specified hostname (with | ||
311 | optional port number) from a known_hosts file. This option is | ||
312 | useful to delete hashed hosts (see the -H option above). | ||
313 | |||
314 | -r hostname | ||
315 | Print the SSHFP fingerprint resource record named hostname for | ||
316 | the specified public key file. | ||
317 | |||
318 | -s ca_key | ||
319 | Certify (sign) a public key using the specified CA key. Please | ||
320 | see the CERTIFICATES section for details. | ||
321 | |||
322 | When generating a KRL, -s specifies a path to a CA public key | ||
323 | file used to revoke certificates directly by key ID or serial | ||
324 | number. See the KEY REVOCATION LISTS section for details. | ||
325 | |||
326 | -t dsa | ecdsa | ecdsa-sk | ed25519 | ed25519-sk | rsa | ||
327 | Specifies the type of key to create. The possible values are | ||
328 | M-bM-^@M-^\dsaM-bM-^@M-^], M-bM-^@M-^\ecdsaM-bM-^@M-^], M-bM-^@M-^\ecdsa-skM-bM-^@M-^], M-bM-^@M-^\ed25519M-bM-^@M-^], M-bM-^@M-^\ed25519-skM-bM-^@M-^], or M-bM-^@M-^\rsaM-bM-^@M-^]. | ||
329 | |||
330 | This flag may also be used to specify the desired signature type | ||
331 | when signing certificates using an RSA CA key. The available RSA | ||
332 | signature variants are M-bM-^@M-^\ssh-rsaM-bM-^@M-^] (SHA1 signatures, not | ||
333 | recommended), M-bM-^@M-^\rsa-sha2-256M-bM-^@M-^], and M-bM-^@M-^\rsa-sha2-512M-bM-^@M-^] (the default). | ||
334 | |||
335 | -U When used in combination with -s, this option indicates that a CA | ||
336 | key resides in a ssh-agent(1). See the CERTIFICATES section for | ||
337 | more information. | ||
338 | |||
339 | -u Update a KRL. When specified with -k, keys listed via the | ||
340 | command line are added to the existing KRL rather than a new KRL | ||
341 | being created. | ||
342 | |||
343 | -V validity_interval | ||
344 | Specify a validity interval when signing a certificate. A | ||
345 | validity interval may consist of a single time, indicating that | ||
346 | the certificate is valid beginning now and expiring at that time, | ||
347 | or may consist of two times separated by a colon to indicate an | ||
348 | explicit time interval. | ||
349 | |||
350 | The start time may be specified as the string M-bM-^@M-^\alwaysM-bM-^@M-^] to | ||
351 | indicate the certificate has no specified start time, a date in | ||
352 | YYYYMMDD format, a time in YYYYMMDDHHMM[SS] format, a relative | ||
353 | time (to the current time) consisting of a minus sign followed by | ||
354 | an interval in the format described in the TIME FORMATS section | ||
355 | of sshd_config(5). | ||
356 | |||
357 | The end time may be specified as a YYYYMMDD date, a | ||
358 | YYYYMMDDHHMM[SS] time, a relative time starting with a plus | ||
359 | character or the string M-bM-^@M-^\foreverM-bM-^@M-^] to indicate that the | ||
360 | certificate has no expiry date. | ||
361 | |||
362 | For example: M-bM-^@M-^\+52w1dM-bM-^@M-^] (valid from now to 52 weeks and one day | ||
363 | from now), M-bM-^@M-^\-4w:+4wM-bM-^@M-^] (valid from four weeks ago to four weeks | ||
364 | from now), M-bM-^@M-^\20100101123000:20110101123000M-bM-^@M-^] (valid from 12:30 PM, | ||
365 | January 1st, 2010 to 12:30 PM, January 1st, 2011), M-bM-^@M-^\-1d:20110101M-bM-^@M-^] | ||
366 | (valid from yesterday to midnight, January 1st, 2011). | ||
367 | M-bM-^@M-^\-1m:foreverM-bM-^@M-^] (valid from one minute ago and never expiring). | ||
368 | |||
369 | -v Verbose mode. Causes ssh-keygen to print debugging messages | ||
370 | about its progress. This is helpful for debugging moduli | ||
371 | generation. Multiple -v options increase the verbosity. The | ||
372 | maximum is 3. | ||
373 | |||
374 | -w provider | ||
375 | Specifies a path to a library that will be used when creating | ||
376 | FIDO authenticator-hosted keys, overriding the default of using | ||
377 | the internal USB HID support. | ||
378 | |||
379 | -Y find-principals | ||
380 | Find the principal(s) associated with the public key of a | ||
381 | signature, provided using the -s flag in an authorized signers | ||
382 | file provided using the -f flag. The format of the allowed | ||
383 | signers file is documented in the ALLOWED SIGNERS section below. | ||
384 | If one or more matching principals are found, they are returned | ||
385 | on standard output. | ||
386 | |||
387 | -Y check-novalidate | ||
388 | Checks that a signature generated using ssh-keygen -Y sign has a | ||
389 | valid structure. This does not validate if a signature comes | ||
390 | from an authorized signer. When testing a signature, ssh-keygen | ||
391 | accepts a message on standard input and a signature namespace | ||
392 | using -n. A file containing the corresponding signature must | ||
393 | also be supplied using the -s flag. Successful testing of the | ||
394 | signature is signalled by ssh-keygen returning a zero exit | ||
395 | status. | ||
396 | |||
397 | -Y sign | ||
398 | Cryptographically sign a file or some data using a SSH key. When | ||
399 | signing, ssh-keygen accepts zero or more files to sign on the | ||
400 | command-line - if no files are specified then ssh-keygen will | ||
401 | sign data presented on standard input. Signatures are written to | ||
402 | the path of the input file with M-bM-^@M-^\.sigM-bM-^@M-^] appended, or to standard | ||
403 | output if the message to be signed was read from standard input. | ||
404 | |||
405 | The key used for signing is specified using the -f option and may | ||
406 | refer to either a private key, or a public key with the private | ||
407 | half available via ssh-agent(1). An additional signature | ||
408 | namespace, used to prevent signature confusion across different | ||
409 | domains of use (e.g. file signing vs email signing) must be | ||
410 | provided via the -n flag. Namespaces are arbitrary strings, and | ||
411 | may include: M-bM-^@M-^\fileM-bM-^@M-^] for file signing, M-bM-^@M-^\emailM-bM-^@M-^] for email signing. | ||
412 | For custom uses, it is recommended to use names following a | ||
413 | NAMESPACE@YOUR.DOMAIN pattern to generate unambiguous namespaces. | ||
414 | |||
415 | -Y verify | ||
416 | Request to verify a signature generated using ssh-keygen -Y sign | ||
417 | as described above. When verifying a signature, ssh-keygen | ||
418 | accepts a message on standard input and a signature namespace | ||
419 | using -n. A file containing the corresponding signature must | ||
420 | also be supplied using the -s flag, along with the identity of | ||
421 | the signer using -I and a list of allowed signers via the -f | ||
422 | flag. The format of the allowed signers file is documented in | ||
423 | the ALLOWED SIGNERS section below. A file containing revoked | ||
424 | keys can be passed using the -r flag. The revocation file may be | ||
425 | a KRL or a one-per-line list of public keys. Successful | ||
426 | verification by an authorized signer is signalled by ssh-keygen | ||
427 | returning a zero exit status. | ||
428 | |||
429 | -y This option will read a private OpenSSH format file and print an | ||
430 | OpenSSH public key to stdout. | ||
431 | |||
432 | -z serial_number | ||
433 | Specifies a serial number to be embedded in the certificate to | ||
434 | distinguish this certificate from others from the same CA. If | ||
435 | the serial_number is prefixed with a M-bM-^@M-^X+M-bM-^@M-^Y character, then the | ||
436 | serial number will be incremented for each certificate signed on | ||
437 | a single command-line. The default serial number is zero. | ||
438 | |||
439 | When generating a KRL, the -z flag is used to specify a KRL | ||
440 | version number. | ||
441 | |||
442 | MODULI GENERATION | ||
443 | ssh-keygen may be used to generate groups for the Diffie-Hellman Group | ||
444 | Exchange (DH-GEX) protocol. Generating these groups is a two-step | ||
445 | process: first, candidate primes are generated using a fast, but memory | ||
446 | intensive process. These candidate primes are then tested for | ||
447 | suitability (a CPU-intensive process). | ||
448 | |||
449 | Generation of primes is performed using the -M generate option. The | ||
450 | desired length of the primes may be specified by the -O bits option. For | ||
451 | example: | ||
452 | |||
453 | # ssh-keygen -M generate -O bits=2048 moduli-2048.candidates | ||
454 | |||
455 | By default, the search for primes begins at a random point in the desired | ||
456 | length range. This may be overridden using the -O start option, which | ||
457 | specifies a different start point (in hex). | ||
458 | |||
459 | Once a set of candidates have been generated, they must be screened for | ||
460 | suitability. This may be performed using the -M screen option. In this | ||
461 | mode ssh-keygen will read candidates from standard input (or a file | ||
462 | specified using the -f option). For example: | ||
463 | |||
464 | # ssh-keygen -M screen -f moduli-2048.candidates moduli-2048 | ||
465 | |||
466 | By default, each candidate will be subjected to 100 primality tests. | ||
467 | This may be overridden using the -O prime-tests option. The DH generator | ||
468 | value will be chosen automatically for the prime under consideration. If | ||
469 | a specific generator is desired, it may be requested using the -O | ||
470 | generator option. Valid generator values are 2, 3, and 5. | ||
471 | |||
472 | Screened DH groups may be installed in /etc/moduli. It is important that | ||
473 | this file contains moduli of a range of bit lengths and that both ends of | ||
474 | a connection share common moduli. | ||
475 | |||
476 | A number of options are available for moduli generation and screening via | ||
477 | the -O flag: | ||
478 | |||
479 | lines=number | ||
480 | Exit after screening the specified number of lines while | ||
481 | performing DH candidate screening. | ||
482 | |||
483 | start-line=line-number | ||
484 | Start screening at the specified line number while performing DH | ||
485 | candidate screening. | ||
486 | |||
487 | checkpoint=filename | ||
488 | Write the last line processed to the specified file while | ||
489 | performing DH candidate screening. This will be used to skip | ||
490 | lines in the input file that have already been processed if the | ||
491 | job is restarted. | ||
492 | |||
493 | memory=mbytes | ||
494 | Specify the amount of memory to use (in megabytes) when | ||
495 | generating candidate moduli for DH-GEX. | ||
496 | |||
497 | start=hex-value | ||
498 | Specify start point (in hex) when generating candidate moduli for | ||
499 | DH-GEX. | ||
500 | |||
501 | generator=value | ||
502 | Specify desired generator (in decimal) when testing candidate | ||
503 | moduli for DH-GEX. | ||
504 | |||
505 | CERTIFICATES | ||
506 | ssh-keygen supports signing of keys to produce certificates that may be | ||
507 | used for user or host authentication. Certificates consist of a public | ||
508 | key, some identity information, zero or more principal (user or host) | ||
509 | names and a set of options that are signed by a Certification Authority | ||
510 | (CA) key. Clients or servers may then trust only the CA key and verify | ||
511 | its signature on a certificate rather than trusting many user/host keys. | ||
512 | Note that OpenSSH certificates are a different, and much simpler, format | ||
513 | to the X.509 certificates used in ssl(8). | ||
514 | |||
515 | ssh-keygen supports two types of certificates: user and host. User | ||
516 | certificates authenticate users to servers, whereas host certificates | ||
517 | authenticate server hosts to users. To generate a user certificate: | ||
518 | |||
519 | $ ssh-keygen -s /path/to/ca_key -I key_id /path/to/user_key.pub | ||
520 | |||
521 | The resultant certificate will be placed in /path/to/user_key-cert.pub. | ||
522 | A host certificate requires the -h option: | ||
523 | |||
524 | $ ssh-keygen -s /path/to/ca_key -I key_id -h /path/to/host_key.pub | ||
525 | |||
526 | The host certificate will be output to /path/to/host_key-cert.pub. | ||
527 | |||
528 | It is possible to sign using a CA key stored in a PKCS#11 token by | ||
529 | providing the token library using -D and identifying the CA key by | ||
530 | providing its public half as an argument to -s: | ||
531 | |||
532 | $ ssh-keygen -s ca_key.pub -D libpkcs11.so -I key_id user_key.pub | ||
533 | |||
534 | Similarly, it is possible for the CA key to be hosted in a ssh-agent(1). | ||
535 | This is indicated by the -U flag and, again, the CA key must be | ||
536 | identified by its public half. | ||
537 | |||
538 | $ ssh-keygen -Us ca_key.pub -I key_id user_key.pub | ||
539 | |||
540 | In all cases, key_id is a "key identifier" that is logged by the server | ||
541 | when the certificate is used for authentication. | ||
542 | |||
543 | Certificates may be limited to be valid for a set of principal | ||
544 | (user/host) names. By default, generated certificates are valid for all | ||
545 | users or hosts. To generate a certificate for a specified set of | ||
546 | principals: | ||
547 | |||
548 | $ ssh-keygen -s ca_key -I key_id -n user1,user2 user_key.pub | ||
549 | $ ssh-keygen -s ca_key -I key_id -h -n host.domain host_key.pub | ||
550 | |||
551 | Additional limitations on the validity and use of user certificates may | ||
552 | be specified through certificate options. A certificate option may | ||
553 | disable features of the SSH session, may be valid only when presented | ||
554 | from particular source addresses or may force the use of a specific | ||
555 | command. | ||
556 | |||
557 | The options that are valid for user certificates are: | ||
558 | |||
559 | clear Clear all enabled permissions. This is useful for clearing the | ||
560 | default set of permissions so permissions may be added | ||
561 | individually. | ||
562 | |||
563 | critical:name[=contents] | ||
564 | extension:name[=contents] | ||
565 | Includes an arbitrary certificate critical option or extension. | ||
566 | The specified name should include a domain suffix, e.g. | ||
567 | M-bM-^@M-^\name@example.comM-bM-^@M-^]. If contents is specified then it is included | ||
568 | as the contents of the extension/option encoded as a string, | ||
569 | otherwise the extension/option is created with no contents | ||
570 | (usually indicating a flag). Extensions may be ignored by a | ||
571 | client or server that does not recognise them, whereas unknown | ||
572 | critical options will cause the certificate to be refused. | ||
573 | |||
574 | force-command=command | ||
575 | Forces the execution of command instead of any shell or command | ||
576 | specified by the user when the certificate is used for | ||
577 | authentication. | ||
578 | |||
579 | no-agent-forwarding | ||
580 | Disable ssh-agent(1) forwarding (permitted by default). | ||
581 | |||
582 | no-port-forwarding | ||
583 | Disable port forwarding (permitted by default). | ||
584 | |||
585 | no-pty Disable PTY allocation (permitted by default). | ||
586 | |||
587 | no-user-rc | ||
588 | Disable execution of ~/.ssh/rc by sshd(8) (permitted by default). | ||
589 | |||
590 | no-x11-forwarding | ||
591 | Disable X11 forwarding (permitted by default). | ||
592 | |||
593 | permit-agent-forwarding | ||
594 | Allows ssh-agent(1) forwarding. | ||
595 | |||
596 | permit-port-forwarding | ||
597 | Allows port forwarding. | ||
598 | |||
599 | permit-pty | ||
600 | Allows PTY allocation. | ||
601 | |||
602 | permit-user-rc | ||
603 | Allows execution of ~/.ssh/rc by sshd(8). | ||
604 | |||
605 | permit-X11-forwarding | ||
606 | Allows X11 forwarding. | ||
607 | |||
608 | no-touch-required | ||
609 | Do not require signatures made using this key require | ||
610 | demonstration of user presence (e.g. by having the user touch the | ||
611 | authenticator). This option only makes sense for the FIDO | ||
612 | authenticator algorithms ecdsa-sk and ed25519-sk. | ||
613 | |||
614 | source-address=address_list | ||
615 | Restrict the source addresses from which the certificate is | ||
616 | considered valid. The address_list is a comma-separated list of | ||
617 | one or more address/netmask pairs in CIDR format. | ||
618 | |||
619 | At present, no standard options are valid for host keys. | ||
620 | |||
621 | Finally, certificates may be defined with a validity lifetime. The -V | ||
622 | option allows specification of certificate start and end times. A | ||
623 | certificate that is presented at a time outside this range will not be | ||
624 | considered valid. By default, certificates are valid from UNIX Epoch to | ||
625 | the distant future. | ||
626 | |||
627 | For certificates to be used for user or host authentication, the CA | ||
628 | public key must be trusted by sshd(8) or ssh(1). Please refer to those | ||
629 | manual pages for details. | ||
630 | |||
631 | KEY REVOCATION LISTS | ||
632 | ssh-keygen is able to manage OpenSSH format Key Revocation Lists (KRLs). | ||
633 | These binary files specify keys or certificates to be revoked using a | ||
634 | compact format, taking as little as one bit per certificate if they are | ||
635 | being revoked by serial number. | ||
636 | |||
637 | KRLs may be generated using the -k flag. This option reads one or more | ||
638 | files from the command line and generates a new KRL. The files may | ||
639 | either contain a KRL specification (see below) or public keys, listed one | ||
640 | per line. Plain public keys are revoked by listing their hash or | ||
641 | contents in the KRL and certificates revoked by serial number or key ID | ||
642 | (if the serial is zero or not available). | ||
643 | |||
644 | Revoking keys using a KRL specification offers explicit control over the | ||
645 | types of record used to revoke keys and may be used to directly revoke | ||
646 | certificates by serial number or key ID without having the complete | ||
647 | original certificate on hand. A KRL specification consists of lines | ||
648 | containing one of the following directives followed by a colon and some | ||
649 | directive-specific information. | ||
650 | |||
651 | serial: serial_number[-serial_number] | ||
652 | Revokes a certificate with the specified serial number. Serial | ||
653 | numbers are 64-bit values, not including zero and may be | ||
654 | expressed in decimal, hex or octal. If two serial numbers are | ||
655 | specified separated by a hyphen, then the range of serial numbers | ||
656 | including and between each is revoked. The CA key must have been | ||
657 | specified on the ssh-keygen command line using the -s option. | ||
658 | |||
659 | id: key_id | ||
660 | Revokes a certificate with the specified key ID string. The CA | ||
661 | key must have been specified on the ssh-keygen command line using | ||
662 | the -s option. | ||
663 | |||
664 | key: public_key | ||
665 | Revokes the specified key. If a certificate is listed, then it | ||
666 | is revoked as a plain public key. | ||
667 | |||
668 | sha1: public_key | ||
669 | Revokes the specified key by including its SHA1 hash in the KRL. | ||
670 | |||
671 | sha256: public_key | ||
672 | Revokes the specified key by including its SHA256 hash in the | ||
673 | KRL. KRLs that revoke keys by SHA256 hash are not supported by | ||
674 | OpenSSH versions prior to 7.9. | ||
675 | |||
676 | hash: fingerprint | ||
677 | Revokes a key using a fingerprint hash, as obtained from a | ||
678 | sshd(8) authentication log message or the ssh-keygen -l flag. | ||
679 | Only SHA256 fingerprints are supported here and resultant KRLs | ||
680 | are not supported by OpenSSH versions prior to 7.9. | ||
681 | |||
682 | KRLs may be updated using the -u flag in addition to -k. When this | ||
683 | option is specified, keys listed via the command line are merged into the | ||
684 | KRL, adding to those already there. | ||
685 | |||
686 | It is also possible, given a KRL, to test whether it revokes a particular | ||
687 | key (or keys). The -Q flag will query an existing KRL, testing each key | ||
688 | specified on the command line. If any key listed on the command line has | ||
689 | been revoked (or an error encountered) then ssh-keygen will exit with a | ||
690 | non-zero exit status. A zero exit status will only be returned if no key | ||
691 | was revoked. | ||
692 | |||
693 | ALLOWED SIGNERS | ||
694 | When verifying signatures, ssh-keygen uses a simple list of identities | ||
695 | and keys to determine whether a signature comes from an authorized | ||
696 | source. This "allowed signers" file uses a format patterned after the | ||
697 | AUTHORIZED_KEYS FILE FORMAT described in sshd(8). Each line of the file | ||
698 | contains the following space-separated fields: principals, options, | ||
699 | keytype, base64-encoded key. Empty lines and lines starting with a M-bM-^@M-^X#M-bM-^@M-^Y | ||
700 | are ignored as comments. | ||
701 | |||
702 | The principals field is a pattern-list (See PATTERNS in ssh_config(5)) | ||
703 | consisting of one or more comma-separated USER@DOMAIN identity patterns | ||
704 | that are accepted for signing. When verifying, the identity presented | ||
705 | via the -I option must match a principals pattern in order for the | ||
706 | corresponding key to be considered acceptable for verification. | ||
707 | |||
708 | The options (if present) consist of comma-separated option | ||
709 | specifications. No spaces are permitted, except within double quotes. | ||
710 | The following option specifications are supported (note that option | ||
711 | keywords are case-insensitive): | ||
712 | |||
713 | cert-authority | ||
714 | Indicates that this key is accepted as a certificate authority | ||
715 | (CA) and that certificates signed by this CA may be accepted for | ||
716 | verification. | ||
717 | |||
718 | namespaces="namespace-list" | ||
719 | Specifies a pattern-list of namespaces that are accepted for this | ||
720 | key. If this option is present, the signature namespace embedded | ||
721 | in the signature object and presented on the verification | ||
722 | command-line must match the specified list before the key will be | ||
723 | considered acceptable. | ||
724 | |||
725 | When verifying signatures made by certificates, the expected principal | ||
726 | name must match both the principals pattern in the allowed signers file | ||
727 | and the principals embedded in the certificate itself. | ||
728 | |||
729 | An example allowed signers file: | ||
730 | |||
731 | # Comments allowed at start of line | ||
732 | user1@example.com,user2@example.com ssh-rsa AAAAX1... | ||
733 | # A certificate authority, trusted for all principals in a domain. | ||
734 | *@example.com cert-authority ssh-ed25519 AAAB4... | ||
735 | # A key that is accepted only for file signing. | ||
736 | user2@example.com namespaces="file" ssh-ed25519 AAA41... | ||
737 | |||
738 | ENVIRONMENT | ||
739 | SSH_SK_PROVIDER | ||
740 | Specifies a path to a library that will be used when loading any | ||
741 | FIDO authenticator-hosted keys, overriding the default of using | ||
742 | the built-in USB HID support. | ||
743 | |||
744 | FILES | ||
745 | ~/.ssh/id_dsa | ||
746 | ~/.ssh/id_ecdsa | ||
747 | ~/.ssh/id_ecdsa_sk | ||
748 | ~/.ssh/id_ed25519 | ||
749 | ~/.ssh/id_ed25519_sk | ||
750 | ~/.ssh/id_rsa | ||
751 | Contains the DSA, ECDSA, authenticator-hosted ECDSA, Ed25519, | ||
752 | authenticator-hosted Ed25519 or RSA authentication identity of | ||
753 | the user. This file should not be readable by anyone but the | ||
754 | user. It is possible to specify a passphrase when generating the | ||
755 | key; that passphrase will be used to encrypt the private part of | ||
756 | this file using 128-bit AES. This file is not automatically | ||
757 | accessed by ssh-keygen but it is offered as the default file for | ||
758 | the private key. ssh(1) will read this file when a login attempt | ||
759 | is made. | ||
760 | |||
761 | ~/.ssh/id_dsa.pub | ||
762 | ~/.ssh/id_ecdsa.pub | ||
763 | ~/.ssh/id_ecdsa_sk.pub | ||
764 | ~/.ssh/id_ed25519.pub | ||
765 | ~/.ssh/id_ed25519_sk.pub | ||
766 | ~/.ssh/id_rsa.pub | ||
767 | Contains the DSA, ECDSA, authenticator-hosted ECDSA, Ed25519, | ||
768 | authenticator-hosted Ed25519 or RSA public key for | ||
769 | authentication. The contents of this file should be added to | ||
770 | ~/.ssh/authorized_keys on all machines where the user wishes to | ||
771 | log in using public key authentication. There is no need to keep | ||
772 | the contents of this file secret. | ||
773 | |||
774 | /etc/moduli | ||
775 | Contains Diffie-Hellman groups used for DH-GEX. The file format | ||
776 | is described in moduli(5). | ||
777 | |||
778 | SEE ALSO | ||
779 | ssh(1), ssh-add(1), ssh-agent(1), moduli(5), sshd(8) | ||
780 | |||
781 | The Secure Shell (SSH) Public Key File Format, RFC 4716, 2006. | ||
782 | |||
783 | AUTHORS | ||
784 | OpenSSH is a derivative of the original and free ssh 1.2.12 release by | ||
785 | Tatu Ylonen. Aaron Campbell, Bob Beck, Markus Friedl, Niels Provos, Theo | ||
786 | de Raadt and Dug Song removed many bugs, re-added newer features and | ||
787 | created OpenSSH. Markus Friedl contributed the support for SSH protocol | ||
788 | versions 1.5 and 2.0. | ||
789 | |||
790 | OpenBSD 6.7 April 3, 2020 OpenBSD 6.7 | ||