diff options
Diffstat (limited to 'crypto/heimdal/doc/standardisation/rfc2078.txt')
| -rw-r--r-- | crypto/heimdal/doc/standardisation/rfc2078.txt | 4763 |
1 files changed, 0 insertions, 4763 deletions
diff --git a/crypto/heimdal/doc/standardisation/rfc2078.txt b/crypto/heimdal/doc/standardisation/rfc2078.txt deleted file mode 100644 index 1dd1e4a..0000000 --- a/crypto/heimdal/doc/standardisation/rfc2078.txt +++ /dev/null @@ -1,4763 +0,0 @@ - - - - - - -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] - |
