| blob | fb407dd427832c43b34b1d7dbdfbbc727343d564 |
1 .\" Copyright (c) 2003 Kungliga Tekniska Högskolan
2 .\" (Royal Institute of Technology, Stockholm, Sweden).
3 .\" All rights reserved.
4 .\"
5 .\" Redistribution and use in source and binary forms, with or without
6 .\" modification, are permitted provided that the following conditions
7 .\" are met:
8 .\"
9 .\" 1. Redistributions of source code must retain the above copyright
10 .\" notice, this list of conditions and the following disclaimer.
11 .\"
12 .\" 2. Redistributions in binary form must reproduce the above copyright
13 .\" notice, this list of conditions and the following disclaimer in the
14 .\" documentation and/or other materials provided with the distribution.
15 .\"
16 .\" 3. Neither the name of the Institute nor the names of its contributors
17 .\" may be used to endorse or promote products derived from this software
18 .\" without specific prior written permission.
19 .\"
20 .\" THIS SOFTWARE IS PROVIDED BY THE INSTITUTE AND CONTRIBUTORS ``AS IS'' AND
21 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
22 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
23 .\" ARE DISCLAIMED. IN NO EVENT SHALL THE INSTITUTE OR CONTRIBUTORS BE LIABLE
24 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
25 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
26 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
27 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
28 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
29 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
30 .\" SUCH DAMAGE.
31 .\"
32 .\" $Id$
33 .\"
34 .Dd April 2, 2003
35 .Dt GSS_ACQUIRE_CRED 3
36 .Os HEIMDAL
37 .Sh NAME
38 .Nm gss_accept_sec_context ,
39 .Nm gss_acquire_cred ,
40 .Nm gss_add_cred ,
41 .Nm gss_add_oid_set_member ,
42 .Nm gss_canonicalize_name ,
43 .Nm gss_compare_name ,
44 .Nm gss_context_time ,
45 .Nm gss_create_empty_oid_set ,
46 .Nm gss_delete_sec_context ,
47 .Nm gss_display_name ,
48 .Nm gss_display_status ,
49 .Nm gss_duplicate_name ,
50 .Nm gss_export_name ,
51 .Nm gss_export_sec_context ,
52 .Nm gss_get_mic ,
53 .Nm gss_import_name ,
54 .Nm gss_import_sec_context ,
55 .Nm gss_indicate_mechs ,
56 .Nm gss_init_sec_context ,
57 .Nm gss_inquire_context ,
58 .Nm gss_inquire_cred ,
59 .Nm gss_inquire_cred_by_mech ,
60 .Nm gss_inquire_mechs_for_name ,
61 .Nm gss_inquire_names_for_mech ,
62 .Nm gss_krb5_copy_ccache ,
63 .Nm gss_process_context_token ,
64 .Nm gss_release_buffer ,
65 .Nm gss_release_cred ,
66 .Nm gss_release_name ,
67 .Nm gss_release_oid_set ,
68 .Nm gss_seal ,
69 .Nm gss_sign ,
70 .Nm gss_test_oid_set_member ,
71 .Nm gss_unseal ,
72 .Nm gss_unwrap ,
73 .Nm gss_verify ,
74 .Nm gss_verify_mic ,
75 .Nm gss_wrap ,
76 .Nm gss_wrap_size_limit
77 .Nd Generic Security Service Application Program Interface library
78 .Sh LIBRARY
79 GSS-API library (libgssapi, -lgssapi)
80 .Sh SYNOPSIS
81 .In gssapi.h
82 .Pp
83 .Ft OM_uint32
84 .Fo gss_accept_sec_context
85 .Fa "OM_uint32 * minor_status"
86 .Fa "gss_ctx_id_t * context_handle"
87 .Fa "const gss_cred_id_t acceptor_cred_handle"
88 .Fa "const gss_buffer_t input_token_buffer"
89 .Fa "const gss_channel_bindings_t input_chan_bindings"
90 .Fa "gss_name_t * src_name"
91 .Fa "gss_OID * mech_type"
92 .Fa "gss_buffer_t output_token"
93 .Fa "OM_uint32 * ret_flags"
94 .Fa "OM_uint32 * time_rec"
95 .Fa "gss_cred_id_t * delegated_cred_handle"
96 .Fc
97 .Pp
98 .Ft OM_uint32
99 .Fo gss_acquire_cred
100 .Fa "OM_uint32 * minor_status"
101 .Fa "const gss_name_t desired_name"
102 .Fa "OM_uint32 time_req"
103 .Fa "const gss_OID_set desired_mechs"
104 .Fa "gss_cred_usage_t cred_usage"
105 .Fa "gss_cred_id_t * output_cred_handle"
106 .Fa "gss_OID_set * actual_mechs"
107 .Fa "OM_uint32 * time_rec"
108 .Fc
109 .\" .Fn gss_add_cred
110 .Ft OM_uint32
111 .Fo gss_add_oid_set_member
112 .Fa "OM_uint32 * minor_status"
113 .Fa "const gss_OID member_oid"
114 .Fa "gss_OID_set * oid_set"
115 .Fc
116 .Ft OM_uint32
117 .Fo gss_canonicalize_name
118 .Fa "OM_uint32 * minor_status"
119 .Fa "const gss_name_t input_name"
120 .Fa "const gss_OID mech_type"
121 .Fa "gss_name_t * output_name"
122 .Fc
123 .Ft OM_uint32
124 .Fo gss_compare_name
125 .Fa "OM_uint32 * minor_status"
126 .Fa "const gss_name_t name1"
127 .Fa "const gss_name_t name2"
128 .Fa "int * name_equal"
129 .Fc
130 .Ft OM_uint32
131 .Fo gss_context_time
132 .Fa "OM_uint32 * minor_status"
133 .Fa "const gss_ctx_id_t context_handle"
134 .Fa "OM_uint32 * time_rec"
135 .Fc
136 .Ft OM_uint32
137 .Fo gss_create_empty_oid_set
138 .Fa "OM_uint32 * minor_status"
139 .Fa "gss_OID_set * oid_set"
140 .Fc
141 .Ft OM_uint32
142 .Fo gss_delete_sec_context
143 .Fa "OM_uint32 * minor_status"
144 .Fa "gss_ctx_id_t * context_handle"
145 .Fa "gss_buffer_t output_token"
146 .Fc
147 .Ft OM_uint32
148 .Fo gss_display_name
149 .Fa "OM_uint32 * minor_status"
150 .Fa "const gss_name_t input_name"
151 .Fa "gss_buffer_t output_name_buffer"
152 .Fa "gss_OID * output_name_type"
153 .Fc
154 .Ft OM_uint32
155 .Fo gss_display_status
156 .Fa "OM_uint32 *minor_status"
157 .Fa "OM_uint32 status_value"
158 .Fa "int status_type"
159 .Fa "const gss_OID mech_type"
160 .Fa "OM_uint32 *message_context"
161 .Fa "gss_buffer_t status_string"
162 .Fc
163 .Ft OM_uint32
164 .Fo gss_duplicate_name
165 .Fa "OM_uint32 * minor_status"
166 .Fa "const gss_name_t src_name"
167 .Fa "gss_name_t * dest_name"
168 .Fc
169 .Ft OM_uint32
170 .Fo gss_export_name
171 .Fa "OM_uint32 * minor_status"
172 .Fa "const gss_name_t input_name"
173 .Fa "gss_buffer_t exported_name"
174 .Fc
175 .Ft OM_uint32
176 .Fo gss_export_sec_context
177 .Fa "OM_uint32 * minor_status"
178 .Fa "gss_ctx_id_t * context_handle"
179 .Fa "gss_buffer_t interprocess_token"
180 .Fc
181 .Ft OM_uint32
182 .Fo gss_get_mic
183 .Fa "OM_uint32 * minor_status"
184 .Fa "const gss_ctx_id_t context_handle"
185 .Fa "gss_qop_t qop_req"
186 .Fa "const gss_buffer_t message_buffer"
187 .Fa "gss_buffer_t message_token"
188 .Fc
189 .Ft OM_uint32
190 .Fo gss_import_name
191 .Fa "OM_uint32 * minor_status,
192 .Fa "const gss_buffer_t input_name_buffer"
193 .Fa "const gss_OID input_name_type"
194 .Fa "gss_name_t * output_name"
195 .Fc
196 .Ft OM_uint32
197 .Fo gss_import_sec_context
198 .Fa "OM_uint32 * minor_status"
199 .Fa "const gss_buffer_t interprocess_token"
200 .Fa "gss_ctx_id_t * context_handle"
201 .Fc
202 .Ft OM_uint32
203 .Fo gss_indicate_mechs
204 .Fa "OM_uint32 * minor_status"
205 .Fa "gss_OID_set * mech_set"
206 .Fc
207 .Ft OM_uint32
208 .Fo gss_init_sec_context
209 .Fa "OM_uint32 * minor_status"
210 .Fa "const gss_cred_id_t initiator_cred_handle"
211 .Fa "gss_ctx_id_t * context_handle"
212 .Fa "const gss_name_t target_name"
213 .Fa "const gss_OID mech_type"
214 .Fa "OM_uint32 req_flags"
215 .Fa "OM_uint32 time_req"
216 .Fa "const gss_channel_bindings_t input_chan_bindings"
217 .Fa "const gss_buffer_t input_token"
218 .Fa "gss_OID * actual_mech_type"
219 .Fa "gss_buffer_t output_token"
220 .Fa "OM_uint32 * ret_flags"
221 .Fa "OM_uint32 * time_rec"
222 .Fc
223 .Ft OM_uint32
224 .Fo gss_inquire_context
225 .Fa "OM_uint32 * minor_status"
226 .Fa "const gss_ctx_id_t context_handle"
227 .Fa "gss_name_t * src_name"
228 .Fa "gss_name_t * targ_name"
229 .Fa "OM_uint32 * lifetime_rec"
230 .Fa "gss_OID * mech_type"
231 .Fa "OM_uint32 * ctx_flags"
232 .Fa "int * locally_initiated"
233 .Fa "int * open_context"
234 .Fc
235 .Ft OM_uint32
236 .Fo gss_inquire_cred
237 .Fa "OM_uint32 * minor_status"
238 .Fa "const gss_cred_id_t cred_handle"
239 .Fa "gss_name_t * name"
240 .Fa "OM_uint32 * lifetime"
241 .Fa "gss_cred_usage_t * cred_usage"
242 .Fa "gss_OID_set * mechanisms"
243 .Fc
244 .Ft OM_uint32
245 .Fo gss_inquire_cred_by_mech
246 .Fc
247 .Ft OM_uint32
248 .Fo gss_inquire_mechs_for_name
249 .Fc
250 .Ft OM_uint32
251 .Fo gss_inquire_names_for_mech
252 .Fc
253 .Ft OM_uint32
254 .Fo gss_krb5_copy_ccache
255 .Fa "OM_uint32 *minor"
256 .Fa "gss_cred_id_t cred"
257 .Fa "krb5_ccache out"
258 .Fc
259 .Ft OM_uint32
260 .Fo gss_process_context_token
261 .Fc
262 .Ft OM_uint32
263 .Fo gss_release_buffer
264 .Fa "OM_uint32 * minor_status"
265 .Fa "gss_buffer_t buffer"
266 .Fc
267 .Ft OM_uint32
268 .Fo gss_release_cred
269 .Fa "OM_uint32 * minor_status"
270 .Fa "gss_cred_id_t * cred_handle"
271 .Fc
272 .Ft OM_uint32
273 .Fo gss_release_name
274 .Fa "OM_uint32 * minor_status"
275 .Fa "gss_name_t * input_name"
276 .Fc
277 .Ft
278 .Fo gss_release_oid_set
279 .Fa "OM_uint32 * minor_status"
280 .Fa "gss_OID_set * set"
281 .Fc
282 .Ft OM_uint32
283 .Fo gss_seal
284 .Fa "OM_uint32 * minor_status"
285 .Fa "gss_ctx_id_t context_handle"
286 .Fa "int conf_req_flag"
287 .Fa "int qop_req"
288 .Fa "gss_buffer_t input_message_buffer"
289 .Fa "int * conf_state"
290 .Fa "gss_buffer_t output_message_buffer"
291 .Fc
292 .Ft OM_uint32
293 .Fo gss_sign
294 .Fa "OM_uint32 * minor_status"
295 .Fa "gss_ctx_id_t context_handle"
296 .Fa "int qop_req"
297 .Fa "gss_buffer_t message_buffer"
298 .Fa "gss_buffer_t message_token"
299 .Fc
300 .Ft OM_uint32
301 .Fo gss_test_oid_set_member
302 .Fa "OM_uint32 * minor_status"
303 .Fa "const gss_OID member"
304 .Fa "const gss_OID_set set"
305 .Fa "int * present"
306 .Fc
307 .Ft OM_uint32
308 .Fo gss_unseal
309 .Fa "OM_uint32 * minor_status"
310 .Fa "gss_ctx_id_t context_handle"
311 .Fa "gss_buffer_t input_message_buffer"
312 .Fa "gss_buffer_t output_message_buffer"
313 .Fa "int * conf_state"
314 .Fa "int * qop_state"
315 .Fc
316 .Ft OM_uint32
317 .Fo gss_unwrap
318 .Fa "OM_uint32 * minor_status"
319 .Fa "const gss_ctx_id_t context_handle"
320 .Fa "const gss_buffer_t input_message_buffer"
321 .Fa "gss_buffer_t output_message_buffer"
322 .Fa "int * conf_state"
323 .Fa "gss_qop_t * qop_state"
324 .Fc
325 .Ft OM_uint32
326 .Fo gss_verify
327 .Fa "OM_uint32 * minor_status"
328 .Fa "gss_ctx_id_t context_handle"
329 .Fa "gss_buffer_t message_buffer"
330 .Fa "gss_buffer_t token_buffer"
331 .Fa "int * qop_state"
332 .Fc
333 .Ft OM_uint32
334 .Fo gss_verify_mic
335 .Fa "OM_uint32 * minor_status"
336 .Fa "const gss_ctx_id_t context_handle"
337 .Fa "const gss_buffer_t message_buffer"
338 .Fa "const gss_buffer_t token_buffer"
339 .Fa "gss_qop_t * qop_state"
340 .Fc
341 .Ft
342 .Fo gss_wrap
343 .Fa "OM_uint32 * minor_status"
344 .Fa "const gss_ctx_id_t context_handle"
345 .Fa "int conf_req_flag"
346 .Fa "gss_qop_t qop_req"
347 .Fa "const gss_buffer_t input_message_buffer"
348 .Fa "int * conf_state"
349 .Fa "gss_buffer_t output_message_buffer"
350 .Fc
351 .Ft OM_uint32
352 .Fo gss_wrap_size_limit
353 .Fa "OM_uint32 * minor_status"
354 .Fa "const gss_ctx_id_t context_handle"
355 .Fa "int conf_req_flag"
356 .Fa "gss_qop_t qop_req"
357 .Fa "OM_uint32 req_output_size"
358 .Fa "OM_uint32 * max_input_size"
359 .Fc
360 .Sh DESCRIPTION
361 Generic Security Service API (GSS-API) version 2, and its C binding,
362 is described in
363 .Li RFC2743
364 and
365 .Li RFC2744 .
366 Version 1 (deprecated) of the C binding is described in
367 .Li RFC1509 .
368 .Pp
369 Heimdals GSS-API implementation supports the following mechanisms
370 .Bl -bullet
371 .It
372 .Li GSS_KRB5_MECHANISM
373 .El
374 .Pp
375 GSS-API have generic name types that all mechanism are supposed to
376 implement (if possible)
377 .Bl -bullet
378 .It
379 .Li GSS_C_NT_USER_NAME
380 .It
381 .Li GSS_C_NT_MACHINE_UID_NAME
382 .It
383 .Li GSS_C_NT_STRING_UID_NAME
384 .It
385 .Li GSS_C_NT_HOSTBASED_SERVICE
386 .It
387 .Li GSS_C_NT_ANONYMOUS
388 .It
389 .Li GSS_C_NT_EXPORT_NAME
390 .El
391 .Pp
392 GSS-API implementations that supports Kerberos 5 have some additional
393 name types
394 .Bl -bullet
395 .It
396 .Li GSS_KRB5_NT_PRINCIPAL_NAME
397 .It
398 .Li GSS_KRB5_NT_USER_NAME
399 .It
400 .Li GSS_KRB5_NT_MACHINE_UID_NAME
401 .It
402 .Li GSS_KRB5_NT_STRING_UID_NAME
403 .El
404 .Pp
405 .Fn gss_display_name
406 takes the gss name in
407 .Fa input_name
408 and put a printable form in
409 .Fa output_name_buffer .
410 .Fa output_name_buffer
411 should be freed when done using
412 .Fn gss_release_buffer .
413 .Fa output_name_type
414 can either be
415 .Dv NULL
416 or a pointer to a
417 .Li gss_OID
418 and will in the later case contain the OID type of the name.
419 The name should only be used for printing.
420 Access control should be done with the result of
421 .Fn gss_export_name .
422 .Pp
423 .Fn gss_sign ,
424 .Fn gss_verify ,
425 .Fn gss_seal ,
426 and
427 .Fn gss_unseal
428 are part of the GSS-API V1 interface and are obsolete. The functions
429 should not be used for new applications.
430 They are provided so that version 1 applications can link against the
431 library.
432 .Pp
433 .Fn gss_krb5_copy_ccache
434 is an extension to the GSS-API API.
435 The function will extract the krb5 credential that are transfered from
436 the initiator to the acceptor when using token delegation in the
437 Kerberos mechanism.
438 The acceptor receives the delegated token in the last argument to
439 .Fn gss_accept_sec_context .
440 .Sh SEE ALSO
441 .Xr krb5 3 ,
442 .Xr krb5_ccache 3 ,
443 .Xr gssapi 3 ,
444 .Xr kerberos 8