===================================================================
RCS file: /cvsrepo/anoncvs/cvs/src/usr.bin/ssh/ssh-keygen.1,v
retrieving revision 1.152
retrieving revision 1.153
diff -u -r1.152 -r1.153
--- src/usr.bin/ssh/ssh-keygen.1	2018/12/07 03:33:18	1.152
+++ src/usr.bin/ssh/ssh-keygen.1	2019/01/22 11:00:15	1.153
@@ -1,4 +1,4 @@
-.\"	$OpenBSD: ssh-keygen.1,v 1.152 2018/12/07 03:33:18 djm Exp $
+.\"	$OpenBSD: ssh-keygen.1,v 1.153 2019/01/22 11:00:15 djm 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: December 7 2018 $
+.Dd $Mdocdate: January 22 2019 $
 .Dt SSH-KEYGEN 1
 .Os
 .Sh NAME
@@ -205,15 +205,27 @@
 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.