1gss_accept_sec_coGnetneexrti(c3GSSeSc)urity Services API Libragrsys_Faucnccetpito_nssec_context(3GSS)
2
6 gss_accept_sec_context - accept a security context initiated by a peer
7 application
8
10 cc [ flag... ] file... -lgss [ library... ]
11 #include <gssapi/gssapi.h>
12 OM_uint32 gss_accept_sec_context(OM_uint32 *minor_status,
14 gss_ctx_id_t *context_handle,
15 const gss_cred_id_t acceptor_cred_handle,
16 const gss_buffer_t input_token,
17 const gss_channel_bindings_t input_chan_bindings,
18 const gss_name_t * src_name, gss_OID * mech_type,
19 gss_buffer_t output_token, OM_uint32 *ret_flags,
20 OM_uint32 * time_rec, gss_cred_id_t *delegated_cred_handle);
21
24 The parameter descriptions for gss_accept_sec_context() follow:
25 minor_status
27 The status code returned by the underlying mechanism.
29 context_handle
32 The context handle to return to the initiator. This should be set
34 to GSS_C_NO_CONTEXT before the loop begins.
35 acceptor_cred_handle
38 The handle for the credentials acquired by the acceptor, typically
40 through gss_acquire_cred(). It may be initialized to GSS_C_NO_CRE‐
41 DENTIAL to indicate a default credential to use. If no default cre‐
42 dential is defined, the function returns GSS_C_NO_CRED.
43 input_token_buffer
46 Token received from the context initiative.
48 input_chan_bindings
51 Optional application-specified bindings. Allows application to
53 securely bind channel identification information to the security
54 context. Set to GSS_C_NO_CHANNEL_BINDINGS if you do not want to use
55 channel bindings.
56 src_name
59 The authenticated name of the context initiator. After use, this
61 name should be deallocated by passing it to gss_release_name(). See
62 gss_release_name(3GSS). If not required, specify NULL.
63 mech_type
66 The security mechanism used. Set to NULL if it does not matter
68 which mechanism is used.
69 output_token
72 The token to send to the acceptor. Initialize it to GSS_C_NO_BUFFER
74 before the function is called (or its length field set to zero). If
75 the length is zero, no token need be sent.
76 ret_flags
79 Contains various independent flags, each of which indicates that
81 the context supports a specific service option. If not needed,
82 specify NULL. Test the returned bit-mask ret_flags value against
83 its symbolic name to determine if the given option is supported by
84 the context. ret_flags may contain one of the following values:
85 GSS_C_DELEG_FLAG
87 If true, delegated credentials are available by means of the
89 delegated_cred_handle parameter. If false, no credentials were
90 delegated.
91 GSS_C_MUTUAL_FLAG
94 If true, a remote peer asked for mutual authentication. If
96 false, no remote peer asked for mutual authentication.
97 GSS_C_REPLAY_FLAG
100 If true, replay of protected messages will be detected. If
102 false, replayed messages will not be detected.
103 GSS_C_SEQUENCE_FLAG
106 If true, out of sequence protected messages will be detected.
108 If false, they will not be detected.
109 GSS_C_CONF_FLAG
112 If true, confidentiality service may be invoked by calling the
114 gss_wrap() routine. If false, no confidentiality service is
115 available by means of gss_wrap(). gss_wrap() will provide mes‐
116 sage encapsulation, data-origin authentication and integrity
117 services only.
118 GSS_C_INTEG_FLAG
121 If true, integrity service may be invoked by calling either the
123 gss_get_mic(3GSS) or the gss_wrap(3GSS) routine. If false, per-
124 message integrity service is not available.
125 GSS_C_ANON_FLAG
128 If true, the initiator does not wish to be authenticated. The
130 src_name parameter, if requested, contains an anonymous inter‐
131 nal name. If false, the initiator has been authenticated nor‐
132 mally.
133 GSS_C_PROT_READY_FLAG
136 If true, the protection services specified by the states of
138 GSS_C_CONF_FLAG and GSS_C_INTEG_FLAG are available if the
139 accompanying major status return value is either GSS_S_COMPLETE
140 or GSS_S_CONTINUE_NEEDED. If false, the protection services are
141 available only if the accompanying major status return value is
142 GSS_S_COMPLETE.
143 GSS_C_TRANS_FLAG
146 If true, the resultant security context may be transferred to
148 other processes by means of a call to gss_export_sec_con‐
149 text(3GSS). If false, the security context cannot be trans‐
150 ferred.
151 time_rec
155 The number of sections for which the context will remain value
157 Specify NULL if not required.
158 delegated_cred_handle
161 The credential value for credentials received from the context's
163 initiator. It is valid only if the initiator has requested that the
164 acceptor act as a proxy: that is, if the ret_flag argument resolves
165 to GSS_C_DELEG_FLAG.
166
169 The gss_accept_sec_context() function allows a remotely initiated secu‐
170 rity context between the application and a remote peer to be estab‐
171 lished. The routine may return an output_token, which should be trans‐
172 ferred to the peer application, where the peer application will present
173 it to gss_init_sec_context(). See gss_init_sec_context(3GSS). If no
174 token need be sent, gss_accept_sec_context() will indicate this by set‐
175 ting the length field of the output_token argument to zero. To complete
176 the context establishment, one or more reply tokens may be required
177 from the peer application; if so, gss_accept_sec_context() will return
178 a status flag of GSS_S_CONTINUE_NEEDED, in which case it should be
179 called again when the reply token is received from the peer applica‐
180 tion, passing the token to gss_accept_sec_context() by means of the
181 input_token parameters.
182 Portable applications should be constructed to use the token length and
185 return status to determine whether to send or to wait for a token.
186 Whenever gss_accept_sec_context() returns a major status that includes
189 the value GSS_S_CONTINUE_NEEDED, the context is not fully established,
190 and the following restrictions apply to the output parameters:
191 o The value returned by means of the time_rec parameter is
193 undefined.
194 o Unless the accompanying ret_flags parameter contains the bit
196 GSS_C_PROT_READY_FLAG, which indicates that per-message ser‐
197 vices may be applied in advance of a successful completion
198 status, the value returned by the mech_type parameter may be
199 undefined until gss_accept_sec_context() returns a major
200 status value of GSS_S_COMPLETE.
201 The values of the GSS_C_DELEG_FLAG, GSS_C_MUTUAL_FLAG,
204 GSS_C_REPLAY_FLAG, GSS_C_SEQUENCE_FLAG, GSS_C_CONF_FLAG,
205 GSS_C_INTEG_FLAG and GSS_C_ANON_FLAG bits returned by means of the
206 ret_flags parameter are values that would be valid if context estab‐
207 lishment were to succeed.
208 The values of the GSS_C_PROT_READY_FLAG and GSS_C_TRANS_FLAG bits
211 within ret_flags indicate the actual state at the time
212 gss_accept_sec_context() returns, whether or not the context is fully
213 established. However, applications should not rely on this behavior, as
214 GSS_C_PROT_READY_FLAG was not defined in Version 1 of the GSS-API.
215 Instead, applications should be prepared to use per-message services
216 after a successful context establishment, based upon the
217 GSS_C_INTEG_FLAG and GSS_C_CONF_FLAG values.
218 All other bits within the ret_flags argument are set to zero.
221 While gss_accept_sec_context() returns GSS_S_CONTINUE_NEEDED, the val‐
224 ues returned by means of the the ret_flags argument indicate the ser‐
225 vices available from the established context. If the initial call of
226 gss_accept_sec_context() fails, no context object is created, and the
227 value of the context_handle parameter is set to GSS_C_NO_CONTEXT. In
228 the event of a failure on a subsequent call, the security context and
229 the context_handle parameter are left untouched for the application to
230 delete using gss_delete_sec_context(3GSS). During context establish‐
231 ment, the informational status bits GSS_S_OLD_TOKEN and GSS_S_DUPLI‐
232 CATE_TOKEN indicate fatal errors; GSS-API mechanisms always return them
233 in association with a routine error of GSS_S_FAILURE. This pairing
234 requirement did not exist in version 1 of the GSS-API specification, so
235 applications that wish to run over version 1 implementations must spe‐
236 cial-case these codes.
237
239 gss_accept_sec_context() may return the following status codes:
240 GSS_S_COMPLETE Successful completion.
242 GSS_S_CONTINUE_NEEDED A token from the peer application is
245 required to complete the context, and
246 that gss_accept_sec_context() must be
247 called again with that token.
248 GSS_S_DEFECTIVE_TOKEN Consistency checks performed on the
251 input_token failed.
252 GSS_S_DEFECTIVE_CREDENTIAL Consistency checks performed on the cre‐
255 dential failed.
256 GSS_S_NO_CRED The supplied credentials were not valid
259 for context acceptance, or the credential
260 handle did not reference any credentials.
261 GSS_S_CREDENTIALS_EXPIRED The referenced credentials have expired.
264 GSS_S_BAD_BINDINGS The input_token contains different chan‐
267 nel bindings than those specified by
268 means of the input_chan_bindings parame‐
269 ter.
270 GSS_S_NO_CONTEXT The supplied context handle did not refer
273 to a valid context.
274 GSS_S_BAD_SIG The input_token contains an invalid MIC.
277 GSS_S_OLD_TOKEN The input_token was too old. This is a
280 fatal error while establishing context.
281 GSS_S_DUPLICATE_TOKEN The input_token is valid, but it is
284 duplicate of a token already processed.
285 This is a fatal error while establishing
286 context.
287 GSS_S_BAD_MECH The token received specified a mechanism
290 that is not supported by the implementa‐
291 tion or the provided credential.
292 GSS_S_FAILURE The underlying mechanism detected an
295 error for which no specific GSS status
296 code is defined. The mechanism-specific
297 status code reported by means of the
298 minor_status parameter details the error
299 condition.
300
303 Example 1 Invoking gss_accept_sec_context() Within a Loop
304 A typical portable caller should always invoke gss_accept_sec_context()
307 within a loop:
308 gss_ctx_id_t context_hdl = GSS_C_NO_CONTEXT;
311 do {
313 receive_token_from_peer(input_token);
314 maj_stat = gss_accept_sec_context(&min_stat,
315 &context_hdl,
316 cred_hdl,
317 input_token,
318 input_bindings,
319 &client_name,
320 &mech_type,
321 output_token,
322 &ret_flags,
323 &time_rec,
324 &deleg_cred);
325 if (GSS_ERROR(maj_stat)) {
326 report_error(maj_stat, min_stat);
327 };
328 if (output_token->length != 0) {
329 send_token_to_peer(output_token);
330 gss_release_buffer(&min_stat, output_token);
331 };
332 if (GSS_ERROR(maj_stat)) {
333 if (context_hdl != GSS_C_NO_CONTEXT)
334 gss_delete_sec_context(&min_stat,
335 &context_hdl,
336 GSS_C_NO_BUFFER);
337 break;
338 };
339 } while (maj_stat & GSS_S_CONTINUE_NEEDED);
340 /* Check client_name authorization */
342 ...
343 (void) gss_release_name(&min_stat, &client_name);
345 /* Use and/or store delegated credential */
347 ...
348 (void) gss_release_cred(&min_stat, &deleg_cred);
350
353 See attributes(5) for descriptions of the following attributes:
354 ┌─────────────────────────────┬─────────────────────────────┐
359 │ ATTRIBUTE TYPE │ ATTRIBUTE VALUE │
360 ├─────────────────────────────┼─────────────────────────────┤
361 │MT-Level │Safe │
362 └─────────────────────────────┴─────────────────────────────┘
363
365 gss_delete_sec_context(3GSS), gss_export_sec_context(3GSS),
366 gss_get_mic(3GSS), gss_init_sec_context(3GSS), gss_release_cred(3GSS),
367 gss_release_name(3GSS), gss_store_cred(3GSS), gss_wrap(3GSS),
368 attributes(5)
369 Solaris Security for Developers Guide
372SunOS 5.11 22 May 2006 gss_accept_sec_context(3GSS)