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