'\" 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 RPC_GSS_SECCREATE 3NSL "Jun 29, 2001"
.SH NAME
rpc_gss_seccreate \- create a security context using the RPCSEC_GSS protocol
.SH SYNOPSIS
.LP
.nf
#include <rpc/rpcsec_gss.h>

\fBAUTH  *\fR\fBrpc_gss_seccreate\fR(\fBCLIENT\fR \fI*clnt\fR, \fBchar\fR \fI*principal\fR, \fBchar\fR \fI*mechanism\fR,
     \fBrpc_gss_service_t\fR \fIservice_type\fR, \fBchar\fR \fI*qop\fR,
     \fBrpc_gss_options_req_t\fR \fI*options_req\fR,
     \fBrpc_gss_options_ret_t\fR \fI*options_ret\fR);
.fi

.SH DESCRIPTION
.sp
.LP
\fBrpc_gss_seccreate()\fR is used by an appliction to create a security context
using the \fBRPCSEC_GSS\fR protocol, making use of the underlying \fBGSS-API\fR
network layer.   \fBrpc_gss_seccreate()\fR allows an application to specify the
type of security mechanism (for example, Kerberos v5), the type of service (for
example, integrity checking), and the Quality of Protection (\fBQOP\fR) desired
for transferring data.
.SH PARAMETERS
.sp
.LP
Information on  \fBRPCSEC_GSS\fR data types for parameters may be found on the
\fBrpcsec_gss\fR(3NSL) man page.
.sp
.ne 2
.na
\fB\fIclnt\fR\fR
.ad
.RS 16n
This is the RPC client handle. \fIclnt\fR may be obtained, for example, from
\fBclnt_create()\fR.
.RE

.sp
.ne 2
.na
\fB\fIprincipal\fR\fR
.ad
.RS 16n
This is the identity of the server principal, specified in the form
\fIservice\fR@\fIhost\fR, where \fIservice\fR is the name of the service the
client wishes to access and \fIhost\fR is the fully qualified name of the host
where the service resides \(em for example, nfs@mymachine.eng.company.com.
.RE

.sp
.ne 2
.na
\fB\fImechanism\fR\fR
.ad
.RS 16n
This is an ASCII string which indicates which security mechanism to use with
this data.  Appropriate mechanisms may be found in the file
\fB/etc/gss/mech\fR; additionally, \fBrpc_gss_get_mechanisms()\fR returns a
list of supported security mechanisms (as null-terminated strings).
.RE

.sp
.ne 2
.na
\fB\fIservice_type\fR\fR
.ad
.RS 16n
This sets the initial type of service for the session \(em privacy, integrity,
authentication, or none.
.RE

.sp
.ne 2
.na
\fB\fIqop\fR\fR
.ad
.RS 16n
This is an ASCII string which sets the quality of protection (QOP) for the
session. Appropriate values for this string may be found in the file
\fB/etc/gss/qop\fR. Additionally, supported QOPs are returned (as
null-terminated strings) by \fBrpc_gss_get_mech_info()\fR.
.RE

.sp
.ne 2
.na
\fB\fIoptions_req\fR\fR
.ad
.RS 16n
This structure contains options which are passed directly to the underlying
\fBGSS_API\fR layer.  If the caller specifies \fINULL\fR for this parameter,
defaults are used. (See  \fBNOTES\fR, below.)
.RE

.sp
.ne 2
.na
\fB\fIoptions_ret\fR\fR
.ad
.RS 16n
These \fBGSS-API\fR options are returned to the caller. If the caller does not
need to see these options, then it may specify \fINULL\fR for this parameter.
(See \fBNOTES,\fR below.)
.RE

.SH RETURN VALUES
.sp
.LP
\fBrpc_gss_seccreate()\fR returns a security context handle (an RPC
authentication handle) of type \fBAUTH\fR. If \fBrpc_gss_seccreate()\fR cannot
return successfully, the application can get an error number by calling
\fBrpc_gss_get_error()\fR.
.SH FILES
.sp
.ne 2
.na
\fB\fB/etc/gss/mech\fR\fR
.ad
.RS 17n
File containing valid security mechanisms
.RE

.sp
.ne 2
.na
\fB\fB/etc/gss/qop\fR\fR
.ad
.RS 17n
File containing valid QOP values.
.RE

.SH ATTRIBUTES
.sp
.LP
See \fBattributes\fR(5) 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
\fBauth_destroy\fR(3NSL), \fBrpc\fR(3NSL), \fBrpc_gss_get_error\fR(3NSL), \fBrpc_gss_get_mechanisms\fR(3NSL), \fBrpcsec_gss\fR(3NSL), \fBmech\fR(4), \fBqop\fR(4), \fBattributes\fR(5)
.sp
.LP
\fIONC+ 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.
.SH NOTES
.sp