nsec_library(3) DG/UX B2 Security R4.12MU02 nsec_library(3)
NAME
nseclibrary, dgrunningwithnsec, dgnsecgetpeercredentials,
dgnsecfreepeercredentials, dgnsecgetobjectattributes,
dgnsecfreeobjectattributes, dgnsecgetnullattrs,
dgnsecgetattrs, dgnsecsetattrs, dgnsecfreeattrs,
dgnsecgetattr, dgnsecsetattr, dgnsecgeterrmsg - NSEC
(network security) routines in libtrust
SYNOPSIS
#include <dgrunningwith.h>
#include <dgnsec.h>
int dgrunningwithnsec (void)
int dgnsecgetpeercredentials
(int fd,
struct sockaddr *name,
int namelen,
dgseccredt **seccredptrptr)
int dgnsecfreepeercredentials
(dgseccredt **seccredptrptr)
int dgnsecgetobjectattributes
(int fd,
struct sockaddr *name,
int namelen,
dgobjectattrstype **objattrsptrptr)
int dgnsecfreeobjectattributes
(dgobjectattrstype **objattrsptrptr)
int dgnsecgetnullattrs (void **attrshandleptr)
int dgnsecgetattrs (int fd,
int attrstype,
struct sockaddr *name,
int namelen,
void **attrshandleptr)
int dgnsecsetattrs (int fd,
struct sockaddr *name,
int namelen,
void *attrshandle)
int dgnsecfreeattrs(void **attrshandleptr)
int dgnsecgetattr (void *attrshandle,
unsigned int kindofattr,
void *attrptr,
unsigned int *attrlenptr)
int dgnsecsetattr (unsigned int kindofattr,
void *attrptr,
unsigned int attrlen,
void *attrshandle)
char *dgnsecgeterrmsg (void)
DESCRIPTION
The NSEC (Network SECurity) library functions provide a mechanism for
security-aware applications to get and set security attributes on
network sessions. A network session is a unique association of two
network endpoints: a local and a remote endpoint. The client
endpoint is by default the first endpoint to transmit a packet (i.e.
to issue the connect system call for TCP); the server endpoint of the
session is the other endpoint. However, if the endpoint which
receives the first packet had the DGCAPNETCLIENT capability
asserted at the time it was created, then it is the client endpoint.
Each network endpoint has at least two and possibly three sets of
security attributes.
Each endpoint always has a set of object security attributes. Each
network session is an object that is being accessed via the endpoint;
the network session can then be compared to a file that two processes
are sharing. The object attributes can be retrieved by a call to
dgnsecgetobjectattributes() or dgnsecgetattrs().
Each endpoint also always has an outgoing set of attributes that may
be sent to the remote endpoint for the session. By default, the
outgoing attributes for the client endpoint are the credentials of
the client process which created the local endpoint (at the time the
local endpoint was created); similarly, the outgoing attributes for a
server endpoint are the credentials of the server process except that
the MAC label is equal to the MAC label from the incoming attributes.
Therefore, packets traveling in either direction between two
endpoints will have the same MAC label. The outgoing attributes may
be changed with a call to dgnsecsetattrs() by a process with
appropriate privilege; see the ACCESS CONTROL section below for more
information. The current value of the outgoing attributes can be
retrieved with a call to dgnsecgetattrs(). Note that the set of
attributes that are actually transmitted across the network is
typically a subset of the credentials; the set of attributes actually
transmitted is dependent upon the type of the remote host. For
example, if the remote host is a generic (i.e. unlabeled) host, no
attributes are transmitted. (See dn6d.config.4m discussion of
network attributes for more information.)
Each endpoint may also have an incoming set of security attributes,
or peer credentials. These are the last attributes received from the
remote endpoint and are the credentials (i.e. process attributes) of
the peer process at the time the remote endpoint was created. So for
a server process, the incoming set of security attributes are the
client's credentials. If no packets have been received from the
remote endpoint, there are no incoming attributes. Note that for a
TCP connection, packets are transmitted in both directions in order
to establish the connection; therefore, an endpoint corresponding to
an established TCP connection will always have an incoming set of
security attributes. The incoming attributes (or peer's credentials)
can be retrieved with a call to dgnsecgetpeercredentials or
dgnsecgetattrs(). These attributes can not be modified. Note
that Trusted IP assigns default values for the fields of the
credentials which are not actually transmitted over the network; by
default, the following attributes are transmitted from one B2 system
to another: UID and GID (as found in the cred_t structure of the
DG_SEC_CRED_T_ATTR attribute), MAC label, and authentication ID.
(See dn6d.config.4m discussion of network attributes for more
information.)
dgrunningwithnsec
This function returns true if the local system is configured with
network security; otherwise, it returns false.
dgnsecgetpeercredentials
This function returns the peer's credentials; that is, the
credentials of the process at the remote end of the session. The
session has a local endpoint corresponding to fd and a remote
endpoint corresponding to name and namelen. Upon return,
seccredptrptr is set to point to the peer's credentials. It is
the responsibility of the caller to free the credentials by calling
dgseccredfree(). If no error occurs, the function returns 0;
otherwise, it sets errno to indicate the error.
Errors:
ENOMEM Unable to allocate space for the credentials.
dgnsecfreepeercredentials
This function frees the peer's credentials that are allocated by
dgnsecgetpeercredentials(). If no error occurs, the function
returns 0; otherwise, it sets errno to indicate the error.
dgnsecgetobjectattributes
This function returns the session's object attributes. A session can
be viewed as a file through which processes pass information. The
session has a local endpoint corresponding to fd and a remote
endpoint corresponding to name and namelen. Upon return,
objattrsptrptr is set to point to the session's object attributes.
It is the responsibility of the caller to free the credentials by
calling dgnsecfreeobjectattributes(). If no error occurs, the
function returns 0; otherwise, it sets errno to indicate the error.
Errors:
ENOMEM Unable to allocate space for the credentials.
dgnsecfreeobjectattributes
This function frees the object attributes that are allocated by
dgnsecgetobjectattributes(). If no error occurs, the function
returns 0; otherwise, it sets errno to indicate the error.
dgnsecgetnullattrs
This function sets attrshandleptr to point to a set of null
attributes (which may be freed with a call to dgnsecfreeattrs()),
This function is typically used when you need to build a set of
attributes from scratch.n If no error occurs, the function returns 0;
otherwise, it sets errno to indicate the error.
Errors:
ENOMEM Unable to allocate space for the set of null attributes.
dgnsecgetattrs
If attrstype equals 0, the function sets attrshandleptr to point
to the current outgoing attributes for the session. If namelen
equals 0, the attributes that are used to create all future locally
initiated sessions are retrieved; otherwise, the attributes that will
be sent to a particular remote endpoint specified by name are
retrieved. Note that if namelen does not equal 0, a packet must
have been previously sent to or received from the remote endpoint
specified by name.
If attrstype equals 1, this function sets attrshandleptr to point
to the current incoming attributes for the session. The session has
a local endpoint corresponding to fd and a remote endpoint
corresponding to name and namelen. Therefore, to retrieve the
current incoming attributes for the session, the name and namelen
must denote a valid remote network endpoint. If no error occurs, the
function returns 0; otherwise, it sets errno to indicate the error.
If attrstype equals 2, this function sets attrshandleptr to point
to the current object attributes for the session. The session has a
local endpoint corresponding to fd and a remote endpoint
corresponding to name and namelen. Therefore, to retrieve the
current object attributes for the session, the name and namelen must
denote a valid remote network endpoint. If no error occurs, the
function returns 0; otherwise, it sets errno to indicate the error.
The attributes pointed to by *attrshandleptr upon return may be
freed with a call to dgnsecfreeattrs().
Errors:
ENOMEM Unable to allocate space for the set of attributes.
EDGNOATTR No packets have been received for this session, where
attrstype equals 1 or 2.
dgnsecsetattrs
This function sets the outgoing attributes for a session. If
namelen equals 0, set the attributes that are to be used as the
outgoing attributes for all future locally initiated sessions;
otherwise, set the outgoing attributes for the session between the
local endpoint specified by fd and the remote endpoint specified by
name and namelen. If namelen does not equal 0 (i.e. a remote
endpoint is specified), a packet must have previously been received
from (or sent to) the remote endpoint. The caller must have the
appropriate privilege to perform this operation; see ACCESS CONTROL
below for more information.
If no error occurs, the function returns 0; otherwise, it sets errno
to indicate the error.
Errors:
EACCES The caller is not privileged to perform this operation.
ENOMEM Unable to allocate buffer space for the operation.
dgnsecfreeattrs
This function frees the memory used to hold a set of attributes. The
attributes handle pointed to by attrshandleptr is set to NULL upon
return. If no error occurs, the function returns 0; otherwise, it
sets errno to indicate the error.
dgnsecgetattr
This function extracts an individual attribute (specified by
kindofattr) from the set of attributes associated with
attrshandle. If the attribute is found and no error occurs, the
function returns a value greater than 0; if the attribute is not
found but no error occurs, the function returns 0; if an error
occurs, the function sets errno to indicate the error and returns a
value less than 0.
Upon entry to dgnsecgetattr(), *attrlenptr is set to the maximum
length of the buffer pointed to by attrptr. Upon return from
dgnsecgetattr where the return value is greater than 0, the buffer
contains the requested attribute and *attrlenptr is set to the
length of the attribute.
The valid values for kindofattr are listed below. Associated with
each value is the corresponding type of the attribute pointer which
is returned in *attrptr, and whether this attribute is mandatory,
optional, or never exists for incoming, outgoing, and object
attributes.
DGSECMACATTR
Type of attribute pointer returned is maclabelt as
defined in sys/mac.h. Mandatory in incoming and
outgoing attributes; optional in object attributes.
Note that an object must have a MAC label or a MAC
tuple, and may also have both.
DGSECCAPATTR
Type of attribute pointer returned is capt as defined
in sys/capability.h. Mandatory in incoming and
outgoing attributes; optional in object attributes.
DGSECMACTUPLEATTR
Type of attribute pointer returned is mactuplet as
defined in sys/mac.h. Mandatory in incoming and
outgoing attributes; optional in object attributes.
Note that an object must have either a MAC label or a
MAC tuple, and may also have both.
DGSECREQUIREDCAPATTR
Type of attribute pointer returned is caprequiredt as
defined in sys/capability.h. Optional in incoming,
outgoing, and object attributes.
DGSECACLATTR
Type of attribute pointer returned is aclt as defined
in sys/acl.h. Optional in incoming and outgoing
attributes; mandatory in object attributes.
DGSECCREDTATTR
Type of attribute pointer returned is credt as defined
in sys/cred.h. Note that this structure contains the
real and effective UID and GID. Mandatory in incoming
and outgoing attributes; optional in object attributes.
DGSECAUTHINFOATTR
Type of attribute pointer returned is pointer to
dgauthinfot as defined in dgauthinfo.h. Optional in
incoming and outgoing attributes; never exists in
object attributes.
DGSECINFOLABELATTR
Type of attribute pointer returned is maclabelt from
sys/mac.h. Optional in incoming and outgoing
attributes; this attribute will only exist if the
remote endpoint is on a system which needs to receive
this attribute, as is the case for a CMW (Compartmental
Mode Workstation). This attribute never exists in
object attributes.
DGSECAUDITMASKATTR
Type of attribute pointer returned is audmaskt as
defined in sys/audit.h. Mandatory in incoming and
outgoing attributes; never exists in object attributes.
DGSECAUTHIDATTR
Type of attribute pointer returned is authidt as
defined in sys/dgtparms.h. Mandatory in incoming and
outgoing attributes; never exists in object attributes.
DGSECPIDATTR
Type of attribute pointer returned is pidt as defined
in sys/types.h. Optional in incoming attributes;
mandatory in outgoing attributes; never exists in
object attributes.
Errors:
ENOBUFS The attribute was too large for the buffer of size
*attrlenptr.
EINVAL Invalid value for kindofattr specified.
dgnsecsetattr
This function sets an individual attribute (specified by
kindofattr) in the set of attributes associated with attrshandle
to the value pointed to by attrptr with length of attrlen. The
actual type of the structure pointed to by attrptr is dependent upon
the value of kindofattr. For a list of the valid values of
kindofattr and the associated type of structure pointer for
attrptr, see the description under dgnsecgetattr above.
If no error occurs, the function returns 0; otherwise, it sets errno
to indicate the error.
Errors:
EINVAL Invalid value for kindofattr specified.
dgnsecgeterrmsg
If any of the above functions fail, this function can then be used to
retrieve a null terminated error message string denoting the reason
for the failure. Note, however, that the message string is stored in
a single internal buffer and is overwritten by each successive
failure.
ACCESS CONTROL
To perform dgnsecsetattrs, a process must have appropriate
privilege.
For systems supporting the DG/UX Capability Option, appropriate
privilege is defined as having one or more specific capabilities
enabled in the effective capability set of the calling process. See
capdefaults(5) for the default capability for this system call. On
systems without the DG/UX Capability Option, appropriate privilege
means that the process has an effective UID of root. See the
appropriateprivilege(5) man page for more information.
EXAMPLE
/*
* This is a sample program that uses the nseclibrary(3).
* When invoked it accepts tcp connections and then writes some
* of the security attributes of the connection back as data on
* the connection.
*
* This can be compiled and then executed as follows:
*
* Compile:
* m88k: cc -o <program> <program>.c -ltrust
* ix86: cc -o <program> <program>.c -lnsl -lsocket -ltrust
*
* Usage:
* <program> <port-number>
*
* To see the attributes:
* telnet hostname <port-number>
*/
#include <malloc.h>
#include <nsec.h>
#include <dgsecsubject.h>
#include <netinet/in.h>
#include <stdio.h>
#include <sys/audit.h>
#include <sys/capability.h>
#include <sys/cred.h>
#include <sys/dgtparms.h>
#include <sys/mac.h>
#include <sys/socket.h>
#include <sys/types.h>
/*
* This reads the attributes from the connection and
* builds a readable string for the attributes in msg.
*/
void
getclientattributes
(
int newfd,
struct sockaddrin *remoteaddrp,
int remoteaddrlen,
char *msg
)
{
dgseccredt *seccredp;
char *macalias = NULL;
int rtn;
/*
* Get attributes from network connection
*/
rtn = dgnsecgetpeercredentials(
newfd,
remoteaddrp,
remoteaddrlen,
&seccredp );
if( rtn < 0 ) {
sprintf( msg,
"Couldn't get credentials: %s0,
dgnsecgeterrmsg() );
return;
}
/*
* Convert the MAC label to its alias.
*/
rtn = maclabeltoalias( seccredp->label,
MALIAS,
&macalias );
if( rtn < 0 ) {
sprintf(msg,"maclabeltoalias failed0);
goto done;
}
0,
sprintf( msg, 0ID: %d, GID:%d, AUTHID: %d
"MAC: %s
macalias,
seccredp->credptr->cruid,
seccredp->credptr->crgid,
seccredp->auid );
done:
/*
* Free any storage lying around.
*/
(void) dgnsecfreepeercredentials(&seccredp);
if( macalias != NULL ) {
free(macalias);
}
return;
}
main(int argc, char * argv[])
{
int portnumber;
int listenfd;
int newfd;
int result;
struct sockaddrin remoteaddress;
int addrlen;
char replyline[10000];
if(argc != 2) {
fprintf(stderr,"Usage %s <portnumber>0,argv[0]);
exit(1);
}
portnumber = atoi(argv[1]);
if( portnumber == 0 ) {
fprintf("Invalid port number %s0,argv[1]);
exit(1);
}
/*
* Create TCP endpoint and bind to appropriate port.
*/
listenfd = socket(AFINET,SOCKSTREAM,0);
if(listenfd < 0) {
perror("socket call failed");
exit(1);
}
memset((char*)&remoteaddress,0,sizeof(remoteaddress));
remoteaddress.sinport = htons(portnumber);
remoteaddress.sinfamily = AFINET;
result = bind(listenfd,&remoteaddress,sizeof(remoteaddress));
if(result < 0) {
perror("bind failed");
exit(1);
}
result = listen(listenfd,5);
if(result < 0) {
perror("listen failed");
exit(1);
}
printf("Listening on port %d0,portnumber);
/*
* Loop waiting for connections.
*/
for(;;) {
/*
* Accept new connection.
*/
addrlen = sizeof(remoteaddress);
newfd = accept(listenfd,&remoteaddress,&addrlen);
if(newfd < 0) {
perror("accept failed");
exit(1);
}
sprintf( replyline, 0,
"You are calling from addr=%8.8x, port=%d
remoteaddress.sinaddr,
remoteaddress.sinport);
result = write(newfd,replyline,strlen(replyline));
if(result < 0) {
fprintf(stderr,"write failed");
}
/*
* Get attributes into text message.
*/
if( dgrunningwithnsec() ) {
getnetattributes( newfd,
&remoteaddress,
addrlen,
replyline);
} else {
sprintf( replyline, 0);
"No network security attributes available
}
result = write(newfd,replyline,strlen(replyline));
if( result < 0 ) {
fprintf(stderr,"write failed");
}
close(newfd);
} /* end for */
} /* end main */
SEE ALSO
nsecmaplibrary(3).
Licensed material--property of copyright holder(s)