Table of Contents


SSLrshd - SSL remote shell server


SSLrshd [-danLs] [-D port] [-P defpath] [-p logfac] [-R rshchroot] [-t timeout] [-z sslopt]


The SSLrshd server is the server for the ssl_rcmd(3) (routine which is just like rcmd(3) except that SSL transport is used) and, consequently, for the SSLrsh(1) program. The server provides remote execution facilities with authentication based on digitally signed X509 certificates.

The SSLrshd server listens for service requests at the port indicated in the ``sshell'' service specification; see services(5) or on port. When a service request is received the following protocol is initiated:

1. The server initiates a Secure Socket Layer (SSL) handshake with the client. This requires the client to provide its X509 certificate. If the certificate verifies, encrypted communications commence.

2. The client may optionally request to see the server's certificate. If either certificate fails to verify, the connection is closed.

3. If the certificate presented by the client is issued to a host (contains ``.''s and can be found by gethostbyname(3)) then (and only then) the server checks the client's source address and requests the corresponding host name (see gethostbyaddr(3), hosts(5) and named(8)). If the hostname cannot be determined, or does not match the name contained in the certificate, then the certificate is denied access with the message ``wrong hostcert.''

4. The server reads characters from the socket up to a null (`\0') byte. The resultant string is interpreted as an ASCII number, base 10.

5. If the number received above is non-zero, it is interpreted as the port number of a secondary stream to be used for the stderr. A second SSL connection is then created to the specified port on the client's machine.

6. A null terminated user name of at most 16 characters is retrieved on the initial socket. This user name is interpreted as the user identity on the client's machine. It is not used other than for logging.

7. A null terminated user name of at most 16 characters is retrieved on the initial socket. This user name is interpreted as a user identity to use on the server's machine.

8. A null terminated command to be passed to a shell is retrieved on the initial socket. The length of the command is limited by the upper bound on the size of the system's argument list.

9. SSLrshd then validates the user by looking up the client's certificate in the auth files ( /etc/ssl.deny /etc/ssl.root /etc/ssl.local /etc/ssl.users /etc/ by default). If found, and the requested local user or the user root is listed against the certificate then access is granted except that any entry found in /etc/ssl.deny means that access is denied. This allows a site to use a common auth file like /etc/ssl.users or /etc/ and use /etc/ssl.deny and so on to override it as needed.

10. If the file /etc/nologin exists and the user is not the superuser, the connection is closed.

11. A null byte is returned on the initial socket and the command line is passed to the normal login shell of the user unless the -s option is present, in which case /bin/sh is always used. The shell inherits the network connections established by SSLrshd. On machines that can correctly shutdown(2) a socketpair(2) then a socketpair is used for stdin and stdout, otherwise a separate pipe(2) is used for each. If there is no 2nd channel for stderr which is the case for SSLrcp and SSLrdist a socketpair is always used as both rcp and rdistd expect to be able to write to stdin.

The -z option takes arguments like auth=file, cert=file, key=file and verify=n, it is the same as in SSLtelnet, SSLrsh, and stelnetd. Unless -z was given the argument rcmd=1 SSLrshd does the active SSL open and thus does not need a certificate as one must always be provided by the client doing the passive SSL open.

Transport-level keepalive messages are enabled unless the -n option is present. The use of keepalive messages allows sessions to be timed out if the client crashes or becomes unreachable.

The -L option causes all successful accesses to be logged to syslogd(8) as messages.

If the file /etc/rshchroot or the file named by -R rshchroot exists, and the target user is named in it, then SSLrshd will chroot to the directory named in the file or to the user's home directory befor invoking the user's shell. If chroot(2) does not succeed, SSLrshd logs the fact and exits.


Except for the last one listed below, all diagnostic messages are returned on the initial socket, after which any network connections are closed. An error is indicated by a leading byte with a value of 1 (0 is returned in step 10 above upon successful completion of all the steps prior to the execution of the login shell).

Locuser too long.
The name of the user on the client's machine is longer than 16 characters.

Ruser too long.
The name of the user on the remote machine is longer than 16 characters.

Command too long.
The command line passed exceeds the size of the argument list (as configured into the system).

Login incorrect.
No password file entry for the user name existed.

Remote directory.
The chdir or chroot command to the home directory failed.

Permission denied.
The authentication procedure described above failed.

Can't make pipe.
The pipe needed for the stderr, wasn't created.

Can't fork; try again.
A fork by the server failed.

<shellname>: ...
The user's login shell could not be started. This message is returned on the connection associated with the stderr, and is not preceded by a flag byte.


SSLrsh(1), ssl_rcmd(3)


The rshd command appeared in 4.2BSD.

SSLrshd was derrived from the 4.4BSD rshd(8) by Simon J. Gerraty.

The SSL implementation used is SSLeay by Eric Young <> via sjg's libsslfd.


Use of host certificates which usually have unencrypted private keys, is allowed so that non-interactive jobs can use the facility. It is assumed that such keys are not available to all users (eg. read-only by super user or group wheel). In anycase host certificates should only be allowed for trusted systems (under the same administrative control), otherwise, SSLrsh would be not much safer than rsh.


Simon J. Gerraty <>

Table of Contents