Vendor import of OpenSSH 7.6p1.vendor/openssh/7.6p1

1 files changed, 82 insertions, 79 deletions

diff --git a/ssh-keygen.0 b/ssh-keygen.0
index 569297da42ed..fb2c02fe7f90 100644
--- a/ssh-keygen.0
+++ b/ssh-keygen.0
@@ -4,7 +4,7 @@ NAME
      ssh-keygen M-bM-^@M-^S authentication key generation, management and conversion
 
 SYNOPSIS
-     ssh-keygen [-q] [-b bits] [-t dsa | ecdsa | ed25519 | rsa | rsa1]
+     ssh-keygen [-q] [-b bits] [-t dsa | ecdsa | ed25519 | rsa]
                 [-N new_passphrase] [-C comment] [-f output_keyfile]
      ssh-keygen -p [-P old_passphrase] [-N new_passphrase] [-f keyfile]
      ssh-keygen -i [-m key_format] [-f input_keyfile]
@@ -21,24 +21,21 @@ SYNOPSIS
      ssh-keygen -G output_file [-v] [-b bits] [-M memory] [-S start_point]
      ssh-keygen -T output_file -f input_file [-v] [-a rounds] [-J num_lines]
                 [-j start_line] [-K checkpt] [-W generator]
-     ssh-keygen -s ca_key -I certificate_identity [-h] [-n principals]
-                [-O option] [-V validity_interval] [-z serial_number] file ...
+     ssh-keygen -s ca_key -I certificate_identity [-h] [-U]
+                [-D pkcs11_provider] [-n principals] [-O option]
+                [-V validity_interval] [-z serial_number] file ...
      ssh-keygen -L [-f input_keyfile]
-     ssh-keygen -A
+     ssh-keygen -A [-f prefix_path]
      ssh-keygen -k -f krl_file [-u] [-s ca_public] [-z version_number]
                 file ...
      ssh-keygen -Q -f krl_file file ...
 
 DESCRIPTION
      ssh-keygen generates, manages and converts authentication keys for
-     ssh(1).  ssh-keygen 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.
+     ssh(1).  ssh-keygen can create keys for use by SSH protocol version 2.
 
      The type of key to be generated is specified with the -t option.  If
-     invoked without any arguments, ssh-keygen will generate an RSA key for
-     use in SSH protocol 2 connections.
+     invoked without any arguments, ssh-keygen will generate an RSA key.
 
      ssh-keygen is also used to generate groups for use in Diffie-Hellman
      group exchange (DH-GEX).  See the MODULI GENERATION section for details.
@@ -48,10 +45,10 @@ DESCRIPTION
      KEY REVOCATION LISTS section for details.
 
      Normally each user wishing to use SSH with public key authentication runs
-     this once to create the authentication key in ~/.ssh/identity,
-     ~/.ssh/id_dsa, ~/.ssh/id_ecdsa, ~/.ssh/id_ed25519 or ~/.ssh/id_rsa.
-     Additionally, the system administrator may use this to generate host
-     keys, as seen in /etc/rc.
+     this once to create the authentication key in ~/.ssh/id_dsa,
+     ~/.ssh/id_ecdsa, ~/.ssh/id_ed25519 or ~/.ssh/id_rsa.  Additionally, the
+     system administrator may use this to generate host keys, as seen in
+     /etc/rc.
 
      Normally this program generates the key and asks for a file in which to
      store the private key.  The public key is stored in a file with the same
@@ -71,32 +68,33 @@ DESCRIPTION
      or forgotten, a new key must be generated and the corresponding public
      key copied to other machines.
 
-     For RSA1 keys and 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.  The comment is initialized to M-bM-^@M-^\user@hostM-bM-^@M-^] when the
-     key is created, but can be changed using the -c option.
+     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.  The comment is initialized to M-bM-^@M-^\user@hostM-bM-^@M-^] when the key is
+     created, but can be changed using the -c option.
 
      After a key is generated, instructions below detail where the keys should
      be placed to be activated.
 
      The options are as follows:
 
-     -A      For each of the key types (rsa1, 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.  This is used by /etc/rc to
-             generate new host keys.
+     -A      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 -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 /etc/rc to generate
+             new host keys.
 
      -a rounds
-             When saving a new-format private key (i.e. an ed25519 key or any
-             SSH protocol 2 key when the -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).
-
-             When screening DH-GEX candidates ( using the -T command).  This
+             When saving a new-format private key (i.e. an ed25519 key or when
+             the -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).
+
+             When screening DH-GEX candidates (using the -T command).  This
              option specifies the number of primality tests to perform.
 
      -B      Show the bubblebabble digest of specified private or public key
@@ -117,10 +115,10 @@ DESCRIPTION
              Provides a new comment.
 
      -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 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.
+             files.  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.
 
      -D pkcs11
              Download the RSA public keys provided by the PKCS#11 shared
@@ -200,11 +198,10 @@ DESCRIPTION
 
      -L      Prints the contents of one or more certificates.
 
-     -l      Show fingerprint of specified public key file.  Private RSA1 keys
-             are also supported.  For RSA and DSA keys ssh-keygen tries to
-             find the matching public key file and prints its fingerprint.  If
-             combined with -v, a visual ASCII art representation of the key is
-             supplied with the fingerprint.
+     -l      Show fingerprint of specified public key file.  For RSA and DSA
+             keys ssh-keygen tries to find the matching public key file and
+             prints its fingerprint.  If combined with -v, a visual ASCII art
+             representation of the key is supplied with the fingerprint.
 
      -M memory
              Specify the amount of memory to use (in megabytes) when
@@ -228,14 +225,29 @@ DESCRIPTION
 
      -O option
              Specify a certificate option when signing a key.  This option may
-             be specified multiple times.  Please see the CERTIFICATES section
-             for details.  The options that are valid for user certificates
-             are:
+             be specified multiple times.  See also the CERTIFICATES section
+             for further details.  The options that are valid for user
+             certificates are:
 
              clear   Clear all enabled permissions.  This is useful for
                      clearing the default set of permissions so permissions
                      may be added individually.
 
+             critical:name[=contents]
+             extension:name[=contents]
+                     Includes an arbitrary certificate critical option or
+                     extension.  The specified name should include a domain
+                     suffix, e.g. M-bM-^@M-^\name@example.comM-bM-^@M-^].  If 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.
+
+                     At present, no standard options are valid for host keys.
+
              force-command=command
                      Forces the execution of command instead of any shell or
                      command specified by the user when the certificate is
