1GSS_ACQUIRE_CRED(3)      BSD Library Functions Manual      GSS_ACQUIRE_CRED(3)
2

NAME

4     gss_accept_sec_context, gss_acquire_cred, gss_add_cred,
5     gss_add_oid_set_member, gss_canonicalize_name, gss_compare_name,
6     gss_context_time, gss_create_empty_oid_set, gss_delete_sec_context,
7     gss_display_name, gss_display_status, gss_duplicate_name,
8     gss_export_name, gss_export_sec_context, gss_get_mic, gss_import_name,
9     gss_import_sec_context, gss_indicate_mechs, gss_init_sec_context,
10     gss_inquire_context, gss_inquire_cred, gss_inquire_cred_by_mech,
11     gss_inquire_mechs_for_name, gss_inquire_names_for_mech,
12     gss_krb5_ccache_name, gss_krb5_compat_des3_mic, gss_krb5_copy_ccache,
13     gss_krb5_import_cred gsskrb5_extract_authz_data_from_sec_context,
14     gsskrb5_register_acceptor_identity, gss_krb5_import_ccache,
15     gss_krb5_get_tkt_flags, gss_process_context_token, gss_release_buffer,
16     gss_release_cred, gss_release_name, gss_release_oid_set, gss_seal,
17     gss_sign, gss_test_oid_set_member, gss_unseal, gss_unwrap, gss_verify,
18     gss_verify_mic, gss_wrap, gss_wrap_size_limit — Generic Security Service
19     Application Program Interface library
20

LIBRARY

22     GSS-API library (libgssapi, -lgssapi)
23

SYNOPSIS

