sec_cred_library(3) DG/UX B2 Security R4.12MU02 sec_cred_library(3)
NAME
dgseccreddup, dgseccredfree, dgseccredget,
dgseccredcreate, dgseccredgetacl, dgseccredsetacl
dgseccredgetauditmask, dgseccredsetauditmask
dgseccredgetauid, dgseccredsetauid dgseccredgetauthinfo,
dgseccredsetauthinfo dgseccredgetcap, dgseccredsetcap
dgseccredgetgid, dgseccredsetgid dgseccredgetlabel,
dgseccredsetlabel dgseccredgetngroups,
dgseccredsetngroups dgseccredgetpid, dgseccredsetpid
dgseccredgettuple, dgseccredsettuple dgseccredgetrange,
dgseccredsetrange dgseccredgetrgid, dgseccredsetrgid
dgseccredgetruid, dgseccredsetruid dgseccredgetsupgrps,
dgseccredsetsupgrps dgseccredgetuid, dgseccredsetuid
dgseccredgetversion, dgseccredsetversion dgseccredxdr,
dgseccredset - security credential handling routines in libtrust.a
SYNOPSIS
#include <dgsecsubject.h>
int dgseccreddup (srcp, destpp)
dgseccredt * srcp;
dgseccredt ** destpp;
void dgseccredfree (seccredpp)
dgseccredt ** seccredpp;
int dgseccredget (pid, seccredpp)
pidt pid;
dgseccredt ** seccredpp;
int dgseccredgetacl (seccredp, aclp)
dgseccredt * seccredp;
aclt * aclp;
int dgseccredsetacl (seccredp, acl)
dgseccredt * seccredp;
aclt acl;
int dgseccredgetauditmask (seccredp, audmaskpp)
dgseccredt * seccredp;
audmaskt ** audmaskpp;
int dgseccredsetauditmask (seccredp, audmaskp)
dgseccredt * seccredp;
audmaskt * audmaskp;
int dgseccredgetauid (seccredp, auidp)
dgseccredt * seccredp;
authidt * auidp;
int dgseccredsetauid (seccredp, auid)
dgseccredt * seccredp;
authidt auid;
int dgseccredgetauthinfo (seccredp, authinfopp, sizep)
dgseccredt * seccredp;
void ** authinfopp;
int * sizep;
int dgseccredsetauthinfo (seccredp, authinfop, size)
dgseccredt * seccredp;
void * authinfop;
int size;
int dgseccredgetcap (seccredp, capp)
dgseccredt * seccredp;
capt * capp;
int dgseccredsetcap (seccredp, cap)
dgseccredt * seccredp;
capt cap;
dgseccredt * dgseccredcreate ()
int dgseccredgetgid (seccredp, gidp)
dgseccredt * seccredp;
gidt * gidp;
int dgseccredsetgid (seccredp, gid)
dgseccredt * seccredp;
gidt gid;
int dgseccredgetlabel (seccredp, labelp)
dgseccredt * seccredp;
maclabelt * labelp;
int dgseccredsetlabel (seccredp, label)
dgseccredt * seccredp;
maclabelt label;
int dgseccredgetngroups (seccredp, ngroupsp)
dgseccredt * seccredp;
ushort * ngroupsp;
int dgseccredsetngroups (seccredp, ngroups)
dgseccredt * seccredp;
ushort ngroups;
int dgseccredgetpid (seccredp, pidp)
dgseccredt * seccredp;
pidt * pidp;
int dgseccredsetpid (seccredp, pid)
dgseccredt * seccredp;
pidt pid;
int dgseccredgettuple (seccredp, tuplep)
dgseccredt * seccredp;
mactuplet * tuplep;
int dgseccredsettuple (seccredp, tuple)
dgseccredt * seccredp;
mactuplet tuple;
int dgseccredgetrange (seccredp, rangep)
dgseccredt * seccredp;
macranget * rangep;
int dgseccredsetrange (seccredp, range)
dgseccredt * seccredp;
macranget range;
int dgseccredgetrgid (seccredp, rgidp)
dgseccredt * seccredp;
gidt * rgidp;
int dgseccredsetrgid (seccredp, rgid)
dgseccredt * seccredp;
gidt rgid;
int dgseccredgetruid (seccredp, ruidp)
dgseccredt * seccredp;
uidt * ruidp;
int dgseccredsetruid (seccredp, ruid)
dgseccredt * seccredp;
uidt ruid;
int dgseccredgetsupgrps (seccredp, supgrppp)
dgseccredt * seccredp;
gidt ** supgrppp;
int dgseccredsetsupgrps (seccredp, supgrpp)
dgseccredt * seccredp;
gidt * supgrpp;
int dgseccredgetuid (seccredp, uidp)
dgseccredt * seccredp;
uidt * uidp;
int dgseccredsetuid (seccredp, uid)
dgseccredt * seccredp;
uidt uid;
int dgseccredgetversion (seccredp, versionp);
dgseccredt * seccredp;
unsigned char * versionp;
boolt dgseccredxdr (xdrs, seccredp)
XDR * xdrs;
dgseccredt * seccredp;
int dgseccredset (seccredp)
dgseccredt * seccredp;
Parameters
srcp A pointer to a dgseccredt which will only be read,
not modified.
destpp A pointer to a pointer to a dgseccredt into which a
result will be written.
pid The process id of a process to get the security
credentials for.
seccredp A pointer to a credential structure of type
dgseccredt.
seccredpp A pointer to a pointer to a credential structure of
type dgseccredt.
DESCRIPTION
These routines, found in libtrust.a, allow manipulation of security
credentials. The basic type, dgseccredt, should be treated as
opaque, and its members should only be accessed via the routines
provided. Further, only objects of type dgseccredt * should be
declared-- there is no need to ever declare an instance of the
structure itself directly.
dgseccreddup
This function allocates a new dgseccredt and copies the one
pointed to by its first argument into it. It stores a pointer to the
new structure in the location pointed to by its second argument
before returning. It returns 0 on success and -1 on error with errno
set to indicate the error. When the new structure is no longer
needed, the storage associated with it should be released with a call
to dgseccredfree.
Errors:
ENOMEM Could not allocate memory for the new dgseccredt object.
EINVAL The pointers passed as arguments were invalid.
EINVAL The source pointer points to an unsupported version of
dgseccredt, as indicated by its version field.
dgseccredfree
This function frees the memory associated with a dgseccredt. Its
argument should be a pointer to a pointer to the structure which is
to be freed. Upon successfully freeing the memory, the pointer
pointed to by seccredpp is set to NULL. There is no return value
from this function.
dgseccredget
This function allocates a new dgseccredt of the most recent
version supported by the system, and fills it in with the credentials
of the process whose pid is pid. If pid is 0, it fills the structure
with the credentials of the calling process. If the function is
unable to fill in a particular entry, it simply leaves that entry in
its "empty" state, rather than returning an error. This allows this
routine to be used on systems with varying levels of security
features, and by processes with varying levels of privilege. On
return, seccredpp will point to a pointer to the new structure.
Returns 0 on success, -1 otherwise, with errno set to indicate the
error.
Errors:
ENOMEM The system was unable to allocate needed memory.
EINVAL One of the pointers passed to the function was not valid.
EINVAL pid does not exist, or is not accessible to the calling
process.
dgseccredgetacl
This function stores the aclt value stored in seccredp in the
location pointed to by aclp. It returns 0 on success, and -1 on
failure with errno set to indicate the error.
Errors:
EINVAL One of the pointers passed to the function was invalid.
EINVAL seccredp points to a structure of an unsupported version.
dgseccredsetacl
This function stores acl in the aclt value of seccredp. It
returns 0 on success, and -1 on failure with errno set to indicate
the error.
Errors:
EINVAL One of the pointers passed to the function was invalid.
EINVAL seccredp points to a structure of an unsupported version.
dgseccredgetauditmask
This function stores the audmaskt * value stored in seccredp in
the location pointed to by audmaskpp. It returns 0 on success, and
-1 on failure with errno set to indicate the error.
Errors:
EINVAL One of the pointers passed to the function was invalid.
EINVAL seccredp points to a structure of an unsupported version.
dgseccredsetauditmask
This function stores audmaskp in the audmaskt * value of
seccredp. It returns 0 on success, and -1 on failure with errno
set to indicate the error.
Errors:
EINVAL One of the pointers passed to the function was invalid.
EINVAL seccredp points to a structure of an unsupported version.
dgseccredgetauid
This function stores the authidt value stored in seccredp in the
location pointed to by auid_p. It returns 0 on success, and -1 on
failure with errno set to indicate the error.
Errors:
EINVAL One of the pointers passed to the function was invalid.
EINVAL seccredp points to a structure of an unsupported version.
dgseccredsetauid
This function stores auid in the authidt value of seccredp. It
returns 0 on success, and -1 on failure with errno set to indicate
the error.
Errors:
EINVAL One of the pointers passed to the function was invalid.
EINVAL seccredp points to a structure of an unsupported version.
dgseccredgetauthinfo
This function places a pointer to the authinfo data stored in
seccredp into the location pointed to by its second argument. This
pointer can be treated as being of type authinfot *. The function
stores the size of this block of data in the location pointed to by
sizep. It returns 0 on success, and -1 on failure with errno set to
indicate the error.
Errors:
EINVAL One of the pointers passed to the function was invalid.
EINVAL seccredp points to a structure of an unsupported version.
dgseccredsetauthinfo
This function stores authinfo and size in the authinfo value of
seccredp. It returns 0 on success, and -1 on failure with errno
set to indicate the error.
Errors:
EINVAL One of the pointers passed to the function was invalid.
EINVAL seccredp points to a structure of an unsupported version.
dgseccredgetcap
This function stores the capt value stored in seccredp in the
location pointed to by capp. It returns 0 on success, and -1 on
failure with errno set to indicate the error.
Errors:
EINVAL One of the pointers passed to the function was invalid.
EINVAL seccredp points to a structure of an unsupported version.
dgseccredsetcap
This function stores cap in the capt value of seccredp. It
returns 0 on success, and -1 on failure with errno set to indicate
the error.
Errors:
EINVAL One of the pointers passed to the function was invalid.
EINVAL seccredp points to a structure of an unsupported version.
dgseccredcreate
This function allocates a new dgseccredt. It always allocates the
newest version known to the system. It initializes all the fields to
their empty values except the version number, which is initialized to
the current version. It returns a pointer to the new dgseccredt
on success, and NULL on failure, with errno set to indicate the
error.
Errors:
EINOMEM The system was unable to allocate needed memory.
dgseccredgetgid
This function stores the gidt value stored in seccredp in the
location pointed to by gidp. It returns 0 on success, and -1 on
failure with errno set to indicate the error.
Errors:
EINVAL One of the pointers passed to the function was invalid.
EINVAL seccredp points to a structure of an unsupported version.
dgseccredsetgid
This function stores gid in the gidt value of seccredp. It
returns 0 on success, and -1 on failure with errno set to indicate
the error.
Errors:
EINVAL One of the pointers passed to the function was invalid.
EINVAL seccredp points to a structure of an unsupported version.
dgseccredgetlabel
This function stores the maclabelt value stored in seccredp in
the location pointed to by labelp. It returns 0 on success, and -1
on failure with errno set to indicate the error.
Errors:
EINVAL One of the pointers passed to the function was invalid.
EINVAL seccredp points to a structure of an unsupported version.
dgseccredsetlabel
This function stores label in the maclabelt value of seccredp.
It returns 0 on success, and -1 on failure with errno set to indicate
the error.
Errors:
EINVAL One of the pointers passed to the function was invalid.
EINVAL seccredp points to a structure of an unsupported version.
dgseccredgetngroups
This function stores the number of supplementary groups value stored
in seccredp in the location pointed to by ngroupsp. It returns 0
on success, and -1 on failure with errno set to indicate the error.
Errors:
EINVAL One of the pointers passed to the function was invalid.
EINVAL seccredp points to a structure of an unsupported version.
dgseccredsetngroups
This function stores ngroups in the number of supplementary groups
value of seccredp. It returns 0 on success, and -1 on failure with
errno set to indicate the error.
Errors:
EINVAL One of the pointers passed to the function was invalid.
EINVAL seccredp points to a structure of an unsupported version.
dgseccredgetpid
This function stores the pidt value stored in seccredp in the
location pointed to by pidp. It returns 0 on success, and -1 on
failure with errno set to indicate the error.
Errors:
EINVAL One of the pointers passed to the function was invalid.
EINVAL seccredp points to a structure of an unsupported version.
dgseccredsetpid
This function stores pid in the pidt value of seccredp. It
returns 0 on success, and -1 on failure with errno set to indicate
the error.
Errors:
EINVAL One of the pointers passed to the function was invalid.
EINVAL seccredp points to a structure of an unsupported version.
dgseccredgettuple
This function stores the mactuplet value stored in seccredp in
the location pointed to by tuplep. It returns 0 on success, and -1
on failure with errno set to indicate the error.
Errors:
EINVAL One of the pointers passed to the function was invalid.
EINVAL seccredp points to a structure of an unsupported version.
dgseccredsettuple
This function stores tuple in the mactuplet value of seccredp.
It returns 0 on success, and -1 on failure with errno set to indicate
the error.
Errors:
EINVAL One of the pointers passed to the function was invalid.
EINVAL seccredp points to a structure of an unsupported version.
dgseccredgetrange
This function is obsolete. For compatibility, it will still operate,
although only on the USER region range. Please use
dgseccredgettuple instead. This function will be removed in a
future release.
This function stores the USER region portion of the mactuplet value
stored in seccredp in the location pointed to by rangep. It
returns 0 on success, and -1 on failure with errno set to indicate
the error.
Errors:
EINVAL One of the pointers passed to the function was invalid.
EINVAL seccredp points to a structure of an unsupported version.
dgseccredsetrange
This function is obsolete. For compatibility, it will still operate,
although only on the USER region range. Please use
dgseccredsettuple instead. This function will be removed in a
future release.
This function stores range in the USER region portion of the
mactuplet value of seccredp. It returns 0 on success, and -1 on
failure with errno set to indicate the error.
Errors:
EINVAL One of the pointers passed to the function was invalid.
EINVAL seccredp points to a structure of an unsupported version.
dgseccredgetrgid
This function stores the real group id value stored in seccredp in
the location pointed to by rgidp. It returns 0 on success, and -1
on failure with errno set to indicate the error.
Errors:
EINVAL One of the pointers passed to the function was invalid.
EINVAL seccredp points to a structure of an unsupported version.
dgseccredsetrgid
This function stores rgid in the real group id value of seccredp.
It returns 0 on success, and -1 on failure with errno set to indicate
the error.
Errors:
EINVAL One of the pointers passed to the function was invalid.
EINVAL seccredp points to a structure of an unsupported version.
dgseccredgetruid
This function stores the real user id value stored in seccredp in
the location pointed to by ruidp. It returns 0 on success, and -1
on failure with errno set to indicate the error.
Errors:
EINVAL One of the pointers passed to the function was invalid.
EINVAL seccredp points to a structure of an unsupported version.
dgseccredsetruid
This function stores ruid in the real user id value of seccredp.
It returns 0 on success, and -1 on failure with errno set to indicate
the error.
Errors:
EINVAL One of the pointers passed to the function was invalid.
EINVAL seccredp points to a structure of an unsupported version.
dgseccredgetsupgrps
This function stores the supplementary groups list value stored in
seccredp in the location pointed to by supgrppp. It returns 0 on
success, and -1 on failure with errno set to indicate the error.
Errors:
EINVAL One of the pointers passed to the function was invalid.
EINVAL seccredp points to a structure of an unsupported version.
dgseccredsetsupgrps
This function stores supgrpp in the supplementary group list value
of seccredp. It returns 0 on success, and -1 on failure with errno
set to indicate the error.
Errors:
EINVAL One of the pointers passed to the function was invalid.
EINVAL seccredp points to a structure of an unsupported version.
dgseccredgetuid
This function stores the effective user id value stored in seccredp
in the location pointed to by uidp. It returns 0 on success, and -1
on failure with errno set to indicate the error.
Errors:
EINVAL One of the pointers passed to the function was invalid.
EINVAL seccredp points to a structure of an unsupported version.
dgseccredsetuid
This function stores uid in the effective user id value of
seccredp. It returns 0 on success, and -1 on failure with errno
set to indicate the error.
Errors:
EINVAL One of the pointers passed to the function was invalid.
EINVAL seccredp points to a structure of an unsupported version.
dgseccredgetversion
This function stores the version number value stored in seccredp in
the location pointed to by versionp. It returns 0 on success, and
-1 on failure with errno set to indicate the error. There is no
corresponding set function, as the version number should only be set
by dgseccredcreate.
Errors:
EINVAL One of the pointers passed to the function was invalid.
dgseccredxdr
This function converts a dgseccredt into its eXternal Data
Representation. In this representation, it can be read by machines
of different architectures with, e.g. different byte orders. This
routine is used in conjunction with one of the other xdr(3N) routines
to read or write a dgseccredt. For example, the following code
writes the dgseccredt pointed to by seccredp into a file in a
machine-independent format:
dgseccredt * seccredp;
XDR xdrs;
FILE * fd;
...
/* Get a file descriptor for writing */
fd = fopen ("data", "w");
xdrstdiocreate (&xdrs, fd, XDRENCODE);
dgseccredxdr (&xdrs, seccredp);
The above code assumes that seccredp was previously initialized and
points to something reasonable, and it also ignores potential error
returns. It is merely intended to demonstrate the context in which
the function should be used.
In order to read the data, the dgseccredt in which the incoming
data is to be stored must be allocated in advance. Thus, code to
read back what was written by the code above might look like this
(again ignoring error returns):
dgseccredt * seccredp;
XDR xdrs;
FILE * fd;
...
/* Get the file descriptor for reading */
fd = fopen ("data", "r");
/* Allocate storage. */
seccredp = dgseccredcreate();
xdrstdiocreate (&xdrs, fd, XDRDECODE);
dgseccredxdr (&xdrs, seccredp);
The function returns the constant TRUE on success and the constant
FALSE on failure.
dgseccredset
This function sets the credentials described in the dgseccredt
pointed to by seccredp on the calling process. If any field in the
dgseccredt has not been initialized, that field is not set on the
process. So, for example, if a process gets a dgseccredt by
calling dgseccredget(), but the process does not have sufficient
privilege to access the target process' audit mask, then that the
audit mask in the dgseccredt will remain uninitialized. If the
process then passes this same dgseccredt to dgseccredset(), the
function will not attempt to set any audit mask on the process,
leaving the old one in place. It returns 0 on success, -1 on failure
with errno set to indicate the error.
Errors:
EINVAL One of the pointers passed to the function was invalid.
EINVAL One of the entries in seccredp was not valid for this
system.
EPERM The calling process has insufficient privilege to set the
requested credentials.
ENOMEM The system could not allocate memory needed to complete the
request.
EFAULT The process tried to reference a piece of memory to which it
does not have read access.
SEE ALSO
xdr(3N), rpc(3N).
Licensed material--property of copyright holder(s)