1rpcsec_gss(3NSL) Networking Services Library Functions rpcsec_gss(3NSL)
2
3
4
6 rpcsec_gss - security flavor incorporating GSS-API protections
7
9 cc [ flag... ] file... -lnsl [ library... ]
10 #include <rpc/rpcsec_gss.h>
11
12
14 RPCSEC_GSS is a security flavor which sits "on top" of the GSS-API
15 (Generic Security Service API) for network transmissions. Applications
16 using RPCSEC_GSS can take advantage of GSS-API security features; more‐
17 over, they can use any security mechanism (such as RSA public key or
18 Kerberos) that works with the GSS-API.
19
20
21 The GSS-API offers two security services beyond the traditional authen‐
22 tication services (AUTH_DH, AUTH_SYS, and AUTH_KERB): integrity and
23 privacy. With integrity, the system uses cryptographic checksumming to
24 ensure the authenticity of a message (authenticity of originator,
25 recipient, and data); privacy provides additional security by encrypt‐
26 ing data. Applications using RPCSEC_GSS specify which service they
27 wish to use. Type of security service is mechanism-independent.
28
29
30 Before exchanging data with a peer, an application must establish a
31 context for the exchange. RPCSEC_GSS provides a single function for
32 this purpose, rpc_gss_seccreate(), which allows the application to
33 specify the security mechanism, Quality of Protection (QOP), and type
34 of service at context creation. (The QOP parameter sets the crypto‐
35 graphic algorithms to be used with integrity or privacy, and is mecha‐
36 nism-dependent.) Once a context is established, applications can reset
37 the QOP and type of service for each data unit exchanged, if desired.
38
39
40 Valid mechanisms and QOPs may be obtained from configuration files or
41 from the name service. Each mechanism has a default QOP.
42
43
44 Contexts are destroyed with the usual RPC auth_destroy() call.
45
46 Data Structures
47 Some of the data structures used by the RPCSEC_GSS package are shown
48 below.
49
50 rpc_gss_service_t
51 This enum defines the types of security services the context may have.
52 rpc_gss_seccreate() takes this as one argument when setting the service
53 type for a session.
54
55 typedef enum {
56 rpc_gss_svc_default = 0,
57 rpc_gss_svc_none = 1,
58 rpc_gss_svc_integrity = 2,
59 rpc_gss_svc_privacy = 3
60 } rpc_gss_service_t ;
61
62
63 rpc_gss_options_req_t
64 Structure containing options passed directly through to the GSS-API.
65 rpc_gss_seccreate() takes this as an argument when creating a context.
66
67 typedef struct {
68 int req_flags; /*GSS request bits */
69 int time_req; /*requested credential lifetime */
70 gss_cred_id_t my_cred; /*GSS credential struct*/
71 gss_channel_bindings_t;
72 input_channel_bindings;
73 } rpc_gss_options_req_t ;
74
75
76 rpc_gss_OID
77 This data type is used by in-kernel RPC routines, and thus is mentioned
78 here for informational purposes only.
79
80 typedef struct {
81 u_int length;
82 void *elements
83 } *rpc_gss_OID;
84
85
86 rpc_gss_options_ret_t
87 Structure containing GSS-API options returned to the calling function,
88 rpc_gss_seccreate(). MAX_GSS_MECH is defined as 128.
89
90 typedef struct {
91 int major_status;
92 int minor_status;
93 u_int rpcsec_version /*vers. of RPCSEC_GSS */
94 int ret_flags
95 int time_req
96 gss_ctx_id_t gss_context;
97 char actual_mechanism[MAX_GSS_MECH]; /*mechanism used*/
98 } rpc_gss_options_ret_t;
99
100
101 rpc_gss_principal_t
102 The (mechanism-dependent, opaque) client principal type. Used as an
103 argument to the rpc_gss_get_principal_name() function, and in the gss‐
104 cred table. Also referenced by the rpc_gss_rawcred_t structure for raw
105 credentials (see below).
106
107 typedef struct {
108 int len;
109 char name[1];
110 } *rpc_gss_principal_t;
111
112
113 rpc_gss_rawcred_t
114 Structure for raw credentials. Used by rpc_gss_getcred() and
115 rpc_gss_set_callback().
116
117 typedef struct {
118 u_int version; /*RPC version # */
119 char *mechanism; /*security mechanism*/
120 char *qop; /*Quality of Protection*/
121 rpc_gss_principal_t client_principal; /*client name*/
122 char *svc_principal; /*server name*/
123 rpc_gss_service_t service; /*service (integrity, etc.)*/
124 } rpc_gss_rawcred_t;
125
126
127 rpc_gss_ucred_t
128 Structure for UNIX credentials. Used by rpc_gss_getcred() as an
129 alternative to rpc_gss_rawcred_t.
130
131 typedef struct {
132 uid_t uid; /*user ID*/
133 gid_t gid; /*group ID*/
134 short gidlen;
135 git_t *gidlist; /*list of groups*/
136 } rpc_gss_ucred_t;
137
138
139 rpc_gss_callback_t
140 Callback structure used by rpc_gss_set_callback().
141
142 typedef struct {
143 u_int program; /*RPC program #*/
144 u_int version; /*RPC version #*/
145 bool_t (*callback)(); /*user-defined callback routine*/
146 } rpc_gss_callback_t;
147
148
149 rpc_gss_lock_t
150 Structure used by a callback routine to enforce a particular QOP and
151 service for a session. The locked field is normally set to FALSE; the
152 server sets it to TRUE in order to lock the session. (A locked context
153 will reject all requests having different QOP and service values than
154 those found in the raw_cred structure.) For more information, see the
155 rpc_gss_set_callback(3NSL) man page.
156
157 typedef struct {
158 bool_t locked;
159 rpc_gss_rawcred_t *raw_cred;
160 } rpc_gss_lock_t;
161
162
163 rpc_gss_error_t
164 Structure used by rpc_gss_get_error() to fetch an error code when a
165 RPCSEC_GSS routine fails.
166
167 typedef struct {
168 int rpc_gss_error;
169 int system_error; /*same as errno*/
170 } rpc_gss_error_t;
171
172
173 Index to Routines
174 The following lists RPCSEC_GSS routines and the manual reference
175 pages on which they are described. An (S) indicates it is a server-
176 side function:
177
178 Routine (Manual Page)
179
180 Description
181
182
183 rpc_gss_seccreate(3NSL)
184
185 Create a secure RPCSEC_GSS context
186
187
188 rpc_gss_set_defaults(3NSL)
189
190 Switch service, QOP for a session
191
192
193 rpc_gss_max_data_length(3NSL)
194
195 Get maximum data length allowed by transport
196
197
198 rpc_gss_set_svc_name(3NSL)
199
200 Set server's principal name (S)
201
202
203 rpc_gss_getcred(3NSL)
204
205 Get credentials of caller (S)
206
207
208 rpc_gss_set_callback(3NSL)
209
210 Specify callback to see context use (S)
211
212
213 rpc_gss_get_principal_name(3NSL)
214
215 Get client principal name (S)
216
217
218 rpc_gss_svc_max_data_length(3NSL)
219
220 Get maximum data length allowed by transport (S)
221
222
223 rpc_gss_get_error(3NSL)
224
225 Get error number
226
227
228 rpc_gss_get_mechanisms(3NSL)
229
230 Get valid mechanism strings
231
232
233 rpc_gss_get_mech_info(3NSL)
234
235 Get valid QOP strings, current service
236
237
238 rpc_gss_get_versions(3NSL)
239
240 Get supported RPCSEC_GSS versions
241
242
243 rpc_gss_is_installed(3NSL)
244
245 Checks if a mechanism is installed
246
247
248 rpc_gss_mech_to_oid(3NSL)
249
250 Maps ASCII mechanism to OID representation
251
252
253 rpc_gss_qop_to_num(3NSL)
254
255 Maps ASCII QOP, mechansim to u_int number
256
257
258 Utilities
259 The gsscred utility manages the gsscred table, which contains mappings
260 of principal names between network and local credentials. See gss‐
261 cred(1M).
262
264 /etc/gss/mech List of installed mechanisms
265
266
267 /etc/gss/qop List of valid QOPs
268
269
271 See attributes(5) for descriptions of the following attributes:
272
273
274
275
276 ┌─────────────────────────────┬─────────────────────────────┐
277 │ ATTRIBUTE TYPE │ ATTRIBUTE VALUE │
278 ├─────────────────────────────┼─────────────────────────────┤
279 │MT-Level │MT-Safe │
280 ├─────────────────────────────┼─────────────────────────────┤
281 │Availability │SUNWrsg (32-bit) │
282 ├─────────────────────────────┼─────────────────────────────┤
283 │ │SUNWrsgx (64-bit) │
284 └─────────────────────────────┴─────────────────────────────┘
285
287 gsscred(1M), rpc(3NSL), rpc_clnt_auth(3NSL), xdr(3NSL), attributes(5),
288 environ(5)
289
290
291 ONC+ Developer's Guide
292
293
294 Linn, J. RFC 2743, Generic Security Service Application Program Inter‐
295 face Version 2, Update 1. Network Working Group. January 2000.
296
297
298
299SunOS 5.11 29 Jun 2001 rpcsec_gss(3NSL)