1 .\" Copyright (c) 2003 - 2004 Kungliga Tekniska Högskolan
2 .\" (Royal Institute of Technology, Stockholm, Sweden).
3 .\" All rights reserved.
5 .\" Redistribution and use in source and binary forms, with or without
6 .\" modification, are permitted provided that the following conditions
9 .\" 1. Redistributions of source code must retain the above copyright
10 .\" notice, this list of conditions and the following disclaimer.
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.
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.
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
35 .Dt GSS_ACQUIRE_CRED 3
38 .Nm gss_accept_sec_context ,
39 .Nm gss_acquire_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 ,
51 .Nm gss_export_sec_context ,
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_ccache_name ,
63 .Nm gss_krb5_compat_des3_mic ,
64 .Nm gss_krb5_copy_ccache ,
65 .Nm gsskrb5_extract_authz_data_from_sec_context ,
66 .Nm gss_krb5_get_tkt_flags ,
67 .Nm gss_process_context_token ,
68 .Nm gss_release_buffer ,
69 .Nm gss_release_cred ,
70 .Nm gss_release_name ,
71 .Nm gss_release_oid_set ,
74 .Nm gss_test_oid_set_member ,
80 .Nm gss_wrap_size_limit
81 .Nd Generic Security Service Application Program Interface library
83 GSS-API library (libgssapi, -lgssapi)
88 .Fo gss_accept_sec_context
89 .Fa "OM_uint32 * minor_status"
90 .Fa "gss_ctx_id_t * context_handle"
91 .Fa "const gss_cred_id_t acceptor_cred_handle"
92 .Fa "const gss_buffer_t input_token_buffer"
93 .Fa "const gss_channel_bindings_t input_chan_bindings"
94 .Fa "gss_name_t * src_name"
95 .Fa "gss_OID * mech_type"
96 .Fa "gss_buffer_t output_token"
97 .Fa "OM_uint32 * ret_flags"
98 .Fa "OM_uint32 * time_rec"
99 .Fa "gss_cred_id_t * delegated_cred_handle"
104 .Fa "OM_uint32 * minor_status"
105 .Fa "const gss_name_t desired_name"
106 .Fa "OM_uint32 time_req"
107 .Fa "const gss_OID_set desired_mechs"
108 .Fa "gss_cred_usage_t cred_usage"
109 .Fa "gss_cred_id_t * output_cred_handle"
110 .Fa "gss_OID_set * actual_mechs"
111 .Fa "OM_uint32 * time_rec"
115 .Fa "OM_uint32 *minor_status"
116 .Fa "const gss_cred_id_t input_cred_handle"
117 .Fa "const gss_name_t desired_name"
118 .Fa "const gss_OID desired_mech"
119 .Fa "gss_cred_usage_t cred_usage"
120 .Fa "OM_uint32 initiator_time_req"
121 .Fa "OM_uint32 acceptor_time_req"
122 .Fa "gss_cred_id_t *output_cred_handle"
123 .Fa "gss_OID_set *actual_mechs"
124 .Fa "OM_uint32 *initiator_time_rec"
125 .Fa "OM_uint32 *acceptor_time_rec"
128 .Fo gss_add_oid_set_member
129 .Fa "OM_uint32 * minor_status"
130 .Fa "const gss_OID member_oid"
131 .Fa "gss_OID_set * oid_set"
134 .Fo gss_canonicalize_name
135 .Fa "OM_uint32 * minor_status"
136 .Fa "const gss_name_t input_name"
137 .Fa "const gss_OID mech_type"
138 .Fa "gss_name_t * output_name"
142 .Fa "OM_uint32 * minor_status"
143 .Fa "const gss_name_t name1"
144 .Fa "const gss_name_t name2"
145 .Fa "int * name_equal"
149 .Fa "OM_uint32 * minor_status"
150 .Fa "const gss_ctx_id_t context_handle"
151 .Fa "OM_uint32 * time_rec"
154 .Fo gss_create_empty_oid_set
155 .Fa "OM_uint32 * minor_status"
156 .Fa "gss_OID_set * oid_set"
159 .Fo gss_delete_sec_context
160 .Fa "OM_uint32 * minor_status"
161 .Fa "gss_ctx_id_t * context_handle"
162 .Fa "gss_buffer_t output_token"
166 .Fa "OM_uint32 * minor_status"
167 .Fa "const gss_name_t input_name"
168 .Fa "gss_buffer_t output_name_buffer"
169 .Fa "gss_OID * output_name_type"
172 .Fo gss_display_status
173 .Fa "OM_uint32 *minor_status"
174 .Fa "OM_uint32 status_value"
175 .Fa "int status_type"
176 .Fa "const gss_OID mech_type"
177 .Fa "OM_uint32 *message_context"
178 .Fa "gss_buffer_t status_string"
181 .Fo gss_duplicate_name
182 .Fa "OM_uint32 * minor_status"
183 .Fa "const gss_name_t src_name"
184 .Fa "gss_name_t * dest_name"
188 .Fa "OM_uint32 * minor_status"
189 .Fa "const gss_name_t input_name"
190 .Fa "gss_buffer_t exported_name"
193 .Fo gss_export_sec_context
194 .Fa "OM_uint32 * minor_status"
195 .Fa "gss_ctx_id_t * context_handle"
196 .Fa "gss_buffer_t interprocess_token"
200 .Fa "OM_uint32 * minor_status"
201 .Fa "const gss_ctx_id_t context_handle"
202 .Fa "gss_qop_t qop_req"
203 .Fa "const gss_buffer_t message_buffer"
204 .Fa "gss_buffer_t message_token"
208 .Fa "OM_uint32 * minor_status"
209 .Fa "const gss_buffer_t input_name_buffer"
210 .Fa "const gss_OID input_name_type"
211 .Fa "gss_name_t * output_name"
214 .Fo gss_import_sec_context
215 .Fa "OM_uint32 * minor_status"
216 .Fa "const gss_buffer_t interprocess_token"
217 .Fa "gss_ctx_id_t * context_handle"
220 .Fo gss_indicate_mechs
221 .Fa "OM_uint32 * minor_status"
222 .Fa "gss_OID_set * mech_set"
225 .Fo gss_init_sec_context
226 .Fa "OM_uint32 * minor_status"
227 .Fa "const gss_cred_id_t initiator_cred_handle"
228 .Fa "gss_ctx_id_t * context_handle"
229 .Fa "const gss_name_t target_name"
230 .Fa "const gss_OID mech_type"
231 .Fa "OM_uint32 req_flags"
232 .Fa "OM_uint32 time_req"
233 .Fa "const gss_channel_bindings_t input_chan_bindings"
234 .Fa "const gss_buffer_t input_token"
235 .Fa "gss_OID * actual_mech_type"
236 .Fa "gss_buffer_t output_token"
237 .Fa "OM_uint32 * ret_flags"
238 .Fa "OM_uint32 * time_rec"
241 .Fo gss_inquire_context
242 .Fa "OM_uint32 * minor_status"
243 .Fa "const gss_ctx_id_t context_handle"
244 .Fa "gss_name_t * src_name"
245 .Fa "gss_name_t * targ_name"
246 .Fa "OM_uint32 * lifetime_rec"
247 .Fa "gss_OID * mech_type"
248 .Fa "OM_uint32 * ctx_flags"
249 .Fa "int * locally_initiated"
250 .Fa "int * open_context"
254 .Fa "OM_uint32 * minor_status"
255 .Fa "const gss_cred_id_t cred_handle"
256 .Fa "gss_name_t * name"
257 .Fa "OM_uint32 * lifetime"
258 .Fa "gss_cred_usage_t * cred_usage"
259 .Fa "gss_OID_set * mechanisms"
262 .Fo gss_inquire_cred_by_mech
263 .Fa "OM_uint32 * minor_status"
264 .Fa "const gss_cred_id_t cred_handle"
265 .Fa "const gss_OID mech_type"
266 .Fa "gss_name_t * name"
267 .Fa "OM_uint32 * initiator_lifetime"
268 .Fa "OM_uint32 * acceptor_lifetime"
269 .Fa "gss_cred_usage_t * cred_usage"
272 .Fo gss_inquire_mechs_for_name
273 .Fa "OM_uint32 * minor_status"
274 .Fa "const gss_name_t input_name"
275 .Fa "gss_OID_set * mech_types"
278 .Fo gss_inquire_names_for_mech
279 .Fa "OM_uint32 * minor_status"
280 .Fa "const gss_OID mechanism"
281 .Fa "gss_OID_set * name_types"
284 .Fo gss_krb5_ccache_name
285 .Fa "OM_uint32 *minor"
286 .Fa "const char *name"
287 .Fa "const char **old_name"
290 .Fo gss_krb5_copy_ccache
291 .Fa "OM_uint32 *minor"
292 .Fa "gss_cred_id_t cred"
293 .Fa "krb5_ccache out"
296 .Fo gss_krb5_compat_des3_mic
297 .Fa "OM_uint32 * minor_status"
298 .Fa "gss_ctx_id_t context_handle"
302 .Fo gsskrb5_extract_authz_data_from_sec_context
303 .Fa "OM_uint32 *minor_status"
304 .Fa "gss_ctx_id_t context_handle"
306 .Fa "gss_buffer_t ad_data"
309 .Fo gss_krb5_get_tkt_flags
310 .Fa "OM_uint32 *minor_status"
311 .Fa "gss_ctx_id_t context_handle"
312 .Fa "OM_uint32 *tkt_flags"
315 .Fo gss_process_context_token
316 .Fa "OM_uint32 * minor_status"
317 .Fa "const gss_ctx_id_t context_handle"
318 .Fa "const gss_buffer_t token_buffer"
321 .Fo gss_release_buffer
322 .Fa "OM_uint32 * minor_status"
323 .Fa "gss_buffer_t buffer"
327 .Fa "OM_uint32 * minor_status"
328 .Fa "gss_cred_id_t * cred_handle"
332 .Fa "OM_uint32 * minor_status"
333 .Fa "gss_name_t * input_name"
336 .Fo gss_release_oid_set
337 .Fa "OM_uint32 * minor_status"
338 .Fa "gss_OID_set * set"
342 .Fa "OM_uint32 * minor_status"
343 .Fa "gss_ctx_id_t context_handle"
344 .Fa "int conf_req_flag"
346 .Fa "gss_buffer_t input_message_buffer"
347 .Fa "int * conf_state"
348 .Fa "gss_buffer_t output_message_buffer"
352 .Fa "OM_uint32 * minor_status"
353 .Fa "gss_ctx_id_t context_handle"
355 .Fa "gss_buffer_t message_buffer"
356 .Fa "gss_buffer_t message_token"
359 .Fo gss_test_oid_set_member
360 .Fa "OM_uint32 * minor_status"
361 .Fa "const gss_OID member"
362 .Fa "const gss_OID_set set"
367 .Fa "OM_uint32 * minor_status"
368 .Fa "gss_ctx_id_t context_handle"
369 .Fa "gss_buffer_t input_message_buffer"
370 .Fa "gss_buffer_t output_message_buffer"
371 .Fa "int * conf_state"
372 .Fa "int * qop_state"
376 .Fa "OM_uint32 * minor_status"
377 .Fa "const gss_ctx_id_t context_handle"
378 .Fa "const gss_buffer_t input_message_buffer"
379 .Fa "gss_buffer_t output_message_buffer"
380 .Fa "int * conf_state"
381 .Fa "gss_qop_t * qop_state"
385 .Fa "OM_uint32 * minor_status"
386 .Fa "gss_ctx_id_t context_handle"
387 .Fa "gss_buffer_t message_buffer"
388 .Fa "gss_buffer_t token_buffer"
389 .Fa "int * qop_state"
393 .Fa "OM_uint32 * minor_status"
394 .Fa "const gss_ctx_id_t context_handle"
395 .Fa "const gss_buffer_t message_buffer"
396 .Fa "const gss_buffer_t token_buffer"
397 .Fa "gss_qop_t * qop_state"
401 .Fa "OM_uint32 * minor_status"
402 .Fa "const gss_ctx_id_t context_handle"
403 .Fa "int conf_req_flag"
404 .Fa "gss_qop_t qop_req"
405 .Fa "const gss_buffer_t input_message_buffer"
406 .Fa "int * conf_state"
407 .Fa "gss_buffer_t output_message_buffer"
410 .Fo gss_wrap_size_limit
411 .Fa "OM_uint32 * minor_status"
412 .Fa "const gss_ctx_id_t context_handle"
413 .Fa "int conf_req_flag"
414 .Fa "gss_qop_t qop_req"
415 .Fa "OM_uint32 req_output_size"
416 .Fa "OM_uint32 * max_input_size"
419 Generic Security Service API (GSS-API) version 2, and its C binding,
424 Version 1 (deprecated) of the C binding is described in
427 Heimdals GSS-API implementation supports the following mechanisms
430 .Li GSS_KRB5_MECHANISM
432 .Li GSS_SPNEGO_MECHANISM
435 GSS-API have generic name types that all mechanism are supposed to
436 implement (if possible):
439 .Li GSS_C_NT_USER_NAME
441 .Li GSS_C_NT_MACHINE_UID_NAME
443 .Li GSS_C_NT_STRING_UID_NAME
445 .Li GSS_C_NT_HOSTBASED_SERVICE
447 .Li GSS_C_NT_ANONYMOUS
449 .Li GSS_C_NT_EXPORT_NAME
452 GSS-API implementations that supports Kerberos 5 have some additional
456 .Li GSS_KRB5_NT_PRINCIPAL_NAME
458 .Li GSS_KRB5_NT_USER_NAME
460 .Li GSS_KRB5_NT_MACHINE_UID_NAME
462 .Li GSS_KRB5_NT_STRING_UID_NAME
465 In GSS-API, names have two forms, internal names and contiguous string
469 .Li Internal name and mechanism name
471 Internal names are implementation specific representation of
474 special form of internal names corresponds to one and only one mechanism.
476 In GSS-API an internal name is stored in a
479 .Li Contiguous string name and exported name
481 Contiguous string names are gssapi names stored in a
483 that together with a name type identifier (OID) uniquely specifies a
485 A special form of the contiguous string name is the exported name that
486 have a OID embedded in the string to make it unique.
487 Exported name have the nametype
488 .Dv GSS_C_NT_EXPORT_NAME .
490 In GSS-API an contiguous string name is stored in a
493 Exported names also have the property that they are specified by the
494 mechanism itself and compatible between diffrent GSS-API
498 There are two ways of comparing GSS-API names, either comparing two
499 internal names with each other or two contiguous string names with
502 To compare two internal names with each other, import (if needed) the
505 into the GSS-API implementation and the compare the imported name with
506 .Fn gss_compare_name .
508 Importing names can be slow, so when its possible to store exported
509 names in the access control list, comparing contiguous string name
512 when comparing contiguous string name, first export them into a
513 .Dv GSS_C_NT_EXPORT_NAME
516 and then compare with
519 Note that there are might be a difference between the two methods of
522 .Fn gss_compare_name )
523 will compare to (unauthenticated) names are the same.
524 The second will compare if a mechanism will authenticate them as the
531 the default syntax is used for all mechanism the GSS-API
532 implementation supports.
533 When compare the imported name of
535 it may match serveral mechanism names (MN).
537 The resulting name from
539 must not be used for acccess control.
542 takes the gss name in
544 and puts a printable form in
545 .Fa output_name_buffer .
546 .Fa output_name_buffer
547 should be freed when done using
548 .Fn gss_release_buffer .
554 and will in the latter case contain the OID type of the name.
555 The name must only be used for printing.
556 If access control is needed, see section
559 .Fn gss_inquire_context
560 returns information about the context.
561 Information is available even after the context have expired.
565 (dont expire) or the number of seconds that the context is still valid.
566 A value of 0 means that the context is expired.
568 argument should be considered readonly and must not be released.
572 are both mechanims names and must be released with
577 will return the amount of time (in seconds) of the context is still
582 .Dv GSS_S_CONTEXT_EXPIRED
590 are part of the GSS-API V1 interface and are obsolete.
591 The functions should not be used for new applications.
592 They are provided so that version 1 applications can link against the
595 .Fn gss_krb5_ccache_name
596 sets the internal kerberos 5 credential cache name to
598 The old name is returned in
600 and must not be freed.
601 The data allocated for
603 is free upon next call to
604 .Fn gss_krb5_ccache_name .
605 This function is not threadsafe if
609 .Fn gss_krb5_copy_ccache
610 will extract the krb5 credentials that are transferred from the
611 initiator to the acceptor when using token delegation in the Kerberos
613 The acceptor receives the delegated token in the last argument to
614 .Fn gss_accept_sec_context .
616 .Fn gsskrb5_register_acceptor_identity
617 sets the Kerberos 5 principal that the acceptor will use.
619 .Fn gsskrb5_extract_authz_data_from_sec_context
620 extracts the Kerberos authorizationdata that may be stored within the
622 Tha caller must free the returned buffer
625 .Fn gss_release_buffer
628 .Fn gss_krb5_get_tkt_flags
629 return the ticket flags for the kerberos ticket receive when
630 authenticating the initiator.
631 Only valid on the acceptor context.
633 .Fn gss_krb5_compat_des3_mic
634 turns on or off the compatibility with older version of Heimdal using
635 des3 get and verify mic, this is way to programmatically set the
636 [gssapi]broken_des3_mic and [gssapi]correct_des3_mic flags (see
637 COMPATIBILITY section in
640 .Dv GSS_C_KRB5_COMPAT_DES3_MIC
642 .Fn gss_krb5_compat_des3_mic
644 .Fn gss_krb5_compat_des3_mic
645 will be removed in a later version of the GSS-API library.