1gss_init_sec_contGeexnte(r3iGcSSS)ecurity Services API LibrarygsFsu_nicntiito_nssec_context(3GSS)
2
6 gss_init_sec_context - initiate a GSS-API security context with a peer
7 application
8
10 cc [ flag... ] file... -lgss [ library... ]
11 #include <gssapi/gssapi.h>
12 OM_uint32 gss_init_sec_context(OM_uint32 *minor_status,
14 const gss_cred_id_t initiator_cred_handle,
15 gss_ctx_id_t *context_handle, const gss_name_t *target_name,
16 const gss_OID mech_type, OM_uint32 req_flags,
17 OM_uint32 time_req, const gss_channel_bindings_t input_chan_bindings,
18 const gss_buffer_t input_token, gss_OID *actual_mech_type,
19 gss_buffer_t output_token, OM_uint32 *ret_flags,
20 OM_uint32 *time_rec);
21
24 The parameter descriptions for gss_init_sec_context() follow:
25 minor_status A mechanism specific status code.
27 initiator_cred_handle The handle for the credentials claimed. Supply
30 GSS_C_NO_CREDENTIAL to act as a default ini‐
31 tiator principal. If no default initiator is
32 defined, the function returns GSS_S_NO_CRED.
33 context_handle The context handle for a new context. Supply
36 the value GSS_C_NO_CONTEXT for the first call,
37 and use the value returned in any continuation
38 calls. The resources associated with con‐
39 text_handle must be released by the applica‐
40 tion after use by a call to
41 gss_delete_sec_context(3GSS).
42 target_name The name of the context acceptor.
45 mech_type The object ID of the desired mechanism. To
48 obtain a specific default, supply the value
49 GSS_C_NO_ID.
50 req_flags Contains independent flags, each of which will
53 request that the context support a specific
54 service option. A symbolic name is provided
55 for each flag. Logically-OR the symbolic name
56 to the corresponding required flag to form the
57 bit-mask value. req_flags may contain one of
58 the following values:
59 GSS_C_DELEG_FLAG If true, delegate cre‐
61 dentials to a remote
62 peer. Do not delegate
63 the credentials if the
64 value is false.
65 GSS_C_MUTUAL_FLAG If true, request that
68 the peer authenticate
69 itself. If false,
70 authenticate to the
71 remote peer only.
72 GSS_C_REPLAY_FLAG If true, enable replay
75 detection for messages
76 protected with
77 gss_wrap(3GSS) or
78 gss_get_mic(3GSS). Do
79 not attempt to detect
80 replayed messages if
81 false.
82 GSS_C_SEQUENCE_FLAG If true, enable detec‐
85 tion of out-of-sequence
86 protected messages. Do
87 not attempt to detect
88 out-of-sequence mes‐
89 sages if false.
90 GSS_C_CONF_FLAG If true, request that
93 confidential service be
94 made available by means
95 of gss_wrap(3GSS). If
96 false, no per-message
97 confidential service is
98 required.
99 GSS_C_INTEG_FLAG If true, request that
102 integrity service be
103 made available by means
104 of gss_wrap(3GSS) or
105 gss_get_mic(3GSS). If
106 false, no per-message
107 integrity service is
108 required.
109 GSS_C_ANON_FLAG If true, do not reveal
112 the initiator's iden‐
113 tify to the acceptor.
114 If false, authenticate
115 normally.
116 time_req The number of seconds for which the context
120 will remain valid. Supply a zero value to
121 time_req to request a default validity period.
122 input_chan_bindings Optional application-specified bindings.
125 Allows application to securely bind channel
126 identification information to the security
127 context. Set to GSS_C_NO_CHANNEL_BINDINGS if
128 you do not want to use channel bindings.
129 input_token Token received from the peer application. On
132 the initial call, supply GSS_C_NO_BUFFER or a
133 pointer to a buffer containing the value
134 GSS_C_EMPTY_BUFFER.
135 actual_mech_type The actual mechanism used. The OID returned by
138 means of this parameter will be pointer to
139 static storage that should be treated as read-
140 only. The application should not attempt to
141 free it. To obtain a specific default, supply
142 the value GSS_C_NO_ID. Specify NULL if the
143 parameter is not required.
144 output_token The token to send to the peer application. If
147 the length field of the returned buffer is
148 zero, no token need be sent to the peer appli‐
149 cation. After use storage associated with this
150 buffer must be freed by the application by a
151 call to gss_release_buffer(3GSS).
152 ret_flags Contains various independent flags, each of
155 which indicates that the context supports a
156 specific service option. If not needed, spec‐
157 ify NULL. Test the returned bit-mask ret_flags
158 value against its symbolic name to determine
159 if the given option is supported by the con‐
160 text. ret_flags may contain one of the follow‐
161 ing values:
162 GSS_C_DELEG_FLAG If true, credentials
164 were delegated to the
165 remote peer. If
166 false, no credentials
167 were delegated.
168 GSS_C_MUTUAL_FLAG If true, the remote
171 peer authenticated
172 itself. If false, the
173 remote peer did not
174 authenticate itself.
175 GSS_C_REPLAY_FLAG If true, replay of
178 protected messages
179 will be detected. If
180 false, replayed mes‐
181 sages will not be
182 detected.
183 GSS_C_SEQUENCE_FLAG If true, out of
186 sequence protected
187 messages will be
188 detected. If false,
189 they will not be
190 detected.
191 GSS_C_CONF_FLAG If true, confidential
194 service may be
195 invoked by calling
196 the gss_wrap() rou‐
197 tine. If false, no
198 confidentiality ser‐
199 vice is available by
200 means of
201 gss_wrap(3GSS).
202 gss_wrap() will pro‐
203 vide message encapsu‐
204 lation, data-origin
205 authentication and
206 integrity services
207 only.
208 GSS_C_INTEG_FLAG If true, integrity
211 service may be
212 invoked by calling
213 either the
214 gss_wrap(3GSS) or
215 gss_get_mic(3GSS)
216 routine. If false,
217 per-message integrity
218 service is not avail‐
219 able.
220 GSS_C_ANON_FLAG If true, the initia‐
223 tor's identity has
224 not been revealed; it
225 will not be revealed
226 if any emitted token
227 is passed to the
228 acceptor. If false,
229 the initiator has
230 been or will be
231 authenticated nor‐
232 mally.
233 GSS_C_PROT_READY_FLAG If true, the protec‐
236 tion services speci‐
237 fied by the states of
238 GSS_C_CONF_FLAG and
239 GSS_C_INTEG_FLAG are
240 available if the
241 accompanying major
242 status return value
243 is either GSS_S_COM‐
244 PLETE or GSS_S_CON‐
245 TINUE_NEEDED. If
246 false, the protection
247 services are avail‐
248 able only if the
249 accompanying major
250 status return value
251 is GSS_S_COMPLETE.
252 GSS_C_TRANS_FLAG If true, the resul‐
255 tant security context
256 may be transferred to
257 other processes by
258 means of a call to
259 gss_export_sec_con‐
260 text(3GSS). If false,
261 the security context
262 cannot be trans‐
263 ferred.
264 time_rec The number of seconds for which the context
268 will remain valid. Specify NULL if the parame‐
269 ter is not required.
270
273 The gss_init_sec_context() function initiates the establishment of a
274 security context between the application and a remote peer. Initially,
275 the input_token parameter should be specified either as GSS_C_NO_BUF‐
276 FER, or as a pointer to a gss_buffer_desc object with a length field
277 that contains a zero value. The routine may return a output_token,
278 which should be transferred to the peer application, which will present
279 it to gss_accept_sec_context(3GSS). If no token need be sent,
280 gss_init_sec_context() will indicate this by setting the length field
281 of the output_token argument to zero. To complete context establish‐
282 ment, one or more reply tokens may be required from the peer applica‐
283 tion; if so, gss_init_sec_context() will return a status code that con‐
284 tains the supplementary information bit GSS_S_CONTINUE_NEEDED. In this
285 case, make another call to gss_init_sec_context() when the reply token
286 is received from the peer application and pass the reply token to
287 gss_init_sec_context() by means of the input_token parameter.
288 Construct portable applications to use the token length and return sta‐
291 tus to determine whether to send or wait for a token.
292 Whenever the routine returns a major status that includes the value
295 GSS_S_CONTINUE_NEEDED, the context is not fully established, and the
296 following restrictions apply to the output parameters:
297 o The value returned by means of the time_rec parameter is
299 undefined. Unless the accompanying ret_flags parameter con‐
300 tains the bit GSS_C_PROT_READY_FLAG, which indicates that
301 per-message services may be applied in advance of a success‐
302 ful completion status, the value returned by means of the
303 actual_mech_type parameter is undefined until the routine
304 returns a major status value of GSS_S_COMPLETE.
305 o The values of the GSS_C_DELEG_FLAG, GSS_C_MUTUAL_FLAG,
307 GSS_C_REPLAY_FLAG, GSS_C_SEQUENCE_FLAG, GSS_C_CONF_FLAG,
308 GSS_C_INTEG_FLAG and GSS_C_ANON_FLAG bits returned by the
309 ret_flags parameter contain values that will be valid if
310 context establishment succeeds. For example, if the applica‐
311 tion requests a service such as delegation or anonymous
312 authentication by means of the req_flags argument, and the
313 service is unavailable from the underlying mechanism,
314 gss_init_sec_context() generates a token that will not pro‐
315 vide the service, and it indicate by means of the ret_flags
316 argument that the service will not be supported. The appli‐
317 cation may choose to abort context establishment by calling
318 gss_delete_sec_context(3GSS) if it cannot continue without
319 the service, or if the service was merely desired but not
320 mandatory, it may transmit the token and continue context
321 establishment.
322 o The values of the GSS_C_PROT_READY_FLAG and GSS_C_TRANS_FLAG
324 bits within ret_flags indicate the actual state at the time
325 gss_init_sec_context() returns, whether or not the context
326 is fully established.
327 o The GSS-API sets the GSS_C_PROT_READY_FLAG in the final
329 ret_flags returned to a caller, for example, when accompa‐
330 nied by a GSS_S_COMPLETE status code. However, applications
331 should not rely on this behavior, as the flag was not
332 defined in Version 1 of the GSS-API. Instead, applications
333 should determine what per-message services are available
334 after a successful context establishment according to the
335 GSS_C_INTEG_FLAG and GSS_C_CONF_FLAG values.
336 o All other bits within the ret_flags argument are set to
338 zero.
339 If the initial call of gss_init_sec_context() fails, the GSS-API does
342 not create a context object; it leaves the value of the context_handle
343 parameter set to GSS_C_NO_CONTEXT to indicate this. In the event of
344 failure on a subsequent call, the GSS-API leaves the security context
345 untouched for the application to delete using gss_delete_sec_con‐
346 text(3GSS).
347 During context establishment, the informational status bits
350 GSS_S_OLD_TOKEN and GSS_S_DUPLICATE_TOKEN indicate fatal errors, and
351 GSS-API mechanisms should always return them in association with a sta‐
352 tus code of GSS_S_FAILURE. This pairing requirement was not part of
353 Version 1 of the GSS-API specification, so applications that wish to
354 run on Version 1 implementations must special-case these codes.
355
357 gss_init_sec_context() may return the following status codes:
358 GSS_S_COMPLETE Successful completion.
360 GSS_S_CONTINUE_NEEDED A token from the peer application is
363 required to complete the context, and
364 gss_init_sec_context() must be called
365 again with that token.
366 GSS_S_DEFECTIVE_TOKEN Consistency checks performed on the
369 input_token failed.
370 GSS_S_DEFECTIVE_CREDENTIAL Consistency checks performed on the cre‐
373 dential failed.
374 GSS_S_NO_CRED The supplied credentials are not valid
377 for context acceptance, or the credential
378 handle does not reference any creden‐
379 tials.
380 GSS_S_CREDENTIALS_EXPIRED The referenced credentials have expired.
383 GSS_S_BAD_BINDINGS The input_token contains different chan‐
386 nel bindings than those specified by
387 means of the input_chan_bindings parame‐
388 ter.
389 GSS_S_BAD_SIG The input_token contains an invalid MIC
392 or a MIC that cannot be verified.
393 GSS_S_OLD_TOKEN The input_token is too old. This is a
396 fatal error while establishing context.
397 GSS_S_DUPLICATE_TOKEN The input_token is valid, but it is a
400 duplicate of a token already processed.
401 This is a fatal error while establishing
402 context.
403 GSS_S_NO_CONTEXT The supplied context handle does not
406 refer to a valid context.
407 GSS_S_BAD_NAMETYPE The provided target_name parameter con‐
410 tains an invalid or unsupported name
411 type.
412 GSS_S_BAD_NAME The supplied target_name parameter is
415 ill-formed.
416 GSS_S_BAD_MECH The token received specifies a mechanism
419 that is not supported by the implementa‐
420 tion or the provided credential.
421 GSS_S_FAILURE The underlying mechanism detected an
424 error for which no specific GSS status
425 code is defined. The mechanism-specific
426 status code reported by means of the
427 minor_status parameter details the error
428 condition.
429
432 Example 1 Invoking gss_init_sec_context() Within a Loop
433 A typical portable caller should always invoke gss_init_sec_context()
436 within a loop:
437 int context_established = 0;
440 gss_ctx_id_t context_hdl = GSS_C_NO_CONTEXT;
441 ...
442 input_token->length = 0;
443 while (!context_established) {
445 maj_stat = gss_init_sec_context(&min_stat,
446 cred_hdl,
447 &context_hdl,
448 target_name,
449 desired_mech,
450 desired_services,
451 desired_time,
452 input_bindings,
453 input_token,
454 &actual_mech,
455 output_token,
456 &actual_services,
457 &actual_time);
458 if (GSS_ERROR(maj_stat)) {
459 report_error(maj_stat, min_stat);
460 };
461 if (output_token->length != 0) {
463 send_token_to_peer(output_token);
464 gss_release_buffer(&min_stat, output_token)
465 };
466 if (GSS_ERROR(maj_stat)) {
467 if (context_hdl != GSS_C_NO_CONTEXT)
469 gss_delete_sec_context(&min_stat,
470 &context_hdl,
471 GSS_C_NO_BUFFER);
472 break;
473 };
474 if (maj_stat & GSS_S_CONTINUE_NEEDED) {
475 receive_token_from_peer(input_token);
476 } else {
477 context_established = 1;
478 };
479 };
480
483 See attributes(5) for descriptions of the following attributes:
484 ┌─────────────────────────────┬─────────────────────────────┐
489 │ ATTRIBUTE TYPE │ ATTRIBUTE VALUE │
490 ├─────────────────────────────┼─────────────────────────────┤
491 │MT-Level │Safe │
492 └─────────────────────────────┴─────────────────────────────┘
493
495 gss_delete_sec_context(3GSS), gss_export_sec_context(3GSS),
496 gss_get_mic(3GSS), gss_wrap(3GSS), attributes(5)
497 Solaris Security for Developers Guide
500SunOS 5.11 22 May 2006 gss_init_sec_context(3GSS)