diff options
Diffstat (limited to 'third_party/heimdal/doc/standardisation/rfc2743.txt')
| -rw-r--r-- | third_party/heimdal/doc/standardisation/rfc2743.txt | 5659 |
1 files changed, 5659 insertions, 0 deletions
diff --git a/third_party/heimdal/doc/standardisation/rfc2743.txt b/third_party/heimdal/doc/standardisation/rfc2743.txt new file mode 100644 index 00000000000..e5da571abb4 --- /dev/null +++ b/third_party/heimdal/doc/standardisation/rfc2743.txt @@ -0,0 +1,5659 @@ + + + + + + +Network Working Group J. Linn +Request for Comments: 2743 RSA Laboratories +Obsoletes: 2078 January 2000 +Category: Standards Track + + + Generic Security Service Application Program Interface + Version 2, Update 1 + + +Status of this Memo + + This document specifies an Internet standards track protocol for the + Internet community, and requests discussion and suggestions for + improvements. Please refer to the current edition of the "Internet + Official Protocol Standards" (STD 1) for the standardization state + and status of this protocol. Distribution of this memo is unlimited. + +Copyright Notice + + Copyright (C) The Internet Society (2000). All Rights Reserved. + +Abstract + + The Generic Security Service Application Program Interface (GSS-API), + Version 2, as defined in [RFC-2078], provides security services to + callers in a generic fashion, supportable with a range of underlying + mechanisms and technologies and hence allowing source-level + portability of applications to different environments. This + specification defines GSS-API services and primitives at a level + independent of underlying mechanism and programming language + environment, and is to be complemented by other, related + specifications: + + documents defining specific parameter bindings for particular + language environments + + documents defining token formats, protocols, and procedures to be + implemented in order to realize GSS-API services atop particular + security mechanisms + + This memo obsoletes [RFC-2078], making specific, incremental changes + in response to implementation experience and liaison requests. It is + intended, therefore, that this memo or a successor version thereto + will become the basis for subsequent progression of the GSS-API + specification on the standards track. + + + + + +Linn Standards Track [Page 1] + +RFC 2743 GSS-API January 2000 + + +TABLE OF CONTENTS + + 1: GSS-API Characteristics and Concepts . . . . . . . . . . . . 4 + 1.1: GSS-API Constructs . . . . . . . . . . . . . . . . . . . . 6 + 1.1.1: Credentials . . . . . . . . . . . . . . . . . . . . . . 6 + 1.1.1.1: Credential Constructs and Concepts . . . . . . . . . . 6 + 1.1.1.2: Credential Management . . . . . . . . . . . . . . . . 7 + 1.1.1.3: Default Credential Resolution . . . . . . . . . . . . 8 + 1.1.2: Tokens . . . . . . . . . . . . . . . . . . . . . . . . . 9 + 1.1.3: Security Contexts . . . . . . . . . . . . . . . . . . . 11 + 1.1.4: Mechanism Types . . . . . . . . . . . . . . . . . . . . 12 + 1.1.5: Naming . . . . . . . . . . . . . . . . . . . . . . . . 13 + 1.1.6: Channel Bindings . . . . . . . . . . . . . . . . . . . 16 + 1.2: GSS-API Features and Issues . . . . . . . . . . . . . . . 17 + 1.2.1: Status Reporting and Optional Service Support . . . . 17 + 1.2.1.1: Status Reporting . . . . . . . . . . . . . . . . . . . 17 + 1.2.1.2: Optional Service Support . . . . . . . . . . . . . . . 19 + 1.2.2: Per-Message Security Service Availability . . . . . . . 20 + 1.2.3: Per-Message Replay Detection and Sequencing . . . . . . 21 + 1.2.4: Quality of Protection . . . . . . . . . . . . . . . . . 24 + 1.2.5: Anonymity Support . . . . . . . . . . . . . . . . . . . 25 + 1.2.6: Initialization . . . . . . . . . . . . . . . . . . . . . 25 + 1.2.7: Per-Message Protection During Context Establishment . . 26 + 1.2.8: Implementation Robustness . . . . . . . . . . . . . . . 27 + 1.2.9: Delegation . . . . . . . . . . . . . . . . . . . . . . . 28 + 1.2.10: Interprocess Context Transfer . . . . . . . . . . . . . 28 + 2: Interface Descriptions . . . . . . . . . . . . . . . . . . 29 + 2.1: Credential management calls . . . . . . . . . . . . . . . 31 + 2.1.1: GSS_Acquire_cred call . . . . . . . . . . . . . . . . . 31 + 2.1.2: GSS_Release_cred call . . . . . . . . . . . . . . . . . 34 + 2.1.3: GSS_Inquire_cred call . . . . . . . . . . . . . . . . . 35 + 2.1.4: GSS_Add_cred call . . . . . . . . . . . . . . . . . . . 37 + 2.1.5: GSS_Inquire_cred_by_mech call . . . . . . . . . . . . . 40 + 2.2: Context-level calls . . . . . . . . . . . . . . . . . . . 41 + 2.2.1: GSS_Init_sec_context call . . . . . . . . . . . . . . . 42 + 2.2.2: GSS_Accept_sec_context call . . . . . . . . . . . . . . 49 + 2.2.3: GSS_Delete_sec_context call . . . . . . . . . . . . . . 53 + 2.2.4: GSS_Process_context_token call . . . . . . . . . . . . 54 + 2.2.5: GSS_Context_time call . . . . . . . . . . . . . . . . . 55 + 2.2.6: GSS_Inquire_context call . . . . . . . . . . . . . . . 56 + 2.2.7: GSS_Wrap_size_limit call . . . . . . . . . . . . . . . 57 + 2.2.8: GSS_Export_sec_context call . . . . . . . . . . . . . . 59 + 2.2.9: GSS_Import_sec_context call . . . . . . . . . . . . . . 61 + 2.3: Per-message calls . . . . . . . . . . . . . . . . . . . . 62 + 2.3.1: GSS_GetMIC call . . . . . . . . . . . . . . . . . . . . 63 + 2.3.2: GSS_VerifyMIC call . . . . . . . . . . . . . . . . . . 64 + 2.3.3: GSS_Wrap call . . . . . . . . . . . . . . . . . . . . . 65 + 2.3.4: GSS_Unwrap call . . . . . . . . . . . . . . . . . . . . 66 + + + +Linn Standards Track [Page 2] + +RFC 2743 GSS-API January 2000 + + + 2.4: Support calls . . . . . . . . . . . . . . . . . . . . . . 68 + 2.4.1: GSS_Display_status call . . . . . . . . . . . . . . . . 68 + 2.4.2: GSS_Indicate_mechs call . . . . . . . . . . . . . . . . 69 + 2.4.3: GSS_Compare_name call . . . . . . . . . . . . . . . . . 70 + 2.4.4: GSS_Display_name call . . . . . . . . . . . . . . . . . 71 + 2.4.5: GSS_Import_name call . . . . . . . . . . . . . . . . . 72 + 2.4.6: GSS_Release_name call . . . . . . . . . . . . . . . . . 73 + 2.4.7: GSS_Release_buffer call . . . . . . . . . . . . . . . . 74 + 2.4.8: GSS_Release_OID_set call . . . . . . . . . . . . . . . 74 + 2.4.9: GSS_Create_empty_OID_set call . . . . . . . . . . . . . 75 + 2.4.10: GSS_Add_OID_set_member call . . . . . . . . . . . . . . 76 + 2.4.11: GSS_Test_OID_set_member call . . . . . . . . . . . . . 76 + 2.4.12: GSS_Inquire_names_for_mech call . . . . . . . . . . . . 77 + 2.4.13: GSS_Inquire_mechs_for_name call . . . . . . . . . . . . 77 + 2.4.14: GSS_Canonicalize_name call . . . . . . . . . . . . . . 78 + 2.4.15: GSS_Export_name call . . . . . . . . . . . . . . . . . 79 + 2.4.16: GSS_Duplicate_name call . . . . . . . . . . . . . . . . 80 + 3: Data Structure Definitions for GSS-V2 Usage . . . . . . . . 81 + 3.1: Mechanism-Independent Token Format . . . . . . . . . . . . 81 + 3.2: Mechanism-Independent Exported Name Object Format . . . . 84 + 4: Name Type Definitions . . . . . . . . . . . . . . . . . . . 85 + 4.1: Host-Based Service Name Form . . . . . . . . . . . . . . . 85 + 4.2: User Name Form . . . . . . . . . . . . . . . . . . . . . . 86 + 4.3: Machine UID Form . . . . . . . . . . . . . . . . . . . . . 87 + 4.4: String UID Form . . . . . . . . . . . . . . . . . . . . . 87 + 4.5: Anonymous Nametype . . . . . . . . . . . . . . . . . . . . 87 + 4.6: GSS_C_NO_OID . . . . . . . . . . . . . . . . . . . . . . . 88 + 4.7: Exported Name Object . . . . . . . . . . . . . . . . . . . 88 + 4.8: GSS_C_NO_NAME . . . . . . . . . . . . . . . . . . . . . . 88 + 5: Mechanism-Specific Example Scenarios . . . . . . . . . . . 88 + 5.1: Kerberos V5, single-TGT . . . . . . . . . . . . . . . . . 89 + 5.2: Kerberos V5, double-TGT . . . . . . . . . . . . . . . . . 89 + 5.3: X.509 Authentication Framework . . . . . . . . . . . . . 90 + 6: Security Considerations . . . . . . . . . . . . . . . . . . 91 + 7: Related Activities . . . . . . . . . . . . . . . . . . . . 92 + 8: Referenced Documents . . . . . . . . . . . . . . . . . . . 93 + Appendix A: Mechanism Design Constraints . . . . . . . . . . . 94 + Appendix B: Compatibility with GSS-V1 . . . . . . . . . . . . . 94 + Appendix C: Changes Relative to RFC-2078 . . . . . . . . . . . 96 + Author's Address . . . . . . . . . . . . . . . . . . . . . . .100 + Full Copyright Statement . . . . . . . . . . . . . . . . . . .101 + + + + + + + + + + +Linn Standards Track [Page 3] + +RFC 2743 GSS-API January 2000 + + +1: GSS-API Characteristics and Concepts + + GSS-API operates in the following paradigm. A typical GSS-API caller + is itself a communications protocol, calling on GSS-API in order to + protect its communications with authentication, integrity, and/or + confidentiality security services. A GSS-API caller accepts tokens + provided to it by its local GSS-API implementation and transfers the + tokens to a peer on a remote system; that peer passes the received + tokens to its local GSS-API implementation for processing. The + security services available through GSS-API in this fashion are + implementable (and have been implemented) over a range of underlying + mechanisms based on secret-key and public-key cryptographic + technologies. + + The GSS-API separates the operations of initializing a security + context between peers, achieving peer entity authentication + (GSS_Init_sec_context() and GSS_Accept_sec_context() calls), from the + operations of providing per-message data origin authentication and + data integrity protection (GSS_GetMIC() and GSS_VerifyMIC() calls) + for messages subsequently transferred in conjunction with that + context. (The definition for the peer entity authentication service, + and other definitions used in this document, corresponds to that + provided in [ISO-7498-2].) When establishing a security context, the + GSS-API enables a context initiator to optionally permit its + credentials to be delegated, meaning that the context acceptor may + initiate further security contexts on behalf of the initiating + caller. Per-message GSS_Wrap() and GSS_Unwrap() calls provide the + data origin authentication and data integrity services which + GSS_GetMIC() and GSS_VerifyMIC() offer, and also support selection of + confidentiality services as a caller option. Additional calls provide + supportive functions to the GSS-API's users. + + The following paragraphs provide an example illustrating the + dataflows involved in use of the GSS-API by a client and server in a + mechanism-independent fashion, establishing a security context and + transferring a protected message. The example assumes that credential + acquisition has already been completed. The example also assumes + that the underlying authentication technology is capable of + authenticating a client to a server using elements carried within a + single token, and of authenticating the server to the client (mutual + authentication) with a single returned token; this assumption holds + for some presently-documented CAT mechanisms but is not necessarily + true for other cryptographic technologies and associated protocols. + + The client calls GSS_Init_sec_context() to establish a security + context to the server identified by targ_name, and elects to set the + mutual_req_flag so that mutual authentication is performed in the + course of context establishment. GSS_Init_sec_context() returns an + + + +Linn Standards Track [Page 4] + +RFC 2743 GSS-API January 2000 + + + output_token to be passed to the server, and indicates + GSS_S_CONTINUE_NEEDED status pending completion of the mutual + authentication sequence. Had mutual_req_flag not been set, the + initial call to GSS_Init_sec_context() would have returned + GSS_S_COMPLETE status. The client sends the output_token to the + server. + + The server passes the received token as the input_token parameter to + GSS_Accept_sec_context(). GSS_Accept_sec_context indicates + GSS_S_COMPLETE status, provides the client's authenticated identity + in the src_name result, and provides an output_token to be passed to + the client. The server sends the output_token to the client. + + The client passes the received token as the input_token parameter to + a successor call to GSS_Init_sec_context(), which processes data + included in the token in order to achieve mutual authentication from + the client's viewpoint. This call to GSS_Init_sec_context() returns + GSS_S_COMPLETE status, indicating successful mutual authentication + and the completion of context establishment for this example. + + The client generates a data message and passes it to GSS_Wrap(). + GSS_Wrap() performs data origin authentication, data integrity, and + (optionally) confidentiality processing on the message and + encapsulates the result into output_message, indicating + GSS_S_COMPLETE status. The client sends the output_message to the + server. + + The server passes the received message to GSS_Unwrap(). GSS_Unwrap() + inverts the encapsulation performed by GSS_Wrap(), deciphers the + message if the optional confidentiality feature was applied, and + validates the data origin authentication and data integrity checking + quantities. GSS_Unwrap() indicates successful validation by returning + GSS_S_COMPLETE status along with the resultant output_message. + + For purposes of this example, we assume that the server knows by + out-of-band means that this context will have no further use after + one protected message is transferred from client to server. Given + this premise, the server now calls GSS_Delete_sec_context() to flush + context-level information. Optionally, the server-side application + may provide a token buffer to GSS_Delete_sec_context(), to receive a + context_token to be transferred to the client in order to request + that client-side context-level information be deleted. + + If a context_token is transferred, the client passes the + context_token to GSS_Process_context_token(), which returns + GSS_S_COMPLETE status after deleting context-level information at the + client system. + + + + +Linn Standards Track [Page 5] + +RFC 2743 GSS-API January 2000 + + + The GSS-API design assumes and addresses several basic goals, + including: + + Mechanism independence: The GSS-API defines an interface to + cryptographically implemented strong authentication and other + security services at a generic level which is independent of + particular underlying mechanisms. For example, GSS-API-provided + services have been implemented using secret-key technologies + (e.g., Kerberos, per [RFC-1964]) and with public-key approaches + (e.g., SPKM, per [RFC-2025]). + + Protocol environment independence: The GSS-API is independent of + the communications protocol suites with which it is employed, + permitting use in a broad range of protocol environments. In + appropriate environments, an intermediate implementation "veneer" + which is oriented to a particular communication protocol may be + interposed between applications which call that protocol and the + GSS-API (e.g., as defined in [RFC-2203] for Open Network Computing + Remote Procedure Call (RPC)), thereby invoking GSS-API facilities + in conjunction with that protocol's communications invocations. + + Protocol association independence: The GSS-API's security context + construct is independent of communications protocol association + constructs. This characteristic allows a single GSS-API + implementation to be utilized by a variety of invoking protocol + modules on behalf of those modules' calling applications. GSS-API + services can also be invoked directly by applications, wholly + independent of protocol associations. + + Suitability to a range of implementation placements: GSS-API + clients are not constrained to reside within any Trusted Computing + Base (TCB) perimeter defined on a system where the GSS-API is + implemented; security services are specified in a manner suitable + to both intra-TCB and extra-TCB callers. + +1.1: GSS-API Constructs + + This section describes the basic elements comprising the GSS-API. + +1.1.1: Credentials + +1.1.1.1: Credential Constructs and Concepts + + Credentials provide the prerequisites which permit GSS-API peers to + establish security contexts with each other. A caller may designate + that the credential elements which are to be applied for context + initiation or acceptance be selected by default. Alternately, those + GSS-API callers which need to make explicit selection of particular + + + +Linn Standards Track [Page 6] + +RFC 2743 GSS-API January 2000 + + + credentials structures may make references to those credentials + through GSS-API-provided credential handles ("cred_handles"). In all + cases, callers' credential references are indirect, mediated by GSS- + API implementations and not requiring callers to access the selected + credential elements. + + A single credential structure may be used to initiate outbound + contexts and to accept inbound contexts. Callers needing to operate + in only one of these modes may designate this fact when credentials + are acquired for use, allowing underlying mechanisms to optimize + their processing and storage requirements. The credential elements + defined by a particular mechanism may contain multiple cryptographic + keys, e.g., to enable authentication and message encryption to be + performed with different algorithms. + + A GSS-API credential structure may contain multiple credential + elements, each containing mechanism-specific information for a + particular underlying mechanism (mech_type), but the set of elements + within a given credential structure represent a common entity. A + credential structure's contents will vary depending on the set of + mech_types supported by a particular GSS-API implementation. Each + credential element identifies the data needed by its mechanism in + order to establish contexts on behalf of a particular principal, and + may contain separate credential references for use in context + initiation and context acceptance. Multiple credential elements + within a given credential having overlapping combinations of + mechanism, usage mode, and validity period are not permitted. + + Commonly, a single mech_type will be used for all security contexts + established by a particular initiator to a particular target. A major + motivation for supporting credential sets representing multiple + mech_types is to allow initiators on systems which are equipped to + handle multiple types to initiate contexts to targets on other + systems which can accommodate only a subset of the set supported at + the initiator's system. + +1.1.1.2: Credential Management + + It is the responsibility of underlying system-specific mechanisms and + OS functions below the GSS-API to ensure that the ability to acquire + and use credentials associated with a given identity is constrained + to appropriate processes within a system. This responsibility should + be taken seriously by implementors, as the ability for an entity to + utilize a principal's credentials is equivalent to the entity's + ability to successfully assert that principal's identity. + + + + + + +Linn Standards Track [Page 7] + +RFC 2743 GSS-API January 2000 + + + Once a set of GSS-API credentials is established, the transferability + of that credentials set to other processes or analogous constructs + within a system is a local matter, not defined by the GSS-API. An + example local policy would be one in which any credentials received + as a result of login to a given user account, or of delegation of + rights to that account, are accessible by, or transferable to, + processes running under that account. + + The credential establishment process (particularly when performed on + behalf of users rather than server processes) is likely to require + access to passwords or other quantities which should be protected + locally and exposed for the shortest time possible. As a result, it + will often be appropriate for preliminary credential establishment to + be performed through local means at user login time, with the + result(s) cached for subsequent reference. These preliminary + credentials would be set aside (in a system-specific fashion) for + subsequent use, either: + + to be accessed by an invocation of the GSS-API GSS_Acquire_cred() + call, returning an explicit handle to reference that credential + + to comprise default credential elements to be installed, and to be + used when default credential behavior is requested on behalf of a + process + +1.1.1.3: Default Credential Resolution + + The GSS_Init_sec_context() and GSS_Accept_sec_context() routines + allow the value GSS_C_NO_CREDENTIAL to be specified as their + credential handle parameter. This special credential handle + indicates a desire by the application to act as a default principal. + In support of application portability, support for the default + resolution behavior described below for initiator credentials + (GSS_Init_sec_context() usage) is mandated; support for the default + resolution behavior described below for acceptor credentials + (GSS_Accept_sec_context() usage) is recommended. If default + credential resolution fails, GSS_S_NO_CRED status is to be returned. + + GSS_Init_sec_context: + + (i) If there is only a single principal capable of initiating + security contexts that the application is authorized to act on + behalf of, then that principal shall be used, otherwise + + + + + + + + +Linn Standards Track [Page 8] + +RFC 2743 GSS-API January 2000 + + + (ii) If the platform maintains a concept of a default network- + identity, and if the application is authorized to act on behalf + of that identity for the purpose of initiating security + contexts, then the principal corresponding to that identity + shall be used, otherwise + + (iii) If the platform maintains a concept of a default local + identity, and provides a means to map local identities into + network-identities, and if the application is authorized to act + on behalf of the network-identity image of the default local + identity for the purpose of initiating security contexts, then + the principal corresponding to that identity shall be used, + otherwise + + (iv) A user-configurable default identity should be used. + + GSS_Accept_sec_context: + + (i) If there is only a single authorized principal identity + capable of accepting security contexts, then that principal + shall be used, otherwise + + (ii) If the mechanism can determine the identity of the target + principal by examining the context-establishment token, and if + the accepting application is authorized to act as that + principal for the purpose of accepting security contexts, then + that principal identity shall be used, otherwise + + (iii) If the mechanism supports context acceptance by any + principal, and mutual authentication was not requested, any + principal that the application is authorized to accept security + contexts under may be used, otherwise + + (iv) A user-configurable default identity shall be used. + + The purpose of the above rules is to allow security contexts to be + established by both initiator and acceptor using the default behavior + wherever possible. Applications requesting default behavior are + likely to be more portable across mechanisms and platforms than those + that use GSS_Acquire_cred() to request a specific identity. + +1.1.2: Tokens + + Tokens are data elements transferred between GSS-API callers, and are + divided into two classes. Context-level tokens are exchanged in order + to establish and manage a security context between peers. Per-message + tokens relate to an established context and are exchanged to provide + + + + +Linn Standards Track [Page 9] + +RFC 2743 GSS-API January 2000 + + + protective security services (i.e., data origin authentication, + integrity, and optional confidentiality) for corresponding data + messages. + + The first context-level token obtained from GSS_Init_sec_context() is + required to indicate at its very beginning a globally-interpretable + mechanism identifier, i.e., an Object Identifier (OID) of the + security mechanism. The remaining part of this token as well as the + whole content of all other tokens are specific to the particular + underlying mechanism used to support the GSS-API. Section 3.1 of this + document provides, for designers of GSS-API mechanisms, the + description of the header of the first context-level token which is + then followed by mechanism-specific information. + + Tokens' contents are opaque from the viewpoint of GSS-API callers. + They are generated within the GSS-API implementation at an end + system, provided to a GSS-API caller to be transferred to the peer + GSS-API caller at a remote end system, and processed by the GSS-API + implementation at that remote end system. + + Context-level tokens may be output by GSS-API calls (and should be + transferred to GSS-API peers) whether or not the calls' status + indicators indicate successful completion. Per-message tokens, in + contrast, are to be returned only upon successful completion of per- + message calls. Zero-length tokens are never returned by GSS routines + for transfer to a peer. Token transfer may take place in an in-band + manner, integrated into the same protocol stream used by the GSS-API + callers for other data transfers, or in an out-of-band manner across + a logically separate channel. + + Different GSS-API tokens are used for different purposes (e.g., + context initiation, context acceptance, protected message data on an + established context), and it is the responsibility of a GSS-API + caller receiving tokens to distinguish their types, associate them + with corresponding security contexts, and pass them to appropriate + GSS-API processing routines. Depending on the caller protocol + environment, this distinction may be accomplished in several ways. + + The following examples illustrate means through which tokens' types + may be distinguished: + + - implicit tagging based on state information (e.g., all tokens on + a new association are considered to be context establishment + tokens until context establishment is completed, at which point + all tokens are considered to be wrapped data objects for that + context), + + + + + +Linn Standards Track [Page 10] + +RFC 2743 GSS-API January 2000 + + + - explicit tagging at the caller protocol level, + + - a hybrid of these approaches. + + Commonly, the encapsulated data within a token includes internal + mechanism-specific tagging information, enabling mechanism-level + processing modules to distinguish tokens used within the mechanism + for different purposes. Such internal mechanism-level tagging is + recommended to mechanism designers, and enables mechanisms to + determine whether a caller has passed a particular token for + processing by an inappropriate GSS-API routine. + + Development of GSS-API mechanisms based on a particular underlying + cryptographic technique and protocol (i.e., conformant to a specific + GSS-API mechanism definition) does not necessarily imply that GSS-API + callers using that GSS-API mechanism will be able to interoperate + with peers invoking the same technique and protocol outside the GSS- + API paradigm, or with peers implementing a different GSS-API + mechanism based on the same underlying technology. The format of + GSS-API tokens defined in conjunction with a particular mechanism, + and the techniques used to integrate those tokens into callers' + protocols, may not be interoperable with the tokens used by non-GSS- + API callers of the same underlying technique. + +1.1.3: Security Contexts + + Security contexts are established between peers, using credentials + established locally in conjunction with each peer or received by + peers via delegation. Multiple contexts may exist simultaneously + between a pair of peers, using the same or different sets of + credentials. Coexistence of multiple contexts using different + credentials allows graceful rollover when credentials expire. + Distinction among multiple contexts based on the same credentials + serves applications by distinguishing different message streams in a + security sense. + + The GSS-API is independent of underlying protocols and addressing + structure, and depends on its callers to transport GSS-API-provided + data elements. As a result of these factors, it is a caller + responsibility to parse communicated messages, separating GSS-API- + related data elements from caller-provided data. The GSS-API is + independent of connection vs. connectionless orientation of the + underlying communications service. + + No correlation between security context and communications protocol + association is dictated. (The optional channel binding facility, + discussed in Section 1.1.6 of this document, represents an + intentional exception to this rule, supporting additional protection + + + +Linn Standards Track [Page 11] + +RFC 2743 GSS-API January 2000 + + + features within GSS-API supporting mechanisms.) This separation + allows the GSS-API to be used in a wide range of communications + environments, and also simplifies the calling sequences of the + individual calls. In many cases (depending on underlying security + protocol, associated mechanism, and availability of cached + information), the state information required for context setup can be + sent concurrently with initial signed user data, without interposing + additional message exchanges. Messages may be protected and + transferred in both directions on an established GSS-API security + context concurrently; protection of messages in one direction does + not interfere with protection of messages in the reverse direction. + + GSS-API implementations are expected to retain inquirable context + data on a context until the context is released by a caller, even + after the context has expired, although underlying cryptographic data + elements may be deleted after expiration in order to limit their + exposure. + +1.1.4: Mechanism Types + + In order to successfully establish a security context with a target + peer, it is necessary to identify an appropriate underlying mechanism + type (mech_type) which both initiator and target peers support. The + definition of a mechanism embodies not only the use of a particular + cryptographic technology (or a hybrid or choice among alternative + cryptographic technologies), but also definition of the syntax and + semantics of data element exchanges which that mechanism will employ + in order to support security services. + + It is recommended that callers initiating contexts specify the + "default" mech_type value, allowing system-specific functions within + or invoked by the GSS-API implementation to select the appropriate + mech_type, but callers may direct that a particular mech_type be + employed when necessary. + + For GSS-API purposes, the phrase "negotiating mechanism" refers to a + mechanism which itself performs negotiation in order to select a + concrete mechanism which is shared between peers and is then used for + context establishment. Only those mechanisms which are defined in + their specifications as negotiating mechanisms are to yield selected + mechanisms with different identifier values than the value which is + input by a GSS-API caller, except for the case of a caller requesting + the "default" mech_type. + + The means for identifying a shared mech_type to establish a security + context with a peer will vary in different environments and + circumstances; examples include (but are not limited to): + + + + +Linn Standards Track [Page 12] + +RFC 2743 GSS-API January 2000 + + + use of a fixed mech_type, defined by configuration, within an + environment + + syntactic convention on a target-specific basis, through + examination of a target's name lookup of a target's name in a + naming service or other database in order to identify mech_types + supported by that target + + explicit negotiation between GSS-API callers in advance of + security context setup + + use of a negotiating mechanism + + When transferred between GSS-API peers, mech_type specifiers (per + Section 3 of this document, represented as Object Identifiers (OIDs)) + serve to qualify the interpretation of associated tokens. (The + structure and encoding of Object Identifiers is defined in [ISOIEC- + 8824] and [ISOIEC-8825].) Use of hierarchically structured OIDs + serves to preclude ambiguous interpretation of mech_type specifiers. + The OID representing the DASS ([RFC-1507]) MechType, for example, is + 1.3.12.2.1011.7.5, and that of the Kerberos V5 mechanism ([RFC- + 1964]), having been advanced to the level of Proposed Standard, is + 1.2.840.113554.1.2.2. + +1.1.5: Naming + + The GSS-API avoids prescribing naming structures, treating the names + which are transferred across the interface in order to initiate and + accept security contexts as opaque objects. This approach supports + the GSS-API's goal of implementability atop a range of underlying + security mechanisms, recognizing the fact that different mechanisms + process and authenticate names which are presented in different + forms. Generalized services offering translation functions among + arbitrary sets of naming environments are outside the scope of the + GSS-API; availability and use of local conversion functions to + translate among the naming formats supported within a given end + system is anticipated. + + Different classes of name representations are used in conjunction + with different GSS-API parameters: + + - Internal form (denoted in this document by INTERNAL NAME), + opaque to callers and defined by individual GSS-API + implementations. GSS-API implementations supporting multiple + namespace types must maintain internal tags to disambiguate the + interpretation of particular names. A Mechanism Name (MN) is a + special case of INTERNAL NAME, guaranteed to contain elements + + + + +Linn Standards Track [Page 13] + +RFC 2743 GSS-API January 2000 + + + corresponding to one and only one mechanism; calls which are + guaranteed to emit MNs or which require MNs as input are so + identified within this specification. + + - Contiguous string ("flat") form (denoted in this document by + OCTET STRING); accompanied by OID tags identifying the namespace + to which they correspond. Depending on tag value, flat names may + or may not be printable strings for direct acceptance from and + presentation to users. Tagging of flat names allows GSS-API + callers and underlying GSS-API mechanisms to disambiguate name + types and to determine whether an associated name's type is one + which they are capable of processing, avoiding aliasing problems + which could result from misinterpreting a name of one type as a + name of another type. + + - The GSS-API Exported Name Object, a special case of flat name + designated by a reserved OID value, carries a canonicalized form + of a name suitable for binary comparisons. + + In addition to providing means for names to be tagged with types, + this specification defines primitives to support a level of naming + environment independence for certain calling applications. To provide + basic services oriented towards the requirements of callers which + need not themselves interpret the internal syntax and semantics of + names, GSS-API calls for name comparison (GSS_Compare_name()), + human-readable display (GSS_Display_name()), input conversion + (GSS_Import_name()), internal name deallocation (GSS_Release_name()), + and internal name duplication (GSS_Duplicate_name()) functions are + defined. (It is anticipated that these proposed GSS-API calls will be + implemented in many end systems based on system-specific name + manipulation primitives already extant within those end systems; + inclusion within the GSS-API is intended to offer GSS-API callers a + portable means to perform specific operations, supportive of + authorization and audit requirements, on authenticated names.) + + GSS_Import_name() implementations can, where appropriate, support + more than one printable syntax corresponding to a given namespace + (e.g., alternative printable representations for X.500 Distinguished + Names), allowing flexibility for their callers to select among + alternative representations. GSS_Display_name() implementations + output a printable syntax selected as appropriate to their + operational environments; this selection is a local matter. Callers + desiring portability across alternative printable syntaxes should + refrain from implementing comparisons based on printable name forms + and should instead use the GSS_Compare_name() call to determine + whether or not one internal-format name matches another. + + + + + +Linn Standards Track [Page 14] + +RFC 2743 GSS-API January 2000 + + + When used in large access control lists, the overhead of invoking + GSS_Import_name() and GSS_Compare_name() on each name from the ACL + may be prohibitive. As an alternative way of supporting this case, + GSS-API defines a special form of the contiguous string name which + may be compared directly (e.g., with memcmp()). Contiguous names + suitable for comparison are generated by the GSS_Export_name() + routine, which requires an MN as input. Exported names may be re- + imported by the GSS_Import_name() routine, and the resulting internal + name will also be an MN. The symbolic constant GSS_C_NT_EXPORT_NAME + identifies the "export name" type. Structurally, an exported name + object consists of a header containing an OID identifying the + mechanism that authenticated the name, and a trailer containing the + name itself, where the syntax of the trailer is defined by the + individual mechanism specification. The precise format of an + exported name is defined in Section 3.2 of this specification. + + Note that the results obtained by using GSS_Compare_name() will in + general be different from those obtained by invoking + GSS_Canonicalize_name() and GSS_Export_name(), and then comparing the + exported names. The first series of operations determines whether + two (unauthenticated) names identify the same principal; the second + whether a particular mechanism would authenticate them as the same + principal. These two operations will in general give the same + results only for MNs. + + The following diagram illustrates the intended dataflow among name- + related GSS-API processing routines. + + + + + + + + + + + + + + + + + + + + + + + + +Linn Standards Track [Page 15] + +RFC 2743 GSS-API January 2000 + + + GSS-API library defaults + | + | + V text, for + text --------------> internal_name (IN) -----------> display only + import_name() / display_name() + / + / + / + accept_sec_context() / + | / + | / + | / canonicalize_name() + | / + | / + | / + | / + | / + | | + V V <--------------------- + single mechanism import_name() exported name: flat + internal_name (MN) binary "blob" usable + ----------------------> for access control + export_name() + +1.1.6: Channel Bindings + + The GSS-API accommodates the concept of caller-provided channel + binding ("chan_binding") information. Channel bindings are used to + strengthen the quality with which peer entity authentication is + provided during context establishment, by limiting the scope within + which an intercepted context establishment token can be reused by an + attacker. Specifically, they enable GSS-API callers to bind the + establishment of a security context to relevant characteristics + (e.g., addresses, transformed representations of encryption keys) of + the underlying communications channel, of protection mechanisms + applied to that communications channel, and to application-specific + data. + + The caller initiating a security context must determine the + appropriate channel binding values to provide as input to the + GSS_Init_sec_context() call, and consistent values must be provided + to GSS_Accept_sec_context() by the context's target, in order for + both peers' GSS-API mechanisms to validate that received tokens + possess correct channel-related characteristics. Use or non-use of + the GSS-API channel binding facility is a caller option. GSS-API + mechanisms can operate in an environment where NULL channel bindings + are presented; mechanism implementors are encouraged, but not + + + +Linn Standards Track [Page 16] + +RFC 2743 GSS-API January 2000 + + + required, to make use of caller-provided channel binding data within + their mechanisms. Callers should not assume that underlying + mechanisms provide confidentiality protection for channel binding + information. + + When non-NULL channel bindings are provided by callers, certain + mechanisms can offer enhanced security value by interpreting the + bindings' content (rather than simply representing those bindings, or + integrity check values computed on them, within tokens) and will + therefore depend on presentation of specific data in a defined + format. To this end, agreements among mechanism implementors are + defining conventional interpretations for the contents of channel + binding arguments, including address specifiers (with content + dependent on communications protocol environment) for context + initiators and acceptors. (These conventions are being incorporated + in GSS-API mechanism specifications and into the GSS-API C language + bindings specification.) In order for GSS-API callers to be portable + across multiple mechanisms and achieve the full security + functionality which each mechanism can provide, it is strongly + recommended that GSS-API callers provide channel bindings consistent + with these conventions and those of the networking environment in + which they operate. + +1.2: GSS-API Features and Issues + + This section describes aspects of GSS-API operations, of the security + services which the GSS-API provides, and provides commentary on + design issues. + +1.2.1: Status Reporting and Optional Service Support + +1.2.1.1: Status Reporting + + Each GSS-API call provides two status return values. Major_status + values provide a mechanism-independent indication of call status + (e.g., GSS_S_COMPLETE, GSS_S_FAILURE, GSS_S_CONTINUE_NEEDED), + sufficient to drive normal control flow within the caller in a + generic fashion. Table 1 summarizes the defined major_status return + codes in tabular fashion. + + Sequencing-related informatory major_status codes + (GSS_S_DUPLICATE_TOKEN, GSS_S_OLD_TOKEN, GSS_S_UNSEQ_TOKEN, and + GSS_S_GAP_TOKEN) can be indicated in conjunction with either + GSS_S_COMPLETE or GSS_S_FAILURE status for GSS-API per-message calls. + For context establishment calls, these sequencing-related codes will + be indicated only in conjunction with GSS_S_FAILURE status (never in + + + + + +Linn Standards Track [Page 17] + +RFC 2743 GSS-API January 2000 + + + conjunction with GSS_S_COMPLETE or GSS_S_CONTINUE_NEEDED), and, + therefore, always correspond to fatal failures if encountered during + the context establishment phase. + + Table 1: GSS-API Major Status Codes + + FATAL ERROR CODES + + GSS_S_BAD_BINDINGS channel binding mismatch + GSS_S_BAD_MECH unsupported mechanism requested + GSS_S_BAD_NAME invalid name provided + GSS_S_BAD_NAMETYPE name of unsupported type provided + GSS_S_BAD_STATUS invalid input status selector + GSS_S_BAD_SIG token had invalid integrity check + GSS_S_BAD_MIC preferred alias for GSS_S_BAD_SIG + GSS_S_CONTEXT_EXPIRED specified security context expired + GSS_S_CREDENTIALS_EXPIRED expired credentials detected + GSS_S_DEFECTIVE_CREDENTIAL defective credential detected + GSS_S_DEFECTIVE_TOKEN defective token detected + GSS_S_FAILURE failure, unspecified at GSS-API + level + GSS_S_NO_CONTEXT no valid security context specified + GSS_S_NO_CRED no valid credentials provided + GSS_S_BAD_QOP unsupported QOP value + GSS_S_UNAUTHORIZED operation unauthorized + GSS_S_UNAVAILABLE operation unavailable + GSS_S_DUPLICATE_ELEMENT duplicate credential element requested + GSS_S_NAME_NOT_MN name contains multi-mechanism elements + + INFORMATORY STATUS CODES + + GSS_S_COMPLETE normal completion + GSS_S_CONTINUE_NEEDED continuation call to routine + required + GSS_S_DUPLICATE_TOKEN duplicate per-message token + detected + GSS_S_OLD_TOKEN timed-out per-message token + detected + GSS_S_UNSEQ_TOKEN reordered (early) per-message token + detected + GSS_S_GAP_TOKEN skipped predecessor token(s) + detected + + Minor_status provides more detailed status information which may + include status codes specific to the underlying security mechanism. + Minor_status values are not specified in this document. + + + + + +Linn Standards Track [Page 18] + +RFC 2743 GSS-API January 2000 + + + GSS_S_CONTINUE_NEEDED major_status returns, and optional message + outputs, are provided in GSS_Init_sec_context() and + GSS_Accept_sec_context() calls so that different mechanisms' + employment of different numbers of messages within their + authentication sequences need not be reflected in separate code paths + within calling applications. Instead, such cases are accommodated + with sequences of continuation calls to GSS_Init_sec_context() and + GSS_Accept_sec_context(). The same facility is used to encapsulate + mutual authentication within the GSS-API's context initiation calls. + + For mech_types which require interactions with third-party servers in + order to establish a security context, GSS-API context establishment + calls may block pending completion of such third-party interactions. + On the other hand, no GSS-API calls pend on serialized interactions + with GSS-API peer entities. As a result, local GSS-API status + returns cannot reflect unpredictable or asynchronous exceptions + occurring at remote peers, and reflection of such status information + is a caller responsibility outside the GSS-API. + +1.2.1.2: Optional Service Support + + A context initiator may request various optional services at context + establishment time. Each of these services is requested by setting a + flag in the req_flags input parameter to GSS_Init_sec_context(). + + The optional services currently defined are: + + - Delegation - The (usually temporary) transfer of rights from + initiator to acceptor, enabling the acceptor to authenticate + itself as an agent of the initiator. + + - Mutual Authentication - In addition to the initiator + authenticating its identity to the context acceptor, the context + acceptor should also authenticate itself to the initiator. + + - Replay detection - In addition to providing message integrity + services, GSS_GetMIC() and GSS_Wrap() should include message + numbering information to enable GSS_VerifyMIC() and GSS_Unwrap() + to detect if a message has been duplicated. + + - Out-of-sequence detection - In addition to providing message + integrity services, GSS_GetMIC() and GSS_Wrap() should include + message sequencing information to enable GSS_VerifyMIC() and + GSS_Unwrap() to detect if a message has been received out of + sequence. + + + + + + +Linn Standards Track [Page 19] + +RFC 2743 GSS-API January 2000 + + + - Anonymous authentication - The establishment of the security + context should not reveal the initiator's identity to the context + acceptor. + + - Available per-message confidentiality - requests that per- + message confidentiality services be available on the context. + + - Available per-message integrity - requests that per-message + integrity services be available on the context. + + Any currently undefined bits within such flag arguments should be + ignored by GSS-API implementations when presented by an application, + and should be set to zero when returned to the application by the + GSS-API implementation. + + Some mechanisms may not support all optional services, and some + mechanisms may only support some services in conjunction with others. + Both GSS_Init_sec_context() and GSS_Accept_sec_context() inform the + applications which services will be available from the context when + the establishment phase is complete, via the ret_flags output + parameter. In general, if the security mechanism is capable of + providing a requested service, it should do so, even if additional + services must be enabled in order to provide the requested service. + If the mechanism is incapable of providing a requested service, it + should proceed without the service, leaving the application to abort + the context establishment process if it considers the requested + service to be mandatory. + + Some mechanisms may specify that support for some services is + optional, and that implementors of the mechanism need not provide it. + This is most commonly true of the confidentiality service, often + because of legal restrictions on the use of data-encryption, but may + apply to any of the services. Such mechanisms are required to send + at least one token from acceptor to initiator during context + establishment when the initiator indicates a desire to use such a + service, so that the initiating GSS-API can correctly indicate + whether the service is supported by the acceptor's GSS-API. + +1.2.2: Per-Message Security Service Availability + + When a context is established, two flags are returned to indicate the + set of per-message protection security services which will be + available on the context: + + the integ_avail flag indicates whether per-message integrity and + data origin authentication services are available + + + + + +Linn Standards Track [Page 20] + +RFC 2743 GSS-API January 2000 + + + the conf_avail flag indicates whether per-message confidentiality + services are available, and will never be returned TRUE unless the + integ_avail flag is also returned TRUE + + GSS-API callers desiring per-message security services should check + the values of these flags at context establishment time, and must be + aware that a returned FALSE value for integ_avail means that + invocation of GSS_GetMIC() or GSS_Wrap() primitives on the associated + context will apply no cryptographic protection to user data messages. + + The GSS-API per-message integrity and data origin authentication + services provide assurance to a receiving caller that protection was + applied to a message by the caller's peer on the security context, + corresponding to the entity named at context initiation. The GSS-API + per-message confidentiality service provides assurance to a sending + caller that the message's content is protected from access by + entities other than the context's named peer. + + The GSS-API per-message protection service primitives, as the + category name implies, are oriented to operation at the granularity + of protocol data units. They perform cryptographic operations on the + data units, transfer cryptographic control information in tokens, + and, in the case of GSS_Wrap(), encapsulate the protected data unit. + As such, these primitives are not oriented to efficient data + protection for stream-paradigm protocols (e.g., Telnet) if + cryptography must be applied on an octet-by-octet basis. + +1.2.3: Per-Message Replay Detection and Sequencing + + Certain underlying mech_types offer support for replay detection + and/or sequencing of messages transferred on the contexts they + support. These optionally-selectable protection features are distinct + from replay detection and sequencing features applied to the context + establishment operation itself; the presence or absence of context- + level replay or sequencing features is wholly a function of the + underlying mech_type's capabilities, and is not selected or omitted + as a caller option. + + The caller initiating a context provides flags (replay_det_req_flag + and sequence_req_flag) to specify whether the use of per-message + replay detection and sequencing features is desired on the context + being established. The GSS-API implementation at the initiator system + can determine whether these features are supported (and whether they + are optionally selectable) as a function of the selected mechanism, + without need for bilateral negotiation with the target. When enabled, + these features provide recipients with indicators as a result of + GSS-API processing of incoming messages, identifying whether those + messages were detected as duplicates or out-of-sequence. Detection of + + + +Linn Standards Track [Page 21] + +RFC 2743 GSS-API January 2000 + + + such events does not prevent a suspect message from being provided to + a recipient; the appropriate course of action on a suspect message is + a matter of caller policy. + + The semantics of the replay detection and sequencing services applied + to received messages, as visible across the interface which the GSS- + API provides to its clients, are as follows: + + When replay_det_state is TRUE, the possible major_status returns for + well-formed and correctly signed messages are as follows: + + 1. GSS_S_COMPLETE, without concurrent indication of + GSS_S_DUPLICATE_TOKEN or GSS_S_OLD_TOKEN, indicates that the + message was within the window (of time or sequence space) allowing + replay events to be detected, and that the message was not a + replay of a previously-processed message within that window. + + 2. GSS_S_DUPLICATE_TOKEN indicates that the cryptographic + checkvalue on the received message was correct, but that the + message was recognized as a duplicate of a previously-processed + message. In addition to identifying duplicated tokens originated + by a context's peer, this status may also be used to identify + reflected copies of locally-generated tokens; it is recommended + that mechanism designers include within their protocols facilities + to detect and report such tokens. + + 3. GSS_S_OLD_TOKEN indicates that the cryptographic checkvalue on + the received message was correct, but that the message is too old + to be checked for duplication. + + When sequence_state is TRUE, the possible major_status returns for + well-formed and correctly signed messages are as follows: + + 1. GSS_S_COMPLETE, without concurrent indication of + GSS_S_DUPLICATE_TOKEN, GSS_S_OLD_TOKEN, GSS_S_UNSEQ_TOKEN, or + GSS_S_GAP_TOKEN, indicates that the message was within the window + (of time or sequence space) allowing replay events to be detected, + that the message was not a replay of a previously-processed + message within that window, and that no predecessor sequenced + messages are missing relative to the last received message (if + any) processed on the context with a correct cryptographic + checkvalue. + + 2. GSS_S_DUPLICATE_TOKEN indicates that the integrity check value + on the received message was correct, but that the message was + recognized as a duplicate of a previously-processed message. In + addition to identifying duplicated tokens originated by a + context's peer, this status may also be used to identify reflected + + + +Linn Standards Track [Page 22] + +RFC 2743 GSS-API January 2000 + + + copies of locally-generated tokens; it is recommended that + mechanism designers include within their protocols facilities to + detect and report such tokens. + + 3. GSS_S_OLD_TOKEN indicates that the integrity check value on the + received message was correct, but that the token is too old to be + checked for duplication. + + 4. GSS_S_UNSEQ_TOKEN indicates that the cryptographic checkvalue + on the received message was correct, but that it is earlier in a + sequenced stream than a message already processed on the context. + [Note: Mechanisms can be architected to provide a stricter form of + sequencing service, delivering particular messages to recipients + only after all predecessor messages in an ordered stream have been + delivered. This type of support is incompatible with the GSS-API + paradigm in which recipients receive all messages, whether in + order or not, and provide them (one at a time, without intra-GSS- + API message buffering) to GSS-API routines for validation. GSS- + API facilities provide supportive functions, aiding clients to + achieve strict message stream integrity in an efficient manner in + conjunction with sequencing provisions in communications + protocols, but the GSS-API does not offer this level of message + stream integrity service by itself.] + + 5. GSS_S_GAP_TOKEN indicates that the cryptographic checkvalue on + the received message was correct, but that one or more predecessor + sequenced messages have not been successfully processed relative + to the last received message (if any) processed on the context + with a correct cryptographic checkvalue. + + As the message stream integrity features (especially sequencing) may + interfere with certain applications' intended communications + paradigms, and since support for such features is likely to be + resource intensive, it is highly recommended that mech_types + supporting these features allow them to be activated selectively on + initiator request when a context is established. A context initiator + and target are provided with corresponding indicators + (replay_det_state and sequence_state), signifying whether these + features are active on a given context. + + An example mech_type supporting per-message replay detection could + (when replay_det_state is TRUE) implement the feature as follows: The + underlying mechanism would insert timestamps in data elements output + by GSS_GetMIC() and GSS_Wrap(), and would maintain (within a time- + limited window) a cache (qualified by originator-recipient pair) + identifying received data elements processed by GSS_VerifyMIC() and + GSS_Unwrap(). When this feature is active, exception status returns + (GSS_S_DUPLICATE_TOKEN, GSS_S_OLD_TOKEN) will be provided when + + + +Linn Standards Track [Page 23] + +RFC 2743 GSS-API January 2000 + + + GSS_VerifyMIC() or GSS_Unwrap() is presented with a message which is + either a detected duplicate of a prior message or which is too old to + validate against a cache of recently received messages. + +1.2.4: Quality of Protection + + Some mech_types provide their users with fine granularity control + over the means used to provide per-message protection, allowing + callers to trade off security processing overhead dynamically against + the protection requirements of particular messages. A per-message + quality-of-protection parameter (analogous to quality-of-service, or + QOS) selects among different QOP options supported by that mechanism. + On context establishment for a multi-QOP mech_type, context-level + data provides the prerequisite data for a range of protection + qualities. + + It is expected that the majority of callers will not wish to exert + explicit mechanism-specific QOP control and will therefore request + selection of a default QOP. Definitions of, and choices among, non- + default QOP values are mechanism-specific, and no ordered sequences + of QOP values can be assumed equivalent across different mechanisms. + Meaningful use of non-default QOP values demands that callers be + familiar with the QOP definitions of an underlying mechanism or + mechanisms, and is therefore a non-portable construct. The + GSS_S_BAD_QOP major_status value is defined in order to indicate that + a provided QOP value is unsupported for a security context, most + likely because that value is unrecognized by the underlying + mechanism. + + In the interests of interoperability, mechanisms which allow optional + support of particular QOP values shall satisfy one of the following + conditions. Either: + + (i) All implementations of the mechanism are required to be + capable of processing messages protected using any QOP value, + regardless of whether they can apply protection corresponding to + that QOP, or + + (ii) The set of mutually-supported receiver QOP values must be + determined during context establishment, and messages may be + protected by either peer using only QOP values from this + mutually-supported set. + + NOTE: (i) is just a special-case of (ii), where implementations are + required to support all QOP values on receipt. + + + + + + +Linn Standards Track [Page 24] + +RFC 2743 GSS-API January 2000 + + +1.2.5: Anonymity Support + + In certain situations or environments, an application may wish to + authenticate a peer and/or protect communications using GSS-API per- + message services without revealing its own identity. For example, + consider an application which provides read access to a research + database, and which permits queries by arbitrary requestors. A + client of such a service might wish to authenticate the service, to + establish trust in the information received from it, but might not + wish to disclose its identity to the service for privacy reasons. + + In ordinary GSS-API usage, a context initiator's identity is made + available to the context acceptor as part of the context + establishment process. To provide for anonymity support, a facility + (input anon_req_flag to GSS_Init_sec_context()) is provided through + which context initiators may request that their identity not be + provided to the context acceptor. Mechanisms are not required to + honor this request, but a caller will be informed (via returned + anon_state indicator from GSS_Init_sec_context()) whether or not the + request is honored. Note that authentication as the anonymous + principal does not necessarily imply that credentials are not + required in order to establish a context. + + Section 4.5 of this document defines the Object Identifier value used + to identify an anonymous principal. + + Four possible combinations of anon_state and mutual_state are + possible, with the following results: + + anon_state == FALSE, mutual_state == FALSE: initiator + authenticated to target. + + anon_state == FALSE, mutual_state == TRUE: initiator authenticated + to target, target authenticated to initiator. + + anon_state == TRUE, mutual_state == FALSE: initiator authenticated + as anonymous principal to target. + + anon_state == TRUE, mutual_state == TRUE: initiator authenticated + as anonymous principal to target, target authenticated to + initiator. + +1.2.6: Initialization + + No initialization calls (i.e., calls which must be invoked prior to + invocation of other facilities in the interface) are defined in GSS- + API. As an implication of this fact, GSS-API implementations must + themselves be self-initializing. + + + +Linn Standards Track [Page 25] + +RFC 2743 GSS-API January 2000 + + +1.2.7: Per-Message Protection During Context Establishment + + A facility is defined in GSS-V2 to enable protection and buffering of + data messages for later transfer while a security context's + establishment is in GSS_S_CONTINUE_NEEDED status, to be used in cases + where the caller side already possesses the necessary session key to + enable this processing. Specifically, a new state Boolean, called + prot_ready_state, is added to the set of information returned by + GSS_Init_sec_context(), GSS_Accept_sec_context(), and + GSS_Inquire_context(). + + For context establishment calls, this state Boolean is valid and + interpretable when the associated major_status is either + GSS_S_CONTINUE_NEEDED, or GSS_S_COMPLETE. Callers of GSS-API (both + initiators and acceptors) can assume that per-message protection (via + GSS_Wrap(), GSS_Unwrap(), GSS_GetMIC() and GSS_VerifyMIC()) is + available and ready for use if either: prot_ready_state == TRUE, or + major_status == GSS_S_COMPLETE, though mutual authentication (if + requested) cannot be guaranteed until GSS_S_COMPLETE is returned. + Callers making use of per-message protection services in advance of + GSS_S_COMPLETE status should be aware of the possibility that a + subsequent context establishment step may fail, and that certain + context data (e.g., mech_type) as returned for subsequent calls may + change. + + This approach achieves full, transparent backward compatibility for + GSS-API V1 callers, who need not even know of the existence of + prot_ready_state, and who will get the expected behavior from + GSS_S_COMPLETE, but who will not be able to use per-message + protection before GSS_S_COMPLETE is returned. + + It is not a requirement that GSS-V2 mechanisms ever return TRUE + prot_ready_state before completion of context establishment (indeed, + some mechanisms will not evolve usable message protection keys, + especially at the context acceptor, before context establishment is + complete). It is expected but not required that GSS-V2 mechanisms + will return TRUE prot_ready_state upon completion of context + establishment if they support per-message protection at all (however + GSS-V2 applications should not assume that TRUE prot_ready_state will + always be returned together with the GSS_S_COMPLETE major_status, + since GSS-V2 implementations may continue to support GSS-V1 mechanism + code, which will never return TRUE prot_ready_state). + + When prot_ready_state is returned TRUE, mechanisms shall also set + those context service indicator flags (deleg_state, mutual_state, + replay_det_state, sequence_state, anon_state, trans_state, + conf_avail, integ_avail) which represent facilities confirmed, at + that time, to be available on the context being established. In + + + +Linn Standards Track [Page 26] + +RFC 2743 GSS-API January 2000 + + + situations where prot_ready_state is returned before GSS_S_COMPLETE, + it is possible that additional facilities may be confirmed and + subsequently indicated when GSS_S_COMPLETE is returned. + +1.2.8: Implementation Robustness + + This section recommends aspects of GSS-API implementation behavior in + the interests of overall robustness. + + Invocation of GSS-API calls is to incur no undocumented side effects + visible at the GSS-API level. + + If a token is presented for processing on a GSS-API security context + and that token generates a fatal error in processing or is otherwise + determined to be invalid for that context, the context's state should + not be disrupted for purposes of processing subsequent valid tokens. + + Certain local conditions at a GSS-API implementation (e.g., + unavailability of memory) may preclude, temporarily or permanently, + the successful processing of tokens on a GSS-API security context, + typically generating GSS_S_FAILURE major_status returns along with + locally-significant minor_status. For robust operation under such + conditions, the following recommendations are made: + + Failing calls should free any memory they allocate, so that + callers may retry without causing further loss of resources. + + Failure of an individual call on an established context should not + preclude subsequent calls from succeeding on the same context. + + Whenever possible, it should be possible for + GSS_Delete_sec_context() calls to be successfully processed even + if other calls cannot succeed, thereby enabling context-related + resources to be released. + + A failure of GSS_GetMIC() or GSS_Wrap() due to an attempt to use an + unsupported QOP will not interfere with context validity, nor shall + such a failure impact the ability of the application to subsequently + invoke GSS_GetMIC() or GSS_Wrap() using a supported QOP. Any state + information concerning sequencing of outgoing messages shall be + unchanged by an unsuccessful call of GSS_GetMIC() or GSS_Wrap(). + + + + + + + + + + +Linn Standards Track [Page 27] + +RFC 2743 GSS-API January 2000 + + +1.2.9: Delegation + + The GSS-API allows delegation to be controlled by the initiating + application via a Boolean parameter to GSS_Init_sec_context(), the + routine that establishes a security context. Some mechanisms do not + support delegation, and for such mechanisms attempts by an + application to enable delegation are ignored. + + The acceptor of a security context for which the initiator enabled + delegation will receive (via the delegated_cred_handle parameter of + GSS_Accept_sec_context()) a credential handle that contains the + delegated identity, and this credential handle may be used to + initiate subsequent GSS-API security contexts as an agent or delegate + of the initiator. If the original initiator's identity is "A" and + the delegate's identity is "B", then, depending on the underlying + mechanism, the identity embodied by the delegated credential may be + either "A" or "B acting for A". + + For many mechanisms that support delegation, a simple Boolean does + not provide enough control. Examples of additional aspects of + delegation control that a mechanism might provide to an application + are duration of delegation, network addresses from which delegation + is valid, and constraints on the tasks that may be performed by a + delegate. Such controls are presently outside the scope of the GSS- + API. GSS-API implementations supporting mechanisms offering + additional controls should provide extension routines that allow + these controls to be exercised (perhaps by modifying the initiator's + GSS-API credential prior to its use in establishing a context). + However, the simple delegation control provided by GSS-API should + always be able to over-ride other mechanism-specific delegation + controls; if the application instructs GSS_Init_sec_context() that + delegation is not desired, then the implementation must not permit + delegation to occur. This is an exception to the general rule that a + mechanism may enable services even if they are not requested; + delegation may only be provided at the explicit request of the + application. + +1.2.10: Interprocess Context Transfer + + GSS-API V2 provides routines (GSS_Export_sec_context() and + GSS_Import_sec_context()) which allow a security context to be + transferred between processes on a single machine. The most common + use for such a feature is a client-server design where the server is + implemented as a single process that accepts incoming security + contexts, which then launches child processes to deal with the data + on these contexts. In such a design, the child processes must have + access to the security context data structure created within the + + + + +Linn Standards Track [Page 28] + +RFC 2743 GSS-API January 2000 + + + parent by its call to GSS_Accept_sec_context() so that they can use + per-message protection services and delete the security context when + the communication session ends. + + Since the security context data structure is expected to contain + sequencing information, it is impractical in general to share a + context between processes. Thus GSS-API provides a call + (GSS_Export_sec_context()) that the process which currently owns the + context can call to declare that it has no intention to use the + context subsequently, and to create an inter-process token containing + information needed by the adopting process to successfully import the + context. After successful completion of this call, the original + security context is made inaccessible to the calling process by GSS- + API, and any context handles referring to this context are no longer + valid. The originating process transfers the inter-process token to + the adopting process, which passes it to GSS_Import_sec_context(), + and a fresh context handle is created such that it is functionally + identical to the original context. + + The inter-process token may contain sensitive data from the original + security context (including cryptographic keys). Applications using + inter-process tokens to transfer security contexts must take + appropriate steps to protect these tokens in transit. + Implementations are not required to support the inter-process + transfer of security contexts. The ability to transfer a security + context is indicated when the context is created, by + GSS_Init_sec_context() or GSS_Accept_sec_context() indicating a TRUE + trans_state return value. + +2: Interface Descriptions + + This section describes the GSS-API's service interface, dividing the + set of calls offered into four groups. Credential management calls + are related to the acquisition and release of credentials by + principals. Context-level calls are related to the management of + security contexts between principals. Per-message calls are related + to the protection of individual messages on established security + contexts. Support calls provide ancillary functions useful to GSS-API + callers. Table 2 groups and summarizes the calls in tabular fashion. + + Table 2: GSS-API Calls + + CREDENTIAL MANAGEMENT + + GSS_Acquire_cred acquire credentials for use + GSS_Release_cred release credentials after use + GSS_Inquire_cred display information about + credentials + + + +Linn Standards Track [Page 29] + +RFC 2743 GSS-API January 2000 + + + GSS_Add_cred construct credentials incrementally + GSS_Inquire_cred_by_mech display per-mechanism credential + information + + CONTEXT-LEVEL CALLS + + GSS_Init_sec_context initiate outbound security context + GSS_Accept_sec_context accept inbound security context + GSS_Delete_sec_context flush context when no longer needed + GSS_Process_context_token process received control token on + context + GSS_Context_time indicate validity time remaining on + context + GSS_Inquire_context display information about context + GSS_Wrap_size_limit determine GSS_Wrap token size limit + GSS_Export_sec_context transfer context to other process + GSS_Import_sec_context import transferred context + + PER-MESSAGE CALLS + + GSS_GetMIC apply integrity check, receive as + token separate from message + GSS_VerifyMIC validate integrity check token + along with message + GSS_Wrap sign, optionally encrypt, + encapsulate + GSS_Unwrap decapsulate, decrypt if needed, + validate integrity check + + SUPPORT CALLS + + GSS_Display_status translate status codes to printable + form + GSS_Indicate_mechs indicate mech_types supported on + local system + GSS_Compare_name compare two names for equality + GSS_Display_name translate name to printable form + GSS_Import_name convert printable name to + normalized form + GSS_Release_name free storage of normalized-form + name + GSS_Release_buffer free storage of general GSS-allocated + object + GSS_Release_OID_set free storage of OID set object + GSS_Create_empty_OID_set create empty OID set + GSS_Add_OID_set_member add member to OID set + GSS_Test_OID_set_member test if OID is member of OID set + GSS_Inquire_names_for_mech indicate name types supported by + + + +Linn Standards Track [Page 30] + +RFC 2743 GSS-API January 2000 + + + mechanism + GSS_Inquire_mechs_for_name indicates mechanisms supporting name + type + GSS_Canonicalize_name translate name to per-mechanism form + GSS_Export_name externalize per-mechanism name + GSS_Duplicate_name duplicate name object + +2.1: Credential management calls + + These GSS-API calls provide functions related to the management of + credentials. Their characterization with regard to whether or not + they may block pending exchanges with other network entities (e.g., + directories or authentication servers) depends in part on OS-specific + (extra-GSS-API) issues, so is not specified in this document. + + The GSS_Acquire_cred() call is defined within the GSS-API in support + of application portability, with a particular orientation towards + support of portable server applications. It is recognized that (for + certain systems and mechanisms) credentials for interactive users may + be managed differently from credentials for server processes; in such + environments, it is the GSS-API implementation's responsibility to + distinguish these cases and the procedures for making this + distinction are a local matter. The GSS_Release_cred() call provides + a means for callers to indicate to the GSS-API that use of a + credentials structure is no longer required. The GSS_Inquire_cred() + call allows callers to determine information about a credentials + structure. The GSS_Add_cred() call enables callers to append + elements to an existing credential structure, allowing iterative + construction of a multi-mechanism credential. The + GSS_Inquire_cred_by_mech() call enables callers to extract per- + mechanism information describing a credentials structure. + +2.1.1: GSS_Acquire_cred call + + Inputs: + + o desired_name INTERNAL NAME, -- NULL requests locally-determined + -- default + + o lifetime_req INTEGER, -- in seconds; 0 requests default + + o desired_mechs SET OF OBJECT IDENTIFIER, -- NULL requests + -- system-selected default + + o cred_usage INTEGER -- 0=INITIATE-AND-ACCEPT, 1=INITIATE-ONLY, + -- 2=ACCEPT-ONLY + + + + + +Linn Standards Track [Page 31] + +RFC 2743 GSS-API January 2000 + + + Outputs: + + o major_status INTEGER, + + o minor_status INTEGER, + + o output_cred_handle CREDENTIAL HANDLE, -- if returned non-NULL, + -- caller must release with GSS_Release_cred() + + o actual_mechs SET OF OBJECT IDENTIFIER, -- if returned non-NULL, + -- caller must release with GSS_Release_oid_set() + + o lifetime_rec INTEGER -- in seconds, or reserved value for + -- INDEFINITE + + Return major_status codes: + + o GSS_S_COMPLETE indicates that requested credentials were + successfully established, for the duration indicated in lifetime_rec, + suitable for the usage requested in cred_usage, for the set of + mech_types indicated in actual_mechs, and that those credentials can + be referenced for subsequent use with the handle returned in + output_cred_handle. + + o GSS_S_BAD_MECH indicates that a mech_type unsupported by the GSS- + API implementation type was requested, causing the credential + establishment operation to fail. + + o GSS_S_BAD_NAMETYPE indicates that the provided desired_name is + uninterpretable or of a type unsupported by the applicable underlying + GSS-API mechanism(s), so no credentials could be established for the + accompanying desired_name. + + o GSS_S_BAD_NAME indicates that the provided desired_name is + inconsistent in terms of internally-incorporated type specifier + information, so no credentials could be established for the + accompanying desired_name. + + o GSS_S_CREDENTIALS_EXPIRED indicates that underlying credential + elements corresponding to the requested desired_name have expired, so + requested credentials could not be established. + + o GSS_S_NO_CRED indicates that no credential elements corresponding + to the requested desired_name and usage could be accessed, so + requested credentials could not be established. In particular, this + status should be returned upon temporary user-fixable conditions + + + + + +Linn Standards Track [Page 32] + +RFC 2743 GSS-API January 2000 + + + preventing successful credential establishment and upon lack of + authorization to establish and use credentials associated with the + identity named in the input desired_name argument. + + o GSS_S_FAILURE indicates that credential establishment failed for + reasons unspecified at the GSS-API level. + + GSS_Acquire_cred() is used to acquire credentials so that a principal + can (as a function of the input cred_usage parameter) initiate and/or + accept security contexts under the identity represented by the + desired_name input argument. On successful completion, the returned + output_cred_handle result provides a handle for subsequent references + to the acquired credentials. Typically, single-user client processes + requesting that default credential behavior be applied for context + establishment purposes will have no need to invoke this call. + + A caller may provide the value NULL (GSS_C_NO_NAME) for desired_name, + which will be interpreted as a request for a credential handle that + will invoke default behavior when passed to GSS_Init_sec_context(), + if cred_usage is GSS_C_INITIATE or GSS_C_BOTH, or + GSS_Accept_sec_context(), if cred_usage is GSS_C_ACCEPT or + GSS_C_BOTH. It is possible that multiple pre-established credentials + may exist for the same principal identity (for example, as a result + of multiple user login sessions) when GSS_Acquire_cred() is called; + the means used in such cases to select a specific credential are + local matters. The input lifetime_req argument to GSS_Acquire_cred() + may provide useful information for local GSS-API implementations to + employ in making this disambiguation in a manner which will best + satisfy a caller's intent. + + This routine is expected to be used primarily by context acceptors, + since implementations are likely to provide mechanism-specific ways + of obtaining GSS-API initiator credentials from the system login + process. Some implementations may therefore not support the + acquisition of GSS_C_INITIATE or GSS_C_BOTH credentials via + GSS_Acquire_cred() for any name other than GSS_C_NO_NAME, or a name + resulting from applying GSS_Inquire_context() to an active context, + or a name resulting from applying GSS_Inquire_cred() against a + credential handle corresponding to default behavior. It is important + to recognize that the explicit name which is yielded by resolving a + default reference may change over time, e.g., as a result of local + credential element management operations outside GSS-API; once + resolved, however, the value of such an explicit name will remain + constant. + + The lifetime_rec result indicates the length of time for which the + acquired credentials will be valid, as an offset from the present. A + mechanism may return a reserved value indicating INDEFINITE if no + + + +Linn Standards Track [Page 33] + +RFC 2743 GSS-API January 2000 + + + constraints on credential lifetime are imposed. A caller of + GSS_Acquire_cred() can request a length of time for which acquired + credentials are to be valid (lifetime_req argument), beginning at the + present, or can request credentials with a default validity interval. + (Requests for postdated credentials are not supported within the + GSS-API.) Certain mechanisms and implementations may bind in + credential validity period specifiers at a point preliminary to + invocation of the GSS_Acquire_cred() call (e.g., in conjunction with + user login procedures). As a result, callers requesting non-default + values for lifetime_req must recognize that such requests cannot + always be honored and must be prepared to accommodate the use of + returned credentials with different lifetimes as indicated in + lifetime_rec. + + The caller of GSS_Acquire_cred() can explicitly specify a set of + mech_types which are to be accommodated in the returned credentials + (desired_mechs argument), or can request credentials for a system- + defined default set of mech_types. Selection of the system-specified + default set is recommended in the interests of application + portability. The actual_mechs return value may be interrogated by the + caller to determine the set of mechanisms with which the returned + credentials may be used. + +2.1.2: GSS_Release_cred call + + Input: + + o cred_handle CREDENTIAL HANDLE -- if GSS_C_NO_CREDENTIAL + -- is specified, the call will complete successfully, but + -- will have no effect; no credential elements will be + -- released. + + Outputs: + + o major_status INTEGER, + + o minor_status INTEGER + + Return major_status codes: + + o GSS_S_COMPLETE indicates that the credentials referenced by the + input cred_handle were released for purposes of subsequent access by + the caller. The effect on other processes which may be authorized + shared access to such credentials is a local matter. + + + + + + + +Linn Standards Track [Page 34] + +RFC 2743 GSS-API January 2000 + + + o GSS_S_NO_CRED indicates that no release operation was performed, + either because the input cred_handle was invalid or because the + caller lacks authorization to access the referenced credentials. + + o GSS_S_FAILURE indicates that the release operation failed for + reasons unspecified at the GSS-API level. + + Provides a means for a caller to explicitly request that credentials + be released when their use is no longer required. Note that system- + specific credential management functions are also likely to exist, + for example to assure that credentials shared among processes are + properly deleted when all affected processes terminate, even if no + explicit release requests are issued by those processes. Given the + fact that multiple callers are not precluded from gaining authorized + access to the same credentials, invocation of GSS_Release_cred() + cannot be assumed to delete a particular set of credentials on a + system-wide basis. + +2.1.3: GSS_Inquire_cred call + + Input: + + o cred_handle CREDENTIAL HANDLE -- if GSS_C_NO_CREDENTIAL + -- is specified, default initiator credentials are queried + + Outputs: + + o major_status INTEGER, + + o minor_status INTEGER, + + o cred_name INTERNAL NAME, -- caller must release with + -- GSS_Release_name() + + o lifetime_rec INTEGER -- in seconds, or reserved value for + -- INDEFINITE + + o cred_usage INTEGER, -- 0=INITIATE-AND-ACCEPT, 1=INITIATE-ONLY, + -- 2=ACCEPT-ONLY + + o mech_set SET OF OBJECT IDENTIFIER -- caller must release + -- with GSS_Release_oid_set() + + + + + + + + + +Linn Standards Track [Page 35] + +RFC 2743 GSS-API January 2000 + + + Return major_status codes: + + o GSS_S_COMPLETE indicates that the credentials referenced by the + input cred_handle argument were valid, and that the output cred_name, + lifetime_rec, and cred_usage values represent, respectively, the + credentials' associated principal name, remaining lifetime, suitable + usage modes, and supported mechanism types. + + o GSS_S_NO_CRED indicates that no information could be returned + about the referenced credentials, either because the input + cred_handle was invalid or because the caller lacks authorization to + access the referenced credentials. + + o GSS_S_DEFECTIVE_CREDENTIAL indicates that the referenced + credentials are invalid. + + o GSS_S_CREDENTIALS_EXPIRED indicates that the referenced + credentials have expired. + + o GSS_S_FAILURE indicates that the operation failed for reasons + unspecified at the GSS-API level. + + The GSS_Inquire_cred() call is defined primarily for the use of those + callers which request use of default credential behavior rather than + acquiring credentials explicitly with GSS_Acquire_cred(). It enables + callers to determine a credential structure's associated principal + name, remaining validity period, usability for security context + initiation and/or acceptance, and supported mechanisms. + + For a multi-mechanism credential, the returned "lifetime" specifier + indicates the shortest lifetime of any of the mechanisms' elements in + the credential (for either context initiation or acceptance + purposes). + + GSS_Inquire_cred() should indicate INITIATE-AND-ACCEPT for + "cred_usage" if both of the following conditions hold: + + (1) there exists in the credential an element which allows context + initiation using some mechanism + + (2) there exists in the credential an element which allows context + acceptance using some mechanism (allowably, but not necessarily, + one of the same mechanism(s) qualifying for (1)). + + If condition (1) holds but not condition (2), GSS_Inquire_cred() + should indicate INITIATE-ONLY for "cred_usage". If condition (2) + holds but not condition (1), GSS_Inquire_cred() should indicate + ACCEPT-ONLY for "cred_usage". + + + +Linn Standards Track [Page 36] + +RFC 2743 GSS-API January 2000 + + + Callers requiring finer disambiguation among available combinations + of lifetimes, usage modes, and mechanisms should call the + GSS_Inquire_cred_by_mech() routine, passing that routine one of the + mech OIDs returned by GSS_Inquire_cred(). + +2.1.4: GSS_Add_cred call + + Inputs: + + o input_cred_handle CREDENTIAL HANDLE -- handle to credential + -- structure created with prior GSS_Acquire_cred() or + -- GSS_Add_cred() call; see text for definition of behavior + -- when GSS_C_NO_CREDENTIAL provided. + + o desired_name INTERNAL NAME + + o initiator_time_req INTEGER -- in seconds; 0 requests default + + o acceptor_time_req INTEGER -- in seconds; 0 requests default + + o desired_mech OBJECT IDENTIFIER + + o cred_usage INTEGER -- 0=INITIATE-AND-ACCEPT, 1=INITIATE-ONLY, + -- 2=ACCEPT-ONLY + + Outputs: + + o major_status INTEGER, + + o minor_status INTEGER, + + o output_cred_handle CREDENTIAL HANDLE, -- NULL to request that + -- credential elements be added "in place" to the credential + -- structure identified by input_cred_handle, + -- non-NULL pointer to request that + -- a new credential structure and handle be created. + -- if credential handle returned, caller must release with + -- GSS_Release_cred() + + o actual_mechs SET OF OBJECT IDENTIFIER, -- if returned, caller must + -- release with GSS_Release_oid_set() + + o initiator_time_rec INTEGER -- in seconds, or reserved value for + -- INDEFINITE + + o acceptor_time_rec INTEGER -- in seconds, or reserved value for + -- INDEFINITE + + + + +Linn Standards Track [Page 37] + +RFC 2743 GSS-API January 2000 + + + o cred_usage INTEGER, -- 0=INITIATE-AND-ACCEPT, 1=INITIATE-ONLY, + -- 2=ACCEPT-ONLY + + o mech_set SET OF OBJECT IDENTIFIER -- full set of mechanisms + -- supported by resulting credential. + + Return major_status codes: + + o GSS_S_COMPLETE indicates that the credentials referenced by the + input_cred_handle argument were valid, and that the resulting + credential from GSS_Add_cred() is valid for the durations indicated + in initiator_time_rec and acceptor_time_rec, suitable for the usage + requested in cred_usage, and for the mechanisms indicated in + actual_mechs. + + o GSS_S_DUPLICATE_ELEMENT indicates that the input desired_mech + specified a mechanism for which the referenced credential already + contained a credential element with overlapping cred_usage and + validity time specifiers. + + o GSS_S_BAD_MECH indicates that the input desired_mech specified a + mechanism unsupported by the GSS-API implementation, causing the + GSS_Add_cred() operation to fail. + + o GSS_S_BAD_NAMETYPE indicates that the provided desired_name is + uninterpretable or of a type unsupported by the applicable underlying + GSS-API mechanism(s), so the GSS_Add_cred() operation could not be + performed for that name. + + o GSS_S_BAD_NAME indicates that the provided desired_name is + inconsistent in terms of internally-incorporated type specifier + information, so the GSS_Add_cred() operation could not be performed + for that name. + + o GSS_S_NO_CRED indicates that the input_cred_handle referenced + invalid or inaccessible credentials. In particular, this status + should be returned upon temporary user-fixable conditions preventing + successful credential establishment or upon lack of authorization to + establish or use credentials representing the requested identity. + + o GSS_S_CREDENTIALS_EXPIRED indicates that referenced credential + elements have expired, so the GSS_Add_cred() operation could not be + performed. + + o GSS_S_FAILURE indicates that the operation failed for reasons + unspecified at the GSS-API level. + + + + + +Linn Standards Track [Page 38] + +RFC 2743 GSS-API January 2000 + + + GSS_Add_cred() enables callers to construct credentials iteratively + by adding credential elements in successive operations, corresponding + to different mechanisms. This offers particular value in multi- + mechanism environments, as the major_status and minor_status values + returned on each iteration are individually visible and can therefore + be interpreted unambiguously on a per-mechanism basis. A credential + element is identified by the name of the principal to which it + refers. GSS-API implementations must impose a local access control + policy on callers of this routine to prevent unauthorized callers + from acquiring credential elements to which they are not entitled. + This routine is not intended to provide a "login to the network" + function, as such a function would involve the creation of new + mechanism-specific authentication data, rather than merely acquiring + a GSS-API handle to existing data. Such functions, if required, + should be defined in implementation-specific extension routines. + + If credential acquisition is time-consuming for a mechanism, the + mechanism may choose to delay the actual acquisition until the + credential is required (e.g. by GSS_Init_sec_context() or + GSS_Accept_sec_context()). Such mechanism-specific implementation + decisions should be invisible to the calling application; thus a call + of GSS_Inquire_cred() immediately following the call of + GSS_Acquire_cred() must return valid credential data, and may + therefore incur the overhead of a deferred credential acquisition. + + If GSS_C_NO_CREDENTIAL is specified as input_cred_handle, a non-NULL + output_cred_handle must be supplied. For the case of + GSS_C_NO_CREDENTIAL as input_cred_handle, GSS_Add_cred() will create + the credential referenced by its output_cred_handle based on default + behavior. That is, the call will have the same effect as if the + caller had previously called GSS_Acquire_cred(), specifying the same + usage and passing GSS_C_NO_NAME as the desired_name parameter + (thereby obtaining an explicit credential handle corresponding to + default behavior), had passed that credential handle to + GSS_Add_cred(), and had finally called GSS_Release_cred() on the + credential handle received from GSS_Acquire_cred(). + + This routine is expected to be used primarily by context acceptors, + since implementations are likely to provide mechanism-specific ways + of obtaining GSS-API initiator credentials from the system login + process. Some implementations may therefore not support the + acquisition of GSS_C_INITIATE or GSS_C_BOTH credentials via + GSS_Acquire_cred() for any name other than GSS_C_NO_NAME, or a name + resulting from applying GSS_Inquire_context() to an active context, + or a name resulting from applying GSS_Inquire_cred() against a + credential handle corresponding to default behavior. It is important + to recognize that the explicit name which is yielded by resolving a + default reference may change over time, e.g., as a result of local + + + +Linn Standards Track [Page 39] + +RFC 2743 GSS-API January 2000 + + + credential element management operations outside GSS-API; once + resolved, however, the value of such an explicit name will remain + constant. + + A caller may provide the value NULL (GSS_C_NO_NAME) for desired_name, + which will be interpreted as a request for a credential handle that + will invoke default behavior when passed to GSS_Init_sec_context(), + if cred_usage is GSS_C_INITIATE or GSS_C_BOTH, or + GSS_Accept_sec_context(), if cred_usage is GSS_C_ACCEPT or + GSS_C_BOTH. + + The same input desired_name, or default reference, should be used on + all GSS_Acquire_cred() and GSS_Add_cred() calls corresponding to a + particular credential. + +2.1.5: GSS_Inquire_cred_by_mech call + + Inputs: + + o cred_handle CREDENTIAL HANDLE -- if GSS_C_NO_CREDENTIAL + -- specified, default initiator credentials are queried + + o mech_type OBJECT IDENTIFIER -- specific mechanism for + -- which credentials are being queried + + Outputs: + + o major_status INTEGER, + + o minor_status INTEGER, + + o cred_name INTERNAL NAME, -- guaranteed to be MN; caller must + -- release with GSS_Release_name() + + o lifetime_rec_initiate INTEGER -- in seconds, or reserved value for + -- INDEFINITE + + o lifetime_rec_accept INTEGER -- in seconds, or reserved value for + -- INDEFINITE + + o cred_usage INTEGER, -- 0=INITIATE-AND-ACCEPT, 1=INITIATE-ONLY, + -- 2=ACCEPT-ONLY + + Return major_status codes: + + o GSS_S_COMPLETE indicates that the credentials referenced by the + input cred_handle argument were valid, that the mechanism indicated + by the input mech_type was represented with elements within those + + + +Linn Standards Track [Page 40] + +RFC 2743 GSS-API January 2000 + + + credentials, and that the output cred_name, lifetime_rec_initiate, + lifetime_rec_accept, and cred_usage values represent, respectively, + the credentials' associated principal name, remaining lifetimes, and + suitable usage modes. + + o GSS_S_NO_CRED indicates that no information could be returned + about the referenced credentials, either because the input + cred_handle was invalid or because the caller lacks authorization to + access the referenced credentials. + + o GSS_S_DEFECTIVE_CREDENTIAL indicates that the referenced + credentials are invalid. + + o GSS_S_CREDENTIALS_EXPIRED indicates that the referenced + credentials have expired. + + o GSS_S_BAD_MECH indicates that the referenced credentials do not + contain elements for the requested mechanism. + + o GSS_S_FAILURE indicates that the operation failed for reasons + unspecified at the GSS-API level. + + The GSS_Inquire_cred_by_mech() call enables callers in multi- + mechanism environments to acquire specific data about available + combinations of lifetimes, usage modes, and mechanisms within a + credential structure. The lifetime_rec_initiate result indicates the + available lifetime for context initiation purposes; the + lifetime_rec_accept result indicates the available lifetime for + context acceptance purposes. + +2.2: Context-level calls + + This group of calls is devoted to the establishment and management of + security contexts between peers. A context's initiator calls + GSS_Init_sec_context(), resulting in generation of a token which the + caller passes to the target. At the target, that token is passed to + GSS_Accept_sec_context(). Depending on the underlying mech_type and + specified options, additional token exchanges may be performed in the + course of context establishment; such exchanges are accommodated by + GSS_S_CONTINUE_NEEDED status returns from GSS_Init_sec_context() and + GSS_Accept_sec_context(). + + Either party to an established context may invoke + GSS_Delete_sec_context() to flush context information when a context + is no longer required. GSS_Process_context_token() is used to process + received tokens carrying context-level control information. + GSS_Context_time() allows a caller to determine the length of time + for which an established context will remain valid. + + + +Linn Standards Track [Page 41] + +RFC 2743 GSS-API January 2000 + + + GSS_Inquire_context() returns status information describing context + characteristics. GSS_Wrap_size_limit() allows a caller to determine + the size of a token which will be generated by a GSS_Wrap() + operation. GSS_Export_sec_context() and GSS_Import_sec_context() + enable transfer of active contexts between processes on an end + system. + +2.2.1: GSS_Init_sec_context call + + Inputs: + + o claimant_cred_handle CREDENTIAL HANDLE, -- NULL specifies "use + -- default" + + o input_context_handle CONTEXT HANDLE, -- 0 + -- (GSS_C_NO_CONTEXT) specifies "none assigned yet" + + o targ_name INTERNAL NAME, + + o mech_type OBJECT IDENTIFIER, -- NULL parameter specifies "use + -- default" + + o deleg_req_flag BOOLEAN, + + o mutual_req_flag BOOLEAN, + + o replay_det_req_flag BOOLEAN, + + o sequence_req_flag BOOLEAN, + + o anon_req_flag BOOLEAN, + + o conf_req_flag BOOLEAN, + + o integ_req_flag BOOLEAN, + + o lifetime_req INTEGER, -- 0 specifies default lifetime + + o chan_bindings OCTET STRING, + + o input_token OCTET STRING -- NULL or token received from target + + Outputs: + + o major_status INTEGER, + + o minor_status INTEGER, + + + + +Linn Standards Track [Page 42] + +RFC 2743 GSS-API January 2000 + + + o output_context_handle CONTEXT HANDLE, -- once returned non-NULL, + -- caller must release with GSS_Delete_sec_context() + + o mech_type OBJECT IDENTIFIER, -- actual mechanism always + -- indicated, never NULL; caller should treat as read-only + -- and should not attempt to release + + o output_token OCTET STRING, -- NULL or token to pass to context + -- target; caller must release with GSS_Release_buffer() + + o deleg_state BOOLEAN, + + o mutual_state BOOLEAN, + + o replay_det_state BOOLEAN, + + o sequence_state BOOLEAN, + + o anon_state BOOLEAN, + + o trans_state BOOLEAN, + + o prot_ready_state BOOLEAN, -- see Section 1.2.7 + + o conf_avail BOOLEAN, + + o integ_avail BOOLEAN, + + o lifetime_rec INTEGER -- in seconds, or reserved value for + -- INDEFINITE + + This call may block pending network interactions for those mech_types + in which an authentication server or other network entity must be + consulted on behalf of a context initiator in order to generate an + output_token suitable for presentation to a specified target. + + Return major_status codes: + + o GSS_S_COMPLETE indicates that context-level information was + successfully initialized, and that the returned output_token will + provide sufficient information for the target to perform per-message + processing on the newly-established context. + + o GSS_S_CONTINUE_NEEDED indicates that control information in the + returned output_token must be sent to the target, and that a reply + must be received and passed as the input_token argument + + + + + +Linn Standards Track [Page 43] + +RFC 2743 GSS-API January 2000 + + + to a continuation call to GSS_Init_sec_context(), before per-message + processing can be performed in conjunction with this context (unless + the prot_ready_state value is concurrently returned TRUE). + + o GSS_S_DEFECTIVE_TOKEN indicates that consistency checks performed + on the input_token failed, preventing further processing from being + performed based on that token. + + o GSS_S_DEFECTIVE_CREDENTIAL indicates that consistency checks + performed on the credential structure referenced by + claimant_cred_handle failed, preventing further processing from being + performed using that credential structure. + + o GSS_S_BAD_SIG (GSS_S_BAD_MIC) indicates that the received + input_token contains an incorrect integrity check, so context setup + cannot be accomplished. + + o GSS_S_NO_CRED indicates that no context was established, either + because the input cred_handle was invalid, because the referenced + credentials are valid for context acceptor use only, because the + caller lacks authorization to access the referenced credentials, or + because the resolution of default credentials failed. + + o GSS_S_CREDENTIALS_EXPIRED indicates that the credentials provided + through the input claimant_cred_handle argument are no longer valid, + so context establishment cannot be completed. + + o GSS_S_BAD_BINDINGS indicates that a mismatch between the caller- + provided chan_bindings and those extracted from the input_token was + detected, signifying a security-relevant event and preventing context + establishment. (This result will be returned by + GSS_Init_sec_context() only for contexts where mutual_state is TRUE.) + + o GSS_S_OLD_TOKEN indicates that the input_token is too old to be + checked for integrity. This is a fatal error during context + establishment. + + o GSS_S_DUPLICATE_TOKEN indicates that the input token has a correct + integrity check, but is a duplicate of a token already processed. + This is a fatal error during context establishment. + + o GSS_S_NO_CONTEXT indicates that no valid context was recognized + for the input context_handle provided; this major status will be + returned only for successor calls following GSS_S_CONTINUE_ NEEDED + status returns. + + + + + + +Linn Standards Track [Page 44] + +RFC 2743 GSS-API January 2000 + + + o GSS_S_BAD_NAMETYPE indicates that the provided targ_name is of a + type uninterpretable or unsupported by the applicable underlying + GSS-API mechanism(s), so context establishment cannot be completed. + + o GSS_S_BAD_NAME indicates that the provided targ_name is + inconsistent in terms of internally-incorporated type specifier + information, so context establishment cannot be accomplished. + + o GSS_S_BAD_MECH indicates receipt of a context establishment token + or of a caller request specifying a mechanism unsupported by the + local system or with the caller's active credentials + + o GSS_S_FAILURE indicates that context setup could not be + accomplished for reasons unspecified at the GSS-API level, and that + no interface-defined recovery action is available. + + This routine is used by a context initiator, and ordinarily emits an + output_token suitable for use by the target within the selected + mech_type's protocol. For the case of a multi-step exchange, this + output_token will be one in a series, each generated by a successive + call. Using information in the credentials structure referenced by + claimant_cred_handle, GSS_Init_sec_context() initializes the data + structures required to establish a security context with target + targ_name. + + The targ_name may be any valid INTERNAL NAME; it need not be an MN. + In addition to support for other name types, it is recommended (newly + as of GSS-V2, Update 1) that mechanisms be able to accept + GSS_C_NO_NAME as an input type for targ_name. While recommended, + such support is not required, and it is recognized that not all + mechanisms can construct tokens without explicitly naming the context + target, even when mutual authentication of the target is not + obtained. Callers wishing to make use of this facility and concerned + with portability should be aware that support for GSS_C_NO_NAME as + input targ_name type is unlikely to be provided within mechanism + definitions specified prior to GSS-V2, Update 1. + + The claimant_cred_handle must correspond to the same valid + credentials structure on the initial call to GSS_Init_sec_context() + and on any successor calls resulting from GSS_S_CONTINUE_NEEDED + status returns; different protocol sequences modeled by the + GSS_S_CONTINUE_NEEDED facility will require access to credentials at + different points in the context establishment sequence. + + The caller-provided input_context_handle argument is to be 0 + (GSS_C_NO_CONTEXT), specifying "not yet assigned", on the first + GSS_Init_sec_context() call relating to a given context. If + successful (i.e., if accompanied by major_status GSS_S_COMPLETE or + + + +Linn Standards Track [Page 45] + +RFC 2743 GSS-API January 2000 + + + GSS_S_CONTINUE_NEEDED), and only if successful, the initial + GSS_Init_sec_context() call returns a non-zero output_context_handle + for use in future references to this context. Once a non-zero + output_context_handle has been returned, GSS-API callers should call + GSS_Delete_sec_context() to release context-related resources if + errors occur in later phases of context establishment, or when an + established context is no longer required. If GSS_Init_sec_context() + is passed the handle of a context which is already fully established, + GSS_S_FAILURE status is returned. + + When continuation attempts to GSS_Init_sec_context() are needed to + perform context establishment, the previously-returned non-zero + handle value is entered into the input_context_handle argument and + will be echoed in the returned output_context_handle argument. On + such continuation attempts (and only on continuation attempts) the + input_token value is used, to provide the token returned from the + context's target. + + The chan_bindings argument is used by the caller to provide + information binding the security context to security-related + characteristics (e.g., addresses, cryptographic keys) of the + underlying communications channel. See Section 1.1.6 of this document + for more discussion of this argument's usage. + + The input_token argument contains a message received from the target, + and is significant only on a call to GSS_Init_sec_context() which + follows a previous return indicating GSS_S_CONTINUE_NEEDED + major_status. + + It is the caller's responsibility to establish a communications path + to the target, and to transmit any returned output_token (independent + of the accompanying returned major_status value) to the target over + that path. The output_token can, however, be transmitted along with + the first application-provided input message to be processed by + GSS_GetMIC() or GSS_Wrap() in conjunction with a successfully- + established context. (Note: when the GSS-V2 prot_ready_state + indicator is returned TRUE, it can be possible to transfer a + protected message before context establishment is complete: see also + Section 1.2.7) + + The initiator may request various context-level functions through + input flags: the deleg_req_flag requests delegation of access rights, + the mutual_req_flag requests mutual authentication, the + replay_det_req_flag requests that replay detection features be + applied to messages transferred on the established context, and the + sequence_req_flag requests that sequencing be enforced. (See Section + + + + + +Linn Standards Track [Page 46] + +RFC 2743 GSS-API January 2000 + + + 1.2.3 for more information on replay detection and sequencing + features.) The anon_req_flag requests that the initiator's identity + not be transferred within tokens to be sent to the acceptor. + + The conf_req_flag and integ_req_flag provide informatory inputs to + the GSS-API implementation as to whether, respectively, per-message + confidentiality and per-message integrity services will be required + on the context. This information is important as an input to + negotiating mechanisms. It is important to recognize, however, that + the inclusion of these flags (which are newly defined for GSS-V2) + introduces a backward incompatibility with callers implemented to + GSS-V1, where the flags were not defined. Since no GSS-V1 callers + would set these flags, even if per-message services are desired, + GSS-V2 mechanism implementations which enable such services + selectively based on the flags' values may fail to provide them to + contexts established for GSS-V1 callers. It may be appropriate under + certain circumstances, therefore, for such mechanism implementations + to infer these service request flags to be set if a caller is known + to be implemented to GSS-V1. + + Not all of the optionally-requestable features will be available in + all underlying mech_types. The corresponding return state values + deleg_state, mutual_state, replay_det_state, and sequence_state + indicate, as a function of mech_type processing capabilities and + initiator-provided input flags, the set of features which will be + active on the context. The returned trans_state value indicates + whether the context is transferable to other processes through use of + GSS_Export_sec_context(). These state indicators' values are + undefined unless either the routine's major_status indicates + GSS_S_COMPLETE, or TRUE prot_ready_state is returned along with + GSS_S_CONTINUE_NEEDED major_status; for the latter case, it is + possible that additional features, not confirmed or indicated along + with TRUE prot_ready_state, will be confirmed and indicated when + GSS_S_COMPLETE is subsequently returned. + + The returned anon_state and prot_ready_state values are significant + for both GSS_S_COMPLETE and GSS_S_CONTINUE_NEEDED major_status + returns from GSS_Init_sec_context(). When anon_state is returned + TRUE, this indicates that neither the current token nor its + predecessors delivers or has delivered the initiator's identity. + Callers wishing to perform context establishment only if anonymity + support is provided should transfer a returned token from + GSS_Init_sec_context() to the peer only if it is accompanied by a + TRUE anon_state indicator. When prot_ready_state is returned TRUE in + conjunction with GSS_S_CONTINUE_NEEDED major_status, this indicates + that per-message protection operations may be applied on the context: + see Section 1.2.7 for further discussion of this facility. + + + + +Linn Standards Track [Page 47] + +RFC 2743 GSS-API January 2000 + + + Failure to provide the precise set of features requested by the + caller does not cause context establishment to fail; it is the + caller's prerogative to delete the context if the feature set + provided is unsuitable for the caller's use. + + The returned mech_type value indicates the specific mechanism + employed on the context; it will never indicate the value for + "default". A valid mech_type result must be returned along with a + GSS_S_COMPLETE status return; GSS-API implementations may (but are + not required to) also return mech_type along with predecessor calls + indicating GSS_S_CONTINUE_NEEDED status or (if a mechanism is + determinable) in conjunction with fatal error cases. For the case of + mechanisms which themselves perform negotiation, the returned + mech_type result may indicate selection of a mechanism identified by + an OID different than that passed in the input mech_type argument, + and the returned value may change between successive calls returning + GSS_S_CONTINUE_NEEDED and the final call returning GSS_S_COMPLETE. + + The conf_avail return value indicates whether the context supports + per-message confidentiality services, and so informs the caller + whether or not a request for encryption through the conf_req_flag + input to GSS_Wrap() can be honored. In similar fashion, the + integ_avail return value indicates whether per-message integrity + services are available (through either GSS_GetMIC() or GSS_Wrap()) on + the established context. These state indicators' values are undefined + unless either the routine's major_status indicates GSS_S_COMPLETE, or + TRUE prot_ready_state is returned along with GSS_S_CONTINUE_NEEDED + major_status. + + The lifetime_req input specifies a desired upper bound for the + lifetime of the context to be established, with a value of 0 used to + request a default lifetime. The lifetime_rec return value indicates + the length of time for which the context will be valid, expressed as + an offset from the present; depending on mechanism capabilities, + credential lifetimes, and local policy, it may not correspond to the + value requested in lifetime_req. If no constraints on context + lifetime are imposed, this may be indicated by returning a reserved + value representing INDEFINITE lifetime_req. The value of lifetime_rec + is undefined unless the routine's major_status indicates + GSS_S_COMPLETE. + + If the mutual_state is TRUE, this fact will be reflected within the + output_token. A call to GSS_Accept_sec_context() at the target in + conjunction with such a context will return a token, to be processed + by a continuation call to GSS_Init_sec_context(), in order to achieve + mutual authentication. + + + + + +Linn Standards Track [Page 48] + +RFC 2743 GSS-API January 2000 + + +2.2.2: GSS_Accept_sec_context call + + Inputs: + + o acceptor_cred_handle CREDENTIAL HANDLE, -- NULL specifies + -- "use default" + + o input_context_handle CONTEXT HANDLE, -- 0 + -- (GSS_C_NO_CONTEXT) specifies "not yet assigned" + + o chan_bindings OCTET STRING, + + o input_token OCTET STRING + + Outputs: + + o major_status INTEGER, + + o minor_status INTEGER, + + o src_name INTERNAL NAME, -- guaranteed to be MN + -- once returned, caller must release with GSS_Release_name() + + o mech_type OBJECT IDENTIFIER, -- caller should treat as + -- read-only; does not need to be released + + o output_context_handle CONTEXT HANDLE, -- once returned + -- non-NULL in context establishment sequence, caller + -- must release with GSS_Delete_sec_context() + + o deleg_state BOOLEAN, + + o mutual_state BOOLEAN, + + o replay_det_state BOOLEAN, + + o sequence_state BOOLEAN, + + o anon_state BOOLEAN, + + o trans_state BOOLEAN, + + o prot_ready_state BOOLEAN, -- see Section 1.2.7 for discussion + + o conf_avail BOOLEAN, + + o integ_avail BOOLEAN, + + + + +Linn Standards Track [Page 49] + +RFC 2743 GSS-API January 2000 + + + o lifetime_rec INTEGER, -- in seconds, or reserved value for + -- INDEFINITE + + o delegated_cred_handle CREDENTIAL HANDLE, -- if returned non-NULL, + -- caller must release with GSS_Release_cred() + + o output_token OCTET STRING -- NULL or token to pass to context + -- initiator; if returned non-NULL, caller must release with + -- GSS_Release_buffer() + + This call may block pending network interactions for those mech_types + in which a directory service or other network entity must be + consulted on behalf of a context acceptor in order to validate a + received input_token. + + Return major_status codes: + + o GSS_S_COMPLETE indicates that context-level data structures were + successfully initialized, and that per-message processing can now be + performed in conjunction with this context. + + o GSS_S_CONTINUE_NEEDED indicates that control information in the + returned output_token must be sent to the initiator, and that a + response must be received and passed as the input_token argument to a + continuation call to GSS_Accept_sec_context(), before per-message + processing can be performed in conjunction with this context. + + o GSS_S_DEFECTIVE_TOKEN indicates that consistency checks performed + on the input_token failed, preventing further processing from being + performed based on that token. + + o GSS_S_DEFECTIVE_CREDENTIAL indicates that consistency checks + performed on the credential structure referenced by + acceptor_cred_handle failed, preventing further processing from being + performed using that credential structure. + + o GSS_S_BAD_SIG (GSS_S_BAD_MIC) indicates that the received + input_token contains an incorrect integrity check, so context setup + cannot be accomplished. + + o GSS_S_DUPLICATE_TOKEN indicates that the integrity check on the + received input_token was correct, but that the input_token was + recognized as a duplicate of an input_token already processed. No new + context is established. + + + + + + + +Linn Standards Track [Page 50] + +RFC 2743 GSS-API January 2000 + + + o GSS_S_OLD_TOKEN indicates that the integrity check on the received + input_token was correct, but that the input_token is too old to be + checked for duplication against previously-processed input_tokens. No + new context is established. + + o GSS_S_NO_CRED indicates that no context was established, either + because the input cred_handle was invalid, because the referenced + credentials are valid for context initiator use only, because the + caller lacks authorization to access the referenced credentials, or + because the procedure for default credential resolution failed. + + o GSS_S_CREDENTIALS_EXPIRED indicates that the credentials provided + through the input acceptor_cred_handle argument are no longer valid, + so context establishment cannot be completed. + + o GSS_S_BAD_BINDINGS indicates that a mismatch between the caller- + provided chan_bindings and those extracted from the input_token was + detected, signifying a security-relevant event and preventing context + establishment. + + o GSS_S_NO_CONTEXT indicates that no valid context was recognized + for the input context_handle provided; this major status will be + returned only for successor calls following GSS_S_CONTINUE_ NEEDED + status returns. + + o GSS_S_BAD_MECH indicates receipt of a context establishment token + specifying a mechanism unsupported by the local system or with the + caller's active credentials. + + o GSS_S_FAILURE indicates that context setup could not be + accomplished for reasons unspecified at the GSS-API level, and that + no interface-defined recovery action is available. + + The GSS_Accept_sec_context() routine is used by a context target. + Using information in the credentials structure referenced by the + input acceptor_cred_handle, it verifies the incoming input_token and + (following the successful completion of a context establishment + sequence) returns the authenticated src_name and the mech_type used. + The returned src_name is guaranteed to be an MN, processed by the + mechanism under which the context was established. The + acceptor_cred_handle must correspond to the same valid credentials + structure on the initial call to GSS_Accept_sec_context() and on any + successor calls resulting from GSS_S_CONTINUE_NEEDED status returns; + different protocol sequences modeled by the GSS_S_CONTINUE_NEEDED + mechanism will require access to credentials at different points in + the context establishment sequence. + + + + + +Linn Standards Track [Page 51] + +RFC 2743 GSS-API January 2000 + + + The caller-provided input_context_handle argument is to be 0 + (GSS_C_NO_CONTEXT), specifying "not yet assigned", on the first + GSS_Accept_sec_context() call relating to a given context. If + successful (i.e., if accompanied by major_status GSS_S_COMPLETE or + GSS_S_CONTINUE_NEEDED), and only if successful, the initial + GSS_Accept_sec_context() call returns a non-zero + output_context_handle for use in future references to this context. + Once a non-zero output_context_handle has been returned, GSS-API + callers should call GSS_Delete_sec_context() to release context- + related resources if errors occur in later phases of context + establishment, or when an established context is no longer required. + If GSS_Accept_sec_context() is passed the handle of a context which + is already fully established, GSS_S_FAILURE status is returned. + + The chan_bindings argument is used by the caller to provide + information binding the security context to security-related + characteristics (e.g., addresses, cryptographic keys) of the + underlying communications channel. See Section 1.1.6 of this document + for more discussion of this argument's usage. + + The returned state results (deleg_state, mutual_state, + replay_det_state, sequence_state, anon_state, trans_state, and + prot_ready_state) reflect the same information as described for + GSS_Init_sec_context(), and their values are significant under the + same return state conditions. + + The conf_avail return value indicates whether the context supports + per-message confidentiality services, and so informs the caller + whether or not a request for encryption through the conf_req_flag + input to GSS_Wrap() can be honored. In similar fashion, the + integ_avail return value indicates whether per-message integrity + services are available (through either GSS_GetMIC() or GSS_Wrap()) + on the established context. These values are significant under the + same return state conditions as described under + GSS_Init_sec_context(). + + The lifetime_rec return value is significant only in conjunction with + GSS_S_COMPLETE major_status, and indicates the length of time for + which the context will be valid, expressed as an offset from the + present. + + The returned mech_type value indicates the specific mechanism + employed on the context; it will never indicate the value for + "default". A valid mech_type result must be returned whenever + GSS_S_COMPLETE status is indicated; GSS-API implementations may (but + are not required to) also return mech_type along with predecessor + calls indicating GSS_S_CONTINUE_NEEDED status or (if a mechanism is + determinable) in conjunction with fatal error cases. For the case of + + + +Linn Standards Track [Page 52] + +RFC 2743 GSS-API January 2000 + + + mechanisms which themselves perform negotiation, the returned + mech_type result may indicate selection of a mechanism identified by + an OID different than that passed in the input mech_type argument, + and the returned value may change between successive calls returning + GSS_S_CONTINUE_NEEDED and the final call returning GSS_S_COMPLETE. + + The delegated_cred_handle result is significant only when deleg_state + is TRUE, and provides a means for the target to reference the + delegated credentials. The output_token result, when non-NULL, + provides a context-level token to be returned to the context + initiator to continue a multi-step context establishment sequence. As + noted with GSS_Init_sec_context(), any returned token should be + transferred to the context's peer (in this case, the context + initiator), independent of the value of the accompanying returned + major_status. + + Note: A target must be able to distinguish a context-level + input_token, which is passed to GSS_Accept_sec_context(), from the + per-message data elements passed to GSS_VerifyMIC() or GSS_Unwrap(). + These data elements may arrive in a single application message, and + GSS_Accept_sec_context() must be performed before per-message + processing can be performed successfully. + +2.2.3: GSS_Delete_sec_context call + + Input: + + o context_handle CONTEXT HANDLE + + Outputs: + + o major_status INTEGER, + + o minor_status INTEGER, + + o output_context_token OCTET STRING + + Return major_status codes: + + o GSS_S_COMPLETE indicates that the context was recognized, and that + relevant context-specific information was flushed. If the caller + provides a non-null buffer to receive an output_context_token, and + the mechanism returns a non-NULL token into that buffer, the returned + output_context_token is ready for transfer to the context's peer. + + o GSS_S_NO_CONTEXT indicates that no valid context was recognized + for the input context_handle provided, so no deletion was performed. + + + + +Linn Standards Track [Page 53] + +RFC 2743 GSS-API January 2000 + + + o GSS_S_FAILURE indicates that the context is recognized, but that + the GSS_Delete_sec_context() operation could not be performed for + reasons unspecified at the GSS-API level. + + This call can be made by either peer in a security context, to flush + context-specific information. Once a non-zero output_context_handle + has been returned by context establishment calls, GSS-API callers + should call GSS_Delete_sec_context() to release context-related + resources if errors occur in later phases of context establishment, + or when an established context is no longer required. This call may + block pending network interactions for mech_types in which active + notification must be made to a central server when a security context + is to be deleted. + + If a non-null output_context_token parameter is provided by the + caller, an output_context_token may be returned to the caller. If an + output_context_token is provided to the caller, it can be passed to + the context's peer to inform the peer's GSS-API implementation that + the peer's corresponding context information can also be flushed. + (Once a context is established, the peers involved are expected to + retain cached credential and context-related information until the + information's expiration time is reached or until a + GSS_Delete_sec_context() call is made.) + + The facility for context_token usage to signal context deletion is + retained for compatibility with GSS-API Version 1. For current + usage, it is recommended that both peers to a context invoke + GSS_Delete_sec_context() independently, passing a null + output_context_token buffer to indicate that no context_token is + required. Implementations of GSS_Delete_sec_context() should delete + relevant locally-stored context information. + + Attempts to perform per-message processing on a deleted context will + result in error returns. + +2.2.4: GSS_Process_context_token call + + Inputs: + + o context_handle CONTEXT HANDLE, + + o input_context_token OCTET STRING + + Outputs: + + o major_status INTEGER, + + o minor_status INTEGER, + + + +Linn Standards Track [Page 54] + +RFC 2743 GSS-API January 2000 + + + Return major_status codes: + + o GSS_S_COMPLETE indicates that the input_context_token was + successfully processed in conjunction with the context referenced by + context_handle. + + o GSS_S_DEFECTIVE_TOKEN indicates that consistency checks performed + on the received context_token failed, preventing further processing + from being performed with that token. + + o GSS_S_NO_CONTEXT indicates that no valid context was recognized + for the input context_handle provided. + + o GSS_S_FAILURE indicates that the context is recognized, but that + the GSS_Process_context_token() operation could not be performed for + reasons unspecified at the GSS-API level. + + This call is used to process context_tokens received from a peer once + a context has been established, with corresponding impact on + context-level state information. One use for this facility is + processing of the context_tokens generated by + GSS_Delete_sec_context(); GSS_Process_context_token() will not block + pending network interactions for that purpose. Another use is to + process tokens indicating remote-peer context establishment failures + after the point where the local GSS-API implementation has already + indicated GSS_S_COMPLETE status. + +2.2.5: GSS_Context_time call + + Input: + + o context_handle CONTEXT HANDLE, + + Outputs: + + o major_status INTEGER, + + o minor_status INTEGER, + + o lifetime_rec INTEGER -- in seconds, or reserved value for + -- INDEFINITE + + Return major_status codes: + + o GSS_S_COMPLETE indicates that the referenced context is valid, and + will remain valid for the amount of time indicated in lifetime_rec. + + + + + +Linn Standards Track [Page 55] + +RFC 2743 GSS-API January 2000 + + + o GSS_S_CONTEXT_EXPIRED indicates that data items related to the + referenced context have expired. + + o GSS_S_NO_CONTEXT indicates that no valid context was recognized + for the input context_handle provided. + + o GSS_S_FAILURE indicates that the requested operation failed for + reasons unspecified at the GSS-API level. + + This call is used to determine the amount of time for which a + currently established context will remain valid. + +2.2.6: GSS_Inquire_context call + + Input: + + o context_handle CONTEXT HANDLE, + + Outputs: + + o major_status INTEGER, + + o minor_status INTEGER, + + o src_name INTERNAL NAME, -- name of context initiator, + -- guaranteed to be MN; + -- caller must release with GSS_Release_name() if returned + + o targ_name INTERNAL NAME, -- name of context target, + -- guaranteed to be MN; + -- caller must release with GSS_Release_name() if returned + + o lifetime_rec INTEGER -- in seconds, or reserved value for + -- INDEFINITE or EXPIRED + + o mech_type OBJECT IDENTIFIER, -- the mechanism supporting this + -- security context; caller should treat as read-only and not + -- attempt to release + + o deleg_state BOOLEAN, + + o mutual_state BOOLEAN, + + o replay_det_state BOOLEAN, + + o sequence_state BOOLEAN, + + o anon_state BOOLEAN, + + + +Linn Standards Track [Page 56] + +RFC 2743 GSS-API January 2000 + + + o trans_state BOOLEAN, + + o prot_ready_state BOOLEAN, + + o conf_avail BOOLEAN, + + o integ_avail BOOLEAN, + + o locally_initiated BOOLEAN, -- TRUE if initiator, FALSE if acceptor + + o open BOOLEAN, -- TRUE if context fully established, FALSE + -- if partly established (in CONTINUE_NEEDED state) + + Return major_status codes: + + o GSS_S_COMPLETE indicates that the referenced context is valid and + that deleg_state, mutual_state, replay_det_state, sequence_state, + anon_state, trans_state, prot_ready_state, conf_avail, integ_avail, + locally_initiated, and open return values describe the corresponding + characteristics of the context. If open is TRUE, lifetime_rec is + also returned: if open is TRUE and the context peer's name is known, + src_name and targ_name are valid in addition to the values listed + above. The mech_type value must be returned for contexts where open + is TRUE and may be returned for contexts where open is FALSE. + + o GSS_S_NO_CONTEXT indicates that no valid context was recognized + for the input context_handle provided. Return values other than + major_status and minor_status are undefined. + + o GSS_S_FAILURE indicates that the requested operation failed for + reasons unspecified at the GSS-API level. Return values other than + major_status and minor_status are undefined. + + This call is used to extract information describing characteristics + of a security context. Note that GSS-API implementations are + expected to retain inquirable context data on a context until the + context is released by a caller, even after the context has expired, + although underlying cryptographic data elements may be deleted after + expiration in order to limit their exposure. + +2.2.7: GSS_Wrap_size_limit call + + Inputs: + + o context_handle CONTEXT HANDLE, + + o conf_req_flag BOOLEAN, + + + + +Linn Standards Track [Page 57] + +RFC 2743 GSS-API January 2000 + + + o qop INTEGER, + + o output_size INTEGER + + Outputs: + + o major_status INTEGER, + + o minor_status INTEGER, + + o max_input_size INTEGER + + Return major_status codes: + + o GSS_S_COMPLETE indicates a successful token size determination: + an input message with a length in octets equal to the returned + max_input_size value will, when passed to GSS_Wrap() for processing + on the context identified by the context_handle parameter with the + confidentiality request state as provided in conf_req_flag and with + the quality of protection specifier provided in the qop parameter, + yield an output token no larger than the value of the provided + output_size parameter. + + o GSS_S_CONTEXT_EXPIRED indicates that the provided input + context_handle is recognized, but that the referenced context has + expired. Return values other than major_status and minor_status are + undefined. + + o GSS_S_NO_CONTEXT indicates that no valid context was recognized + for the input context_handle provided. Return values other than + major_status and minor_status are undefined. + + o GSS_S_BAD_QOP indicates that the provided QOP value is not + recognized or supported for the context. + + o GSS_S_FAILURE indicates that the requested operation failed for + reasons unspecified at the GSS-API level. Return values other than + major_status and minor_status are undefined. + + This call is used to determine the largest input datum which may be + passed to GSS_Wrap() without yielding an output token larger than a + caller-specified value. + + + + + + + + + +Linn Standards Track [Page 58] + +RFC 2743 GSS-API January 2000 + + +2.2.8: GSS_Export_sec_context call + + Inputs: + + o context_handle CONTEXT HANDLE + + Outputs: + + o major_status INTEGER, + + o minor_status INTEGER, + + o interprocess_token OCTET STRING -- caller must release + -- with GSS_Release_buffer() + + Return major_status codes: + + o GSS_S_COMPLETE indicates that the referenced context has been + successfully exported to a representation in the interprocess_token, + and is no longer available for use by the caller. + + o GSS_S_UNAVAILABLE indicates that the context export facility is + not available for use on the referenced context. (This status should + occur only for contexts for which the trans_state value is FALSE.) + Return values other than major_status and minor_status are undefined. + + o GSS_S_CONTEXT_EXPIRED indicates that the provided input + context_handle is recognized, but that the referenced context has + expired. Return values other than major_status and minor_status are + undefined. + + o GSS_S_NO_CONTEXT indicates that no valid context was recognized + for the input context_handle provided. Return values other than + major_status and minor_status are undefined. + + o GSS_S_FAILURE indicates that the requested operation failed for + reasons unspecified at the GSS-API level. Return values other than + major_status and minor_status are undefined. + + This call generates an interprocess token for transfer to another + process within an end system, in order to transfer control of a + security context to that process. The recipient of the interprocess + token will call GSS_Import_sec_context() to accept the transfer. The + GSS_Export_sec_context() operation is defined for use only with + security contexts which are fully and successfully established (i.e., + those for which GSS_Init_sec_context() and GSS_Accept_sec_context() + have returned GSS_S_COMPLETE major_status). + + + + +Linn Standards Track [Page 59] + +RFC 2743 GSS-API January 2000 + + + A successful GSS_Export_sec_context() operation deactivates the + security context for the calling process; for this case, the GSS-API + implementation shall deallocate all process-wide resources associated + with the security context and shall set the context_handle to + GSS_C_NO_CONTEXT. In the event of an error that makes it impossible + to complete export of the security context, the GSS-API + implementation must not return an interprocess token and should + strive to leave the security context referenced by the context_handle + untouched. If this is impossible, it is permissible for the + implementation to delete the security context, provided that it also + sets the context_handle parameter to GSS_C_NO_CONTEXT. + + Portable callers must not assume that a given interprocess token can + be imported by GSS_Import_sec_context() more than once, thereby + creating multiple instantiations of a single context. GSS-API + implementations may detect and reject attempted multiple imports, but + are not required to do so. + + The internal representation contained within the interprocess token + is an implementation-defined local matter. Interprocess tokens + cannot be assumed to be transferable across different GSS-API + implementations. + + It is recommended that GSS-API implementations adopt policies suited + to their operational environments in order to define the set of + processes eligible to import a context, but specific constraints in + this area are local matters. Candidate examples include transfers + between processes operating on behalf of the same user identity, or + processes comprising a common job. However, it may be impossible to + enforce such policies in some implementations. + + In support of the above goals, implementations may protect the + transferred context data by using cryptography to protect data within + the interprocess token, or by using interprocess tokens as a means to + reference local interprocess communication facilities (protected by + other means) rather than storing the context data directly within the + tokens. + + Transfer of an open context may, for certain mechanisms and + implementations, reveal data about the credential which was used to + establish the context. Callers should, therefore, be cautious about + the trustworthiness of processes to which they transfer contexts. + Although the GSS-API implementation may provide its own set of + protections over the exported context, the caller is responsible for + protecting the interprocess token from disclosure, and for taking + care that the context is transferred to an appropriate destination + process. + + + + +Linn Standards Track [Page 60] + +RFC 2743 GSS-API January 2000 + + +2.2.9: GSS_Import_sec_context call + + Inputs: + + o interprocess_token OCTET STRING + + Outputs: + + o major_status INTEGER, + + o minor_status INTEGER, + + o context_handle CONTEXT HANDLE -- if successfully returned, + -- caller must release with GSS_Delete_sec_context() + + Return major_status codes: + + o GSS_S_COMPLETE indicates that the context represented by the input + interprocess_token has been successfully transferred to the caller, + and is available for future use via the output context_handle. + + o GSS_S_NO_CONTEXT indicates that the context represented by the + input interprocess_token was invalid. Return values other than + major_status and minor_status are undefined. + + o GSS_S_DEFECTIVE_TOKEN indicates that the input interprocess_token + was defective. Return values other than major_status and + minor_status are undefined. + + o GSS_S_UNAVAILABLE indicates that the context import facility is + not available for use on the referenced context. Return values other + than major_status and minor_status are undefined. + + o GSS_S_UNAUTHORIZED indicates that the context represented by the + input interprocess_token is unauthorized for transfer to the caller. + Return values other than major_status and minor_status are undefined. + + o GSS_S_FAILURE indicates that the requested operation failed for + reasons unspecified at the GSS-API level. Return values other than + major_status and minor_status are undefined. + + This call processes an interprocess token generated by + GSS_Export_sec_context(), making the transferred context available + for use by the caller. After a successful GSS_Import_sec_context() + operation, the imported context is available for use by the importing + process. In particular, the imported context is usable for all per- + message operations and may be deleted or exported by its importer. + The inability to receive delegated credentials through + + + +Linn Standards Track [Page 61] + +RFC 2743 GSS-API January 2000 + + + gss_import_sec_context() precludes establishment of new contexts + based on information delegated to the importer's end system within + the context which is being imported, unless those delegated + credentials are obtained through separate routines (e.g., XGSS-API + calls) outside the GSS-V2 definition. + + For further discussion of the security and authorization issues + regarding this call, please see the discussion in Section 2.2.8. + +2.3: Per-message calls + + This group of calls is used to perform per-message protection + processing on an established security context. None of these calls + block pending network interactions. These calls may be invoked by a + context's initiator or by the context's target. The four members of + this group should be considered as two pairs; the output from + GSS_GetMIC() is properly input to GSS_VerifyMIC(), and the output + from GSS_Wrap() is properly input to GSS_Unwrap(). + + GSS_GetMIC() and GSS_VerifyMIC() support data origin authentication + and data integrity services. When GSS_GetMIC() is invoked on an input + message, it yields a per-message token containing data items which + allow underlying mechanisms to provide the specified security + services. The original message, along with the generated per-message + token, is passed to the remote peer; these two data elements are + processed by GSS_VerifyMIC(), which validates the message in + conjunction with the separate token. + + GSS_Wrap() and GSS_Unwrap() support caller-requested confidentiality + in addition to the data origin authentication and data integrity + services offered by GSS_GetMIC() and GSS_VerifyMIC(). GSS_Wrap() + outputs a single data element, encapsulating optionally enciphered + user data as well as associated token data items. The data element + output from GSS_Wrap() is passed to the remote peer and processed by + GSS_Unwrap() at that system. GSS_Unwrap() combines decipherment (as + required) with validation of data items related to authentication and + integrity. + + Although zero-length tokens are never returned by GSS calls for + transfer to a context's peer, a zero-length object may be passed by a + caller into GSS_Wrap(), in which case the corresponding peer calling + GSS_Unwrap() on the transferred token will receive a zero-length + object as output from GSS_Unwrap(). Similarly, GSS_GetMIC() can be + called on an empty object, yielding a MIC which GSS_VerifyMIC() will + successfully verify against the active security context in + conjunction with a zero-length object. + + + + + +Linn Standards Track [Page 62] + +RFC 2743 GSS-API January 2000 + + +2.3.1: GSS_GetMIC call + + Note: This call is functionally equivalent to the GSS_Sign call as + defined in previous versions of this specification. In the interests + of backward compatibility, it is recommended that implementations + support this function under both names for the present; future + references to this function as GSS_Sign are deprecated. + + Inputs: + + o context_handle CONTEXT HANDLE, + + o qop_req INTEGER, -- 0 specifies default QOP + + o message OCTET STRING + + Outputs: + + o major_status INTEGER, + + o minor_status INTEGER, + + o per_msg_token OCTET STRING -- caller must release + -- with GSS_Release_buffer() + + Return major_status codes: + + o GSS_S_COMPLETE indicates that an integrity check, suitable for an + established security context, was successfully applied and that the + message and corresponding per_msg_token are ready for transmission. + + o GSS_S_CONTEXT_EXPIRED indicates that context-related data items + have expired, so that the requested operation cannot be performed. + + o GSS_S_NO_CONTEXT indicates that no context was recognized for the + input context_handle provided. + + o GSS_S_BAD_QOP indicates that the provided QOP value is not + recognized or supported for the context. + + o GSS_S_FAILURE indicates that the context is recognized, but that + the requested operation could not be performed for reasons + unspecified at the GSS-API level. + + Using the security context referenced by context_handle, apply an + integrity check to the input message (along with timestamps and/or + other data included in support of mech_type-specific mechanisms) and + (if GSS_S_COMPLETE status is indicated) return the result in + + + +Linn Standards Track [Page 63] + +RFC 2743 GSS-API January 2000 + + + per_msg_token. The qop_req parameter, interpretation of which is + discussed in Section 1.2.4, allows quality-of-protection control. The + caller passes the message and the per_msg_token to the target. + + The GSS_GetMIC() function completes before the message and + per_msg_token is sent to the peer; successful application of + GSS_GetMIC() does not guarantee that a corresponding GSS_VerifyMIC() + has been (or can necessarily be) performed successfully when the + message arrives at the destination. + + Mechanisms which do not support per-message protection services + should return GSS_S_FAILURE if this routine is called. + +2.3.2: GSS_VerifyMIC call + + Note: This call is functionally equivalent to the GSS_Verify call as + defined in previous versions of this specification. In the interests + of backward compatibility, it is recommended that implementations + support this function under both names for the present; future + references to this function as GSS_Verify are deprecated. + + Inputs: + + o context_handle CONTEXT HANDLE, + + o message OCTET STRING, + + o per_msg_token OCTET STRING + + Outputs: + + o qop_state INTEGER, + + o major_status INTEGER, + + o minor_status INTEGER, + + Return major_status codes: + + o GSS_S_COMPLETE indicates that the message was successfully + verified. + + o GSS_S_DEFECTIVE_TOKEN indicates that consistency checks performed + on the received per_msg_token failed, preventing further processing + from being performed with that token. + + o GSS_S_BAD_SIG (GSS_S_BAD_MIC) indicates that the received + per_msg_token contains an incorrect integrity check for the message. + + + +Linn Standards Track [Page 64] + +RFC 2743 GSS-API January 2000 + + + o GSS_S_DUPLICATE_TOKEN, GSS_S_OLD_TOKEN, GSS_S_UNSEQ_TOKEN, and + GSS_S_GAP_TOKEN values appear in conjunction with the optional per- + message replay detection features described in Section 1.2.3; their + semantics are described in that section. + + o GSS_S_CONTEXT_EXPIRED indicates that context-related data items + have expired, so that the requested operation cannot be performed. + + o GSS_S_NO_CONTEXT indicates that no context was recognized for the + input context_handle provided. + + o GSS_S_FAILURE indicates that the context is recognized, but that + the GSS_VerifyMIC() operation could not be performed for reasons + unspecified at the GSS-API level. + + Using the security context referenced by context_handle, verify that + the input per_msg_token contains an appropriate integrity check for + the input message, and apply any active replay detection or + sequencing features. Returns an indication of the quality-of- + protection applied to the processed message in the qop_state result. + + Mechanisms which do not support per-message protection services + should return GSS_S_FAILURE if this routine is called. + +2.3.3: GSS_Wrap call + + Note: This call is functionally equivalent to the GSS_Seal call as + defined in previous versions of this specification. In the interests + of backward compatibility, it is recommended that implementations + support this function under both names for the present; future + references to this function as GSS_Seal are deprecated. + + Inputs: + + o context_handle CONTEXT HANDLE, + + o conf_req_flag BOOLEAN, + + o qop_req INTEGER, -- 0 specifies default QOP + + o input_message OCTET STRING + + Outputs: + + o major_status INTEGER, + + o minor_status INTEGER, + + + + +Linn Standards Track [Page 65] + +RFC 2743 GSS-API January 2000 + + + o conf_state BOOLEAN, + + o output_message OCTET STRING -- caller must release with + -- GSS_Release_buffer() + + Return major_status codes: + + o GSS_S_COMPLETE indicates that the input_message was successfully + processed and that the output_message is ready for transmission. + + o GSS_S_CONTEXT_EXPIRED indicates that context-related data items + have expired, so that the requested operation cannot be performed. + + o GSS_S_NO_CONTEXT indicates that no context was recognized for the + input context_handle provided. + + o GSS_S_BAD_QOP indicates that the provided QOP value is not + recognized or supported for the context. + + o GSS_S_FAILURE indicates that the context is recognized, but that + the GSS_Wrap() operation could not be performed for reasons + unspecified at the GSS-API level. + + Performs the data origin authentication and data integrity functions + of GSS_GetMIC(). If the input conf_req_flag is TRUE, requests that + confidentiality be applied to the input_message. Confidentiality may + not be supported in all mech_types or by all implementations; the + returned conf_state flag indicates whether confidentiality was + provided for the input_message. The qop_req parameter, interpretation + of which is discussed in Section 1.2.4, allows quality-of-protection + control. + + When GSS_S_COMPLETE status is returned, the GSS_Wrap() call yields a + single output_message data element containing (optionally enciphered) + user data as well as control information. + + Mechanisms which do not support per-message protection services + should return GSS_S_FAILURE if this routine is called. + +2.3.4: GSS_Unwrap call + + Note: This call is functionally equivalent to the GSS_Unseal call as + defined in previous versions of this specification. In the interests + of backward compatibility, it is recommended that implementations + support this function under both names for the present; future + references to this function as GSS_Unseal are deprecated. + + + + + +Linn Standards Track [Page 66] + +RFC 2743 GSS-API January 2000 + + + Inputs: + + o context_handle CONTEXT HANDLE, + + o input_message OCTET STRING + + Outputs: + + o conf_state BOOLEAN, + + o qop_state INTEGER, + + o major_status INTEGER, + + o minor_status INTEGER, + + o output_message OCTET STRING -- caller must release with + -- GSS_Release_buffer() + + Return major_status codes: + + o GSS_S_COMPLETE indicates that the input_message was successfully + processed and that the resulting output_message is available. + + o GSS_S_DEFECTIVE_TOKEN indicates that consistency checks performed + on the per_msg_token extracted from the input_message failed, + preventing further processing from being performed. + + o GSS_S_BAD_SIG (GSS_S_BAD_MIC) indicates that an incorrect + integrity check was detected for the message. + + o GSS_S_DUPLICATE_TOKEN, GSS_S_OLD_TOKEN, GSS_S_UNSEQ_TOKEN, and + GSS_S_GAP_TOKEN values appear in conjunction with the optional per- + message replay detection features described in Section 1.2.3; their + semantics are described in that section. + + o GSS_S_CONTEXT_EXPIRED indicates that context-related data items + have expired, so that the requested operation cannot be performed. + + o GSS_S_NO_CONTEXT indicates that no context was recognized for the + input context_handle provided. + + o GSS_S_FAILURE indicates that the context is recognized, but that + the GSS_Unwrap() operation could not be performed for reasons + unspecified at the GSS-API level. + + + + + + +Linn Standards Track [Page 67] + +RFC 2743 GSS-API January 2000 + + + Processes a data element generated (and optionally enciphered) by + GSS_Wrap(), provided as input_message. The returned conf_state value + indicates whether confidentiality was applied to the input_message. + If conf_state is TRUE, GSS_Unwrap() has deciphered the input_message. + Returns an indication of the quality-of-protection applied to the + processed message in the qop_state result. GSS_Unwrap() performs the + data integrity and data origin authentication checking functions of + GSS_VerifyMIC() on the plaintext data. Plaintext data is returned in + output_message. + + Mechanisms which do not support per-message protection services + should return GSS_S_FAILURE if this routine is called. + +2.4: Support calls + + This group of calls provides support functions useful to GSS-API + callers, independent of the state of established contexts. Their + characterization with regard to blocking or non-blocking status in + terms of network interactions is unspecified. + +2.4.1: GSS_Display_status call + + Inputs: + + o status_value INTEGER, -- GSS-API major_status or minor_status + -- return value + + o status_type INTEGER, -- 1 if major_status, 2 if minor_status + + o mech_type OBJECT IDENTIFIER -- mech_type to be used for + -- minor_status translation + + Outputs: + + o major_status INTEGER, + + o minor_status INTEGER, + + o status_string_set SET OF OCTET STRING -- required calls for + -- release by caller are specific to language bindings + + Return major_status codes: + + o GSS_S_COMPLETE indicates that a valid printable status + representation (possibly representing more than one status event + encoded within the status_value) is available in the returned + status_string_set. + + + + +Linn Standards Track [Page 68] + +RFC 2743 GSS-API January 2000 + + + o GSS_S_BAD_MECH indicates that translation in accordance with an + unsupported mech_type was requested, so translation could not be + performed. + + o GSS_S_BAD_STATUS indicates that the input status_value was + invalid, or that the input status_type carried a value other than 1 + or 2, so translation could not be performed. + + o GSS_S_FAILURE indicates that the requested operation could not be + performed for reasons unspecified at the GSS-API level. + + Provides a means for callers to translate GSS-API-returned major and + minor status codes into printable string representations. Note: some + language bindings may employ an iterative approach in order to emit + successive status components; this approach is acceptable but not + required for conformance with the current specification. + + Although not contemplated in [RFC-2078], it has been observed that + some existing GSS-API implementations return GSS_S_CONTINUE_NEEDED + status when iterating through successive messages returned from + GSS_Display_status(). This behavior is deprecated; + GSS_S_CONTINUE_NEEDED should be returned only by + GSS_Init_sec_context() and GSS_Accept_sec_context(). For maximal + portability, however, it is recommended that defensive callers be + able to accept and ignore GSS_S_CONTINUE_NEEDED status if indicated + by GSS_Display_status() or any other call other than + GSS_Init_sec_context() or GSS_Accept_sec_context(). + +2.4.2: GSS_Indicate_mechs call + + Input: + + o (none) + + Outputs: + + o major_status INTEGER, + + o minor_status INTEGER, + + o mech_set SET OF OBJECT IDENTIFIER -- caller must release + -- with GSS_Release_oid_set() + + Return major_status codes: + + o GSS_S_COMPLETE indicates that a set of available mechanisms has + been returned in mech_set. + + + + +Linn Standards Track [Page 69] + +RFC 2743 GSS-API January 2000 + + + o GSS_S_FAILURE indicates that the requested operation could not be + performed for reasons unspecified at the GSS-API level. + + Allows callers to determine the set of mechanism types available on + the local system. This call is intended for support of specialized + callers who need to request non-default mech_type sets from GSS-API + calls which accept input mechanism type specifiers. + +2.4.3: GSS_Compare_name call + + Inputs: + + o name1 INTERNAL NAME, + + o name2 INTERNAL NAME + + Outputs: + + o major_status INTEGER, + + o minor_status INTEGER, + + o name_equal BOOLEAN + + Return major_status codes: + + o GSS_S_COMPLETE indicates that name1 and name2 were comparable, and + that the name_equal result indicates whether name1 and name2 + represent the same entity. + + o GSS_S_BAD_NAMETYPE indicates that the two input names' types are + different and incomparable, so that the comparison operation could + not be completed. + + o GSS_S_BAD_NAME indicates that one or both of the input names was + ill-formed in terms of its internal type specifier, so the comparison + operation could not be completed. + + o GSS_S_FAILURE indicates that the call's operation could not be + performed for reasons unspecified at the GSS-API level. + + Allows callers to compare two internal name representations to + determine whether they refer to the same entity. If either name + presented to GSS_Compare_name() denotes an anonymous principal, + GSS_Compare_name() shall indicate FALSE. It is not required that + either or both inputs name1 and name2 be MNs; for some + + + + + +Linn Standards Track [Page 70] + +RFC 2743 GSS-API January 2000 + + + implementations and cases, GSS_S_BAD_NAMETYPE may be returned, + indicating name incomparability, for the case where neither input + name is an MN. + +2.4.4: GSS_Display_name call + + Inputs: + + o name INTERNAL NAME + + Outputs: + + o major_status INTEGER, + + o minor_status INTEGER, + + o name_string OCTET STRING, -- caller must release + -- with GSS_Release_buffer() + + o name_type OBJECT IDENTIFIER -- caller should treat + -- as read-only; does not need to be released + + Return major_status codes: + + o GSS_S_COMPLETE indicates that a valid printable name + representation is available in the returned name_string. + + o GSS_S_BAD_NAME indicates that the contents of the provided name + were inconsistent with the internally-indicated name type, so no + printable representation could be generated. + + o GSS_S_FAILURE indicates that the requested operation could not be + performed for reasons unspecified at the GSS-API level. + + Allows callers to translate an internal name representation into a + printable form with associated namespace type descriptor. The syntax + of the printable form is a local matter. + + If the input name represents an anonymous identity, a reserved value + (GSS_C_NT_ANONYMOUS) shall be returned for name_type. + + The GSS_C_NO_OID name type is to be returned only when the + corresponding internal name was created through import with + GSS_C_NO_OID. It is acceptable for mechanisms to normalize names + imported with GSS_C_NO_OID into other supported types and, therefore, + to display them with types other than GSS_C_NO_OID. + + + + + +Linn Standards Track [Page 71] + +RFC 2743 GSS-API January 2000 + + +2.4.5: GSS_Import_name call + + Inputs: + + o input_name_string OCTET STRING, + + o input_name_type OBJECT IDENTIFIER + + Outputs: + + o major_status INTEGER, + + o minor_status INTEGER, + + o output_name INTERNAL NAME -- caller must release with + -- GSS_Release_name() + + Return major_status codes: + + o GSS_S_COMPLETE indicates that a valid name representation is + output in output_name and described by the type value in + output_name_type. + + o GSS_S_BAD_NAMETYPE indicates that the input_name_type is + unsupported by the applicable underlying GSS-API mechanism(s), so the + import operation could not be completed. + + o GSS_S_BAD_NAME indicates that the provided input_name_string is + ill-formed in terms of the input_name_type, so the import operation + could not be completed. + + o GSS_S_BAD_MECH indicates that the input presented for import was + an exported name object and that its enclosed mechanism type was not + recognized or was unsupported by the GSS-API implementation. + + o GSS_S_FAILURE indicates that the requested operation could not be + performed for reasons unspecified at the GSS-API level. + + Allows callers to provide a name representation as a contiguous octet + string, designate the type of namespace in conjunction with which it + should be parsed, and convert that representation to an internal form + suitable for input to other GSS-API routines. The syntax of the + input_name_string is defined in conjunction with its associated name + type; depending on the input_name_type, the associated + input_name_string may or may not be a printable string. If the + input_name_type's value is GSS_C_NO_OID, a mechanism-specific default + printable syntax (which shall be specified in the corresponding GSS- + V2 mechanism specification) is assumed for the input_name_string; + + + +Linn Standards Track [Page 72] + +RFC 2743 GSS-API January 2000 + + + other input_name_type values as registered by GSS-API implementations + can be used to indicate specific non-default name syntaxes. Note: The + input_name_type argument serves to describe and qualify the + interpretation of the associated input_name_string; it does not + specify the data type of the returned output_name. + + If a mechanism claims support for a particular name type, its + GSS_Import_name() operation shall be able to accept all possible + values conformant to the external name syntax as defined for that + name type. These imported values may correspond to: + + (1) locally registered entities (for which credentials may be + acquired), + + (2) non-local entities (for which local credentials cannot be + acquired, but which may be referenced as targets of initiated + security contexts or initiators of accepted security contexts), or + to + + (3) neither of the above. + + Determination of whether a particular name belongs to class (1), (2), + or (3) as described above is not guaranteed to be performed by the + GSS_Import_name() function. + + The internal name generated by a GSS_Import_name() operation may be a + single-mechanism MN, and is likely to be an MN within a single- + mechanism implementation, but portable callers must not depend on + this property (and must not, therefore, assume that the output from + GSS_Import_name() can be passed directly to GSS_Export_name() without + first being processed through GSS_Canonicalize_name()). + +2.4.6: GSS_Release_name call + + Inputs: + + o name INTERNAL NAME + + Outputs: + + o major_status INTEGER, + + o minor_status INTEGER + + Return major_status codes: + + o GSS_S_COMPLETE indicates that the storage associated with the + input name was successfully released. + + + +Linn Standards Track [Page 73] + +RFC 2743 GSS-API January 2000 + + + o GSS_S_BAD_NAME indicates that the input name argument did not + contain a valid name. + + o GSS_S_FAILURE indicates that the requested operation could not be + performed for reasons unspecified at the GSS-API level. + + Allows callers to release the storage associated with an internal + name representation. This call's specific behavior depends on the + language and programming environment within which a GSS-API + implementation operates, and is therefore detailed within applicable + bindings specifications; in particular, implementation and invocation + of this call may be superfluous (and may be omitted) within bindings + where memory management is automatic. + +2.4.7: GSS_Release_buffer call + + Inputs: + + o buffer OCTET STRING + + Outputs: + + o major_status INTEGER, + + o minor_status INTEGER + + Return major_status codes: + + o GSS_S_COMPLETE indicates that the storage associated with the + input buffer was successfully released. + + o GSS_S_FAILURE indicates that the requested operation could not be + performed for reasons unspecified at the GSS-API level. + + Allows callers to release the storage associated with an OCTET STRING + buffer allocated by another GSS-API call. This call's specific + behavior depends on the language and programming environment within + which a GSS-API implementation operates, and is therefore detailed + within applicable bindings specifications; in particular, + implementation and invocation of this call may be superfluous (and + may be omitted) within bindings where memory management is automatic. + +2.4.8: GSS_Release_OID_set call + + Inputs: + + o buffer SET OF OBJECT IDENTIFIER + + + + +Linn Standards Track [Page 74] + +RFC 2743 GSS-API January 2000 + + + Outputs: + + o major_status INTEGER, + + o minor_status INTEGER + + Return major_status codes: + + o GSS_S_COMPLETE indicates that the storage associated with the + input object identifier set was successfully released. + + o GSS_S_FAILURE indicates that the requested operation could not be + performed for reasons unspecified at the GSS-API level. + + Allows callers to release the storage associated with an object + identifier set object allocated by another GSS-API call. This call's + specific behavior depends on the language and programming environment + within which a GSS-API implementation operates, and is therefore + detailed within applicable bindings specifications; in particular, + implementation and invocation of this call may be superfluous (and + may be omitted) within bindings where memory management is automatic. + +2.4.9: GSS_Create_empty_OID_set call + + Inputs: + + o (none) + + Outputs: + + o major_status INTEGER, + + o minor_status INTEGER, + + o oid_set SET OF OBJECT IDENTIFIER -- caller must release + -- with GSS_Release_oid_set() + + Return major_status codes: + + o GSS_S_COMPLETE indicates successful completion + + o GSS_S_FAILURE indicates that the operation failed + + Creates an object identifier set containing no object identifiers, to + which members may be subsequently added using the + GSS_Add_OID_set_member() routine. These routines are intended to be + used to construct sets of mechanism object identifiers, for input to + GSS_Acquire_cred(). + + + +Linn Standards Track [Page 75] + +RFC 2743 GSS-API January 2000 + + +2.4.10: GSS_Add_OID_set_member call + + Inputs: + + o member_oid OBJECT IDENTIFIER, + + o oid_set SET OF OBJECT IDENTIFIER + + Outputs: + + o major_status INTEGER, + + o minor_status INTEGER, + + Return major_status codes: + + o GSS_S_COMPLETE indicates successful completion + + o GSS_S_FAILURE indicates that the operation failed + + Adds an Object Identifier to an Object Identifier set. This routine + is intended for use in conjunction with GSS_Create_empty_OID_set() + when constructing a set of mechanism OIDs for input to + GSS_Acquire_cred(). + +2.4.11: GSS_Test_OID_set_member call + + Inputs: + + o member OBJECT IDENTIFIER, + + o set SET OF OBJECT IDENTIFIER + + Outputs: + + o major_status INTEGER, + + o minor_status INTEGER, + + o present BOOLEAN + + Return major_status codes: + + o GSS_S_COMPLETE indicates successful completion + + o GSS_S_FAILURE indicates that the operation failed + + + + + +Linn Standards Track [Page 76] + +RFC 2743 GSS-API January 2000 + + + Interrogates an Object Identifier set to determine whether a + specified Object Identifier is a member. This routine is intended to + be used with OID sets returned by GSS_Indicate_mechs(), + GSS_Acquire_cred(), and GSS_Inquire_cred(). + +2.4.12: GSS_Inquire_names_for_mech call + + Input: + + o input_mech_type OBJECT IDENTIFIER, -- mechanism type + + Outputs: + + o major_status INTEGER, + + o minor_status INTEGER, + + o name_type_set SET OF OBJECT IDENTIFIER -- caller must release + -- with GSS_Release_oid_set() + + Return major_status codes: + + o GSS_S_COMPLETE indicates that the output name_type_set contains a + list of name types which are supported by the locally available + mechanism identified by input_mech_type. + + o GSS_S_BAD_MECH indicates that the mechanism identified by + input_mech_type was unsupported within the local implementation, + causing the query to fail. + + o GSS_S_FAILURE indicates that the requested operation could not be + performed for reasons unspecified at the GSS-API level. + + Allows callers to determine the set of name types which are + supportable by a specific locally-available mechanism. + +2.4.13: GSS_Inquire_mechs_for_name call + + Inputs: + + o input_name INTERNAL NAME, + + Outputs: + + o major_status INTEGER, + + o minor_status INTEGER, + + + + +Linn Standards Track [Page 77] + +RFC 2743 GSS-API January 2000 + + + o mech_types SET OF OBJECT IDENTIFIER -- caller must release + -- with GSS_Release_oid_set() + + Return major_status codes: + + o GSS_S_COMPLETE indicates that a set of object identifiers, + corresponding to the set of mechanisms suitable for processing the + input_name, is available in mech_types. + + o GSS_S_BAD_NAME indicates that the input_name was ill-formed and + could not be processed. + + o GSS_S_BAD_NAMETYPE indicates that the input_name parameter + contained an invalid name type or a name type unsupported by the + GSS-API implementation. + + o GSS_S_FAILURE indicates that the requested operation could not be + performed for reasons unspecified at the GSS-API level. + + This routine returns the mechanism set with which the input_name may + be processed. + + Each mechanism returned will recognize at least one element within + the name. It is permissible for this routine to be implemented within + a mechanism-independent GSS-API layer, using the type information + contained within the presented name, and based on registration + information provided by individual mechanism implementations. This + means that the returned mech_types result may indicate that a + particular mechanism will understand a particular name when in fact + it would refuse to accept that name as input to + GSS_Canonicalize_name(), GSS_Init_sec_context(), GSS_Acquire_cred(), + or GSS_Add_cred(), due to some property of the particular name rather + than a property of the name type. Thus, this routine should be used + only as a pre-filter for a call to a subsequent mechanism-specific + routine. + +2.4.14: GSS_Canonicalize_name call + + Inputs: + + o input_name INTERNAL NAME, + + o mech_type OBJECT IDENTIFIER -- must be explicit mechanism, + -- not "default" specifier or identifier of negotiating mechanism + + Outputs: + + o major_status INTEGER, + + + +Linn Standards Track [Page 78] + +RFC 2743 GSS-API January 2000 + + + o minor_status INTEGER, + + o output_name INTERNAL NAME -- caller must release with + -- GSS_Release_name() + + Return major_status codes: + + o GSS_S_COMPLETE indicates that a mechanism-specific reduction of + the input_name, as processed by the mechanism identified by + mech_type, is available in output_name. + + o GSS_S_BAD_MECH indicates that the identified mechanism is + unsupported for this operation; this may correspond either to a + mechanism wholly unsupported by the local GSS-API implementation or + to a negotiating mechanism with which the canonicalization operation + cannot be performed. + + o GSS_S_BAD_NAMETYPE indicates that the input name does not contain + an element with suitable type for processing by the identified + mechanism. + + o GSS_S_BAD_NAME indicates that the input name contains an element + with suitable type for processing by the identified mechanism, but + that this element could not be processed successfully. + + o GSS_S_FAILURE indicates that the requested operation could not be + performed for reasons unspecified at the GSS-API level. + + This routine reduces a GSS-API internal name input_name, which may in + general contain elements corresponding to multiple mechanisms, to a + mechanism-specific Mechanism Name (MN) output_name by applying the + translations corresponding to the mechanism identified by mech_type. + The contents of input_name are unaffected by the + GSS_Canonicalize_name() operation. References to output_name will + remain valid until output_name is released, independent of whether or + not input_name is subsequently released. + +2.4.15: GSS_Export_name call + + Inputs: + + o input_name INTERNAL NAME, -- required to be MN + + Outputs: + + o major_status INTEGER, + + o minor_status INTEGER, + + + +Linn Standards Track [Page 79] + +RFC 2743 GSS-API January 2000 + + + o output_name OCTET STRING -- caller must release + -- with GSS_Release_buffer() + + Return major_status codes: + + o GSS_S_COMPLETE indicates that a flat representation of the input + name is available in output_name. + + o GSS_S_NAME_NOT_MN indicates that the input name contained elements + corresponding to multiple mechanisms, so cannot be exported into a + single-mechanism flat form. + + o GSS_S_BAD_NAME indicates that the input name was an MN, but could + not be processed. + + o GSS_S_BAD_NAMETYPE indicates that the input name was an MN, but + that its type is unsupported by the GSS-API implementation. + + o GSS_S_FAILURE indicates that the requested operation could not be + performed for reasons unspecified at the GSS-API level. + + This routine creates a flat name representation, suitable for + bytewise comparison or for input to GSS_Import_name() in conjunction + with the reserved GSS-API Exported Name Object OID, from a internal- + form Mechanism Name (MN) as emitted, e.g., by GSS_Canonicalize_name() + or GSS_Accept_sec_context(). + + The emitted GSS-API Exported Name Object is self-describing; no + associated parameter-level OID need be emitted by this call. This + flat representation consists of a mechanism-independent wrapper + layer, defined in Section 3.2 of this document, enclosing a + mechanism-defined name representation. + + In all cases, the flat name output by GSS_Export_name() to correspond + to a particular input MN must be invariant over time within a + particular installation. + + The GSS_S_NAME_NOT_MN status code is provided to enable + implementations to reject input names which are not MNs. It is not, + however, required for purposes of conformance to this specification + that all non-MN input names must necessarily be rejected. + +2.4.16: GSS_Duplicate_name call + + Inputs: + + o src_name INTERNAL NAME + + + + +Linn Standards Track [Page 80] + +RFC 2743 GSS-API January 2000 + + + Outputs: + + o major_status INTEGER, + + o minor_status INTEGER, + + o dest_name INTERNAL NAME -- caller must release + -- with GSS_Release_name() + + Return major_status codes: + + o GSS_S_COMPLETE indicates that dest_name references an internal + name object containing the same name as passed to src_name. + + o GSS_S_BAD_NAME indicates that the input name was invalid. + + o GSS_S_FAILURE indicates that the requested operation could not be + performed for reasons unspecified at the GSS-API level. + + This routine takes input internal name src_name, and returns another + reference (dest_name) to that name which can be used even if src_name + is later freed. (Note: This may be implemented by copying or through + use of reference counts.) + +3: Data Structure Definitions for GSS-V2 Usage + + Subsections of this section define, for interoperability and + portability purposes, certain data structures for use with GSS-V2. + +3.1: Mechanism-Independent Token Format + + This section specifies a mechanism-independent level of encapsulating + representation for the initial token of a GSS-API context + establishment sequence, incorporating an identifier of the mechanism + type to be used on that context and enabling tokens to be interpreted + unambiguously at GSS-API peers. Use of this format is required for + initial context establishment tokens of Internet standards-track + GSS-API mechanisms; use in non-initial tokens is optional. + + The encoding format for the token tag is derived from ASN.1 and DER + (per illustrative ASN.1 syntax included later within this + subsection), but its concrete representation is defined directly in + terms of octets rather than at the ASN.1 level in order to facilitate + interoperable implementation without use of general ASN.1 processing + code. The token tag consists of the following elements, in order: + + 1. 0x60 -- Tag for [APPLICATION 0] SEQUENCE; indicates that + -- constructed form, definite length encoding follows. + + + +Linn Standards Track [Page 81] + +RFC 2743 GSS-API January 2000 + + + 2. Token length octets, specifying length of subsequent data + (i.e., the summed lengths of elements 3-5 in this list, and of the + mechanism-defined token object following the tag). This element + comprises a variable number of octets: + + 2a. If the indicated value is less than 128, it shall be + represented in a single octet with bit 8 (high order) set to + "0" and the remaining bits representing the value. + + 2b. If the indicated value is 128 or more, it shall be + represented in two or more octets, with bit 8 of the first + octet set to "1" and the remaining bits of the first octet + specifying the number of additional octets. The subsequent + octets carry the value, 8 bits per octet, most significant + digit first. The minimum number of octets shall be used to + encode the length (i.e., no octets representing leading zeros + shall be included within the length encoding). + + 3. 0x06 -- Tag for OBJECT IDENTIFIER + + 4. Object identifier length -- length (number of octets) of + -- the encoded object identifier contained in element 5, + -- encoded per rules as described in 2a. and 2b. above. + + 5. Object identifier octets -- variable number of octets, + -- encoded per ASN.1 BER rules: + + 5a. The first octet contains the sum of two values: (1) the + top-level object identifier component, multiplied by 40 + (decimal), and (2) the second-level object identifier + component. This special case is the only point within an + object identifier encoding where a single octet represents + contents of more than one component. + + 5b. Subsequent octets, if required, encode successively-lower + components in the represented object identifier. A component's + encoding may span multiple octets, encoding 7 bits per octet + (most significant bits first) and with bit 8 set to "1" on all + but the final octet in the component's encoding. The minimum + number of octets shall be used to encode each component (i.e., + no octets representing leading zeros shall be included within a + component's encoding). + + (Note: In many implementations, elements 3-5 may be stored and + referenced as a contiguous string constant.) + + + + + + +Linn Standards Track [Page 82] + +RFC 2743 GSS-API January 2000 + + + The token tag is immediately followed by a mechanism-defined token + object. Note that no independent size specifier intervenes following + the object identifier value to indicate the size of the mechanism- + defined token object. While ASN.1 usage within mechanism-defined + tokens is permitted, there is no requirement that the mechanism- + specific innerContextToken, innerMsgToken, and sealedUserData data + elements must employ ASN.1 BER/DER encoding conventions. + + The following ASN.1 syntax is included for descriptive purposes only, + to illustrate structural relationships among token and tag objects. + For interoperability purposes, token and tag encoding shall be + performed using the concrete encoding procedures described earlier in + this subsection. + + GSS-API DEFINITIONS ::= + + BEGIN + + MechType ::= OBJECT IDENTIFIER + -- data structure definitions + -- callers must be able to distinguish among + -- InitialContextToken, SubsequentContextToken, + -- PerMsgToken, and SealedMessage data elements + -- based on the usage in which they occur + + InitialContextToken ::= + -- option indication (delegation, etc.) indicated within + -- mechanism-specific token + [APPLICATION 0] IMPLICIT SEQUENCE { + thisMech MechType, + innerContextToken ANY DEFINED BY thisMech + -- contents mechanism-specific + -- ASN.1 structure not required + } + + SubsequentContextToken ::= innerContextToken ANY + -- interpretation based on predecessor InitialContextToken + -- ASN.1 structure not required + + PerMsgToken ::= + -- as emitted by GSS_GetMIC and processed by GSS_VerifyMIC + -- ASN.1 structure not required + innerMsgToken ANY + + SealedMessage ::= + -- as emitted by GSS_Wrap and processed by GSS_Unwrap + -- includes internal, mechanism-defined indicator + -- of whether or not encrypted + + + +Linn Standards Track [Page 83] + +RFC 2743 GSS-API January 2000 + + + -- ASN.1 structure not required + sealedUserData ANY + + END + +3.2: Mechanism-Independent Exported Name Object Format + + This section specifies a mechanism-independent level of encapsulating + representation for names exported via the GSS_Export_name() call, + including an object identifier representing the exporting mechanism. + The format of names encapsulated via this representation shall be + defined within individual mechanism drafts. The Object Identifier + value to indicate names of this type is defined in Section 4.7 of + this document. + + No name type OID is included in this mechanism-independent level of + format definition, since (depending on individual mechanism + specifications) the enclosed name may be implicitly typed or may be + explicitly typed using a means other than OID encoding. + + The bytes within MECH_OID_LEN and NAME_LEN elements are represented + most significant byte first (equivalently, in IP network byte order). + + Length Name Description + + 2 TOK_ID Token Identifier + For exported name objects, this + must be hex 04 01. + 2 MECH_OID_LEN Length of the Mechanism OID + MECH_OID_LEN MECH_OID Mechanism OID, in DER + 4 NAME_LEN Length of name + NAME_LEN NAME Exported name; format defined in + applicable mechanism draft. + + A concrete example of the contents of an exported name object, + derived from the Kerberos Version 5 mechanism, is as follows: + + 04 01 00 0B 06 09 2A 86 48 86 F7 12 01 02 02 hx xx xx xl pp qq ... zz + + 04 01 mandatory token identifier + + 00 0B 2-byte length of the immediately following DER-encoded + ASN.1 value of type OID, most significant octet first + + + + + + + + +Linn Standards Track [Page 84] + +RFC 2743 GSS-API January 2000 + + + 06 09 2A 86 48 86 F7 12 01 02 02 DER-encoded ASN.1 value + of type OID; Kerberos V5 + mechanism OID indicates + Kerberos V5 exported name + + in Detail: 06 Identifier octet (6=OID) + 09 Length octet(s) + 2A 86 48 86 F7 12 01 02 02 Content octet(s) + + hx xx xx xl 4-byte length of the immediately following exported + name blob, most significant octet first + + pp qq ... zz exported name blob of specified length, + bits and bytes specified in the + (Kerberos 5) GSS-API v2 mechanism spec + +4: Name Type Definitions + + This section includes definitions for name types and associated + syntaxes which are defined in a mechanism-independent fashion at the + GSS-API level rather than being defined in individual mechanism + specifications. + +4.1: Host-Based Service Name Form + + This name form shall be represented by the Object Identifier: + + {iso(1) member-body(2) United States(840) mit(113554) infosys(1) + "gssapi(2) generic(1) service_name(4)}. + + The recommended symbolic name for this type is + "GSS_C_NT_HOSTBASED_SERVICE". + + For reasons of compatibility with existing implementations, it is + recommended that this OID be used rather than the alternate value as + included in [RFC-2078]: + + {1(iso), 3(org), 6(dod), 1(internet), 5(security), 6(nametypes), + 2(gss-host-based-services)} + + While it is not recommended that this alternate value be emitted on + output by GSS implementations, it is recommended that it be accepted + on input as equivalent to the recommended value. + + + + + + + + +Linn Standards Track [Page 85] + +RFC 2743 GSS-API January 2000 + + + This name type is used to represent services associated with host + computers. Support for this name form is recommended to mechanism + designers in the interests of portability, but is not mandated by + this specification. This name form is constructed using two elements, + "service" and "hostname", as follows: + + service@hostname + + When a reference to a name of this type is resolved, the "hostname" + may (as an example implementation strategy) be canonicalized by + attempting a DNS lookup and using the fully-qualified domain name + which is returned, or by using the "hostname" as provided if the DNS + lookup fails. The canonicalization operation also maps the host's + name into lower-case characters. + + The "hostname" element may be omitted. If no "@" separator is + included, the entire name is interpreted as the service specifier, + with the "hostname" defaulted to the canonicalized name of the local + host. + + Documents specifying means for GSS integration into a particular + protocol should state either: + + (a) that a specific IANA-registered name associated with that + protocol shall be used for the "service" element (this admits, if + needed, the possibility that a single name can be registered and + shared among a related set of protocols), or + + (b) that the generic name "host" shall be used for the "service" + element, or + + (c) that, for that protocol, fallback in specified order (a, then + b) or (b, then a) shall be applied. + + IANA registration of specific names per (a) should be handled in + accordance with the "Specification Required" assignment policy, + defined by BCP 26, RFC 2434 as follows: "Values and their meaning + must be documented in an RFC or other available reference, in + sufficient detail so that interoperability between independent + implementations is possible." + +4.2: User Name Form + + This name form shall be represented by the Object Identifier {iso(1) + member-body(2) United States(840) mit(113554) infosys(1) gssapi(2) + generic(1) user_name(1)}. The recommended mechanism-independent + symbolic name for this type is "GSS_C_NT_USER_NAME". (Note: the same + + + + +Linn Standards Track [Page 86] + +RFC 2743 GSS-API January 2000 + + + name form and OID is defined within the Kerberos V5 GSS-API + mechanism, but the symbolic name recommended there begins with a + "GSS_KRB5_NT_" prefix.) + + This name type is used to indicate a named user on a local system. + Its syntax and interpretation may be OS-specific. This name form is + constructed as: + + username + +4.3: Machine UID Form + + This name form shall be represented by the Object Identifier {iso(1) + member-body(2) United States(840) mit(113554) infosys(1) gssapi(2) + generic(1) machine_uid_name(2)}. The recommended mechanism- + independent symbolic name for this type is + "GSS_C_NT_MACHINE_UID_NAME". (Note: the same name form and OID is + defined within the Kerberos V5 GSS-API mechanism, but the symbolic + name recommended there begins with a "GSS_KRB5_NT_" prefix.) + + This name type is used to indicate a numeric user identifier + corresponding to a user on a local system. Its interpretation is + OS-specific. The gss_buffer_desc representing a name of this type + should contain a locally-significant user ID, represented in host + byte order. The GSS_Import_name() operation resolves this uid into a + username, which is then treated as the User Name Form. + +4.4: String UID Form + + This name form shall be represented by the Object Identifier {iso(1) + member-body(2) United States(840) mit(113554) infosys(1) gssapi(2) + generic(1) string_uid_name(3)}. The recommended symbolic name for + this type is "GSS_C_NT_STRING_UID_NAME". (Note: the same name form + and OID is defined within the Kerberos V5 GSS-API mechanism, but the + symbolic name recommended there begins with a "GSS_KRB5_NT_" prefix.) + + This name type is used to indicate a string of digits representing + the numeric user identifier of a user on a local system. Its + interpretation is OS-specific. This name type is similar to the + Machine UID Form, except that the buffer contains a string + representing the user ID. + +4.5: Anonymous Nametype + + The following Object Identifier value is provided as a means to + identify anonymous names, and can be compared against in order to + determine, in a mechanism-independent fashion, whether a name refers + to an anonymous principal: + + + +Linn Standards Track [Page 87] + +RFC 2743 GSS-API January 2000 + + + {1(iso), 3(org), 6(dod), 1(internet), 5(security), 6(nametypes), + 3(gss-anonymous-name)} + + The recommended symbolic name corresponding to this definition is + GSS_C_NT_ANONYMOUS. + +4.6: GSS_C_NO_OID + + The recommended symbolic name GSS_C_NO_OID corresponds to a null + input value instead of an actual object identifier. Where specified, + it indicates interpretation of an associated name based on a + mechanism-specific default printable syntax. + +4.7: Exported Name Object + + Name objects of the Mechanism-Independent Exported Name Object type, + as defined in Section 3.2 of this document, will be identified with + the following Object Identifier: + + {1(iso), 3(org), 6(dod), 1(internet), 5(security), 6(nametypes), + 4(gss-api-exported-name)} + + The recommended symbolic name corresponding to this definition is + GSS_C_NT_EXPORT_NAME. + +4.8: GSS_C_NO_NAME + + The recommended symbolic name GSS_C_NO_NAME indicates that no name is + being passed within a particular value of a parameter used for the + purpose of transferring names. Note: GSS_C_NO_NAME is not an actual + name type, and is not represented by an OID; its acceptability in + lieu of an actual name is confined to specific calls + (GSS_Acquire_cred(), GSS_Add_cred(), and GSS_Init_sec_context()) with + usages as identified within this specification. + +5: Mechanism-Specific Example Scenarios + + This section provides illustrative overviews of the use of various + candidate mechanism types to support the GSS-API. These discussions + are intended primarily for readers familiar with specific security + technologies, demonstrating how GSS-API functions can be used and + implemented by candidate underlying mechanisms. They should not be + regarded as constrictive to implementations or as defining the only + means through which GSS-API functions can be realized with a + particular underlying technology, and do not demonstrate all GSS-API + features with each technology. + + + + + +Linn Standards Track [Page 88] + +RFC 2743 GSS-API January 2000 + + +5.1: Kerberos V5, single-TGT + + OS-specific login functions yield a TGT to the local realm Kerberos + server; TGT is placed in a credentials structure for the client. + Client calls GSS_Acquire_cred() to acquire a cred_handle in order to + reference the credentials for use in establishing security contexts. + + Client calls GSS_Init_sec_context(). If the requested service is + located in a different realm, GSS_Init_sec_context() gets the + necessary TGT/key pairs needed to traverse the path from local to + target realm; these data are placed in the owner's TGT cache. After + any needed remote realm resolution, GSS_Init_sec_context() yields a + service ticket to the requested service with a corresponding session + key; these data are stored in conjunction with the context. GSS-API + code sends KRB_TGS_REQ request(s) and receives KRB_TGS_REP + response(s) (in the successful case) or KRB_ERROR. + + Assuming success, GSS_Init_sec_context() builds a Kerberos-formatted + KRB_AP_REQ message, and returns it in output_token. The client sends + the output_token to the service. + + The service passes the received token as the input_token argument to + GSS_Accept_sec_context(), which verifies the authenticator, provides + the service with the client's authenticated name, and returns an + output_context_handle. + + Both parties now hold the session key associated with the service + ticket, and can use this key in subsequent GSS_GetMIC(), + GSS_VerifyMIC(), GSS_Wrap(), and GSS_Unwrap() operations. + +5.2: Kerberos V5, double-TGT + + TGT acquisition as above. + + Note: To avoid unnecessary frequent invocations of error paths when + implementing the GSS-API atop Kerberos V5, it seems appropriate to + represent "single-TGT K-V5" and "double-TGT K-V5" with separate + mech_types, and this discussion makes that assumption. + + Based on the (specified or defaulted) mech_type, + GSS_Init_sec_context() determines that the double-TGT protocol + should be employed for the specified target. GSS_Init_sec_context() + returns GSS_S_CONTINUE_NEEDED major_status, and its returned + output_token contains a request to the service for the service's TGT. + (If a service TGT with suitably long remaining lifetime already + exists in a cache, it may be usable, obviating the need for this + step.) The client passes the output_token to the service. Note: this + scenario illustrates a different use for the GSS_S_CONTINUE_NEEDED + + + +Linn Standards Track [Page 89] + +RFC 2743 GSS-API January 2000 + + + status return facility than for support of mutual authentication; + note that both uses can coexist as successive operations within a + single context establishment operation. + + The service passes the received token as the input_token argument to + GSS_Accept_sec_context(), which recognizes it as a request for TGT. + (Note that current Kerberos V5 defines no intra-protocol mechanism to + represent such a request.) GSS_Accept_sec_context() returns + GSS_S_CONTINUE_NEEDED major_status and provides the service's TGT in + its output_token. The service sends the output_token to the client. + + The client passes the received token as the input_token argument to a + continuation of GSS_Init_sec_context(). GSS_Init_sec_context() caches + the received service TGT and uses it as part of a service ticket + request to the Kerberos authentication server, storing the returned + service ticket and session key in conjunction with the context. + GSS_Init_sec_context() builds a Kerberos-formatted authenticator, and + returns it in output_token along with GSS_S_COMPLETE return + major_status. The client sends the output_token to the service. + + Service passes the received token as the input_token argument to a + continuation call to GSS_Accept_sec_context(). + GSS_Accept_sec_context() verifies the authenticator, provides the + service with the client's authenticated name, and returns + major_status GSS_S_COMPLETE. + + GSS_GetMIC(), GSS_VerifyMIC(), GSS_Wrap(), and GSS_Unwrap() as + above. + +5.3: X.509 Authentication Framework + + This example illustrates use of the GSS-API in conjunction with + public-key mechanisms, consistent with the X.509 Directory + Authentication Framework. + + The GSS_Acquire_cred() call establishes a credentials structure, + making the client's private key accessible for use on behalf of the + client. + + The client calls GSS_Init_sec_context(), which interrogates the + Directory to acquire (and validate) a chain of public-key + certificates, thereby collecting the public key of the service. The + certificate validation operation determines that suitable integrity + checks were applied by trusted authorities and that those + certificates have not expired. GSS_Init_sec_context() generates a + secret key for use in per-message protection operations on the + context, and enciphers that secret key under the service's public + key. + + + +Linn Standards Track [Page 90] + +RFC 2743 GSS-API January 2000 + + + The enciphered secret key, along with an authenticator quantity + signed with the client's private key, is included in the output_token + from GSS_Init_sec_context(). The output_token also carries a + certification path, consisting of a certificate chain leading from + the service to the client; a variant approach would defer this path + resolution to be performed by the service instead of being asserted + by the client. The client application sends the output_token to the + service. + + The service passes the received token as the input_token argument to + GSS_Accept_sec_context(). GSS_Accept_sec_context() validates the + certification path, and as a result determines a certified binding + between the client's distinguished name and the client's public key. + Given that public key, GSS_Accept_sec_context() can process the + input_token's authenticator quantity and verify that the client's + private key was used to sign the input_token. At this point, the + client is authenticated to the service. The service uses its private + key to decipher the enciphered secret key provided to it for per- + message protection operations on the context. + + The client calls GSS_GetMIC() or GSS_Wrap() on a data message, which + causes per-message authentication, integrity, and (optional) + confidentiality facilities to be applied to that message. The service + uses the context's shared secret key to perform corresponding + GSS_VerifyMIC() and GSS_Unwrap() calls. + +6: Security Considerations + + This document specifies a service interface for security facilities + and services; as such, security considerations are considered + throughout the specification. Nonetheless, it is appropriate to + summarize certain specific points relevant to GSS-API implementors + and calling applications. Usage of the GSS-API interface does not in + itself provide security services or assurance; instead, these + attributes are dependent on the underlying mechanism(s) which support + a GSS-API implementation. Callers must be attentive to the requests + made to GSS-API calls and to the status indicators returned by GSS- + API, as these specify the security service characteristics which + GSS-API will provide. When the interprocess context transfer + facility is used, appropriate local controls should be applied to + constrain access to interprocess tokens and to the sensitive data + which they contain. + + + + + + + + + +Linn Standards Track [Page 91] + +RFC 2743 GSS-API January 2000 + + +7: Related Activities + + In order to implement the GSS-API atop existing, emerging, and future + security mechanisms: + + object identifiers must be assigned to candidate GSS-API + mechanisms and the name types which they support + + concrete data element formats and processing procedures must be + defined for candidate mechanisms + + Calling applications must implement formatting conventions which will + enable them to distinguish GSS-API tokens from other data carried in + their application protocols. + + Concrete language bindings are required for the programming + environments in which the GSS-API is to be employed, as [RFC-1509] + defines for the C programming language and GSS-V1. C Language + bindings for GSS-V2 are defined in [RFC-2744]. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +Linn Standards Track [Page 92] + +RFC 2743 GSS-API January 2000 + + +8: Referenced Documents + + [ISO-7498-2] International Standard ISO 7498-2-1988(E), Security + Architecture. + + [ISOIEC-8824] ISO/IEC 8824, "Specification of Abstract Syntax + Notation One (ASN.1)". + + [ISOIEC-8825] ISO/IEC 8825, "Specification of Basic Encoding Rules + for Abstract Syntax Notation One (ASN.1)".) + + [RFC-1507]: Kaufman, C., "DASS: Distributed Authentication Security + Service", RFC 1507, September 1993. + + [RFC-1508]: Linn, J., "Generic Security Service Application Program + Interface", RFC 1508, September 1993. + + [RFC-1509]: Wray, J., "Generic Security Service API: C-bindings", + RFC 1509, September 1993. + + [RFC-1964]: Linn, J., "The Kerberos Version 5 GSS-API Mechanism", + RFC 1964, June 1996. + + [RFC-2025]: Adams, C., "The Simple Public-Key GSS-API Mechanism + (SPKM)", RFC 2025, October 1996. + + [RFC-2078]: Linn, J., "Generic Security Service Application Program + Interface, Version 2", RFC 2078, January 1997. + + [RFC-2203]: Eisler, M., Chiu, A. and L. Ling, "RPCSEC_GSS Protocol + Specification", RFC 2203, September 1997. + + [RFC-2744]: Wray, J., "Generic Security Service API Version 2 : + C-bindings", RFC 2744, January 2000. + + + + + + + + + + + + + + + + + +Linn Standards Track [Page 93] + +RFC 2743 GSS-API January 2000 + + +APPENDIX A + +MECHANISM DESIGN CONSTRAINTS + + The following constraints on GSS-API mechanism designs are adopted in + response to observed caller protocol requirements, and adherence + thereto is anticipated in subsequent descriptions of GSS-API + mechanisms to be documented in standards-track Internet + specifications. + + It is strongly recommended that mechanisms offering per-message + protection services also offer at least one of the replay detection + and sequencing services, as mechanisms offering neither of the latter + will fail to satisfy recognized requirements of certain candidate + caller protocols. + +APPENDIX B + +COMPATIBILITY WITH GSS-V1 + + It is the intent of this document to define an interface and + procedures which preserve compatibility between GSS-V1 [RFC-1508] + callers and GSS-V2 providers. All calls defined in GSS-V1 are + preserved, and it has been a goal that GSS-V1 callers should be able + to operate atop GSS-V2 provider implementations. Certain detailed + changes, summarized in this section, have been made in order to + resolve omissions identified in GSS-V1. + + The following GSS-V1 constructs, while supported within GSS-V2, are + deprecated: + + Names for per-message processing routines: GSS_Seal() deprecated + in favor of GSS_Wrap(); GSS_Sign() deprecated in favor of + GSS_GetMIC(); GSS_Unseal() deprecated in favor of GSS_Unwrap(); + GSS_Verify() deprecated in favor of GSS_VerifyMIC(). + + GSS_Delete_sec_context() facility for context_token usage, + allowing mechanisms to signal context deletion, is retained for + compatibility with GSS-V1. For current usage, it is recommended + that both peers to a context invoke GSS_Delete_sec_context() + independently, passing a null output_context_token buffer to + indicate that no context_token is required. Implementations of + GSS_Delete_sec_context() should delete relevant locally-stored + context information. + + This GSS-V2 specification adds the following calls which are not + present in GSS-V1: + + + + +Linn Standards Track [Page 94] + +RFC 2743 GSS-API January 2000 + + + Credential management calls: GSS_Add_cred(), + GSS_Inquire_cred_by_mech(). + + Context-level calls: GSS_Inquire_context(), GSS_Wrap_size_limit(), + GSS_Export_sec_context(), GSS_Import_sec_context(). + + Per-message calls: No new calls. Existing calls have been + renamed. + + Support calls: GSS_Create_empty_OID_set(), + GSS_Add_OID_set_member(), GSS_Test_OID_set_member(), + GSS_Inquire_names_for_mech(), GSS_Inquire_mechs_for_name(), + GSS_Canonicalize_name(), GSS_Export_name(), GSS_Duplicate_name(). + + This GSS-V2 specification introduces three new facilities applicable + to security contexts, indicated using the following context state + values which are not present in GSS-V1: + + anon_state, set TRUE to indicate that a context's initiator is + anonymous from the viewpoint of the target; Section 1.2.5 of this + specification provides a summary description of the GSS-V2 + anonymity support facility, support and use of which is optional. + + prot_ready_state, set TRUE to indicate that a context may be used + for per-message protection before final completion of context + establishment; Section 1.2.7 of this specification provides a + summary description of the GSS-V2 facility enabling mechanisms to + selectively permit per-message protection during context + establishment, support and use of which is optional. + + trans_state, set TRUE to indicate that a context is transferable + to another process using the GSS-V2 GSS_Export_sec_context() + facility. + + These state values are represented (at the C bindings level) in + positions within a bit vector which are unused in GSS-V1, and may be + safely ignored by GSS-V1 callers. + + New conf_req_flag and integ_req_flag inputs are defined for + GSS_Init_sec_context(), primarily to provide information to + negotiating mechanisms. This introduces a compatibility issue with + GSS-V1 callers, discussed in section 2.2.1 of this specification. + + + + + + + + + +Linn Standards Track [Page 95] + +RFC 2743 GSS-API January 2000 + + + Relative to GSS-V1, GSS-V2 provides additional guidance to GSS-API + implementors in the following areas: implementation robustness, + credential management, behavior in multi-mechanism configurations, + naming support, and inclusion of optional sequencing services. The + token tagging facility as defined in GSS-V2, Section 3.1, is now + described directly in terms of octets to facilitate interoperable + implementation without general ASN.1 processing code; the + corresponding ASN.1 syntax, included for descriptive purposes, is + unchanged from that in GSS-V1. For use in conjunction with added + naming support facilities, a new Exported Name Object construct is + added. Additional name types are introduced in Section 4. + + This GSS-V2 specification adds the following major_status values + which are not defined in GSS-V1: + + GSS_S_BAD_QOP unsupported QOP value + GSS_S_UNAUTHORIZED operation unauthorized + GSS_S_UNAVAILABLE operation unavailable + GSS_S_DUPLICATE_ELEMENT duplicate credential element + requested + GSS_S_NAME_NOT_MN name contains multi-mechanism + elements + GSS_S_GAP_TOKEN skipped predecessor token(s) + detected + + Of these added status codes, only two values are defined to be + returnable by calls existing in GSS-V1: GSS_S_BAD_QOP (returnable by + GSS_GetMIC() and GSS_Wrap()), and GSS_S_GAP_TOKEN (returnable by + GSS_VerifyMIC() and GSS_Unwrap()). + + Additionally, GSS-V2 descriptions of certain calls present in GSS-V1 + have been updated to allow return of additional major_status values + from the set as defined in GSS-V1: GSS_Inquire_cred() has + GSS_S_DEFECTIVE_CREDENTIAL and GSS_S_CREDENTIALS_EXPIRED defined as + returnable, GSS_Init_sec_context() has GSS_S_OLD_TOKEN, + GSS_S_DUPLICATE_TOKEN, and GSS_S_BAD_MECH defined as returnable, and + GSS_Accept_sec_context() has GSS_S_BAD_MECH defined as returnable. + +APPENDIX C + +CHANGES RELATIVE TO RFC-2078 + + This document incorporates a number of changes relative to RFC-2078, + made primarily in response to implementation experience, for purposes + of alignment with the GSS-V2 C language bindings document, and to add + informative clarification. This section summarizes technical changes + incorporated. + + + + +Linn Standards Track [Page 96] + +RFC 2743 GSS-API January 2000 + + + General: + + Clarified usage of object release routines, and incorporated + statement that some may be omitted within certain operating + environments. + + Removed GSS_Release_OID, GSS_OID_to_str(), and GSS_Str_to_OID() + routines. + + Clarified circumstances under which zero-length tokens may validly + exist as inputs and outputs to/from GSS-API calls. + + Added GSS_S_BAD_MIC status code as alias for GSS_S_BAD_SIG. + + For GSS_Display_status(), deferred to language bindings the choice + of whether to return multiple status values in parallel or via + iteration, and added commentary deprecating return of + GSS_S_CONTINUE_NEEDED. + + Adapted and incorporated clarifying material on optional service + support, delegation, and interprocess context transfer from C + bindings document. + + Added and updated references to related documents, and to current + status of cited Kerberos mechanism OID. + + Added general statement about GSS-API calls having no side effects + visible at the GSS-API level. + + Context-related (including per-message protection issues): + + Clarified GSS_Delete_sec_context() usage for partially-established + contexts. + + Added clarification on GSS_Export_sec_context() and + GSS_Import_sec_context() behavior and context usage following an + export-import sequence. + + Added informatory conf_req_flag, integ_req_flag inputs to + GSS_Init_sec_context(). (Note: this facility introduces a + backward incompatibility with GSS-V1 callers, discussed in Section + 2.2.1; this implication was recognized and accepted in working + group discussion.) + + Stated that GSS_S_FAILURE is to be returned if + GSS_Init_sec_context() or GSS_Accept_sec_context() is passed the + handle of a context which is already fully established. + + + + +Linn Standards Track [Page 97] + +RFC 2743 GSS-API January 2000 + + + Re GSS_Inquire_sec_context(), stated that src_name and targ_name + are not returned until GSS_S_COMPLETE status is reached; removed + use of GSS_S_CONTEXT_EXPIRED status code (replacing with EXPIRED + lifetime return value); stated requirement to retain inquirable + data until context released by caller; added result value + indicating whether or not context is fully open. + + Added discussion of interoperability conditions for mechanisms + permitting optional support of QOPs. Removed reference to + structured QOP elements in GSS_Verify_MIC(). + + Added discussion of use of GSS_S_DUPLICATE_TOKEN status to + indicate reflected per-message tokens. + + Clarified use of informational sequencing codes from per-message + protection calls in conjunction with GSS_S_COMPLETE and + GSS_S_FAILURE major_status returns, adjusting status code + descriptions accordingly. + + Added specific statements about impact of GSS_GetMIC() and + GSS_Wrap() failures on context state information, and generalized + existing statements about impact of processing failures on + received per-message tokens. + + For GSS_Init_sec_context() and GSS_Accept_sec_context(), permitted + returned mech_type to be valid before GSS_S_COMPLETE, recognizing + that the value may change on successive continuation calls in the + negotiated mechanism case. + + Deleted GSS_S_CONTEXT_EXPIRED status from + GSS_Import_sec_context(). + + Added conf_req_flag input to GSS_Wrap_size_limit(). + + Stated requirement for mechanisms' support of per-message + protection services to be usable concurrently in both directions + on a context. + + Credential-related: + + For GSS_Acquire_cred() and GSS_Add_cred(), aligned with C bindings + statement of likely non-support for INITIATE or BOTH credentials + if input name is neither empty nor a name resulting from applying + GSS_Inquire_cred() against the default credential. Further, + stated that an explicit name returned by GSS_Inquire_context() + should also be accepted. Added commentary about potentially + time-variant results of default resolution and attendant + implications. Aligned with C bindings re behavior when + + + +Linn Standards Track [Page 98] + +RFC 2743 GSS-API January 2000 + + + GSS_C_NO_NAME provided for desired_name. In GSS_Acquire_cred(), + stated that NULL, rather than empty OID set, should be used for + desired_mechs in order to request default mechanism set. + + Added GSS_S_CREDENTIALS_EXPIRED as returnable major_status for + GSS_Acquire_cred(), GSS_Add_cred(), also specifying GSS_S_NO_CRED + as appropriate return for temporary, user-fixable credential + unavailability. GSS_Acquire_cred() and GSS_Add_cred() are also to + return GSS_S_NO_CRED if an authorization failure is encountered + upon credential acquisition. + + Removed GSS_S_CREDENTIALS_EXPIRED status return from per-message + protection, GSS_Context_time(), and GSS_Inquire_context() calls. + + For GSS_Add_cred(), aligned with C bindings' description of + behavior when addition of elements to the default credential is + requested. + + Upgraded recommended default credential resolution algorithm to + status of requirement for initiator credentials. + + For GSS_Release_cred(), GSS_Inquire_cred(), and + GSS_Inquire_cred_by_mech(), clarified behavior for input + GSS_C_NO_CREDENTIAL. + + Name-related: + + Aligned GSS_Inquire_mechs_for_name() description with C bindings. + + Removed GSS_S_BAD_NAMETYPE status return from + GSS_Duplicate_name(), GSS_Display_name(); constrained its + applicability for GSS_Compare_name(). + + Aligned with C bindings statement re GSS_Import_name() behavior + with GSS_C_NO_OID input name type, and stated that GSS-V2 + mechanism specifications are to define processing procedures + applicable to their mechanisms. Also clarified GSS_C_NO_OID usage + with GSS_Display_name(). + + Downgraded reference to name canonicalization via DNS lookup to an + example. + + For GSS_Canonicalize_name(), stated that neither negotiated + mechanisms nor the default mechanism are supported input + mech_types for this operation, and specified GSS_S_BAD_MECH status + to be returned in this case. Clarified that the + GSS_Canonicalize_name() operation is non-destructive to its input + name. + + + +Linn Standards Track [Page 99] + +RFC 2743 GSS-API January 2000 + + + Clarified semantics of GSS_C_NT_USER_NAME name type. + + Added descriptions of additional name types. Also added + discussion of GSS_C_NO_NAME and its constrained usage with + specific GSS calls. + + Adapted and incorporated C bindings discussion about name + comparisons with exported name objects. + + Added recommendation to mechanism designers for support of host- + based service name type, deferring any requirement statement to + individual mechanism specifications. Added discussion of host- + based service's service name element and proposed approach for + IANA registration policy therefor. + + Clarified byte ordering within exported name object. Stated that + GSS_S_BAD_MECH is to be returned if, in the course of attempted + import of an exported name object, the name object's enclosed + mechanism type is unrecognized or unsupported. + + Stated that mechanisms may optionally accept GSS_C_NO_NAME as an + input target name to GSS_Init_sec_context(), with comment that + such support is unlikely within mechanisms predating GSS-V2, + Update 1. + +AUTHOR'S ADDRESS + + John Linn + RSA Laboratories + 20 Crosby Drive + Bedford, MA 01730 USA + + Phone: +1 781.687.7817 + EMail: jlinn@rsasecurity.com + + + + + + + + + + + + + + + + + +Linn Standards Track [Page 100] + +RFC 2743 GSS-API January 2000 + + +Full Copyright Statement + + Copyright (C) The Internet Society (2000). All Rights Reserved. + + This document and translations of it may be copied and furnished to + others, and derivative works that comment on or otherwise explain it + or assist in its implementation may be prepared, copied, published + and distributed, in whole or in part, without restriction of any + kind, provided that the above copyright notice and this paragraph are + included on all such copies and derivative works. However, this + document itself may not be modified in any way, such as by removing + the copyright notice or references to the Internet Society or other + Internet organizations, except as needed for the purpose of + developing Internet standards in which case the procedures for + copyrights defined in the Internet Standards process must be + followed, or as required to translate it into languages other than + English. + + The limited permissions granted above are perpetual and will not be + revoked by the Internet Society or its successors or assigns. + + This document and the information contained herein is provided on an + "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING + TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING + BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION + HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF + MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. + +Acknowledgement + + Funding for the RFC Editor function is currently provided by the + Internet Society. + + + + + + + + + + + + + + + + + + + +Linn Standards Track [Page 101] + |