sec_cred_library(3) DG/UX B2 Security R4.12MU02 sec_cred_library(3)
NAME
dg_sec_cred_dup, dg_sec_cred_free, dg_sec_cred_get,
dg_sec_cred_create, dg_sec_cred_get_acl, dg_sec_cred_set_acl
dg_sec_cred_get_audit_mask, dg_sec_cred_set_audit_mask
dg_sec_cred_get_auid, dg_sec_cred_set_auid dg_sec_cred_get_authinfo,
dg_sec_cred_set_authinfo dg_sec_cred_get_cap, dg_sec_cred_set_cap
dg_sec_cred_get_gid, dg_sec_cred_set_gid dg_sec_cred_get_label,
dg_sec_cred_set_label dg_sec_cred_get_ngroups,
dg_sec_cred_set_ngroups dg_sec_cred_get_pid, dg_sec_cred_set_pid
dg_sec_cred_get_tuple, dg_sec_cred_set_tuple dg_sec_cred_get_range,
dg_sec_cred_set_range dg_sec_cred_get_rgid, dg_sec_cred_set_rgid
dg_sec_cred_get_ruid, dg_sec_cred_set_ruid dg_sec_cred_get_sup_grps,
dg_sec_cred_set_sup_grps dg_sec_cred_get_uid, dg_sec_cred_set_uid
dg_sec_cred_get_version, dg_sec_cred_set_version dg_sec_cred_xdr,
dg_sec_cred_set - security credential handling routines in libtrust.a
SYNOPSIS
#include <dg_sec_subject.h>
int dg_sec_cred_dup (src_p, dest_pp)
dg_sec_cred_t * src_p;
dg_sec_cred_t ** dest_pp;
void dg_sec_cred_free (sec_cred_pp)
dg_sec_cred_t ** sec_cred_pp;
int dg_sec_cred_get (pid, sec_cred_pp)
pid_t pid;
dg_sec_cred_t ** sec_cred_pp;
int dg_sec_cred_get_acl (sec_cred_p, acl_p)
dg_sec_cred_t * sec_cred_p;
acl_t * acl_p;
int dg_sec_cred_set_acl (sec_cred_p, acl)
dg_sec_cred_t * sec_cred_p;
acl_t acl;
int dg_sec_cred_get_audit_mask (sec_cred_p, audmask_pp)
dg_sec_cred_t * sec_cred_p;
aud_mask_t ** audmask_pp;
int dg_sec_cred_set_audit_mask (sec_cred_p, audmask_p)
dg_sec_cred_t * sec_cred_p;
aud_mask_t * audmask_p;
int dg_sec_cred_get_auid (sec_cred_p, auid_p)
dg_sec_cred_t * sec_cred_p;
auth_id_t * auid_p;
int dg_sec_cred_set_auid (sec_cred_p, auid)
dg_sec_cred_t * sec_cred_p;
auth_id_t auid;
int dg_sec_cred_get_authinfo (sec_cred_p, authinfo_pp, size_p)
dg_sec_cred_t * sec_cred_p;
void ** authinfo_pp;
int * size_p;
int dg_sec_cred_set_authinfo (sec_cred_p, authinfo_p, size)
dg_sec_cred_t * sec_cred_p;
void * authinfo_p;
int size;
int dg_sec_cred_get_cap (sec_cred_p, cap_p)
dg_sec_cred_t * sec_cred_p;
cap_t * cap_p;
int dg_sec_cred_set_cap (sec_cred_p, cap)
dg_sec_cred_t * sec_cred_p;
cap_t cap;
dg_sec_cred_t * dg_sec_cred_create ()
int dg_sec_cred_get_gid (sec_cred_p, gid_p)
dg_sec_cred_t * sec_cred_p;
gid_t * gid_p;
int dg_sec_cred_set_gid (sec_cred_p, gid)
dg_sec_cred_t * sec_cred_p;
gid_t gid;
int dg_sec_cred_get_label (sec_cred_p, label_p)
dg_sec_cred_t * sec_cred_p;
mac_label_t * label_p;
int dg_sec_cred_set_label (sec_cred_p, label)
dg_sec_cred_t * sec_cred_p;
mac_label_t label;
int dg_sec_cred_get_ngroups (sec_cred_p, ngroups_p)
dg_sec_cred_t * sec_cred_p;
ushort * ngroups_p;
int dg_sec_cred_set_ngroups (sec_cred_p, ngroups)
dg_sec_cred_t * sec_cred_p;
ushort ngroups;
int dg_sec_cred_get_pid (sec_cred_p, pid_p)
dg_sec_cred_t * sec_cred_p;
pid_t * pid_p;
int dg_sec_cred_set_pid (sec_cred_p, pid)
dg_sec_cred_t * sec_cred_p;
pid_t pid;
int dg_sec_cred_get_tuple (sec_cred_p, tuple_p)
dg_sec_cred_t * sec_cred_p;
mac_tuple_t * tuple_p;
int dg_sec_cred_set_tuple (sec_cred_p, tuple)
dg_sec_cred_t * sec_cred_p;
mac_tuple_t tuple;
int dg_sec_cred_get_range (sec_cred_p, range_p)
dg_sec_cred_t * sec_cred_p;
mac_range_t * range_p;
int dg_sec_cred_set_range (sec_cred_p, range)
dg_sec_cred_t * sec_cred_p;
mac_range_t range;
int dg_sec_cred_get_rgid (sec_cred_p, rgid_p)
dg_sec_cred_t * sec_cred_p;
gid_t * rgid_p;
int dg_sec_cred_set_rgid (sec_cred_p, rgid)
dg_sec_cred_t * sec_cred_p;
gid_t rgid;
int dg_sec_cred_get_ruid (sec_cred_p, ruid_p)
dg_sec_cred_t * sec_cred_p;
uid_t * ruid_p;
int dg_sec_cred_set_ruid (sec_cred_p, ruid)
dg_sec_cred_t * sec_cred_p;
uid_t ruid;
int dg_sec_cred_get_sup_grps (sec_cred_p, sup_grp_pp)
dg_sec_cred_t * sec_cred_p;
gid_t ** sup_grp_pp;
int dg_sec_cred_set_sup_grps (sec_cred_p, sup_grp_p)
dg_sec_cred_t * sec_cred_p;
gid_t * sup_grp_p;
int dg_sec_cred_get_uid (sec_cred_p, uid_p)
dg_sec_cred_t * sec_cred_p;
uid_t * uid_p;
int dg_sec_cred_set_uid (sec_cred_p, uid)
dg_sec_cred_t * sec_cred_p;
uid_t uid;
int dg_sec_cred_get_version (sec_cred_p, version_p);
dg_sec_cred_t * sec_cred_p;
unsigned char * version_p;
bool_t dg_sec_cred_xdr (xdrs, sec_cred_p)
XDR * xdrs;
dg_sec_cred_t * sec_cred_p;
int dg_sec_cred_set (sec_cred_p)
dg_sec_cred_t * sec_cred_p;
Parameters
src_p A pointer to a dg_sec_cred_t which will only be read,
not modified.
dest_pp A pointer to a pointer to a dg_sec_cred_t into which a
result will be written.
pid The process id of a process to get the security
credentials for.
sec_cred_p A pointer to a credential structure of type
dg_sec_cred_t.
sec_cred_pp A pointer to a pointer to a credential structure of
type dg_sec_cred_t.
DESCRIPTION
These routines, found in libtrust.a, allow manipulation of security
credentials. The basic type, dg_sec_cred_t, should be treated as
opaque, and its members should only be accessed via the routines
provided. Further, only objects of type dg_sec_cred_t * should be
declared-- there is no need to ever declare an instance of the
structure itself directly.
dg_sec_cred_dup
This function allocates a new dg_sec_cred_t 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 dg_sec_cred_free.
Errors:
ENOMEM Could not allocate memory for the new dg_sec_cred_t object.
EINVAL The pointers passed as arguments were invalid.
EINVAL The source pointer points to an unsupported version of
dg_sec_cred_t, as indicated by its version field.
dg_sec_cred_free
This function frees the memory associated with a dg_sec_cred_t. 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 sec_cred_pp is set to NULL. There is no return value
from this function.
dg_sec_cred_get
This function allocates a new dg_sec_cred_t 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, sec_cred_pp 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.
dg_sec_cred_get_acl
This function stores the acl_t value stored in sec_cred_p in the
location pointed to by acl_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 sec_cred_p points to a structure of an unsupported version.
dg_sec_cred_set_acl
This function stores acl in the acl_t value of sec_cred_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 sec_cred_p points to a structure of an unsupported version.
dg_sec_cred_get_audit_mask
This function stores the aud_mask_t * value stored in sec_cred_p in
the location pointed to by audmask_pp. 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 sec_cred_p points to a structure of an unsupported version.
dg_sec_cred_set_audit_mask
This function stores audmask_p in the aud_mask_t * value of
sec_cred_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 sec_cred_p points to a structure of an unsupported version.
dg_sec_cred_get_auid
This function stores the auth_id_t value stored in sec_cred_p 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 sec_cred_p points to a structure of an unsupported version.
dg_sec_cred_set_auid
This function stores auid in the auth_id_t value of sec_cred_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 sec_cred_p points to a structure of an unsupported version.
dg_sec_cred_get_authinfo
This function places a pointer to the authinfo data stored in
sec_cred_p into the location pointed to by its second argument. This
pointer can be treated as being of type authinfo_t *. The function
stores the size of this block of data in the location pointed to by
size_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 sec_cred_p points to a structure of an unsupported version.
dg_sec_cred_set_authinfo
This function stores authinfo and size in the authinfo value of
sec_cred_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 sec_cred_p points to a structure of an unsupported version.
dg_sec_cred_get_cap
This function stores the cap_t value stored in sec_cred_p in the
location pointed to by cap_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 sec_cred_p points to a structure of an unsupported version.
dg_sec_cred_set_cap
This function stores cap in the cap_t value of sec_cred_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 sec_cred_p points to a structure of an unsupported version.
dg_sec_cred_create
This function allocates a new dg_sec_cred_t. 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 dg_sec_cred_t
on success, and NULL on failure, with errno set to indicate the
error.
Errors:
EINOMEM The system was unable to allocate needed memory.
dg_sec_cred_get_gid
This function stores the gid_t value stored in sec_cred_p in the
location pointed to by gid_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 sec_cred_p points to a structure of an unsupported version.
dg_sec_cred_set_gid
This function stores gid in the gid_t value of sec_cred_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 sec_cred_p points to a structure of an unsupported version.
dg_sec_cred_get_label
This function stores the mac_label_t value stored in sec_cred_p in
the location pointed to by label_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 sec_cred_p points to a structure of an unsupported version.
dg_sec_cred_set_label
This function stores label in the mac_label_t value of sec_cred_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 sec_cred_p points to a structure of an unsupported version.
dg_sec_cred_get_ngroups
This function stores the number of supplementary groups value stored
in sec_cred_p in the location pointed to by ngroups_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 sec_cred_p points to a structure of an unsupported version.
dg_sec_cred_set_ngroups
This function stores ngroups in the number of supplementary groups
value of sec_cred_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 sec_cred_p points to a structure of an unsupported version.
dg_sec_cred_get_pid
This function stores the pid_t value stored in sec_cred_p in the
location pointed to by pid_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 sec_cred_p points to a structure of an unsupported version.
dg_sec_cred_set_pid
This function stores pid in the pid_t value of sec_cred_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 sec_cred_p points to a structure of an unsupported version.
dg_sec_cred_get_tuple
This function stores the mac_tuple_t value stored in sec_cred_p in
the location pointed to by tuple_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 sec_cred_p points to a structure of an unsupported version.
dg_sec_cred_set_tuple
This function stores tuple in the mac_tuple_t value of sec_cred_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 sec_cred_p points to a structure of an unsupported version.
dg_sec_cred_get_range
This function is obsolete. For compatibility, it will still operate,
although only on the USER region range. Please use
dg_sec_cred_get_tuple instead. This function will be removed in a
future release.
This function stores the USER region portion of the mac_tuple_t value
stored in sec_cred_p in the location pointed to by range_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 sec_cred_p points to a structure of an unsupported version.
dg_sec_cred_set_range
This function is obsolete. For compatibility, it will still operate,
although only on the USER region range. Please use
dg_sec_cred_set_tuple instead. This function will be removed in a
future release.
This function stores range in the USER region portion of the
mac_tuple_t value of sec_cred_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 sec_cred_p points to a structure of an unsupported version.
dg_sec_cred_get_rgid
This function stores the real group id value stored in sec_cred_p in
the location pointed to by rgid_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 sec_cred_p points to a structure of an unsupported version.
dg_sec_cred_set_rgid
This function stores rgid in the real group id value of sec_cred_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 sec_cred_p points to a structure of an unsupported version.
dg_sec_cred_get_ruid
This function stores the real user id value stored in sec_cred_p in
the location pointed to by ruid_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 sec_cred_p points to a structure of an unsupported version.
dg_sec_cred_set_ruid
This function stores ruid in the real user id value of sec_cred_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 sec_cred_p points to a structure of an unsupported version.
dg_sec_cred_get_sup_grps
This function stores the supplementary groups list value stored in
sec_cred_p in the location pointed to by sup_grp_pp. 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 sec_cred_p points to a structure of an unsupported version.
dg_sec_cred_set_sup_grps
This function stores sup_grp_p in the supplementary group list value
of sec_cred_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 sec_cred_p points to a structure of an unsupported version.
dg_sec_cred_get_uid
This function stores the effective user id value stored in sec_cred_p
in the location pointed to by uid_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 sec_cred_p points to a structure of an unsupported version.
dg_sec_cred_set_uid
This function stores uid in the effective user id value of
sec_cred_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 sec_cred_p points to a structure of an unsupported version.
dg_sec_cred_get_version
This function stores the version number value stored in sec_cred_p in
the location pointed to by version_p. 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 dg_sec_cred_create.
Errors:
EINVAL One of the pointers passed to the function was invalid.
dg_sec_cred_xdr
This function converts a dg_sec_cred_t 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 dg_sec_cred_t. For example, the following code
writes the dg_sec_cred_t pointed to by sec_cred_p into a file in a
machine-independent format:
dg_sec_cred_t * sec_cred_p;
XDR xdrs;
FILE * fd;
...
/* Get a file descriptor for writing */
fd = fopen ("data", "w");
xdrstdio_create (&xdrs, fd, XDR_ENCODE);
dg_sec_cred_xdr (&xdrs, sec_cred_p);
The above code assumes that sec_cred_p 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 dg_sec_cred_t 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):
dg_sec_cred_t * sec_cred_p;
XDR xdrs;
FILE * fd;
...
/* Get the file descriptor for reading */
fd = fopen ("data", "r");
/* Allocate storage. */
sec_cred_p = dg_sec_cred_create();
xdrstdio_create (&xdrs, fd, XDR_DECODE);
dg_sec_cred_xdr (&xdrs, sec_cred_p);
The function returns the constant TRUE on success and the constant
FALSE on failure.
dg_sec_cred_set
This function sets the credentials described in the dg_sec_cred_t
pointed to by sec_cred_p on the calling process. If any field in the
dg_sec_cred_t has not been initialized, that field is not set on the
process. So, for example, if a process gets a dg_sec_cred_t by
calling dg_sec_cred_get(), but the process does not have sufficient
privilege to access the target process' audit mask, then that the
audit mask in the dg_sec_cred_t will remain uninitialized. If the
process then passes this same dg_sec_cred_t to dg_sec_cred_set(), 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 sec_cred_p 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)