7 Network Working Group J. Linn
8 Request for Comments: 2743 RSA Laboratories
9 Obsoletes: 2078 January 2000
10 Category: Standards Track
13 Generic Security Service Application Program Interface
19 This document specifies an Internet standards track protocol for the
20 Internet community, and requests discussion and suggestions for
21 improvements. Please refer to the current edition of the "Internet
22 Official Protocol Standards" (STD 1) for the standardization state
23 and status of this protocol. Distribution of this memo is unlimited.
27 Copyright (C) The Internet Society (2000). All Rights Reserved.
31 The Generic Security Service Application Program Interface (GSS-API),
32 Version 2, as defined in [RFC-2078], provides security services to
33 callers in a generic fashion, supportable with a range of underlying
34 mechanisms and technologies and hence allowing source-level
35 portability of applications to different environments. This
36 specification defines GSS-API services and primitives at a level
37 independent of underlying mechanism and programming language
38 environment, and is to be complemented by other, related
41 documents defining specific parameter bindings for particular
44 documents defining token formats, protocols, and procedures to be
45 implemented in order to realize GSS-API services atop particular
48 This memo obsoletes [RFC-2078], making specific, incremental changes
49 in response to implementation experience and liaison requests. It is
50 intended, therefore, that this memo or a successor version thereto
51 will become the basis for subsequent progression of the GSS-API
52 specification on the standards track.
58 Linn Standards Track [Page 1]
60 RFC 2743 GSS-API January 2000
65 1: GSS-API Characteristics and Concepts . . . . . . . . . . . . 4
66 1.1: GSS-API Constructs . . . . . . . . . . . . . . . . . . . . 6
67 1.1.1: Credentials . . . . . . . . . . . . . . . . . . . . . . 6
68 1.1.1.1: Credential Constructs and Concepts . . . . . . . . . . 6
69 1.1.1.2: Credential Management . . . . . . . . . . . . . . . . 7
70 1.1.1.3: Default Credential Resolution . . . . . . . . . . . . 8
71 1.1.2: Tokens . . . . . . . . . . . . . . . . . . . . . . . . . 9
72 1.1.3: Security Contexts . . . . . . . . . . . . . . . . . . . 11
73 1.1.4: Mechanism Types . . . . . . . . . . . . . . . . . . . . 12
74 1.1.5: Naming . . . . . . . . . . . . . . . . . . . . . . . . 13
75 1.1.6: Channel Bindings . . . . . . . . . . . . . . . . . . . 16
76 1.2: GSS-API Features and Issues . . . . . . . . . . . . . . . 17
77 1.2.1: Status Reporting and Optional Service Support . . . . 17
78 1.2.1.1: Status Reporting . . . . . . . . . . . . . . . . . . . 17
79 1.2.1.2: Optional Service Support . . . . . . . . . . . . . . . 19
80 1.2.2: Per-Message Security Service Availability . . . . . . . 20
81 1.2.3: Per-Message Replay Detection and Sequencing . . . . . . 21
82 1.2.4: Quality of Protection . . . . . . . . . . . . . . . . . 24
83 1.2.5: Anonymity Support . . . . . . . . . . . . . . . . . . . 25
84 1.2.6: Initialization . . . . . . . . . . . . . . . . . . . . . 25
85 1.2.7: Per-Message Protection During Context Establishment . . 26
86 1.2.8: Implementation Robustness . . . . . . . . . . . . . . . 27
87 1.2.9: Delegation . . . . . . . . . . . . . . . . . . . . . . . 28
88 1.2.10: Interprocess Context Transfer . . . . . . . . . . . . . 28
89 2: Interface Descriptions . . . . . . . . . . . . . . . . . . 29
90 2.1: Credential management calls . . . . . . . . . . . . . . . 31
91 2.1.1: GSS_Acquire_cred call . . . . . . . . . . . . . . . . . 31
92 2.1.2: GSS_Release_cred call . . . . . . . . . . . . . . . . . 34
93 2.1.3: GSS_Inquire_cred call . . . . . . . . . . . . . . . . . 35
94 2.1.4: GSS_Add_cred call . . . . . . . . . . . . . . . . . . . 37
95 2.1.5: GSS_Inquire_cred_by_mech call . . . . . . . . . . . . . 40
96 2.2: Context-level calls . . . . . . . . . . . . . . . . . . . 41
97 2.2.1: GSS_Init_sec_context call . . . . . . . . . . . . . . . 42
98 2.2.2: GSS_Accept_sec_context call . . . . . . . . . . . . . . 49
99 2.2.3: GSS_Delete_sec_context call . . . . . . . . . . . . . . 53
100 2.2.4: GSS_Process_context_token call . . . . . . . . . . . . 54
101 2.2.5: GSS_Context_time call . . . . . . . . . . . . . . . . . 55
102 2.2.6: GSS_Inquire_context call . . . . . . . . . . . . . . . 56
103 2.2.7: GSS_Wrap_size_limit call . . . . . . . . . . . . . . . 57
104 2.2.8: GSS_Export_sec_context call . . . . . . . . . . . . . . 59
105 2.2.9: GSS_Import_sec_context call . . . . . . . . . . . . . . 61
106 2.3: Per-message calls . . . . . . . . . . . . . . . . . . . . 62
107 2.3.1: GSS_GetMIC call . . . . . . . . . . . . . . . . . . . . 63
108 2.3.2: GSS_VerifyMIC call . . . . . . . . . . . . . . . . . . 64
109 2.3.3: GSS_Wrap call . . . . . . . . . . . . . . . . . . . . . 65
110 2.3.4: GSS_Unwrap call . . . . . . . . . . . . . . . . . . . . 66
114 Linn Standards Track [Page 2]
116 RFC 2743 GSS-API January 2000
119 2.4: Support calls . . . . . . . . . . . . . . . . . . . . . . 68
120 2.4.1: GSS_Display_status call . . . . . . . . . . . . . . . . 68
121 2.4.2: GSS_Indicate_mechs call . . . . . . . . . . . . . . . . 69
122 2.4.3: GSS_Compare_name call . . . . . . . . . . . . . . . . . 70
123 2.4.4: GSS_Display_name call . . . . . . . . . . . . . . . . . 71
124 2.4.5: GSS_Import_name call . . . . . . . . . . . . . . . . . 72
125 2.4.6: GSS_Release_name call . . . . . . . . . . . . . . . . . 73
126 2.4.7: GSS_Release_buffer call . . . . . . . . . . . . . . . . 74
127 2.4.8: GSS_Release_OID_set call . . . . . . . . . . . . . . . 74
128 2.4.9: GSS_Create_empty_OID_set call . . . . . . . . . . . . . 75
129 2.4.10: GSS_Add_OID_set_member call . . . . . . . . . . . . . . 76
130 2.4.11: GSS_Test_OID_set_member call . . . . . . . . . . . . . 76
131 2.4.12: GSS_Inquire_names_for_mech call . . . . . . . . . . . . 77
132 2.4.13: GSS_Inquire_mechs_for_name call . . . . . . . . . . . . 77
133 2.4.14: GSS_Canonicalize_name call . . . . . . . . . . . . . . 78
134 2.4.15: GSS_Export_name call . . . . . . . . . . . . . . . . . 79
135 2.4.16: GSS_Duplicate_name call . . . . . . . . . . . . . . . . 80
136 3: Data Structure Definitions for GSS-V2 Usage . . . . . . . . 81
137 3.1: Mechanism-Independent Token Format . . . . . . . . . . . . 81
138 3.2: Mechanism-Independent Exported Name Object Format . . . . 84
139 4: Name Type Definitions . . . . . . . . . . . . . . . . . . . 85
140 4.1: Host-Based Service Name Form . . . . . . . . . . . . . . . 85
141 4.2: User Name Form . . . . . . . . . . . . . . . . . . . . . . 86
142 4.3: Machine UID Form . . . . . . . . . . . . . . . . . . . . . 87
143 4.4: String UID Form . . . . . . . . . . . . . . . . . . . . . 87
144 4.5: Anonymous Nametype . . . . . . . . . . . . . . . . . . . . 87
145 4.6: GSS_C_NO_OID . . . . . . . . . . . . . . . . . . . . . . . 88
146 4.7: Exported Name Object . . . . . . . . . . . . . . . . . . . 88
147 4.8: GSS_C_NO_NAME . . . . . . . . . . . . . . . . . . . . . . 88
148 5: Mechanism-Specific Example Scenarios . . . . . . . . . . . 88
149 5.1: Kerberos V5, single-TGT . . . . . . . . . . . . . . . . . 89
150 5.2: Kerberos V5, double-TGT . . . . . . . . . . . . . . . . . 89
151 5.3: X.509 Authentication Framework . . . . . . . . . . . . . 90
152 6: Security Considerations . . . . . . . . . . . . . . . . . . 91
153 7: Related Activities . . . . . . . . . . . . . . . . . . . . 92
154 8: Referenced Documents . . . . . . . . . . . . . . . . . . . 93
155 Appendix A: Mechanism Design Constraints . . . . . . . . . . . 94
156 Appendix B: Compatibility with GSS-V1 . . . . . . . . . . . . . 94
157 Appendix C: Changes Relative to RFC-2078 . . . . . . . . . . . 96
158 Author's Address . . . . . . . . . . . . . . . . . . . . . . .100
159 Full Copyright Statement . . . . . . . . . . . . . . . . . . .101
170 Linn Standards Track [Page 3]
172 RFC 2743 GSS-API January 2000
175 1: GSS-API Characteristics and Concepts
177 GSS-API operates in the following paradigm. A typical GSS-API caller
178 is itself a communications protocol, calling on GSS-API in order to
179 protect its communications with authentication, integrity, and/or
180 confidentiality security services. A GSS-API caller accepts tokens
181 provided to it by its local GSS-API implementation and transfers the
182 tokens to a peer on a remote system; that peer passes the received
183 tokens to its local GSS-API implementation for processing. The
184 security services available through GSS-API in this fashion are
185 implementable (and have been implemented) over a range of underlying
186 mechanisms based on secret-key and public-key cryptographic
189 The GSS-API separates the operations of initializing a security
190 context between peers, achieving peer entity authentication
191 (GSS_Init_sec_context() and GSS_Accept_sec_context() calls), from the
192 operations of providing per-message data origin authentication and
193 data integrity protection (GSS_GetMIC() and GSS_VerifyMIC() calls)
194 for messages subsequently transferred in conjunction with that
195 context. (The definition for the peer entity authentication service,
196 and other definitions used in this document, corresponds to that
197 provided in [ISO-7498-2].) When establishing a security context, the
198 GSS-API enables a context initiator to optionally permit its
199 credentials to be delegated, meaning that the context acceptor may
200 initiate further security contexts on behalf of the initiating
201 caller. Per-message GSS_Wrap() and GSS_Unwrap() calls provide the
202 data origin authentication and data integrity services which
203 GSS_GetMIC() and GSS_VerifyMIC() offer, and also support selection of
204 confidentiality services as a caller option. Additional calls provide
205 supportive functions to the GSS-API's users.
207 The following paragraphs provide an example illustrating the
208 dataflows involved in use of the GSS-API by a client and server in a
209 mechanism-independent fashion, establishing a security context and
210 transferring a protected message. The example assumes that credential
211 acquisition has already been completed. The example also assumes
212 that the underlying authentication technology is capable of
213 authenticating a client to a server using elements carried within a
214 single token, and of authenticating the server to the client (mutual
215 authentication) with a single returned token; this assumption holds
216 for some presently-documented CAT mechanisms but is not necessarily
217 true for other cryptographic technologies and associated protocols.
219 The client calls GSS_Init_sec_context() to establish a security
220 context to the server identified by targ_name, and elects to set the
221 mutual_req_flag so that mutual authentication is performed in the
222 course of context establishment. GSS_Init_sec_context() returns an
226 Linn Standards Track [Page 4]
228 RFC 2743 GSS-API January 2000
231 output_token to be passed to the server, and indicates
232 GSS_S_CONTINUE_NEEDED status pending completion of the mutual
233 authentication sequence. Had mutual_req_flag not been set, the
234 initial call to GSS_Init_sec_context() would have returned
235 GSS_S_COMPLETE status. The client sends the output_token to the
238 The server passes the received token as the input_token parameter to
239 GSS_Accept_sec_context(). GSS_Accept_sec_context indicates
240 GSS_S_COMPLETE status, provides the client's authenticated identity
241 in the src_name result, and provides an output_token to be passed to
242 the client. The server sends the output_token to the client.
244 The client passes the received token as the input_token parameter to
245 a successor call to GSS_Init_sec_context(), which processes data
246 included in the token in order to achieve mutual authentication from
247 the client's viewpoint. This call to GSS_Init_sec_context() returns
248 GSS_S_COMPLETE status, indicating successful mutual authentication
249 and the completion of context establishment for this example.
251 The client generates a data message and passes it to GSS_Wrap().
252 GSS_Wrap() performs data origin authentication, data integrity, and
253 (optionally) confidentiality processing on the message and
254 encapsulates the result into output_message, indicating
255 GSS_S_COMPLETE status. The client sends the output_message to the
258 The server passes the received message to GSS_Unwrap(). GSS_Unwrap()
259 inverts the encapsulation performed by GSS_Wrap(), deciphers the
260 message if the optional confidentiality feature was applied, and
261 validates the data origin authentication and data integrity checking
262 quantities. GSS_Unwrap() indicates successful validation by returning
263 GSS_S_COMPLETE status along with the resultant output_message.
265 For purposes of this example, we assume that the server knows by
266 out-of-band means that this context will have no further use after
267 one protected message is transferred from client to server. Given
268 this premise, the server now calls GSS_Delete_sec_context() to flush
269 context-level information. Optionally, the server-side application
270 may provide a token buffer to GSS_Delete_sec_context(), to receive a
271 context_token to be transferred to the client in order to request
272 that client-side context-level information be deleted.
274 If a context_token is transferred, the client passes the
275 context_token to GSS_Process_context_token(), which returns
276 GSS_S_COMPLETE status after deleting context-level information at the
282 Linn Standards Track [Page 5]
284 RFC 2743 GSS-API January 2000
287 The GSS-API design assumes and addresses several basic goals,
290 Mechanism independence: The GSS-API defines an interface to
291 cryptographically implemented strong authentication and other
292 security services at a generic level which is independent of
293 particular underlying mechanisms. For example, GSS-API-provided
294 services have been implemented using secret-key technologies
295 (e.g., Kerberos, per [RFC-1964]) and with public-key approaches
296 (e.g., SPKM, per [RFC-2025]).
298 Protocol environment independence: The GSS-API is independent of
299 the communications protocol suites with which it is employed,
300 permitting use in a broad range of protocol environments. In
301 appropriate environments, an intermediate implementation "veneer"
302 which is oriented to a particular communication protocol may be
303 interposed between applications which call that protocol and the
304 GSS-API (e.g., as defined in [RFC-2203] for Open Network Computing
305 Remote Procedure Call (RPC)), thereby invoking GSS-API facilities
306 in conjunction with that protocol's communications invocations.
308 Protocol association independence: The GSS-API's security context
309 construct is independent of communications protocol association
310 constructs. This characteristic allows a single GSS-API
311 implementation to be utilized by a variety of invoking protocol
312 modules on behalf of those modules' calling applications. GSS-API
313 services can also be invoked directly by applications, wholly
314 independent of protocol associations.
316 Suitability to a range of implementation placements: GSS-API
317 clients are not constrained to reside within any Trusted Computing
318 Base (TCB) perimeter defined on a system where the GSS-API is
319 implemented; security services are specified in a manner suitable
320 to both intra-TCB and extra-TCB callers.
322 1.1: GSS-API Constructs
324 This section describes the basic elements comprising the GSS-API.
328 1.1.1.1: Credential Constructs and Concepts
330 Credentials provide the prerequisites which permit GSS-API peers to
331 establish security contexts with each other. A caller may designate
332 that the credential elements which are to be applied for context
333 initiation or acceptance be selected by default. Alternately, those
334 GSS-API callers which need to make explicit selection of particular
338 Linn Standards Track [Page 6]
340 RFC 2743 GSS-API January 2000
343 credentials structures may make references to those credentials
344 through GSS-API-provided credential handles ("cred_handles"). In all
345 cases, callers' credential references are indirect, mediated by GSS-
346 API implementations and not requiring callers to access the selected
349 A single credential structure may be used to initiate outbound
350 contexts and to accept inbound contexts. Callers needing to operate
351 in only one of these modes may designate this fact when credentials
352 are acquired for use, allowing underlying mechanisms to optimize
353 their processing and storage requirements. The credential elements
354 defined by a particular mechanism may contain multiple cryptographic
355 keys, e.g., to enable authentication and message encryption to be
356 performed with different algorithms.
358 A GSS-API credential structure may contain multiple credential
359 elements, each containing mechanism-specific information for a
360 particular underlying mechanism (mech_type), but the set of elements
361 within a given credential structure represent a common entity. A
362 credential structure's contents will vary depending on the set of
363 mech_types supported by a particular GSS-API implementation. Each
364 credential element identifies the data needed by its mechanism in
365 order to establish contexts on behalf of a particular principal, and
366 may contain separate credential references for use in context
367 initiation and context acceptance. Multiple credential elements
368 within a given credential having overlapping combinations of
369 mechanism, usage mode, and validity period are not permitted.
371 Commonly, a single mech_type will be used for all security contexts
372 established by a particular initiator to a particular target. A major
373 motivation for supporting credential sets representing multiple
374 mech_types is to allow initiators on systems which are equipped to
375 handle multiple types to initiate contexts to targets on other
376 systems which can accommodate only a subset of the set supported at
377 the initiator's system.
379 1.1.1.2: Credential Management
381 It is the responsibility of underlying system-specific mechanisms and
382 OS functions below the GSS-API to ensure that the ability to acquire
383 and use credentials associated with a given identity is constrained
384 to appropriate processes within a system. This responsibility should
385 be taken seriously by implementors, as the ability for an entity to
386 utilize a principal's credentials is equivalent to the entity's
387 ability to successfully assert that principal's identity.
394 Linn Standards Track [Page 7]
396 RFC 2743 GSS-API January 2000
399 Once a set of GSS-API credentials is established, the transferability
400 of that credentials set to other processes or analogous constructs
401 within a system is a local matter, not defined by the GSS-API. An
402 example local policy would be one in which any credentials received
403 as a result of login to a given user account, or of delegation of
404 rights to that account, are accessible by, or transferable to,
405 processes running under that account.
407 The credential establishment process (particularly when performed on
408 behalf of users rather than server processes) is likely to require
409 access to passwords or other quantities which should be protected
410 locally and exposed for the shortest time possible. As a result, it
411 will often be appropriate for preliminary credential establishment to
412 be performed through local means at user login time, with the
413 result(s) cached for subsequent reference. These preliminary
414 credentials would be set aside (in a system-specific fashion) for
415 subsequent use, either:
417 to be accessed by an invocation of the GSS-API GSS_Acquire_cred()
418 call, returning an explicit handle to reference that credential
420 to comprise default credential elements to be installed, and to be
421 used when default credential behavior is requested on behalf of a
424 1.1.1.3: Default Credential Resolution
426 The GSS_Init_sec_context() and GSS_Accept_sec_context() routines
427 allow the value GSS_C_NO_CREDENTIAL to be specified as their
428 credential handle parameter. This special credential handle
429 indicates a desire by the application to act as a default principal.
430 In support of application portability, support for the default
431 resolution behavior described below for initiator credentials
432 (GSS_Init_sec_context() usage) is mandated; support for the default
433 resolution behavior described below for acceptor credentials
434 (GSS_Accept_sec_context() usage) is recommended. If default
435 credential resolution fails, GSS_S_NO_CRED status is to be returned.
437 GSS_Init_sec_context:
439 (i) If there is only a single principal capable of initiating
440 security contexts that the application is authorized to act on
441 behalf of, then that principal shall be used, otherwise
450 Linn Standards Track [Page 8]
452 RFC 2743 GSS-API January 2000
455 (ii) If the platform maintains a concept of a default network-
456 identity, and if the application is authorized to act on behalf
457 of that identity for the purpose of initiating security
458 contexts, then the principal corresponding to that identity
459 shall be used, otherwise
461 (iii) If the platform maintains a concept of a default local
462 identity, and provides a means to map local identities into
463 network-identities, and if the application is authorized to act
464 on behalf of the network-identity image of the default local
465 identity for the purpose of initiating security contexts, then
466 the principal corresponding to that identity shall be used,
469 (iv) A user-configurable default identity should be used.
471 GSS_Accept_sec_context:
473 (i) If there is only a single authorized principal identity
474 capable of accepting security contexts, then that principal
475 shall be used, otherwise
477 (ii) If the mechanism can determine the identity of the target
478 principal by examining the context-establishment token, and if
479 the accepting application is authorized to act as that
480 principal for the purpose of accepting security contexts, then
481 that principal identity shall be used, otherwise
483 (iii) If the mechanism supports context acceptance by any
484 principal, and mutual authentication was not requested, any
485 principal that the application is authorized to accept security
486 contexts under may be used, otherwise
488 (iv) A user-configurable default identity shall be used.
490 The purpose of the above rules is to allow security contexts to be
491 established by both initiator and acceptor using the default behavior
492 wherever possible. Applications requesting default behavior are
493 likely to be more portable across mechanisms and platforms than those
494 that use GSS_Acquire_cred() to request a specific identity.
498 Tokens are data elements transferred between GSS-API callers, and are
499 divided into two classes. Context-level tokens are exchanged in order
500 to establish and manage a security context between peers. Per-message
501 tokens relate to an established context and are exchanged to provide
506 Linn Standards Track [Page 9]
508 RFC 2743 GSS-API January 2000
511 protective security services (i.e., data origin authentication,
512 integrity, and optional confidentiality) for corresponding data
515 The first context-level token obtained from GSS_Init_sec_context() is
516 required to indicate at its very beginning a globally-interpretable
517 mechanism identifier, i.e., an Object Identifier (OID) of the
518 security mechanism. The remaining part of this token as well as the
519 whole content of all other tokens are specific to the particular
520 underlying mechanism used to support the GSS-API. Section 3.1 of this
521 document provides, for designers of GSS-API mechanisms, the
522 description of the header of the first context-level token which is
523 then followed by mechanism-specific information.
525 Tokens' contents are opaque from the viewpoint of GSS-API callers.
526 They are generated within the GSS-API implementation at an end
527 system, provided to a GSS-API caller to be transferred to the peer
528 GSS-API caller at a remote end system, and processed by the GSS-API
529 implementation at that remote end system.
531 Context-level tokens may be output by GSS-API calls (and should be
532 transferred to GSS-API peers) whether or not the calls' status
533 indicators indicate successful completion. Per-message tokens, in
534 contrast, are to be returned only upon successful completion of per-
535 message calls. Zero-length tokens are never returned by GSS routines
536 for transfer to a peer. Token transfer may take place in an in-band
537 manner, integrated into the same protocol stream used by the GSS-API
538 callers for other data transfers, or in an out-of-band manner across
539 a logically separate channel.
541 Different GSS-API tokens are used for different purposes (e.g.,
542 context initiation, context acceptance, protected message data on an
543 established context), and it is the responsibility of a GSS-API
544 caller receiving tokens to distinguish their types, associate them
545 with corresponding security contexts, and pass them to appropriate
546 GSS-API processing routines. Depending on the caller protocol
547 environment, this distinction may be accomplished in several ways.
549 The following examples illustrate means through which tokens' types
550 may be distinguished:
552 - implicit tagging based on state information (e.g., all tokens on
553 a new association are considered to be context establishment
554 tokens until context establishment is completed, at which point
555 all tokens are considered to be wrapped data objects for that
562 Linn Standards Track [Page 10]
564 RFC 2743 GSS-API January 2000
567 - explicit tagging at the caller protocol level,
569 - a hybrid of these approaches.
571 Commonly, the encapsulated data within a token includes internal
572 mechanism-specific tagging information, enabling mechanism-level
573 processing modules to distinguish tokens used within the mechanism
574 for different purposes. Such internal mechanism-level tagging is
575 recommended to mechanism designers, and enables mechanisms to
576 determine whether a caller has passed a particular token for
577 processing by an inappropriate GSS-API routine.
579 Development of GSS-API mechanisms based on a particular underlying
580 cryptographic technique and protocol (i.e., conformant to a specific
581 GSS-API mechanism definition) does not necessarily imply that GSS-API
582 callers using that GSS-API mechanism will be able to interoperate
583 with peers invoking the same technique and protocol outside the GSS-
584 API paradigm, or with peers implementing a different GSS-API
585 mechanism based on the same underlying technology. The format of
586 GSS-API tokens defined in conjunction with a particular mechanism,
587 and the techniques used to integrate those tokens into callers'
588 protocols, may not be interoperable with the tokens used by non-GSS-
589 API callers of the same underlying technique.
591 1.1.3: Security Contexts
593 Security contexts are established between peers, using credentials
594 established locally in conjunction with each peer or received by
595 peers via delegation. Multiple contexts may exist simultaneously
596 between a pair of peers, using the same or different sets of
597 credentials. Coexistence of multiple contexts using different
598 credentials allows graceful rollover when credentials expire.
599 Distinction among multiple contexts based on the same credentials
600 serves applications by distinguishing different message streams in a
603 The GSS-API is independent of underlying protocols and addressing
604 structure, and depends on its callers to transport GSS-API-provided
605 data elements. As a result of these factors, it is a caller
606 responsibility to parse communicated messages, separating GSS-API-
607 related data elements from caller-provided data. The GSS-API is
608 independent of connection vs. connectionless orientation of the
609 underlying communications service.
611 No correlation between security context and communications protocol
612 association is dictated. (The optional channel binding facility,
613 discussed in Section 1.1.6 of this document, represents an
614 intentional exception to this rule, supporting additional protection
618 Linn Standards Track [Page 11]
620 RFC 2743 GSS-API January 2000
623 features within GSS-API supporting mechanisms.) This separation
624 allows the GSS-API to be used in a wide range of communications
625 environments, and also simplifies the calling sequences of the
626 individual calls. In many cases (depending on underlying security
627 protocol, associated mechanism, and availability of cached
628 information), the state information required for context setup can be
629 sent concurrently with initial signed user data, without interposing
630 additional message exchanges. Messages may be protected and
631 transferred in both directions on an established GSS-API security
632 context concurrently; protection of messages in one direction does
633 not interfere with protection of messages in the reverse direction.
635 GSS-API implementations are expected to retain inquirable context
636 data on a context until the context is released by a caller, even
637 after the context has expired, although underlying cryptographic data
638 elements may be deleted after expiration in order to limit their
641 1.1.4: Mechanism Types
643 In order to successfully establish a security context with a target
644 peer, it is necessary to identify an appropriate underlying mechanism
645 type (mech_type) which both initiator and target peers support. The
646 definition of a mechanism embodies not only the use of a particular
647 cryptographic technology (or a hybrid or choice among alternative
648 cryptographic technologies), but also definition of the syntax and
649 semantics of data element exchanges which that mechanism will employ
650 in order to support security services.
652 It is recommended that callers initiating contexts specify the
653 "default" mech_type value, allowing system-specific functions within
654 or invoked by the GSS-API implementation to select the appropriate
655 mech_type, but callers may direct that a particular mech_type be
656 employed when necessary.
658 For GSS-API purposes, the phrase "negotiating mechanism" refers to a
659 mechanism which itself performs negotiation in order to select a
660 concrete mechanism which is shared between peers and is then used for
661 context establishment. Only those mechanisms which are defined in
662 their specifications as negotiating mechanisms are to yield selected
663 mechanisms with different identifier values than the value which is
664 input by a GSS-API caller, except for the case of a caller requesting
665 the "default" mech_type.
667 The means for identifying a shared mech_type to establish a security
668 context with a peer will vary in different environments and
669 circumstances; examples include (but are not limited to):
674 Linn Standards Track [Page 12]
676 RFC 2743 GSS-API January 2000
679 use of a fixed mech_type, defined by configuration, within an
682 syntactic convention on a target-specific basis, through
683 examination of a target's name lookup of a target's name in a
684 naming service or other database in order to identify mech_types
685 supported by that target
687 explicit negotiation between GSS-API callers in advance of
688 security context setup
690 use of a negotiating mechanism
692 When transferred between GSS-API peers, mech_type specifiers (per
693 Section 3 of this document, represented as Object Identifiers (OIDs))
694 serve to qualify the interpretation of associated tokens. (The
695 structure and encoding of Object Identifiers is defined in [ISOIEC-
696 8824] and [ISOIEC-8825].) Use of hierarchically structured OIDs
697 serves to preclude ambiguous interpretation of mech_type specifiers.
698 The OID representing the DASS ([RFC-1507]) MechType, for example, is
699 1.3.12.2.1011.7.5, and that of the Kerberos V5 mechanism ([RFC-
700 1964]), having been advanced to the level of Proposed Standard, is
701 1.2.840.113554.1.2.2.
705 The GSS-API avoids prescribing naming structures, treating the names
706 which are transferred across the interface in order to initiate and
707 accept security contexts as opaque objects. This approach supports
708 the GSS-API's goal of implementability atop a range of underlying
709 security mechanisms, recognizing the fact that different mechanisms
710 process and authenticate names which are presented in different
711 forms. Generalized services offering translation functions among
712 arbitrary sets of naming environments are outside the scope of the
713 GSS-API; availability and use of local conversion functions to
714 translate among the naming formats supported within a given end
715 system is anticipated.
717 Different classes of name representations are used in conjunction
718 with different GSS-API parameters:
720 - Internal form (denoted in this document by INTERNAL NAME),
721 opaque to callers and defined by individual GSS-API
722 implementations. GSS-API implementations supporting multiple
723 namespace types must maintain internal tags to disambiguate the
724 interpretation of particular names. A Mechanism Name (MN) is a
725 special case of INTERNAL NAME, guaranteed to contain elements
730 Linn Standards Track [Page 13]
732 RFC 2743 GSS-API January 2000
735 corresponding to one and only one mechanism; calls which are
736 guaranteed to emit MNs or which require MNs as input are so
737 identified within this specification.
739 - Contiguous string ("flat") form (denoted in this document by
740 OCTET STRING); accompanied by OID tags identifying the namespace
741 to which they correspond. Depending on tag value, flat names may
742 or may not be printable strings for direct acceptance from and
743 presentation to users. Tagging of flat names allows GSS-API
744 callers and underlying GSS-API mechanisms to disambiguate name
745 types and to determine whether an associated name's type is one
746 which they are capable of processing, avoiding aliasing problems
747 which could result from misinterpreting a name of one type as a
748 name of another type.
750 - The GSS-API Exported Name Object, a special case of flat name
751 designated by a reserved OID value, carries a canonicalized form
752 of a name suitable for binary comparisons.
754 In addition to providing means for names to be tagged with types,
755 this specification defines primitives to support a level of naming
756 environment independence for certain calling applications. To provide
757 basic services oriented towards the requirements of callers which
758 need not themselves interpret the internal syntax and semantics of
759 names, GSS-API calls for name comparison (GSS_Compare_name()),
760 human-readable display (GSS_Display_name()), input conversion
761 (GSS_Import_name()), internal name deallocation (GSS_Release_name()),
762 and internal name duplication (GSS_Duplicate_name()) functions are
763 defined. (It is anticipated that these proposed GSS-API calls will be
764 implemented in many end systems based on system-specific name
765 manipulation primitives already extant within those end systems;
766 inclusion within the GSS-API is intended to offer GSS-API callers a
767 portable means to perform specific operations, supportive of
768 authorization and audit requirements, on authenticated names.)
770 GSS_Import_name() implementations can, where appropriate, support
771 more than one printable syntax corresponding to a given namespace
772 (e.g., alternative printable representations for X.500 Distinguished
773 Names), allowing flexibility for their callers to select among
774 alternative representations. GSS_Display_name() implementations
775 output a printable syntax selected as appropriate to their
776 operational environments; this selection is a local matter. Callers
777 desiring portability across alternative printable syntaxes should
778 refrain from implementing comparisons based on printable name forms
779 and should instead use the GSS_Compare_name() call to determine
780 whether or not one internal-format name matches another.
786 Linn Standards Track [Page 14]
788 RFC 2743 GSS-API January 2000
791 When used in large access control lists, the overhead of invoking
792 GSS_Import_name() and GSS_Compare_name() on each name from the ACL
793 may be prohibitive. As an alternative way of supporting this case,
794 GSS-API defines a special form of the contiguous string name which
795 may be compared directly (e.g., with memcmp()). Contiguous names
796 suitable for comparison are generated by the GSS_Export_name()
797 routine, which requires an MN as input. Exported names may be re-
798 imported by the GSS_Import_name() routine, and the resulting internal
799 name will also be an MN. The symbolic constant GSS_C_NT_EXPORT_NAME
800 identifies the "export name" type. Structurally, an exported name
801 object consists of a header containing an OID identifying the
802 mechanism that authenticated the name, and a trailer containing the
803 name itself, where the syntax of the trailer is defined by the
804 individual mechanism specification. The precise format of an
805 exported name is defined in Section 3.2 of this specification.
807 Note that the results obtained by using GSS_Compare_name() will in
808 general be different from those obtained by invoking
809 GSS_Canonicalize_name() and GSS_Export_name(), and then comparing the
810 exported names. The first series of operations determines whether
811 two (unauthenticated) names identify the same principal; the second
812 whether a particular mechanism would authenticate them as the same
813 principal. These two operations will in general give the same
814 results only for MNs.
816 The following diagram illustrates the intended dataflow among name-
817 related GSS-API processing routines.
842 Linn Standards Track [Page 15]
844 RFC 2743 GSS-API January 2000
847 GSS-API library defaults
851 text --------------> internal_name (IN) -----------> display only
852 import_name() / display_name()
856 accept_sec_context() /
859 | / canonicalize_name()
866 V V <---------------------
867 single mechanism import_name() exported name: flat
868 internal_name (MN) binary "blob" usable
869 ----------------------> for access control
872 1.1.6: Channel Bindings
874 The GSS-API accommodates the concept of caller-provided channel
875 binding ("chan_binding") information. Channel bindings are used to
876 strengthen the quality with which peer entity authentication is
877 provided during context establishment, by limiting the scope within
878 which an intercepted context establishment token can be reused by an
879 attacker. Specifically, they enable GSS-API callers to bind the
880 establishment of a security context to relevant characteristics
881 (e.g., addresses, transformed representations of encryption keys) of
882 the underlying communications channel, of protection mechanisms
883 applied to that communications channel, and to application-specific
886 The caller initiating a security context must determine the
887 appropriate channel binding values to provide as input to the
888 GSS_Init_sec_context() call, and consistent values must be provided
889 to GSS_Accept_sec_context() by the context's target, in order for
890 both peers' GSS-API mechanisms to validate that received tokens
891 possess correct channel-related characteristics. Use or non-use of
892 the GSS-API channel binding facility is a caller option. GSS-API
893 mechanisms can operate in an environment where NULL channel bindings
894 are presented; mechanism implementors are encouraged, but not
898 Linn Standards Track [Page 16]
900 RFC 2743 GSS-API January 2000
903 required, to make use of caller-provided channel binding data within
904 their mechanisms. Callers should not assume that underlying
905 mechanisms provide confidentiality protection for channel binding
908 When non-NULL channel bindings are provided by callers, certain
909 mechanisms can offer enhanced security value by interpreting the
910 bindings' content (rather than simply representing those bindings, or
911 integrity check values computed on them, within tokens) and will
912 therefore depend on presentation of specific data in a defined
913 format. To this end, agreements among mechanism implementors are
914 defining conventional interpretations for the contents of channel
915 binding arguments, including address specifiers (with content
916 dependent on communications protocol environment) for context
917 initiators and acceptors. (These conventions are being incorporated
918 in GSS-API mechanism specifications and into the GSS-API C language
919 bindings specification.) In order for GSS-API callers to be portable
920 across multiple mechanisms and achieve the full security
921 functionality which each mechanism can provide, it is strongly
922 recommended that GSS-API callers provide channel bindings consistent
923 with these conventions and those of the networking environment in
926 1.2: GSS-API Features and Issues
928 This section describes aspects of GSS-API operations, of the security
929 services which the GSS-API provides, and provides commentary on
932 1.2.1: Status Reporting and Optional Service Support
934 1.2.1.1: Status Reporting
936 Each GSS-API call provides two status return values. Major_status
937 values provide a mechanism-independent indication of call status
938 (e.g., GSS_S_COMPLETE, GSS_S_FAILURE, GSS_S_CONTINUE_NEEDED),
939 sufficient to drive normal control flow within the caller in a
940 generic fashion. Table 1 summarizes the defined major_status return
941 codes in tabular fashion.
943 Sequencing-related informatory major_status codes
944 (GSS_S_DUPLICATE_TOKEN, GSS_S_OLD_TOKEN, GSS_S_UNSEQ_TOKEN, and
945 GSS_S_GAP_TOKEN) can be indicated in conjunction with either
946 GSS_S_COMPLETE or GSS_S_FAILURE status for GSS-API per-message calls.
947 For context establishment calls, these sequencing-related codes will
948 be indicated only in conjunction with GSS_S_FAILURE status (never in
954 Linn Standards Track [Page 17]
956 RFC 2743 GSS-API January 2000
959 conjunction with GSS_S_COMPLETE or GSS_S_CONTINUE_NEEDED), and,
960 therefore, always correspond to fatal failures if encountered during
961 the context establishment phase.
963 Table 1: GSS-API Major Status Codes
967 GSS_S_BAD_BINDINGS channel binding mismatch
968 GSS_S_BAD_MECH unsupported mechanism requested
969 GSS_S_BAD_NAME invalid name provided
970 GSS_S_BAD_NAMETYPE name of unsupported type provided
971 GSS_S_BAD_STATUS invalid input status selector
972 GSS_S_BAD_SIG token had invalid integrity check
973 GSS_S_BAD_MIC preferred alias for GSS_S_BAD_SIG
974 GSS_S_CONTEXT_EXPIRED specified security context expired
975 GSS_S_CREDENTIALS_EXPIRED expired credentials detected
976 GSS_S_DEFECTIVE_CREDENTIAL defective credential detected
977 GSS_S_DEFECTIVE_TOKEN defective token detected
978 GSS_S_FAILURE failure, unspecified at GSS-API
980 GSS_S_NO_CONTEXT no valid security context specified
981 GSS_S_NO_CRED no valid credentials provided
982 GSS_S_BAD_QOP unsupported QOP value
983 GSS_S_UNAUTHORIZED operation unauthorized
984 GSS_S_UNAVAILABLE operation unavailable
985 GSS_S_DUPLICATE_ELEMENT duplicate credential element requested
986 GSS_S_NAME_NOT_MN name contains multi-mechanism elements
988 INFORMATORY STATUS CODES
990 GSS_S_COMPLETE normal completion
991 GSS_S_CONTINUE_NEEDED continuation call to routine
993 GSS_S_DUPLICATE_TOKEN duplicate per-message token
995 GSS_S_OLD_TOKEN timed-out per-message token
997 GSS_S_UNSEQ_TOKEN reordered (early) per-message token
999 GSS_S_GAP_TOKEN skipped predecessor token(s)
1002 Minor_status provides more detailed status information which may
1003 include status codes specific to the underlying security mechanism.
1004 Minor_status values are not specified in this document.
1010 Linn Standards Track [Page 18]
1012 RFC 2743 GSS-API January 2000
1015 GSS_S_CONTINUE_NEEDED major_status returns, and optional message
1016 outputs, are provided in GSS_Init_sec_context() and
1017 GSS_Accept_sec_context() calls so that different mechanisms'
1018 employment of different numbers of messages within their
1019 authentication sequences need not be reflected in separate code paths
1020 within calling applications. Instead, such cases are accommodated
1021 with sequences of continuation calls to GSS_Init_sec_context() and
1022 GSS_Accept_sec_context(). The same facility is used to encapsulate
1023 mutual authentication within the GSS-API's context initiation calls.
1025 For mech_types which require interactions with third-party servers in
1026 order to establish a security context, GSS-API context establishment
1027 calls may block pending completion of such third-party interactions.
1028 On the other hand, no GSS-API calls pend on serialized interactions
1029 with GSS-API peer entities. As a result, local GSS-API status
1030 returns cannot reflect unpredictable or asynchronous exceptions
1031 occurring at remote peers, and reflection of such status information
1032 is a caller responsibility outside the GSS-API.
1034 1.2.1.2: Optional Service Support
1036 A context initiator may request various optional services at context
1037 establishment time. Each of these services is requested by setting a
1038 flag in the req_flags input parameter to GSS_Init_sec_context().
1040 The optional services currently defined are:
1042 - Delegation - The (usually temporary) transfer of rights from
1043 initiator to acceptor, enabling the acceptor to authenticate
1044 itself as an agent of the initiator.
1046 - Mutual Authentication - In addition to the initiator
1047 authenticating its identity to the context acceptor, the context
1048 acceptor should also authenticate itself to the initiator.
1050 - Replay detection - In addition to providing message integrity
1051 services, GSS_GetMIC() and GSS_Wrap() should include message
1052 numbering information to enable GSS_VerifyMIC() and GSS_Unwrap()
1053 to detect if a message has been duplicated.
1055 - Out-of-sequence detection - In addition to providing message
1056 integrity services, GSS_GetMIC() and GSS_Wrap() should include
1057 message sequencing information to enable GSS_VerifyMIC() and
1058 GSS_Unwrap() to detect if a message has been received out of
1066 Linn Standards Track [Page 19]
1068 RFC 2743 GSS-API January 2000
1071 - Anonymous authentication - The establishment of the security
1072 context should not reveal the initiator's identity to the context
1075 - Available per-message confidentiality - requests that per-
1076 message confidentiality services be available on the context.
1078 - Available per-message integrity - requests that per-message
1079 integrity services be available on the context.
1081 Any currently undefined bits within such flag arguments should be
1082 ignored by GSS-API implementations when presented by an application,
1083 and should be set to zero when returned to the application by the
1084 GSS-API implementation.
1086 Some mechanisms may not support all optional services, and some
1087 mechanisms may only support some services in conjunction with others.
1088 Both GSS_Init_sec_context() and GSS_Accept_sec_context() inform the
1089 applications which services will be available from the context when
1090 the establishment phase is complete, via the ret_flags output
1091 parameter. In general, if the security mechanism is capable of
1092 providing a requested service, it should do so, even if additional
1093 services must be enabled in order to provide the requested service.
1094 If the mechanism is incapable of providing a requested service, it
1095 should proceed without the service, leaving the application to abort
1096 the context establishment process if it considers the requested
1097 service to be mandatory.
1099 Some mechanisms may specify that support for some services is
1100 optional, and that implementors of the mechanism need not provide it.
1101 This is most commonly true of the confidentiality service, often
1102 because of legal restrictions on the use of data-encryption, but may
1103 apply to any of the services. Such mechanisms are required to send
1104 at least one token from acceptor to initiator during context
1105 establishment when the initiator indicates a desire to use such a
1106 service, so that the initiating GSS-API can correctly indicate
1107 whether the service is supported by the acceptor's GSS-API.
1109 1.2.2: Per-Message Security Service Availability
1111 When a context is established, two flags are returned to indicate the
1112 set of per-message protection security services which will be
1113 available on the context:
1115 the integ_avail flag indicates whether per-message integrity and
1116 data origin authentication services are available
1122 Linn Standards Track [Page 20]
1124 RFC 2743 GSS-API January 2000
1127 the conf_avail flag indicates whether per-message confidentiality
1128 services are available, and will never be returned TRUE unless the
1129 integ_avail flag is also returned TRUE
1131 GSS-API callers desiring per-message security services should check
1132 the values of these flags at context establishment time, and must be
1133 aware that a returned FALSE value for integ_avail means that
1134 invocation of GSS_GetMIC() or GSS_Wrap() primitives on the associated
1135 context will apply no cryptographic protection to user data messages.
1137 The GSS-API per-message integrity and data origin authentication
1138 services provide assurance to a receiving caller that protection was
1139 applied to a message by the caller's peer on the security context,
1140 corresponding to the entity named at context initiation. The GSS-API
1141 per-message confidentiality service provides assurance to a sending
1142 caller that the message's content is protected from access by
1143 entities other than the context's named peer.
1145 The GSS-API per-message protection service primitives, as the
1146 category name implies, are oriented to operation at the granularity
1147 of protocol data units. They perform cryptographic operations on the
1148 data units, transfer cryptographic control information in tokens,
1149 and, in the case of GSS_Wrap(), encapsulate the protected data unit.
1150 As such, these primitives are not oriented to efficient data
1151 protection for stream-paradigm protocols (e.g., Telnet) if
1152 cryptography must be applied on an octet-by-octet basis.
1154 1.2.3: Per-Message Replay Detection and Sequencing
1156 Certain underlying mech_types offer support for replay detection
1157 and/or sequencing of messages transferred on the contexts they
1158 support. These optionally-selectable protection features are distinct
1159 from replay detection and sequencing features applied to the context
1160 establishment operation itself; the presence or absence of context-
1161 level replay or sequencing features is wholly a function of the
1162 underlying mech_type's capabilities, and is not selected or omitted
1165 The caller initiating a context provides flags (replay_det_req_flag
1166 and sequence_req_flag) to specify whether the use of per-message
1167 replay detection and sequencing features is desired on the context
1168 being established. The GSS-API implementation at the initiator system
1169 can determine whether these features are supported (and whether they
1170 are optionally selectable) as a function of the selected mechanism,
1171 without need for bilateral negotiation with the target. When enabled,
1172 these features provide recipients with indicators as a result of
1173 GSS-API processing of incoming messages, identifying whether those
1174 messages were detected as duplicates or out-of-sequence. Detection of
1178 Linn Standards Track [Page 21]
1180 RFC 2743 GSS-API January 2000
1183 such events does not prevent a suspect message from being provided to
1184 a recipient; the appropriate course of action on a suspect message is
1185 a matter of caller policy.
1187 The semantics of the replay detection and sequencing services applied
1188 to received messages, as visible across the interface which the GSS-
1189 API provides to its clients, are as follows:
1191 When replay_det_state is TRUE, the possible major_status returns for
1192 well-formed and correctly signed messages are as follows:
1194 1. GSS_S_COMPLETE, without concurrent indication of
1195 GSS_S_DUPLICATE_TOKEN or GSS_S_OLD_TOKEN, indicates that the
1196 message was within the window (of time or sequence space) allowing
1197 replay events to be detected, and that the message was not a
1198 replay of a previously-processed message within that window.
1200 2. GSS_S_DUPLICATE_TOKEN indicates that the cryptographic
1201 checkvalue on the received message was correct, but that the
1202 message was recognized as a duplicate of a previously-processed
1203 message. In addition to identifying duplicated tokens originated
1204 by a context's peer, this status may also be used to identify
1205 reflected copies of locally-generated tokens; it is recommended
1206 that mechanism designers include within their protocols facilities
1207 to detect and report such tokens.
1209 3. GSS_S_OLD_TOKEN indicates that the cryptographic checkvalue on
1210 the received message was correct, but that the message is too old
1211 to be checked for duplication.
1213 When sequence_state is TRUE, the possible major_status returns for
1214 well-formed and correctly signed messages are as follows:
1216 1. GSS_S_COMPLETE, without concurrent indication of
1217 GSS_S_DUPLICATE_TOKEN, GSS_S_OLD_TOKEN, GSS_S_UNSEQ_TOKEN, or
1218 GSS_S_GAP_TOKEN, indicates that the message was within the window
1219 (of time or sequence space) allowing replay events to be detected,
1220 that the message was not a replay of a previously-processed
1221 message within that window, and that no predecessor sequenced
1222 messages are missing relative to the last received message (if
1223 any) processed on the context with a correct cryptographic
1226 2. GSS_S_DUPLICATE_TOKEN indicates that the integrity check value
1227 on the received message was correct, but that the message was
1228 recognized as a duplicate of a previously-processed message. In
1229 addition to identifying duplicated tokens originated by a
1230 context's peer, this status may also be used to identify reflected
1234 Linn Standards Track [Page 22]
1236 RFC 2743 GSS-API January 2000
1239 copies of locally-generated tokens; it is recommended that
1240 mechanism designers include within their protocols facilities to
1241 detect and report such tokens.
1243 3. GSS_S_OLD_TOKEN indicates that the integrity check value on the
1244 received message was correct, but that the token is too old to be
1245 checked for duplication.
1247 4. GSS_S_UNSEQ_TOKEN indicates that the cryptographic checkvalue
1248 on the received message was correct, but that it is earlier in a
1249 sequenced stream than a message already processed on the context.
1250 [Note: Mechanisms can be architected to provide a stricter form of
1251 sequencing service, delivering particular messages to recipients
1252 only after all predecessor messages in an ordered stream have been
1253 delivered. This type of support is incompatible with the GSS-API
1254 paradigm in which recipients receive all messages, whether in
1255 order or not, and provide them (one at a time, without intra-GSS-
1256 API message buffering) to GSS-API routines for validation. GSS-
1257 API facilities provide supportive functions, aiding clients to
1258 achieve strict message stream integrity in an efficient manner in
1259 conjunction with sequencing provisions in communications
1260 protocols, but the GSS-API does not offer this level of message
1261 stream integrity service by itself.]
1263 5. GSS_S_GAP_TOKEN indicates that the cryptographic checkvalue on
1264 the received message was correct, but that one or more predecessor
1265 sequenced messages have not been successfully processed relative
1266 to the last received message (if any) processed on the context
1267 with a correct cryptographic checkvalue.
1269 As the message stream integrity features (especially sequencing) may
1270 interfere with certain applications' intended communications
1271 paradigms, and since support for such features is likely to be
1272 resource intensive, it is highly recommended that mech_types
1273 supporting these features allow them to be activated selectively on
1274 initiator request when a context is established. A context initiator
1275 and target are provided with corresponding indicators
1276 (replay_det_state and sequence_state), signifying whether these
1277 features are active on a given context.
1279 An example mech_type supporting per-message replay detection could
1280 (when replay_det_state is TRUE) implement the feature as follows: The
1281 underlying mechanism would insert timestamps in data elements output
1282 by GSS_GetMIC() and GSS_Wrap(), and would maintain (within a time-
1283 limited window) a cache (qualified by originator-recipient pair)
1284 identifying received data elements processed by GSS_VerifyMIC() and
1285 GSS_Unwrap(). When this feature is active, exception status returns
1286 (GSS_S_DUPLICATE_TOKEN, GSS_S_OLD_TOKEN) will be provided when
1290 Linn Standards Track [Page 23]
1292 RFC 2743 GSS-API January 2000
1295 GSS_VerifyMIC() or GSS_Unwrap() is presented with a message which is
1296 either a detected duplicate of a prior message or which is too old to
1297 validate against a cache of recently received messages.
1299 1.2.4: Quality of Protection
1301 Some mech_types provide their users with fine granularity control
1302 over the means used to provide per-message protection, allowing
1303 callers to trade off security processing overhead dynamically against
1304 the protection requirements of particular messages. A per-message
1305 quality-of-protection parameter (analogous to quality-of-service, or
1306 QOS) selects among different QOP options supported by that mechanism.
1307 On context establishment for a multi-QOP mech_type, context-level
1308 data provides the prerequisite data for a range of protection
1311 It is expected that the majority of callers will not wish to exert
1312 explicit mechanism-specific QOP control and will therefore request
1313 selection of a default QOP. Definitions of, and choices among, non-
1314 default QOP values are mechanism-specific, and no ordered sequences
1315 of QOP values can be assumed equivalent across different mechanisms.
1316 Meaningful use of non-default QOP values demands that callers be
1317 familiar with the QOP definitions of an underlying mechanism or
1318 mechanisms, and is therefore a non-portable construct. The
1319 GSS_S_BAD_QOP major_status value is defined in order to indicate that
1320 a provided QOP value is unsupported for a security context, most
1321 likely because that value is unrecognized by the underlying
1324 In the interests of interoperability, mechanisms which allow optional
1325 support of particular QOP values shall satisfy one of the following
1328 (i) All implementations of the mechanism are required to be
1329 capable of processing messages protected using any QOP value,
1330 regardless of whether they can apply protection corresponding to
1333 (ii) The set of mutually-supported receiver QOP values must be
1334 determined during context establishment, and messages may be
1335 protected by either peer using only QOP values from this
1336 mutually-supported set.
1338 NOTE: (i) is just a special-case of (ii), where implementations are
1339 required to support all QOP values on receipt.
1346 Linn Standards Track [Page 24]
1348 RFC 2743 GSS-API January 2000
1351 1.2.5: Anonymity Support
1353 In certain situations or environments, an application may wish to
1354 authenticate a peer and/or protect communications using GSS-API per-
1355 message services without revealing its own identity. For example,
1356 consider an application which provides read access to a research
1357 database, and which permits queries by arbitrary requestors. A
1358 client of such a service might wish to authenticate the service, to
1359 establish trust in the information received from it, but might not
1360 wish to disclose its identity to the service for privacy reasons.
1362 In ordinary GSS-API usage, a context initiator's identity is made
1363 available to the context acceptor as part of the context
1364 establishment process. To provide for anonymity support, a facility
1365 (input anon_req_flag to GSS_Init_sec_context()) is provided through
1366 which context initiators may request that their identity not be
1367 provided to the context acceptor. Mechanisms are not required to
1368 honor this request, but a caller will be informed (via returned
1369 anon_state indicator from GSS_Init_sec_context()) whether or not the
1370 request is honored. Note that authentication as the anonymous
1371 principal does not necessarily imply that credentials are not
1372 required in order to establish a context.
1374 Section 4.5 of this document defines the Object Identifier value used
1375 to identify an anonymous principal.
1377 Four possible combinations of anon_state and mutual_state are
1378 possible, with the following results:
1380 anon_state == FALSE, mutual_state == FALSE: initiator
1381 authenticated to target.
1383 anon_state == FALSE, mutual_state == TRUE: initiator authenticated
1384 to target, target authenticated to initiator.
1386 anon_state == TRUE, mutual_state == FALSE: initiator authenticated
1387 as anonymous principal to target.
1389 anon_state == TRUE, mutual_state == TRUE: initiator authenticated
1390 as anonymous principal to target, target authenticated to
1393 1.2.6: Initialization
1395 No initialization calls (i.e., calls which must be invoked prior to
1396 invocation of other facilities in the interface) are defined in GSS-
1397 API. As an implication of this fact, GSS-API implementations must
1398 themselves be self-initializing.
1402 Linn Standards Track [Page 25]
1404 RFC 2743 GSS-API January 2000
1407 1.2.7: Per-Message Protection During Context Establishment
1409 A facility is defined in GSS-V2 to enable protection and buffering of
1410 data messages for later transfer while a security context's
1411 establishment is in GSS_S_CONTINUE_NEEDED status, to be used in cases
1412 where the caller side already possesses the necessary session key to
1413 enable this processing. Specifically, a new state Boolean, called
1414 prot_ready_state, is added to the set of information returned by
1415 GSS_Init_sec_context(), GSS_Accept_sec_context(), and
1416 GSS_Inquire_context().
1418 For context establishment calls, this state Boolean is valid and
1419 interpretable when the associated major_status is either
1420 GSS_S_CONTINUE_NEEDED, or GSS_S_COMPLETE. Callers of GSS-API (both
1421 initiators and acceptors) can assume that per-message protection (via
1422 GSS_Wrap(), GSS_Unwrap(), GSS_GetMIC() and GSS_VerifyMIC()) is
1423 available and ready for use if either: prot_ready_state == TRUE, or
1424 major_status == GSS_S_COMPLETE, though mutual authentication (if
1425 requested) cannot be guaranteed until GSS_S_COMPLETE is returned.
1426 Callers making use of per-message protection services in advance of
1427 GSS_S_COMPLETE status should be aware of the possibility that a
1428 subsequent context establishment step may fail, and that certain
1429 context data (e.g., mech_type) as returned for subsequent calls may
1432 This approach achieves full, transparent backward compatibility for
1433 GSS-API V1 callers, who need not even know of the existence of
1434 prot_ready_state, and who will get the expected behavior from
1435 GSS_S_COMPLETE, but who will not be able to use per-message
1436 protection before GSS_S_COMPLETE is returned.
1438 It is not a requirement that GSS-V2 mechanisms ever return TRUE
1439 prot_ready_state before completion of context establishment (indeed,
1440 some mechanisms will not evolve usable message protection keys,
1441 especially at the context acceptor, before context establishment is
1442 complete). It is expected but not required that GSS-V2 mechanisms
1443 will return TRUE prot_ready_state upon completion of context
1444 establishment if they support per-message protection at all (however
1445 GSS-V2 applications should not assume that TRUE prot_ready_state will
1446 always be returned together with the GSS_S_COMPLETE major_status,
1447 since GSS-V2 implementations may continue to support GSS-V1 mechanism
1448 code, which will never return TRUE prot_ready_state).
1450 When prot_ready_state is returned TRUE, mechanisms shall also set
1451 those context service indicator flags (deleg_state, mutual_state,
1452 replay_det_state, sequence_state, anon_state, trans_state,
1453 conf_avail, integ_avail) which represent facilities confirmed, at
1454 that time, to be available on the context being established. In
1458 Linn Standards Track [Page 26]
1460 RFC 2743 GSS-API January 2000
1463 situations where prot_ready_state is returned before GSS_S_COMPLETE,
1464 it is possible that additional facilities may be confirmed and
1465 subsequently indicated when GSS_S_COMPLETE is returned.
1467 1.2.8: Implementation Robustness
1469 This section recommends aspects of GSS-API implementation behavior in
1470 the interests of overall robustness.
1472 Invocation of GSS-API calls is to incur no undocumented side effects
1473 visible at the GSS-API level.
1475 If a token is presented for processing on a GSS-API security context
1476 and that token generates a fatal error in processing or is otherwise
1477 determined to be invalid for that context, the context's state should
1478 not be disrupted for purposes of processing subsequent valid tokens.
1480 Certain local conditions at a GSS-API implementation (e.g.,
1481 unavailability of memory) may preclude, temporarily or permanently,
1482 the successful processing of tokens on a GSS-API security context,
1483 typically generating GSS_S_FAILURE major_status returns along with
1484 locally-significant minor_status. For robust operation under such
1485 conditions, the following recommendations are made:
1487 Failing calls should free any memory they allocate, so that
1488 callers may retry without causing further loss of resources.
1490 Failure of an individual call on an established context should not
1491 preclude subsequent calls from succeeding on the same context.
1493 Whenever possible, it should be possible for
1494 GSS_Delete_sec_context() calls to be successfully processed even
1495 if other calls cannot succeed, thereby enabling context-related
1496 resources to be released.
1498 A failure of GSS_GetMIC() or GSS_Wrap() due to an attempt to use an
1499 unsupported QOP will not interfere with context validity, nor shall
1500 such a failure impact the ability of the application to subsequently
1501 invoke GSS_GetMIC() or GSS_Wrap() using a supported QOP. Any state
1502 information concerning sequencing of outgoing messages shall be
1503 unchanged by an unsuccessful call of GSS_GetMIC() or GSS_Wrap().
1514 Linn Standards Track [Page 27]
1516 RFC 2743 GSS-API January 2000
1521 The GSS-API allows delegation to be controlled by the initiating
1522 application via a Boolean parameter to GSS_Init_sec_context(), the
1523 routine that establishes a security context. Some mechanisms do not
1524 support delegation, and for such mechanisms attempts by an
1525 application to enable delegation are ignored.
1527 The acceptor of a security context for which the initiator enabled
1528 delegation will receive (via the delegated_cred_handle parameter of
1529 GSS_Accept_sec_context()) a credential handle that contains the
1530 delegated identity, and this credential handle may be used to
1531 initiate subsequent GSS-API security contexts as an agent or delegate
1532 of the initiator. If the original initiator's identity is "A" and
1533 the delegate's identity is "B", then, depending on the underlying
1534 mechanism, the identity embodied by the delegated credential may be
1535 either "A" or "B acting for A".
1537 For many mechanisms that support delegation, a simple Boolean does
1538 not provide enough control. Examples of additional aspects of
1539 delegation control that a mechanism might provide to an application
1540 are duration of delegation, network addresses from which delegation
1541 is valid, and constraints on the tasks that may be performed by a
1542 delegate. Such controls are presently outside the scope of the GSS-
1543 API. GSS-API implementations supporting mechanisms offering
1544 additional controls should provide extension routines that allow
1545 these controls to be exercised (perhaps by modifying the initiator's
1546 GSS-API credential prior to its use in establishing a context).
1547 However, the simple delegation control provided by GSS-API should
1548 always be able to over-ride other mechanism-specific delegation
1549 controls; if the application instructs GSS_Init_sec_context() that
1550 delegation is not desired, then the implementation must not permit
1551 delegation to occur. This is an exception to the general rule that a
1552 mechanism may enable services even if they are not requested;
1553 delegation may only be provided at the explicit request of the
1556 1.2.10: Interprocess Context Transfer
1558 GSS-API V2 provides routines (GSS_Export_sec_context() and
1559 GSS_Import_sec_context()) which allow a security context to be
1560 transferred between processes on a single machine. The most common
1561 use for such a feature is a client-server design where the server is
1562 implemented as a single process that accepts incoming security
1563 contexts, which then launches child processes to deal with the data
1564 on these contexts. In such a design, the child processes must have
1565 access to the security context data structure created within the
1570 Linn Standards Track [Page 28]
1572 RFC 2743 GSS-API January 2000
1575 parent by its call to GSS_Accept_sec_context() so that they can use
1576 per-message protection services and delete the security context when
1577 the communication session ends.
1579 Since the security context data structure is expected to contain
1580 sequencing information, it is impractical in general to share a
1581 context between processes. Thus GSS-API provides a call
1582 (GSS_Export_sec_context()) that the process which currently owns the
1583 context can call to declare that it has no intention to use the
1584 context subsequently, and to create an inter-process token containing
1585 information needed by the adopting process to successfully import the
1586 context. After successful completion of this call, the original
1587 security context is made inaccessible to the calling process by GSS-
1588 API, and any context handles referring to this context are no longer
1589 valid. The originating process transfers the inter-process token to
1590 the adopting process, which passes it to GSS_Import_sec_context(),
1591 and a fresh context handle is created such that it is functionally
1592 identical to the original context.
1594 The inter-process token may contain sensitive data from the original
1595 security context (including cryptographic keys). Applications using
1596 inter-process tokens to transfer security contexts must take
1597 appropriate steps to protect these tokens in transit.
1598 Implementations are not required to support the inter-process
1599 transfer of security contexts. The ability to transfer a security
1600 context is indicated when the context is created, by
1601 GSS_Init_sec_context() or GSS_Accept_sec_context() indicating a TRUE
1602 trans_state return value.
1604 2: Interface Descriptions
1606 This section describes the GSS-API's service interface, dividing the
1607 set of calls offered into four groups. Credential management calls
1608 are related to the acquisition and release of credentials by
1609 principals. Context-level calls are related to the management of
1610 security contexts between principals. Per-message calls are related
1611 to the protection of individual messages on established security
1612 contexts. Support calls provide ancillary functions useful to GSS-API
1613 callers. Table 2 groups and summarizes the calls in tabular fashion.
1615 Table 2: GSS-API Calls
1617 CREDENTIAL MANAGEMENT
1619 GSS_Acquire_cred acquire credentials for use
1620 GSS_Release_cred release credentials after use
1621 GSS_Inquire_cred display information about
1626 Linn Standards Track [Page 29]
1628 RFC 2743 GSS-API January 2000
1631 GSS_Add_cred construct credentials incrementally
1632 GSS_Inquire_cred_by_mech display per-mechanism credential
1637 GSS_Init_sec_context initiate outbound security context
1638 GSS_Accept_sec_context accept inbound security context
1639 GSS_Delete_sec_context flush context when no longer needed
1640 GSS_Process_context_token process received control token on
1642 GSS_Context_time indicate validity time remaining on
1644 GSS_Inquire_context display information about context
1645 GSS_Wrap_size_limit determine GSS_Wrap token size limit
1646 GSS_Export_sec_context transfer context to other process
1647 GSS_Import_sec_context import transferred context
1651 GSS_GetMIC apply integrity check, receive as
1652 token separate from message
1653 GSS_VerifyMIC validate integrity check token
1655 GSS_Wrap sign, optionally encrypt,
1657 GSS_Unwrap decapsulate, decrypt if needed,
1658 validate integrity check
1662 GSS_Display_status translate status codes to printable
1664 GSS_Indicate_mechs indicate mech_types supported on
1666 GSS_Compare_name compare two names for equality
1667 GSS_Display_name translate name to printable form
1668 GSS_Import_name convert printable name to
1670 GSS_Release_name free storage of normalized-form
1672 GSS_Release_buffer free storage of general GSS-allocated
1674 GSS_Release_OID_set free storage of OID set object
1675 GSS_Create_empty_OID_set create empty OID set
1676 GSS_Add_OID_set_member add member to OID set
1677 GSS_Test_OID_set_member test if OID is member of OID set
1678 GSS_Inquire_names_for_mech indicate name types supported by
1682 Linn Standards Track [Page 30]
1684 RFC 2743 GSS-API January 2000
1688 GSS_Inquire_mechs_for_name indicates mechanisms supporting name
1690 GSS_Canonicalize_name translate name to per-mechanism form
1691 GSS_Export_name externalize per-mechanism name
1692 GSS_Duplicate_name duplicate name object
1694 2.1: Credential management calls
1696 These GSS-API calls provide functions related to the management of
1697 credentials. Their characterization with regard to whether or not
1698 they may block pending exchanges with other network entities (e.g.,
1699 directories or authentication servers) depends in part on OS-specific
1700 (extra-GSS-API) issues, so is not specified in this document.
1702 The GSS_Acquire_cred() call is defined within the GSS-API in support
1703 of application portability, with a particular orientation towards
1704 support of portable server applications. It is recognized that (for
1705 certain systems and mechanisms) credentials for interactive users may
1706 be managed differently from credentials for server processes; in such
1707 environments, it is the GSS-API implementation's responsibility to
1708 distinguish these cases and the procedures for making this
1709 distinction are a local matter. The GSS_Release_cred() call provides
1710 a means for callers to indicate to the GSS-API that use of a
1711 credentials structure is no longer required. The GSS_Inquire_cred()
1712 call allows callers to determine information about a credentials
1713 structure. The GSS_Add_cred() call enables callers to append
1714 elements to an existing credential structure, allowing iterative
1715 construction of a multi-mechanism credential. The
1716 GSS_Inquire_cred_by_mech() call enables callers to extract per-
1717 mechanism information describing a credentials structure.
1719 2.1.1: GSS_Acquire_cred call
1723 o desired_name INTERNAL NAME, -- NULL requests locally-determined
1726 o lifetime_req INTEGER, -- in seconds; 0 requests default
1728 o desired_mechs SET OF OBJECT IDENTIFIER, -- NULL requests
1729 -- system-selected default
1731 o cred_usage INTEGER -- 0=INITIATE-AND-ACCEPT, 1=INITIATE-ONLY,
1738 Linn Standards Track [Page 31]
1740 RFC 2743 GSS-API January 2000
1745 o major_status INTEGER,
1747 o minor_status INTEGER,
1749 o output_cred_handle CREDENTIAL HANDLE, -- if returned non-NULL,
1750 -- caller must release with GSS_Release_cred()
1752 o actual_mechs SET OF OBJECT IDENTIFIER, -- if returned non-NULL,
1753 -- caller must release with GSS_Release_oid_set()
1755 o lifetime_rec INTEGER -- in seconds, or reserved value for
1758 Return major_status codes:
1760 o GSS_S_COMPLETE indicates that requested credentials were
1761 successfully established, for the duration indicated in lifetime_rec,
1762 suitable for the usage requested in cred_usage, for the set of
1763 mech_types indicated in actual_mechs, and that those credentials can
1764 be referenced for subsequent use with the handle returned in
1767 o GSS_S_BAD_MECH indicates that a mech_type unsupported by the GSS-
1768 API implementation type was requested, causing the credential
1769 establishment operation to fail.
1771 o GSS_S_BAD_NAMETYPE indicates that the provided desired_name is
1772 uninterpretable or of a type unsupported by the applicable underlying
1773 GSS-API mechanism(s), so no credentials could be established for the
1774 accompanying desired_name.
1776 o GSS_S_BAD_NAME indicates that the provided desired_name is
1777 inconsistent in terms of internally-incorporated type specifier
1778 information, so no credentials could be established for the
1779 accompanying desired_name.
1781 o GSS_S_CREDENTIALS_EXPIRED indicates that underlying credential
1782 elements corresponding to the requested desired_name have expired, so
1783 requested credentials could not be established.
1785 o GSS_S_NO_CRED indicates that no credential elements corresponding
1786 to the requested desired_name and usage could be accessed, so
1787 requested credentials could not be established. In particular, this
1788 status should be returned upon temporary user-fixable conditions
1794 Linn Standards Track [Page 32]
1796 RFC 2743 GSS-API January 2000
1799 preventing successful credential establishment and upon lack of
1800 authorization to establish and use credentials associated with the
1801 identity named in the input desired_name argument.
1803 o GSS_S_FAILURE indicates that credential establishment failed for
1804 reasons unspecified at the GSS-API level.
1806 GSS_Acquire_cred() is used to acquire credentials so that a principal
1807 can (as a function of the input cred_usage parameter) initiate and/or
1808 accept security contexts under the identity represented by the
1809 desired_name input argument. On successful completion, the returned
1810 output_cred_handle result provides a handle for subsequent references
1811 to the acquired credentials. Typically, single-user client processes
1812 requesting that default credential behavior be applied for context
1813 establishment purposes will have no need to invoke this call.
1815 A caller may provide the value NULL (GSS_C_NO_NAME) for desired_name,
1816 which will be interpreted as a request for a credential handle that
1817 will invoke default behavior when passed to GSS_Init_sec_context(),
1818 if cred_usage is GSS_C_INITIATE or GSS_C_BOTH, or
1819 GSS_Accept_sec_context(), if cred_usage is GSS_C_ACCEPT or
1820 GSS_C_BOTH. It is possible that multiple pre-established credentials
1821 may exist for the same principal identity (for example, as a result
1822 of multiple user login sessions) when GSS_Acquire_cred() is called;
1823 the means used in such cases to select a specific credential are
1824 local matters. The input lifetime_req argument to GSS_Acquire_cred()
1825 may provide useful information for local GSS-API implementations to
1826 employ in making this disambiguation in a manner which will best
1827 satisfy a caller's intent.
1829 This routine is expected to be used primarily by context acceptors,
1830 since implementations are likely to provide mechanism-specific ways
1831 of obtaining GSS-API initiator credentials from the system login
1832 process. Some implementations may therefore not support the
1833 acquisition of GSS_C_INITIATE or GSS_C_BOTH credentials via
1834 GSS_Acquire_cred() for any name other than GSS_C_NO_NAME, or a name
1835 resulting from applying GSS_Inquire_context() to an active context,
1836 or a name resulting from applying GSS_Inquire_cred() against a
1837 credential handle corresponding to default behavior. It is important
1838 to recognize that the explicit name which is yielded by resolving a
1839 default reference may change over time, e.g., as a result of local
1840 credential element management operations outside GSS-API; once
1841 resolved, however, the value of such an explicit name will remain
1844 The lifetime_rec result indicates the length of time for which the
1845 acquired credentials will be valid, as an offset from the present. A
1846 mechanism may return a reserved value indicating INDEFINITE if no
1850 Linn Standards Track [Page 33]
1852 RFC 2743 GSS-API January 2000
1855 constraints on credential lifetime are imposed. A caller of
1856 GSS_Acquire_cred() can request a length of time for which acquired
1857 credentials are to be valid (lifetime_req argument), beginning at the
1858 present, or can request credentials with a default validity interval.
1859 (Requests for postdated credentials are not supported within the
1860 GSS-API.) Certain mechanisms and implementations may bind in
1861 credential validity period specifiers at a point preliminary to
1862 invocation of the GSS_Acquire_cred() call (e.g., in conjunction with
1863 user login procedures). As a result, callers requesting non-default
1864 values for lifetime_req must recognize that such requests cannot
1865 always be honored and must be prepared to accommodate the use of
1866 returned credentials with different lifetimes as indicated in
1869 The caller of GSS_Acquire_cred() can explicitly specify a set of
1870 mech_types which are to be accommodated in the returned credentials
1871 (desired_mechs argument), or can request credentials for a system-
1872 defined default set of mech_types. Selection of the system-specified
1873 default set is recommended in the interests of application
1874 portability. The actual_mechs return value may be interrogated by the
1875 caller to determine the set of mechanisms with which the returned
1876 credentials may be used.
1878 2.1.2: GSS_Release_cred call
1882 o cred_handle CREDENTIAL HANDLE -- if GSS_C_NO_CREDENTIAL
1883 -- is specified, the call will complete successfully, but
1884 -- will have no effect; no credential elements will be
1889 o major_status INTEGER,
1891 o minor_status INTEGER
1893 Return major_status codes:
1895 o GSS_S_COMPLETE indicates that the credentials referenced by the
1896 input cred_handle were released for purposes of subsequent access by
1897 the caller. The effect on other processes which may be authorized
1898 shared access to such credentials is a local matter.
1906 Linn Standards Track [Page 34]
1908 RFC 2743 GSS-API January 2000
1911 o GSS_S_NO_CRED indicates that no release operation was performed,
1912 either because the input cred_handle was invalid or because the
1913 caller lacks authorization to access the referenced credentials.
1915 o GSS_S_FAILURE indicates that the release operation failed for
1916 reasons unspecified at the GSS-API level.
1918 Provides a means for a caller to explicitly request that credentials
1919 be released when their use is no longer required. Note that system-
1920 specific credential management functions are also likely to exist,
1921 for example to assure that credentials shared among processes are
1922 properly deleted when all affected processes terminate, even if no
1923 explicit release requests are issued by those processes. Given the
1924 fact that multiple callers are not precluded from gaining authorized
1925 access to the same credentials, invocation of GSS_Release_cred()
1926 cannot be assumed to delete a particular set of credentials on a
1929 2.1.3: GSS_Inquire_cred call
1933 o cred_handle CREDENTIAL HANDLE -- if GSS_C_NO_CREDENTIAL
1934 -- is specified, default initiator credentials are queried
1938 o major_status INTEGER,
1940 o minor_status INTEGER,
1942 o cred_name INTERNAL NAME, -- caller must release with
1943 -- GSS_Release_name()
1945 o lifetime_rec INTEGER -- in seconds, or reserved value for
1948 o cred_usage INTEGER, -- 0=INITIATE-AND-ACCEPT, 1=INITIATE-ONLY,
1951 o mech_set SET OF OBJECT IDENTIFIER -- caller must release
1952 -- with GSS_Release_oid_set()
1962 Linn Standards Track [Page 35]
1964 RFC 2743 GSS-API January 2000
1967 Return major_status codes:
1969 o GSS_S_COMPLETE indicates that the credentials referenced by the
1970 input cred_handle argument were valid, and that the output cred_name,
1971 lifetime_rec, and cred_usage values represent, respectively, the
1972 credentials' associated principal name, remaining lifetime, suitable
1973 usage modes, and supported mechanism types.
1975 o GSS_S_NO_CRED indicates that no information could be returned
1976 about the referenced credentials, either because the input
1977 cred_handle was invalid or because the caller lacks authorization to
1978 access the referenced credentials.
1980 o GSS_S_DEFECTIVE_CREDENTIAL indicates that the referenced
1981 credentials are invalid.
1983 o GSS_S_CREDENTIALS_EXPIRED indicates that the referenced
1984 credentials have expired.
1986 o GSS_S_FAILURE indicates that the operation failed for reasons
1987 unspecified at the GSS-API level.
1989 The GSS_Inquire_cred() call is defined primarily for the use of those
1990 callers which request use of default credential behavior rather than
1991 acquiring credentials explicitly with GSS_Acquire_cred(). It enables
1992 callers to determine a credential structure's associated principal
1993 name, remaining validity period, usability for security context
1994 initiation and/or acceptance, and supported mechanisms.
1996 For a multi-mechanism credential, the returned "lifetime" specifier
1997 indicates the shortest lifetime of any of the mechanisms' elements in
1998 the credential (for either context initiation or acceptance
2001 GSS_Inquire_cred() should indicate INITIATE-AND-ACCEPT for
2002 "cred_usage" if both of the following conditions hold:
2004 (1) there exists in the credential an element which allows context
2005 initiation using some mechanism
2007 (2) there exists in the credential an element which allows context
2008 acceptance using some mechanism (allowably, but not necessarily,
2009 one of the same mechanism(s) qualifying for (1)).
2011 If condition (1) holds but not condition (2), GSS_Inquire_cred()
2012 should indicate INITIATE-ONLY for "cred_usage". If condition (2)
2013 holds but not condition (1), GSS_Inquire_cred() should indicate
2014 ACCEPT-ONLY for "cred_usage".
2018 Linn Standards Track [Page 36]
2020 RFC 2743 GSS-API January 2000
2023 Callers requiring finer disambiguation among available combinations
2024 of lifetimes, usage modes, and mechanisms should call the
2025 GSS_Inquire_cred_by_mech() routine, passing that routine one of the
2026 mech OIDs returned by GSS_Inquire_cred().
2028 2.1.4: GSS_Add_cred call
2032 o input_cred_handle CREDENTIAL HANDLE -- handle to credential
2033 -- structure created with prior GSS_Acquire_cred() or
2034 -- GSS_Add_cred() call; see text for definition of behavior
2035 -- when GSS_C_NO_CREDENTIAL provided.
2037 o desired_name INTERNAL NAME
2039 o initiator_time_req INTEGER -- in seconds; 0 requests default
2041 o acceptor_time_req INTEGER -- in seconds; 0 requests default
2043 o desired_mech OBJECT IDENTIFIER
2045 o cred_usage INTEGER -- 0=INITIATE-AND-ACCEPT, 1=INITIATE-ONLY,
2050 o major_status INTEGER,
2052 o minor_status INTEGER,
2054 o output_cred_handle CREDENTIAL HANDLE, -- NULL to request that
2055 -- credential elements be added "in place" to the credential
2056 -- structure identified by input_cred_handle,
2057 -- non-NULL pointer to request that
2058 -- a new credential structure and handle be created.
2059 -- if credential handle returned, caller must release with
2060 -- GSS_Release_cred()
2062 o actual_mechs SET OF OBJECT IDENTIFIER, -- if returned, caller must
2063 -- release with GSS_Release_oid_set()
2065 o initiator_time_rec INTEGER -- in seconds, or reserved value for
2068 o acceptor_time_rec INTEGER -- in seconds, or reserved value for
2074 Linn Standards Track [Page 37]
2076 RFC 2743 GSS-API January 2000
2079 o cred_usage INTEGER, -- 0=INITIATE-AND-ACCEPT, 1=INITIATE-ONLY,
2082 o mech_set SET OF OBJECT IDENTIFIER -- full set of mechanisms
2083 -- supported by resulting credential.
2085 Return major_status codes:
2087 o GSS_S_COMPLETE indicates that the credentials referenced by the
2088 input_cred_handle argument were valid, and that the resulting
2089 credential from GSS_Add_cred() is valid for the durations indicated
2090 in initiator_time_rec and acceptor_time_rec, suitable for the usage
2091 requested in cred_usage, and for the mechanisms indicated in
2094 o GSS_S_DUPLICATE_ELEMENT indicates that the input desired_mech
2095 specified a mechanism for which the referenced credential already
2096 contained a credential element with overlapping cred_usage and
2097 validity time specifiers.
2099 o GSS_S_BAD_MECH indicates that the input desired_mech specified a
2100 mechanism unsupported by the GSS-API implementation, causing the
2101 GSS_Add_cred() operation to fail.
2103 o GSS_S_BAD_NAMETYPE indicates that the provided desired_name is
2104 uninterpretable or of a type unsupported by the applicable underlying
2105 GSS-API mechanism(s), so the GSS_Add_cred() operation could not be
2106 performed for that name.
2108 o GSS_S_BAD_NAME indicates that the provided desired_name is
2109 inconsistent in terms of internally-incorporated type specifier
2110 information, so the GSS_Add_cred() operation could not be performed
2113 o GSS_S_NO_CRED indicates that the input_cred_handle referenced
2114 invalid or inaccessible credentials. In particular, this status
2115 should be returned upon temporary user-fixable conditions preventing
2116 successful credential establishment or upon lack of authorization to
2117 establish or use credentials representing the requested identity.
2119 o GSS_S_CREDENTIALS_EXPIRED indicates that referenced credential
2120 elements have expired, so the GSS_Add_cred() operation could not be
2123 o GSS_S_FAILURE indicates that the operation failed for reasons
2124 unspecified at the GSS-API level.
2130 Linn Standards Track [Page 38]
2132 RFC 2743 GSS-API January 2000
2135 GSS_Add_cred() enables callers to construct credentials iteratively
2136 by adding credential elements in successive operations, corresponding
2137 to different mechanisms. This offers particular value in multi-
2138 mechanism environments, as the major_status and minor_status values
2139 returned on each iteration are individually visible and can therefore
2140 be interpreted unambiguously on a per-mechanism basis. A credential
2141 element is identified by the name of the principal to which it
2142 refers. GSS-API implementations must impose a local access control
2143 policy on callers of this routine to prevent unauthorized callers
2144 from acquiring credential elements to which they are not entitled.
2145 This routine is not intended to provide a "login to the network"
2146 function, as such a function would involve the creation of new
2147 mechanism-specific authentication data, rather than merely acquiring
2148 a GSS-API handle to existing data. Such functions, if required,
2149 should be defined in implementation-specific extension routines.
2151 If credential acquisition is time-consuming for a mechanism, the
2152 mechanism may choose to delay the actual acquisition until the
2153 credential is required (e.g. by GSS_Init_sec_context() or
2154 GSS_Accept_sec_context()). Such mechanism-specific implementation
2155 decisions should be invisible to the calling application; thus a call
2156 of GSS_Inquire_cred() immediately following the call of
2157 GSS_Acquire_cred() must return valid credential data, and may
2158 therefore incur the overhead of a deferred credential acquisition.
2160 If GSS_C_NO_CREDENTIAL is specified as input_cred_handle, a non-NULL
2161 output_cred_handle must be supplied. For the case of
2162 GSS_C_NO_CREDENTIAL as input_cred_handle, GSS_Add_cred() will create
2163 the credential referenced by its output_cred_handle based on default
2164 behavior. That is, the call will have the same effect as if the
2165 caller had previously called GSS_Acquire_cred(), specifying the same
2166 usage and passing GSS_C_NO_NAME as the desired_name parameter
2167 (thereby obtaining an explicit credential handle corresponding to
2168 default behavior), had passed that credential handle to
2169 GSS_Add_cred(), and had finally called GSS_Release_cred() on the
2170 credential handle received from GSS_Acquire_cred().
2172 This routine is expected to be used primarily by context acceptors,
2173 since implementations are likely to provide mechanism-specific ways
2174 of obtaining GSS-API initiator credentials from the system login
2175 process. Some implementations may therefore not support the
2176 acquisition of GSS_C_INITIATE or GSS_C_BOTH credentials via
2177 GSS_Acquire_cred() for any name other than GSS_C_NO_NAME, or a name
2178 resulting from applying GSS_Inquire_context() to an active context,
2179 or a name resulting from applying GSS_Inquire_cred() against a
2180 credential handle corresponding to default behavior. It is important
2181 to recognize that the explicit name which is yielded by resolving a
2182 default reference may change over time, e.g., as a result of local
2186 Linn Standards Track [Page 39]
2188 RFC 2743 GSS-API January 2000
2191 credential element management operations outside GSS-API; once
2192 resolved, however, the value of such an explicit name will remain
2195 A caller may provide the value NULL (GSS_C_NO_NAME) for desired_name,
2196 which will be interpreted as a request for a credential handle that
2197 will invoke default behavior when passed to GSS_Init_sec_context(),
2198 if cred_usage is GSS_C_INITIATE or GSS_C_BOTH, or
2199 GSS_Accept_sec_context(), if cred_usage is GSS_C_ACCEPT or
2202 The same input desired_name, or default reference, should be used on
2203 all GSS_Acquire_cred() and GSS_Add_cred() calls corresponding to a
2204 particular credential.
2206 2.1.5: GSS_Inquire_cred_by_mech call
2210 o cred_handle CREDENTIAL HANDLE -- if GSS_C_NO_CREDENTIAL
2211 -- specified, default initiator credentials are queried
2213 o mech_type OBJECT IDENTIFIER -- specific mechanism for
2214 -- which credentials are being queried
2218 o major_status INTEGER,
2220 o minor_status INTEGER,
2222 o cred_name INTERNAL NAME, -- guaranteed to be MN; caller must
2223 -- release with GSS_Release_name()
2225 o lifetime_rec_initiate INTEGER -- in seconds, or reserved value for
2228 o lifetime_rec_accept INTEGER -- in seconds, or reserved value for
2231 o cred_usage INTEGER, -- 0=INITIATE-AND-ACCEPT, 1=INITIATE-ONLY,
2234 Return major_status codes:
2236 o GSS_S_COMPLETE indicates that the credentials referenced by the
2237 input cred_handle argument were valid, that the mechanism indicated
2238 by the input mech_type was represented with elements within those
2242 Linn Standards Track [Page 40]
2244 RFC 2743 GSS-API January 2000
2247 credentials, and that the output cred_name, lifetime_rec_initiate,
2248 lifetime_rec_accept, and cred_usage values represent, respectively,
2249 the credentials' associated principal name, remaining lifetimes, and
2250 suitable usage modes.
2252 o GSS_S_NO_CRED indicates that no information could be returned
2253 about the referenced credentials, either because the input
2254 cred_handle was invalid or because the caller lacks authorization to
2255 access the referenced credentials.
2257 o GSS_S_DEFECTIVE_CREDENTIAL indicates that the referenced
2258 credentials are invalid.
2260 o GSS_S_CREDENTIALS_EXPIRED indicates that the referenced
2261 credentials have expired.
2263 o GSS_S_BAD_MECH indicates that the referenced credentials do not
2264 contain elements for the requested mechanism.
2266 o GSS_S_FAILURE indicates that the operation failed for reasons
2267 unspecified at the GSS-API level.
2269 The GSS_Inquire_cred_by_mech() call enables callers in multi-
2270 mechanism environments to acquire specific data about available
2271 combinations of lifetimes, usage modes, and mechanisms within a
2272 credential structure. The lifetime_rec_initiate result indicates the
2273 available lifetime for context initiation purposes; the
2274 lifetime_rec_accept result indicates the available lifetime for
2275 context acceptance purposes.
2277 2.2: Context-level calls
2279 This group of calls is devoted to the establishment and management of
2280 security contexts between peers. A context's initiator calls
2281 GSS_Init_sec_context(), resulting in generation of a token which the
2282 caller passes to the target. At the target, that token is passed to
2283 GSS_Accept_sec_context(). Depending on the underlying mech_type and
2284 specified options, additional token exchanges may be performed in the
2285 course of context establishment; such exchanges are accommodated by
2286 GSS_S_CONTINUE_NEEDED status returns from GSS_Init_sec_context() and
2287 GSS_Accept_sec_context().
2289 Either party to an established context may invoke
2290 GSS_Delete_sec_context() to flush context information when a context
2291 is no longer required. GSS_Process_context_token() is used to process
2292 received tokens carrying context-level control information.
2293 GSS_Context_time() allows a caller to determine the length of time
2294 for which an established context will remain valid.
2298 Linn Standards Track [Page 41]
2300 RFC 2743 GSS-API January 2000
2303 GSS_Inquire_context() returns status information describing context
2304 characteristics. GSS_Wrap_size_limit() allows a caller to determine
2305 the size of a token which will be generated by a GSS_Wrap()
2306 operation. GSS_Export_sec_context() and GSS_Import_sec_context()
2307 enable transfer of active contexts between processes on an end
2310 2.2.1: GSS_Init_sec_context call
2314 o claimant_cred_handle CREDENTIAL HANDLE, -- NULL specifies "use
2317 o input_context_handle CONTEXT HANDLE, -- 0
2318 -- (GSS_C_NO_CONTEXT) specifies "none assigned yet"
2320 o targ_name INTERNAL NAME,
2322 o mech_type OBJECT IDENTIFIER, -- NULL parameter specifies "use
2325 o deleg_req_flag BOOLEAN,
2327 o mutual_req_flag BOOLEAN,
2329 o replay_det_req_flag BOOLEAN,
2331 o sequence_req_flag BOOLEAN,
2333 o anon_req_flag BOOLEAN,
2335 o conf_req_flag BOOLEAN,
2337 o integ_req_flag BOOLEAN,
2339 o lifetime_req INTEGER, -- 0 specifies default lifetime
2341 o chan_bindings OCTET STRING,
2343 o input_token OCTET STRING -- NULL or token received from target
2347 o major_status INTEGER,
2349 o minor_status INTEGER,
2354 Linn Standards Track [Page 42]
2356 RFC 2743 GSS-API January 2000
2359 o output_context_handle CONTEXT HANDLE, -- once returned non-NULL,
2360 -- caller must release with GSS_Delete_sec_context()
2362 o mech_type OBJECT IDENTIFIER, -- actual mechanism always
2363 -- indicated, never NULL; caller should treat as read-only
2364 -- and should not attempt to release
2366 o output_token OCTET STRING, -- NULL or token to pass to context
2367 -- target; caller must release with GSS_Release_buffer()
2369 o deleg_state BOOLEAN,
2371 o mutual_state BOOLEAN,
2373 o replay_det_state BOOLEAN,
2375 o sequence_state BOOLEAN,
2377 o anon_state BOOLEAN,
2379 o trans_state BOOLEAN,
2381 o prot_ready_state BOOLEAN, -- see Section 1.2.7
2383 o conf_avail BOOLEAN,
2385 o integ_avail BOOLEAN,
2387 o lifetime_rec INTEGER -- in seconds, or reserved value for
2390 This call may block pending network interactions for those mech_types
2391 in which an authentication server or other network entity must be
2392 consulted on behalf of a context initiator in order to generate an
2393 output_token suitable for presentation to a specified target.
2395 Return major_status codes:
2397 o GSS_S_COMPLETE indicates that context-level information was
2398 successfully initialized, and that the returned output_token will
2399 provide sufficient information for the target to perform per-message
2400 processing on the newly-established context.
2402 o GSS_S_CONTINUE_NEEDED indicates that control information in the
2403 returned output_token must be sent to the target, and that a reply
2404 must be received and passed as the input_token argument
2410 Linn Standards Track [Page 43]
2412 RFC 2743 GSS-API January 2000
2415 to a continuation call to GSS_Init_sec_context(), before per-message
2416 processing can be performed in conjunction with this context (unless
2417 the prot_ready_state value is concurrently returned TRUE).
2419 o GSS_S_DEFECTIVE_TOKEN indicates that consistency checks performed
2420 on the input_token failed, preventing further processing from being
2421 performed based on that token.
2423 o GSS_S_DEFECTIVE_CREDENTIAL indicates that consistency checks
2424 performed on the credential structure referenced by
2425 claimant_cred_handle failed, preventing further processing from being
2426 performed using that credential structure.
2428 o GSS_S_BAD_SIG (GSS_S_BAD_MIC) indicates that the received
2429 input_token contains an incorrect integrity check, so context setup
2430 cannot be accomplished.
2432 o GSS_S_NO_CRED indicates that no context was established, either
2433 because the input cred_handle was invalid, because the referenced
2434 credentials are valid for context acceptor use only, because the
2435 caller lacks authorization to access the referenced credentials, or
2436 because the resolution of default credentials failed.
2438 o GSS_S_CREDENTIALS_EXPIRED indicates that the credentials provided
2439 through the input claimant_cred_handle argument are no longer valid,
2440 so context establishment cannot be completed.
2442 o GSS_S_BAD_BINDINGS indicates that a mismatch between the caller-
2443 provided chan_bindings and those extracted from the input_token was
2444 detected, signifying a security-relevant event and preventing context
2445 establishment. (This result will be returned by
2446 GSS_Init_sec_context() only for contexts where mutual_state is TRUE.)
2448 o GSS_S_OLD_TOKEN indicates that the input_token is too old to be
2449 checked for integrity. This is a fatal error during context
2452 o GSS_S_DUPLICATE_TOKEN indicates that the input token has a correct
2453 integrity check, but is a duplicate of a token already processed.
2454 This is a fatal error during context establishment.
2456 o GSS_S_NO_CONTEXT indicates that no valid context was recognized
2457 for the input context_handle provided; this major status will be
2458 returned only for successor calls following GSS_S_CONTINUE_ NEEDED
2466 Linn Standards Track [Page 44]
2468 RFC 2743 GSS-API January 2000
2471 o GSS_S_BAD_NAMETYPE indicates that the provided targ_name is of a
2472 type uninterpretable or unsupported by the applicable underlying
2473 GSS-API mechanism(s), so context establishment cannot be completed.
2475 o GSS_S_BAD_NAME indicates that the provided targ_name is
2476 inconsistent in terms of internally-incorporated type specifier
2477 information, so context establishment cannot be accomplished.
2479 o GSS_S_BAD_MECH indicates receipt of a context establishment token
2480 or of a caller request specifying a mechanism unsupported by the
2481 local system or with the caller's active credentials
2483 o GSS_S_FAILURE indicates that context setup could not be
2484 accomplished for reasons unspecified at the GSS-API level, and that
2485 no interface-defined recovery action is available.
2487 This routine is used by a context initiator, and ordinarily emits an
2488 output_token suitable for use by the target within the selected
2489 mech_type's protocol. For the case of a multi-step exchange, this
2490 output_token will be one in a series, each generated by a successive
2491 call. Using information in the credentials structure referenced by
2492 claimant_cred_handle, GSS_Init_sec_context() initializes the data
2493 structures required to establish a security context with target
2496 The targ_name may be any valid INTERNAL NAME; it need not be an MN.
2497 In addition to support for other name types, it is recommended (newly
2498 as of GSS-V2, Update 1) that mechanisms be able to accept
2499 GSS_C_NO_NAME as an input type for targ_name. While recommended,
2500 such support is not required, and it is recognized that not all
2501 mechanisms can construct tokens without explicitly naming the context
2502 target, even when mutual authentication of the target is not
2503 obtained. Callers wishing to make use of this facility and concerned
2504 with portability should be aware that support for GSS_C_NO_NAME as
2505 input targ_name type is unlikely to be provided within mechanism
2506 definitions specified prior to GSS-V2, Update 1.
2508 The claimant_cred_handle must correspond to the same valid
2509 credentials structure on the initial call to GSS_Init_sec_context()
2510 and on any successor calls resulting from GSS_S_CONTINUE_NEEDED
2511 status returns; different protocol sequences modeled by the
2512 GSS_S_CONTINUE_NEEDED facility will require access to credentials at
2513 different points in the context establishment sequence.
2515 The caller-provided input_context_handle argument is to be 0
2516 (GSS_C_NO_CONTEXT), specifying "not yet assigned", on the first
2517 GSS_Init_sec_context() call relating to a given context. If
2518 successful (i.e., if accompanied by major_status GSS_S_COMPLETE or
2522 Linn Standards Track [Page 45]
2524 RFC 2743 GSS-API January 2000
2527 GSS_S_CONTINUE_NEEDED), and only if successful, the initial
2528 GSS_Init_sec_context() call returns a non-zero output_context_handle
2529 for use in future references to this context. Once a non-zero
2530 output_context_handle has been returned, GSS-API callers should call
2531 GSS_Delete_sec_context() to release context-related resources if
2532 errors occur in later phases of context establishment, or when an
2533 established context is no longer required. If GSS_Init_sec_context()
2534 is passed the handle of a context which is already fully established,
2535 GSS_S_FAILURE status is returned.
2537 When continuation attempts to GSS_Init_sec_context() are needed to
2538 perform context establishment, the previously-returned non-zero
2539 handle value is entered into the input_context_handle argument and
2540 will be echoed in the returned output_context_handle argument. On
2541 such continuation attempts (and only on continuation attempts) the
2542 input_token value is used, to provide the token returned from the
2545 The chan_bindings argument is used by the caller to provide
2546 information binding the security context to security-related
2547 characteristics (e.g., addresses, cryptographic keys) of the
2548 underlying communications channel. See Section 1.1.6 of this document
2549 for more discussion of this argument's usage.
2551 The input_token argument contains a message received from the target,
2552 and is significant only on a call to GSS_Init_sec_context() which
2553 follows a previous return indicating GSS_S_CONTINUE_NEEDED
2556 It is the caller's responsibility to establish a communications path
2557 to the target, and to transmit any returned output_token (independent
2558 of the accompanying returned major_status value) to the target over
2559 that path. The output_token can, however, be transmitted along with
2560 the first application-provided input message to be processed by
2561 GSS_GetMIC() or GSS_Wrap() in conjunction with a successfully-
2562 established context. (Note: when the GSS-V2 prot_ready_state
2563 indicator is returned TRUE, it can be possible to transfer a
2564 protected message before context establishment is complete: see also
2567 The initiator may request various context-level functions through
2568 input flags: the deleg_req_flag requests delegation of access rights,
2569 the mutual_req_flag requests mutual authentication, the
2570 replay_det_req_flag requests that replay detection features be
2571 applied to messages transferred on the established context, and the
2572 sequence_req_flag requests that sequencing be enforced. (See Section
2578 Linn Standards Track [Page 46]
2580 RFC 2743 GSS-API January 2000
2583 1.2.3 for more information on replay detection and sequencing
2584 features.) The anon_req_flag requests that the initiator's identity
2585 not be transferred within tokens to be sent to the acceptor.
2587 The conf_req_flag and integ_req_flag provide informatory inputs to
2588 the GSS-API implementation as to whether, respectively, per-message
2589 confidentiality and per-message integrity services will be required
2590 on the context. This information is important as an input to
2591 negotiating mechanisms. It is important to recognize, however, that
2592 the inclusion of these flags (which are newly defined for GSS-V2)
2593 introduces a backward incompatibility with callers implemented to
2594 GSS-V1, where the flags were not defined. Since no GSS-V1 callers
2595 would set these flags, even if per-message services are desired,
2596 GSS-V2 mechanism implementations which enable such services
2597 selectively based on the flags' values may fail to provide them to
2598 contexts established for GSS-V1 callers. It may be appropriate under
2599 certain circumstances, therefore, for such mechanism implementations
2600 to infer these service request flags to be set if a caller is known
2601 to be implemented to GSS-V1.
2603 Not all of the optionally-requestable features will be available in
2604 all underlying mech_types. The corresponding return state values
2605 deleg_state, mutual_state, replay_det_state, and sequence_state
2606 indicate, as a function of mech_type processing capabilities and
2607 initiator-provided input flags, the set of features which will be
2608 active on the context. The returned trans_state value indicates
2609 whether the context is transferable to other processes through use of
2610 GSS_Export_sec_context(). These state indicators' values are
2611 undefined unless either the routine's major_status indicates
2612 GSS_S_COMPLETE, or TRUE prot_ready_state is returned along with
2613 GSS_S_CONTINUE_NEEDED major_status; for the latter case, it is
2614 possible that additional features, not confirmed or indicated along
2615 with TRUE prot_ready_state, will be confirmed and indicated when
2616 GSS_S_COMPLETE is subsequently returned.
2618 The returned anon_state and prot_ready_state values are significant
2619 for both GSS_S_COMPLETE and GSS_S_CONTINUE_NEEDED major_status
2620 returns from GSS_Init_sec_context(). When anon_state is returned
2621 TRUE, this indicates that neither the current token nor its
2622 predecessors delivers or has delivered the initiator's identity.
2623 Callers wishing to perform context establishment only if anonymity
2624 support is provided should transfer a returned token from
2625 GSS_Init_sec_context() to the peer only if it is accompanied by a
2626 TRUE anon_state indicator. When prot_ready_state is returned TRUE in
2627 conjunction with GSS_S_CONTINUE_NEEDED major_status, this indicates
2628 that per-message protection operations may be applied on the context:
2629 see Section 1.2.7 for further discussion of this facility.
2634 Linn Standards Track [Page 47]
2636 RFC 2743 GSS-API January 2000
2639 Failure to provide the precise set of features requested by the
2640 caller does not cause context establishment to fail; it is the
2641 caller's prerogative to delete the context if the feature set
2642 provided is unsuitable for the caller's use.
2644 The returned mech_type value indicates the specific mechanism
2645 employed on the context; it will never indicate the value for
2646 "default". A valid mech_type result must be returned along with a
2647 GSS_S_COMPLETE status return; GSS-API implementations may (but are
2648 not required to) also return mech_type along with predecessor calls
2649 indicating GSS_S_CONTINUE_NEEDED status or (if a mechanism is
2650 determinable) in conjunction with fatal error cases. For the case of
2651 mechanisms which themselves perform negotiation, the returned
2652 mech_type result may indicate selection of a mechanism identified by
2653 an OID different than that passed in the input mech_type argument,
2654 and the returned value may change between successive calls returning
2655 GSS_S_CONTINUE_NEEDED and the final call returning GSS_S_COMPLETE.
2657 The conf_avail return value indicates whether the context supports
2658 per-message confidentiality services, and so informs the caller
2659 whether or not a request for encryption through the conf_req_flag
2660 input to GSS_Wrap() can be honored. In similar fashion, the
2661 integ_avail return value indicates whether per-message integrity
2662 services are available (through either GSS_GetMIC() or GSS_Wrap()) on
2663 the established context. These state indicators' values are undefined
2664 unless either the routine's major_status indicates GSS_S_COMPLETE, or
2665 TRUE prot_ready_state is returned along with GSS_S_CONTINUE_NEEDED
2668 The lifetime_req input specifies a desired upper bound for the
2669 lifetime of the context to be established, with a value of 0 used to
2670 request a default lifetime. The lifetime_rec return value indicates
2671 the length of time for which the context will be valid, expressed as
2672 an offset from the present; depending on mechanism capabilities,
2673 credential lifetimes, and local policy, it may not correspond to the
2674 value requested in lifetime_req. If no constraints on context
2675 lifetime are imposed, this may be indicated by returning a reserved
2676 value representing INDEFINITE lifetime_req. The value of lifetime_rec
2677 is undefined unless the routine's major_status indicates
2680 If the mutual_state is TRUE, this fact will be reflected within the
2681 output_token. A call to GSS_Accept_sec_context() at the target in
2682 conjunction with such a context will return a token, to be processed
2683 by a continuation call to GSS_Init_sec_context(), in order to achieve
2684 mutual authentication.
2690 Linn Standards Track [Page 48]
2692 RFC 2743 GSS-API January 2000
2695 2.2.2: GSS_Accept_sec_context call
2699 o acceptor_cred_handle CREDENTIAL HANDLE, -- NULL specifies
2702 o input_context_handle CONTEXT HANDLE, -- 0
2703 -- (GSS_C_NO_CONTEXT) specifies "not yet assigned"
2705 o chan_bindings OCTET STRING,
2707 o input_token OCTET STRING
2711 o major_status INTEGER,
2713 o minor_status INTEGER,
2715 o src_name INTERNAL NAME, -- guaranteed to be MN
2716 -- once returned, caller must release with GSS_Release_name()
2718 o mech_type OBJECT IDENTIFIER, -- caller should treat as
2719 -- read-only; does not need to be released
2721 o output_context_handle CONTEXT HANDLE, -- once returned
2722 -- non-NULL in context establishment sequence, caller
2723 -- must release with GSS_Delete_sec_context()
2725 o deleg_state BOOLEAN,
2727 o mutual_state BOOLEAN,
2729 o replay_det_state BOOLEAN,
2731 o sequence_state BOOLEAN,
2733 o anon_state BOOLEAN,
2735 o trans_state BOOLEAN,
2737 o prot_ready_state BOOLEAN, -- see Section 1.2.7 for discussion
2739 o conf_avail BOOLEAN,
2741 o integ_avail BOOLEAN,
2746 Linn Standards Track [Page 49]
2748 RFC 2743 GSS-API January 2000
2751 o lifetime_rec INTEGER, -- in seconds, or reserved value for
2754 o delegated_cred_handle CREDENTIAL HANDLE, -- if returned non-NULL,
2755 -- caller must release with GSS_Release_cred()
2757 o output_token OCTET STRING -- NULL or token to pass to context
2758 -- initiator; if returned non-NULL, caller must release with
2759 -- GSS_Release_buffer()
2761 This call may block pending network interactions for those mech_types
2762 in which a directory service or other network entity must be
2763 consulted on behalf of a context acceptor in order to validate a
2764 received input_token.
2766 Return major_status codes:
2768 o GSS_S_COMPLETE indicates that context-level data structures were
2769 successfully initialized, and that per-message processing can now be
2770 performed in conjunction with this context.
2772 o GSS_S_CONTINUE_NEEDED indicates that control information in the
2773 returned output_token must be sent to the initiator, and that a
2774 response must be received and passed as the input_token argument to a
2775 continuation call to GSS_Accept_sec_context(), before per-message
2776 processing can be performed in conjunction with this context.
2778 o GSS_S_DEFECTIVE_TOKEN indicates that consistency checks performed
2779 on the input_token failed, preventing further processing from being
2780 performed based on that token.
2782 o GSS_S_DEFECTIVE_CREDENTIAL indicates that consistency checks
2783 performed on the credential structure referenced by
2784 acceptor_cred_handle failed, preventing further processing from being
2785 performed using that credential structure.
2787 o GSS_S_BAD_SIG (GSS_S_BAD_MIC) indicates that the received
2788 input_token contains an incorrect integrity check, so context setup
2789 cannot be accomplished.
2791 o GSS_S_DUPLICATE_TOKEN indicates that the integrity check on the
2792 received input_token was correct, but that the input_token was
2793 recognized as a duplicate of an input_token already processed. No new
2794 context is established.
2802 Linn Standards Track [Page 50]
2804 RFC 2743 GSS-API January 2000
2807 o GSS_S_OLD_TOKEN indicates that the integrity check on the received
2808 input_token was correct, but that the input_token is too old to be
2809 checked for duplication against previously-processed input_tokens. No
2810 new context is established.
2812 o GSS_S_NO_CRED indicates that no context was established, either
2813 because the input cred_handle was invalid, because the referenced
2814 credentials are valid for context initiator use only, because the
2815 caller lacks authorization to access the referenced credentials, or
2816 because the procedure for default credential resolution failed.
2818 o GSS_S_CREDENTIALS_EXPIRED indicates that the credentials provided
2819 through the input acceptor_cred_handle argument are no longer valid,
2820 so context establishment cannot be completed.
2822 o GSS_S_BAD_BINDINGS indicates that a mismatch between the caller-
2823 provided chan_bindings and those extracted from the input_token was
2824 detected, signifying a security-relevant event and preventing context
2827 o GSS_S_NO_CONTEXT indicates that no valid context was recognized
2828 for the input context_handle provided; this major status will be
2829 returned only for successor calls following GSS_S_CONTINUE_ NEEDED
2832 o GSS_S_BAD_MECH indicates receipt of a context establishment token
2833 specifying a mechanism unsupported by the local system or with the
2834 caller's active credentials.
2836 o GSS_S_FAILURE indicates that context setup could not be
2837 accomplished for reasons unspecified at the GSS-API level, and that
2838 no interface-defined recovery action is available.
2840 The GSS_Accept_sec_context() routine is used by a context target.
2841 Using information in the credentials structure referenced by the
2842 input acceptor_cred_handle, it verifies the incoming input_token and
2843 (following the successful completion of a context establishment
2844 sequence) returns the authenticated src_name and the mech_type used.
2845 The returned src_name is guaranteed to be an MN, processed by the
2846 mechanism under which the context was established. The
2847 acceptor_cred_handle must correspond to the same valid credentials
2848 structure on the initial call to GSS_Accept_sec_context() and on any
2849 successor calls resulting from GSS_S_CONTINUE_NEEDED status returns;
2850 different protocol sequences modeled by the GSS_S_CONTINUE_NEEDED
2851 mechanism will require access to credentials at different points in
2852 the context establishment sequence.
2858 Linn Standards Track [Page 51]
2860 RFC 2743 GSS-API January 2000
2863 The caller-provided input_context_handle argument is to be 0
2864 (GSS_C_NO_CONTEXT), specifying "not yet assigned", on the first
2865 GSS_Accept_sec_context() call relating to a given context. If
2866 successful (i.e., if accompanied by major_status GSS_S_COMPLETE or
2867 GSS_S_CONTINUE_NEEDED), and only if successful, the initial
2868 GSS_Accept_sec_context() call returns a non-zero
2869 output_context_handle for use in future references to this context.
2870 Once a non-zero output_context_handle has been returned, GSS-API
2871 callers should call GSS_Delete_sec_context() to release context-
2872 related resources if errors occur in later phases of context
2873 establishment, or when an established context is no longer required.
2874 If GSS_Accept_sec_context() is passed the handle of a context which
2875 is already fully established, GSS_S_FAILURE status is returned.
2877 The chan_bindings argument is used by the caller to provide
2878 information binding the security context to security-related
2879 characteristics (e.g., addresses, cryptographic keys) of the
2880 underlying communications channel. See Section 1.1.6 of this document
2881 for more discussion of this argument's usage.
2883 The returned state results (deleg_state, mutual_state,
2884 replay_det_state, sequence_state, anon_state, trans_state, and
2885 prot_ready_state) reflect the same information as described for
2886 GSS_Init_sec_context(), and their values are significant under the
2887 same return state conditions.
2889 The conf_avail return value indicates whether the context supports
2890 per-message confidentiality services, and so informs the caller
2891 whether or not a request for encryption through the conf_req_flag
2892 input to GSS_Wrap() can be honored. In similar fashion, the
2893 integ_avail return value indicates whether per-message integrity
2894 services are available (through either GSS_GetMIC() or GSS_Wrap())
2895 on the established context. These values are significant under the
2896 same return state conditions as described under
2897 GSS_Init_sec_context().
2899 The lifetime_rec return value is significant only in conjunction with
2900 GSS_S_COMPLETE major_status, and indicates the length of time for
2901 which the context will be valid, expressed as an offset from the
2904 The returned mech_type value indicates the specific mechanism
2905 employed on the context; it will never indicate the value for
2906 "default". A valid mech_type result must be returned whenever
2907 GSS_S_COMPLETE status is indicated; GSS-API implementations may (but
2908 are not required to) also return mech_type along with predecessor
2909 calls indicating GSS_S_CONTINUE_NEEDED status or (if a mechanism is
2910 determinable) in conjunction with fatal error cases. For the case of
2914 Linn Standards Track [Page 52]
2916 RFC 2743 GSS-API January 2000
2919 mechanisms which themselves perform negotiation, the returned
2920 mech_type result may indicate selection of a mechanism identified by
2921 an OID different than that passed in the input mech_type argument,
2922 and the returned value may change between successive calls returning
2923 GSS_S_CONTINUE_NEEDED and the final call returning GSS_S_COMPLETE.
2925 The delegated_cred_handle result is significant only when deleg_state
2926 is TRUE, and provides a means for the target to reference the
2927 delegated credentials. The output_token result, when non-NULL,
2928 provides a context-level token to be returned to the context
2929 initiator to continue a multi-step context establishment sequence. As
2930 noted with GSS_Init_sec_context(), any returned token should be
2931 transferred to the context's peer (in this case, the context
2932 initiator), independent of the value of the accompanying returned
2935 Note: A target must be able to distinguish a context-level
2936 input_token, which is passed to GSS_Accept_sec_context(), from the
2937 per-message data elements passed to GSS_VerifyMIC() or GSS_Unwrap().
2938 These data elements may arrive in a single application message, and
2939 GSS_Accept_sec_context() must be performed before per-message
2940 processing can be performed successfully.
2942 2.2.3: GSS_Delete_sec_context call
2946 o context_handle CONTEXT HANDLE
2950 o major_status INTEGER,
2952 o minor_status INTEGER,
2954 o output_context_token OCTET STRING
2956 Return major_status codes:
2958 o GSS_S_COMPLETE indicates that the context was recognized, and that
2959 relevant context-specific information was flushed. If the caller
2960 provides a non-null buffer to receive an output_context_token, and
2961 the mechanism returns a non-NULL token into that buffer, the returned
2962 output_context_token is ready for transfer to the context's peer.
2964 o GSS_S_NO_CONTEXT indicates that no valid context was recognized
2965 for the input context_handle provided, so no deletion was performed.
2970 Linn Standards Track [Page 53]
2972 RFC 2743 GSS-API January 2000
2975 o GSS_S_FAILURE indicates that the context is recognized, but that
2976 the GSS_Delete_sec_context() operation could not be performed for
2977 reasons unspecified at the GSS-API level.
2979 This call can be made by either peer in a security context, to flush
2980 context-specific information. Once a non-zero output_context_handle
2981 has been returned by context establishment calls, GSS-API callers
2982 should call GSS_Delete_sec_context() to release context-related
2983 resources if errors occur in later phases of context establishment,
2984 or when an established context is no longer required. This call may
2985 block pending network interactions for mech_types in which active
2986 notification must be made to a central server when a security context
2989 If a non-null output_context_token parameter is provided by the
2990 caller, an output_context_token may be returned to the caller. If an
2991 output_context_token is provided to the caller, it can be passed to
2992 the context's peer to inform the peer's GSS-API implementation that
2993 the peer's corresponding context information can also be flushed.
2994 (Once a context is established, the peers involved are expected to
2995 retain cached credential and context-related information until the
2996 information's expiration time is reached or until a
2997 GSS_Delete_sec_context() call is made.)
2999 The facility for context_token usage to signal context deletion is
3000 retained for compatibility with GSS-API Version 1. For current
3001 usage, it is recommended that both peers to a context invoke
3002 GSS_Delete_sec_context() independently, passing a null
3003 output_context_token buffer to indicate that no context_token is
3004 required. Implementations of GSS_Delete_sec_context() should delete
3005 relevant locally-stored context information.
3007 Attempts to perform per-message processing on a deleted context will
3008 result in error returns.
3010 2.2.4: GSS_Process_context_token call
3014 o context_handle CONTEXT HANDLE,
3016 o input_context_token OCTET STRING
3020 o major_status INTEGER,
3022 o minor_status INTEGER,
3026 Linn Standards Track [Page 54]
3028 RFC 2743 GSS-API January 2000
3031 Return major_status codes:
3033 o GSS_S_COMPLETE indicates that the input_context_token was
3034 successfully processed in conjunction with the context referenced by
3037 o GSS_S_DEFECTIVE_TOKEN indicates that consistency checks performed
3038 on the received context_token failed, preventing further processing
3039 from being performed with that token.
3041 o GSS_S_NO_CONTEXT indicates that no valid context was recognized
3042 for the input context_handle provided.
3044 o GSS_S_FAILURE indicates that the context is recognized, but that
3045 the GSS_Process_context_token() operation could not be performed for
3046 reasons unspecified at the GSS-API level.
3048 This call is used to process context_tokens received from a peer once
3049 a context has been established, with corresponding impact on
3050 context-level state information. One use for this facility is
3051 processing of the context_tokens generated by
3052 GSS_Delete_sec_context(); GSS_Process_context_token() will not block
3053 pending network interactions for that purpose. Another use is to
3054 process tokens indicating remote-peer context establishment failures
3055 after the point where the local GSS-API implementation has already
3056 indicated GSS_S_COMPLETE status.
3058 2.2.5: GSS_Context_time call
3062 o context_handle CONTEXT HANDLE,
3066 o major_status INTEGER,
3068 o minor_status INTEGER,
3070 o lifetime_rec INTEGER -- in seconds, or reserved value for
3073 Return major_status codes:
3075 o GSS_S_COMPLETE indicates that the referenced context is valid, and
3076 will remain valid for the amount of time indicated in lifetime_rec.
3082 Linn Standards Track [Page 55]
3084 RFC 2743 GSS-API January 2000
3087 o GSS_S_CONTEXT_EXPIRED indicates that data items related to the
3088 referenced context have expired.
3090 o GSS_S_NO_CONTEXT indicates that no valid context was recognized
3091 for the input context_handle provided.
3093 o GSS_S_FAILURE indicates that the requested operation failed for
3094 reasons unspecified at the GSS-API level.
3096 This call is used to determine the amount of time for which a
3097 currently established context will remain valid.
3099 2.2.6: GSS_Inquire_context call
3103 o context_handle CONTEXT HANDLE,
3107 o major_status INTEGER,
3109 o minor_status INTEGER,
3111 o src_name INTERNAL NAME, -- name of context initiator,
3112 -- guaranteed to be MN;
3113 -- caller must release with GSS_Release_name() if returned
3115 o targ_name INTERNAL NAME, -- name of context target,
3116 -- guaranteed to be MN;
3117 -- caller must release with GSS_Release_name() if returned
3119 o lifetime_rec INTEGER -- in seconds, or reserved value for
3120 -- INDEFINITE or EXPIRED
3122 o mech_type OBJECT IDENTIFIER, -- the mechanism supporting this
3123 -- security context; caller should treat as read-only and not
3124 -- attempt to release
3126 o deleg_state BOOLEAN,
3128 o mutual_state BOOLEAN,
3130 o replay_det_state BOOLEAN,
3132 o sequence_state BOOLEAN,
3134 o anon_state BOOLEAN,
3138 Linn Standards Track [Page 56]
3140 RFC 2743 GSS-API January 2000
3143 o trans_state BOOLEAN,
3145 o prot_ready_state BOOLEAN,
3147 o conf_avail BOOLEAN,
3149 o integ_avail BOOLEAN,
3151 o locally_initiated BOOLEAN, -- TRUE if initiator, FALSE if acceptor
3153 o open BOOLEAN, -- TRUE if context fully established, FALSE
3154 -- if partly established (in CONTINUE_NEEDED state)
3156 Return major_status codes:
3158 o GSS_S_COMPLETE indicates that the referenced context is valid and
3159 that deleg_state, mutual_state, replay_det_state, sequence_state,
3160 anon_state, trans_state, prot_ready_state, conf_avail, integ_avail,
3161 locally_initiated, and open return values describe the corresponding
3162 characteristics of the context. If open is TRUE, lifetime_rec is
3163 also returned: if open is TRUE and the context peer's name is known,
3164 src_name and targ_name are valid in addition to the values listed
3165 above. The mech_type value must be returned for contexts where open
3166 is TRUE and may be returned for contexts where open is FALSE.
3168 o GSS_S_NO_CONTEXT indicates that no valid context was recognized
3169 for the input context_handle provided. Return values other than
3170 major_status and minor_status are undefined.
3172 o GSS_S_FAILURE indicates that the requested operation failed for
3173 reasons unspecified at the GSS-API level. Return values other than
3174 major_status and minor_status are undefined.
3176 This call is used to extract information describing characteristics
3177 of a security context. Note that GSS-API implementations are
3178 expected to retain inquirable context data on a context until the
3179 context is released by a caller, even after the context has expired,
3180 although underlying cryptographic data elements may be deleted after
3181 expiration in order to limit their exposure.
3183 2.2.7: GSS_Wrap_size_limit call
3187 o context_handle CONTEXT HANDLE,
3189 o conf_req_flag BOOLEAN,
3194 Linn Standards Track [Page 57]
3196 RFC 2743 GSS-API January 2000
3201 o output_size INTEGER
3205 o major_status INTEGER,
3207 o minor_status INTEGER,
3209 o max_input_size INTEGER
3211 Return major_status codes:
3213 o GSS_S_COMPLETE indicates a successful token size determination:
3214 an input message with a length in octets equal to the returned
3215 max_input_size value will, when passed to GSS_Wrap() for processing
3216 on the context identified by the context_handle parameter with the
3217 confidentiality request state as provided in conf_req_flag and with
3218 the quality of protection specifier provided in the qop parameter,
3219 yield an output token no larger than the value of the provided
3220 output_size parameter.
3222 o GSS_S_CONTEXT_EXPIRED indicates that the provided input
3223 context_handle is recognized, but that the referenced context has
3224 expired. Return values other than major_status and minor_status are
3227 o GSS_S_NO_CONTEXT indicates that no valid context was recognized
3228 for the input context_handle provided. Return values other than
3229 major_status and minor_status are undefined.
3231 o GSS_S_BAD_QOP indicates that the provided QOP value is not
3232 recognized or supported for the context.
3234 o GSS_S_FAILURE indicates that the requested operation failed for
3235 reasons unspecified at the GSS-API level. Return values other than
3236 major_status and minor_status are undefined.
3238 This call is used to determine the largest input datum which may be
3239 passed to GSS_Wrap() without yielding an output token larger than a
3240 caller-specified value.
3250 Linn Standards Track [Page 58]
3252 RFC 2743 GSS-API January 2000
3255 2.2.8: GSS_Export_sec_context call
3259 o context_handle CONTEXT HANDLE
3263 o major_status INTEGER,
3265 o minor_status INTEGER,
3267 o interprocess_token OCTET STRING -- caller must release
3268 -- with GSS_Release_buffer()
3270 Return major_status codes:
3272 o GSS_S_COMPLETE indicates that the referenced context has been
3273 successfully exported to a representation in the interprocess_token,
3274 and is no longer available for use by the caller.
3276 o GSS_S_UNAVAILABLE indicates that the context export facility is
3277 not available for use on the referenced context. (This status should
3278 occur only for contexts for which the trans_state value is FALSE.)
3279 Return values other than major_status and minor_status are undefined.
3281 o GSS_S_CONTEXT_EXPIRED indicates that the provided input
3282 context_handle is recognized, but that the referenced context has
3283 expired. Return values other than major_status and minor_status are
3286 o GSS_S_NO_CONTEXT indicates that no valid context was recognized
3287 for the input context_handle provided. Return values other than
3288 major_status and minor_status are undefined.
3290 o GSS_S_FAILURE indicates that the requested operation failed for
3291 reasons unspecified at the GSS-API level. Return values other than
3292 major_status and minor_status are undefined.
3294 This call generates an interprocess token for transfer to another
3295 process within an end system, in order to transfer control of a
3296 security context to that process. The recipient of the interprocess
3297 token will call GSS_Import_sec_context() to accept the transfer. The
3298 GSS_Export_sec_context() operation is defined for use only with
3299 security contexts which are fully and successfully established (i.e.,
3300 those for which GSS_Init_sec_context() and GSS_Accept_sec_context()
3301 have returned GSS_S_COMPLETE major_status).
3306 Linn Standards Track [Page 59]
3308 RFC 2743 GSS-API January 2000
3311 A successful GSS_Export_sec_context() operation deactivates the
3312 security context for the calling process; for this case, the GSS-API
3313 implementation shall deallocate all process-wide resources associated
3314 with the security context and shall set the context_handle to
3315 GSS_C_NO_CONTEXT. In the event of an error that makes it impossible
3316 to complete export of the security context, the GSS-API
3317 implementation must not return an interprocess token and should
3318 strive to leave the security context referenced by the context_handle
3319 untouched. If this is impossible, it is permissible for the
3320 implementation to delete the security context, provided that it also
3321 sets the context_handle parameter to GSS_C_NO_CONTEXT.
3323 Portable callers must not assume that a given interprocess token can
3324 be imported by GSS_Import_sec_context() more than once, thereby
3325 creating multiple instantiations of a single context. GSS-API
3326 implementations may detect and reject attempted multiple imports, but
3327 are not required to do so.
3329 The internal representation contained within the interprocess token
3330 is an implementation-defined local matter. Interprocess tokens
3331 cannot be assumed to be transferable across different GSS-API
3334 It is recommended that GSS-API implementations adopt policies suited
3335 to their operational environments in order to define the set of
3336 processes eligible to import a context, but specific constraints in
3337 this area are local matters. Candidate examples include transfers
3338 between processes operating on behalf of the same user identity, or
3339 processes comprising a common job. However, it may be impossible to
3340 enforce such policies in some implementations.
3342 In support of the above goals, implementations may protect the
3343 transferred context data by using cryptography to protect data within
3344 the interprocess token, or by using interprocess tokens as a means to
3345 reference local interprocess communication facilities (protected by
3346 other means) rather than storing the context data directly within the
3349 Transfer of an open context may, for certain mechanisms and
3350 implementations, reveal data about the credential which was used to
3351 establish the context. Callers should, therefore, be cautious about
3352 the trustworthiness of processes to which they transfer contexts.
3353 Although the GSS-API implementation may provide its own set of
3354 protections over the exported context, the caller is responsible for
3355 protecting the interprocess token from disclosure, and for taking
3356 care that the context is transferred to an appropriate destination
3362 Linn Standards Track [Page 60]
3364 RFC 2743 GSS-API January 2000
3367 2.2.9: GSS_Import_sec_context call
3371 o interprocess_token OCTET STRING
3375 o major_status INTEGER,
3377 o minor_status INTEGER,
3379 o context_handle CONTEXT HANDLE -- if successfully returned,
3380 -- caller must release with GSS_Delete_sec_context()
3382 Return major_status codes:
3384 o GSS_S_COMPLETE indicates that the context represented by the input
3385 interprocess_token has been successfully transferred to the caller,
3386 and is available for future use via the output context_handle.
3388 o GSS_S_NO_CONTEXT indicates that the context represented by the
3389 input interprocess_token was invalid. Return values other than
3390 major_status and minor_status are undefined.
3392 o GSS_S_DEFECTIVE_TOKEN indicates that the input interprocess_token
3393 was defective. Return values other than major_status and
3394 minor_status are undefined.
3396 o GSS_S_UNAVAILABLE indicates that the context import facility is
3397 not available for use on the referenced context. Return values other
3398 than major_status and minor_status are undefined.
3400 o GSS_S_UNAUTHORIZED indicates that the context represented by the
3401 input interprocess_token is unauthorized for transfer to the caller.
3402 Return values other than major_status and minor_status are undefined.
3404 o GSS_S_FAILURE indicates that the requested operation failed for
3405 reasons unspecified at the GSS-API level. Return values other than
3406 major_status and minor_status are undefined.
3408 This call processes an interprocess token generated by
3409 GSS_Export_sec_context(), making the transferred context available
3410 for use by the caller. After a successful GSS_Import_sec_context()
3411 operation, the imported context is available for use by the importing
3412 process. In particular, the imported context is usable for all per-
3413 message operations and may be deleted or exported by its importer.
3414 The inability to receive delegated credentials through
3418 Linn Standards Track [Page 61]
3420 RFC 2743 GSS-API January 2000
3423 gss_import_sec_context() precludes establishment of new contexts
3424 based on information delegated to the importer's end system within
3425 the context which is being imported, unless those delegated
3426 credentials are obtained through separate routines (e.g., XGSS-API
3427 calls) outside the GSS-V2 definition.
3429 For further discussion of the security and authorization issues
3430 regarding this call, please see the discussion in Section 2.2.8.
3432 2.3: Per-message calls
3434 This group of calls is used to perform per-message protection
3435 processing on an established security context. None of these calls
3436 block pending network interactions. These calls may be invoked by a
3437 context's initiator or by the context's target. The four members of
3438 this group should be considered as two pairs; the output from
3439 GSS_GetMIC() is properly input to GSS_VerifyMIC(), and the output
3440 from GSS_Wrap() is properly input to GSS_Unwrap().
3442 GSS_GetMIC() and GSS_VerifyMIC() support data origin authentication
3443 and data integrity services. When GSS_GetMIC() is invoked on an input
3444 message, it yields a per-message token containing data items which
3445 allow underlying mechanisms to provide the specified security
3446 services. The original message, along with the generated per-message
3447 token, is passed to the remote peer; these two data elements are
3448 processed by GSS_VerifyMIC(), which validates the message in
3449 conjunction with the separate token.
3451 GSS_Wrap() and GSS_Unwrap() support caller-requested confidentiality
3452 in addition to the data origin authentication and data integrity
3453 services offered by GSS_GetMIC() and GSS_VerifyMIC(). GSS_Wrap()
3454 outputs a single data element, encapsulating optionally enciphered
3455 user data as well as associated token data items. The data element
3456 output from GSS_Wrap() is passed to the remote peer and processed by
3457 GSS_Unwrap() at that system. GSS_Unwrap() combines decipherment (as
3458 required) with validation of data items related to authentication and
3461 Although zero-length tokens are never returned by GSS calls for
3462 transfer to a context's peer, a zero-length object may be passed by a
3463 caller into GSS_Wrap(), in which case the corresponding peer calling
3464 GSS_Unwrap() on the transferred token will receive a zero-length
3465 object as output from GSS_Unwrap(). Similarly, GSS_GetMIC() can be
3466 called on an empty object, yielding a MIC which GSS_VerifyMIC() will
3467 successfully verify against the active security context in
3468 conjunction with a zero-length object.
3474 Linn Standards Track [Page 62]
3476 RFC 2743 GSS-API January 2000
3479 2.3.1: GSS_GetMIC call
3481 Note: This call is functionally equivalent to the GSS_Sign call as
3482 defined in previous versions of this specification. In the interests
3483 of backward compatibility, it is recommended that implementations
3484 support this function under both names for the present; future
3485 references to this function as GSS_Sign are deprecated.
3489 o context_handle CONTEXT HANDLE,
3491 o qop_req INTEGER, -- 0 specifies default QOP
3493 o message OCTET STRING
3497 o major_status INTEGER,
3499 o minor_status INTEGER,
3501 o per_msg_token OCTET STRING -- caller must release
3502 -- with GSS_Release_buffer()
3504 Return major_status codes:
3506 o GSS_S_COMPLETE indicates that an integrity check, suitable for an
3507 established security context, was successfully applied and that the
3508 message and corresponding per_msg_token are ready for transmission.
3510 o GSS_S_CONTEXT_EXPIRED indicates that context-related data items
3511 have expired, so that the requested operation cannot be performed.
3513 o GSS_S_NO_CONTEXT indicates that no context was recognized for the
3514 input context_handle provided.
3516 o GSS_S_BAD_QOP indicates that the provided QOP value is not
3517 recognized or supported for the context.
3519 o GSS_S_FAILURE indicates that the context is recognized, but that
3520 the requested operation could not be performed for reasons
3521 unspecified at the GSS-API level.
3523 Using the security context referenced by context_handle, apply an
3524 integrity check to the input message (along with timestamps and/or
3525 other data included in support of mech_type-specific mechanisms) and
3526 (if GSS_S_COMPLETE status is indicated) return the result in
3530 Linn Standards Track [Page 63]
3532 RFC 2743 GSS-API January 2000
3535 per_msg_token. The qop_req parameter, interpretation of which is
3536 discussed in Section 1.2.4, allows quality-of-protection control. The
3537 caller passes the message and the per_msg_token to the target.
3539 The GSS_GetMIC() function completes before the message and
3540 per_msg_token is sent to the peer; successful application of
3541 GSS_GetMIC() does not guarantee that a corresponding GSS_VerifyMIC()
3542 has been (or can necessarily be) performed successfully when the
3543 message arrives at the destination.
3545 Mechanisms which do not support per-message protection services
3546 should return GSS_S_FAILURE if this routine is called.
3548 2.3.2: GSS_VerifyMIC call
3550 Note: This call is functionally equivalent to the GSS_Verify call as
3551 defined in previous versions of this specification. In the interests
3552 of backward compatibility, it is recommended that implementations
3553 support this function under both names for the present; future
3554 references to this function as GSS_Verify are deprecated.
3558 o context_handle CONTEXT HANDLE,
3560 o message OCTET STRING,
3562 o per_msg_token OCTET STRING
3566 o qop_state INTEGER,
3568 o major_status INTEGER,
3570 o minor_status INTEGER,
3572 Return major_status codes:
3574 o GSS_S_COMPLETE indicates that the message was successfully
3577 o GSS_S_DEFECTIVE_TOKEN indicates that consistency checks performed
3578 on the received per_msg_token failed, preventing further processing
3579 from being performed with that token.
3581 o GSS_S_BAD_SIG (GSS_S_BAD_MIC) indicates that the received
3582 per_msg_token contains an incorrect integrity check for the message.
3586 Linn Standards Track [Page 64]
3588 RFC 2743 GSS-API January 2000
3591 o GSS_S_DUPLICATE_TOKEN, GSS_S_OLD_TOKEN, GSS_S_UNSEQ_TOKEN, and
3592 GSS_S_GAP_TOKEN values appear in conjunction with the optional per-
3593 message replay detection features described in Section 1.2.3; their
3594 semantics are described in that section.
3596 o GSS_S_CONTEXT_EXPIRED indicates that context-related data items
3597 have expired, so that the requested operation cannot be performed.
3599 o GSS_S_NO_CONTEXT indicates that no context was recognized for the
3600 input context_handle provided.
3602 o GSS_S_FAILURE indicates that the context is recognized, but that
3603 the GSS_VerifyMIC() operation could not be performed for reasons
3604 unspecified at the GSS-API level.
3606 Using the security context referenced by context_handle, verify that
3607 the input per_msg_token contains an appropriate integrity check for
3608 the input message, and apply any active replay detection or
3609 sequencing features. Returns an indication of the quality-of-
3610 protection applied to the processed message in the qop_state result.
3612 Mechanisms which do not support per-message protection services
3613 should return GSS_S_FAILURE if this routine is called.
3615 2.3.3: GSS_Wrap call
3617 Note: This call is functionally equivalent to the GSS_Seal call as
3618 defined in previous versions of this specification. In the interests
3619 of backward compatibility, it is recommended that implementations
3620 support this function under both names for the present; future
3621 references to this function as GSS_Seal are deprecated.
3625 o context_handle CONTEXT HANDLE,
3627 o conf_req_flag BOOLEAN,
3629 o qop_req INTEGER, -- 0 specifies default QOP
3631 o input_message OCTET STRING
3635 o major_status INTEGER,
3637 o minor_status INTEGER,
3642 Linn Standards Track [Page 65]
3644 RFC 2743 GSS-API January 2000
3647 o conf_state BOOLEAN,
3649 o output_message OCTET STRING -- caller must release with
3650 -- GSS_Release_buffer()
3652 Return major_status codes:
3654 o GSS_S_COMPLETE indicates that the input_message was successfully
3655 processed and that the output_message is ready for transmission.
3657 o GSS_S_CONTEXT_EXPIRED indicates that context-related data items
3658 have expired, so that the requested operation cannot be performed.
3660 o GSS_S_NO_CONTEXT indicates that no context was recognized for the
3661 input context_handle provided.
3663 o GSS_S_BAD_QOP indicates that the provided QOP value is not
3664 recognized or supported for the context.
3666 o GSS_S_FAILURE indicates that the context is recognized, but that
3667 the GSS_Wrap() operation could not be performed for reasons
3668 unspecified at the GSS-API level.
3670 Performs the data origin authentication and data integrity functions
3671 of GSS_GetMIC(). If the input conf_req_flag is TRUE, requests that
3672 confidentiality be applied to the input_message. Confidentiality may
3673 not be supported in all mech_types or by all implementations; the
3674 returned conf_state flag indicates whether confidentiality was
3675 provided for the input_message. The qop_req parameter, interpretation
3676 of which is discussed in Section 1.2.4, allows quality-of-protection
3679 When GSS_S_COMPLETE status is returned, the GSS_Wrap() call yields a
3680 single output_message data element containing (optionally enciphered)
3681 user data as well as control information.
3683 Mechanisms which do not support per-message protection services
3684 should return GSS_S_FAILURE if this routine is called.
3686 2.3.4: GSS_Unwrap call
3688 Note: This call is functionally equivalent to the GSS_Unseal call as
3689 defined in previous versions of this specification. In the interests
3690 of backward compatibility, it is recommended that implementations
3691 support this function under both names for the present; future
3692 references to this function as GSS_Unseal are deprecated.
3698 Linn Standards Track [Page 66]
3700 RFC 2743 GSS-API January 2000
3705 o context_handle CONTEXT HANDLE,
3707 o input_message OCTET STRING
3711 o conf_state BOOLEAN,
3713 o qop_state INTEGER,
3715 o major_status INTEGER,
3717 o minor_status INTEGER,
3719 o output_message OCTET STRING -- caller must release with
3720 -- GSS_Release_buffer()
3722 Return major_status codes:
3724 o GSS_S_COMPLETE indicates that the input_message was successfully
3725 processed and that the resulting output_message is available.
3727 o GSS_S_DEFECTIVE_TOKEN indicates that consistency checks performed
3728 on the per_msg_token extracted from the input_message failed,
3729 preventing further processing from being performed.
3731 o GSS_S_BAD_SIG (GSS_S_BAD_MIC) indicates that an incorrect
3732 integrity check was detected for the message.
3734 o GSS_S_DUPLICATE_TOKEN, GSS_S_OLD_TOKEN, GSS_S_UNSEQ_TOKEN, and
3735 GSS_S_GAP_TOKEN values appear in conjunction with the optional per-
3736 message replay detection features described in Section 1.2.3; their
3737 semantics are described in that section.
3739 o GSS_S_CONTEXT_EXPIRED indicates that context-related data items
3740 have expired, so that the requested operation cannot be performed.
3742 o GSS_S_NO_CONTEXT indicates that no context was recognized for the
3743 input context_handle provided.
3745 o GSS_S_FAILURE indicates that the context is recognized, but that
3746 the GSS_Unwrap() operation could not be performed for reasons
3747 unspecified at the GSS-API level.
3754 Linn Standards Track [Page 67]
3756 RFC 2743 GSS-API January 2000
3759 Processes a data element generated (and optionally enciphered) by
3760 GSS_Wrap(), provided as input_message. The returned conf_state value
3761 indicates whether confidentiality was applied to the input_message.
3762 If conf_state is TRUE, GSS_Unwrap() has deciphered the input_message.
3763 Returns an indication of the quality-of-protection applied to the
3764 processed message in the qop_state result. GSS_Unwrap() performs the
3765 data integrity and data origin authentication checking functions of
3766 GSS_VerifyMIC() on the plaintext data. Plaintext data is returned in
3769 Mechanisms which do not support per-message protection services
3770 should return GSS_S_FAILURE if this routine is called.
3774 This group of calls provides support functions useful to GSS-API
3775 callers, independent of the state of established contexts. Their
3776 characterization with regard to blocking or non-blocking status in
3777 terms of network interactions is unspecified.
3779 2.4.1: GSS_Display_status call
3783 o status_value INTEGER, -- GSS-API major_status or minor_status
3786 o status_type INTEGER, -- 1 if major_status, 2 if minor_status
3788 o mech_type OBJECT IDENTIFIER -- mech_type to be used for
3789 -- minor_status translation
3793 o major_status INTEGER,
3795 o minor_status INTEGER,
3797 o status_string_set SET OF OCTET STRING -- required calls for
3798 -- release by caller are specific to language bindings
3800 Return major_status codes:
3802 o GSS_S_COMPLETE indicates that a valid printable status
3803 representation (possibly representing more than one status event
3804 encoded within the status_value) is available in the returned
3810 Linn Standards Track [Page 68]
3812 RFC 2743 GSS-API January 2000
3815 o GSS_S_BAD_MECH indicates that translation in accordance with an
3816 unsupported mech_type was requested, so translation could not be
3819 o GSS_S_BAD_STATUS indicates that the input status_value was
3820 invalid, or that the input status_type carried a value other than 1
3821 or 2, so translation could not be performed.
3823 o GSS_S_FAILURE indicates that the requested operation could not be
3824 performed for reasons unspecified at the GSS-API level.
3826 Provides a means for callers to translate GSS-API-returned major and
3827 minor status codes into printable string representations. Note: some
3828 language bindings may employ an iterative approach in order to emit
3829 successive status components; this approach is acceptable but not
3830 required for conformance with the current specification.
3832 Although not contemplated in [RFC-2078], it has been observed that
3833 some existing GSS-API implementations return GSS_S_CONTINUE_NEEDED
3834 status when iterating through successive messages returned from
3835 GSS_Display_status(). This behavior is deprecated;
3836 GSS_S_CONTINUE_NEEDED should be returned only by
3837 GSS_Init_sec_context() and GSS_Accept_sec_context(). For maximal
3838 portability, however, it is recommended that defensive callers be
3839 able to accept and ignore GSS_S_CONTINUE_NEEDED status if indicated
3840 by GSS_Display_status() or any other call other than
3841 GSS_Init_sec_context() or GSS_Accept_sec_context().
3843 2.4.2: GSS_Indicate_mechs call
3851 o major_status INTEGER,
3853 o minor_status INTEGER,
3855 o mech_set SET OF OBJECT IDENTIFIER -- caller must release
3856 -- with GSS_Release_oid_set()
3858 Return major_status codes:
3860 o GSS_S_COMPLETE indicates that a set of available mechanisms has
3861 been returned in mech_set.
3866 Linn Standards Track [Page 69]
3868 RFC 2743 GSS-API January 2000
3871 o GSS_S_FAILURE indicates that the requested operation could not be
3872 performed for reasons unspecified at the GSS-API level.
3874 Allows callers to determine the set of mechanism types available on
3875 the local system. This call is intended for support of specialized
3876 callers who need to request non-default mech_type sets from GSS-API
3877 calls which accept input mechanism type specifiers.
3879 2.4.3: GSS_Compare_name call
3883 o name1 INTERNAL NAME,
3885 o name2 INTERNAL NAME
3889 o major_status INTEGER,
3891 o minor_status INTEGER,
3893 o name_equal BOOLEAN
3895 Return major_status codes:
3897 o GSS_S_COMPLETE indicates that name1 and name2 were comparable, and
3898 that the name_equal result indicates whether name1 and name2
3899 represent the same entity.
3901 o GSS_S_BAD_NAMETYPE indicates that the two input names' types are
3902 different and incomparable, so that the comparison operation could
3905 o GSS_S_BAD_NAME indicates that one or both of the input names was
3906 ill-formed in terms of its internal type specifier, so the comparison
3907 operation could not be completed.
3909 o GSS_S_FAILURE indicates that the call's operation could not be
3910 performed for reasons unspecified at the GSS-API level.
3912 Allows callers to compare two internal name representations to
3913 determine whether they refer to the same entity. If either name
3914 presented to GSS_Compare_name() denotes an anonymous principal,
3915 GSS_Compare_name() shall indicate FALSE. It is not required that
3916 either or both inputs name1 and name2 be MNs; for some
3922 Linn Standards Track [Page 70]
3924 RFC 2743 GSS-API January 2000
3927 implementations and cases, GSS_S_BAD_NAMETYPE may be returned,
3928 indicating name incomparability, for the case where neither input
3931 2.4.4: GSS_Display_name call
3935 o name INTERNAL NAME
3939 o major_status INTEGER,
3941 o minor_status INTEGER,
3943 o name_string OCTET STRING, -- caller must release
3944 -- with GSS_Release_buffer()
3946 o name_type OBJECT IDENTIFIER -- caller should treat
3947 -- as read-only; does not need to be released
3949 Return major_status codes:
3951 o GSS_S_COMPLETE indicates that a valid printable name
3952 representation is available in the returned name_string.
3954 o GSS_S_BAD_NAME indicates that the contents of the provided name
3955 were inconsistent with the internally-indicated name type, so no
3956 printable representation could be generated.
3958 o GSS_S_FAILURE indicates that the requested operation could not be
3959 performed for reasons unspecified at the GSS-API level.
3961 Allows callers to translate an internal name representation into a
3962 printable form with associated namespace type descriptor. The syntax
3963 of the printable form is a local matter.
3965 If the input name represents an anonymous identity, a reserved value
3966 (GSS_C_NT_ANONYMOUS) shall be returned for name_type.
3968 The GSS_C_NO_OID name type is to be returned only when the
3969 corresponding internal name was created through import with
3970 GSS_C_NO_OID. It is acceptable for mechanisms to normalize names
3971 imported with GSS_C_NO_OID into other supported types and, therefore,
3972 to display them with types other than GSS_C_NO_OID.
3978 Linn Standards Track [Page 71]
3980 RFC 2743 GSS-API January 2000
3983 2.4.5: GSS_Import_name call
3987 o input_name_string OCTET STRING,
3989 o input_name_type OBJECT IDENTIFIER
3993 o major_status INTEGER,
3995 o minor_status INTEGER,
3997 o output_name INTERNAL NAME -- caller must release with
3998 -- GSS_Release_name()
4000 Return major_status codes:
4002 o GSS_S_COMPLETE indicates that a valid name representation is
4003 output in output_name and described by the type value in
4006 o GSS_S_BAD_NAMETYPE indicates that the input_name_type is
4007 unsupported by the applicable underlying GSS-API mechanism(s), so the
4008 import operation could not be completed.
4010 o GSS_S_BAD_NAME indicates that the provided input_name_string is
4011 ill-formed in terms of the input_name_type, so the import operation
4012 could not be completed.
4014 o GSS_S_BAD_MECH indicates that the input presented for import was
4015 an exported name object and that its enclosed mechanism type was not
4016 recognized or was unsupported by the GSS-API implementation.
4018 o GSS_S_FAILURE indicates that the requested operation could not be
4019 performed for reasons unspecified at the GSS-API level.
4021 Allows callers to provide a name representation as a contiguous octet
4022 string, designate the type of namespace in conjunction with which it
4023 should be parsed, and convert that representation to an internal form
4024 suitable for input to other GSS-API routines. The syntax of the
4025 input_name_string is defined in conjunction with its associated name
4026 type; depending on the input_name_type, the associated
4027 input_name_string may or may not be a printable string. If the
4028 input_name_type's value is GSS_C_NO_OID, a mechanism-specific default
4029 printable syntax (which shall be specified in the corresponding GSS-
4030 V2 mechanism specification) is assumed for the input_name_string;
4034 Linn Standards Track [Page 72]
4036 RFC 2743 GSS-API January 2000
4039 other input_name_type values as registered by GSS-API implementations
4040 can be used to indicate specific non-default name syntaxes. Note: The
4041 input_name_type argument serves to describe and qualify the
4042 interpretation of the associated input_name_string; it does not
4043 specify the data type of the returned output_name.
4045 If a mechanism claims support for a particular name type, its
4046 GSS_Import_name() operation shall be able to accept all possible
4047 values conformant to the external name syntax as defined for that
4048 name type. These imported values may correspond to:
4050 (1) locally registered entities (for which credentials may be
4053 (2) non-local entities (for which local credentials cannot be
4054 acquired, but which may be referenced as targets of initiated
4055 security contexts or initiators of accepted security contexts), or
4058 (3) neither of the above.
4060 Determination of whether a particular name belongs to class (1), (2),
4061 or (3) as described above is not guaranteed to be performed by the
4062 GSS_Import_name() function.
4064 The internal name generated by a GSS_Import_name() operation may be a
4065 single-mechanism MN, and is likely to be an MN within a single-
4066 mechanism implementation, but portable callers must not depend on
4067 this property (and must not, therefore, assume that the output from
4068 GSS_Import_name() can be passed directly to GSS_Export_name() without
4069 first being processed through GSS_Canonicalize_name()).
4071 2.4.6: GSS_Release_name call
4075 o name INTERNAL NAME
4079 o major_status INTEGER,
4081 o minor_status INTEGER
4083 Return major_status codes:
4085 o GSS_S_COMPLETE indicates that the storage associated with the
4086 input name was successfully released.
4090 Linn Standards Track [Page 73]
4092 RFC 2743 GSS-API January 2000
4095 o GSS_S_BAD_NAME indicates that the input name argument did not
4096 contain a valid name.
4098 o GSS_S_FAILURE indicates that the requested operation could not be
4099 performed for reasons unspecified at the GSS-API level.
4101 Allows callers to release the storage associated with an internal
4102 name representation. This call's specific behavior depends on the
4103 language and programming environment within which a GSS-API
4104 implementation operates, and is therefore detailed within applicable
4105 bindings specifications; in particular, implementation and invocation
4106 of this call may be superfluous (and may be omitted) within bindings
4107 where memory management is automatic.
4109 2.4.7: GSS_Release_buffer call
4113 o buffer OCTET STRING
4117 o major_status INTEGER,
4119 o minor_status INTEGER
4121 Return major_status codes:
4123 o GSS_S_COMPLETE indicates that the storage associated with the
4124 input buffer was successfully released.
4126 o GSS_S_FAILURE indicates that the requested operation could not be
4127 performed for reasons unspecified at the GSS-API level.
4129 Allows callers to release the storage associated with an OCTET STRING
4130 buffer allocated by another GSS-API call. This call's specific
4131 behavior depends on the language and programming environment within
4132 which a GSS-API implementation operates, and is therefore detailed
4133 within applicable bindings specifications; in particular,
4134 implementation and invocation of this call may be superfluous (and
4135 may be omitted) within bindings where memory management is automatic.
4137 2.4.8: GSS_Release_OID_set call
4141 o buffer SET OF OBJECT IDENTIFIER
4146 Linn Standards Track [Page 74]
4148 RFC 2743 GSS-API January 2000
4153 o major_status INTEGER,
4155 o minor_status INTEGER
4157 Return major_status codes:
4159 o GSS_S_COMPLETE indicates that the storage associated with the
4160 input object identifier set was successfully released.
4162 o GSS_S_FAILURE indicates that the requested operation could not be
4163 performed for reasons unspecified at the GSS-API level.
4165 Allows callers to release the storage associated with an object
4166 identifier set object allocated by another GSS-API call. This call's
4167 specific behavior depends on the language and programming environment
4168 within which a GSS-API implementation operates, and is therefore
4169 detailed within applicable bindings specifications; in particular,
4170 implementation and invocation of this call may be superfluous (and
4171 may be omitted) within bindings where memory management is automatic.
4173 2.4.9: GSS_Create_empty_OID_set call
4181 o major_status INTEGER,
4183 o minor_status INTEGER,
4185 o oid_set SET OF OBJECT IDENTIFIER -- caller must release
4186 -- with GSS_Release_oid_set()
4188 Return major_status codes:
4190 o GSS_S_COMPLETE indicates successful completion
4192 o GSS_S_FAILURE indicates that the operation failed
4194 Creates an object identifier set containing no object identifiers, to
4195 which members may be subsequently added using the
4196 GSS_Add_OID_set_member() routine. These routines are intended to be
4197 used to construct sets of mechanism object identifiers, for input to
4202 Linn Standards Track [Page 75]
4204 RFC 2743 GSS-API January 2000
4207 2.4.10: GSS_Add_OID_set_member call
4211 o member_oid OBJECT IDENTIFIER,
4213 o oid_set SET OF OBJECT IDENTIFIER
4217 o major_status INTEGER,
4219 o minor_status INTEGER,
4221 Return major_status codes:
4223 o GSS_S_COMPLETE indicates successful completion
4225 o GSS_S_FAILURE indicates that the operation failed
4227 Adds an Object Identifier to an Object Identifier set. This routine
4228 is intended for use in conjunction with GSS_Create_empty_OID_set()
4229 when constructing a set of mechanism OIDs for input to
4232 2.4.11: GSS_Test_OID_set_member call
4236 o member OBJECT IDENTIFIER,
4238 o set SET OF OBJECT IDENTIFIER
4242 o major_status INTEGER,
4244 o minor_status INTEGER,
4248 Return major_status codes:
4250 o GSS_S_COMPLETE indicates successful completion
4252 o GSS_S_FAILURE indicates that the operation failed
4258 Linn Standards Track [Page 76]
4260 RFC 2743 GSS-API January 2000
4263 Interrogates an Object Identifier set to determine whether a
4264 specified Object Identifier is a member. This routine is intended to
4265 be used with OID sets returned by GSS_Indicate_mechs(),
4266 GSS_Acquire_cred(), and GSS_Inquire_cred().
4268 2.4.12: GSS_Inquire_names_for_mech call
4272 o input_mech_type OBJECT IDENTIFIER, -- mechanism type
4276 o major_status INTEGER,
4278 o minor_status INTEGER,
4280 o name_type_set SET OF OBJECT IDENTIFIER -- caller must release
4281 -- with GSS_Release_oid_set()
4283 Return major_status codes:
4285 o GSS_S_COMPLETE indicates that the output name_type_set contains a
4286 list of name types which are supported by the locally available
4287 mechanism identified by input_mech_type.
4289 o GSS_S_BAD_MECH indicates that the mechanism identified by
4290 input_mech_type was unsupported within the local implementation,
4291 causing the query to fail.
4293 o GSS_S_FAILURE indicates that the requested operation could not be
4294 performed for reasons unspecified at the GSS-API level.
4296 Allows callers to determine the set of name types which are
4297 supportable by a specific locally-available mechanism.
4299 2.4.13: GSS_Inquire_mechs_for_name call
4303 o input_name INTERNAL NAME,
4307 o major_status INTEGER,
4309 o minor_status INTEGER,
4314 Linn Standards Track [Page 77]
4316 RFC 2743 GSS-API January 2000
4319 o mech_types SET OF OBJECT IDENTIFIER -- caller must release
4320 -- with GSS_Release_oid_set()
4322 Return major_status codes:
4324 o GSS_S_COMPLETE indicates that a set of object identifiers,
4325 corresponding to the set of mechanisms suitable for processing the
4326 input_name, is available in mech_types.
4328 o GSS_S_BAD_NAME indicates that the input_name was ill-formed and
4329 could not be processed.
4331 o GSS_S_BAD_NAMETYPE indicates that the input_name parameter
4332 contained an invalid name type or a name type unsupported by the
4333 GSS-API implementation.
4335 o GSS_S_FAILURE indicates that the requested operation could not be
4336 performed for reasons unspecified at the GSS-API level.
4338 This routine returns the mechanism set with which the input_name may
4341 Each mechanism returned will recognize at least one element within
4342 the name. It is permissible for this routine to be implemented within
4343 a mechanism-independent GSS-API layer, using the type information
4344 contained within the presented name, and based on registration
4345 information provided by individual mechanism implementations. This
4346 means that the returned mech_types result may indicate that a
4347 particular mechanism will understand a particular name when in fact
4348 it would refuse to accept that name as input to
4349 GSS_Canonicalize_name(), GSS_Init_sec_context(), GSS_Acquire_cred(),
4350 or GSS_Add_cred(), due to some property of the particular name rather
4351 than a property of the name type. Thus, this routine should be used
4352 only as a pre-filter for a call to a subsequent mechanism-specific
4355 2.4.14: GSS_Canonicalize_name call
4359 o input_name INTERNAL NAME,
4361 o mech_type OBJECT IDENTIFIER -- must be explicit mechanism,
4362 -- not "default" specifier or identifier of negotiating mechanism
4366 o major_status INTEGER,
4370 Linn Standards Track [Page 78]
4372 RFC 2743 GSS-API January 2000
4375 o minor_status INTEGER,
4377 o output_name INTERNAL NAME -- caller must release with
4378 -- GSS_Release_name()
4380 Return major_status codes:
4382 o GSS_S_COMPLETE indicates that a mechanism-specific reduction of
4383 the input_name, as processed by the mechanism identified by
4384 mech_type, is available in output_name.
4386 o GSS_S_BAD_MECH indicates that the identified mechanism is
4387 unsupported for this operation; this may correspond either to a
4388 mechanism wholly unsupported by the local GSS-API implementation or
4389 to a negotiating mechanism with which the canonicalization operation
4390 cannot be performed.
4392 o GSS_S_BAD_NAMETYPE indicates that the input name does not contain
4393 an element with suitable type for processing by the identified
4396 o GSS_S_BAD_NAME indicates that the input name contains an element
4397 with suitable type for processing by the identified mechanism, but
4398 that this element could not be processed successfully.
4400 o GSS_S_FAILURE indicates that the requested operation could not be
4401 performed for reasons unspecified at the GSS-API level.
4403 This routine reduces a GSS-API internal name input_name, which may in
4404 general contain elements corresponding to multiple mechanisms, to a
4405 mechanism-specific Mechanism Name (MN) output_name by applying the
4406 translations corresponding to the mechanism identified by mech_type.
4407 The contents of input_name are unaffected by the
4408 GSS_Canonicalize_name() operation. References to output_name will
4409 remain valid until output_name is released, independent of whether or
4410 not input_name is subsequently released.
4412 2.4.15: GSS_Export_name call
4416 o input_name INTERNAL NAME, -- required to be MN
4420 o major_status INTEGER,
4422 o minor_status INTEGER,
4426 Linn Standards Track [Page 79]
4428 RFC 2743 GSS-API January 2000
4431 o output_name OCTET STRING -- caller must release
4432 -- with GSS_Release_buffer()
4434 Return major_status codes:
4436 o GSS_S_COMPLETE indicates that a flat representation of the input
4437 name is available in output_name.
4439 o GSS_S_NAME_NOT_MN indicates that the input name contained elements
4440 corresponding to multiple mechanisms, so cannot be exported into a
4441 single-mechanism flat form.
4443 o GSS_S_BAD_NAME indicates that the input name was an MN, but could
4446 o GSS_S_BAD_NAMETYPE indicates that the input name was an MN, but
4447 that its type is unsupported by the GSS-API implementation.
4449 o GSS_S_FAILURE indicates that the requested operation could not be
4450 performed for reasons unspecified at the GSS-API level.
4452 This routine creates a flat name representation, suitable for
4453 bytewise comparison or for input to GSS_Import_name() in conjunction
4454 with the reserved GSS-API Exported Name Object OID, from a internal-
4455 form Mechanism Name (MN) as emitted, e.g., by GSS_Canonicalize_name()
4456 or GSS_Accept_sec_context().
4458 The emitted GSS-API Exported Name Object is self-describing; no
4459 associated parameter-level OID need be emitted by this call. This
4460 flat representation consists of a mechanism-independent wrapper
4461 layer, defined in Section 3.2 of this document, enclosing a
4462 mechanism-defined name representation.
4464 In all cases, the flat name output by GSS_Export_name() to correspond
4465 to a particular input MN must be invariant over time within a
4466 particular installation.
4468 The GSS_S_NAME_NOT_MN status code is provided to enable
4469 implementations to reject input names which are not MNs. It is not,
4470 however, required for purposes of conformance to this specification
4471 that all non-MN input names must necessarily be rejected.
4473 2.4.16: GSS_Duplicate_name call
4477 o src_name INTERNAL NAME
4482 Linn Standards Track [Page 80]
4484 RFC 2743 GSS-API January 2000
4489 o major_status INTEGER,
4491 o minor_status INTEGER,
4493 o dest_name INTERNAL NAME -- caller must release
4494 -- with GSS_Release_name()
4496 Return major_status codes:
4498 o GSS_S_COMPLETE indicates that dest_name references an internal
4499 name object containing the same name as passed to src_name.
4501 o GSS_S_BAD_NAME indicates that the input name was invalid.
4503 o GSS_S_FAILURE indicates that the requested operation could not be
4504 performed for reasons unspecified at the GSS-API level.
4506 This routine takes input internal name src_name, and returns another
4507 reference (dest_name) to that name which can be used even if src_name
4508 is later freed. (Note: This may be implemented by copying or through
4509 use of reference counts.)
4511 3: Data Structure Definitions for GSS-V2 Usage
4513 Subsections of this section define, for interoperability and
4514 portability purposes, certain data structures for use with GSS-V2.
4516 3.1: Mechanism-Independent Token Format
4518 This section specifies a mechanism-independent level of encapsulating
4519 representation for the initial token of a GSS-API context
4520 establishment sequence, incorporating an identifier of the mechanism
4521 type to be used on that context and enabling tokens to be interpreted
4522 unambiguously at GSS-API peers. Use of this format is required for
4523 initial context establishment tokens of Internet standards-track
4524 GSS-API mechanisms; use in non-initial tokens is optional.
4526 The encoding format for the token tag is derived from ASN.1 and DER
4527 (per illustrative ASN.1 syntax included later within this
4528 subsection), but its concrete representation is defined directly in
4529 terms of octets rather than at the ASN.1 level in order to facilitate
4530 interoperable implementation without use of general ASN.1 processing
4531 code. The token tag consists of the following elements, in order:
4533 1. 0x60 -- Tag for [APPLICATION 0] SEQUENCE; indicates that
4534 -- constructed form, definite length encoding follows.
4538 Linn Standards Track [Page 81]
4540 RFC 2743 GSS-API January 2000
4543 2. Token length octets, specifying length of subsequent data
4544 (i.e., the summed lengths of elements 3-5 in this list, and of the
4545 mechanism-defined token object following the tag). This element
4546 comprises a variable number of octets:
4548 2a. If the indicated value is less than 128, it shall be
4549 represented in a single octet with bit 8 (high order) set to
4550 "0" and the remaining bits representing the value.
4552 2b. If the indicated value is 128 or more, it shall be
4553 represented in two or more octets, with bit 8 of the first
4554 octet set to "1" and the remaining bits of the first octet
4555 specifying the number of additional octets. The subsequent
4556 octets carry the value, 8 bits per octet, most significant
4557 digit first. The minimum number of octets shall be used to
4558 encode the length (i.e., no octets representing leading zeros
4559 shall be included within the length encoding).
4561 3. 0x06 -- Tag for OBJECT IDENTIFIER
4563 4. Object identifier length -- length (number of octets) of
4564 -- the encoded object identifier contained in element 5,
4565 -- encoded per rules as described in 2a. and 2b. above.
4567 5. Object identifier octets -- variable number of octets,
4568 -- encoded per ASN.1 BER rules:
4570 5a. The first octet contains the sum of two values: (1) the
4571 top-level object identifier component, multiplied by 40
4572 (decimal), and (2) the second-level object identifier
4573 component. This special case is the only point within an
4574 object identifier encoding where a single octet represents
4575 contents of more than one component.
4577 5b. Subsequent octets, if required, encode successively-lower
4578 components in the represented object identifier. A component's
4579 encoding may span multiple octets, encoding 7 bits per octet
4580 (most significant bits first) and with bit 8 set to "1" on all
4581 but the final octet in the component's encoding. The minimum
4582 number of octets shall be used to encode each component (i.e.,
4583 no octets representing leading zeros shall be included within a
4584 component's encoding).
4586 (Note: In many implementations, elements 3-5 may be stored and
4587 referenced as a contiguous string constant.)
4594 Linn Standards Track [Page 82]
4596 RFC 2743 GSS-API January 2000
4599 The token tag is immediately followed by a mechanism-defined token
4600 object. Note that no independent size specifier intervenes following
4601 the object identifier value to indicate the size of the mechanism-
4602 defined token object. While ASN.1 usage within mechanism-defined
4603 tokens is permitted, there is no requirement that the mechanism-
4604 specific innerContextToken, innerMsgToken, and sealedUserData data
4605 elements must employ ASN.1 BER/DER encoding conventions.
4607 The following ASN.1 syntax is included for descriptive purposes only,
4608 to illustrate structural relationships among token and tag objects.
4609 For interoperability purposes, token and tag encoding shall be
4610 performed using the concrete encoding procedures described earlier in
4613 GSS-API DEFINITIONS ::=
4617 MechType ::= OBJECT IDENTIFIER
4618 -- data structure definitions
4619 -- callers must be able to distinguish among
4620 -- InitialContextToken, SubsequentContextToken,
4621 -- PerMsgToken, and SealedMessage data elements
4622 -- based on the usage in which they occur
4624 InitialContextToken ::=
4625 -- option indication (delegation, etc.) indicated within
4626 -- mechanism-specific token
4627 [APPLICATION 0] IMPLICIT SEQUENCE {
4629 innerContextToken ANY DEFINED BY thisMech
4630 -- contents mechanism-specific
4631 -- ASN.1 structure not required
4634 SubsequentContextToken ::= innerContextToken ANY
4635 -- interpretation based on predecessor InitialContextToken
4636 -- ASN.1 structure not required
4639 -- as emitted by GSS_GetMIC and processed by GSS_VerifyMIC
4640 -- ASN.1 structure not required
4644 -- as emitted by GSS_Wrap and processed by GSS_Unwrap
4645 -- includes internal, mechanism-defined indicator
4646 -- of whether or not encrypted
4650 Linn Standards Track [Page 83]
4652 RFC 2743 GSS-API January 2000
4655 -- ASN.1 structure not required
4660 3.2: Mechanism-Independent Exported Name Object Format
4662 This section specifies a mechanism-independent level of encapsulating
4663 representation for names exported via the GSS_Export_name() call,
4664 including an object identifier representing the exporting mechanism.
4665 The format of names encapsulated via this representation shall be
4666 defined within individual mechanism drafts. The Object Identifier
4667 value to indicate names of this type is defined in Section 4.7 of
4670 No name type OID is included in this mechanism-independent level of
4671 format definition, since (depending on individual mechanism
4672 specifications) the enclosed name may be implicitly typed or may be
4673 explicitly typed using a means other than OID encoding.
4675 The bytes within MECH_OID_LEN and NAME_LEN elements are represented
4676 most significant byte first (equivalently, in IP network byte order).
4678 Length Name Description
4680 2 TOK_ID Token Identifier
4681 For exported name objects, this
4683 2 MECH_OID_LEN Length of the Mechanism OID
4684 MECH_OID_LEN MECH_OID Mechanism OID, in DER
4685 4 NAME_LEN Length of name
4686 NAME_LEN NAME Exported name; format defined in
4687 applicable mechanism draft.
4689 A concrete example of the contents of an exported name object,
4690 derived from the Kerberos Version 5 mechanism, is as follows:
4692 04 01 00 0B 06 09 2A 86 48 86 F7 12 01 02 02 hx xx xx xl pp qq ... zz
4694 04 01 mandatory token identifier
4696 00 0B 2-byte length of the immediately following DER-encoded
4697 ASN.1 value of type OID, most significant octet first
4706 Linn Standards Track [Page 84]
4708 RFC 2743 GSS-API January 2000
4711 06 09 2A 86 48 86 F7 12 01 02 02 DER-encoded ASN.1 value
4712 of type OID; Kerberos V5
4713 mechanism OID indicates
4714 Kerberos V5 exported name
4716 in Detail: 06 Identifier octet (6=OID)
4718 2A 86 48 86 F7 12 01 02 02 Content octet(s)
4720 hx xx xx xl 4-byte length of the immediately following exported
4721 name blob, most significant octet first
4723 pp qq ... zz exported name blob of specified length,
4724 bits and bytes specified in the
4725 (Kerberos 5) GSS-API v2 mechanism spec
4727 4: Name Type Definitions
4729 This section includes definitions for name types and associated
4730 syntaxes which are defined in a mechanism-independent fashion at the
4731 GSS-API level rather than being defined in individual mechanism
4734 4.1: Host-Based Service Name Form
4736 This name form shall be represented by the Object Identifier:
4738 {iso(1) member-body(2) United States(840) mit(113554) infosys(1)
4739 "gssapi(2) generic(1) service_name(4)}.
4741 The recommended symbolic name for this type is
4742 "GSS_C_NT_HOSTBASED_SERVICE".
4744 For reasons of compatibility with existing implementations, it is
4745 recommended that this OID be used rather than the alternate value as
4746 included in [RFC-2078]:
4748 {1(iso), 3(org), 6(dod), 1(internet), 5(security), 6(nametypes),
4749 2(gss-host-based-services)}
4751 While it is not recommended that this alternate value be emitted on
4752 output by GSS implementations, it is recommended that it be accepted
4753 on input as equivalent to the recommended value.
4762 Linn Standards Track [Page 85]
4764 RFC 2743 GSS-API January 2000
4767 This name type is used to represent services associated with host
4768 computers. Support for this name form is recommended to mechanism
4769 designers in the interests of portability, but is not mandated by
4770 this specification. This name form is constructed using two elements,
4771 "service" and "hostname", as follows:
4775 When a reference to a name of this type is resolved, the "hostname"
4776 may (as an example implementation strategy) be canonicalized by
4777 attempting a DNS lookup and using the fully-qualified domain name
4778 which is returned, or by using the "hostname" as provided if the DNS
4779 lookup fails. The canonicalization operation also maps the host's
4780 name into lower-case characters.
4782 The "hostname" element may be omitted. If no "@" separator is
4783 included, the entire name is interpreted as the service specifier,
4784 with the "hostname" defaulted to the canonicalized name of the local
4787 Documents specifying means for GSS integration into a particular
4788 protocol should state either:
4790 (a) that a specific IANA-registered name associated with that
4791 protocol shall be used for the "service" element (this admits, if
4792 needed, the possibility that a single name can be registered and
4793 shared among a related set of protocols), or
4795 (b) that the generic name "host" shall be used for the "service"
4798 (c) that, for that protocol, fallback in specified order (a, then
4799 b) or (b, then a) shall be applied.
4801 IANA registration of specific names per (a) should be handled in
4802 accordance with the "Specification Required" assignment policy,
4803 defined by BCP 26, RFC 2434 as follows: "Values and their meaning
4804 must be documented in an RFC or other available reference, in
4805 sufficient detail so that interoperability between independent
4806 implementations is possible."
4810 This name form shall be represented by the Object Identifier {iso(1)
4811 member-body(2) United States(840) mit(113554) infosys(1) gssapi(2)
4812 generic(1) user_name(1)}. The recommended mechanism-independent
4813 symbolic name for this type is "GSS_C_NT_USER_NAME". (Note: the same
4818 Linn Standards Track [Page 86]
4820 RFC 2743 GSS-API January 2000
4823 name form and OID is defined within the Kerberos V5 GSS-API
4824 mechanism, but the symbolic name recommended there begins with a
4825 "GSS_KRB5_NT_" prefix.)
4827 This name type is used to indicate a named user on a local system.
4828 Its syntax and interpretation may be OS-specific. This name form is
4833 4.3: Machine UID Form
4835 This name form shall be represented by the Object Identifier {iso(1)
4836 member-body(2) United States(840) mit(113554) infosys(1) gssapi(2)
4837 generic(1) machine_uid_name(2)}. The recommended mechanism-
4838 independent symbolic name for this type is
4839 "GSS_C_NT_MACHINE_UID_NAME". (Note: the same name form and OID is
4840 defined within the Kerberos V5 GSS-API mechanism, but the symbolic
4841 name recommended there begins with a "GSS_KRB5_NT_" prefix.)
4843 This name type is used to indicate a numeric user identifier
4844 corresponding to a user on a local system. Its interpretation is
4845 OS-specific. The gss_buffer_desc representing a name of this type
4846 should contain a locally-significant user ID, represented in host
4847 byte order. The GSS_Import_name() operation resolves this uid into a
4848 username, which is then treated as the User Name Form.
4850 4.4: String UID Form
4852 This name form shall be represented by the Object Identifier {iso(1)
4853 member-body(2) United States(840) mit(113554) infosys(1) gssapi(2)
4854 generic(1) string_uid_name(3)}. The recommended symbolic name for
4855 this type is "GSS_C_NT_STRING_UID_NAME". (Note: the same name form
4856 and OID is defined within the Kerberos V5 GSS-API mechanism, but the
4857 symbolic name recommended there begins with a "GSS_KRB5_NT_" prefix.)
4859 This name type is used to indicate a string of digits representing
4860 the numeric user identifier of a user on a local system. Its
4861 interpretation is OS-specific. This name type is similar to the
4862 Machine UID Form, except that the buffer contains a string
4863 representing the user ID.
4865 4.5: Anonymous Nametype
4867 The following Object Identifier value is provided as a means to
4868 identify anonymous names, and can be compared against in order to
4869 determine, in a mechanism-independent fashion, whether a name refers
4870 to an anonymous principal:
4874 Linn Standards Track [Page 87]
4876 RFC 2743 GSS-API January 2000
4879 {1(iso), 3(org), 6(dod), 1(internet), 5(security), 6(nametypes),
4880 3(gss-anonymous-name)}
4882 The recommended symbolic name corresponding to this definition is
4887 The recommended symbolic name GSS_C_NO_OID corresponds to a null
4888 input value instead of an actual object identifier. Where specified,
4889 it indicates interpretation of an associated name based on a
4890 mechanism-specific default printable syntax.
4892 4.7: Exported Name Object
4894 Name objects of the Mechanism-Independent Exported Name Object type,
4895 as defined in Section 3.2 of this document, will be identified with
4896 the following Object Identifier:
4898 {1(iso), 3(org), 6(dod), 1(internet), 5(security), 6(nametypes),
4899 4(gss-api-exported-name)}
4901 The recommended symbolic name corresponding to this definition is
4902 GSS_C_NT_EXPORT_NAME.
4906 The recommended symbolic name GSS_C_NO_NAME indicates that no name is
4907 being passed within a particular value of a parameter used for the
4908 purpose of transferring names. Note: GSS_C_NO_NAME is not an actual
4909 name type, and is not represented by an OID; its acceptability in
4910 lieu of an actual name is confined to specific calls
4911 (GSS_Acquire_cred(), GSS_Add_cred(), and GSS_Init_sec_context()) with
4912 usages as identified within this specification.
4914 5: Mechanism-Specific Example Scenarios
4916 This section provides illustrative overviews of the use of various
4917 candidate mechanism types to support the GSS-API. These discussions
4918 are intended primarily for readers familiar with specific security
4919 technologies, demonstrating how GSS-API functions can be used and
4920 implemented by candidate underlying mechanisms. They should not be
4921 regarded as constrictive to implementations or as defining the only
4922 means through which GSS-API functions can be realized with a
4923 particular underlying technology, and do not demonstrate all GSS-API
4924 features with each technology.
4930 Linn Standards Track [Page 88]
4932 RFC 2743 GSS-API January 2000
4935 5.1: Kerberos V5, single-TGT
4937 OS-specific login functions yield a TGT to the local realm Kerberos
4938 server; TGT is placed in a credentials structure for the client.
4939 Client calls GSS_Acquire_cred() to acquire a cred_handle in order to
4940 reference the credentials for use in establishing security contexts.
4942 Client calls GSS_Init_sec_context(). If the requested service is
4943 located in a different realm, GSS_Init_sec_context() gets the
4944 necessary TGT/key pairs needed to traverse the path from local to
4945 target realm; these data are placed in the owner's TGT cache. After
4946 any needed remote realm resolution, GSS_Init_sec_context() yields a
4947 service ticket to the requested service with a corresponding session
4948 key; these data are stored in conjunction with the context. GSS-API
4949 code sends KRB_TGS_REQ request(s) and receives KRB_TGS_REP
4950 response(s) (in the successful case) or KRB_ERROR.
4952 Assuming success, GSS_Init_sec_context() builds a Kerberos-formatted
4953 KRB_AP_REQ message, and returns it in output_token. The client sends
4954 the output_token to the service.
4956 The service passes the received token as the input_token argument to
4957 GSS_Accept_sec_context(), which verifies the authenticator, provides
4958 the service with the client's authenticated name, and returns an
4959 output_context_handle.
4961 Both parties now hold the session key associated with the service
4962 ticket, and can use this key in subsequent GSS_GetMIC(),
4963 GSS_VerifyMIC(), GSS_Wrap(), and GSS_Unwrap() operations.
4965 5.2: Kerberos V5, double-TGT
4967 TGT acquisition as above.
4969 Note: To avoid unnecessary frequent invocations of error paths when
4970 implementing the GSS-API atop Kerberos V5, it seems appropriate to
4971 represent "single-TGT K-V5" and "double-TGT K-V5" with separate
4972 mech_types, and this discussion makes that assumption.
4974 Based on the (specified or defaulted) mech_type,
4975 GSS_Init_sec_context() determines that the double-TGT protocol
4976 should be employed for the specified target. GSS_Init_sec_context()
4977 returns GSS_S_CONTINUE_NEEDED major_status, and its returned
4978 output_token contains a request to the service for the service's TGT.
4979 (If a service TGT with suitably long remaining lifetime already
4980 exists in a cache, it may be usable, obviating the need for this
4981 step.) The client passes the output_token to the service. Note: this
4982 scenario illustrates a different use for the GSS_S_CONTINUE_NEEDED
4986 Linn Standards Track [Page 89]
4988 RFC 2743 GSS-API January 2000
4991 status return facility than for support of mutual authentication;
4992 note that both uses can coexist as successive operations within a
4993 single context establishment operation.
4995 The service passes the received token as the input_token argument to
4996 GSS_Accept_sec_context(), which recognizes it as a request for TGT.
4997 (Note that current Kerberos V5 defines no intra-protocol mechanism to
4998 represent such a request.) GSS_Accept_sec_context() returns
4999 GSS_S_CONTINUE_NEEDED major_status and provides the service's TGT in
5000 its output_token. The service sends the output_token to the client.
5002 The client passes the received token as the input_token argument to a
5003 continuation of GSS_Init_sec_context(). GSS_Init_sec_context() caches
5004 the received service TGT and uses it as part of a service ticket
5005 request to the Kerberos authentication server, storing the returned
5006 service ticket and session key in conjunction with the context.
5007 GSS_Init_sec_context() builds a Kerberos-formatted authenticator, and
5008 returns it in output_token along with GSS_S_COMPLETE return
5009 major_status. The client sends the output_token to the service.
5011 Service passes the received token as the input_token argument to a
5012 continuation call to GSS_Accept_sec_context().
5013 GSS_Accept_sec_context() verifies the authenticator, provides the
5014 service with the client's authenticated name, and returns
5015 major_status GSS_S_COMPLETE.
5017 GSS_GetMIC(), GSS_VerifyMIC(), GSS_Wrap(), and GSS_Unwrap() as
5020 5.3: X.509 Authentication Framework
5022 This example illustrates use of the GSS-API in conjunction with
5023 public-key mechanisms, consistent with the X.509 Directory
5024 Authentication Framework.
5026 The GSS_Acquire_cred() call establishes a credentials structure,
5027 making the client's private key accessible for use on behalf of the
5030 The client calls GSS_Init_sec_context(), which interrogates the
5031 Directory to acquire (and validate) a chain of public-key
5032 certificates, thereby collecting the public key of the service. The
5033 certificate validation operation determines that suitable integrity
5034 checks were applied by trusted authorities and that those
5035 certificates have not expired. GSS_Init_sec_context() generates a
5036 secret key for use in per-message protection operations on the
5037 context, and enciphers that secret key under the service's public
5042 Linn Standards Track [Page 90]
5044 RFC 2743 GSS-API January 2000
5047 The enciphered secret key, along with an authenticator quantity
5048 signed with the client's private key, is included in the output_token
5049 from GSS_Init_sec_context(). The output_token also carries a
5050 certification path, consisting of a certificate chain leading from
5051 the service to the client; a variant approach would defer this path
5052 resolution to be performed by the service instead of being asserted
5053 by the client. The client application sends the output_token to the
5056 The service passes the received token as the input_token argument to
5057 GSS_Accept_sec_context(). GSS_Accept_sec_context() validates the
5058 certification path, and as a result determines a certified binding
5059 between the client's distinguished name and the client's public key.
5060 Given that public key, GSS_Accept_sec_context() can process the
5061 input_token's authenticator quantity and verify that the client's
5062 private key was used to sign the input_token. At this point, the
5063 client is authenticated to the service. The service uses its private
5064 key to decipher the enciphered secret key provided to it for per-
5065 message protection operations on the context.
5067 The client calls GSS_GetMIC() or GSS_Wrap() on a data message, which
5068 causes per-message authentication, integrity, and (optional)
5069 confidentiality facilities to be applied to that message. The service
5070 uses the context's shared secret key to perform corresponding
5071 GSS_VerifyMIC() and GSS_Unwrap() calls.
5073 6: Security Considerations
5075 This document specifies a service interface for security facilities
5076 and services; as such, security considerations are considered
5077 throughout the specification. Nonetheless, it is appropriate to
5078 summarize certain specific points relevant to GSS-API implementors
5079 and calling applications. Usage of the GSS-API interface does not in
5080 itself provide security services or assurance; instead, these
5081 attributes are dependent on the underlying mechanism(s) which support
5082 a GSS-API implementation. Callers must be attentive to the requests
5083 made to GSS-API calls and to the status indicators returned by GSS-
5084 API, as these specify the security service characteristics which
5085 GSS-API will provide. When the interprocess context transfer
5086 facility is used, appropriate local controls should be applied to
5087 constrain access to interprocess tokens and to the sensitive data
5098 Linn Standards Track [Page 91]
5100 RFC 2743 GSS-API January 2000
5103 7: Related Activities
5105 In order to implement the GSS-API atop existing, emerging, and future
5106 security mechanisms:
5108 object identifiers must be assigned to candidate GSS-API
5109 mechanisms and the name types which they support
5111 concrete data element formats and processing procedures must be
5112 defined for candidate mechanisms
5114 Calling applications must implement formatting conventions which will
5115 enable them to distinguish GSS-API tokens from other data carried in
5116 their application protocols.
5118 Concrete language bindings are required for the programming
5119 environments in which the GSS-API is to be employed, as [RFC-1509]
5120 defines for the C programming language and GSS-V1. C Language
5121 bindings for GSS-V2 are defined in [RFC-2744].
5154 Linn Standards Track [Page 92]
5156 RFC 2743 GSS-API January 2000
5159 8: Referenced Documents
5161 [ISO-7498-2] International Standard ISO 7498-2-1988(E), Security
5164 [ISOIEC-8824] ISO/IEC 8824, "Specification of Abstract Syntax
5165 Notation One (ASN.1)".
5167 [ISOIEC-8825] ISO/IEC 8825, "Specification of Basic Encoding Rules
5168 for Abstract Syntax Notation One (ASN.1)".)
5170 [RFC-1507]: Kaufman, C., "DASS: Distributed Authentication Security
5171 Service", RFC 1507, September 1993.
5173 [RFC-1508]: Linn, J., "Generic Security Service Application Program
5174 Interface", RFC 1508, September 1993.
5176 [RFC-1509]: Wray, J., "Generic Security Service API: C-bindings",
5177 RFC 1509, September 1993.
5179 [RFC-1964]: Linn, J., "The Kerberos Version 5 GSS-API Mechanism",
5180 RFC 1964, June 1996.
5182 [RFC-2025]: Adams, C., "The Simple Public-Key GSS-API Mechanism
5183 (SPKM)", RFC 2025, October 1996.
5185 [RFC-2078]: Linn, J., "Generic Security Service Application Program
5186 Interface, Version 2", RFC 2078, January 1997.
5188 [RFC-2203]: Eisler, M., Chiu, A. and L. Ling, "RPCSEC_GSS Protocol
5189 Specification", RFC 2203, September 1997.
5191 [RFC-2744]: Wray, J., "Generic Security Service API Version 2 :
5192 C-bindings", RFC 2744, January 2000.
5210 Linn Standards Track [Page 93]
5212 RFC 2743 GSS-API January 2000
5217 MECHANISM DESIGN CONSTRAINTS
5219 The following constraints on GSS-API mechanism designs are adopted in
5220 response to observed caller protocol requirements, and adherence
5221 thereto is anticipated in subsequent descriptions of GSS-API
5222 mechanisms to be documented in standards-track Internet
5225 It is strongly recommended that mechanisms offering per-message
5226 protection services also offer at least one of the replay detection
5227 and sequencing services, as mechanisms offering neither of the latter
5228 will fail to satisfy recognized requirements of certain candidate
5233 COMPATIBILITY WITH GSS-V1
5235 It is the intent of this document to define an interface and
5236 procedures which preserve compatibility between GSS-V1 [RFC-1508]
5237 callers and GSS-V2 providers. All calls defined in GSS-V1 are
5238 preserved, and it has been a goal that GSS-V1 callers should be able
5239 to operate atop GSS-V2 provider implementations. Certain detailed
5240 changes, summarized in this section, have been made in order to
5241 resolve omissions identified in GSS-V1.
5243 The following GSS-V1 constructs, while supported within GSS-V2, are
5246 Names for per-message processing routines: GSS_Seal() deprecated
5247 in favor of GSS_Wrap(); GSS_Sign() deprecated in favor of
5248 GSS_GetMIC(); GSS_Unseal() deprecated in favor of GSS_Unwrap();
5249 GSS_Verify() deprecated in favor of GSS_VerifyMIC().
5251 GSS_Delete_sec_context() facility for context_token usage,
5252 allowing mechanisms to signal context deletion, is retained for
5253 compatibility with GSS-V1. For current usage, it is recommended
5254 that both peers to a context invoke GSS_Delete_sec_context()
5255 independently, passing a null output_context_token buffer to
5256 indicate that no context_token is required. Implementations of
5257 GSS_Delete_sec_context() should delete relevant locally-stored
5258 context information.
5260 This GSS-V2 specification adds the following calls which are not
5266 Linn Standards Track [Page 94]
5268 RFC 2743 GSS-API January 2000
5271 Credential management calls: GSS_Add_cred(),
5272 GSS_Inquire_cred_by_mech().
5274 Context-level calls: GSS_Inquire_context(), GSS_Wrap_size_limit(),
5275 GSS_Export_sec_context(), GSS_Import_sec_context().
5277 Per-message calls: No new calls. Existing calls have been
5280 Support calls: GSS_Create_empty_OID_set(),
5281 GSS_Add_OID_set_member(), GSS_Test_OID_set_member(),
5282 GSS_Inquire_names_for_mech(), GSS_Inquire_mechs_for_name(),
5283 GSS_Canonicalize_name(), GSS_Export_name(), GSS_Duplicate_name().
5285 This GSS-V2 specification introduces three new facilities applicable
5286 to security contexts, indicated using the following context state
5287 values which are not present in GSS-V1:
5289 anon_state, set TRUE to indicate that a context's initiator is
5290 anonymous from the viewpoint of the target; Section 1.2.5 of this
5291 specification provides a summary description of the GSS-V2
5292 anonymity support facility, support and use of which is optional.
5294 prot_ready_state, set TRUE to indicate that a context may be used
5295 for per-message protection before final completion of context
5296 establishment; Section 1.2.7 of this specification provides a
5297 summary description of the GSS-V2 facility enabling mechanisms to
5298 selectively permit per-message protection during context
5299 establishment, support and use of which is optional.
5301 trans_state, set TRUE to indicate that a context is transferable
5302 to another process using the GSS-V2 GSS_Export_sec_context()
5305 These state values are represented (at the C bindings level) in
5306 positions within a bit vector which are unused in GSS-V1, and may be
5307 safely ignored by GSS-V1 callers.
5309 New conf_req_flag and integ_req_flag inputs are defined for
5310 GSS_Init_sec_context(), primarily to provide information to
5311 negotiating mechanisms. This introduces a compatibility issue with
5312 GSS-V1 callers, discussed in section 2.2.1 of this specification.
5322 Linn Standards Track [Page 95]
5324 RFC 2743 GSS-API January 2000
5327 Relative to GSS-V1, GSS-V2 provides additional guidance to GSS-API
5328 implementors in the following areas: implementation robustness,
5329 credential management, behavior in multi-mechanism configurations,
5330 naming support, and inclusion of optional sequencing services. The
5331 token tagging facility as defined in GSS-V2, Section 3.1, is now
5332 described directly in terms of octets to facilitate interoperable
5333 implementation without general ASN.1 processing code; the
5334 corresponding ASN.1 syntax, included for descriptive purposes, is
5335 unchanged from that in GSS-V1. For use in conjunction with added
5336 naming support facilities, a new Exported Name Object construct is
5337 added. Additional name types are introduced in Section 4.
5339 This GSS-V2 specification adds the following major_status values
5340 which are not defined in GSS-V1:
5342 GSS_S_BAD_QOP unsupported QOP value
5343 GSS_S_UNAUTHORIZED operation unauthorized
5344 GSS_S_UNAVAILABLE operation unavailable
5345 GSS_S_DUPLICATE_ELEMENT duplicate credential element
5347 GSS_S_NAME_NOT_MN name contains multi-mechanism
5349 GSS_S_GAP_TOKEN skipped predecessor token(s)
5352 Of these added status codes, only two values are defined to be
5353 returnable by calls existing in GSS-V1: GSS_S_BAD_QOP (returnable by
5354 GSS_GetMIC() and GSS_Wrap()), and GSS_S_GAP_TOKEN (returnable by
5355 GSS_VerifyMIC() and GSS_Unwrap()).
5357 Additionally, GSS-V2 descriptions of certain calls present in GSS-V1
5358 have been updated to allow return of additional major_status values
5359 from the set as defined in GSS-V1: GSS_Inquire_cred() has
5360 GSS_S_DEFECTIVE_CREDENTIAL and GSS_S_CREDENTIALS_EXPIRED defined as
5361 returnable, GSS_Init_sec_context() has GSS_S_OLD_TOKEN,
5362 GSS_S_DUPLICATE_TOKEN, and GSS_S_BAD_MECH defined as returnable, and
5363 GSS_Accept_sec_context() has GSS_S_BAD_MECH defined as returnable.
5367 CHANGES RELATIVE TO RFC-2078
5369 This document incorporates a number of changes relative to RFC-2078,
5370 made primarily in response to implementation experience, for purposes
5371 of alignment with the GSS-V2 C language bindings document, and to add
5372 informative clarification. This section summarizes technical changes
5378 Linn Standards Track [Page 96]
5380 RFC 2743 GSS-API January 2000
5385 Clarified usage of object release routines, and incorporated
5386 statement that some may be omitted within certain operating
5389 Removed GSS_Release_OID, GSS_OID_to_str(), and GSS_Str_to_OID()
5392 Clarified circumstances under which zero-length tokens may validly
5393 exist as inputs and outputs to/from GSS-API calls.
5395 Added GSS_S_BAD_MIC status code as alias for GSS_S_BAD_SIG.
5397 For GSS_Display_status(), deferred to language bindings the choice
5398 of whether to return multiple status values in parallel or via
5399 iteration, and added commentary deprecating return of
5400 GSS_S_CONTINUE_NEEDED.
5402 Adapted and incorporated clarifying material on optional service
5403 support, delegation, and interprocess context transfer from C
5406 Added and updated references to related documents, and to current
5407 status of cited Kerberos mechanism OID.
5409 Added general statement about GSS-API calls having no side effects
5410 visible at the GSS-API level.
5412 Context-related (including per-message protection issues):
5414 Clarified GSS_Delete_sec_context() usage for partially-established
5417 Added clarification on GSS_Export_sec_context() and
5418 GSS_Import_sec_context() behavior and context usage following an
5419 export-import sequence.
5421 Added informatory conf_req_flag, integ_req_flag inputs to
5422 GSS_Init_sec_context(). (Note: this facility introduces a
5423 backward incompatibility with GSS-V1 callers, discussed in Section
5424 2.2.1; this implication was recognized and accepted in working
5427 Stated that GSS_S_FAILURE is to be returned if
5428 GSS_Init_sec_context() or GSS_Accept_sec_context() is passed the
5429 handle of a context which is already fully established.
5434 Linn Standards Track [Page 97]
5436 RFC 2743 GSS-API January 2000
5439 Re GSS_Inquire_sec_context(), stated that src_name and targ_name
5440 are not returned until GSS_S_COMPLETE status is reached; removed
5441 use of GSS_S_CONTEXT_EXPIRED status code (replacing with EXPIRED
5442 lifetime return value); stated requirement to retain inquirable
5443 data until context released by caller; added result value
5444 indicating whether or not context is fully open.
5446 Added discussion of interoperability conditions for mechanisms
5447 permitting optional support of QOPs. Removed reference to
5448 structured QOP elements in GSS_Verify_MIC().
5450 Added discussion of use of GSS_S_DUPLICATE_TOKEN status to
5451 indicate reflected per-message tokens.
5453 Clarified use of informational sequencing codes from per-message
5454 protection calls in conjunction with GSS_S_COMPLETE and
5455 GSS_S_FAILURE major_status returns, adjusting status code
5456 descriptions accordingly.
5458 Added specific statements about impact of GSS_GetMIC() and
5459 GSS_Wrap() failures on context state information, and generalized
5460 existing statements about impact of processing failures on
5461 received per-message tokens.
5463 For GSS_Init_sec_context() and GSS_Accept_sec_context(), permitted
5464 returned mech_type to be valid before GSS_S_COMPLETE, recognizing
5465 that the value may change on successive continuation calls in the
5466 negotiated mechanism case.
5468 Deleted GSS_S_CONTEXT_EXPIRED status from
5469 GSS_Import_sec_context().
5471 Added conf_req_flag input to GSS_Wrap_size_limit().
5473 Stated requirement for mechanisms' support of per-message
5474 protection services to be usable concurrently in both directions
5479 For GSS_Acquire_cred() and GSS_Add_cred(), aligned with C bindings
5480 statement of likely non-support for INITIATE or BOTH credentials
5481 if input name is neither empty nor a name resulting from applying
5482 GSS_Inquire_cred() against the default credential. Further,
5483 stated that an explicit name returned by GSS_Inquire_context()
5484 should also be accepted. Added commentary about potentially
5485 time-variant results of default resolution and attendant
5486 implications. Aligned with C bindings re behavior when
5490 Linn Standards Track [Page 98]
5492 RFC 2743 GSS-API January 2000
5495 GSS_C_NO_NAME provided for desired_name. In GSS_Acquire_cred(),
5496 stated that NULL, rather than empty OID set, should be used for
5497 desired_mechs in order to request default mechanism set.
5499 Added GSS_S_CREDENTIALS_EXPIRED as returnable major_status for
5500 GSS_Acquire_cred(), GSS_Add_cred(), also specifying GSS_S_NO_CRED
5501 as appropriate return for temporary, user-fixable credential
5502 unavailability. GSS_Acquire_cred() and GSS_Add_cred() are also to
5503 return GSS_S_NO_CRED if an authorization failure is encountered
5504 upon credential acquisition.
5506 Removed GSS_S_CREDENTIALS_EXPIRED status return from per-message
5507 protection, GSS_Context_time(), and GSS_Inquire_context() calls.
5509 For GSS_Add_cred(), aligned with C bindings' description of
5510 behavior when addition of elements to the default credential is
5513 Upgraded recommended default credential resolution algorithm to
5514 status of requirement for initiator credentials.
5516 For GSS_Release_cred(), GSS_Inquire_cred(), and
5517 GSS_Inquire_cred_by_mech(), clarified behavior for input
5518 GSS_C_NO_CREDENTIAL.
5522 Aligned GSS_Inquire_mechs_for_name() description with C bindings.
5524 Removed GSS_S_BAD_NAMETYPE status return from
5525 GSS_Duplicate_name(), GSS_Display_name(); constrained its
5526 applicability for GSS_Compare_name().
5528 Aligned with C bindings statement re GSS_Import_name() behavior
5529 with GSS_C_NO_OID input name type, and stated that GSS-V2
5530 mechanism specifications are to define processing procedures
5531 applicable to their mechanisms. Also clarified GSS_C_NO_OID usage
5532 with GSS_Display_name().
5534 Downgraded reference to name canonicalization via DNS lookup to an
5537 For GSS_Canonicalize_name(), stated that neither negotiated
5538 mechanisms nor the default mechanism are supported input
5539 mech_types for this operation, and specified GSS_S_BAD_MECH status
5540 to be returned in this case. Clarified that the
5541 GSS_Canonicalize_name() operation is non-destructive to its input
5546 Linn Standards Track [Page 99]
5548 RFC 2743 GSS-API January 2000
5551 Clarified semantics of GSS_C_NT_USER_NAME name type.
5553 Added descriptions of additional name types. Also added
5554 discussion of GSS_C_NO_NAME and its constrained usage with
5557 Adapted and incorporated C bindings discussion about name
5558 comparisons with exported name objects.
5560 Added recommendation to mechanism designers for support of host-
5561 based service name type, deferring any requirement statement to
5562 individual mechanism specifications. Added discussion of host-
5563 based service's service name element and proposed approach for
5564 IANA registration policy therefor.
5566 Clarified byte ordering within exported name object. Stated that
5567 GSS_S_BAD_MECH is to be returned if, in the course of attempted
5568 import of an exported name object, the name object's enclosed
5569 mechanism type is unrecognized or unsupported.
5571 Stated that mechanisms may optionally accept GSS_C_NO_NAME as an
5572 input target name to GSS_Init_sec_context(), with comment that
5573 such support is unlikely within mechanisms predating GSS-V2,
5581 Bedford, MA 01730 USA
5583 Phone: +1 781.687.7817
5584 EMail: jlinn@rsasecurity.com
5602 Linn Standards Track [Page 100]
5604 RFC 2743 GSS-API January 2000
5607 Full Copyright Statement
5609 Copyright (C) The Internet Society (2000). All Rights Reserved.
5611 This document and translations of it may be copied and furnished to
5612 others, and derivative works that comment on or otherwise explain it
5613 or assist in its implementation may be prepared, copied, published
5614 and distributed, in whole or in part, without restriction of any
5615 kind, provided that the above copyright notice and this paragraph are
5616 included on all such copies and derivative works. However, this
5617 document itself may not be modified in any way, such as by removing
5618 the copyright notice or references to the Internet Society or other
5619 Internet organizations, except as needed for the purpose of
5620 developing Internet standards in which case the procedures for
5621 copyrights defined in the Internet Standards process must be
5622 followed, or as required to translate it into languages other than
5625 The limited permissions granted above are perpetual and will not be
5626 revoked by the Internet Society or its successors or assigns.
5628 This document and the information contained herein is provided on an
5629 "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING
5630 TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING
5631 BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION
5632 HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF
5633 MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
5637 Funding for the RFC Editor function is currently provided by the
5658 Linn Standards Track [Page 101]
projects / dragonfly.git / blob