SSH(4)                                                     SSH(4)

     NAME
          ssh, netssh - serve SSH v2 over TCP

     SYNOPSIS
          netssh [ -9dkv ] [ -m mntpt ] [ -s srvpt ]

          cd /net/ssh                     ./n/remote
          ./clone                         ./n/status
          ./ctl                           ./n/tcp
          ./keys                          ...
          ./n                             ./n/ch
          ./n/clone                       ./n/ch/ctl
          ./n/ctl                         ./n/ch/data
          ./n/data                        ./n/ch/listen
          ./n/listen                      ./n/ch/request
          ./n/local                       ./n/ch/status
                                          ...

    DESCRIPTION
         The netssh file server implements SSH v2 over TCP.  All of
         the encryption, 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 connec-
         tions.  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 equiva-
             lent 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 num-
         ber 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 currently 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

    SSH(4)                                                     SSH(4)

         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.  Read-
         ing 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 exchange versions, lists of supported
                  algorithms, and to establish the encryption keys to
                  use.
         ssh-userauth
                  Attempt to authenticate a user with the remote sys-
                  tem, with either 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 call-
                  ing 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 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, 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 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

    SSH(4)                                                     SSH(4)

                  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 listening 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 received through the request file.  Among these are env,
         exec, exit-signal, 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 sys-
         tem.

         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 supported 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 prefer-
         ence given in that order.  The final list is message authen-
         tication 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 implementation, there is a system-wide

    SSH(4)                                                     SSH(4)

         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 ses-
         sion, 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 daemon'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 authentication.  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 put-
         ting 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 suit-
         able 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
            attribute/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 sys-
            tem, and the value of the sys attribute is expected to be
            the remote system as specified in the ssh invocation.
         3. The key with the greatest number of matches (most

    SSH(4)                                                     SSH(4)

            specific match) is selected.  Among keys with equal num-
            ber 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 authenti-
         cation 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 after the initial negotiation.  This
         would fit better with dial(2), permit transports other than
         TCP, and allow co-existence of v1 and v2 implementations 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
         `#ยค/caphash', which isn't normally 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.

    SSH(4)                                                     SSH(4)

         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 temporar-
         ily until it's fixed.