@@ -277,8 +289,6 @@ DESCRIPTION
                      separated list of one or more address/netmask pairs in
                      CIDR format.
 
-             At present, no options are valid for host keys.
-
      -o      Causes ssh-keygen to save 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
@@ -322,10 +332,13 @@ DESCRIPTION
              Test DH group exchange candidate primes (generated using the -G
              option) for safety.
 
-     -t dsa | ecdsa | ed25519 | rsa | rsa1
+     -t dsa | ecdsa | ed25519 | rsa
              Specifies the type of key to create.  The possible values are
-             M-bM-^@M-^\rsa1M-bM-^@M-^] for protocol version 1 and M-bM-^@M-^\dsaM-bM-^@M-^], M-bM-^@M-^\ecdsaM-bM-^@M-^], M-bM-^@M-^\ed25519M-bM-^@M-^], or
-             M-bM-^@M-^\rsaM-bM-^@M-^] for protocol version 2.
+             M-bM-^@M-^\dsaM-bM-^@M-^], M-bM-^@M-^\ecdsaM-bM-^@M-^], M-bM-^@M-^\ed25519M-bM-^@M-^], or M-bM-^@M-^\rsaM-bM-^@M-^].
+
+     -U      When used in combination with -s, this option indicates that a CA
+             key resides in a ssh-agent(1).  See the CERTIFICATES section for
+             more information.
 
      -u      Update a KRL.  When specified with -k, keys listed via the
              command line are added to the existing KRL rather than a new KRL
@@ -432,6 +445,12 @@ CERTIFICATES
 
            $ ssh-keygen -s ca_key.pub -D libpkcs11.so -I key_id user_key.pub
 
+     Similarly, it is possible for the CA key to be hosted in a ssh-agent(1).
+     This is indicated by the -U flag and, again, the CA key must be
+     identified by its public half.
+
+           $ ssh-keygen -Us ca_key.pub -I key_id user_key.pub
+
      In all cases, key_id is a "key identifier" that is logged by the server
      when the certificate is used for authentication.
 
@@ -512,44 +531,28 @@ KEY REVOCATION LISTS
      was revoked.
 
 FILES
-     ~/.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
-             ssh-keygen but it is offered as the default file for the private
-             key.  ssh(1) will read this file when a login attempt is made.
-
-     ~/.ssh/identity.pub
-             Contains the protocol version 1 RSA public key for
-             authentication.  The contents of this file should be added to
-             ~/.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.
-
      ~/.ssh/id_dsa
      ~/.ssh/id_ecdsa
      ~/.ssh/id_ed25519
      ~/.ssh/id_rsa
-             Contains the protocol version 2 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 specify a
-             passphrase when generating the key; that passphrase will be used
-             to encrypt the private part of this file using 128-bit AES.  This
-             file is not automatically accessed by ssh-keygen but it is
-             offered as the default file for the private key.  ssh(1) will
-             read this file when a login attempt is made.
+             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 specify a passphrase when generating the
+             key; that passphrase will be used to encrypt the private part of
+             this file using 128-bit AES.  This file is not automatically
+             accessed by ssh-keygen but it is offered as the default file for
+             the private key.  ssh(1) will read this file when a login attempt
+             is made.
 
      ~/.ssh/id_dsa.pub
      ~/.ssh/id_ecdsa.pub
      ~/.ssh/id_ed25519.pub
      ~/.ssh/id_rsa.pub
-             Contains the protocol version 2 DSA, ECDSA, Ed25519 or RSA public
-             key for authentication.  The contents of this file should be
-             added to ~/.ssh/authorized_keys on all machines where the user
-             wishes to log in using public key authentication.  There is no
-             need to keep the contents of this file secret.
+             Contains the DSA, ECDSA, Ed25519 or RSA public key for
+             authentication.  The contents of this file should be added to
+             ~/.ssh/authorized_keys on all machines where the user wishes to
+             log in using public key authentication.  There is no need to keep
+             the contents of this file secret.
 
      /etc/moduli
              Contains Diffie-Hellman groups used for DH-GEX.  The file format
@@ -567,4 +570,4 @@ AUTHORS
      created OpenSSH.  Markus Friedl contributed the support for SSH protocol
      versions 1.5 and 2.0.
 
-OpenBSD 6.0                      June 16, 2016                     OpenBSD 6.0
+OpenBSD 6.2                      July 8, 2017                      OpenBSD 6.2