1GSS_ACQUIRE_CRED(3) BSD Library Functions Manual GSS_ACQUIRE_CRED(3)
2
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
22 GSS-API library (libgssapi, -lgssapi)
23
25 #include <gssapi.h>
26 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 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 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 OM_uint32
52 gss_add_oid_set_member(OM_uint32 * minor_status,
53 const gss_OID member_oid, gss_OID_set * oid_set);
54 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 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 OM_uint32
65 gss_context_time(OM_uint32 * minor_status,
66 gss_const_ctx_id_t context_handle, OM_uint32 * time_rec);
67 OM_uint32
69 gss_create_empty_oid_set(OM_uint32 * minor_status,
70 gss_OID_set * oid_set);
71 OM_uint32
73 gss_delete_sec_context(OM_uint32 * minor_status,
74 gss_ctx_id_t * context_handle, gss_buffer_t output_token);
75 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 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 OM_uint32
86 gss_duplicate_name(OM_uint32 * minor_status, gss_const_name_t src_name,
87 gss_name_t * dest_name);
88 OM_uint32
90 gss_export_name(OM_uint32 * minor_status, gss_const_name_t input_name,
91 gss_buffer_t exported_name);
92 OM_uint32
94 gss_export_sec_context(OM_uint32 * minor_status,
95 gss_ctx_id_t * context_handle, gss_buffer_t interprocess_token);
96 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 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 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 OM_uint32
113 gss_indicate_mechs(OM_uint32 * minor_status, gss_OID_set * mech_set);
114 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 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 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 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 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 OM_uint32
149 gss_inquire_names_for_mech(OM_uint32 * minor_status,
150 const gss_OID mechanism, gss_OID_set * name_types);
151 OM_uint32
153 gss_krb5_ccache_name(OM_uint32 *minor, const char *name,
154 const char **old_name);
155 OM_uint32
157 gss_krb5_copy_ccache(OM_uint32 *minor, gss_cred_id_t cred,
158 krb5_ccache out);
159 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 OM_uint32
166 gss_krb5_compat_des3_mic(OM_uint32 * minor_status,
167 gss_ctx_id_t context_handle, int onoff);
168 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 OM_uint32
174 gsskrb5_register_acceptor_identity(const char *identity);
175 OM_uint32
177 gss_krb5_import_cache(OM_uint32 *minor, krb5_ccache id,
178 krb5_keytab keytab, gss_cred_id_t *cred);
179 OM_uint32
181 gss_krb5_get_tkt_flags(OM_uint32 *minor_status,
182 gss_ctx_id_t context_handle, OM_uint32 *tkt_flags);
183 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 OM_uint32
189 gss_release_buffer(OM_uint32 * minor_status, gss_buffer_t buffer);
190 OM_uint32
192 gss_release_cred(OM_uint32 * minor_status, gss_cred_id_t * cred_handle);
193 OM_uint32
195 gss_release_name(OM_uint32 * minor_status, gss_name_t * input_name);
196 OM_uint32
198 gss_release_oid_set(OM_uint32 * minor_status, gss_OID_set * set);
199 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 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 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 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 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 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 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 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 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
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 Heimdals GSS-API implementation supports the following mechanisms
254 · GSS_KRB5_MECHANISM
256 · GSS_SPNEGO_MECHANISM
258 GSS-API have generic name types that all mechanism are supposed to imple‐
260 ment (if possible):
261 · GSS_C_NT_USER_NAME
263 · GSS_C_NT_MACHINE_UID_NAME
265 · GSS_C_NT_STRING_UID_NAME
267 · GSS_C_NT_HOSTBASED_SERVICE
269 · GSS_C_NT_ANONYMOUS
271 · GSS_C_NT_EXPORT_NAME
273 GSS-API implementations that supports Kerberos 5 have some additional
275 name types:
276 · GSS_KRB5_NT_PRINCIPAL_NAME
278 · GSS_KRB5_NT_USER_NAME
280 · GSS_KRB5_NT_MACHINE_UID_NAME
282 · GSS_KRB5_NT_STRING_UID_NAME
284 In GSS-API, names have two forms, internal names and contiguous string
286 names.
287 · Internal name and mechanism name
289 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 In GSS-API an internal name is stored in a gss_name_t.
295 · Contiguous string name and exported name
297 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 In GSS-API an contiguous string name is stored in a gss_buffer_t.
305 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
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 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 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 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 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 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 The resulting name from gss_display_name() must not be used for acccess
338 control.
339
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 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 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 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
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 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 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 gsskrb5_register_acceptor_identity() sets the Kerberos 5 filebased keytab
384 that the acceptor will use. The identifier is the file name.
385 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 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 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
403 gssapi(3), krb5(3), krb5_ccache(3), kerberos(8)
404HEIMDAL October 26, 2005 HEIMDAL