cs_connect(3N)

cs_connect, cs_perror -- application interface to the Connection Server

Synopsis

cc [options] file -lnsl

#include <cs.h>

int cs_connect(const char *host, char *service,
	struct csopts *cs_opt, int *error);

void cs_perror(const char *string, int error);

Description

The library routines cs_connect and cs_perror provide an interface that network applications use to establish an authenticated TLI/XTI connection to a network service on host. The Connection Server interface shields the client application from details of connection establishment and authentication. Since cs_connect performs authentication on behalf of the client process, authentication is effectively automated. The way in which cs_connect accesses authentication schemes also allows the system administrator to use modular schemes that are interchangeable and can be administered on a per-service basis.

cs_connect communicates with the Connection Server daemon, which establishes a TLI/XTI connection on behalf of the client application and returns a file descriptor associated with the connection. The Connection Server uses the Network Selection mechanism to determine the transport provider needed to connect to the specified service and uses the Name-to-Address Mapping facility to obtain the address of the network service over that transport.

The arguments are defined as follows:

host

The name of the server machine that is supplying the service. This name can be any string acceptable to the Name-to-Address Mapping facility.

service

The name of the service with which the application wishes to communicate. To connect to a service via the NLPS server use the following syntax:

   listen:service_tag

where service_tag is the argument taken from the first field in _pmtab on the server machine.

cs_opt

To bind to a reserved port, or to make a special type of network selection, the csopts structure may be used. Since applications rarely need this functionality, this argument will typically be NULL. Network selection usually means restricting the choice of transport providers by name (where a transport provider name is specified in the first field of the /etc/netconfig file). The preferred method of selection is setting the NETPATH environment variable to a colon-separated list of transport provider names. To do such special types of network selection as restricting by network semantics, use csopts.

The csopts structure 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 as follows:

struct netconfig *nc_p

To restrict the networks which may be used in making a connection, the user may set the element nc_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_opt

To bind to a reserved port, the user should set this element to ND_SET_RESERVEDPORT.

struct netbuf *nb_p

To bind to a reserved port on a specific address, nd_opt should be set as described above and nb_p should be set to point to a netbuf structure. The buf field of the netbuf structure should point to a sockaddr structure. See sys/socket.h.

error

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

string

The string that is to precede error messages.

The Connection Server establishes a connection by trying each visible transport provider in the order listed in /etc/netconfig. Users can choose the transport providers to be tried and the order in which they will be tried, 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 pipe and sends the hostname 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 the csopts structure 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/XTI operations (t_snd(3xti), t_rcv(3xti), and so on) on the file descriptor.

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.

Files

/etc/cs/auth: Connection Server authentication scheme file
/etc/iaf/serve.alias: database of network services and their aliases
/etc/iaf/serve.allow: database of allowable authentication schemes and network services
/etc/inet/hosts: Name-to-Address Mapping hosts file for TCP. For compatibility, /etc/inet/hosts is linked to /etc/hosts.
/etc/inet/services: Name-to-Address Mapping services file for TCP. For compatibility, /etc/inet/services is linked to /etc/services.
/etc/net/transport_name/hosts: Name-to-Address Mapping hosts file for transport_name
/etc/net/transport_name/services: Name-to-Address Mapping services file for transport_name
/etc/netconfig: Network Selection database file
/var/adm/log/cs.debug: Connection Server debug file
/var/adm/log/cs.log: Connection Server log file
/usr/lib/locale/locale/LC_MESSAGES/uxnsu

Return values

On success, cs_connect returns a file descriptor containing a positive integer. On failure, cs_connect returns -1.

On failure, cs_perror may report the following errors:

CS_NO_ERROR: No Error
CS_SYS_ERROR: System Error
CS_DIAL_ERROR: Dial error
CS_MALLOC: No Memory
CS_AUTH: Authentication scheme specified by server is not acceptable
CS_CONNECT: Connection to service failed
CS_INVOKE: Error in invoking authentication scheme
CS_SCHEME: Authentication scheme unsuccessful
CS_TRANSPORT: Could not obtain address of service over any transport
CS_PIPE: Could not create CS pipe
CS_FATTACH: Could not mount remote stream to CS pipe
CS_CONNLD: Could not push CONNLD
CS_FORK: Could not fork CS child request
CS_CHDIR: Could not chdir
CS_SETNETPATH: Host/service not found over available transport
CS_TOPEN: TLI/XTI failure: t_open failed
CS_TBIND: TLI/XTI failure: t_bind failed
CS_TCONNECT: TLI/XTI failure: t_connect failed
CS_TALLOC: TLI/XTI failure: t_alloc failed
CS_MAC: MAC check failure or Secure Device access denied
CS_DAC: DAC check failure or Secure Device access denied
CS_TIMEDOUT: Connection attempt timed out
CS_NETPRIV: Privileges not correct for requested network options
CS_NETOPTION: Netdir option incorrectly set in csopts struct
CS_NOTFOUND: Service not found in server's _pmtab
CS_LIDAUTH: Connection not permitted by LIDAUTH.map

References

cs(1Mbnu), dials(3N), reportscheme(1Mbnu)

Notices

Not all values stored in the csopts structure are sent to the Connection Server. In particular, the last two elements of nc_p, that is, nc_lookups and nc_nlookups, are not sent. See netconfig(4bnu).

The Connection Server daemon logs a message to /var/adm/log/cs.log on startup.

If it is invoked with the debug option (-d), the Connection Server daemon prints debug information to /var/adm/log/cs.debug:

/usr/sbin/cs -d

In order for network applications to use cs_connect, the following network components must be correctly administered:

the port monitor
the Identification and Authentication Facility (IAF)
ID Mapping
Name-to-Address Mapping

Examples

A typical call to cs_connect is of the form:

   #include <cs.h>
   	. . .
   
   int error=0;
   	. . .
   

   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 */
   	. . .