1 files changed, 109 insertions, 36 deletions

diff --git a/ssh_config.5 b/ssh_config.5
index 81b9b740f..51765c99e 100644
--- a/ssh_config.5
+++ b/ssh_config.5
@@ -33,8 +33,8 @@
 .\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
 .\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 .\"
-.\" $OpenBSD: ssh_config.5,v 1.215 2015/08/14 15:32:41 jmc Exp $
-.Dd $Mdocdate: August 14 2015 $
+.\" $OpenBSD: ssh_config.5,v 1.228 2016/02/20 23:01:46 sobrado Exp $
+.Dd $Mdocdate: February 20 2016 $
 .Dt SSH_CONFIG 5
 .Os
 .Sh NAME
@@ -155,7 +155,7 @@ or
 keyword) to be used only when the conditions following the
 .Cm Match
 keyword are satisfied.
-Match conditions are specified using one or more critera
+Match conditions are specified using one or more criteria
 or the single token
 .Cm all
 which always matches.
@@ -237,6 +237,39 @@ keyword matches against the name of the local user running
 (this keyword may be useful in system-wide
 .Nm
 files).
+.It Cm AddKeysToAgent
+Specifies whether keys should be automatically added to a running
+.Xr ssh-agent 1 .
+If this option is set to
+.Dq yes
+and a key is loaded from a file, the key and its passphrase are added to
+the agent with the default lifetime, as if by
+.Xr ssh-add 1 .
+If this option is set to
+.Dq ask ,
+.Nm ssh
+will require confirmation using the
+.Ev SSH_ASKPASS
+program before adding a key (see
+.Xr ssh-add 1
+for details).
+If this option is set to
+.Dq confirm ,
+each use of the key must be confirmed, as if the
+.Fl c
+option was specified to
+.Xr ssh-add 1 .
+If this option is set to
+.Dq no ,
+no keys are added to the agent.
+The argument must be
+.Dq yes ,
+.Dq confirm ,
+.Dq ask ,
+or
+.Dq no .
+The default is
+.Dq no .
 .It Cm AddressFamily
 Specifies which address family to use when connecting.
 Valid arguments are
@@ -245,6 +278,8 @@ Valid arguments are
 (use IPv4 only), or
 .Dq inet6
 (use IPv6 only).
+The default is
+.Dq any .
 .It Cm BatchMode
 If set to
 .Dq yes ,
@@ -345,6 +380,41 @@ to be canonicalized to names in the
 or
 .Dq *.c.example.com
 domains.
+.It Cm CertificateFile
+Specifies a file from which the user's certificate is read.
+A corresponding private key must be provided separately in order
+to use this certificate either
+from an
+.Cm IdentityFile
+directive or
+.Fl i
+flag to
+.Xr ssh 1 ,
+via
+.Xr ssh-agent 1 ,
+or via a
+.Cm PKCS11Provider .
+.Pp
+The file name may use the tilde
+syntax to refer to a user's home directory or one of the following
+escape characters:
+.Ql %d
+(local user's home directory),
+.Ql %u
+(local user name),
+.Ql %l
+(local host name),
+.Ql %h
+(remote host name) or
+.Ql %r
+(remote user name).
+.Pp
+It is possible to have multiple certificate files specified in
+configuration files; these certificates will be tried in sequence.
+Multiple
+.Cm CertificateFile
+directives will add to the list of certificates used for
+authentication.
 .It Cm ChallengeResponseAuthentication
 Specifies whether to use challenge-response authentication.
 The argument to this keyword must be
@@ -438,9 +508,7 @@ The default is:
 chacha20-poly1305@openssh.com,
 aes128-ctr,aes192-ctr,aes256-ctr,
 aes128-gcm@openssh.com,aes256-gcm@openssh.com,
-arcfour256,arcfour128,
-aes128-cbc,3des-cbc,blowfish-cbc,cast128-cbc,
-aes192-cbc,aes256-cbc,arcfour
+aes128-cbc,aes192-cbc,aes256-cbc,3des-cbc
 .Ed
 .Pp
 The list of available ciphers may also be obtained using the
@@ -558,8 +626,11 @@ the destination port,
 .Ql %r
 by the remote login username,
 .Ql %u
-by the username of the user running
-.Xr ssh 1 , and
+by the username and
+.Ql %i
+by the numeric user ID (uid) of the user running
+.Xr ssh 1 ,
+and
 .Ql \&%C
 by a hash of the concatenation: %l%h%p%r.
 It is recommended that any
@@ -659,7 +730,14 @@ data).
 Specifies whether
 .Xr ssh 1
 should terminate the connection if it cannot set up all requested