25     #include <gssapi.h>
26
27     OM_uint32
28     gss_accept_sec_context(OM_uint32 * minor_status,
29         gss_ctx_id_t * context_handle,
30         gss_const_cred_id_t acceptor_cred_handle,
31         const gss_buffer_t input_token_buffer,
32         const gss_channel_bindings_t input_chan_bindings,
33         gss_name_t * src_name, gss_OID * mech_type,
34         gss_buffer_t output_token, OM_uint32 * ret_flags,
35         OM_uint32 * time_rec, gss_cred_id_t * delegated_cred_handle);
36
37     OM_uint32
38     gss_acquire_cred(OM_uint32 * minor_status, gss_const_name_t desired_name,
39         OM_uint32 time_req, const gss_OID_set desired_mechs,
40         gss_cred_usage_t cred_usage, gss_cred_id_t * output_cred_handle,
41         gss_OID_set * actual_mechs, OM_uint32 * time_rec);
42
43     OM_uint32
44     gss_add_cred(OM_uint32 *minor_status,
45         gss_const_cred_id_t input_cred_handle, gss_const_name_t desired_name,
46         const gss_OID desired_mech, gss_cred_usage_t cred_usage,
47         OM_uint32 initiator_time_req, OM_uint32 acceptor_time_req,
48         gss_cred_id_t *output_cred_handle, gss_OID_set *actual_mechs,
49         OM_uint32 *initiator_time_rec, OM_uint32 *acceptor_time_rec);
50
51     OM_uint32
52     gss_add_oid_set_member(OM_uint32 * minor_status,
53         const gss_OID member_oid, gss_OID_set * oid_set);
54
55     OM_uint32
56     gss_canonicalize_name(OM_uint32 * minor_status,
57         gss_const_name_t input_name, const gss_OID mech_type,
58         gss_name_t * output_name);
59
60     OM_uint32
61     gss_compare_name(OM_uint32 * minor_status, gss_const_name_t name1,
62         gss_const_name_t name2, int * name_equal);
63
64     OM_uint32
65     gss_context_time(OM_uint32 * minor_status,
66         gss_const_ctx_id_t context_handle, OM_uint32 * time_rec);
67
68     OM_uint32
69     gss_create_empty_oid_set(OM_uint32 * minor_status,
70         gss_OID_set * oid_set);
71
72     OM_uint32
73     gss_delete_sec_context(OM_uint32 * minor_status,
74         gss_ctx_id_t * context_handle, gss_buffer_t output_token);
75
76     OM_uint32
77     gss_display_name(OM_uint32 * minor_status, gss_const_name_t input_name,
78         gss_buffer_t output_name_buffer, gss_OID * output_name_type);
79
80     OM_uint32
81     gss_display_status(OM_uint32 *minor_status, OM_uint32 status_value,
82         int status_type, const gss_OID mech_type, OM_uint32 *message_context,
83         gss_buffer_t status_string);
84
85     OM_uint32
86     gss_duplicate_name(OM_uint32 * minor_status, gss_const_name_t src_name,
87         gss_name_t * dest_name);
88
89     OM_uint32
90     gss_export_name(OM_uint32 * minor_status, gss_const_name_t input_name,
91         gss_buffer_t exported_name);
92
93     OM_uint32
94     gss_export_sec_context(OM_uint32 * minor_status,
95         gss_ctx_id_t * context_handle, gss_buffer_t interprocess_token);
96
97     OM_uint32
98     gss_get_mic(OM_uint32 * minor_status, gss_const_ctx_id_t context_handle,
99         gss_qop_t qop_req, const gss_buffer_t message_buffer,
100         gss_buffer_t message_token);
101
102     OM_uint32
103     gss_import_name(OM_uint32 * minor_status,
104         const gss_buffer_t input_name_buffer, const gss_OID input_name_type,
105         gss_name_t * output_name);
106
107     OM_uint32
108     gss_import_sec_context(OM_uint32 * minor_status,
109         const gss_buffer_t interprocess_token,
110         gss_ctx_id_t * context_handle);
111
112     OM_uint32
113     gss_indicate_mechs(OM_uint32 * minor_status, gss_OID_set * mech_set);
114
115     OM_uint32
116     gss_init_sec_context(OM_uint32 * minor_status,
117         gss_const_cred_id_t initiator_cred_handle,
118         gss_ctx_id_t * context_handle, gss_const_name_t target_name,
119         const gss_OID mech_type, OM_uint32 req_flags, OM_uint32 time_req,
120         const gss_channel_bindings_t input_chan_bindings,
121         const gss_buffer_t input_token, gss_OID * actual_mech_type,
122         gss_buffer_t output_token, OM_uint32 * ret_flags,
123         OM_uint32 * time_rec);
124
125     OM_uint32
126     gss_inquire_context(OM_uint32 * minor_status,
127         gss_const_ctx_id_t context_handle, gss_name_t * src_name,
128         gss_name_t * targ_name, OM_uint32 * lifetime_rec,
129         gss_OID * mech_type, OM_uint32 * ctx_flags, int * locally_initiated,
130         int * open_context);
131
132     OM_uint32
133     gss_inquire_cred(OM_uint32 * minor_status,
134         gss_const_cred_id_t cred_handle, gss_name_t * name,
135         OM_uint32 * lifetime, gss_cred_usage_t * cred_usage,
136         gss_OID_set * mechanisms);
137
138     OM_uint32
139     gss_inquire_cred_by_mech(OM_uint32 * minor_status,
140         gss_const_cred_id_t cred_handle, const gss_OID mech_type,
141         gss_name_t * name, OM_uint32 * initiator_lifetime,
142         OM_uint32 * acceptor_lifetime, gss_cred_usage_t * cred_usage);
143
144     OM_uint32
145     gss_inquire_mechs_for_name(OM_uint32 * minor_status,
146         gss_const_name_t input_name, gss_OID_set * mech_types);
147
148     OM_uint32
149     gss_inquire_names_for_mech(OM_uint32 * minor_status,
150         const gss_OID mechanism, gss_OID_set * name_types);
151
152     OM_uint32
153     gss_krb5_ccache_name(OM_uint32 *minor, const char *name,
154         const char **old_name);
155
156     OM_uint32
157     gss_krb5_copy_ccache(OM_uint32 *minor, gss_cred_id_t cred,
158         krb5_ccache out);
159
160     OM_uint32
161     gss_krb5_import_cred(OM_uint32 *minor_status, krb5_ccache id,
162         krb5_principal keytab_principal, krb5_keytab keytab,
163         gss_cred_id_t *cred);
164
165     OM_uint32
166     gss_krb5_compat_des3_mic(OM_uint32 * minor_status,
167         gss_ctx_id_t context_handle, int onoff);
168
169     OM_uint32
170     gsskrb5_extract_authz_data_from_sec_context(OM_uint32 *minor_status,
171         gss_ctx_id_t context_handle, int ad_type, gss_buffer_t ad_data);
172
173     OM_uint32
174     gsskrb5_register_acceptor_identity(const char *identity);
175
176     OM_uint32
177     gss_krb5_import_cache(OM_uint32 *minor, krb5_ccache id,
178         krb5_keytab keytab, gss_cred_id_t *cred);
179
180     OM_uint32
181     gss_krb5_get_tkt_flags(OM_uint32 *minor_status,
182         gss_ctx_id_t context_handle, OM_uint32 *tkt_flags);
183
184     OM_uint32
185     gss_process_context_token(OM_uint32 * minor_status,
186         gss_const_ctx_id_t context_handle, const gss_buffer_t token_buffer);
187
188     OM_uint32
189     gss_release_buffer(OM_uint32 * minor_status, gss_buffer_t buffer);
190
191     OM_uint32
192     gss_release_cred(OM_uint32 * minor_status, gss_cred_id_t * cred_handle);
193
194     OM_uint32
195     gss_release_name(OM_uint32 * minor_status, gss_name_t * input_name);
196
197     OM_uint32
198     gss_release_oid_set(OM_uint32 * minor_status, gss_OID_set * set);
199
200     OM_uint32
201     gss_seal(OM_uint32 * minor_status, gss_ctx_id_t context_handle,
202         int conf_req_flag, int qop_req, gss_buffer_t input_message_buffer,
203         int * conf_state, gss_buffer_t output_message_buffer);
204
205     OM_uint32
206     gss_sign(OM_uint32 * minor_status, gss_ctx_id_t context_handle,
207         int qop_req, gss_buffer_t message_buffer,
208         gss_buffer_t message_token);
209
210     OM_uint32
211     gss_test_oid_set_member(OM_uint32 * minor_status, const gss_OID member,
212         const gss_OID_set set, int * present);
213
214     OM_uint32
215     gss_unseal(OM_uint32 * minor_status, gss_ctx_id_t context_handle,
216         gss_buffer_t input_message_buffer,
217         gss_buffer_t output_message_buffer, int * conf_state,
218         int * qop_state);
219
220     OM_uint32
221     gss_unwrap(OM_uint32 * minor_status, gss_const_ctx_id_t context_handle,
222         const gss_buffer_t input_message_buffer,
223         gss_buffer_t output_message_buffer, int * conf_state,
224         gss_qop_t * qop_state);
225
226     OM_uint32
227     gss_verify(OM_uint32 * minor_status, gss_ctx_id_t context_handle,
228         gss_buffer_t message_buffer, gss_buffer_t token_buffer,
229         int * qop_state);
230
231     OM_uint32
232     gss_verify_mic(OM_uint32 * minor_status,
233         gss_const_ctx_id_t context_handle, const gss_buffer_t message_buffer,
234         const gss_buffer_t token_buffer, gss_qop_t * qop_state);
235
236     OM_uint32
237     gss_wrap(OM_uint32 * minor_status, gss_const_ctx_id_t context_handle,
238         int conf_req_flag, gss_qop_t qop_req,
239         const gss_buffer_t input_message_buffer, int * conf_state,
240         gss_buffer_t output_message_buffer);
241
242     OM_uint32
243     gss_wrap_size_limit(OM_uint32 * minor_status,
244         gss_const_ctx_id_t context_handle, int conf_req_flag,
245         gss_qop_t qop_req, OM_uint32 req_output_size,
246         OM_uint32 * max_input_size);
247

