NAME

ssh, sshsession, sshtun, scp, rsa2ssh2 – Plan 9 support for SSHv2

SYNOPSIS

ssh [ –CdriIvaxkKm ] [ –l user ] [ –n dir ] [ –s subsystem ] [ –z attribute=value ] addr [ cmd [ args ]]
scp [host:]file [host:]file
scp [host:]file ... [host:]dir
sshsession [ –t ] [ –n namespace ] [ –R dir ] [ –r dir ] [ –s command ] [ –S srvpt ]
sshtun [ –9dk ] [ –m mntpt ] [ –s srvpt ]
rsa2ssh2 [ file ]

DESCRIPTION

These programs collectively provide support for SSHv2 for Plan 9. It supports only SSHv2 and will reject connections with a remote system that supports only SSHv1. Both client and server operation is provided. All of the encryption, authentication, and SSH protocol are handled by a tunnel that is presented as a protocol directory in /net.

CLIENT OPERATION

Ssh and scp are the applications that provide normal client access to the SSH tunnel. Ssh dials a remote system and runs a shell (or some other command) there. In its simplest usage, it works like any other ssh command line application. So the command:
ssh root@hannibal
will result in a command prompt on the machine hannibal logged in as root. To accomplish this, ssh first looks to see if there is an ssh tunnel in /net, and if not, it runs sshtun with no options. Using the usual technique of opening the clone file and writing a connect message, ssh dials the remote ssh server and exchanges encryption keys with the server using Diffie–Hellman key exchange. A similar clone file and connect message protocol creates a session in the established connection. In the course of session creation, ssh first attempts to authenticate the user with the server using public key authentication. If that fails, it then prompts for a password, and attempts to authenticate with password authentication. It also passes across the value of the environment variable TERM as would be set if ssh is run inside of vt(1).
Following the convention in other Plan 9 communications applications, typing a control–\ will result in a >>> prompt. There are currently only four commands that can be issued at that prompt: C to toggle cooked (local echo) mode, c to continue the ssh session, h to print a list of the available commands, r to toggle the supression of carriage returns, and q to close the session started by this instance of ssh.
Ssh can take the following command–line options:
C    Cooked mode, echo characters typed locally, this is useful on high latency links and allows the use of all of rio(1)'s editing facilities.
d    Increase the amount of debugging output.
l    A deprecated method of specifying the user name on the remote system.
r    Strip carriage return characters coming from the remote system. This will normally be desired when running in a raw rio(1) window or from within win in acme(1). It is normally not used when running ssh from within vt(1).
k    Skip the attempt to authenticate using public key authentication.
K    Do not fall back to password authentication. If the public key authentication fails, ssh will exit.
m    Remove the special meaning of control–\. This is needed by scp to prevent that character in files being copied from triggering the special command mode.
n    Specify the network directory of an alternate network to use. The default is /net.
–s    
Request an ssh2 subsystem on the remote server, this is used by sftpfs(4).
z    Used to specify which of several possible keys to use.
i –I
Sets ssh to interactive (–i) or non–interactive (–I) mode. This determines whether the user is prompted for a password if none is found in factotum. Without either of these options, ssh uses interactive mode if run in a term window.
v –a –x
All no–ops but included for compatibility with scp.
The scp program does all its work by running ssh to execute an instance of scp on the server, it functions normally with this implementation of ssh.

SERVER OPERATION

The sshsession program provides the server functionality for SSHv2. It is suitable for running by listen(8) Therefore, it is not normally run directly by the user. Like ssh, it does all of its communication through the tunnel. Sshsession handles running a shell or a requested command when a remote system requests a new connection and session.
One can run a private ssh server by first setting up the tunnel and then running the command:
aux/listen1 –t ssh!*!2222 sshsession
Similarly, a system–wide ssh server can be run by including a file called ssh22 in /rc/bin/service.auth.
With no command–line options, sshsession runs in a way suitable for the typical ssh server. Several aspects of its behavior can be changed, however, via the following options:
s    Specify an alternative to /bin/rc for shell sessions.
r    Specify a starting directory for the ssh session to run in.
R    Same as –r but additionally prevent any arguments on the command line to be executed from referencing anything outside this directory. This is mostly used to limit where scp can deposit or get files.
n    Specify a namespace(6) file to be used before starting the shell or running the requested command. The default is /lib/namespace.
–S    
Specify an alternative file in /srv where the tunnel can be found if it is not already mounted in /net.
–t    
Specify that the sshsession instance is trusted and should run in the same name space as the listen that started it.
For shell channels, sshsession will print the contents of /sys/lib/motd to the client, if that file is present.

