logo

oasis-root

Compiled tree of Oasis Linux based on own branch at <https://hacktivis.me/git/oasis/> git clone https://anongit.hacktivis.me/git/oasis-root.git

ssh-keygen.1 (41767B)


  1. .\" $OpenBSD: ssh-keygen.1,v 1.234 2024/11/27 13:00:23 djm Exp $
  2. .\"
  3. .\" Author: Tatu Ylonen <ylo@cs.hut.fi>
  4. .\" Copyright (c) 1995 Tatu Ylonen <ylo@cs.hut.fi>, Espoo, Finland
  5. .\" All rights reserved
  6. .\"
  7. .\" As far as I am concerned, the code I have written for this software
  8. .\" can be used freely for any purpose. Any derived versions of this
  9. .\" software must be clearly marked as such, and if the derived work is
  10. .\" incompatible with the protocol description in the RFC file, it must be
  11. .\" called by a name other than "ssh" or "Secure Shell".
  12. .\"
  13. .\"
  14. .\" Copyright (c) 1999,2000 Markus Friedl. All rights reserved.
  15. .\" Copyright (c) 1999 Aaron Campbell. All rights reserved.
  16. .\" Copyright (c) 1999 Theo de Raadt. All rights reserved.
  17. .\"
  18. .\" Redistribution and use in source and binary forms, with or without
  19. .\" modification, are permitted provided that the following conditions
  20. .\" are met:
  21. .\" 1. Redistributions of source code must retain the above copyright
  22. .\" notice, this list of conditions and the following disclaimer.
  23. .\" 2. Redistributions in binary form must reproduce the above copyright
  24. .\" notice, this list of conditions and the following disclaimer in the
  25. .\" documentation and/or other materials provided with the distribution.
  26. .\"
  27. .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
  28. .\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
  29. .\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
  30. .\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
  31. .\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
  32. .\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
  33. .\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
  34. .\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
  35. .\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
  36. .\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  37. .\"
  38. .Dd $Mdocdate: November 27 2024 $
  39. .Dt SSH-KEYGEN 1
  40. .Os
  41. .Sh NAME
  42. .Nm ssh-keygen
  43. .Nd OpenSSH authentication key utility
  44. .Sh SYNOPSIS
  45. .Nm ssh-keygen
  46. .Op Fl q
  47. .Op Fl a Ar rounds
  48. .Op Fl b Ar bits
  49. .Op Fl C Ar comment
  50. .Op Fl f Ar output_keyfile
  51. .Op Fl m Ar format
  52. .Op Fl N Ar new_passphrase
  53. .Op Fl O Ar option
  54. .Op Fl t Cm ecdsa | ecdsa-sk | ed25519 | ed25519-sk | rsa
  55. .Op Fl w Ar provider
  56. .Op Fl Z Ar cipher
  57. .Nm ssh-keygen
  58. .Fl p
  59. .Op Fl a Ar rounds
  60. .Op Fl f Ar keyfile
  61. .Op Fl m Ar format
  62. .Op Fl N Ar new_passphrase
  63. .Op Fl P Ar old_passphrase
  64. .Op Fl Z Ar cipher
  65. .Nm ssh-keygen
  66. .Fl i
  67. .Op Fl f Ar input_keyfile
  68. .Op Fl m Ar key_format
  69. .Nm ssh-keygen
  70. .Fl e
  71. .Op Fl f Ar input_keyfile
  72. .Op Fl m Ar key_format
  73. .Nm ssh-keygen
  74. .Fl y
  75. .Op Fl f Ar input_keyfile
  76. .Nm ssh-keygen
  77. .Fl c
  78. .Op Fl a Ar rounds
  79. .Op Fl C Ar comment
  80. .Op Fl f Ar keyfile
  81. .Op Fl P Ar passphrase
  82. .Nm ssh-keygen
  83. .Fl l
  84. .Op Fl v
  85. .Op Fl E Ar fingerprint_hash
  86. .Op Fl f Ar input_keyfile
  87. .Nm ssh-keygen
  88. .Fl B
  89. .Op Fl f Ar input_keyfile
  90. .Nm ssh-keygen
  91. .Fl D Ar pkcs11
  92. .Nm ssh-keygen
  93. .Fl F Ar hostname
  94. .Op Fl lv
  95. .Op Fl f Ar known_hosts_file
  96. .Nm ssh-keygen
  97. .Fl H
  98. .Op Fl f Ar known_hosts_file
  99. .Nm ssh-keygen
  100. .Fl K
  101. .Op Fl a Ar rounds
  102. .Op Fl w Ar provider
  103. .Nm ssh-keygen
  104. .Fl R Ar hostname
  105. .Op Fl f Ar known_hosts_file
  106. .Nm ssh-keygen
  107. .Fl r Ar hostname
  108. .Op Fl g
  109. .Op Fl f Ar input_keyfile
  110. .Nm ssh-keygen
  111. .Fl M Cm generate
  112. .Op Fl O Ar option
  113. .Ar output_file
  114. .Nm ssh-keygen
  115. .Fl M Cm screen
  116. .Op Fl f Ar input_file
  117. .Op Fl O Ar option
  118. .Ar output_file
  119. .Nm ssh-keygen
  120. .Fl I Ar certificate_identity
  121. .Fl s Ar ca_key
  122. .Op Fl hU
  123. .Op Fl D Ar pkcs11_provider
  124. .Op Fl n Ar principals
  125. .Op Fl O Ar option
  126. .Op Fl V Ar validity_interval
  127. .Op Fl z Ar serial_number
  128. .Ar
  129. .Nm ssh-keygen
  130. .Fl L
  131. .Op Fl f Ar input_keyfile
  132. .Nm ssh-keygen
  133. .Fl A
  134. .Op Fl a Ar rounds
  135. .Op Fl f Ar prefix_path
  136. .Nm ssh-keygen
  137. .Fl k
  138. .Fl f Ar krl_file
  139. .Op Fl u
  140. .Op Fl s Ar ca_public
  141. .Op Fl z Ar version_number
  142. .Ar
  143. .Nm ssh-keygen
  144. .Fl Q
  145. .Op Fl l
  146. .Fl f Ar krl_file
  147. .Ar
  148. .Nm ssh-keygen
  149. .Fl Y Cm find-principals
  150. .Op Fl O Ar option
  151. .Fl s Ar signature_file
  152. .Fl f Ar allowed_signers_file
  153. .Nm ssh-keygen
  154. .Fl Y Cm match-principals
  155. .Fl I Ar signer_identity
  156. .Fl f Ar allowed_signers_file
  157. .Nm ssh-keygen
  158. .Fl Y Cm check-novalidate
  159. .Op Fl O Ar option
  160. .Fl n Ar namespace
  161. .Fl s Ar signature_file
  162. .Nm ssh-keygen
  163. .Fl Y Cm sign
  164. .Op Fl O Ar option
  165. .Fl f Ar key_file
  166. .Fl n Ar namespace
  167. .Ar
  168. .Nm ssh-keygen
  169. .Fl Y Cm verify
  170. .Op Fl O Ar option
  171. .Fl f Ar allowed_signers_file
  172. .Fl I Ar signer_identity
  173. .Fl n Ar namespace
  174. .Fl s Ar signature_file
  175. .Op Fl r Ar revocation_file
  176. .Sh DESCRIPTION
  177. .Nm
  178. generates, manages and converts authentication keys for
  179. .Xr ssh 1 .
  180. .Nm
  181. can create keys for use by SSH protocol version 2.
  182. .Pp
  183. The type of key to be generated is specified with the
  184. .Fl t
  185. option.
  186. If invoked without any arguments,
  187. .Nm
  188. will generate an Ed25519 key.
  189. .Pp
  190. .Nm
  191. is also used to generate groups for use in Diffie-Hellman group
  192. exchange (DH-GEX).
  193. See the
  194. .Sx MODULI GENERATION
  195. section for details.
  196. .Pp
  197. Finally,
  198. .Nm
  199. can be used to generate and update Key Revocation Lists, and to test whether
  200. given keys have been revoked by one.
  201. See the
  202. .Sx KEY REVOCATION LISTS
  203. section for details.
  204. .Pp
  205. Normally each user wishing to use SSH
  206. with public key authentication runs this once to create the authentication
  207. key in
  208. .Pa ~/.ssh/id_ecdsa ,
  209. .Pa ~/.ssh/id_ecdsa_sk ,
  210. .Pa ~/.ssh/id_ed25519 ,
  211. .Pa ~/.ssh/id_ed25519_sk
  212. or
  213. .Pa ~/.ssh/id_rsa .
  214. Additionally, the system administrator may use this to generate host keys,
  215. as seen in
  216. .Pa /etc/rc .
  217. .Pp
  218. Normally this program generates the key and asks for a file in which
  219. to store the private key.
  220. The public key is stored in a file with the same name but
  221. .Dq .pub
  222. appended.
  223. The program also asks for a passphrase.
  224. The passphrase may be empty to indicate no passphrase
  225. (host keys must have an empty passphrase), or it may be a string of
  226. arbitrary length.
  227. A passphrase is similar to a password, except it can be a phrase with a
  228. series of words, punctuation, numbers, whitespace, or any string of
  229. characters you want.
  230. Good passphrases are 10-30 characters long, are
  231. not simple sentences or otherwise easily guessable (English
  232. prose has only 1-2 bits of entropy per character, and provides very bad
  233. passphrases), and contain a mix of upper and lowercase letters,
  234. numbers, and non-alphanumeric characters.
  235. The passphrase can be changed later by using the
  236. .Fl p
  237. option.
  238. .Pp
  239. There is no way to recover a lost passphrase.
  240. If the passphrase is lost or forgotten, a new key must be generated
  241. and the corresponding public key copied to other machines.
  242. .Pp
  243. .Nm
  244. will by default write keys in an OpenSSH-specific format.
  245. This format is preferred as it offers better protection for
  246. keys at rest as well as allowing storage of key comments within
  247. the private key file itself.
  248. The key comment may be useful to help identify the key.
  249. The comment is initialized to
  250. .Dq user@host
  251. when the key is created, but can be changed using the
  252. .Fl c
  253. option.
  254. .Pp
  255. It is still possible for
  256. .Nm
  257. to write the previously-used PEM format private keys using the
  258. .Fl m
  259. flag.
  260. This may be used when generating new keys, and existing new-format
  261. keys may be converted using this option in conjunction with the
  262. .Fl p
  263. (change passphrase) flag.
  264. .Pp
  265. After a key is generated,
  266. .Nm
  267. will ask where the keys
  268. should be placed to be activated.
  269. .Pp
  270. The options are as follows:
  271. .Bl -tag -width Ds
  272. .It Fl A
  273. Generate host keys of all default key types (rsa, ecdsa, and
  274. ed25519) if they do not already exist.
  275. The host keys are generated with the default key file path,
  276. an empty passphrase, default bits for the key type, and default comment.
  277. If
  278. .Fl f
  279. has also been specified, its argument is used as a prefix to the
  280. default path for the resulting host key files.
  281. This is used by
  282. .Pa /etc/rc
  283. to generate new host keys.
  284. .It Fl a Ar rounds
  285. When saving a private key, this option specifies the number of KDF
  286. (key derivation function, currently
  287. .Xr bcrypt_pbkdf 3 )
  288. rounds used.
  289. Higher numbers result in slower passphrase verification and increased
  290. resistance to brute-force password cracking (should the keys be stolen).
  291. The default is 16 rounds.
  292. .It Fl B
  293. Show the bubblebabble digest of specified private or public key file.
  294. .It Fl b Ar bits
  295. Specifies the number of bits in the key to create.
  296. For RSA keys, the minimum size is 1024 bits and the default is 3072 bits.
  297. Generally, 3072 bits is considered sufficient.
  298. For ECDSA keys, the
  299. .Fl b
  300. flag determines the key length by selecting from one of three elliptic
  301. curve sizes: 256, 384 or 521 bits.
  302. Attempting to use bit lengths other than these three values for ECDSA keys
  303. will fail.
  304. ECDSA-SK, Ed25519 and Ed25519-SK keys have a fixed length and the
  305. .Fl b
  306. flag will be ignored.
  307. .It Fl C Ar comment
  308. Provides a new comment.
  309. .It Fl c
  310. Requests changing the comment in the private and public key files.
  311. The program will prompt for the file containing the private keys, for
  312. the passphrase if the key has one, and for the new comment.
  313. .It Fl D Ar pkcs11
  314. Download the public keys provided by the PKCS#11 shared library
  315. .Ar pkcs11 .
  316. When used in combination with
  317. .Fl s ,
  318. this option indicates that a CA key resides in a PKCS#11 token (see the
  319. .Sx CERTIFICATES
  320. section for details).
  321. .It Fl E Ar fingerprint_hash
  322. Specifies the hash algorithm used when displaying key fingerprints.
  323. Valid options are:
  324. .Dq md5
  325. and
  326. .Dq sha256 .
  327. The default is
  328. .Dq sha256 .
  329. .It Fl e
  330. This option will read a private or public OpenSSH key file and
  331. print to stdout a public key in one of the formats specified by the
  332. .Fl m
  333. option.
  334. The default export format is
  335. .Dq RFC4716 .
  336. This option allows exporting OpenSSH keys for use by other programs, including
  337. several commercial SSH implementations.
  338. .It Fl F Ar hostname | [hostname]:port
  339. Search for the specified
  340. .Ar hostname
  341. (with optional port number)
  342. in a
  343. .Pa known_hosts
  344. file, listing any occurrences found.
  345. This option is useful to find hashed host names or addresses and may also be
  346. used in conjunction with the
  347. .Fl H
  348. option to print found keys in a hashed format.
  349. .It Fl f Ar filename
  350. Specifies the filename of the key file.
  351. .It Fl g
  352. Use generic DNS format when printing fingerprint resource records using the
  353. .Fl r
  354. command.
  355. .It Fl H
  356. Hash a
  357. .Pa known_hosts
  358. file.
  359. This replaces all hostnames and addresses with hashed representations
  360. within the specified file; the original content is moved to a file with
  361. a .old suffix.
  362. These hashes may be used normally by
  363. .Nm ssh
  364. and
  365. .Nm sshd ,
  366. but they do not reveal identifying information should the file's contents
  367. be disclosed.
  368. This option will not modify existing hashed hostnames and is therefore safe
  369. to use on files that mix hashed and non-hashed names.
  370. .It Fl h
  371. When signing a key, create a host certificate instead of a user
  372. certificate.
  373. See the
  374. .Sx CERTIFICATES
  375. section for details.
  376. .It Fl I Ar certificate_identity
  377. Specify the key identity when signing a public key.
  378. See the
  379. .Sx CERTIFICATES
  380. section for details.
  381. .It Fl i
  382. This option will read an unencrypted private (or public) key file
  383. in the format specified by the
  384. .Fl m
  385. option and print an OpenSSH compatible private
  386. (or public) key to stdout.
  387. This option allows importing keys from other software, including several
  388. commercial SSH implementations.
  389. The default import format is
  390. .Dq RFC4716 .
  391. .It Fl K
  392. Download resident keys from a FIDO authenticator.
  393. Public and private key files will be written to the current directory for
  394. each downloaded key.
  395. If multiple FIDO authenticators are attached, keys will be downloaded from
  396. the first touched authenticator.
  397. See the
  398. .Sx FIDO AUTHENTICATOR
  399. section for more information.
  400. .It Fl k
  401. Generate a KRL file.
  402. In this mode,
  403. .Nm
  404. will generate a KRL file at the location specified via the
  405. .Fl f
  406. flag that revokes every key or certificate presented on the command line.
  407. Keys/certificates to be revoked may be specified by public key file or
  408. using the format described in the
  409. .Sx KEY REVOCATION LISTS
  410. section.
  411. .It Fl L
  412. Prints the contents of one or more certificates.
  413. .It Fl l
  414. Show fingerprint of specified public key file.
  415. .Nm
  416. will try to find the matching public key file and prints its fingerprint.
  417. If combined with
  418. .Fl v ,
  419. a visual ASCII art representation of the key is supplied with the
  420. fingerprint.
  421. .It Fl M Cm generate
  422. Generate candidate Diffie-Hellman Group Exchange (DH-GEX) parameters for
  423. eventual use by the
  424. .Sq diffie-hellman-group-exchange-*
  425. key exchange methods.
  426. The numbers generated by this operation must be further screened before
  427. use.
  428. See the
  429. .Sx MODULI GENERATION
  430. section for more information.
  431. .It Fl M Cm screen
  432. Screen candidate parameters for Diffie-Hellman Group Exchange.
  433. This will accept a list of candidate numbers and test that they are
  434. safe (Sophie Germain) primes with acceptable group generators.
  435. The results of this operation may be added to the
  436. .Pa /etc/moduli
  437. file.
  438. See the
  439. .Sx MODULI GENERATION
  440. section for more information.
  441. .It Fl m Ar key_format
  442. Specify a key format for key generation, the
  443. .Fl i
  444. (import),
  445. .Fl e
  446. (export) conversion options, and the
  447. .Fl p
  448. change passphrase operation.
  449. The latter may be used to convert between OpenSSH private key and PEM
  450. private key formats.
  451. The supported key formats are:
  452. .Dq RFC4716
  453. (RFC 4716/SSH2 public or private key),
  454. .Dq PKCS8
  455. (PKCS8 public or private key)
  456. or
  457. .Dq PEM
  458. (PEM public key).
  459. By default OpenSSH will write newly-generated private keys in its own
  460. format, but when converting public keys for export the default format is
  461. .Dq RFC4716 .
  462. Setting a format of
  463. .Dq PEM
  464. when generating or updating a supported private key type will cause the
  465. key to be stored in the legacy PEM private key format.
  466. .It Fl N Ar new_passphrase
  467. Provides the new passphrase.
  468. .It Fl n Ar principals
  469. Specify one or more principals (user or host names) to be included in
  470. a certificate when signing a key.
  471. Multiple principals may be specified, separated by commas.
  472. See the
  473. .Sx CERTIFICATES
  474. section for details.
  475. .It Fl O Ar option
  476. Specify a key/value option.
  477. These are specific to the operation that
  478. .Nm
  479. has been requested to perform.
  480. .Pp
  481. When signing certificates, one of the options listed in the
  482. .Sx CERTIFICATES
  483. section may be specified here.
  484. .Pp
  485. When performing moduli generation or screening, one of the options
  486. listed in the
  487. .Sx MODULI GENERATION
  488. section may be specified.
  489. .Pp
  490. When generating FIDO authenticator-backed keys, the options listed in the
  491. .Sx FIDO AUTHENTICATOR
  492. section may be specified.
  493. .Pp
  494. When performing signature-related options using the
  495. .Fl Y
  496. flag, the following options are accepted:
  497. .Bl -tag -width Ds
  498. .It Cm hashalg Ns = Ns Ar algorithm
  499. Selects the hash algorithm to use for hashing the message to be signed.
  500. Valid algorithms are
  501. .Dq sha256
  502. and
  503. .Dq sha512.
  504. The default is
  505. .Dq sha512.
  506. .It Cm print-pubkey
  507. Print the full public key to standard output after signature verification.
  508. .It Cm verify-time Ns = Ns Ar timestamp
  509. Specifies a time to use when validating signatures instead of the current
  510. time.
  511. The time may be specified as a date or time in the YYYYMMDD[Z] or
  512. in YYYYMMDDHHMM[SS][Z] formats.
  513. Dates and times will be interpreted in the current system time zone unless
  514. suffixed with a Z character, which causes them to be interpreted in the
  515. UTC time zone.
  516. .El
  517. .Pp
  518. When generating SSHFP DNS records from public keys using the
  519. .Fl r
  520. flag, the following options are accepted:
  521. .Bl -tag -width Ds
  522. .It Cm hashalg Ns = Ns Ar algorithm
  523. Selects a hash algorithm to use when printing SSHFP records using the
  524. .Fl D
  525. flag.
  526. Valid algorithms are
  527. .Dq sha1
  528. and
  529. .Dq sha256 .
  530. The default is to print both.
  531. .El
  532. .Pp
  533. The
  534. .Fl O
  535. option may be specified multiple times.
  536. .It Fl P Ar passphrase
  537. Provides the (old) passphrase.
  538. .It Fl p
  539. Requests changing the passphrase of a private key file instead of
  540. creating a new private key.
  541. The program will prompt for the file
  542. containing the private key, for the old passphrase, and twice for the
  543. new passphrase.
  544. .It Fl Q
  545. Test whether keys have been revoked in a KRL.
  546. If the
  547. .Fl l
  548. option is also specified then the contents of the KRL will be printed.
  549. .It Fl q
  550. Silence
  551. .Nm ssh-keygen .
  552. .It Fl R Ar hostname | [hostname]:port
  553. Removes all keys belonging to the specified
  554. .Ar hostname
  555. (with optional port number)
  556. from a
  557. .Pa known_hosts
  558. file.
  559. This option is useful to delete hashed hosts (see the
  560. .Fl H
  561. option above).
  562. .It Fl r Ar hostname
  563. Print the SSHFP fingerprint resource record named
  564. .Ar hostname
  565. for the specified public key file.
  566. .It Fl s Ar ca_key
  567. Certify (sign) a public key using the specified CA key.
  568. See the
  569. .Sx CERTIFICATES
  570. section for details.
  571. .Pp
  572. When generating a KRL,
  573. .Fl s
  574. specifies a path to a CA public key file used to revoke certificates directly
  575. by key ID or serial number.
  576. See the
  577. .Sx KEY REVOCATION LISTS
  578. section for details.
  579. .It Fl t Cm ecdsa | ecdsa-sk | ed25519 | ed25519-sk | rsa
  580. Specifies the type of key to create.
  581. The possible values are
  582. .Dq ecdsa ,
  583. .Dq ecdsa-sk ,
  584. .Dq ed25519 (the default),
  585. .Dq ed25519-sk ,
  586. or
  587. .Dq rsa .
  588. .Pp
  589. This flag may also be used to specify the desired signature type when
  590. signing certificates using an RSA CA key.
  591. The available RSA signature variants are
  592. .Dq ssh-rsa
  593. (SHA1 signatures, not recommended),
  594. .Dq rsa-sha2-256 ,
  595. and
  596. .Dq rsa-sha2-512
  597. (the default for RSA keys).
  598. .It Fl U
  599. When used in combination with
  600. .Fl s
  601. or
  602. .Fl Y Cm sign ,
  603. this option indicates that a CA key resides in a
  604. .Xr ssh-agent 1 .
  605. See the
  606. .Sx CERTIFICATES
  607. section for more information.
  608. .It Fl u
  609. Update a KRL.
  610. When specified with
  611. .Fl k ,
  612. keys listed via the command line are added to the existing KRL rather than
  613. a new KRL being created.
  614. .It Fl V Ar validity_interval
  615. Specify a validity interval when signing a certificate.
  616. A validity interval may consist of a single time, indicating that the
  617. certificate is valid beginning now and expiring at that time, or may consist
  618. of two times separated by a colon to indicate an explicit time interval.
  619. .Pp
  620. The start time may be specified as:
  621. .Bl -bullet -compact
  622. .It
  623. The string
  624. .Dq always
  625. to indicate the certificate has no specified start time.
  626. .It
  627. A date or time in the system time zone formatted as YYYYMMDD or
  628. YYYYMMDDHHMM[SS].
  629. .It
  630. A date or time in the UTC time zone as YYYYMMDDZ or YYYYMMDDHHMM[SS]Z.
  631. .It
  632. A relative time before the current system time consisting of a minus sign
  633. followed by an interval in the format described in the
  634. TIME FORMATS section of
  635. .Xr sshd_config 5 .
  636. .It
  637. A raw seconds since epoch (Jan 1 1970 00:00:00 UTC) as a hexadecimal
  638. number beginning with
  639. .Dq 0x .
  640. .El
  641. .Pp
  642. The end time may be specified similarly to the start time:
  643. .Bl -bullet -compact
  644. .It
  645. The string
  646. .Dq forever
  647. to indicate the certificate has no specified end time.
  648. .It
  649. A date or time in the system time zone formatted as YYYYMMDD or
  650. YYYYMMDDHHMM[SS].
  651. .It
  652. A date or time in the UTC time zone as YYYYMMDDZ or YYYYMMDDHHMM[SS]Z.
  653. .It
  654. A relative time after the current system time consisting of a plus sign
  655. followed by an interval in the format described in the
  656. TIME FORMATS section of
  657. .Xr sshd_config 5 .
  658. .It
  659. A raw seconds since epoch (Jan 1 1970 00:00:00 UTC) as a hexadecimal
  660. number beginning with
  661. .Dq 0x .
  662. .El
  663. .Pp
  664. For example:
  665. .Bl -tag -width Ds
  666. .It +52w1d
  667. Valid from now to 52 weeks and one day from now.
  668. .It -4w:+4w
  669. Valid from four weeks ago to four weeks from now.
  670. .It 20100101123000:20110101123000
  671. Valid from 12:30 PM, January 1st, 2010 to 12:30 PM, January 1st, 2011.
  672. .It 20100101123000Z:20110101123000Z
  673. Similar, but interpreted in the UTC time zone rather than the system time zone.
  674. .It -1d:20110101
  675. Valid from yesterday to midnight, January 1st, 2011.
  676. .It 0x1:0x2000000000
  677. Valid from roughly early 1970 to May 2033.
  678. .It -1m:forever
  679. Valid from one minute ago and never expiring.
  680. .El
  681. .It Fl v
  682. Verbose mode.
  683. Causes
  684. .Nm
  685. to print debugging messages about its progress.
  686. This is helpful for debugging moduli generation.
  687. Multiple
  688. .Fl v
  689. options increase the verbosity.
  690. The maximum is 3.
  691. .It Fl w Ar provider
  692. Specifies a path to a library that will be used when creating
  693. FIDO authenticator-hosted keys, overriding the default of using
  694. the internal USB HID support.
  695. .It Fl Y Cm find-principals
  696. Find the principal(s) associated with the public key of a signature,
  697. provided using the
  698. .Fl s
  699. flag in an authorized signers file provided using the
  700. .Fl f
  701. flag.
  702. The format of the allowed signers file is documented in the
  703. .Sx ALLOWED SIGNERS
  704. section below.
  705. If one or more matching principals are found, they are returned on
  706. standard output.
  707. .It Fl Y Cm match-principals
  708. Find principal matching the principal name provided using the
  709. .Fl I
  710. flag in the authorized signers file specified using the
  711. .Fl f
  712. flag.
  713. If one or more matching principals are found, they are returned on
  714. standard output.
  715. .It Fl Y Cm check-novalidate
  716. Checks that a signature generated using
  717. .Nm
  718. .Fl Y Cm sign
  719. has a valid structure.
  720. This does not validate if a signature comes from an authorized signer.
  721. When testing a signature,
  722. .Nm
  723. accepts a message on standard input and a signature namespace using
  724. .Fl n .
  725. A file containing the corresponding signature must also be supplied using the
  726. .Fl s
  727. flag.
  728. Successful testing of the signature is signalled by
  729. .Nm
  730. returning a zero exit status.
  731. .It Fl Y Cm sign
  732. Cryptographically sign a file or some data using an SSH key.
  733. When signing,
  734. .Nm
  735. accepts zero or more files to sign on the command-line - if no files
  736. are specified then
  737. .Nm
  738. will sign data presented on standard input.
  739. Signatures are written to the path of the input file with
  740. .Dq .sig
  741. appended, or to standard output if the message to be signed was read from
  742. standard input.
  743. .Pp
  744. The key used for signing is specified using the
  745. .Fl f
  746. option and may refer to either a private key, or a public key with the private
  747. half available via
  748. .Xr ssh-agent 1 .
  749. An additional signature namespace, used to prevent signature confusion across
  750. different domains of use (e.g. file signing vs email signing) must be provided
  751. via the
  752. .Fl n
  753. flag.
  754. Namespaces are arbitrary strings, and may include:
  755. .Dq file
  756. for file signing,
  757. .Dq email
  758. for email signing.
  759. For custom uses, it is recommended to use names following a
  760. NAMESPACE@YOUR.DOMAIN pattern to generate unambiguous namespaces.
  761. .It Fl Y Cm verify
  762. Request to verify a signature generated using
  763. .Nm
  764. .Fl Y Cm sign
  765. as described above.
  766. When verifying a signature,
  767. .Nm
  768. accepts a message on standard input and a signature namespace using
  769. .Fl n .
  770. A file containing the corresponding signature must also be supplied using the
  771. .Fl s
  772. flag, along with the identity of the signer using
  773. .Fl I
  774. and a list of allowed signers via the
  775. .Fl f
  776. flag.
  777. The format of the allowed signers file is documented in the
  778. .Sx ALLOWED SIGNERS
  779. section below.
  780. A file containing revoked keys can be passed using the
  781. .Fl r
  782. flag.
  783. The revocation file may be a KRL or a one-per-line list of public keys.
  784. Successful verification by an authorized signer is signalled by
  785. .Nm
  786. returning a zero exit status.
  787. .It Fl y
  788. This option will read a private
  789. OpenSSH format file and print an OpenSSH public key to stdout.
  790. .It Fl Z Ar cipher
  791. Specifies the cipher to use for encryption when writing an OpenSSH-format
  792. private key file.
  793. The list of available ciphers may be obtained using
  794. .Qq ssh -Q cipher .
  795. The default is
  796. .Dq aes256-ctr .
  797. .It Fl z Ar serial_number
  798. Specifies a serial number to be embedded in the certificate to distinguish
  799. this certificate from others from the same CA.
  800. If the
  801. .Ar serial_number
  802. is prefixed with a
  803. .Sq +
  804. character, then the serial number will be incremented for each certificate
  805. signed on a single command-line.
  806. The default serial number is zero.
  807. .Pp
  808. When generating a KRL, the
  809. .Fl z
  810. flag is used to specify a KRL version number.
  811. .El
  812. .Sh MODULI GENERATION
  813. .Nm
  814. may be used to generate groups for the Diffie-Hellman Group Exchange
  815. (DH-GEX) protocol.
  816. Generating these groups is a two-step process: first, candidate
  817. primes are generated using a fast, but memory intensive process.
  818. These candidate primes are then tested for suitability (a CPU-intensive
  819. process).
  820. .Pp
  821. Generation of primes is performed using the
  822. .Fl M Cm generate
  823. option.
  824. The desired length of the primes may be specified by the
  825. .Fl O Cm bits
  826. option.
  827. For example:
  828. .Pp
  829. .Dl # ssh-keygen -M generate -O bits=2048 moduli-2048.candidates
  830. .Pp
  831. By default, the search for primes begins at a random point in the
  832. desired length range.
  833. This may be overridden using the
  834. .Fl O Cm start
  835. option, which specifies a different start point (in hex).
  836. .Pp
  837. Once a set of candidates have been generated, they must be screened for
  838. suitability.
  839. This may be performed using the
  840. .Fl M Cm screen
  841. option.
  842. In this mode
  843. .Nm
  844. will read candidates from standard input (or a file specified using the
  845. .Fl f
  846. option).
  847. For example:
  848. .Pp
  849. .Dl # ssh-keygen -M screen -f moduli-2048.candidates moduli-2048
  850. .Pp
  851. By default, each candidate will be subjected to 100 primality tests.
  852. This may be overridden using the
  853. .Fl O Cm prime-tests
  854. option.
  855. The DH generator value will be chosen automatically for the
  856. prime under consideration.
  857. If a specific generator is desired, it may be requested using the
  858. .Fl O Cm generator
  859. option.
  860. Valid generator values are 2, 3, and 5.
  861. .Pp
  862. Screened DH groups may be installed in
  863. .Pa /etc/moduli .
  864. It is important that this file contains moduli of a range of bit lengths.
  865. .Pp
  866. A number of options are available for moduli generation and screening via the
  867. .Fl O
  868. flag:
  869. .Bl -tag -width Ds
  870. .It Ic lines Ns = Ns Ar number
  871. Exit after screening the specified number of lines while performing DH
  872. candidate screening.
  873. .It Ic start-line Ns = Ns Ar line-number
  874. Start screening at the specified line number while performing DH candidate
  875. screening.
  876. .It Ic checkpoint Ns = Ns Ar filename
  877. Write the last line processed to the specified file while performing DH
  878. candidate screening.
  879. This will be used to skip lines in the input file that have already been
  880. processed if the job is restarted.
  881. .It Ic memory Ns = Ns Ar mbytes
  882. Specify the amount of memory to use (in megabytes) when generating
  883. candidate moduli for DH-GEX.
  884. .It Ic start Ns = Ns Ar hex-value
  885. Specify start point (in hex) when generating candidate moduli for DH-GEX.
  886. .It Ic generator Ns = Ns Ar value
  887. Specify desired generator (in decimal) when testing candidate moduli for DH-GEX.
  888. .El
  889. .Sh CERTIFICATES
  890. .Nm
  891. supports signing of keys to produce certificates that may be used for
  892. user or host authentication.
  893. Certificates consist of a public key, some identity information, zero or
  894. more principal (user or host) names and a set of options that
  895. are signed by a Certification Authority (CA) key.
  896. Clients or servers may then trust only the CA key and verify its signature
  897. on a certificate rather than trusting many user/host keys.
  898. Note that OpenSSH certificates are a different, and much simpler, format to
  899. the X.509 certificates used in
  900. .Xr ssl 8 .
  901. .Pp
  902. .Nm
  903. supports two types of certificates: user and host.
  904. User certificates authenticate users to servers, whereas host certificates
  905. authenticate server hosts to users.
  906. To generate a user certificate:
  907. .Pp
  908. .Dl $ ssh-keygen -s /path/to/ca_key -I key_id /path/to/user_key.pub
  909. .Pp
  910. The resultant certificate will be placed in
  911. .Pa /path/to/user_key-cert.pub .
  912. A host certificate requires the
  913. .Fl h
  914. option:
  915. .Pp
  916. .Dl $ ssh-keygen -s /path/to/ca_key -I key_id -h /path/to/host_key.pub
  917. .Pp
  918. The host certificate will be output to
  919. .Pa /path/to/host_key-cert.pub .
  920. .Pp
  921. It is possible to sign using a CA key stored in a PKCS#11 token by
  922. providing the token library using
  923. .Fl D
  924. and identifying the CA key by providing its public half as an argument
  925. to
  926. .Fl s :
  927. .Pp
  928. .Dl $ ssh-keygen -s ca_key.pub -D libpkcs11.so -I key_id user_key.pub
  929. .Pp
  930. Similarly, it is possible for the CA key to be hosted in a
  931. .Xr ssh-agent 1 .
  932. This is indicated by the
  933. .Fl U
  934. flag and, again, the CA key must be identified by its public half.
  935. .Pp
  936. .Dl $ ssh-keygen -Us ca_key.pub -I key_id user_key.pub
  937. .Pp
  938. In all cases,
  939. .Ar key_id
  940. is a "key identifier" that is logged by the server when the certificate
  941. is used for authentication.
  942. .Pp
  943. Certificates may be limited to be valid for a set of principal (user/host)
  944. names.
  945. By default, generated certificates are valid for all users or hosts.
  946. To generate a certificate for a specified set of principals:
  947. .Pp
  948. .Dl $ ssh-keygen -s ca_key -I key_id -n user1,user2 user_key.pub
  949. .Dl "$ ssh-keygen -s ca_key -I key_id -h -n host.domain host_key.pub"
  950. .Pp
  951. Additional limitations on the validity and use of user certificates may
  952. be specified through certificate options.
  953. A certificate option may disable features of the SSH session, may be
  954. valid only when presented from particular source addresses or may
  955. force the use of a specific command.
  956. .Pp
  957. The options that are valid for user certificates are:
  958. .Pp
  959. .Bl -tag -width Ds -compact
  960. .It Ic clear
  961. Clear all enabled permissions.
  962. This is useful for clearing the default set of permissions so permissions may
  963. be added individually.
  964. .Pp
  965. .It Ic critical : Ns Ar name Ns Op Ns = Ns Ar contents
  966. .It Ic extension : Ns Ar name Ns Op Ns = Ns Ar contents
  967. Includes an arbitrary certificate critical option or extension.
  968. The specified
  969. .Ar name
  970. should include a domain suffix, e.g.\&
  971. .Dq name@example.com .
  972. If
  973. .Ar contents
  974. is specified then it is included as the contents of the extension/option
  975. encoded as a string, otherwise the extension/option is created with no
  976. contents (usually indicating a flag).
  977. Extensions may be ignored by a client or server that does not recognise them,
  978. whereas unknown critical options will cause the certificate to be refused.
  979. .Pp
  980. .It Ic force-command Ns = Ns Ar command
  981. Forces the execution of
  982. .Ar command
  983. instead of any shell or command specified by the user when
  984. the certificate is used for authentication.
  985. .Pp
  986. .It Ic no-agent-forwarding
  987. Disable
  988. .Xr ssh-agent 1
  989. forwarding (permitted by default).
  990. .Pp
  991. .It Ic no-port-forwarding
  992. Disable port forwarding (permitted by default).
  993. .Pp
  994. .It Ic no-pty
  995. Disable PTY allocation (permitted by default).
  996. .Pp
  997. .It Ic no-user-rc
  998. Disable execution of
  999. .Pa ~/.ssh/rc
  1000. by
  1001. .Xr sshd 8
  1002. (permitted by default).
  1003. .Pp
  1004. .It Ic no-x11-forwarding
  1005. Disable X11 forwarding (permitted by default).
  1006. .Pp
  1007. .It Ic permit-agent-forwarding
  1008. Allows
  1009. .Xr ssh-agent 1
  1010. forwarding.
  1011. .Pp
  1012. .It Ic permit-port-forwarding
  1013. Allows port forwarding.
  1014. .Pp
  1015. .It Ic permit-pty
  1016. Allows PTY allocation.
  1017. .Pp
  1018. .It Ic permit-user-rc
  1019. Allows execution of
  1020. .Pa ~/.ssh/rc
  1021. by
  1022. .Xr sshd 8 .
  1023. .Pp
  1024. .It Ic permit-X11-forwarding
  1025. Allows X11 forwarding.
  1026. .Pp
  1027. .It Ic no-touch-required
  1028. Do not require signatures made using this key include demonstration
  1029. of user presence (e.g. by having the user touch the authenticator).
  1030. This option only makes sense for the FIDO authenticator algorithms
  1031. .Cm ecdsa-sk
  1032. and
  1033. .Cm ed25519-sk .
  1034. .Pp
  1035. .It Ic source-address Ns = Ns Ar address_list
  1036. Restrict the source addresses from which the certificate is considered valid.
  1037. The
  1038. .Ar address_list
  1039. is a comma-separated list of one or more address/netmask pairs in CIDR
  1040. format.
  1041. .Pp
  1042. .It Ic verify-required
  1043. Require signatures made using this key indicate that the user was first
  1044. verified, e.g. by PIN or on-token biometrics.
  1045. This option only makes sense for the FIDO authenticator algorithms
  1046. .Cm ecdsa-sk
  1047. and
  1048. .Cm ed25519-sk .
  1049. .El
  1050. .Pp
  1051. At present, no standard options are valid for host keys.
  1052. .Pp
  1053. Finally, certificates may be defined with a validity lifetime.
  1054. The
  1055. .Fl V
  1056. option allows specification of certificate start and end times.
  1057. A certificate that is presented at a time outside this range will not be
  1058. considered valid.
  1059. By default, certificates are valid from the
  1060. .Ux
  1061. Epoch to the distant future.
  1062. .Pp
  1063. For certificates to be used for user or host authentication, the CA
  1064. public key must be trusted by
  1065. .Xr sshd 8
  1066. or
  1067. .Xr ssh 1 .
  1068. Refer to those manual pages for details.
  1069. .Sh FIDO AUTHENTICATOR
  1070. .Nm
  1071. is able to generate FIDO authenticator-backed keys, after which
  1072. they may be used much like any other key type supported by OpenSSH, so
  1073. long as the hardware authenticator is attached when the keys are used.
  1074. FIDO authenticators generally require the user to explicitly authorise
  1075. operations by touching or tapping them.
  1076. FIDO keys consist of two parts: a key handle part stored in the
  1077. private key file on disk, and a per-device private key that is unique
  1078. to each FIDO authenticator and that cannot be exported from the
  1079. authenticator hardware.
  1080. These are combined by the hardware at authentication time to derive
  1081. the real key that is used to sign authentication challenges.
  1082. Supported key types are
  1083. .Cm ecdsa-sk
  1084. and
  1085. .Cm ed25519-sk .
  1086. .Pp
  1087. The options that are valid for FIDO keys are:
  1088. .Bl -tag -width Ds
  1089. .It Cm application
  1090. Override the default FIDO application/origin string of
  1091. .Dq ssh: .
  1092. This may be useful when generating host or domain-specific resident keys.
  1093. The specified application string must begin with
  1094. .Dq ssh: .
  1095. .It Cm challenge Ns = Ns Ar path
  1096. Specifies a path to a challenge string that will be passed to the
  1097. FIDO authenticator during key generation.
  1098. The challenge string may be used as part of an out-of-band
  1099. protocol for key enrollment
  1100. (a random challenge is used by default).
  1101. .It Cm device
  1102. Explicitly specify a
  1103. .Xr fido 4
  1104. device to use, rather than letting the authenticator middleware select one.
  1105. .It Cm no-touch-required
  1106. Indicate that the generated private key should not require touch
  1107. events (user presence) when making signatures.
  1108. Note that
  1109. .Xr sshd 8
  1110. will refuse such signatures by default, unless overridden via
  1111. an authorized_keys option.
  1112. .It Cm resident
  1113. Indicate that the key handle should be stored on the FIDO
  1114. authenticator itself.
  1115. This makes it easier to use the authenticator on multiple computers.
  1116. Resident keys may be supported on FIDO2 authenticators and typically
  1117. require that a PIN be set on the authenticator prior to generation.
  1118. Resident keys may be loaded off the authenticator using
  1119. .Xr ssh-add 1 .
  1120. Storing both parts of a key on a FIDO authenticator increases the likelihood
  1121. of an attacker being able to use a stolen authenticator device.
  1122. .It Cm user
  1123. A username to be associated with a resident key,
  1124. overriding the empty default username.
  1125. Specifying a username may be useful when generating multiple resident keys
  1126. for the same application name.
  1127. .It Cm verify-required
  1128. Indicate that this private key should require user verification for
  1129. each signature.
  1130. Not all FIDO authenticators support this option.
  1131. Currently PIN authentication is the only supported verification method,
  1132. but other methods may be supported in the future.
  1133. .It Cm write-attestation Ns = Ns Ar path
  1134. May be used at key generation time to record the attestation data
  1135. returned from FIDO authenticators during key generation.
  1136. This information is potentially sensitive.
  1137. By default, this information is discarded.
  1138. .El
  1139. .Sh KEY REVOCATION LISTS
  1140. .Nm
  1141. is able to manage OpenSSH format Key Revocation Lists (KRLs).
  1142. These binary files specify keys or certificates to be revoked using a
  1143. compact format, taking as little as one bit per certificate if they are being
  1144. revoked by serial number.
  1145. .Pp
  1146. KRLs may be generated using the
  1147. .Fl k
  1148. flag.
  1149. This option reads one or more files from the command line and generates a new
  1150. KRL.
  1151. The files may either contain a KRL specification (see below) or public keys,
  1152. listed one per line.
  1153. Plain public keys are revoked by listing their hash or contents in the KRL and
  1154. certificates revoked by serial number or key ID (if the serial is zero or
  1155. not available).
  1156. .Pp
  1157. Revoking keys using a KRL specification offers explicit control over the
  1158. types of record used to revoke keys and may be used to directly revoke
  1159. certificates by serial number or key ID without having the complete original
  1160. certificate on hand.
  1161. A KRL specification consists of lines containing one of the following directives
  1162. followed by a colon and some directive-specific information.
  1163. .Bl -tag -width Ds
  1164. .It Cm serial : Ar serial_number Ns Op - Ns Ar serial_number
  1165. Revokes a certificate with the specified serial number.
  1166. Serial numbers are 64-bit values, not including zero and may be expressed
  1167. in decimal, hex or octal.
  1168. If two serial numbers are specified separated by a hyphen, then the range
  1169. of serial numbers including and between each is revoked.
  1170. The CA key must have been specified on the
  1171. .Nm
  1172. command line using the
  1173. .Fl s
  1174. option.
  1175. .It Cm id : Ar key_id
  1176. Revokes a certificate with the specified key ID string.
  1177. The CA key must have been specified on the
  1178. .Nm
  1179. command line using the
  1180. .Fl s
  1181. option.
  1182. .It Cm key : Ar public_key
  1183. Revokes the specified key.
  1184. If a certificate is listed, then it is revoked as a plain public key.
  1185. .It Cm sha1 : Ar public_key
  1186. Revokes the specified key by including its SHA1 hash in the KRL.
  1187. .It Cm sha256 : Ar public_key
  1188. Revokes the specified key by including its SHA256 hash in the KRL.
  1189. KRLs that revoke keys by SHA256 hash are not supported by OpenSSH versions
  1190. prior to 7.9.
  1191. .It Cm hash : Ar fingerprint
  1192. Revokes a key using a fingerprint hash, as obtained from a
  1193. .Xr sshd 8
  1194. authentication log message or the
  1195. .Nm
  1196. .Fl l
  1197. flag.
  1198. Only SHA256 fingerprints are supported here and resultant KRLs are
  1199. not supported by OpenSSH versions prior to 7.9.
  1200. .El
  1201. .Pp
  1202. KRLs may be updated using the
  1203. .Fl u
  1204. flag in addition to
  1205. .Fl k .
  1206. When this option is specified, keys listed via the command line are merged into
  1207. the KRL, adding to those already there.
  1208. .Pp
  1209. It is also possible, given a KRL, to test whether it revokes a particular key
  1210. (or keys).
  1211. The
  1212. .Fl Q
  1213. flag will query an existing KRL, testing each key specified on the command line.
  1214. If any key listed on the command line has been revoked (or an error encountered)
  1215. then
  1216. .Nm
  1217. will exit with a non-zero exit status.
  1218. A zero exit status will only be returned if no key was revoked.
  1219. .Sh ALLOWED SIGNERS
  1220. When verifying signatures,
  1221. .Nm
  1222. uses a simple list of identities and keys to determine whether a signature
  1223. comes from an authorized source.
  1224. This "allowed signers" file uses a format patterned after the
  1225. AUTHORIZED_KEYS FILE FORMAT described in
  1226. .Xr sshd 8 .
  1227. Each line of the file contains the following space-separated fields:
  1228. principals, options, keytype, base64-encoded key.
  1229. Empty lines and lines starting with a
  1230. .Ql #
  1231. are ignored as comments.
  1232. .Pp
  1233. The principals field is a pattern-list (see PATTERNS in
  1234. .Xr ssh_config 5 )
  1235. consisting of one or more comma-separated USER@DOMAIN identity patterns
  1236. that are accepted for signing.
  1237. When verifying, the identity presented via the
  1238. .Fl I
  1239. option must match a principals pattern in order for the corresponding key to be
  1240. considered acceptable for verification.
  1241. .Pp
  1242. The options (if present) consist of comma-separated option specifications.
  1243. No spaces are permitted, except within double quotes.
  1244. The following option specifications are supported (note that option keywords
  1245. are case-insensitive):
  1246. .Bl -tag -width Ds
  1247. .It Cm cert-authority
  1248. Indicates that this key is accepted as a certificate authority (CA) and
  1249. that certificates signed by this CA may be accepted for verification.
  1250. .It Cm namespaces Ns = Ns "namespace-list"
  1251. Specifies a pattern-list of namespaces that are accepted for this key.
  1252. If this option is present, the signature namespace embedded in the
  1253. signature object and presented on the verification command-line must
  1254. match the specified list before the key will be considered acceptable.
  1255. .It Cm valid-after Ns = Ns "timestamp"
  1256. Indicates that the key is valid for use at or after the specified timestamp,
  1257. which may be a date or time in the YYYYMMDD[Z] or YYYYMMDDHHMM[SS][Z] formats.
  1258. Dates and times will be interpreted in the current system time zone unless
  1259. suffixed with a Z character, which causes them to be interpreted in the UTC
  1260. time zone.
  1261. .It Cm valid-before Ns = Ns "timestamp"
  1262. Indicates that the key is valid for use at or before the specified timestamp.
  1263. .El
  1264. .Pp
  1265. When verifying signatures made by certificates, the expected principal
  1266. name must match both the principals pattern in the allowed signers file and
  1267. the principals embedded in the certificate itself.
  1268. .Pp
  1269. An example allowed signers file:
  1270. .Bd -literal -offset 3n
  1271. # Comments allowed at start of line
  1272. user1@example.com,user2@example.com ssh-rsa AAAAX1...
  1273. # A certificate authority, trusted for all principals in a domain.
  1274. *@example.com cert-authority ssh-ed25519 AAAB4...
  1275. # A key that is accepted only for file signing.
  1276. user2@example.com namespaces="file" ssh-ed25519 AAA41...
  1277. .Ed
  1278. .Sh ENVIRONMENT
  1279. .Bl -tag -width Ds
  1280. .It Ev SSH_SK_PROVIDER
  1281. Specifies a path to a library that will be used when loading any
  1282. FIDO authenticator-hosted keys, overriding the default of using
  1283. the built-in USB HID support.
  1284. .El
  1285. .Sh FILES
  1286. .Bl -tag -width Ds -compact
  1287. .It Pa ~/.ssh/id_ecdsa
  1288. .It Pa ~/.ssh/id_ecdsa_sk
  1289. .It Pa ~/.ssh/id_ed25519
  1290. .It Pa ~/.ssh/id_ed25519_sk
  1291. .It Pa ~/.ssh/id_rsa
  1292. Contains the ECDSA, authenticator-hosted ECDSA, Ed25519,
  1293. authenticator-hosted Ed25519 or RSA authentication identity of the user.
  1294. This file should not be readable by anyone but the user.
  1295. It is possible to
  1296. specify a passphrase when generating the key; that passphrase will be
  1297. used to encrypt the private part of this file using 128-bit AES.
  1298. This file is not automatically accessed by
  1299. .Nm
  1300. but it is offered as the default file for the private key.
  1301. .Xr ssh 1
  1302. will read this file when a login attempt is made.
  1303. .Pp
  1304. .It Pa ~/.ssh/id_ecdsa.pub
  1305. .It Pa ~/.ssh/id_ecdsa_sk.pub
  1306. .It Pa ~/.ssh/id_ed25519.pub
  1307. .It Pa ~/.ssh/id_ed25519_sk.pub
  1308. .It Pa ~/.ssh/id_rsa.pub
  1309. Contains the ECDSA, authenticator-hosted ECDSA, Ed25519,
  1310. authenticator-hosted Ed25519 or RSA public key for authentication.
  1311. The contents of this file should be added to
  1312. .Pa ~/.ssh/authorized_keys
  1313. on all machines
  1314. where the user wishes to log in using public key authentication.
  1315. There is no need to keep the contents of this file secret.
  1316. .Pp
  1317. .It Pa /etc/moduli
  1318. Contains Diffie-Hellman groups used for DH-GEX.
  1319. The file format is described in
  1320. .Xr moduli 5 .
  1321. .El
  1322. .Sh SEE ALSO
  1323. .Xr ssh 1 ,
  1324. .Xr ssh-add 1 ,
  1325. .Xr ssh-agent 1 ,
  1326. .Xr moduli 5 ,
  1327. .Xr sshd 8
  1328. .Rs
  1329. .%R RFC 4716
  1330. .%T "The Secure Shell (SSH) Public Key File Format"
  1331. .%D 2006
  1332. .Re
  1333. .Sh AUTHORS
  1334. OpenSSH is a derivative of the original and free
  1335. ssh 1.2.12 release by Tatu Ylonen.
  1336. Aaron Campbell, Bob Beck, Markus Friedl, Niels Provos,
  1337. Theo de Raadt and Dug Song
  1338. removed many bugs, re-added newer features and
  1339. created OpenSSH.
  1340. Markus Friedl contributed the support for SSH
  1341. protocol versions 1.5 and 2.0.