Networking Services Library Functions rpcsecgss(3NSL)
NAME
rpcsecgss - security flavor incorporating GS-API protec-
tions
SYNOPSIS
cc [ flag... ] file... -lnsl [ library... ]
#include
DESCRIPTION
RPCSECGS is a security flavor which sits "on top" of the
GS-API (Generic Security Service API) for network transmis-
sions. Applications using RPCSECGS can take advantage of
GS-API security features; moreover, they can use any secu-
rity mechanism (such as RSA public key or Kerberos) that
works with the GS-API.
The GS-API offers two security services beyond the tradi-
tional authentication services (AUTHDH, AUTHSYS, and
AUTHKERB): integrity and privacy. With integrity, the sys-
tem uses cryptographic checksumming to ensure the authenti-
city of a message (authenticity of originator, recipient,
and data); privacy provides additional security by encrypt-
ing data. Applications using RPCSECGS specify which ser-
vice they wish to use. Type of security service is
mechanism-independent.
Before exchanging data with a peer, an application must
establish a context for the exchange. RPCSECGS provides
a single function for this purpose, rpcgssseccreate(),
which allows the application to specify the security mechan-
ism, Quality of Protection (QOP), and type of service at
context creation. (The QOP parameter sets the cryptographic
algorithms to be used with integrity or privacy, and is
mechanism-dependent.) Once a context is established, appli-
cations can reset the QOP and type of service for each data
unit exchanged, if desired.
Valid mechanisms and QOPs may be obtained from configuration
files or from the name service. Each mechanism has a
default QOP.
Contexts are destroyed with the usual RPC authdestroy()
call.
Data Structures
Some of the data structures used by the RPCSECGS package
are shown below.
SunOS 5.11 Last change: 29 Jun 2001 1
Networking Services Library Functions rpcsecgss(3NSL)
rpcgssservicet
This enum defines the types of security services the context
may have. rpcgssseccreate() takes this as one argument
when setting the service type for a session.
typedef enum {
rpcgsssvcdefault = 0,
rpcgsssvcnone = 1,
rpcgsssvcintegrity = 2,
rpcgsssvcprivacy = 3
} rpcgssservicet ;
rpcgssoptionsreqt
Structure containing options passed directly through to the
GS-API. rpcgssseccreate() takes this as an argument when
creating a context.
typedef struct {
int reqflags; /*GS request bits */
int timereq; /*requested credential lifetime */
gsscredidt mycred; /*GS credential struct*/
gsschannelbindingst;
inputchannelbindings;
} rpcgssoptionsreqt ;
rpcgssOID
This data type is used by in-kernel RPC routines, and thus
is mentioned here for informational purposes only.
typedef struct {
uint length;
void *elements
} *rpcgssOID;
rpcgssoptionsrett
Structure containing GS-API options returned to the cal-
ling function, rpcgssseccreate(). MAXGSMECH is defined
as 128.
typedef struct {
int majorstatus;
int minorstatus;
uint rpcsecversion /*vers. of RPCSECGS */
int retflags
int timereq
gssctxidt gsscontext;
char actualmechanism[MAXGSMECH]; /*mechanism used*/
} rpcgssoptionsrett;
SunOS 5.11 Last change: 29 Jun 2001 2
Networking Services Library Functions rpcsecgss(3NSL)
rpcgssprincipalt
The (mechanism-dependent, opaque) client principal type.
Used as an argument to the rpcgssgetprincipalname()
function, and in the gsscred table. Also referenced by the
rpcgssrawcredt structure for raw credentials (see below).
typedef struct {
int len;
char name[1];
} *rpcgssprincipalt;
rpcgssrawcredt
Structure for raw credentials. Used by rpcgssgetcred()
and rpcgsssetcallback().
typedef struct {
uint version; /*RPC version # */
char *mechanism; /*security mechanism*/
char *qop; /*Quality of Protection*/
rpcgssprincipalt clientprincipal; /*client name*/
char *svcprincipal; /*server name*/
rpcgssservicet service; /*service (integrity, etc.)*/
} rpcgssrawcredt;
rpcgssucredt
Structure for UNIX credentials. Used by rpcgssgetcred()
as an alternative to rpcgssrawcredt.
typedef struct {
uidt uid; /*user ID*/
gidt gid; /*group ID*/
short gidlen;
gitt *gidlist; /*list of groups*/
} rpcgssucredt;
rpcgsscallbackt
Callback structure used by rpcgsssetcallback().
typedef struct {
uint program; /*RPC program #*/
uint version; /*RPC version #*/
boolt (*callback)(); /*user-defined callback routine*/
} rpcgsscallbackt;
rpcgsslockt
Structure used by a callback routine to enforce a particular
QOP and service for a session. The locked field is normally
set to FALSE; the server sets it to TRUE in order to lock
SunOS 5.11 Last change: 29 Jun 2001 3
Networking Services Library Functions rpcsecgss(3NSL)
the session. (A locked context will reject all requests
having different QOP and service values than those found in
the rawcred structure.) For more information, see the
rpcgsssetcallback(3NSL) man page.
typedef struct {
boolt locked;
rpcgssrawcredt *rawcred;
} rpcgsslockt;
rpcgsserrort
Structure used by rpcgssgeterror() to fetch an error code
when a RPCSECGS routine fails.
typedef struct {
int rpcgsserror;
int systemerror; /*same as errno*/
} rpcgsserrort;
Index to Routines
The following lists RPCSECGS routines and the manual
reference pages on which they are described. An (S) indi-
cates it is a server-side function:
Routine (Manual Page)
Description
rpcgssseccreate(3NSL)
Create a secure RPCSECGS context
rpcgsssetdefaults(3NSL)
Switch service, QOP for a session
rpcgssmaxdatalength(3NSL)
Get maximum data length allowed by transport
rpcgsssetsvcname(3NSL)
Set server's principal name (S)
SunOS 5.11 Last change: 29 Jun 2001 4
Networking Services Library Functions rpcsecgss(3NSL)
rpcgssgetcred(3NSL)
Get credentials of caller (S)
rpcgsssetcallback(3NSL)
Specify callback to see context use (S)
rpcgssgetprincipalname(3NSL)
Get client principal name (S)
rpcgsssvcmaxdatalength(3NSL)
Get maximum data length allowed by transport (S)
rpcgssgeterror(3NSL)
Get error number
rpcgssgetmechanisms(3NSL)
Get valid mechanism strings
rpcgssgetmechinfo(3NSL)
Get valid QOP strings, current service
rpcgssgetversions(3NSL)
Get supported RPCSECGS versions
rpcgssisinstalled(3NSL)
Checks if a mechanism is installed
rpcgssmechtooid(3NSL)
Maps ASCI mechanism to OID representation
rpcgssqoptonum(3NSL)
SunOS 5.11 Last change: 29 Jun 2001 5
Networking Services Library Functions rpcsecgss(3NSL)
Maps ASCI QOP, mechansim to uint number
Utilities
The gsscred utility manages the gsscred table, which con-
tains mappings of principal names between network and local
credentials. See gsscred(1M).
FILES
/etc/gss/mech List of installed mechanisms
/etc/gss/qop List of valid QOPs
ATRIBUTES
See attributes(5) for descriptions of the following attri-
butes:
ATRIBUTE TYPE ATRIBUTE VALUE
MT-Level MT-Safe
Availability SUNWrsg (32-bit)
SUNWrsgx (64-bit)
SEE ALSO
gsscred(1M), rpc(3NSL), rpcclntauth(3NSL), xdr(3NSL),
attributes(5), environ(5)
ONC] Developer's Guide
Linn, J. RFC 2743, Generic Security Service Application Pro-
gram Interface Version 2, Update 1. Network Working Group.
January 2000.
SunOS 5.11 Last change: 29 Jun 2001 6
|
