diff options
Diffstat (limited to 'third_party/heimdal/doc/standardisation/rfc2078.txt')
| -rw-r--r-- | third_party/heimdal/doc/standardisation/rfc2078.txt | 4763 |
1 files changed, 4763 insertions, 0 deletions
diff --git a/third_party/heimdal/doc/standardisation/rfc2078.txt b/third_party/heimdal/doc/standardisation/rfc2078.txt new file mode 100644 index 00000000000..1dd1e4aebd2 --- /dev/null +++ b/third_party/heimdal/doc/standardisation/rfc2078.txt @@ -0,0 +1,4763 @@ + + + + + + +Network Working Group J. Linn +Request for Comments: 2078 OpenVision Technologies +Category: Standards Track January 1997 +Obsoletes: 1508 + + + Generic Security Service Application Program Interface, Version 2 + +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. + +Abstract + + The Generic Security Service Application Program Interface (GSS-API), + as defined in RFC-1508, 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 revises RFC-1508, 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. + +Table of Contents + + 1: GSS-API Characteristics and Concepts.......................... 3 + 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 + + + +Linn Standards Track [Page 1] + +RFC 2078 GSS-API January 1997 + + + 1.1.2: Tokens.................................................... 9 + 1.1.3: Security Contexts........................................ 10 + 1.1.4: Mechanism Types.......................................... 11 + 1.1.5: Naming................................................... 12 + 1.1.6: Channel Bindings......................................... 14 + 1.2: GSS-API Features and Issues................................ 15 + 1.2.1: Status Reporting......................................... 15 + 1.2.2: Per-Message Security Service Availability................. 17 + 1.2.3: Per-Message Replay Detection and Sequencing............... 18 + 1.2.4: Quality of Protection.................................... 20 + 1.2.5: Anonymity Support......................................... 21 + 1.2.6: Initialization............................................ 22 + 1.2.7: Per-Message Protection During Context Establishment....... 22 + 1.2.8: Implementation Robustness................................. 23 + 2: Interface Descriptions....................................... 23 + 2.1: Credential management calls................................ 25 + 2.1.1: GSS_Acquire_cred call.................................... 26 + 2.1.2: GSS_Release_cred call.................................... 28 + 2.1.3: GSS_Inquire_cred call.................................... 29 + 2.1.4: GSS_Add_cred call........................................ 31 + 2.1.5: GSS_Inquire_cred_by_mech call............................ 33 + 2.2: Context-level calls........................................ 34 + 2.2.1: GSS_Init_sec_context call................................ 34 + 2.2.2: GSS_Accept_sec_context call.............................. 40 + 2.2.3: GSS_Delete_sec_context call.............................. 44 + 2.2.4: GSS_Process_context_token call........................... 46 + 2.2.5: GSS_Context_time call.................................... 47 + 2.2.6: GSS_Inquire_context call................................. 47 + 2.2.7: GSS_Wrap_size_limit call................................. 49 + 2.2.8: GSS_Export_sec_context call.............................. 50 + 2.2.9: GSS_Import_sec_context call.............................. 52 + 2.3: Per-message calls.......................................... 53 + 2.3.1: GSS_GetMIC call.......................................... 54 + 2.3.2: GSS_VerifyMIC call....................................... 55 + 2.3.3: GSS_Wrap call............................................ 56 + 2.3.4: GSS_Unwrap call.......................................... 58 + 2.4: Support calls.............................................. 59 + 2.4.1: GSS_Display_status call.................................. 60 + 2.4.2: GSS_Indicate_mechs call.................................. 60 + 2.4.3: GSS_Compare_name call.................................... 61 + 2.4.4: GSS_Display_name call.................................... 62 + 2.4.5: GSS_Import_name call..................................... 63 + 2.4.6: GSS_Release_name call.................................... 64 + 2.4.7: GSS_Release_buffer call.................................. 65 + 2.4.8: GSS_Release_OID_set call................................. 65 + 2.4.9: GSS_Create_empty_OID_set call............................ 66 + 2.4.10: GSS_Add_OID_set_member call.............................. 67 + 2.4.11: GSS_Test_OID_set_member call............................. 67 + + + +Linn Standards Track [Page 2] + +RFC 2078 GSS-API January 1997 + + + 2.4.12: GSS_Release_OID call..................................... 68 + 2.4.13: GSS_OID_to_str call...................................... 68 + 2.4.14: GSS_Str_to_OID call...................................... 69 + 2.4.15: GSS_Inquire_names_for_mech call.......................... 69 + 2.4.16: GSS_Inquire_mechs_for_name call.......................... 70 + 2.4.17: GSS_Canonicalize_name call............................... 71 + 2.4.18: GSS_Export_name call..................................... 72 + 2.4.19: GSS_Duplicate_name call.................................. 73 + 3: Data Structure Definitions for GSS-V2 Usage................... 73 + 3.1: Mechanism-Independent Token Format.......................... 74 + 3.2: Mechanism-Independent Exported Name Object Format........... 77 + 4: Name Type Definitions......................................... 77 + 4.1: Host-Based Service Name Form................................ 77 + 4.2: User Name Form.............................................. 78 + 4.3: Machine UID Form............................................ 78 + 4.4: String UID Form............................................. 79 + 5: Mechanism-Specific Example Scenarios......................... 79 + 5.1: Kerberos V5, single-TGT..................................... 79 + 5.2: Kerberos V5, double-TGT..................................... 80 + 5.3: X.509 Authentication Framework............................. 81 + 6: Security Considerations...................................... 82 + 7: Related Activities........................................... 82 + Appendix A: Mechanism Design Constraints......................... 83 + Appendix B: Compatibility with GSS-V1............................ 83 + +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 (This + security service definition, and other definitions used in this + document, corresponds to that provided in International Standard ISO + 7498-2-1988(E), Security Architecture.) (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. When establishing a + + + +Linn Standards Track [Page 3] + +RFC 2078 GSS-API January 1997 + + + 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 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 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 + 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 + + + +Linn Standards Track [Page 4] + +RFC 2078 GSS-API January 1997 + + + 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. + + 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 can be implemented by secret-key technologies (e.g., + Kerberos) or public-key approaches (e.g., X.509). + + 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 (e.g., + Remote Procedure Call (RPC)) may be interposed between + applications which call that protocol and the GSS-API, 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 + + + +Linn Standards Track [Page 5] + +RFC 2078 GSS-API January 1997 + + + 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 + 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 + + + +Linn Standards Track [Page 6] + +RFC 2078 GSS-API January 1997 + + + 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. + + 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 + + + + +Linn Standards Track [Page 7] + +RFC 2078 GSS-API January 1997 + + +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. While individual + GSS-API implementations are free to determine such default behavior + as appropriate to the mechanism, the following default behavior by + these routines is recommended for portability: + + 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 + + (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 + + + + +Linn Standards Track [Page 8] + +RFC 2078 GSS-API January 1997 + + + (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 ones + 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 + 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 of this + document provides, for designers of GSS-API support 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. 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. + 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. + + + + +Linn Standards Track [Page 9] + +RFC 2078 GSS-API January 1997 + + + 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), + + - 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 support primitives 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 + + + +Linn Standards Track [Page 10] + +RFC 2078 GSS-API January 1997 + + + 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 + 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. + +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. + + 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): + + 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 + + + + +Linn Standards Track [Page 11] + +RFC 2078 GSS-API January 1997 + + + explicit negotiation between GSS-API callers in advance of + security context setup + + When transferred between GSS-API peers, mech_type specifiers (per + Section 3, represented as Object Identifiers (OIDs)) serve to qualify + the interpretation of associated tokens. (The structure and encoding + of Object Identifiers is defined in ISO/IEC 8824, "Specification of + Abstract Syntax Notation One (ASN.1)" and in ISO/IEC 8825, + "Specification of Basic Encoding Rules for Abstract Syntax Notation + One (ASN.1)".) Use of hierarchically structured OIDs serves to + preclude ambiguous interpretation of mech_type specifiers. The OID + representing the DASS MechType, for example, is 1.3.12.2.1011.7.5, + and that of the Kerberos V5 mechanism, once advanced to the level of + Proposed Standard, will be 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 + 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 + + + +Linn Standards Track [Page 12] + +RFC 2078 GSS-API January 1997 + + + 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. + + The GSS_Canonicalize_name() and GSS_Export_name() calls enable + callers to acquire and process Exported Name Objects, canonicalized + and translated in accordance with the procedures of a particular + GSS-API mechanism. Exported Name Objects can, in turn, be input to + GSS_Import_name(), yielding equivalent MNs. These facilities are + designed specifically to enable efficient storage and comparison of + names (e.g., for use in access control lists). + + + + + + + +Linn Standards Track [Page 13] + +RFC 2078 GSS-API January 1997 + + + The following diagram illustrates the intended dataflow among name- + related GSS-API processing routines. + + 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 + + + +Linn Standards Track [Page 14] + +RFC 2078 GSS-API January 1997 + + + 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 + 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 + + 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. + + + + + + + + + + + +Linn Standards Track [Page 15] + +RFC 2078 GSS-API January 1997 + + +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_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. + + 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 + + + +Linn Standards Track [Page 16] + +RFC 2078 GSS-API January 1997 + + + with sequences of continuation calls to GSS_Init_sec_context() and + GSS_Accept_sec_context(). The same mechanism 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.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 + + 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. + + + + + + + + + + +Linn Standards Track [Page 17] + +RFC 2078 GSS-API January 1997 + + + 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 mech_type, 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 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 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. + + + + + + +Linn Standards Track [Page 18] + +RFC 2078 GSS-API January 1997 + + + 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. + + 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 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. + + 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.] + + + + + + + + +Linn Standards Track [Page 19] + +RFC 2078 GSS-API January 1997 + + + 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 + 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 + + + +Linn Standards Track [Page 20] + +RFC 2078 GSS-API January 1997 + + + 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. + +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. + + 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: + + {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. + + 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. + + + + +Linn Standards Track [Page 21] + +RFC 2078 GSS-API January 1997 + + + 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. + +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. + + This 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 + + + +Linn Standards Track [Page 22] + +RFC 2078 GSS-API January 1997 + + + 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 + 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. + + If a token is presented for processing on a GSS-API security context + and that token is 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. + +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 + + + +Linn Standards Track [Page 23] + +RFC 2078 GSS-API January 1997 + + + 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 + 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 + + + + + + + + + + + +Linn Standards Track [Page 24] + +RFC 2078 GSS-API January 1997 + + + 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 printable name + GSS_Release_OID free storage of OID 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_OID_to_str display OID as string + GSS_Str_to_OID construct OID from string + GSS_Inquire_names_for_mech indicate name types supported by + 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 + + + +Linn Standards Track [Page 25] + +RFC 2078 GSS-API January 1997 + + + 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,-empty set requests + system-selected default + + 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, + + o actual_mechs SET OF OBJECT IDENTIFIER, + + 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. + + + + + + +Linn Standards Track [Page 26] + +RFC 2078 GSS-API January 1997 + + + 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_FAILURE indicates that credential establishment failed + for reasons unspecified at the GSS-API level, including lack + of authorization to establish and use credentials associated + with the identity named in the input desired_name argument. + + 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 for desired_name, signifying a + request for credentials corresponding to a principal identity + selected by default for the caller. The procedures used by GSS-API + implementations to select the appropriate principal identity in + response to such a request are local matters. 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. + + 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 + 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 + + + +Linn Standards Track [Page 27] + +RFC 2078 GSS-API January 1997 + + + 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 - NULL specifies that + the credential elements used when default credential behavior + is requested 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. + + 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. + + + + + +Linn Standards Track [Page 28] + +RFC 2078 GSS-API January 1997 + + + 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 -NULL specifies that the + credential elements used when default credential behavior is + requested are to be queried + + Outputs: + + o major_status INTEGER, + + o minor_status INTEGER, + + o cred_name INTERNAL 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 + + 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. + + + +Linn Standards Track [Page 29] + +RFC 2078 GSS-API January 1997 + + + 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". + + 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(). + + + + + + + + + + + +Linn Standards Track [Page 30] + +RFC 2078 GSS-API January 1997 + + +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, or NULL to append elements to the set + which are applied for the caller when default credential + behavior is specified. + + o desired_name INTERNAL NAME - NULL requests locally-determined + default + + 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. + + o actual_mechs SET OF OBJECT IDENTIFIER, + + o initiator_time_rec INTEGER - in seconds, or reserved value for + INDEFINITE + + o acceptor_time_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 -- full set of mechanisms + supported by resulting credential. + + + + + +Linn Standards Track [Page 31] + +RFC 2078 GSS-API January 1997 + + + 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. + + o GSS_S_FAILURE indicates that the operation failed for + reasons unspecified at the GSS-API level, including lack of + authorization to establish or use credentials representing + the requested identity. + + 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. + + 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. + + + + + +Linn Standards Track [Page 32] + +RFC 2078 GSS-API January 1997 + + +2.1.5: GSS_Inquire_cred_by_mech call + + Inputs: + + o cred_handle CREDENTIAL HANDLE -- NULL specifies that the + credential elements used when default credential behavior is + requested are to be 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 + + 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 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. + + + +Linn Standards Track [Page 33] + +RFC 2078 GSS-API January 1997 + + + 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. + 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 specifies "none assigned + yet" + + + +Linn Standards Track [Page 34] + +RFC 2078 GSS-API January 1997 + + + 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 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, + + o output_context_handle CONTEXT HANDLE, + + o mech_type OBJECT IDENTIFIER, -actual mechanism always + indicated, never NULL + + o output_token OCTET STRING, -NULL or token to pass to context + target + + 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 + + + +Linn Standards Track [Page 35] + +RFC 2078 GSS-API January 1997 + + + 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 + to a continuation call to GSS_Init_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 + claimant_cred_handle failed, preventing further processing from + being performed using that credential structure. + + o GSS_S_BAD_SIG 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, or because the caller lacks authorization to access the + referenced credentials. + + 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. + + + +Linn Standards Track [Page 36] + +RFC 2078 GSS-API January 1997 + + + 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. + + 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 one + (or, for the case of a multi-step exchange, more than one) + output_token suitable for use by the target within the selected + mech_type's protocol. 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. 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 + + + +Linn Standards Track [Page 37] + +RFC 2078 GSS-API January 1997 + + + sequences modeled by the GSS_S_CONTINUE_NEEDED facility will require + access to credentials at different points in the context + establishment sequence. + + The input_context_handle argument is 0, 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 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. + + 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. + + 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 38] + +RFC 2078 GSS-API January 1997 + + + 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. + + 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. + + 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, is valid only along with major_status + GSS_S_COMPLETE, and will never indicate the value for "default". + Note that, for the case of certain 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. + + 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 + + + +Linn Standards Track [Page 39] + +RFC 2078 GSS-API January 1997 + + + 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. + +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 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 + + + + +Linn Standards Track [Page 40] + +RFC 2078 GSS-API January 1997 + + + o mech_type OBJECT IDENTIFIER, + + o output_context_handle CONTEXT HANDLE, + + 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, + + o lifetime_rec INTEGER, - in seconds, or reserved value for + INDEFINITE + + o delegated_cred_handle CREDENTIAL HANDLE, + + o output_token OCTET STRING -NULL or token to pass to context + initiator + + 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. + + + + +Linn Standards Track [Page 41] + +RFC 2078 GSS-API January 1997 + + + 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 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. + + 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, or because the caller lacks authorization to access the + referenced credentials. + + 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. + + + + + +Linn Standards Track [Page 42] + +RFC 2078 GSS-API January 1997 + + + 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. + + The input_context_handle argument is 0, 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. + + 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. + + + + + + + + + + + +Linn Standards Track [Page 43] + +RFC 2078 GSS-API January 1997 + + + 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 mech_type return value indicates the specific mechanism employed + on the context, is valid only along with major_status GSS_S_COMPLETE, + and will never indicate the value for "default". + + 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, + + + + +Linn Standards Track [Page 44] + +RFC 2078 GSS-API January 1997 + + + 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. + + 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 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. + + This call can be made by either peer in a security context, to flush + context-specific information. 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. + + + + + + + +Linn Standards Track [Page 45] + +RFC 2078 GSS-API January 1997 + + +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, + + 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. + + + + + + + + + + + +Linn Standards Track [Page 46] + +RFC 2078 GSS-API January 1997 + + +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. + + o GSS_S_CONTEXT_EXPIRED indicates that data items related to the + referenced context have expired. + + o GSS_S_CREDENTIALS_EXPIRED indicates that the context is + recognized, but that its associated credentials 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, + + + + +Linn Standards Track [Page 47] + +RFC 2078 GSS-API January 1997 + + + o src_name INTERNAL NAME, -- name of context initiator, + -- guaranteed to be MN + + o targ_name INTERNAL NAME, -- name of context target, + -- guaranteed to be MN + + + o lifetime_rec INTEGER -- in seconds, or reserved value for + INDEFINITE, + + o mech_type OBJECT IDENTIFIER, -- the mechanism supporting this + security 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, + + o conf_avail BOOLEAN, + + o integ_avail BOOLEAN, + + o locally_initiated BOOLEAN, -- TRUE if initiator, FALSE if acceptor + + Return major_status codes: + + o GSS_S_COMPLETE indicates that the referenced context is valid + and that src_name, targ_name, lifetime_rec, mech_type, deleg_state, + mutual_state, replay_det_state, sequence_state, anon_state, + trans_state, prot_ready_state, conf_avail, integ_avail, and + locally_initiated return values describe the corresponding + characteristics of the context. + + 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. + + + + + +Linn Standards Track [Page 48] + +RFC 2078 GSS-API January 1997 + + + 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. + +2.2.7: GSS_Wrap_size_limit call + + Inputs: + + o context_handle CONTEXT HANDLE, + + 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 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. + + + + +Linn Standards Track [Page 49] + +RFC 2078 GSS-API January 1997 + + + 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. + +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 + + 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. + + + + + + +Linn Standards Track [Page 50] + +RFC 2078 GSS-API January 1997 + + + 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). + + To ensure portability, a caller of GSS_Export_sec_context() must not + assume that a context may continue to be used once it has been + exported; following export, the context referenced by the + context_handle cannot be assumed to remain valid. Further, 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 + + + +Linn Standards Track [Page 51] + +RFC 2078 GSS-API January 1997 + + + 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. + +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 + + 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_CONTEXT_EXPIRED indicates that the context represented by + the input interprocess_token has expired. Return values other + than major_status and minor_status are undefined. + + 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. + + + + + +Linn Standards Track [Page 52] + +RFC 2078 GSS-API January 1997 + + + 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. + + 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. + + + + + + + + + + +Linn Standards Track [Page 53] + +RFC 2078 GSS-API January 1997 + + +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 + + 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_CREDENTIALS_EXPIRED indicates that the context is recognized, + but that its associated credentials have expired, so + that the requested operation cannot be performed. + + o GSS_S_NO_CONTEXT indicates that no valid 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. + + + +Linn Standards Track [Page 54] + +RFC 2078 GSS-API January 1997 + + + 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 + return the result in 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. + + + + + + +Linn Standards Track [Page 55] + +RFC 2078 GSS-API January 1997 + + + 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 indicates that the received per_msg_token contains + an incorrect integrity check 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_CREDENTIALS_EXPIRED indicates that the context is + recognized, + but that its associated credentials have expired, so + that the requested operation cannot be performed. + + 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_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. Return an indication of the quality-of- + protection applied to the processed message in the qop_state result. + Since the GSS_VerifyMIC() routine never provides a confidentiality + service, its implementations should not return non-zero values in the + confidentiality fields of the output qop_state. + + 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. + + + + +Linn Standards Track [Page 56] + +RFC 2078 GSS-API January 1997 + + + 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, + + o conf_state BOOLEAN, + + o output_message OCTET STRING + + 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_CREDENTIALS_EXPIRED indicates that the context is + recognized, + but that its associated credentials have expired, so + that the requested operation cannot be performed. + + o GSS_S_NO_CONTEXT indicates that no valid 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 + + + +Linn Standards Track [Page 57] + +RFC 2078 GSS-API January 1997 + + + 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. + + In all cases, 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. + + 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 + + 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. + + + +Linn Standards Track [Page 58] + +RFC 2078 GSS-API January 1997 + + + o GSS_S_BAD_SIG 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_CREDENTIALS_EXPIRED indicates that the context is + recognized, + but that its associated credentials have expired, so + that the requested operation cannot be performed. + + 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_Unwrap() operation could not be performed for + reasons unspecified at the GSS-API level. + + 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() deciphers the input_message. + Returns an indication of the quality-of-protection applied to the + processed message in the qop_state result. GSS_Wrap() 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. + + + + + + + +Linn Standards Track [Page 59] + +RFC 2078 GSS-API January 1997 + + +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 + + 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. + + 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. + +2.4.2: GSS_Indicate_mechs call + + Input: + + o (none) + + + + + +Linn Standards Track [Page 60] + +RFC 2078 GSS-API January 1997 + + + Outputs: + + o major_status INTEGER, + + o minor_status INTEGER, + + o mech_set SET OF OBJECT IDENTIFIER + + Return major_status codes: + + o GSS_S_COMPLETE indicates that a set of available mechanisms has + been returned in mech_set. + + 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_Acquire_cred(), and should not be needed by other callers. + +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 one or both of name1 and + name2 contained internal type specifiers uninterpretable + by the applicable underlying GSS-API mechanism(s), or that + the two names' types are different and incomparable, so that + the comparison operation could not be completed. + + + +Linn Standards Track [Page 61] + +RFC 2078 GSS-API January 1997 + + + 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 + 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, + + o name_type OBJECT IDENTIFIER + + 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_NAMETYPE indicates that the provided name was of a + type uninterpretable by the applicable underlying GSS-API + mechanism(s), so no printable representation could be generated. + + 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. + + + + +Linn Standards Track [Page 62] + +RFC 2078 GSS-API January 1997 + + + 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. + +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 + + 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_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. Note: The + input_name_type argument serves to describe and qualify the + + + +Linn Standards Track [Page 63] + +RFC 2078 GSS-API January 1997 + + + 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. + + o GSS_S_BAD_NAME indicates that the input name argument did not + contain a valid name. + + + +Linn Standards Track [Page 64] + +RFC 2078 GSS-API January 1997 + + + 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, this call may be superfluous + 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, this call + may be superfluous within bindings where memory management is + automatic. + +2.4.8: GSS_Release_OID_set call + + Inputs: + + o buffer SET OF OBJECT IDENTIFIER + + Outputs: + + o major_status INTEGER, + + + + +Linn Standards Track [Page 65] + +RFC 2078 GSS-API January 1997 + + + 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, + this call may be superfluous 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 + + 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 66] + +RFC 2078 GSS-API January 1997 + + +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 67] + +RFC 2078 GSS-API January 1997 + + + 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_Release_OID call + + Inputs: + + o oid 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 + + Allows the caller to release the storage associated with an OBJECT + IDENTIFIER 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, + this call may be superfluous within bindings where memory management + is automatic. + +2.4.13: GSS_OID_to_str call + + Inputs: + + o oid OBJECT IDENTIFIER + + Outputs: + + o major_status INTEGER, + + o minor_status INTEGER, + + o oid_str OCTET STRING + + Return major_status codes: + + o GSS_S_COMPLETE indicates successful completion + + + +Linn Standards Track [Page 68] + +RFC 2078 GSS-API January 1997 + + + o GSS_S_FAILURE indicates that the operation failed + + The function GSS_OID_to_str() returns a string representing the input + OID in numeric ASN.1 syntax format (curly-brace enclosed, space- + delimited, e.g., "{2 16 840 1 113687 1 2 1}"). The string is + releasable using GSS_Release_buffer(). If the input "oid" does not + represent a syntactically valid object identifier, GSS_S_FAILURE + status is returned and the returned oid_str result is NULL. + +2.4.14: GSS_Str_to_OID call + + Inputs: + + o oid_str OCTET STRING + + Outputs: + + o major_status INTEGER, + + o minor_status INTEGER, + + o oid OBJECT IDENTIFIER + + Return major_status codes: + + o GSS_S_COMPLETE indicates successful completion + + o GSS_S_FAILURE indicates that the operation failed + + The function GSS_Str_to_OID() constructs and returns an OID from its + printable form; implementations should be able to accept the numeric + ASN.1 syntax form as described for GSS_OID_to_str(), and this form + should be used for portability, but implementations of this routine + may also accept other formats (e.g., "1.2.3.3"). The OID is suitable + for release using the function GSS_Release_OID(). If the input + oid_str cannot be translated into an OID, GSS_S_FAILURE status is + returned and the "oid" result is NULL. + +2.4.15: GSS_Inquire_names_for_mech call + + Input: + + o input_mech_type OBJECT IDENTIFIER, -- mechanism type + + Outputs: + + o major_status INTEGER, + + + + +Linn Standards Track [Page 69] + +RFC 2078 GSS-API January 1997 + + + o minor_status INTEGER, + + o name_type_set SET OF OBJECT IDENTIFIER + + 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.16: GSS_Inquire_mechs_for_name call + + Inputs: + + o input_name INTERNAL NAME, + + Outputs: + + o major_status INTEGER, + + o minor_status INTEGER, + + o mech_types SET OF OBJECT IDENTIFIER + + 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 could not be + processed. + + o GSS_S_BAD_NAMETYPE indicates that the type of the input_name + 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. + + + +Linn Standards Track [Page 70] + +RFC 2078 GSS-API January 1997 + + + This routine returns the mechanism set with which the input_name may + be processed. After use, the mech_types object should be freed by + the caller via the GSS_Release_OID_set() call. Note: it is + anticipated that implementations of GSS_Inquire_mechs_for_name() will + commonly operate based on type information describing the + capabilities of available mechanisms; it is not guaranteed that all + identified mechanisms will necessarily be able to canonicalize (via + GSS_Canonicalize_name()) a particular name. + +2.4.17: GSS_Canonicalize_name call + + Inputs: + + o input_name INTERNAL NAME, + + o mech_type OBJECT IDENTIFIER -- must be explicit mechanism, + not "default" specifier + + Outputs: + + o major_status INTEGER, + + o minor_status INTEGER, + + o output_name INTERNAL 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. + + 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. + + + + + +Linn Standards Track [Page 71] + +RFC 2078 GSS-API January 1997 + + + This routine reduces a GSS-API internal name, which may in general + contain elements corresponding to multiple mechanisms, to a + mechanism-specific Mechanism Name (MN) by applying the translations + corresponding to the mechanism identified by mech_type. + +2.4.18: GSS_Export_name call + + Inputs: + + o input_name INTERNAL NAME, -- required to be MN + + Outputs: + + o major_status INTEGER, + + o minor_status INTEGER, + + o output_name OCTET STRING + + 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. + + + +Linn Standards Track [Page 72] + +RFC 2078 GSS-API January 1997 + + + 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.19: GSS_Duplicate_name call + + Inputs: + + o src_name INTERNAL NAME + + Outputs: + + o major_status INTEGER, + + o minor_status INTEGER, + + o dest_name INTERNAL 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_BAD_NAMETYPE indicates that the input name's 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 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. + + + + + + +Linn Standards Track [Page 73] + +RFC 2078 GSS-API January 1997 + + +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. + + 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: + + + + + +Linn Standards Track [Page 74] + +RFC 2078 GSS-API January 1997 + + + 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.) + + 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. + + + + + + + + + + + + + + + + + + + + + + + + + + +Linn Standards Track [Page 75] + +RFC 2078 GSS-API January 1997 + + + 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 + -- ASN.1 structure not required + sealedUserData ANY + + END + + + + + + +Linn Standards Track [Page 76] + +RFC 2078 GSS-API January 1997 + + +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. Name objects of this + type 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)} + + 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. + + 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. + +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 + + The following Object Identifier value is provided as a means to + identify this name form: + + {1(iso), 3(org), 6(dod), 1(internet), 5(security), 6(nametypes), + 2(gss-host-based-services)} + + The recommended symbolic name for this type is + "GSS_C_NT_HOSTBASED_SERVICE". + + + + + + +Linn Standards Track [Page 77] + +RFC 2078 GSS-API January 1997 + + + This name type is used to represent services associated with host + computers. 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" + is 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. + + Values for the "service" element are registered with the IANA. + +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 + 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 interpretation is 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 uid_t, represented in host byte + + + +Linn Standards Track [Page 78] + +RFC 2078 GSS-API January 1997 + + + 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 uid_t. + +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. + +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. + + + + + +Linn Standards Track [Page 79] + +RFC 2078 GSS-API January 1997 + + + 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 + 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, + + + +Linn Standards Track [Page 80] + +RFC 2078 GSS-API January 1997 + + + 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. + + 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 + + + +Linn Standards Track [Page 81] + +RFC 2078 GSS-API January 1997 + + + 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 + + Security issues are discussed throughout this memo. + +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. + + + + + + + + + + + + + + + + + + + +Linn Standards Track [Page 82] + +RFC 2078 GSS-API January 1997 + + +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. + + + + + + + +Linn Standards Track [Page 83] + +RFC 2078 GSS-API January 1997 + + + This GSS-V2 specification adds the following calls which are not + present in GSS-V1: + + 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_Release_OID(), GSS_OID_to_str(), GSS_Str_to_OID(), + 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. + + 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 + + + +Linn Standards Track [Page 84] + +RFC 2078 GSS-API January 1997 + + + 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. + +Author's Address + + John Linn + OpenVision Technologies + One Main St. + Cambridge, MA 02142 USA + + Phone: +1 617.374.2245 + EMail: John.Linn@ov.com + + + + + + + + + + + + + + +Linn Standards Track [Page 85] + |