.\" (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.1,v 1.100 2001/03/26 15:47:59 stevesk Exp $
+.\" $OpenBSD: ssh.1,v 1.116 2001/06/23 02:34:31 markus Exp $
.Dd September 25, 1999
.Dt SSH 1
.Os
.Pp
.Nm ssh
.Op Fl afgknqstvxACNPTX1246
+.Op Fl b Ar bind_address
.Op Fl c Ar cipher_spec
.Op Fl e Ar escape_char
.Op Fl i Ar identity_file
This form of authentication alone is normally not
allowed by the server because it is not secure.
.Pp
-The second (and primary) authentication method is the
+The second authentication method is the
.Pa rhosts
or
.Pa hosts.equiv
.Ss SSH protocol version 2
.Pp
When a user connects using the protocol version 2
-different authentication methods are available:
-At first, the client attempts to authenticate using the public key method.
-If this method fails password authentication is tried.
+different authentication methods are available.
+Using the default values for
+.Cm PreferredAuthentications ,
+the client will try to authenticate first using the public key method;
+if this method fails password authentication is attempted,
+and finally if this method fails keyboard-interactive authentication
+is attempted.
+If this method fails password authentication is
+tried.
.Pp
The public key method is similar to RSA authentication described
-in the previous section except that the DSA or RSA algorithm is used
-instead.
-The client uses his private key
+in the previous section and allows the RSA or DSA algorithm to be used:
+The client uses his private key,
.Pa $HOME/.ssh/id_dsa
+or
+.Pa $HOME/.ssh/id_rsa ,
to sign the session identifier and sends the result to the server.
The server checks whether the matching public key is listed in
-.Pa $HOME/.ssh/authorized_keys2
+.Pa $HOME/.ssh/authorized_keys
and grants access if both the key is found and the signature is correct.
The session identifier is derived from a shared Diffie-Hellman value
and is only known to the client and the server.
.Pp
If public key authentication fails or is not available a password
can be sent encrypted to the remote host for proving the user's identity.
-This protocol 2 implementation does not yet support Kerberos or
-S/Key authentication.
+.Pp
+Additionally,
+.Nm
+supports hostbased or challenge response authentication.
.Pp
Protocol 2 provides additional mechanisms for confidentiality
(the traffic is encrypted using 3DES, Blowfish, CAST128 or Arcfour)
the remote command or shell will be automatically encrypted.
.Pp
If a pseudo-terminal has been allocated (normal login session), the
-user can disconnect with
-.Ic ~. ,
-and suspend
-.Nm
-with
-.Ic ~^Z .
-All forwarded connections can be listed with
-.Ic ~#
-and if
-the session blocks waiting for forwarded X11 or TCP/IP
-connections to terminate, it can be backgrounded with
-.Ic ~&
-(this should not be used while the user shell is active, as it can cause the
-shell to hang).
-All available escapes can be listed with
-.Ic ~? .
-.Pp
-A single tilde character can be sent as
-.Ic ~~
-(or by following the tilde by a character other than those described above).
-The escape character must always follow a newline to be interpreted as
-special.
-The escape character can be changed in configuration files
-or on the command line.
+user may use the escape characters noted below.
.Pp
If no pseudo tty has been allocated, the
session is transparent and can be used to reliably transfer binary
of
.Nm ssh .
.Pp
+.Ss Escape Characters
+.Pp
+When a pseudo terminal has been requested, ssh supports a number of functions
+through the use of an escape character.
+.Pp
+A single tilde character can be sent as
+.Ic ~~
+(or by following the tilde by a character other than those described above).
+The escape character must always follow a newline to be interpreted as
+special.
+The escape character can be changed in configuration files using the
+.Cm EscapeChar
+configuration directive or on the command line by the
+.Fl e
+option.
+.Pp
+The supported escapes (assuming the default
+.Ql ~ )
+are:
+.Bl -tag -width Ds
+.It Cm ~.
+Disconnect
+.It Cm ~^Z
+Background ssh
+.It Cm ~#
+List forwarded connections
+.It Cm ~&
+Background ssh at logout when waiting for forwarded connection / X11 sessions
+to terminate (protocol version 1 only)
+.It Cm ~?
+Display a list of escape characters
+.It Cm ~R
+Request rekeying of the connection (only useful for SSH protocol version 2
+and if the peer supports it)
+.El
+.Pp
.Ss X11 and TCP forwarding
.Pp
-If the user is using X11 (the
+If the
+.Cm ForwardX11
+variable is set to
+.Dq yes
+(or, see the description of the
+.Fl X
+and
+.Fl x
+options described later)
+and the user is using X11 (the
.Ev DISPLAY
environment variable is set), the connection to the X11 display is
automatically forwarded to the remote side in such a way that any X11
.Nm
automatically maintains and checks a database containing
identifications for all hosts it has ever been used with.
-RSA host keys are stored in
+Host keys are stored in
.Pa $HOME/.ssh/known_hosts
-and
-host keys used in the protocol version 2 are stored in
-.Pa $HOME/.ssh/known_hosts2
in the user's home directory.
-Additionally, the files
+Additionally, the file
.Pa /etc/ssh_known_hosts
-and
-.Pa /etc/ssh_known_hosts2
-are automatically checked for known hosts.
+is automatically checked for known hosts.
Any new hosts are automatically added to the user's file.
If a host's identification
ever changes,
.It Fl A
Enables forwarding of the authentication agent connection.
This can also be specified on a per-host basis in a configuration file.
+.It Fl b Ar bind_address
+Specify the interface to transmit from on machines with multiple
+interfaces or aliased addresses.
.It Fl c Ar blowfish|3des
Selects the cipher to use for encrypting the session.
.Ar 3des
Only fatal errors are displayed.
.It Fl s
May be used to request invocation of a subsystem on the remote system. Subsystems are a feature of the SSH2 protocol which facilitate the use
-of SSH as a secure transport for other application (eg. sftp). The
+of SSH as a secure transport for other applications (eg. sftp). The
subsystem is specified as the remote command.
.It Fl t
Force pseudo-tty allocation.
Port forwardings can also be specified in the configuration file.
Privileged ports can be forwarded only when
logging in as root on the remote machine.
+IPv6 addresses can be specified with an alternative syntax:
+.Ar port/host/hostport
.It Fl 1
Forces
.Nm
.Dq yes
or
.Dq no .
+This option applies to protocol version 1 only.
.It Cm BatchMode
If set to
.Dq yes ,
.Dq no .
The default is
.Dq no .
+.It Cm BindAddress
+Specify the interface to transmit from on machines with multiple
+interfaces or aliased addresses.
+Note that this option does not work if
+.Cm UsePrivilegedPort
+is set to
+.Dq yes .
.It Cm CheckHostIP
If this flag is set to
.Dq yes ,
.Pp
.Bd -literal
``aes128-cbc,3des-cbc,blowfish-cbc,cast128-cbc,arcfour,
- aes192-cbc,aes256-cbc,rijndael128-cbc,rijndael192-cbc,
- rijndael256-cbc,rijndael-cbc@lysator.liu.se''
+ aes192-cbc,aes256-cbc''
.Ed
.It Cm Compression
Specifies whether to use compression.
The default level is 6, which is good for most applications.
The meaning of the values is the same as in
.Xr gzip 1 .
+Note that this option applies to protocol version 1 only.
.It Cm ConnectionAttempts
Specifies the number of tries (one per second) to make before falling
back to rsh or exiting.
The argument must be an integer.
This may be useful in scripts if the connection sometimes fails.
The default is 4.
-.It Cm PubkeyAuthentication
-Specifies whether to try public key authentication.
-The argument to this keyword must be
-.Dq yes
-or
-.Dq no .
-The default is
-.Dq yes .
-Note that this option applies to protocol version 2 only.
.It Cm EscapeChar
Sets the escape character (default:
.Ql ~ ) .
The default is
.Dq no .
.It Cm GlobalKnownHostsFile
-Specifies a file to use for the protocol version 1 global
+Specifies a file to use for the global
host key database instead of
.Pa /etc/ssh_known_hosts .
-.It Cm GlobalKnownHostsFile2
-Specifies a file to use for the protocol version 2 global
-host key database instead of
-.Pa /etc/ssh_known_hosts2 .
+.It Cm HostbasedAuthentication
+Specifies whether to try rhosts based authentication with public key
+authentication.
+The argument must be
+.Dq yes
+or
+.Dq no .
+The default is
+.Dq no .
+This option applies to protocol version 2 only and
+is similar to
+.Cm RhostsRSAAuthentication .
+.It Cm HostKeyAlgorithms
+Specifies the protocol version 2 host key algorithms
+that the client wants to use in order of preference.
+The default for this option is:
+.Dq ssh-rsa,ssh-dss
.It Cm HostKeyAlias
Specifies an alias that should be used instead of the
real host name when looking up or saving the host key
-in the known_hosts files.
+in the host key database files.
This option is useful for tunneling ssh connections
or if you have multiple servers running on a single host.
.It Cm HostName
.Cm HostName
specifications).
.It Cm IdentityFile
-Specifies the file from which the user's RSA authentication identity
+Specifies the file from which the user's RSA or DSA authentication identity
is read (default
.Pa $HOME/.ssh/identity
in the user's home directory).
for data integrity protection.
Multiple algorithms must be comma-separated.
The default is
-.Pp
-.Bd -literal
- ``hmac-md5,hmac-sha1,hmac-ripemd160,hmac-ripemd160@openssh.com,
- hmac-sha1-96,hmac-md5-96''
-.Ed
+.Dq hmac-md5,hmac-sha1,hmac-ripemd160,hmac-sha1-96,hmac-md5-96 .
.It Cm NumberOfPasswordPrompts
Specifies the number of password prompts before giving up.
The argument to this keyword must be an integer.
.Dq no .
The default is
.Dq yes .
-Note that this option applies to both protocol version 1 and 2.
.It Cm Port
Specifies the port number to connect on the remote host.
Default is 22.
over another method (e.g.
.Cm password )
The default for this option is:
-.Dq publickey, password, keyboard-interactive
+.Dq publickey,hostbased,password,keyboard-interactive
.It Cm Protocol
Specifies the protocol versions
.Nm
.Dq 2 .
Multiple versions must be comma-separated.
The default is
-.Dq 1,2 .
+.Dq 2,1 .
This means that
.Nm
-tries version 1 and falls back to version 2
-if version 1 is not available.
+tries version 2 and falls back to version 1
+if version 2 is not available.
.It Cm ProxyCommand
Specifies the command to use to connect to the server.
The command
.Cm CheckHostIP
is not available for connects with a proxy command.
.Pp
+.It Cm PubkeyAuthentication
+Specifies whether to try public key authentication.
+The argument to this keyword must be
+.Dq yes
+or
+.Dq no .
+The default is
+.Dq yes .
+This option applies to protocol version 2 only.
.It Cm RemoteForward
Specifies that a TCP/IP port on the remote machine be forwarded over
the secure channel to given host:port from the local machine.
authentication time on slow connections when rhosts authentication is
not used.
Most servers do not permit RhostsAuthentication because it
-is not secure (see RhostsRSAAuthentication).
+is not secure (see
+.Cm RhostsRSAAuthentication ) .
The argument to this keyword must be
.Dq yes
or
.Dq no .
The default is
.Dq yes .
+This option applies to protocol version 1 only.
.It Cm RhostsRSAAuthentication
Specifies whether to try rhosts based authentication with RSA host
authentication.
.Dq no .
The default is
.Dq yes .
+This option applies to protocol version 1 only.
.It Cm RSAAuthentication
Specifies whether to try RSA authentication.
The argument to this keyword must be
.Nm
will never automatically add host keys to the
.Pa $HOME/.ssh/known_hosts
-and
-.Pa $HOME/.ssh/known_hosts2
-files, and refuses to connect to hosts whose host key has changed.
+file, and refuses to connect to hosts whose host key has changed.
This provides maximum protection against trojan horse attacks.
However, it can be somewhat annoying if you don't have good
.Pa /etc/ssh_known_hosts
-and
-.Pa /etc/ssh_known_hosts2
files installed and frequently
connect to new hosts.
This option forces the user to manually
.Dq no .
The default is
.Dq no .
-Note that setting this option to
-.Dq no
-turns off
+Note that you need to set this option to
+.Dq yes
+if you want to use
.Cm RhostsAuthentication
and
.Cm RhostsRSAAuthentication
-for older servers.
+with older servers.
.It Cm User
Specifies the user to log in as.
This can be useful if you have a different user name on different machines.
This saves the trouble of
having to remember to give the user name on the command line.
.It Cm UserKnownHostsFile
-Specifies a file to use for the protocol version 1 user
+Specifies a file to use for the user
host key database instead of
.Pa $HOME/.ssh/known_hosts .
-.It Cm UserKnownHostsFile2
-Specifies a file to use for the protocol version 2 user
-host key database instead of
-.Pa $HOME/.ssh/known_hosts2 .
.It Cm UseRsh
Specifies that rlogin/rsh should be used for this host.
It is possible that the host does not at all support the
.Nm
uses this special value to forward X11 connections over the secure
channel.
-The user should normally not set DISPLAY explicitly, as that
+The user should normally not set
+.Ev DISPLAY
+explicitly, as that
will render the X11 connection insecure (and will require the user to
manually copy any required authorization cookies).
.It Ev HOME
to the environment.
.Sh FILES
.Bl -tag -width Ds
-.It Pa $HOME/.ssh/known_hosts, $HOME/.ssh/known_hosts2
+.It Pa $HOME/.ssh/known_hosts
Records host keys for all hosts the user has logged into (that are not
in
-.Pa /etc/ssh_known_hosts
-for protocol version 1 or
-.Pa /etc/ssh_known_hosts2
-for protocol version 2).
+.Pa /etc/ssh_known_hosts .
See
.Xr sshd 8 .
-.It Pa $HOME/.ssh/identity, $HOME/.ssh/id_dsa
-Contains the RSA and the DSA authentication identity of the user.
+.It Pa $HOME/.ssh/identity, $HOME/.ssh/id_dsa, $HOME/.ssh/id_rsa
+Contains the authentication identity of the user.
+They are for protocol 1 RSA, protocol 2 DSA, and protocol 2 RSA, respectively.
These files
contain sensitive data and should be readable by the user but not
accessible by others (read/write/execute).
It is possible to specify a passphrase when
generating the key; the passphrase will be used to encrypt the
sensitive part of this file using 3DES.
-.It Pa $HOME/.ssh/identity.pub, $HOME/.ssh/id_dsa.pub
+.It Pa $HOME/.ssh/identity.pub, $HOME/.ssh/id_dsa.pub, $HOME/.ssh/id_rsa.pub
Contains the public key for authentication (public part of the
identity file in human-readable form).
The contents of the
file should be added to
.Pa $HOME/.ssh/authorized_keys
on all machines
-where you wish to log in using RSA authentication.
+where you wish to log in using protocol version 1 RSA authentication.
The contents of the
.Pa $HOME/.ssh/id_dsa.pub
+and
+.Pa $HOME/.ssh/id_rsa.pub
file should be added to
-.Pa $HOME/.ssh/authorized_keys2
+.Pa $HOME/.ssh/authorized_keys
on all machines
-where you wish to log in using DSA authentication.
+where you wish to log in using protocol version 2 DSA/RSA authentication.
These files are not
sensitive and can (but need not) be readable by anyone.
These files are
but the recommended permissions are read/write for the user, and not
accessible by others.
.It Pa $HOME/.ssh/authorized_keys
-Lists the RSA keys that can be used for logging in as this user.
+Lists the public keys (RSA/DSA) that can be used for logging in as this user.
The format of this file is described in the
.Xr sshd 8
manual page.
In the simplest form the format is the same as the .pub
-identity files (that is, each line contains the number of bits in
-modulus, public exponent, modulus, and comment fields, separated by
-spaces).
-This file is not highly sensitive, but the recommended
-permissions are read/write for the user, and not accessible by others.
-.It Pa $HOME/.ssh/authorized_keys2
-Lists the public keys (DSA/RSA) that can be used for logging in as this user.
+identity files.
This file is not highly sensitive, but the recommended
permissions are read/write for the user, and not accessible by others.
-.It Pa /etc/ssh_known_hosts, /etc/ssh_known_hosts2
+.It Pa /etc/ssh_known_hosts
Systemwide list of known host keys.
-.Pa /etc/ssh_known_hosts
-contains RSA and
-.Pa /etc/ssh_known_hosts2
-contains DSA or RSA keys for protocol version 2.
-These files should be prepared by the
+This file should be prepared by the
system administrator to contain the public host keys of all machines in the
organization.
This file should be world-readable.
This file contains
public keys, one per line, in the following format (fields separated
-by spaces): system name, number of bits in modulus, public exponent,
-modulus, and optional comment field.
+by spaces): system name, public key and optional comment field.
When different names are used
for the same machine, all such names should be listed, separated by
commas.
.Xr ssh-keygen 1 ,
.Xr telnet 1 ,
.Xr sshd 8
+.Rs
+.%A T. Ylonen
+.%A T. Kivinen
+.%A M. Saarinen
+.%A T. Rinne
+.%A S. Lehtinen
+.%T "SSH Protocol Architecture"
+.%N draft-ietf-secsh-architecture-07.txt
+.%D January 2001
+.%O work in progress material
+.Re
andersk / openssh.git / blobdiff