'\" te
.\" Copyright (c) 2002, 2011, Oracle and/or its affiliates. All rights reserved.
.TH rpc_gss_seccreate 3NSL "22 Aug 2011" "SunOS 5.11" "Networking Services Library Functions"
.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
.mk
.na
\fB\fIclnt\fR\fR
.ad
.RS 16n
.rt  
This is the RPC client handle. \fIclnt\fR may be obtained, for example, from \fBclnt_create()\fR.
.RE

.sp
.ne 2
.mk
.na
\fB\fIprincipal\fR\fR
.ad
.RS 16n
.rt  
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
.mk
.na
\fB\fImechanism\fR\fR
.ad
.RS 16n
.rt  
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
.mk
.na
\fB\fIservice_type\fR\fR
.ad
.RS 16n
.rt  
This sets the initial type of service for the session \(em privacy, integrity, authentication, or none.  
.RE

.sp
.ne 2
.mk
.na
\fB\fIqop\fR\fR
.ad
.RS 16n
.rt  
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
.mk
.na
\fB\fIoptions_req\fR\fR
.ad
.RS 16n
.rt  
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
.mk
.na
\fB\fIoptions_ret\fR\fR
.ad
.RS 16n
.rt  
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
.mk
.na
\fB\fB/etc/gss/mech\fR\fR
.ad
.RS 17n
.rt  
File containing valid security mechanisms
.RE

.sp
.ne 2
.mk
.na
\fB\fB/etc/gss/qop\fR\fR
.ad
.RS 17n
.rt  
File containing valid QOP values.
.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
\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+ 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.
.SH NOTES
.sp
.LP
Contexts may be destroyed normally, with  \fBauth_destroy()\fR.