ssl_rcmd, - establish an SSL stream to a remote command
#include <sslfd.h>
int
ssl_rcmd(char **ahost, int inport, const char *locuser,
const char *remuser, const char *cmd, int *fd2p);
The ssl_rcmd() function is used to execute a command on a remote machine using an authentication scheme based on X.509 digitally signed certificates. The transport used is the Secure Socket Layer (SSL) to the SSLrshd(8) server running on the remote host. Because trust is placed in the X.509 certificates rather than hosts or users, there is no need for reserved ports or for programs that use ssl_rcmd() to be set-uid. By comparision see rcmd(3), and rshd(8).
If ssl_setopt(3) was called with an argument like proxy=url or one of the environment variables sshell_proxy,https_proxy,http_proxy is set, then ssl_rcmd() will connect to the HTTP proxy described by the url and ask it to connect to *ahost. The proxy can be given as just host:port though more commonly as a url like http://host[:port]. The variable no_proxy is used to disable proxying for certain domains. A proxy is never used for unqualified host names. If the variable proxy_auth_token is set, its content (which should be base64 encoded) is included as a Basic authentication token for the proxy. In general, proxies which do not require it will not be upset. Note that the proxy must be configured to allow connections to ports other than ``https'', specifically the ``sshell'' port (614).
The ssl_rcmd() function looks up the host *ahost using gethostbyname(3), returning -1 if the host does not exist and a proxy is not being used. Otherwise *ahost is set to the standard name of the host and a connection is established to a server residing at the well-known Internet port inport. If inport is 0 or -1, then the service sshell is looked up via getservbyname(3) and if that fails, the official port 614 is used.
If the connection succeeds, then ssl_rcmd() establishes the SSL protocol over the connection. Note that the SSL protocol is established with SSLrshd(8) playing the active role, this is because the passive side ( ssl_rcmd() in this case) is always required to supply a certificate which is what is desired for this facility.
If ssl_setopt(3) was called with rcmd=1 for both SSLrshd(8) and the client, then ssl_rcmd() will play the active role. Allowing SSLrshd(8) to support the passive role makes it easier to support clients written in Java.
If the SSL negotiation succeeds and SSLrshd(8) accepts the offered certificate as authority to run as remuser, a socket in the Internet domain of type SOCK_STREAM is returned to the caller, and given to the remote command as stdin and stdout. If fd2p is non-zero, then an auxiliary SSL channel to a control process will be set up, and a descriptor for it will be placed in *fd2p. The control process will return diagnostic output from the command (file descriptor 2) on this channel, and will also accept bytes on this channel as being UNIX signal numbers, to be forwarded to the process group of the command. If fd2p is 0, then the stderr (file descriptor 2 of the remote command) will be made the same as the stdout and no provision is made for sending arbitrary signals to the remote process, although you may be able to get its attention by using out-of-band data.
The protocol is described in detail in SSLrshd(8).
The ssl_rcmd() function returns a valid socket descriptor on success. It returns -1 on error and prints a diagnostic message on the standard error.
rcmd(3), SSLrsh(1), SSLrshd(8)
The rcmd() function appeared in 4.2BSD.
ssl_rcmd() was derrived from the 4.4BSD rcmd(3) by Simon J. Gerraty.
The SSL implementation used is SSLeay by Eric Young <eay@mincom.oz.au> via sjg's libsslfd.
Simon J. Gerraty <sjg@crufty.net>