SSH2(1) SSH2(1)
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 open-
ing 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).
Page 1 Plan 9 (printed 12/21/24)
SSH2(1) SSH2(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
Page 2 Plan 9 (printed 12/21/24)
SSH2(1) SSH2(1)
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 suit-
able 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 any-
thing 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 directo-
ries, 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 con-
nection number reserved, and writing to it writes to the ctl
Page 3 Plan 9 (printed 12/21/24)
SSH2(1) SSH2(1)
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. Read-
ing 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 connec-
tion 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:
Page 4 Plan 9 (printed 12/21/24)
SSH2(1) SSH2(1)
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 han-
dles 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
Page 5 Plan 9 (printed 12/21/24)
SSH2(1) SSH2(1)
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 alterna-
tive 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 run-
ning 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 facto-
tum 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 suit-
able for loading into factotum.
Page 6 Plan 9 (printed 12/21/24)
SSH2(1) SSH2(1)
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 vali-
date 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.
Page 7 Plan 9 (printed 12/21/24)