ad_library(3) DG/UX B2 Security R4.12MU02 ad_library(3)
NAME
adlibrary: dgadagenttoclientfd, dgadfdclose,
dgadkitcreate, dgadkitfree, dgadkitsend, dgadkitreceive -
authentication server interface routines in libsm.a
SYNOPSIS
#include <dgadinterface.h>
int dgadagentstart (char * accessname)
void dgadagentstop (char * accessname)
int dgadagenttoclientfd ( )
int dgadfdclose (int fd)
int dgadkitcreate (dgadkitt ** adkitpp)
void dgadkitfree (dgadkitt ** adkitpp)
int dgadkitsend (int fd,
dgadkitt ** adkitpp)
int dgadkitreceive (int fd,
dgadkitt ** adkitpp)
DESCRIPTION
The functions in adlibrary provide support for communicating with
the credential server (daemon), credentiald, allowing the writing of
new authentication agents. On DG/UX systems configured for
authorization and authentication, the server program dgpasswd is an
example of such an agent. These agents can require users to
authenticate in new ways other than just with a password.
The functions return 0 on success and -1 on failure unless otherwise
noted.
dgadagentstart
This function takes care of registering the authenticator with the
system so that other system components, like credentiald, can find
it. accessname should be a simple string containing only characters
that would be valid in a UNIX filename. This identifier must be
unique among authenticators on the system. It will be the name by
which this authenticator is known on the system. This function must
be called by an authenticator at start-up, before calling any of the
other functions in this family. The authenticator will not be able
to receive any connections and will not appear to exist on the system
until after returning from this function.
Errors:
EINVAL accessname is not a valid pointer.
ENOMEM The system was unable to allocate sufficient memory to
complete the request.
EIO An I/O error occurred while writing to the filesystem.
EACCESS The process did not have sufficient privilege to write to the
filesystem in the step of registering with the system.
EROFS A read-only filesystem prevented the function from writing.
ENOSPC There was insufficient filesystem space for start-up to
complete.
EPERM The pathname contains a character not in the allowed
character set.
dgadagentstop
This function de-registers the authenticator with the system. It
will only remove resources that were created by a call to
dgadagentstart with the same value for accessname. After this
function returns, the authenticator can no longer receive
connections. Calling any of the functions on this man page other
than dgadagentstart after a call to this function results in
undefined behavior.
dgadagenttoclientfd
This function will block when called, until a connection request is
received. It then returns a file descriptor which is used for any
further communication. This file descriptor should be used as the fd
argument for both dgadkitsend and dgadkitreceive.
This function performs an event check when it receives a connection
request. It will only succeed if the process attempting to open the
connection has appropriate privilege. On systems configured for
capability, this means that the process must have the
DG_CAP_ACCESS_AUTHENTICATOR capability in its permitted set. On
systems without capability, the process must have a uid of 0. If a
process without appropriate privilege attempts to connect, this
function will return to the caller with an error and errno set to
EACCES so that the caller may take appropriate action (e.g.
auditing).
Errors:
EINTR The call was interrupted by a signal.
ENOMEM The system was unable to allocate sufficient memory to
complete the request.
EINVAL The start-up data read from the connection was not what was
expected.
EACCES A process lacking appropriate privilege attempted to open a
connection.
dgadfdclose
This function closes the connection to the credential server. It
takes the file descriptor that was returned by
dgadagenttoclientfd() as an argument. Possible errno values on
error are the same as from close(2).
dgadkitcreate
This function allocates and initializes a new dg_ad_kit_t structure.
Its argument should be the address of a pointer, which will be set to
point to the new structure on return.
Errors:
EINVAL adkitpp is not a valid pointer.
ENOMEM The system was unable to allocate sufficient memory for the
new structure.
dgadkitfree
This function frees all the memory associated with the dg_ad_kit_t *
whose address is the argument to the function. It frees both the
structure and any fields of the structure which are pointers which
are not NULL.
dgadkitsend
This function sends the kit pointed to by the pointer whose address
is the second argument of the function to the credential server,
which it assumes is listening at the other end of fd. fd should be
previously obtained by a call to dgadagenttoclientfd(). The kit
passed in is treated in a read-only manner by the function-- the data
in it is simply copied across the connection to the credential
server.
Errors:
EINVAL adkitpp or the pointer it points to is NULL.
EBADF fd is not a valid file descriptor as returned by a call to
dgadagenttoclientfd().
EMFILE The system is out of file descriptors
EIO The communication with the credential server failed.
dgadkitreceive
Receive a kit from the credential server via fd. fd should be the
file descriptor returned by a previous call to
dgadagenttoclientfd(). adkitpp should be the address of a
pointer which is set to NULL. The function will allocate a new kit,
read the data from the credential server, and store the incoming data
in the new kit. Finally it will set the pointer pointed to by
adkitpp to point to the new kit. When it is no longer needed, the
received kit can be disposed of with a call to dgadkitfree.
Errors:
EINVAL adkitpp is not a valid address.
EBADF fd is not a valid file descriptor as returned by a call to
dgadagenttoclientfd().
EMFILE The system is out of file descriptors.
EIO The communication with the credential server failed.
dgadkit{get,put} functions
The various fields of the dgadkitt structure should not be
accessed directly with the C language's '.' or '->' operators.
Instead, all access to the internals of the kit should be through the
various get/put functions which are provided. The precise list of
these (with function prototypes) is available in the header file
dgadinterface.h. These functions define what should be considered
the kit, rather than the structure definition itself. The structure
may change in the future, but compatibility will be preserved through
the function interfaces. The various "options" fields, such as
DG_AD_A_WEAK_AUTHENTICATION, should be boolean values: 1 indicates
that the option is turned on, 0 indicates that it is turned off.
SEE ALSO
credentiald(1M), open(2), close(2), cdlibrary(3), silibrary(3).
Licensed material--property of copyright holder(s)