cd_library(3)            DG/UX B2 Security R4.12MU02           cd_library(3)


NAME
       cdlibrary: dgcdclienttoagentfd, dgcdfdclose,
       dgcdkitcreate, dgcdkitfree, dgcdkitsend, dgcdkitreceive -
       credential server interface routines in libsm.a

SYNOPSIS
       #include <dgcdinterface.h>

       int     dgcdclienttoagentfd ( )

       int     dgcdfdclose (int                     fd)

       int     dgcdkitcreate (dgcdkitt **        cdkitpp)

       void    dgcdkitfree (dgcdkitt **          cdkitpp)

       int     dgcdkitsend (int                     fd,
                               dgcdkitt **          cdkitpp)

       int     dgcdkitreceive (int                  fd,
                                  dgcdkitt **       cdkitpp)

DESCRIPTION
       The functions in cdlibrary provide support for communicating with
       the credential server (daemon), credentiald, and therefore for
       session creation.

       The functions return 0 on success and -1 on failure, unless otherwise
       noted.

   dgcdclienttoagentfd
       This function establishes the connection to the credential server.
       On success, it returns a file descriptor (a non-negative integer)
       that should be used as an argument to the other functions in this
       family that require an fd argument.  On failure it returns 0 and sets
       errno to indicate the error.  Possible errno values are the same as
       those for open(2).  Use of this function requires appropriate
       privilege, as access to credentiald is restricted by the system.  On
       a process configured for capability (ie., dgrunningwithcap()
       returns 1), the process calling this function must have the
       capability DG_CAP_SI_ACCESS_CREDENTIALD in its permitted set in order
       to succeed.  On a system which is not configured for capability, the
       process must have a user id of 0.  If the process does not have
       appropriate privilege, this function will still appear to succeed,
       but credentiald will immediately drop the connection, and subsequent
       attempts to use the fd returned by this function will fail.

   dgcdfdclose
       This function closes the connection to the credential server.  It
       takes as an argument the file descriptor that was returned by
       dgcdclienttoagentfd().  Possible errno values on error are the
       same as those for close(2).

   dgcdkitcreate
       This function allocates and initializes a new dgcdkitt structure.
       Its argument should be the address of a pointer, which will be set to
       point to the new structure on return.

       Errors:

       EINVAL  cdkitpp is not a valid pointer.

       ENOMEM  The system was unable to allocate sufficient memory for the
               new structure.

   dgcdkitfree
       This function frees all the memory associated with the dgcdkitt *
       whose  address is the argument to the function.  It frees both the
       structure and any fields of the structure that are pointers that are
       not NULL.

   dgcdkitsend
       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 dgcdclienttoagentfd().  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  cdkitpp or the pointer it points to is NULL.

       EBADF   fd is not a valid file descriptor as returned by a call to
               dgcdclienttoagentfd().

       EMFILE  The system is out of file descriptors.

       EIO     The communication with the credential server failed.

   dgcdkitreceive
       Receive a kit from the credential server via fd. fd should be the
       file descriptor returned by a previous call to
       dgcdclienttoagentfd().  cdkitpp 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
       cdkitpp to point to the new kit.  When it is no longer needed, the
       received kit can be disposed of with a call to dgcdkitfree.

       Errors:

       EINVAL  cdkitpp is not a valid address.

       EBADF   fd is not a valid file descriptor as returned by a call to
               dgcdclienttoagentfd().

       EMFILE  The system is out of file descriptors.

       EIO     The communication with the credential server failed.

   dgcdkit{get,put} functions
       The various fields of the dgcdkitt 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 that are provided.  The precise list of
       these (with function prototypes) is available in the header file
       dgcdinterface.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
       B_BYPASS_LOCATION_LOCKED, 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), adlibrary(3), silibrary(3),
       dgrunningwith(3C).


Licensed material--property of copyright holder(s)