usr/src/man/man3nsl/rpc_gss_seccreate.3nsl

   1 '\" te
   2 .\" Copyright (C) 2001, Sun Microsystems, Inc. All Rights Reserved
   3 .\" 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.
   4 .\" 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.
   5 .\" 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]
   6 .TH RPC_GSS_SECCREATE 3NSL "Jun 29, 2001"
   7 .SH NAME
   8 rpc_gss_seccreate \- create a security context using the RPCSEC_GSS protocol
   9 .SH SYNOPSIS
  10 .LP
  11 .nf
  12 #include <rpc/rpcsec_gss.h>
  13
  14 \fBAUTH  *\fR\fBrpc_gss_seccreate\fR(\fBCLIENT\fR \fI*clnt\fR, \fBchar\fR \fI*principal\fR, \fBchar\fR \fI*mechanism\fR,
  15      \fBrpc_gss_service_t\fR \fIservice_type\fR, \fBchar\fR \fI*qop\fR,
  16      \fBrpc_gss_options_req_t\fR \fI*options_req\fR,
  17      \fBrpc_gss_options_ret_t\fR \fI*options_ret\fR);
  18 .fi
  19
  20 .SH DESCRIPTION
  21 .sp
  22 .LP
  23 \fBrpc_gss_seccreate()\fR is used by an appliction to create a security context
  24 using the \fBRPCSEC_GSS\fR protocol, making use of the underlying \fBGSS-API\fR
  25 network layer.   \fBrpc_gss_seccreate()\fR allows an application to specify the
  26 type of security mechanism (for example, Kerberos v5), the type of service (for
  27 example, integrity checking), and the Quality of Protection (\fBQOP\fR) desired
  28 for transferring data.
  29 .SH PARAMETERS
  30 .sp
  31 .LP
  32 Information on  \fBRPCSEC_GSS\fR data types for parameters may be found on the
  33 \fBrpcsec_gss\fR(3NSL) man page.
  34 .sp
  35 .ne 2
  36 .na
  37 \fB\fIclnt\fR\fR
  38 .ad
  39 .RS 16n
  40 This is the RPC client handle. \fIclnt\fR may be obtained, for example, from
  41 \fBclnt_create()\fR.
  42 .RE
  43
  44 .sp
  45 .ne 2
  46 .na
  47 \fB\fIprincipal\fR\fR
  48 .ad
  49 .RS 16n
  50 This is the identity of the server principal, specified in the form
  51 \fIservice\fR@\fIhost\fR, where \fIservice\fR is the name of the service the
  52 client wishes to access and \fIhost\fR is the fully qualified name of the host
  53 where the service resides \(em for example, nfs@mymachine.eng.company.com.
  54 .RE
  55
  56 .sp
  57 .ne 2
  58 .na
  59 \fB\fImechanism\fR\fR
  60 .ad
  61 .RS 16n
  62 This is an ASCII string which indicates which security mechanism to use with
  63 this data.  Appropriate mechanisms may be found in the file
  64 \fB/etc/gss/mech\fR; additionally, \fBrpc_gss_get_mechanisms()\fR returns a
  65 list of supported security mechanisms (as null-terminated strings).
  66 .RE
  67
  68 .sp
  69 .ne 2
  70 .na
  71 \fB\fIservice_type\fR\fR
  72 .ad
  73 .RS 16n
  74 This sets the initial type of service for the session \(em privacy, integrity,
  75 authentication, or none.
  76 .RE
  77
  78 .sp
  79 .ne 2
  80 .na
  81 \fB\fIqop\fR\fR
  82 .ad
  83 .RS 16n
  84 This is an ASCII string which sets the quality of protection (QOP) for the
  85 session. Appropriate values for this string may be found in the file
  86 \fB/etc/gss/qop\fR. Additionally, supported QOPs are returned (as
  87 null-terminated strings) by \fBrpc_gss_get_mech_info()\fR.
  88 .RE
  89
  90 .sp
  91 .ne 2
  92 .na
  93 \fB\fIoptions_req\fR\fR
  94 .ad
  95 .RS 16n
  96 This structure contains options which are passed directly to the underlying
  97 \fBGSS_API\fR layer.  If the caller specifies \fINULL\fR for this parameter,
  98 defaults are used. (See  \fBNOTES\fR, below.)
  99 .RE
 100
 101 .sp
 102 .ne 2
 103 .na
 104 \fB\fIoptions_ret\fR\fR
 105 .ad
 106 .RS 16n
 107 These \fBGSS-API\fR options are returned to the caller. If the caller does not
 108 need to see these options, then it may specify \fINULL\fR for this parameter.
 109 (See \fBNOTES,\fR below.)
 110 .RE
 111
 112 .SH RETURN VALUES
 113 .sp
 114 .LP
 115 \fBrpc_gss_seccreate()\fR returns a security context handle (an RPC
 116 authentication handle) of type \fBAUTH\fR. If \fBrpc_gss_seccreate()\fR cannot
 117 return successfully, the application can get an error number by calling
 118 \fBrpc_gss_get_error()\fR.
 119 .SH FILES
 120 .sp
 121 .ne 2
 122 .na
 123 \fB\fB/etc/gss/mech\fR\fR
 124 .ad
 125 .RS 17n
 126 File containing valid security mechanisms
 127 .RE
 128
 129 .sp
 130 .ne 2
 131 .na
 132 \fB\fB/etc/gss/qop\fR\fR
 133 .ad
 134 .RS 17n
 135 File containing valid QOP values.
 136 .RE
 137
 138 .SH ATTRIBUTES
 139 .sp
 140 .LP
 141 See \fBattributes\fR(5) for descriptions of the following attributes:
 142 .sp
 143
 144 .sp
 145 .TS
 146 box;
 147 c | c
 148 l | l .
 149 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 150 _
 151 MT-Level        MT-Safe
 152 .TE
 153
 154 .SH SEE ALSO
 155 .sp
 156 .LP
 157 \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)
 158 .sp
 159 .LP
 160 \fIONC+ Developer\&'s Guide\fR
 161 .sp
 162 .LP
 163 Linn, J. \fIRFC 2743, Generic Security Service Application Program Interface Version 2, Update 1\fR. Network Working Group. January 2000.
 164 .SH NOTES
 165 .sp