1 files changed, 70 insertions, 50 deletions

diff --git a/ssh-keygen.1 b/ssh-keygen.1
index 01711dfff..dfbc65ddb 100644
--- a/ssh-keygen.1
+++ b/ssh-keygen.1
@@ -1,4 +1,4 @@
-.\"     $OpenBSD: ssh-keygen.1,v 1.133 2016/06/16 06:10:45 jmc Exp $
+.\"     $OpenBSD: ssh-keygen.1,v 1.144 2017/07/08 18:32:54 jmc 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 16 2016 $
+.Dd $Mdocdate: July 8 2017 $
 .Dt SSH-KEYGEN 1
 .Os
 .Sh NAME
@@ -46,7 +46,7 @@
 .Nm ssh-keygen
 .Op Fl q
 .Op Fl b Ar bits
-.Op Fl t Cm dsa | ecdsa | ed25519 | rsa | rsa1
+.Op Fl t Cm dsa | ecdsa | ed25519 | rsa
 .Op Fl N Ar new_passphrase
 .Op Fl C Ar comment
 .Op Fl f Ar output_keyfile
@@ -114,6 +114,8 @@
 .Fl s Ar ca_key
 .Fl I Ar certificate_identity
 .Op Fl h
+.Op Fl U
+.Op Fl D Ar pkcs11_provider
 .Op Fl n Ar principals
 .Op Fl O Ar option
 .Op Fl V Ar validity_interval
@@ -124,6 +126,7 @@
 .Op Fl f Ar input_keyfile
 .Nm ssh-keygen
 .Fl A
+.Op Fl f Ar prefix_path
 .Nm ssh-keygen
 .Fl k
 .Fl f Ar krl_file
@@ -141,18 +144,14 @@
 generates, manages and converts authentication keys for
 .Xr ssh 1 .
 .Nm
-can create keys for use by SSH protocol versions 1 and 2.
-Protocol 1 should not be used
-and is only offered to support legacy devices.
-It suffers from a number of cryptographic weaknesses
-and doesn't support many of the advanced features available for protocol 2.
+can create keys for use by SSH protocol version 2.
 .Pp
 The type of key to be generated is specified with the
 .Fl t
 option.
 If invoked without any arguments,
 .Nm
-will generate an RSA key for use in SSH protocol 2 connections.
+will generate an RSA key.
 .Pp
 .Nm
 is also used to generate groups for use in Diffie-Hellman group
@@ -172,7 +171,6 @@ section for details.
 Normally each user wishing to use SSH
 with public key authentication runs this once to create the authentication
 key in
-.Pa ~/.ssh/identity ,
 .Pa ~/.ssh/id_dsa ,
 .Pa ~/.ssh/id_ecdsa ,
 .Pa ~/.ssh/id_ed25519
@@ -205,7 +203,7 @@ 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 RSA1 keys and keys stored in the newer OpenSSH format,
+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.
@@ -221,22 +219,24 @@ should be placed to be activated.
 The options are as follows:
 .Bl -tag -width Ds
 .It Fl A
-For each of the key types (rsa1, rsa, dsa, ecdsa and ed25519)
+For each of the key types (rsa, dsa, ecdsa and ed25519)
 for which host keys
 do not exist, generate the host keys with the default key file path,
 an empty passphrase, default bits for the key type, and default comment.
+If
+.Fl f
+has also been specified, its argument is used as a prefix to the
+default path for the resulting host key files.
 This is used by system administration scripts to generate new host keys.
 .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