DESCRIPTION

249     Generic Security Service API (GSS-API) version 2, and its C binding, is
250     described in RFC2743 and RFC2744.  Version 1 (deprecated) of the C bind‐
251     ing is described in RFC1509.
252
253     Heimdals GSS-API implementation supports the following mechanisms
254
255     ·   GSS_KRB5_MECHANISM
256
257     ·   GSS_SPNEGO_MECHANISM
258
259     GSS-API have generic name types that all mechanism are supposed to imple‐
260     ment (if possible):
261
262     ·   GSS_C_NT_USER_NAME
263
264     ·   GSS_C_NT_MACHINE_UID_NAME
265
266     ·   GSS_C_NT_STRING_UID_NAME
267
268     ·   GSS_C_NT_HOSTBASED_SERVICE
269
270     ·   GSS_C_NT_ANONYMOUS
271
272     ·   GSS_C_NT_EXPORT_NAME
273
274     GSS-API implementations that supports Kerberos 5 have some additional
275     name types:
276
277     ·   GSS_KRB5_NT_PRINCIPAL_NAME
278
279     ·   GSS_KRB5_NT_USER_NAME
280
281     ·   GSS_KRB5_NT_MACHINE_UID_NAME
282
283     ·   GSS_KRB5_NT_STRING_UID_NAME
284
285     In GSS-API, names have two forms, internal names and contiguous string
286     names.
287
288     ·   Internal name and mechanism name
289
290         Internal names are implementation specific representation of a GSS-
291         API name.  Mechanism names special form of internal names corresponds
292         to one and only one mechanism.
293
294         In GSS-API an internal name is stored in a gss_name_t.
295
296     ·   Contiguous string name and exported name
297
298         Contiguous string names are gssapi names stored in a OCTET STRING
299         that together with a name type identifier (OID) uniquely specifies a
300         gss-name.  A special form of the contiguous string name is the
301         exported name that have a OID embedded in the string to make it
302         unique.  Exported name have the nametype GSS_C_NT_EXPORT_NAME.
303
304         In GSS-API an contiguous string name is stored in a gss_buffer_t.
305
306         Exported names also have the property that they are specified by the
307         mechanism itself and compatible between different GSS-API implementa‐
308         tions.
309