TUNNEL

Sshtun is the program that implements the ssh tunnel used by ssh and sshsession. It handles all the necessary work to implement SSHv2. The following options may be given to sshtun
d    Increase the amount of debugging output.
k    Use keyfs(4) for password validation.
m    Mount point for the ssh protocol directory; defaults to /net.
–s    
Name to post in /srv. If –s is not given, no file is posted to /srv.
Access to the tunnel is provided though a protocol directory /net/ssh. This directory contains a set of numbered directories, each of which is an ssh connection that is curently active or has been used in the past. It also serves the files clone, ctl, and keys. Clone behaves like the clone files in other protocol directories. In particular, opening it reserves an ssh connection, reading from it gets the connection number reserved, and writing to it writes to the ctl file in the numbered connection directory. Reading the ctl file returns the most active state of any connection. There are currently no commands that can be written to /net/ssh/ctl. Finally, the keys file is used by ssh to relay information about keys and passwords between a user and the tunnel.
Each of the numbered connection directories also contains a set of numbered directories, one for each channel used on that connection. It also contains the files clone, ctl, data, listen, local, remote, and status. Similar to the top–level clone file, opening a connection's clone file reserves a channel and gives access to its ctl file. Reading from the ctl file gives the connection number (also the name of that directory). Several commands are available to write into a connection's ctl file:
connect
This command dials the remote system and carries out the initial handshake to exchange versions, lists of supported algorithms, and to establish the encryption keys to use.
ssh–userauth
Attempt to authenticate a user with the remote system, with either public key authentication or a password.
ssh–connection
Currently unsupported.
hangup
Shut down a connection and all of its channels.
announce
Announce the tunnel's willingness to accept connection requests from remote systems.
accept
Do the initial connection handshake with the remote system.
reject
Send back a connection rejection message and shut down the connection.
Because data is always carried over a channel, the connection data file is not used for usual data. However, reads from the connection data file do return the capability needed for sshsession to change identity to the user logging in. As with other protocol directories, opens on listen block until a remote system establishes a connection, at which point, the application should write either an accept or reject message to the ctl file. The local and remote files give the IP addresses and port numbers of the local and remote systems. The connection status file gives the status of the channel with the status closest to Established.
Each channel directory contains the files ctl, data, listen, request, and status. As with connections, reads from channel ctl files return the channel number. Commands that may be written to a channel ctl file include:
connect
Initiate the establishment of a new channel over this connection. SSHv2 defines session, x11, forwarded–tcpip, and direct–tcpip channels. The connect command defaults to a session channel if no argument is given. (This implementation correctly handles only session channel requests.)
global
Reserved for future development. In particular, this is necessary to support TCP/IP forwarding.
hangup
Shut down a channel. If this is the last open channel on this connection, then shut down the connection too.
announce
Announce the willingness to accept new channel requests from the remote end.
The channel data file is the file over which all application data is carried. Opens of the channel listen file block until a channel is opened by the remote end. Unlike the connection listen file, the listening application should not write an accept or reject message to the ctl file. SSHv2 defines a number of out of band channel requests. These are sent and received through the request file. Among these are pty–req, x11–req, env, shell, exec, subsystem, window–change, xon–xoff, signal, exit–status, and exit–signal. Sshsession only fully handles the shell and exec requests. Others are either blithly acknowledged, rejected or ignored, depending on whether they are expected to be available by the remote system. Finally, the channel status file gives the current status of the channel. The possible statuses are Empty, Allocated, Initting, Listening, Opening, Negotiating, Authing, Established, Eof, Closing, and Closed.

CRYPTOGRAPHIC FEATURES

