SSL_RCMD(3)

NAME
ssl_rcmd, - establish an SSL stream to a remote command

SYNOPSIS
#include <sslfd.h>
int
ssl_rcmd(char **ahost, int inport, const char *locuser, const char *remuser, const char *cmd, int *fd2p);

DESCRIPTION
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).

The ssl_rcmd() function looks up the host *ahost using gethostbyname(3), returning -1 if the host does not exist. 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 SSLshell is looked up via getservbyname(3).

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 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).

DIAGNOSTICS
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.

SEE ALSO
rcmd(3), SSLrsh(1), SSLrshd(8)

HISTORY
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.

AUTHOR
Simon J. Gerraty <sjg@quick.com.au>