-dynamic, tunnel, local, and remote port forwardings.
+dynamic, tunnel, local, and remote port forwardings, (e.g.\&
+if either end is unable to bind and listen on a specified port).
+Note that
+.Cm ExitOnForwardFailure
+does not apply to connections made over port forwardings and will not,
+for example, cause
+.Xr ssh 1
+to exit if TCP connections to the ultimate forwarding destination fail.
 The argument must be
 .Dq yes
 or
@@ -769,13 +847,11 @@ The default is
 Specifies whether user authentication based on GSSAPI is allowed.
 The default is
 .Dq no .
-Note that this option applies to protocol version 2 only.
 .It Cm GSSAPIKeyExchange
 Specifies whether key exchange based on GSSAPI may be used. When using
 GSSAPI key exchange the server need not have a host key.
 The default is
 .Dq no .
-Note that this option applies to protocol version 2 only.
 .It Cm GSSAPIClientIdentity
 If set, specifies the GSSAPI client identity that ssh should use when 
 connecting to the server. The default is unset, which means that the default 
@@ -789,7 +865,6 @@ hostname.
 Forward (delegate) credentials to the server.
 The default is
 .Dq no .
-Note that this option applies to protocol version 2 connections using GSSAPI.
 .It Cm GSSAPIRenewalForcesRekey
 If set to 
 .Dq yes
@@ -808,7 +883,6 @@ the hostname entered on the
 command line will be passed untouched to the GSSAPI library.
 The default is
 .Dq no .
-This option only applies to protocol version 2 connections using GSSAPI.
 .It Cm HashKnownHosts
 Indicates that
 .Xr ssh 1
@@ -838,9 +912,6 @@ or
 .Dq no .
 The default is
 .Dq no .
-This option applies to protocol version 2 only and
-is similar to
-.Cm RhostsRSAAuthentication .
 .It Cm HostbasedKeyTypes
 Specifies the key types that will be used for hostbased authentication
 as a comma-separated pattern list.
@@ -865,7 +936,7 @@ option of
 .Xr ssh 1
 may be used to list supported key types.
 .It Cm HostKeyAlgorithms
-Specifies the protocol version 2 host key algorithms
+Specifies the host key algorithms
 that the client wants to use in order of preference.
 Alternately if the specified value begins with a
 .Sq +
@@ -917,9 +988,13 @@ specifications).
 .It Cm IdentitiesOnly
 Specifies that
 .Xr ssh 1
-should only use the authentication identity files configured in the
+should only use the authentication identity and certificate files explicitly
+configured in the
 .Nm
-files,
+files
+or passed on the
+.Xr ssh 1
+command-line,
 even if
 .Xr ssh-agent 1
 or a
@@ -949,6 +1024,8 @@ Additionally, any identities represented by the authentication agent
 will be used for authentication unless
 .Cm IdentitiesOnly
 is set.
+If no certificates have been explicitly specified by
+.Cm CertificateFile ,
 .Xr ssh 1
 will try to load certificate information from the filename obtained by
 appending
@@ -982,6 +1059,11 @@ differs from that of other configuration directives).
 may be used in conjunction with
 .Cm IdentitiesOnly
 to select which identities in an agent are offered during authentication.
+.Cm IdentityFile
+may also be used in conjunction with
+.Cm CertificateFile
+in order to provide any certificate also needed for authentication with
+the identity.
 .It Cm IgnoreUnknown
 Specifies a pattern-list of unknown options to be ignored if they are
 encountered in configuration parsing.
@@ -1141,8 +1223,7 @@ DEBUG2 and DEBUG3 each specify higher levels of verbose output.
 .It Cm MACs
 Specifies the MAC (message authentication code) algorithms
 in order of preference.
