'\" te
.\" Copyright (C) 2001, Sun Microsystems, Inc. All Rights Reserved
.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License").  You may not use this file except in compliance with the License.
.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.  See the License for the specific language governing permissions and limitations under the License.
.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE.  If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
.TH RPCSEC_GSS 3NSL "Jun 29, 2001"
.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
.na
\fB\fBRoutine\fR (Manual Page) \fR
.ad
.sp .6
.RS 4n
\fBDescription\fR
.RE

.sp
.ne 2
.na
\fB\fBrpc_gss_seccreate\fR(3NSL) \fR
.ad
.sp .6
.RS 4n
Create a secure \fBRPCSEC_GSS\fR context
.RE

.sp
.ne 2
.na
\fB\fBrpc_gss_set_defaults\fR(3NSL) \fR
.ad
.sp .6
.RS 4n
Switch service, QOP for a session
.RE

.sp
.ne 2
.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
.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
.na
\fB\fBrpc_gss_getcred\fR(3NSL) \fR
.ad
.sp .6
.RS 4n
Get credentials of caller (S)
.RE

.sp
.ne 2
.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
.na
\fB\fBrpc_gss_get_principal_name\fR(3NSL) \fR
.ad
.sp .6
.RS 4n
Get client principal name (S)
.RE

.sp
.ne 2
.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
.na
\fB\fBrpc_gss_get_error\fR(3NSL) \fR
.ad
.sp .6
.RS 4n
Get error number
.RE

.sp
.ne 2
.na
\fB\fBrpc_gss_get_mechanisms\fR(3NSL) \fR
.ad
.sp .6
.RS 4n
Get valid mechanism strings
.RE

.sp
.ne 2
.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
.na
\fB\fBrpc_gss_get_versions\fR(3NSL) \fR
.ad
.sp .6
.RS 4n
Get supported \fBRPCSEC_GSS\fR versions
.RE

.sp
.ne 2
.na
\fB\fBrpc_gss_is_installed\fR(3NSL) \fR
.ad
.sp .6
.RS 4n
Checks if a mechanism is installed
.RE

.sp
.ne 2
.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
.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(8).
.SH FILES
.sp
.ne 2
.na
\fB\fB/etc/gss/mech\fR \fR
.ad
.RS 18n
List of installed mechanisms
.RE

.sp
.ne 2
.na
\fB\fB/etc/gss/qop\fR \fR
.ad
.RS 18n
List of valid QOPs
.RE

.SH ATTRIBUTES
.sp
.LP
See \fBattributes\fR(7) for descriptions of the following attributes:
.sp

.sp
.TS
box;
c | c
l | l .
ATTRIBUTE TYPE	ATTRIBUTE VALUE
_
MT-Level	MT-Safe
.TE

.SH SEE ALSO
.sp
.LP
.BR rpc (3NSL),
.BR rpc_clnt_auth (3NSL),
.BR xdr (3NSL),
.BR attributes (7),
.BR environ (7),
.BR gsscred (8)
.sp
.LP
\fIONC+ Developer\&'s Guide\fR
.sp