| Current File : //usr/share/man/man3nsl/rpcsec_gss.3nsl |
'\" te
.\" Copyright (c) 2002, 2011, Oracle and/or its affiliates. All rights reserved.
.TH rpcsec_gss 3NSL "22 Aug 2011" "SunOS 5.11" "Networking Services Library Functions"
.SH NAME
rpcsec_gss \- security flavor incorporating GSS-API protections
.SH SYNOPSIS
.LP
.nf
cc [ \fIflag\fR... ] \fIfile\fR... -lnsl [ \fIlibrary\fR... ]
#include <rpc/rpcsec_gss.h>
.fi
.SH DESCRIPTION
.sp
.LP
\fBRPCSEC_GSS\fR is a security flavor which sits "on top" of the \fBGSS-API\fR (Generic Security Service API) for network transmissions. Applications using \fBRPCSEC_GSS\fR can take advantage of \fBGSS-API\fR security features; moreover, they can use any security mechanism (such as RSA public key or Kerberos) that works with the \fBGSS-API.\fR
.sp
.LP
The \fBGSS-API\fR offers two security services beyond the traditional authentication services \fB(AUTH_DH,\fR \fBAUTH_SYS,\fR and \fBAUTH_KERB):\fR integrity and privacy. With integrity, the system uses cryptographic checksumming to ensure the authenticity of a message (authenticity of originator, recipient, and data); privacy provides additional security by encrypting data. Applications using \fBRPCSEC_GSS\fR specify which service they wish to use. Type of security service is mechanism-independent.
.sp
.LP
Before exchanging data with a peer, an application must establish a context for the exchange. \fBRPCSEC_GSS\fR provides a single function for this purpose, \fBrpc_gss_seccreate()\fR, which allows the application to specify the security mechanism, 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, applications can reset the QOP and type of service for each data unit exchanged, if desired.
.sp
.LP
Valid mechanisms and QOPs may be obtained from configuration files or from the name service. Each mechanism has a default QOP.
.sp
.LP
Contexts are destroyed with the usual RPC \fBauth_destroy()\fR call.
.SS "Data Structures"
.sp
.LP
Some of the data structures used by the \fBRPCSEC_GSS\fR package are shown below.
.SS "\fBrpc_gss_service_t\fR"
.sp
.LP
This enum defines the types of security services the context may have. \fBrpc_gss_seccreate()\fR takes this as one argument when setting the service type for a session.
.sp
.in +2
.nf
typedef enum {
rpc_gss_svc_default = 0,
rpc_gss_svc_none = 1,
rpc_gss_svc_integrity = 2,
rpc_gss_svc_privacy = 3
} rpc_gss_service_t ;
.fi
.in -2
.SS "\fBrpc_gss_options_req_t\fR"
.sp
.LP
Structure containing options passed directly through to the \fBGSS-API.\fR \fBrpc_gss_seccreate()\fR takes this as an argument when creating a context.
.sp
.in +2
.nf
typedef struct {
int req_flags; /*GSS request bits */
int time_req; /*requested credential lifetime */
gss_cred_id_t my_cred; /*GSS credential struct*/
gss_channel_bindings_t;
input_channel_bindings;
} rpc_gss_options_req_t ;
.fi
.in -2
.SS "\fBrpc_gss_OID\fR"
.sp
.LP
This data type is used by in-kernel RPC routines, and thus is mentioned here for informational purposes only.
.sp
.in +2
.nf
typedef struct {
u_int length;
void *elements
} *rpc_gss_OID;
.fi
.in -2
.SS "\fBrpc_gss_options_ret_t\fR"
.sp
.LP
Structure containing \fBGSS-API\fR options returned to the calling function, \fBrpc_gss_seccreate()\fR. \fBMAX_GSS_MECH\fR is defined as 128.
.sp
.in +2
.nf
typedef struct {
int major_status;
int minor_status;
u_int rpcsec_version /*vers. of RPCSEC_GSS */
int ret_flags
int time_req
gss_ctx_id_t gss_context;
char actual_mechanism[MAX_GSS_MECH]; /*mechanism used*/
} rpc_gss_options_ret_t;
.fi
.in -2
.SS "\fBrpc_gss_principal_t\fR"
.sp
.LP
The (mechanism-dependent, opaque) client principal type. Used as an argument to the \fBrpc_gss_get_principal_name()\fR function, and in the \fBgsscred\fR table. Also referenced by the \fBrpc_gss_rawcred_t\fR structure for raw credentials (see below).
.sp
.in +2
.nf
typedef struct {
int len;
char name[1];
} *rpc_gss_principal_t;
.fi
.in -2
.SS "\fBrpc_gss_rawcred_t\fR"
.sp
.LP
Structure for raw credentials. Used by \fBrpc_gss_getcred()\fR and \fBrpc_gss_set_callback()\fR.
.sp
.in +2
.nf
typedef struct {
u_int version; /*RPC version # */
char *mechanism; /*security mechanism*/
char *qop; /*Quality of Protection*/
rpc_gss_principal_t client_principal; /*client name*/
char *svc_principal; /*server name*/
rpc_gss_service_t service; /*service (integrity, etc.)*/
} rpc_gss_rawcred_t;
.fi
.in -2
.SS "\fBrpc_gss_ucred_t\fR"
.sp
.LP
Structure for UNIX credentials. Used by \fBrpc_gss_getcred()\fR as an alternative to \fBrpc_gss_rawcred_t\fR.
.sp
.in +2
.nf
typedef struct {
uid_t uid; /*user ID*/
gid_t gid; /*group ID*/
short gidlen;
git_t *gidlist; /*list of groups*/
} rpc_gss_ucred_t;
.fi
.in -2
.SS "\fBrpc_gss_callback_t\fR"
.sp
.LP
Callback structure used by \fBrpc_gss_set_callback()\fR.
.sp
.in +2
.nf
typedef struct {
u_int program; /*RPC program #*/
u_int version; /*RPC version #*/
bool_t (*callback)(); /*user-defined callback routine*/
} rpc_gss_callback_t;
.fi
.in -2
.SS "\fBrpc_gss_lock_t\fR"
.sp
.LP
Structure used by a callback routine to enforce a particular QOP and service for a session. The \fBlocked\fR field is normally set to \fBFALSE;\fR the server sets it to \fBTRUE\fR in order to lock the session. (A locked context will reject all requests having different QOP and service values than those found in the \fBraw_cred\fR structure.) For more information, see the \fBrpc_gss_set_callback\fR(3NSL) man page.
.sp
.in +2
.nf
typedef struct {
bool_t locked;
rpc_gss_rawcred_t *raw_cred;
} rpc_gss_lock_t;
.fi
.in -2
.SS "\fBrpc_gss_error_t\fR"
.sp
.LP
Structure used by \fBrpc_gss_get_error()\fR to fetch an error code when a \fBRPCSEC_GSS\fR routine fails.
.sp
.in +2
.nf
typedef struct {
int rpc_gss_error;
int system_error; /*same as errno*/
} rpc_gss_error_t;
.fi
.in -2
.SS "Index to Routines"
.sp
.LP
The following lists \fBRPCSEC_GSS\fR routines and the manual reference pages on which they are described. An (S) indicates it is a server-side function:
.sp
.ne 2
.mk
.na
\fB\fBRoutine\fR (Manual Page) \fR
.ad
.sp .6
.RS 4n
\fBDescription\fR
.RE
.sp
.ne 2
.mk
.na
\fB\fBrpc_gss_seccreate\fR(3NSL) \fR
.ad
.sp .6
.RS 4n
Create a secure \fBRPCSEC_GSS\fR context
.RE
.sp
.ne 2
.mk
.na
\fB\fBrpc_gss_set_defaults\fR(3NSL) \fR
.ad
.sp .6
.RS 4n
Switch service, QOP for a session
.RE
.sp
.ne 2
.mk
.na
\fB\fBrpc_gss_max_data_length\fR(3NSL) \fR
.ad
.sp .6
.RS 4n
Get maximum data length allowed by transport
.RE
.sp
.ne 2
.mk
.na
\fB\fBrpc_gss_set_svc_name\fR(3NSL) \fR
.ad
.sp .6
.RS 4n
Set server's principal name (S)
.RE
.sp
.ne 2
.mk
.na
\fB\fBrpc_gss_getcred\fR(3NSL) \fR
.ad
.sp .6
.RS 4n
Get credentials of caller (S)
.RE
.sp
.ne 2
.mk
.na
\fB\fBrpc_gss_set_callback\fR(3NSL) \fR
.ad
.sp .6
.RS 4n
Specify callback to see context use (S)
.RE
.sp
.ne 2
.mk
.na
\fB\fBrpc_gss_get_principal_name\fR(3NSL) \fR
.ad
.sp .6
.RS 4n
Get client principal name (S)
.RE
.sp
.ne 2
.mk
.na
\fB\fBrpc_gss_svc_max_data_length\fR(3NSL) \fR
.ad
.sp .6
.RS 4n
Get maximum data length allowed by transport (S)
.RE
.sp
.ne 2
.mk
.na
\fB\fBrpc_gss_get_error\fR(3NSL) \fR
.ad
.sp .6
.RS 4n
Get error number
.RE
.sp
.ne 2
.mk
.na
\fB\fBrpc_gss_get_mechanisms\fR(3NSL) \fR
.ad
.sp .6
.RS 4n
Get valid mechanism strings
.RE
.sp
.ne 2
.mk
.na
\fB\fBrpc_gss_get_mech_info\fR(3NSL) \fR
.ad
.sp .6
.RS 4n
Get valid QOP strings, current service
.RE
.sp
.ne 2
.mk
.na
\fB\fBrpc_gss_get_versions\fR(3NSL) \fR
.ad
.sp .6
.RS 4n
Get supported \fBRPCSEC_GSS\fR versions
.RE
.sp
.ne 2
.mk
.na
\fB\fBrpc_gss_is_installed\fR(3NSL) \fR
.ad
.sp .6
.RS 4n
Checks if a mechanism is installed
.RE
.sp
.ne 2
.mk
.na
\fB\fBrpc_gss_mech_to_oid\fR(3NSL) \fR
.ad
.sp .6
.RS 4n
Maps ASCII mechanism to OID representation
.RE
.sp
.ne 2
.mk
.na
\fB\fBrpc_gss_qop_to_num\fR(3NSL) \fR
.ad
.sp .6
.RS 4n
Maps ASCII QOP, mechansim to u_int number
.RE
.SS "Utilities"
.sp
.LP
The \fBgsscred\fR utility manages the \fBgsscred\fR table, which contains mappings of principal names between network and local credentials. See \fBgsscred\fR(1M).
.SH FILES
.sp
.ne 2
.mk
.na
\fB\fB/etc/gss/mech\fR \fR
.ad
.RS 18n
.rt
List of installed mechanisms
.RE
.sp
.ne 2
.mk
.na
\fB\fB/etc/gss/qop\fR \fR
.ad
.RS 18n
.rt
List of valid QOPs
.RE
.SH ATTRIBUTES
.sp
.LP
See \fBattributes\fR(5) for descriptions of the following attributes:
.sp
.sp
.TS
tab() box;
cw(2.75i) |cw(2.75i)
lw(2.75i) |lw(2.75i)
.
ATTRIBUTE TYPEATTRIBUTE VALUE
_
Availabilitysystem/library/security/rpcsec
_
MT-LevelMT-Safe
.TE
.SH SEE ALSO
.sp
.LP
\fBgsscred\fR(1M), \fBrpc\fR(3NSL), \fBrpc_clnt_auth\fR(3NSL), \fBxdr\fR(3NSL), \fBattributes\fR(5), \fBenviron\fR(5)
.sp
.LP
\fIONC+ RPC Developer\&'s Guide\fR
.sp
.LP
Linn, J. \fIRFC 2743, Generic Security Service Application Program Interface Version 2, Update 1\fR. Network Working Group. January 2000.