-The MAC algorithm is used in protocol version 2
-for data integrity protection.
+The MAC algorithm is used for data integrity protection.
 Multiple algorithms must be comma-separated.
 If the specified value begins with a
 .Sq +
@@ -1158,13 +1239,9 @@ The default is:
 .Bd -literal -offset indent
 umac-64-etm@openssh.com,umac-128-etm@openssh.com,
 hmac-sha2-256-etm@openssh.com,hmac-sha2-512-etm@openssh.com,
+hmac-sha1-etm@openssh.com,
 umac-64@openssh.com,umac-128@openssh.com,
-hmac-sha2-256,hmac-sha2-512,
-hmac-md5-etm@openssh.com,hmac-sha1-etm@openssh.com,
-hmac-ripemd160-etm@openssh.com,
-hmac-sha1-96-etm@openssh.com,hmac-md5-96-etm@openssh.com,
-hmac-md5,hmac-sha1,hmac-ripemd160,
-hmac-sha1-96,hmac-md5-96
+hmac-sha2-256,hmac-sha2-512,hmac-sha1
 .Ed
 .Pp
 The list of available MAC algorithms may also be obtained using the
@@ -1218,8 +1295,7 @@ private RSA key.
 Specifies the port number to connect on the remote host.
 The default is 22.
 .It Cm PreferredAuthentications
-Specifies the order in which the client should try protocol 2
-authentication methods.
+Specifies the order in which the client should try authentication methods.
 This allows a client to prefer one method (e.g.\&
 .Cm keyboard-interactive )
 over another method (e.g.\&
@@ -1245,6 +1321,9 @@ will try version 2 and fall back to version 1
 if version 2 is not available.
 The default is
 .Sq 2 .
+Protocol 1 suffers from a number of cryptographic weaknesses and should
+not be used.
+It is only offered to support legacy devices.
 .It Cm ProxyCommand
 Specifies the command to use to connect to the server.
 The command
@@ -1325,7 +1404,6 @@ or
 .Dq no .
 The default is
 .Dq yes .
-This option applies to protocol version 2 only.
 .It Cm RekeyLimit
 Specifies the maximum amount of data that may be transmitted before the
 session key is renegotiated, optionally followed a maximum amount of
@@ -1351,7 +1429,6 @@ is
 .Dq default none ,
 which means that rekeying is performed after the cipher's default amount
 of data has been sent or received and no time based rekeying is done.
-This option applies to protocol version 2 only.
 .It Cm RemoteForward
 Specifies that a TCP port on the remote machine be forwarded over
 the secure channel to the specified host and port from the local machine.
@@ -1444,7 +1521,6 @@ Note that this option applies to protocol version 1 only.
 Specifies what variables from the local
 .Xr environ 7
 should be sent to the server.
-Note that environment passing is only supported for protocol 2.
 The server must also support it, and the server must be configured to
 accept these environment variables.
 Note that the
@@ -1492,7 +1568,6 @@ If, for example,
 .Cm ServerAliveCountMax
 is left at the default, if the server becomes unresponsive,
 ssh will disconnect after approximately 45 seconds.
-This option applies to protocol version 2 only.
 .It Cm ServerAliveInterval
 Sets a timeout interval in seconds after which if no data has been received
 from the server,
@@ -1504,7 +1579,6 @@ is 0, indicating that these messages will not be sent to the server,
 or 300 if the
 .Cm BatchMode
 option is set.
-This option applies to protocol version 2 only.
 .Cm ProtocolKeepAlives
 and
 .Cm SetupTimeOut
@@ -1646,7 +1720,7 @@ Enabling this option allows learning alternate hostkeys for a server
 and supports graceful key rotation by allowing a server to send replacement
 public keys before old ones are removed.
 Additional hostkeys are only accepted if the key used to authenticate the
-host was already trusted or explicity accepted by the user.
+host was already trusted or explicitly accepted by the user.
 If
 .Cm UpdateHostKeys
 is set to
@@ -1711,7 +1785,6 @@ or
 .Dq ask .
 The default is
 .Dq no .
-Note that this option applies to protocol version 2 only.
 .Pp
 See also VERIFYING HOST KEYS in
 .Xr ssh 1 .