During the initial connection exchange, both parties send lists of supported algorithms. The first algorithms listed are for key exchange. This implementation supports the diffie–hellman–group1–sha1 and diffie–hellman–group14–sha1 key exchange algorithms. The second list is the set of algorithms for which corresponding host keys exist. Both the ssh–rsa and ssh–dss algorithms are supported. The next lists are encryption algorithms, which may be negotiated independently for the server–to–client and client–to–server directions. This implementation supports the aes128–cbc, aes192–cbc, aes256–cbc, 3des–cbc, and arcfour algorithms with preference given in that order. Finally, the message authentication code algorithms are listed, and only the hmac–sha1 algorithm is supported here.

KEY MANAGEMENT

There are a number of different keys that are used by the SSH tunnel. Most of them are expected to be stored in the instance of factotum(4) running in the name space of that tunnel instance. However, in some cases, there are alternative locations available.
The first key needed is the host key for server operation. In the case of the keys being stored in factotum(4), these keys will be the first ones listed with proto=rsa and proto=dss. Alternatively, these keys can be specified in the environment variables rsakey and dsskey or in the same named files located in the directory where sshtun is started.
The next set of keys are the public host keys used by clients to verify the identities of servers. As with the original Plan 9 SSH implementation, there is a system–wide list of these in /sys/lib/ssh/keyring and each user may have a list in $home/lib/keyring. If a public key for a remote server is listed and matches the one offered by the server, the connection proceeds. If a public key for a remote server is listed but does not match the one offered by the server, the connection is terminated. If no public key is listed for a remote server, ssh presents the key to the user and asks whether to reject the key, accept the key only for that session, or accept the key permanently. The last option causes the key to be written to the user's keyring. In the case of a mismatching key, the accept option can either be to add to or replace the old key.
The next key is a user's private key to be used for public key authentication. Currently, only RSA keys are supported for this, and the key must be in the factotum instance running in the name space of the tunnel instance. Creating a key and putting it in factotum can be done by:
auth/rsagen > key
cp key /mnt/factotum/ctl
Of course, the key file will normally be loaded when factotum is started either by way of secstore(1) or directly in the user's lib/profile. The following command will extract the public part of the key and add it to the authorized_keys file on a remote UNIX system.
grep 'proto=rsa' /mnt/factotum/ctl | rsa2ssh2 |
ssh user@unix 'cat >> .ssh/authorized_keys'
The command
auth/pemdecode 'RSA PRIVATE KEY' id_rsa | auth/asn12rsa > key
will translate a private key used with OpenSSH to one suitable for loading into factotum.
To disambiguate when a user has more than one private key stored in factotum, the following selection criteria are applied:
1.    The selected key must have both proto=rsa and !dk= attributes present.
2.    Among those keys, the attributes user=, sys=, and the attribute/value pair specified in the –z option to ssh, if any, are examined. The value of the user attribute is expected to be the user name being authenticated on the remote system, and the value of the sys attribute is expected to be the remote
system as specified on the ssh command line.
3.    The key with the greatest number of matches is selected. Among keys with equal number of matches, the first is chosen.
An SSH server must also have a list of public keys that can be used for public key authentication. Again, these keys must be stored in the factotum instance running in the name space of the server's tunnel. Each such key must have the attributes role=verify, proto=rsa, and either user= or sys=.
For password–based user authentication, sshtun can operation in one of two modes. If given the –k option, it will validate passwords against those stored in /mnt/keys provided by keyfs(4). If run without –k, sshtun will attempt to validate passwords with an authentication server using the auth_userpasswd (see auth(2)) call.

FILES

/sys/lib/ssh/keyring
System–wide known host public keys.
$home/lib/keyring
Per–user known host public keys.
/sys/lib/motd
Message of the day file.

SEE ALSO

RFCs 4250, 4251, 4252, 4253, 4254, and 4419, secstore(1), vt(1), factotum(4), keyfs(4), authsrv(6), listen(8), rsa(8), sftpfs(4)

BUGS

TCP/IP forwarding and some potentially useful channel requests have not been implemented. Zlib compression is not supported, also probably not needed. Several aspects of key management still need some work.