+When saving a new-format private key (i.e. an ed25519 key or 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
+When screening DH-GEX candidates (using the
 .Fl T
 command).
 This option specifies the number of primality tests to perform.
@@ -260,7 +260,7 @@ flag will be ignored.
 Provides a new comment.
 .It Fl c
 Requests changing the comment in the private and public key files.
-This operation is only supported for RSA1 keys and keys stored in the
+This operation is only supported for keys stored in the
 newer OpenSSH format.
 The program will prompt for the file containing the private keys, for
 the passphrase if the key has one, and for the new comment.
@@ -380,7 +380,6 @@ section.
 Prints the contents of one or more certificates.
 .It Fl l
 Show fingerprint of specified public key file.
-Private RSA1 keys are also supported.
 For RSA and DSA keys
 .Nm
 tries to find the matching public key file and prints its fingerprint.
@@ -419,51 +418,81 @@ section for details.
 .It Fl O Ar option
 Specify a certificate option when signing a key.
 This option may be specified multiple times.
-Please see the
+See also the
 .Sx CERTIFICATES
-section for details.
+section for further details.
 The options that are valid for user certificates are:
-.Bl -tag -width Ds
+.Pp
+.Bl -tag -width Ds -compact
 .It Ic clear
 Clear all enabled permissions.
 This is useful for clearing the default set of permissions so permissions may
 be added individually.
+.Pp
+.It Ic critical : Ns Ar name Ns Op Ns = Ns Ar contents
+.It Ic extension : Ns Ar name Ns Op Ns = Ns Ar contents
+Includes an arbitrary certificate critical option or extension.
+The specified
+.Ar name
+should include a domain suffix, e.g.\&
+.Dq name@example.com .
+If
+.Ar contents
+is specified then it is included as the contents of the extension/option
+encoded as a string, otherwise the extension/option is created with no
+contents (usually indicating a flag).
+Extensions may be ignored by a client or server that does not recognise them,
+whereas unknown critical options will cause the certificate to be refused.
+.Pp
+At present, no standard options are valid for host keys.
+.Pp
 .It Ic force-command Ns = Ns Ar command
 Forces the execution of
 .Ar command
 instead of any shell or command specified by the user when
 the certificate is used for authentication.
+.Pp
 .It Ic no-agent-forwarding
 Disable
 .Xr ssh-agent 1
 forwarding (permitted by default).
+.Pp
 .It Ic no-port-forwarding
 Disable port forwarding (permitted by default).
+.Pp
 .It Ic no-pty
 Disable PTY allocation (permitted by default).
+.Pp
 .It Ic no-user-rc
 Disable execution of
 .Pa ~/.ssh/rc
 by
 .Xr sshd 8
 (permitted by default).
+.Pp
 .It Ic no-x11-forwarding
 Disable X11 forwarding (permitted by default).
+.Pp
 .It Ic permit-agent-forwarding
 Allows
 .Xr ssh-agent 1
 forwarding.
+.Pp
 .It Ic permit-port-forwarding
 Allows port forwarding.
+.Pp
 .It Ic permit-pty
 Allows PTY allocation.
+.Pp
 .It Ic permit-user-rc
 Allows execution of
 .Pa ~/.ssh/rc
 by
 .Xr sshd 8 .
+.Pp
 .It Ic permit-x11-forwarding
 Allows X11 forwarding.
+.Pp
 .It Ic source-address Ns = Ns Ar address_list
 Restrict the source addresses from which the certificate is considered valid.
 The
@@ -471,8 +500,6 @@ The
 is a comma-separated list of one or more address/netmask pairs in CIDR
 format.
 .El
-.Pp
-At present, no options are valid for host keys.
 .It Fl o
 Causes
 .Nm
@@ -526,17 +553,22 @@ section for details.
 Test DH group exchange candidate primes (generated using the
 .Fl G
 option) for safety.
-.It Fl t Cm dsa | ecdsa | ed25519 | rsa | rsa1
+.It Fl t Cm dsa | ecdsa | ed25519 | rsa
 Specifies the type of key to create.
 The possible values are
-.Dq rsa1
-for protocol version 1 and
 .Dq dsa ,
 .Dq ecdsa ,
 .Dq ed25519 ,
 or
-.Dq rsa
-for protocol version 2.
+.Dq rsa .
+.It Fl U
+When used in combination with
+.Fl s ,
+this option indicates that a CA key resides in a
+.Xr ssh-agent 1 .
+See the
+.Sx CERTIFICATES
+section for more information.
 .It Fl u
 Update a KRL.
 When specified with
@@ -684,6 +716,14 @@ to
 .Pp
 .Dl $ ssh-keygen -s ca_key.pub -D libpkcs11.so -I key_id user_key.pub
 .Pp
+Similarly, it is possible for the CA key to be hosted in a
+.Xr ssh-agent 1 .
+This is indicated by the
+.Fl U
+flag and, again, the CA key must be identified by its public half.
+.Pp
+.Dl $ ssh-keygen -Us ca_key.pub -I key_id user_key.pub
+.Pp
 In all cases,
 .Ar key_id
 is a "key identifier" that is logged by the server when the certificate
@@ -791,31 +831,11 @@ will exit with a non-zero exit status.
 A zero exit status will only be returned if no key was revoked.
 .Sh FILES
 .Bl -tag -width Ds -compact
-.It Pa ~/.ssh/identity
-Contains the protocol version 1 RSA authentication identity of the user.
-This file should not be readable by anyone but the user.
-It is possible to
-specify a passphrase when generating the key; that passphrase will be
-used to encrypt the private part of this file using 3DES.
-This file is not automatically accessed by
-.Nm
-but it is offered as the default file for the private key.
-.Xr ssh 1
-will read this file when a login attempt is made.
-.Pp
-.It Pa ~/.ssh/identity.pub
-Contains the protocol version 1 RSA public key for authentication.
-The contents of this file should be added to
-.Pa ~/.ssh/authorized_keys
-on all machines
-where the user wishes to log in using RSA authentication.
-There is no need to keep the contents of this file secret.
-.Pp
 .It Pa ~/.ssh/id_dsa
 .It Pa ~/.ssh/id_ecdsa
 .It Pa ~/.ssh/id_ed25519
 .It Pa ~/.ssh/id_rsa
-Contains the protocol version 2 DSA, ECDSA, Ed25519 or RSA
+Contains the DSA, ECDSA, Ed25519 or RSA
 authentication identity of the user.
 This file should not be readable by anyone but the user.
 It is possible to
@@ -831,7 +851,7 @@ will read this file when a login attempt is made.
 .It Pa ~/.ssh/id_ecdsa.pub
 .It Pa ~/.ssh/id_ed25519.pub
 .It Pa ~/.ssh/id_rsa.pub
-Contains the protocol version 2 DSA, ECDSA, Ed25519 or RSA
+Contains the DSA, ECDSA, Ed25519 or RSA
 public key for authentication.
 The contents of this file should be added to
 .Pa ~/.ssh/authorized_keys