- djm@cvs.openbsd.org 2013/12/07 08:08:26

     [ssh-keygen.1]
     document -a and -o wrt new key format

1 files changed, 24 insertions, 7 deletions

diff --git a/ssh-keygen.1 b/ssh-keygen.1
index 0d55854e9..689db22ff 100644
--- a/ssh-keygen.1
+++ b/ssh-keygen.1
@@ -1,4 +1,4 @@
-.\"     $OpenBSD: ssh-keygen.1,v 1.116 2013/06/27 14:05:37 jmc Exp $
+.\"     $OpenBSD: ssh-keygen.1,v 1.117 2013/12/07 08:08:26 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: June 27 2013 $
+.Dd $Mdocdate: December 7 2013 $
 .Dt SSH-KEYGEN 1
 .Os
 .Sh NAME
@@ -103,7 +103,7 @@
 .Fl T Ar output_file
 .Fl f Ar input_file
 .Op Fl v
-.Op Fl a Ar num_trials
+.Op Fl a Ar rounds
 .Op Fl J Ar num_lines
 .Op Fl j Ar start_line
 .Op Fl K Ar checkpt
@@ -222,11 +222,20 @@ an empty passphrase, default bits for the key type, and default comment.
 This is used by
 .Pa /etc/rc
 to generate new host keys.
-.It Fl a Ar trials
-Specifies the number of primality tests to perform when screening DH-GEX
-candidates using the
+.It Fl a Ar rounds
+When saving a new-format private key (i.e. an ed25519 key or any SSH protocol
+2 key when the
+.Fl o
+flag is set), this option specifies the number of KDF (key derivation function)
+rounds used.
+Higher numbers result in slower passphrase verification and increased
+resistance to brute-force password cracking (should the keys be stolen).
+.Pp
+When screening DH-GEX candidates (
+using the
 .Fl T
-command.
+command).
+This option specifies the number of primality tests to perform.
 .It Fl B
 Show the bubblebabble digest of specified private or public key file.
 .It Fl b Ar bits
@@ -447,6 +456,14 @@ format.
 .El
 .Pp
 At present, no options are valid for host keys.
+.It Fl o
+Causes
+.Nm
+to save SSH protocol 2 private keys using the new OpenSSH format rather than
+the more compatible PEM format.
+The new format has increased resistance to brute-force password cracking
+but is not supported by versions of OpenSSH prior to 6.5.
+Ed25519 keys always use the new private key format.
 .It Fl P Ar passphrase
 Provides the (old) passphrase.
 .It Fl p