X-Git-Url: http://andersk.mit.edu/gitweb/openssh.git/blobdiff_plain/e1520719ca5fc1aa81749c93b7fe4148c2cdf2a8..32560f077f93eb11a8d199ada25e7f7dfec79af4:/ssh.1 diff --git a/ssh.1 b/ssh.1 index 053fedd2..4cc1738c 100644 --- a/ssh.1 +++ b/ssh.1 @@ -34,7 +34,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. .\" -.\" $OpenBSD: ssh.1,v 1.183 2004/04/19 13:02:40 djm Exp $ +.\" $OpenBSD: ssh.1,v 1.208 2005/05/23 23:32:46 djm Exp $ .Dd September 25, 1999 .Dt SSH 1 .Os @@ -43,39 +43,35 @@ .Nd OpenSSH SSH client (remote login program) .Sh SYNOPSIS .Nm ssh -.Op Fl 1246AaCfgkNnqsTtVvXxY +.Bk -words +.Op Fl 1246AaCfgkMNnqsTtVvXxY .Op Fl b Ar bind_address .Op Fl c Ar cipher_spec .Op Fl D Ar port .Op Fl e Ar escape_char .Op Fl F Ar configfile .Op Fl i Ar identity_file -.Bk -words -.Oo Fl L Xo +.Oo Fl L\ \& .Sm off -.Ar port : -.Ar host : -.Ar hostport +.Oo Ar bind_address : Oc +.Ar port : host : hostport .Sm on -.Xc .Oc -.Ek .Op Fl l Ar login_name .Op Fl m Ar mac_spec +.Op Fl O Ar ctl_cmd .Op Fl o Ar option -.Bk -words .Op Fl p Ar port -.Ek -.Oo Fl R Xo +.Oo Fl R\ \& .Sm off -.Ar port : -.Ar host : -.Ar hostport +.Oo Ar bind_address : Oc +.Ar port : host : hostport .Sm on -.Xc .Oc +.Op Fl S Ar ctl_path .Oo Ar user Ns @ Oc Ns Ar hostname .Op Ar command +.Ek .Sh DESCRIPTION .Nm (SSH client) is a program for logging into a remote machine and for @@ -102,39 +98,29 @@ is specified, .Ar command is executed on the remote host instead of a login shell. .Ss SSH protocol version 1 -First, if the machine the user logs in from is listed in +The first authentication method is the +.Em rhosts +or +.Em hosts.equiv +method combined with RSA-based host authentication. +If the machine the user logs in from is listed in .Pa /etc/hosts.equiv or .Pa /etc/shosts.equiv on the remote machine, and the user names are -the same on both sides, the user is immediately permitted to log in. -Second, if -.Pa .rhosts +the same on both sides, or if the files +.Pa ~/.rhosts or -.Pa .shosts -exists in the user's home directory on the -remote machine and contains a line containing the name of the client +.Pa ~/.shosts +exist in the user's home directory on the +remote machine and contain a line containing the name of the client machine and the name of the user on that machine, the user is -permitted to log in. -This form of authentication alone is normally not -allowed by the server because it is not secure. -.Pp -The second authentication method is the -.Em rhosts -or -.Em hosts.equiv -method combined with RSA-based host authentication. -It means that if the login would be permitted by -.Pa $HOME/.rhosts , -.Pa $HOME/.shosts , -.Pa /etc/hosts.equiv , -or -.Pa /etc/shosts.equiv , -and if additionally the server can verify the client's +considered for log in. +Additionally, if the server can verify the client's host key (see .Pa /etc/ssh/ssh_known_hosts and -.Pa $HOME/.ssh/known_hosts +.Pa ~/.ssh/known_hosts in the .Sx FILES section), only then is login permitted. @@ -142,11 +128,11 @@ This authentication method closes security holes due to IP spoofing, DNS spoofing and routing spoofing. [Note to the administrator: .Pa /etc/hosts.equiv , -.Pa $HOME/.rhosts , +.Pa ~/.rhosts , and the rlogin/rsh protocol in general, are inherently insecure and should be disabled if security is desired.] .Pp -As a third authentication method, +As a second authentication method, .Nm supports RSA based authentication. The scheme is based on public-key cryptography: there are cryptosystems @@ -158,7 +144,7 @@ key pair for authentication purposes. The server knows the public key, and only the user knows the private key. .Pp The file -.Pa $HOME/.ssh/authorized_keys +.Pa ~/.ssh/authorized_keys lists the public keys that are permitted for logging in. When the user logs in, the .Nm @@ -179,24 +165,21 @@ implements the RSA authentication protocol automatically. The user creates his/her RSA key pair by running .Xr ssh-keygen 1 . This stores the private key in -.Pa $HOME/.ssh/identity +.Pa ~/.ssh/identity and stores the public key in -.Pa $HOME/.ssh/identity.pub +.Pa ~/.ssh/identity.pub in the user's home directory. The user should then copy the .Pa identity.pub to -.Pa $HOME/.ssh/authorized_keys +.Pa ~/.ssh/authorized_keys in his/her home directory on the remote machine (the .Pa authorized_keys file corresponds to the conventional -.Pa $HOME/.rhosts +.Pa ~/.rhosts file, and has one key per line, though the lines can be very long). After this, the user can log in without giving the password. -RSA authentication is much more secure than -.Em rhosts -authentication. .Pp The most convenient way to use RSA authentication may be with an authentication agent. @@ -223,12 +206,12 @@ password authentication are tried. The public key method is similar to RSA authentication described 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 +.Pa ~/.ssh/id_dsa or -.Pa $HOME/.ssh/id_rsa , +.Pa ~/.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_keys +.Pa ~/.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. @@ -241,8 +224,8 @@ Additionally, supports hostbased or challenge response authentication. .Pp Protocol 2 provides additional mechanisms for confidentiality -(the traffic is encrypted using 3DES, Blowfish, CAST128 or Arcfour) -and integrity (hmac-md5, hmac-sha1). +(the traffic is encrypted using AES, 3DES, Blowfish, CAST128 or Arcfour) +and integrity (hmac-md5, hmac-sha1, hmac-ripemd160). Note that protocol 1 lacks a strong mechanism for ensuring the integrity of the connection. .Ss Login session and remote execution @@ -302,11 +285,18 @@ Display a list of escape characters. Send a BREAK to the remote system (only useful for SSH protocol version 2 and if the peer supports it). .It Cm ~C -Open command line (only useful for adding port forwardings using the +Open command line. +Currently this allows the addition of port forwardings using the .Fl L and .Fl R -options). +options (see below). +It also allows the cancellation of existing remote port-forwardings +using +.Fl KR Ar hostport . +Basic help is available, using the +.Fl h +option. .It Cm ~R Request rekeying of the connection (only useful for SSH protocol version 2 and if the peer supports it). @@ -375,7 +365,7 @@ electronic purse; another is going through firewalls. automatically maintains and checks a database containing identifications for all hosts it has ever been used with. Host keys are stored in -.Pa $HOME/.ssh/known_hosts +.Pa ~/.ssh/known_hosts in the user's home directory. Additionally, the file .Pa /etc/ssh/ssh_known_hosts @@ -392,6 +382,15 @@ The option can be used to prevent logins to machines whose host key is not known or has changed. .Pp +.Nm +can be configured to verify host identification using fingerprint resource +records (SSHFP) published in DNS. +The +.Cm VerifyHostKeyDNS +option can be used to control how DNS lookups are performed. +SSHFP resource records can be generated using +.Xr ssh-keygen 1 . +.Pp The options are as follows: .Bl -tag -width Ds .It Fl 1 @@ -424,7 +423,7 @@ authenticate using the identities loaded into the agent. .It Fl a Disables forwarding of the authentication agent connection. .It Fl b Ar bind_address -Specify the interface to transmit from on machines with multiple +Specify the interface address to transmit from on machines with multiple interfaces or aliased addresses. .It Fl C Requests compression of all data (including stdin, stdout, stderr, and @@ -442,13 +441,18 @@ The default value can be set on a host-by-host basis in the configuration files; see the .Cm Compression option. -.It Fl c Ar blowfish | 3des | des -Selects the cipher to use for encrypting the session. -.Ar 3des -is used by default. -It is believed to be secure. +.It Fl c Ar cipher_spec +Selects the cipher specification for encrypting the session. +.Pp +Protocol version 1 allows specification of a single cipher. +The suported values are +.Dq 3des , +.Dq blowfish +and +.Dq des . .Ar 3des (triple-des) is an encrypt-decrypt-encrypt triple with three different keys. +It is believed to be secure. .Ar blowfish is a fast block cipher; it appears very secure and is much faster than .Ar 3des . @@ -460,12 +464,33 @@ that do not support the .Ar 3des cipher. Its use is strongly discouraged due to cryptographic weaknesses. -.It Fl c Ar cipher_spec -Additionally, for protocol version 2 a comma-separated list of ciphers can -be specified in order of preference. -See -.Cm Ciphers -for more information. +The default is +.Dq 3des . +.Pp +For protocol version 2 +.Ar cipher_spec +is a comma-separated list of ciphers +listed in order of preference. +The supported ciphers are +.Dq 3des-cbc , +.Dq aes128-cbc , +.Dq aes192-cbc , +.Dq aes256-cbc , +.Dq aes128-ctr , +.Dq aes192-ctr , +.Dq aes256-ctr , +.Dq arcfour128 , +.Dq arcfour256 , +.Dq arcfour , +.Dq blowfish-cbc , +and +.Dq cast128-cbc . +The default is +.Bd -literal + ``aes128-cbc,3des-cbc,blowfish-cbc,cast128-cbc,arcfour128, + arcfour256,arcfour,aes192-cbc,aes256-cbc,aes128-ctr, + aes192-ctr,aes256-ctr'' +.Ed .It Fl D Ar port Specifies a local .Dq dynamic @@ -500,7 +525,7 @@ the system-wide configuration file .Pq Pa /etc/ssh/ssh_config will be ignored. The default for the per-user configuration file is -.Pa $HOME/.ssh/config . +.Pa ~/.ssh/config . .It Fl f Requests .Nm @@ -526,11 +551,11 @@ private RSA key. Selects a file from which the identity (private key) for RSA or DSA authentication is read. The default is -.Pa $HOME/.ssh/identity +.Pa ~/.ssh/identity for protocol version 1, and -.Pa $HOME/.ssh/id_rsa +.Pa ~/.ssh/id_rsa and -.Pa $HOME/.ssh/id_dsa +.Pa ~/.ssh/id_dsa for protocol version 2. Identity files may also be specified on a per-host basis in the configuration file. @@ -542,6 +567,7 @@ configuration files). Disables forwarding (delegation) of GSSAPI credentials to the server. .It Fl L Xo .Sm off +.Oo Ar bind_address : Oc .Ar port : host : hostport .Sm on .Xc @@ -549,7 +575,9 @@ Specifies that the given port on the local (client) host is to be forwarded to the given host and port on the remote side. This works by allocating a socket to listen to .Ar port -on the local side, and whenever a connection is made to this port, the +on the local side, optionally bound to the specified +.Ar bind_address . +Whenever a connection is made to this port, the connection is forwarded over the secure channel, and a connection is made to .Ar host @@ -557,17 +585,44 @@ port .Ar hostport from the remote machine. Port forwardings can also be specified in the configuration file. -Only root can forward privileged ports. IPv6 addresses can be specified with an alternative syntax: .Sm off .Xo +.Op Ar bind_address No / .Ar port No / Ar host No / -.Ar hostport . +.Ar hostport .Xc .Sm on +or by enclosing the address in square brackets. +Only the superuser can forward privileged ports. +By default, the local port is bound in accordance with the +.Cm GatewayPorts +setting. +However, an explicit +.Ar bind_address +may be used to bind the connection to a specific address. +The +.Ar bind_address +of +.Dq localhost +indicates that the listening port be bound for local use only, while an +empty address or +.Sq * +indicates that the port should be available from all interfaces. .It Fl l Ar login_name Specifies the user to log in as on the remote machine. This also may be specified on a per-host basis in the configuration file. +.It Fl M +Places the +.Nm +client into +.Dq master +mode for connection sharing. +Refer to the description of +.Cm ControlMaster +in +.Xr ssh_config 5 +for details. .It Fl m Ar mac_spec Additionally, for protocol version 2 a comma-separated list of MAC (message authentication code) algorithms can @@ -599,6 +654,18 @@ program will be put in the background. needs to ask for a password or passphrase; see also the .Fl f option.) +.It Fl O Ar ctl_cmd +Control an active connection multiplexing master process. +When the +.Fl O +option is specified, the +.Ar ctl_cmd +argument is interpreted and passed to the master process. +Valid commands are: +.Dq check +(check that the master process is running) and +.Dq exit +(request the master to exit). .It Fl o Ar option Can be used to give options in the format used in the configuration file. This is useful for specifying options for which there is no separate @@ -618,7 +685,9 @@ For full details of the options listed below, and their possible values, see .It Compression .It CompressionLevel .It ConnectionAttempts -.It ConnectionTimeout +.It ConnectTimeout +.It ControlMaster +.It ControlPath .It DynamicForward .It EscapeChar .It ForwardAgent @@ -628,6 +697,7 @@ For full details of the options listed below, and their possible values, see .It GlobalKnownHostsFile .It GSSAPIAuthentication .It GSSAPIDelegateCredentials +.It HashKnownHosts .It Host .It HostbasedAuthentication .It HostKeyAlgorithms @@ -635,6 +705,7 @@ For full details of the options listed below, and their possible values, see .It HostName .It IdentityFile .It IdentitiesOnly +.It KbdInteractiveDevices .It LocalForward .It LogLevel .It MACs @@ -649,6 +720,7 @@ For full details of the options listed below, and their possible values, see .It RemoteForward .It RhostsRSAAuthentication .It RSAAuthentication +.It SendEnv .It ServerAliveInterval .It ServerAliveCountMax .It SmartcardDevice @@ -669,6 +741,7 @@ Quiet mode. Causes all warning and diagnostic messages to be suppressed. .It Fl R Xo .Sm off +.Oo Ar bind_address : Oc .Ar port : host : hostport .Sm on .Xc @@ -683,16 +756,44 @@ made to port .Ar hostport from the local machine. +.Pp 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: +IPv6 addresses can be specified by enclosing the address in square braces or +using an alternative syntax: .Sm off .Xo -.Ar port No / Ar host No / -.Ar hostport . -.Xc +.Op Ar bind_address No / +.Ar host No / Ar port No / +.Ar hostport +.Xc . .Sm on +.Pp +By default, the listening socket on the server will be bound to the loopback +interface only. +This may be overriden by specifying a +.Ar bind_address . +An empty +.Ar bind_address , +or the address +.Ql * , +indicates that the remote socket should listen on all interfaces. +Specifying a remote +.Ar bind_address +will only succeed if the server's +.Cm GatewayPorts +option is enabled (see +.Xr sshd_config 5 ) . +.It Fl S Ar ctl_path +Specifies the location of a control socket for connection sharing. +Refer to the description of +.Cm ControlPath +and +.Cm ControlMaster +in +.Xr ssh_config 5 +for details. .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 @@ -733,10 +834,23 @@ Users with the ability to bypass file permissions on the remote host (for the user's X authorization database) can access the local X11 display through the forwarded connection. An attacker may then be able to perform activities such as keystroke monitoring. +.Pp +For this reason, X11 forwarding is subjected to X11 SECURITY extension +restrictions by default. +Please refer to the +.Nm +.Fl Y +option and the +.Cm ForwardX11Trusted +directive in +.Xr ssh_config 5 +for more information. .It Fl x Disables X11 forwarding. .It Fl Y Enables trusted X11 forwarding. +Trusted X11 forwardings are not subjected to the X11 SECURITY extension +controls. .El .Sh CONFIGURATION FILES .Nm @@ -796,7 +910,7 @@ and open an X11 window to read the passphrase. This is particularly useful when calling .Nm from a -.Pa .Xsession +.Pa .xsession or related script. (Note that on some machines it may be necessary to redirect the input from @@ -830,7 +944,7 @@ Set to the name of the user logging in. Additionally, .Nm reads -.Pa $HOME/.ssh/environment , +.Pa ~/.ssh/environment , and adds lines of the format .Dq VARNAME=value to the environment if the file exists and if users are allowed to @@ -841,13 +955,13 @@ option in .Xr sshd_config 5 . .Sh FILES .Bl -tag -width Ds -.It Pa $HOME/.ssh/known_hosts +.It Pa ~/.ssh/known_hosts Records host keys for all hosts the user has logged into that are not in .Pa /etc/ssh/ssh_known_hosts . See .Xr sshd 8 . -.It Pa $HOME/.ssh/identity, $HOME/.ssh/id_dsa, $HOME/.ssh/id_rsa +.It Pa ~/.ssh/identity, ~/.ssh/id_dsa, ~/.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 @@ -859,21 +973,21 @@ ignores a private key file if it is accessible by others. 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, $HOME/.ssh/id_rsa.pub +.It Pa ~/.ssh/identity.pub, ~/.ssh/id_dsa.pub, ~/.ssh/id_rsa.pub Contains the public key for authentication (public part of the identity file in human-readable form). The contents of the -.Pa $HOME/.ssh/identity.pub +.Pa ~/.ssh/identity.pub file should be added to the file -.Pa $HOME/.ssh/authorized_keys +.Pa ~/.ssh/authorized_keys on all machines where the user wishes to log in using protocol version 1 RSA authentication. The contents of the -.Pa $HOME/.ssh/id_dsa.pub +.Pa ~/.ssh/id_dsa.pub and -.Pa $HOME/.ssh/id_rsa.pub +.Pa ~/.ssh/id_rsa.pub file should be added to -.Pa $HOME/.ssh/authorized_keys +.Pa ~/.ssh/authorized_keys on all machines where the user wishes to log in using protocol version 2 DSA/RSA authentication. These files are not @@ -881,13 +995,13 @@ sensitive and can (but need not) be readable by anyone. These files are never used automatically and are not necessary; they are only provided for the convenience of the user. -.It Pa $HOME/.ssh/config +.It Pa ~/.ssh/config This is the per-user configuration file. The file format and configuration options are described in .Xr ssh_config 5 . Because of the potential for abuse, this file must have strict permissions: read/write for the user, and not accessible by others. -.It Pa $HOME/.ssh/authorized_keys +.It Pa ~/.ssh/authorized_keys 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 @@ -947,9 +1061,11 @@ be setuid root when that authentication method is used. By default .Nm is not setuid root. -.It Pa $HOME/.rhosts +.It Pa ~/.rhosts This file is used in -.Em rhosts +.Cm RhostsRSAAuthentication +and +.Cm HostbasedAuthentication authentication to list the host/user pairs that are permitted to log in. (Note that this file is @@ -968,33 +1084,35 @@ The recommended permission for most machines is read/write for the user, and not accessible by others. .Pp -Note that by default +Note that .Xr sshd 8 -will be installed so that it requires successful RSA host -authentication before permitting -.Em rhosts -authentication. +allows authentication only in combination with client host key +authentication before permitting log in. If the server machine does not have the client's host key in .Pa /etc/ssh/ssh_known_hosts , it can be stored in -.Pa $HOME/.ssh/known_hosts . +.Pa ~/.ssh/known_hosts . The easiest way to do this is to connect back to the client from the server machine using ssh; this will automatically add the host key to -.Pa $HOME/.ssh/known_hosts . -.It Pa $HOME/.shosts +.Pa ~/.ssh/known_hosts . +.It Pa ~/.shosts This file is used exactly the same way as .Pa .rhosts . The purpose for -having this file is to be able to use rhosts authentication with -.Nm -without permitting login with +having this file is to be able to use +.Cm RhostsRSAAuthentication +and +.Cm HostbasedAuthentication +authentication without permitting login with .Xr rlogin or .Xr rsh 1 . .It Pa /etc/hosts.equiv This file is used during -.Em rhosts +.Cm RhostsRSAAuthentication +and +.Cm HostbasedAuthentication authentication. It contains canonical hosts names, one per line (the full format is described in the @@ -1003,8 +1121,7 @@ manual page). If the client host is found in this file, login is automatically permitted provided client and server user names are the same. -Additionally, successful RSA host authentication is normally -required. +Additionally, successful client host key authentication is required. This file should only be writable by root. .It Pa /etc/shosts.equiv This file is processed exactly as @@ -1019,7 +1136,7 @@ when the user logs in just before the user's shell (or command) is started. See the .Xr sshd 8 manual page for more information. -.It Pa $HOME/.ssh/rc +.It Pa ~/.ssh/rc Commands in this file are executed by .Nm when the user logs in just before the user's shell (or command) is @@ -1027,7 +1144,7 @@ started. See the .Xr sshd 8 manual page for more information. -.It Pa $HOME/.ssh/environment +.It Pa ~/.ssh/environment Contains additional definitions for environment variables, see section .Sx ENVIRONMENT above.