DOC HOME SITE MAP MAN PAGES GNU INFO SEARCH PRINT BOOK
 
Network services

The connection server application interface

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:


NOTE: If a scheme cannot be obtained either because the address of reportscheme could not be obtained or because a connection to reportscheme could not be established, the connection server assumes that no authentication scheme is registered. This allows for backward compatibility with System V systems previous to Release 4.0ES.

If any of the above processes fails, the reason for failure is logged.

Necessary administration

The following administrative steps are required for each network service:

Server administration

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.

Client administration

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.

cs_connect() and cs_perror()

#include <cs.h>

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

void cs_perror(char *string, int error)

The arguments have the following values:

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 listen server use the following syntax:
listen:service tag
where 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''.

cs_opt
To bind to a reserve port, or to make a special type of network selection, the struct csopts 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 special types of network selection such as restricting by network semantics, use the struct csopts.

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_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. See netdir(3N).

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. See netdir(3N).

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

... 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 successful completion, cs_connect() returns a file descriptor containing a positive integer. cs_connect() returns a -1 on failure.

On failure, the status value may be set to the following:


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 failure: t_open failed

CS_TBIND
TLI failure: t_bind failed

CS_TCONNECT
TLI failure: t_connect failed

CS_TALLOC
TLI 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 struct csopts

CS_NOTFOUND
Service not found in server's _pmtab

CS_LIDAUTH
Connection not permitted by LIDAUTH.map

dials()

Refer to the dials(3N) manual page for information.


© 2004 The SCO Group, Inc. All rights reserved.
UnixWare 7 Release 7.1.4 - 27 April 2004