1 files changed, 40 insertions, 14 deletions

diff --git a/ssh-keygen.1 b/ssh-keygen.1
index bfa2eb5f3..124456577 100644
--- a/ssh-keygen.1
+++ b/ssh-keygen.1
@@ -1,4 +1,4 @@
-.\"     $OpenBSD: ssh-keygen.1,v 1.150 2018/09/12 06:18:59 djm Exp $
+.\"     $OpenBSD: ssh-keygen.1,v 1.157 2019/03/05 16:17:12 naddy Exp $
 .\"
 .\" Author: Tatu Ylonen <ylo@cs.hut.fi>
 .\" Copyright (c) 1995 Tatu Ylonen <ylo@cs.hut.fi>, Espoo, Finland
@@ -35,7 +35,7 @@
 .\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
 .\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 .\"
-.Dd $Mdocdate: September 12 2018 $
+.Dd $Mdocdate: March 5 2019 $
 .Dt SSH-KEYGEN 1
 .Os
 .Sh NAME
@@ -50,11 +50,13 @@
 .Op Fl N Ar new_passphrase
 .Op Fl C Ar comment
 .Op Fl f Ar output_keyfile
+.Op Fl m Ar format
 .Nm ssh-keygen
 .Fl p
 .Op Fl P Ar old_passphrase
 .Op Fl N Ar new_passphrase
 .Op Fl f Ar keyfile
+.Op Fl m Ar format
 .Nm ssh-keygen
 .Fl i
 .Op Fl m Ar key_format
@@ -205,16 +207,28 @@ There is no way to recover a lost passphrase.
 If the passphrase is lost or forgotten, a new key must be generated
 and the corresponding public key copied to other machines.
 .Pp
-For keys stored in the newer OpenSSH format,
-there is also a comment field in the key file that is only for
-convenience to the user to help identify the key.
-The comment can tell what the key is for, or whatever is useful.
+.Nm
+will by default write keys in an OpenSSH-specific format.
+This format is preferred as it offers better protection for
+keys at rest as well as allowing storage of key comments within
+the private key file itself.
+The key comment may be useful to help identify the key.
 The comment is initialized to
 .Dq user@host
 when the key is created, but can be changed using the
 .Fl c
 option.
 .Pp
+It is still possible for
+.Nm
+to write the previously-used PEM format private keys using the
+.Fl m
+flag.
+This may be used when generating new keys, and existing new-format
+keys may be converted using this option in conjunction with the
+.Fl p
+(change passphrase) flag.
+.Pp
 After a key is generated, instructions below detail where the keys
 should be placed to be activated.
 .Pp
@@ -265,7 +279,7 @@ Requests changing the comment in the private and public key files.
 The program will prompt for the file containing the private keys, for
 the passphrase if the key has one, and for the new comment.
 .It Fl D Ar pkcs11
-Download the RSA public keys provided by the PKCS#11 shared library
+Download the public keys provided by the PKCS#11 shared library
 .Ar pkcs11 .
 When used in combination with
 .Fl s ,
@@ -282,16 +296,17 @@ The default is
 .Dq sha256 .
 .It Fl e
 This option will read a private or public OpenSSH key file and
-print to stdout the key in one of the formats specified by the
+print to stdout a public key in one of the formats specified by the
 .Fl m
 option.
 The default export format is
 .Dq RFC4716 .
 This option allows exporting OpenSSH keys for use by other programs, including
 several commercial SSH implementations.
-.It Fl F Ar hostname
+.It Fl F Ar hostname | [hostname]:port
 Search for the specified
 .Ar hostname
+(with optional port number)
 in a
 .Pa known_hosts
 file, listing any occurrences found.
@@ -391,11 +406,15 @@ fingerprint.
 Specify the amount of memory to use (in megabytes) when generating
 candidate moduli for DH-GEX.
 .It Fl m Ar key_format
-Specify a key format for the
+Specify a key format for key generation, the
 .Fl i
-(import) or
+(import),
 .Fl e
-(export) conversion options.
+(export) conversion options, and the
+.Fl p
+change passphrase operation.
+The latter may be used to convert between OpenSSH private key and PEM
+private key formats.
 The supported key formats are:
 .Dq RFC4716
 (RFC 4716/SSH2 public or private key),
@@ -517,9 +536,10 @@ Test whether keys have been revoked in a KRL.
 .It Fl q
 Silence
 .Nm ssh-keygen .
-.It Fl R Ar hostname
-Removes all keys belonging to
+.It Fl R Ar hostname | [hostname]:port
+Removes all keys belonging to the specified
 .Ar hostname
+(with optional port number)
 from a
 .Pa known_hosts
 file.
@@ -620,6 +640,12 @@ OpenSSH format file and print an OpenSSH public key to stdout.
 .It Fl z Ar serial_number
 Specifies a serial number to be embedded in the certificate to distinguish
 this certificate from others from the same CA.
+If the
+.Ar serial_number
+is prefixed with a
+.Sq +
+character, then the serial number will be incremented for each certificate
+signed on a single command-line.
 The default serial number is zero.
 .Pp
 When generating a KRL, the