upstream: mention the new vs. old key formats in the introduction

and give some hints on how keys may be converted or written in the old
format.

OpenBSD-Commit-ID: 9c90a9f92eddc249e07fad1204d0e15c8aa13823

1 files changed, 18 insertions, 6 deletions

diff --git a/ssh-keygen.1 b/ssh-keygen.1
index 8e96d9014..56815e272 100644
--- a/ssh-keygen.1
+++ b/ssh-keygen.1
@@ -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,16 +205,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