term% cat index.txt SSH(4) Kernel Interfaces Manual SSH(4)
NAME
ssh, netssh - serve SSH v2 over TCP
SYNOPSIS
netssh [ -9dkv ] [ -m mntpt ] [ -s srvpt ]
cd /net/ssh ./clone ./ctl ./keys ./n ./n/clone ./n/ctl ./n/data
./n/listen ./n/local ./n/remote ./n/status ./n/tcp ... ./n/ch
./n/ch/ctl ./n/ch/data ./n/ch/listen ./n/ch/request ./n/ch/status ...
DESCRIPTION
The netssh file server implements SSH v2 over TCP. All of the encryp‐
tion, authentication, and SSH protocol are handled by a server managing
SSH tunnels that appears as a protocol directory, /net/ssh, similar to
those of ip(3) but with an extra level of hierarchy for SSH channels
within connections. Options are:
-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.
-v Do not verify the remote system's host key (which is somewhat
pedantic anyway). This lets us talk to SSH v1 systems. The
presence of /env/nosshkeyverify is equivalent to specifying this
option.
/net/ssh contains a set of numbered directories, each of which is an
SSH connection that is currently active or has been used in the past,
per ip(3). Opening clone reserves an SSH connection, reading from it
returns 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. /net/ssh/ctl cur‐
rently implements no commands. Finally, the keys file is used by
ssh2(1) to relay information about keys and passwords between a user
and the SSH server.
Each of the numbered connection directories contains a set of numbered
directories, one for each channel used on that connection (see Channel
Directories below). 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 returns the connection number (also
the name of that directory). Commands may be written to a connection's
ctl file:
connect
Dial the remote system and perform the initial handshake to ex‐
change 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 ei‐
ther public key authentication or a password.
ssh-connection
Currently unsupported.
hangup Shut down a connection and all of its channels.
announce
/net/ssh will accept connection requests from remote systems.
accept Do the initial connection handshake with the calling system.
reject Send back a connection rejection message to the caller 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, a server 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 most-recently established channel.
Channel Directories
In each channel directory, /net/ssh/conn/chan, reads from channel ctl
files return the channel number. Commands that may be written to a
channel ctl file include:
connect
Create a new channel over this connection. SSHv2 defines ses‐
sion, x11, forwarded-tcpip, and direct-tcpip channels. The con‐
nect 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 neces‐
sary 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 willingness to accept new channel requests from the
calling system.
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 lis‐
tening program should not write an accept or reject message to the ctl
file.
SSHv2 defines a number of out-of-band channel requests, sent and re‐
ceived through the request file. Among these are env, exec, exit-sig‐
nal, exit-status, pty-req, shell, signal, subsystem, window-change,
x11-req, and xon-xoff. Sshsession only fully handles the shell and
exec requests. Others are blithely acknowledged, rejected or ignored,
depending on whether they are expected to be available by the remote
system.
The channel status file contains one of: Empty, Allocated, Initting,
Listening, Opening, Negotiating, Authing, Established, Eof, Closing, or
Closed.
Cryptographic Algorithms
During the initial connection exchange, both parties send lists of sup‐
ported algorithms. The first list is for key exchange; we support
diffie-hellman-group1-sha1 and diffie-hellman-group14-sha1. The second
list is the set for which corresponding host keys exist; we support
ssh-rsa and ssh-dss. The next lists are encryption algorithms, which
may be negotiated independently for the server-to-client and client-to-
server directions; we support aes128-cbc, aes192-cbc, aes256-cbc, 3des-
cbc, and arcfour with preference given in that order. The final list
is message authentication code algorithms; we only support hmac-sha1.
Keys and Management
Various keys are used by the SSH server. Most of them are expected to
be stored in the instance of factotum(4) running in the namespace of
that server instance. Sometimes there are alternative locations.
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
files of the same names in the directory where netssh 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 implementa‐
tion, 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, or if no public key is
listed for a remote server, ssh (see ssh2(1)) 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.
An SSH daemon, such as sshsession in ssh2(1), must also have a list of
public keys for public key authentication. Again, these keys must be
stored in the factotum instance running in the name space of the dae‐
mon's SSH server. Each such key must have the attributes role=verify,
proto=rsa, and either user= or sys=.
The next key is a user's private key to be used for public key authen‐
tication. We only support RSA keys for this, and the key must be in
the factotum instance running in the namespace of the ssh(4) instance.
Creating a key and putting it in factotum can be done by:
auth/rsagen >key; read -m key >/mnt/factotum/ctl
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. See
ssh2(1) for rsa2ssh2.
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 any attri‐
bute/value pair specified in a -z option to ssh 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 attri‐
bute is expected to be the remote system as specified in the ssh in‐
vocation.
3. The key with the greatest number of matches (most specific match) is
selected. Among keys with equal number of matches, the first is
chosen.
For password-based user authentication, netssh can run in one of two
modes. If given -k, it will validate passwords against those stored in
/mnt/keys provided by keyfs(4). If run without -k, it will validate
passwords with an authentication server using auth_userpasswd in
auth(2).
FILES
/sys/lib/ssh/keyring
System-wide known host public keys.
$home/lib/keyring
Per-user known host public keys.
/env/nosshkeyverify
SOURCE
/sys/src/cmd/ssh2
SEE ALSO
ssh2(1), ip(3), factotum(4), keyfs(4), authsrv(6), dsa(8), rsa(8)
RFCs 4250, 4251, 4252, 4253, 4254, and 4419
BUGS
Netssh shouldn't have to run as the host owner and using factotum(4)
correctly would permit this.
Netssh should be simplified by removing the top (connection) level of
the /net/ssh hierarchy and multiplexing a single network connection af‐
ter the initial negotiation. This would fit better with dial(2), per‐
mit transports other than TCP, and allow co-existence of v1 and v2 im‐
plementations on a single TCP port. Better still, use only a single
channel (since we don't use X11) and eliminate the top 2 levels.
Netssh authentication via keyfs and public keys uses which isn't nor‐
mally present after cpurc runs, so netssh needs to be converted to use
factotum.
netssh -k assumes that keyfs is mounted, which is typically only true
of authentication servers.
The keys file protocol should be documented.
Only capable of using TCP for underlying connections.
Can't coexist with SSH v1 on the same port.
Several aspects of key management still need some work.
TCP/IP forwarding and some potentially useful channel requests have not
been implemented.
Zlib compression is not supported and probably not needed.
The SSH v2 protocol is a classic second system: over-engineered, overly
complicated, misdesigned and jammed full of pointless goodies.
Host key verification is broken, so it's disabled temporarily until
it's fixed.
SSH(4)