|
|
The application interface to the connection server consists of the library routines cs_connect(3N), cs_perror(3N), and dials(3N). The connection server does the following:
If any of the above processes fails, the reason for failure is logged.
The following administrative steps are required for each network service:
The administrator of the server machine registers the name of the authentication scheme for a network service. Registering a scheme name consists of including it in the port monitor administrative file for the port monitor under which the service runs. The service line in this file includes a ``scheme'' field for the authentication scheme name. The values in the ``scheme'' field are manipulated by pmadm. See ``The Service Access Facility'' or the pmadm(1M) manual page. Once an authentication scheme is registered, client machines can obtain its name from the reportscheme(1Mbnu) service.
The administrator of the client machine associates a list of allowable authentication schemes with the network services it uses by entering this information in the /etc/iaf/serve.allow file on the client machine. The name-to-address mapping files, hosts and services, must also be in place. See ``Administering name-to-address mapping''
The administrator may also want to set up an /etc/iaf/serve.alias file. The /etc/iaf/serve.allow and /etc/iaf/serve.alias files are described in ``Administering the connection server''.
Once these two steps are complete, client machine applications can use the connection server Interface library routines.
#include <cs.h>The arguments have the following values:int cs_connect(char *host, char *service, struct csopts *cs_opt, int *error);
void cs_perror(char *string, int error)
listen:service tagwhere service tag is the argument taken from the first field in the _pmtab file on the server machine. For more information on the listen server, see ``Writing a port monitor for the SAC''.
struct csopts is defined in the header file /usr/include/cs.h as:
struct csopts {
struct netconfig *nc_p;
int nd_opt;
struct netbuf *nb_p;
The elements of this structure are described below.
struct netconfig *nc_pnc_p to point to a netconfig
structure.
A network will be selected which matches with all the elements in the
netconfig structure that have been filled in by the user
(see
netconfig(4bnu)).
For example, if the user wants to use only TCP
protocol networks,
then nc_p->nc_proto
should be set to tcp and all other elements should be set to zero or
NULL.
If the user does not want to restrict network selection but does want
to bind to a reserved port, nc_p should be
set to
(struct netconfig *)NULL
and the other members should be set as described below.
int nd_optstruct netbuf *nb_pnd_opt should be set
as described above and nb_p should be set to point to a
netbuf structure.
See
netdir(3N).
int that is declared in the application that calls
cs_connect
and
cs_perror.
A pointer to error is passed to
cs_connect
and will
be set to an error value.
Calling
cs_perror
with the value of
error will print out an appropriate error message.
The connection server establishes a connection by trying each visible transport provider in the order listed in etc/netconfig. Each transport provider is tried until a successful connection is made. Users can choose the transport providers to be tried and the order for trying them by setting the NETPATH environment variable to a colon-separated list of transport provider names. (A transport provider name is specified in the first field of the /etc/netconfig file.)
cs_connect() establishes communication with
the connection server daemon via a named Stream
and sends the host name and
service name as parameters.
cs_connect() also sends the value of the NETPATH environment variable,
or a NULL value if NETPATH is not set.
If the pointer to struct csopts
is not NULL, cs_connect will send the contents of the three member structures
with the exception of the last two elements of struct netconfig
(that is, nc_lookups and nc_nlookups).
The connection server daemon uses the network selection and name-to-address mapping facilities to attempt to establish an authenticated connection to host for service over each available transport until a connection is established or connection establishment fails for every transport. Transport providers may be restricted by setting the NETPATH environment variable to a colon-separated list of transport provider names. See environ(5).
The connection server consults the /etc/iaf/serve.allow file for the list of authentication schemes acceptable to the client machine for service on host.
If an authenticated connection is established, the connection server returns a file descriptor associated with the connection. The application can then perform all TLI operations (t_snd(3xti), t_rcv(3xti), for example) on the file descriptor.
If the Enhanced Security package is installed, the connection server daemon is a trusted process that acts on behalf of the client application; it executes privileged operations such as authentication and device allocation, and, if the application satisfies all required system criteria, it passes the authenticated file descriptor back to the client application. All applications that access network devices must use the connection server interface library to request connections.
cs_perror() prints an error message on the standard error. The error message is derived from indexing a value referenced by error, which was set by cs_connect(). The message is preceded by string and a colon.
A typical call to cs_connect() is of the form:
#include<cs.h> ... int error=0; int fd;On successful completion, cs_connect() returns a file descriptor containing a positive integer. cs_connect() returns a -1 on failure.... if ((fd = cs_connect("host", "service", (struct csopts *)NULL, &error)) < 0) { /* do error handling */ cs_perror("application specific string", error); exit(1); } /* continue with normal execution */ ...
On failure, the status value may be set to the following:
Refer to the dials(3N) manual page for information.