1 .\" Copyright (c) 2008 Isilon Inc http://www.isilon.com/
2 .\" Authors: Doug Rabson <dfr@rabson.org>
3 .\" Developed with Red Inc: Alfred Perlstein <alfred@FreeBSD.org>
5 .\" Redistribution and use in source and binary forms, with or without
6 .\" modification, are permitted provided that the following conditions
8 .\" 1. Redistributions of source code must retain the above copyright
9 .\" notice, this list of conditions and the following disclaimer.
10 .\" 2. Redistributions in binary form must reproduce the above copyright
11 .\" notice, this list of conditions and the following disclaimer in the
12 .\" documentation and/or other materials provided with the distribution.
14 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
15 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
16 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
17 .\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
18 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
19 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
20 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
21 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
22 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
23 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
26 .Dt RPC_GSS_SECCREATE 3
30 .Nd "GSS-API based authentication for RPC"
37 is a security mechanism for the RPC protocol.
38 It uses the Generic Security Service API (GSS-API) to establish a
39 security context between a client and a server and to ensure that all
40 subsequent communication between client and server are properly
42 Optionally, extra protection can be applied to the connection.
43 The integrity service uses checksums to ensure that all data sent by
44 a peer is received without modification.
45 The privacy service uses encryption to ensure that no third party can
46 access the data for a connection.
48 To use this system, an application must first use
50 to establish a security context.
52 Data structures used by
55 .Bl -tag -width "MMMM"
56 .It Vt rpc_gss_service_t
57 This type defines the types of security service required for
58 .Fn rpc_gss_seccreate .
61 rpc_gss_svc_default = 0,
63 rpc_gss_svc_integrity = 2,
64 rpc_gss_svc_privacy = 3
67 .It Vt rpc_gss_options_ret_t
68 This structure contains various optional values which are used while
69 creating a security context.
72 int req_flags; /* GSS request bits */
73 int time_req; /* requested lifetime */
74 gss_cred_id_t my_cred; /* GSS credential */
75 gss_channel_bindings_t input_channel_bindings;
76 } rpc_gss_options_req_t;
78 .It Vt rpc_gss_options_ret_t
79 Various details of the created security context are returned using
88 gss_ctx_id_t gss_context;
89 char actual_mechanism[MAX_GSS_MECH];
90 } rpc_gss_options_ret_t;
92 .It Vt rpc_gss_principal_t
93 This type is used to refer to an client principal which is represented
94 in GSS-API exported name form
98 Names in this format may be stored in access control lists or compared
99 with other names in exported name form.
100 This structure is returned by
101 .Fn rpc_gss_get_principal_name
102 and is also referenced by the
103 .Vt rpc_gss_rawcred_t
109 } *rpc_gss_principal_t;
111 .It Vt rpc_gss_rawcred_t
112 This structure is used to access the raw credentials associated with a
116 u_int version; /* RPC version number */
117 const char *mechanism; /* security mechanism */
118 const char *qop; /* quality of protection */
119 rpc_gss_principal_t client_principal; /* client name */
120 const char *svc_principal; /* server name */
121 rpc_gss_service_t service; /* service type */
124 .It Vt rpc_gss_ucred_t
125 Unix credentials which are derived form the raw credentials,
127 .Fn rpc_gss_getcred .
130 uid_t uid; /* user ID */
131 gid_t gid; /* group ID */
133 gid_t *gidlist; /* list of groups */
136 .It Vt rpc_gss_lock_t
137 Structure used to enforce a particular QOP and service.
141 rpc_gss_rawcred_t *raw_cred;
144 .It Vt rpc_gss_callback_t
145 Callback structure used by
146 .Fn rpc_gss_set_callback .
149 u_int program; /* RPC program number */
150 u_int version; /* RPC version number */
151 /* user defined callback */
152 bool_t (*callback)(struct svc_req *req,
154 gss_ctx_id_t gss_context,
155 rpc_gss_lock_t *lock,
157 } rpc_gss_callback_t;
159 .It Vt rpc_gss_error_t
160 Structure used to return error information by
161 .Fn rpc_gss_get_error .
165 int system_error; /* same as errno */
169 * Values for rpc_gss_error
171 #define RPC_GSS_ER_SUCCESS 0 /* no error */
172 #define RPC_GSS_ER_SYSTEMERROR 1 /* system error */
176 .Bl -tag -width "MMMM"
177 .It Xr rpc_gss_seccreate 3
178 Create a new security context
179 .It Xr rpc_gss_set_defaults 3
180 Set service and quality of protection for a context
181 .It Xr rpc_gss_max_data_length 3
182 Calculate maximum client message sizes.
183 .It Xr rpc_gss_get_error 3
184 Get details of the last error
185 .It Xr rpc_gss_mech_to_oid 3
186 Convert a mechanism name to the corresponding GSS-API oid.
187 .It Xr rpc_gss_oid_to_mech 3
188 Convert a GSS-API oid to a mechanism name
189 .It Xr rpc_gss_qop_to_num 3
190 Convert a quality of protection name to the corresponding number
191 .It Xr rpc_gss_get_mechanisms 3
192 Get a list of security mechanisms.
193 .It Xr rpc_gss_get_mech_info 3
194 Return extra information about a security mechanism
195 .It Xr rpc_gss_get_versions 3
196 Return the maximum and minimum supported versions of the
199 .It Xr rpc_gss_is_installed 3
200 Query for the presence of a particular security mechanism
201 .It Xr rpc_gss_set_svc_name 3
202 Set the name of a service principal which matches a given RPC program
204 .It Xr rpc_gss_getcred 3
205 Get credential details for the security context of an RPC request
206 .It Xr rpc_gss_set_callback 3
207 Install a callback routine which is called on the server when new
208 security contexts are created
209 .It Xr rpc_gss_get_principal_name 3
210 Create a client principal name from various strings
211 .It Xr rpc_gss_svc_max_data_length 3
212 Calculate maximum server message sizes.
215 .Xr gss_export_name 3 ,
224 library first appeared in
228 manual page was written by
229 .An Doug Rabson Aq Mt dfr@FreeBSD.org .