ACCESS CONTROL

311     There are two ways of comparing GSS-API names, either comparing two
312     internal names with each other or two contiguous string names with either
313     other.
314
315     To compare two internal names with each other, import (if needed) the
316     names with gss_import_name() into the GSS-API implementation and the com‐
317     pare the imported name with gss_compare_name().
318
319     Importing names can be slow, so when its possible to store exported names
320     in the access control list, comparing contiguous string name might be
321     better.
322
323     when comparing contiguous string name, first export them into a
324     GSS_C_NT_EXPORT_NAME name with gss_export_name() and then compare with
325     memcmp(3).
326
327     Note that there are might be a difference between the two methods of com‐
328     paring names.  The first (using gss_compare_name()) will compare to
329     (unauthenticated) names are the same.  The second will compare if a mech‐
330     anism will authenticate them as the same principal.
331
332     For example, if gss_import_name() name was used with GSS_C_NO_OID the
333     default syntax is used for all mechanism the GSS-API implementation sup‐
334     ports.  When compare the imported name of GSS_C_NO_OID it may match sev‐
335     eral mechanism names (MN).
336
337     The resulting name from gss_display_name() must not be used for acccess
338     control.
339

FUNCTIONS

341     gss_display_name() takes the gss name in input_name and puts a printable
342     form in output_name_buffer.  output_name_buffer should be freed when done
343     using gss_release_buffer().  output_name_type can either be NULL or a
344     pointer to a gss_OID and will in the latter case contain the OID type of
345     the name.  The name must only be used for printing.  If access control is
346     needed, see section ACCESS CONTROL.
347
348     gss_inquire_context() returns information about the context.  Information
349     is available even after the context have expired.  lifetime_rec argument
350     is set to GSS_C_INDEFINITE (don't expire) or the number of seconds that
351     the context is still valid.  A value of 0 means that the context is
352     expired.  mech_type argument should be considered readonly and must not
353     be released.  src_name and dest_name() are both mechanims names and must
354     be released with gss_release_name() when no longer used.
355
356     gss_context_time will return the amount of time (in seconds) of the con‐
357     text is still valid.  If its expired time_rec will be set to 0 and
358     GSS_S_CONTEXT_EXPIRED returned.
359
360     gss_sign(), gss_verify(), gss_seal(), and gss_unseal() are part of the
361     GSS-API V1 interface and are obsolete.  The functions should not be used
362     for new applications.  They are provided so that version 1 applications
363     can link against the library.
364

EXTENSIONS

366     gss_krb5_ccache_name() sets the internal kerberos 5 credential cache name
367     to name.  The old name is returned in old_name, and must not be freed.
368     The data allocated for old_name is free upon next call to
369     gss_krb5_ccache_name().  This function is not threadsafe if old_name
370     argument is used.
371
372     gss_krb5_copy_ccache() will extract the krb5 credentials that are trans‐
373     ferred from the initiator to the acceptor when using token delegation in
374     the Kerberos mechanism.  The acceptor receives the delegated token in the
375     last argument to gss_accept_sec_context().
376
377     gss_krb5_import_cred() will import the krb5 credentials (both keytab
378     and/or credential cache) into gss credential so it can be used withing
379     GSS-API.  The ccache is copied by reference and thus shared, so if the
380     credential is destroyed with krb5_cc_destroy, all users of thep
381     gss_cred_id_t returned by gss_krb5_import_ccache() will fail.
382
383     gsskrb5_register_acceptor_identity() sets the Kerberos 5 filebased keytab
384     that the acceptor will use.  The identifier is the file name.
385
386     gsskrb5_extract_authz_data_from_sec_context() extracts the Kerberos
387     authorizationdata that may be stored within the context.  Tha caller must
388     free the returned buffer ad_data with gss_release_buffer() upon success.
389
390     gss_krb5_get_tkt_flags() return the ticket flags for the kerberos ticket
391     receive when authenticating the initiator.  Only valid on the acceptor
392     context.
393
394     gss_krb5_compat_des3_mic() turns on or off the compatibility with older
395     version of Heimdal using des3 get and verify mic, this is way to program‐
396     matically set the [gssapi]broken_des3_mic and [gssapi]correct_des3_mic
397     flags (see COMPATIBILITY section in gssapi(3)).  If the CPP symbol
398     GSS_C_KRB5_COMPAT_DES3_MIC is present, gss_krb5_compat_des3_mic() exists.
399     gss_krb5_compat_des3_mic() will be removed in a later version of the GSS-
400     API library.
401

SEE ALSO

403     gssapi(3), krb5(3), krb5_ccache(3), kerberos(8)
404
405HEIMDAL                        October 26, 2005                        HEIMDAL
Impressum