RFC 2078
Generic Security Service Application Program Interface, Version 2
Generic Security Service Application Program Interface, Version 2 🎀
okay bestie, let's get into this one 💖 it's RFC 2078, and the title block is giving us the tea:
- Network Working Group
- Request for Comments: 2078
- Author: J. Linn, OpenVision Technologies
- Category: Standards Track
- Date: January 1997
- Obsoletes: 1508
so J. Linn from OpenVision Technologies wrote this, it's on the Standards Track, and it's dated January 1997. it obsoletes 1508, which means 1508 is the old version and this one is the glow-up 👑
Status of This Memo 📜
ngl this part is kinda formal, but it matters 🫶 this document specifies an Internet standards track protocol for the Internet community, and it's asking for discussion and suggestions for improvements. if you want the standardization state and status of this protocol, check the current edition of the "Internet Official Protocol Standards" (STD 1). and distribution of this memo is unlimited, so share away 🦋
Abstract ✨
okay so GSS-API (the Generic Security Service Application Program Interface, as defined in RFC-1508) gives callers security services in a generic way. it can run on a whole range of underlying mechanisms and technologies, which means applications can be source-level portable across different environments. it's giving flexibility 💅
this spec defines the GSS-API services and primitives at a level that doesn't depend on the underlying mechanism or the programming language environment. it's meant to be complemented by other related specs, like:
- 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 with specific, incremental changes based on implementation experience and liaison requests. the plan is that this memo, or a successor version of it, becomes the basis for the later 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
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
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............................ 831. GSS-API Characteristics and Concepts ✨
Okay bestie, let's talk about how GSS-API actually works 💅. A typical GSS-API caller is itself a communications protocol, and it calls GSS-API to protect its communications with authentication, integrity, and/or confidentiality security services 🔐. The caller takes the tokens its local GSS-API implementation hands it and transfers them to a peer on a remote system. That peer then passes the received tokens to its own local GSS-API implementation for processing 🫶. The security services you get this way can be implemented (and have been implemented) over a range of underlying mechanisms based on secret-key and public-key cryptographic technologies 🌈.
The GSS-API splits up the work into separate pieces. There's initializing a security context between peers and achieving peer entity authentication (this is the GSS_Init_sec_context() and GSS_Accept_sec_context() calls 🦋). That's separate from providing per-message data origin authentication and data integrity protection (the GSS_GetMIC() and GSS_VerifyMIC() calls) for messages sent later on that same context ✨. (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.) When setting up a security context, the GSS-API lets a context initiator optionally permit its credentials to be delegated, which means the context acceptor may initiate further security contexts on behalf of the initiating caller 🧚. Per-message GSS_Wrap() and GSS_Unwrap() calls give you the same data origin authentication and data integrity services that GSS_GetMIC() and GSS_VerifyMIC() offer, and they also let the caller pick confidentiality services as an option 💜. Additional calls provide supportive functions for the GSS-API's users 🌸.
Let's walk through an example of how a client and a server use the GSS-API in a mechanism-independent way, setting up a security context and sending a protected message 🎀. The example assumes credential acquisition has already been completed. It also assumes the underlying authentication technology can authenticate a client to a server using elements carried within a single token, and can authenticate the server to the client (mutual authentication) with a single returned token. This assumption holds for presently-documented CAT mechanisms, but it's 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 it elects to set the mutual_req_flag so mutual authentication happens during context establishment 🔥. GSS_Init_sec_context() returns an output_token to be passed to the server, and it indicates GSS_S_CONTINUE_NEEDED status while the mutual authentication sequence is still pending ⏳. Had mutual_req_flag not been set, the initial call to GSS_Init_sec_context() would have returned GSS_S_COMPLETE status instead. 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 back to the client 👑. The server sends that 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(). That call processes the data in the token to achieve mutual authentication from the client's viewpoint 🦋. This call to GSS_Init_sec_context() returns GSS_S_COMPLETE status, which means mutual authentication succeeded and context establishment is complete 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, encapsulates the result into output_message, and indicates 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 done 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 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 that premise, the server 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, which gets transferred to the client to request that client-side context-level information be deleted 🧹.
If a context_token is transferred, the client passes it 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 the following 🌟:
- Mechanism independence: The GSS-API defines an interface to cryptographically implemented strong authentication and other security services at a generic level, 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 it's employed with, which permits use in a broad range of protocol environments 🌈. In appropriate environments, an intermediate implementation "veneer" oriented to a particular communication protocol (e.g., Remote Procedure Call (RPC)) may be interposed between applications that call that protocol and the GSS-API. That way GSS-API facilities get invoked in conjunction with the protocol's communications invocations 🧚.
- Protocol association independence: The GSS-API's security context construct is independent of communications protocol association constructs. This lets a single GSS-API implementation be used by a variety of invoking protocol modules on behalf of those modules' calling applications 💖. GSS-API services can also be invoked directly by applications, completely 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 that make up the GSS-API 🧩.
1.1.1. Credentials
1.1.1.1. Credential Constructs and Concepts
Credentials provide the prerequisites that let GSS-API peers establish security contexts with each other 🗝️. A caller may designate that the credential elements to be applied for context initiation or acceptance be selected by default. Alternatively, GSS-API callers that need to explicitly select particular credential structures may reference them through GSS-API-provided credential handles ("cred_handles") 🎀. In all cases, callers' credential references are indirect. They're mediated by GSS-API implementations, and callers don't have to access the selected credential elements directly 🫶.
A single credential structure may be used to initiate outbound contexts and to accept inbound contexts. Callers that only need to operate in one of these modes can say so when credentials are acquired for use. That lets underlying mechanisms optimize their processing and storage requirements ✨. The credential elements defined by a particular mechanism may contain multiple cryptographic keys, for example so that authentication and message encryption can be performed with different algorithms 🔐.
A GSS-API credential structure may contain multiple credential elements, each holding mechanism-specific information for a particular underlying mechanism (mech_type). However, the set of elements within a given credential structure represents a common entity 🌸. A credential structure's contents vary depending on the set of mech_types supported by a particular GSS-API implementation 💜. Each credential element identifies the data its mechanism needs to establish contexts on behalf of a particular principal. It may also contain separate credential references for use in context initiation and context acceptance 🦋. Multiple credential elements within a given credential that have 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 that represent multiple mech_types is to let initiators on systems equipped to handle multiple types initiate contexts to targets on other systems. Those targets can only accommodate a subset of the set supported at the initiator's system 🌈.
1.1.1.2. Credential Management
It's 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 🔒. Implementors should take this responsibility seriously, because the ability for an entity to use 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, whether that credentials set can be transferred 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 💅.
Credential establishment (particularly when it's performed on behalf of users rather than server processes) is likely to require access to passwords or other quantities that should be protected locally and exposed for the shortest time possible 😭. Because of that, 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 later reference 🧁. These preliminary credentials would be set aside (in a system-specific fashion) for later use, either:
- to be accessed by an invocation of the GSS-API
GSS_Acquire_cred()call, returning an explicit handle to reference that credential 🔑 - to comprise default credential elements to be installed, and to be used when default credential behavior is requested on behalf of a process 🌟
1.1.1.3: Default Credential Resolution 🎀
okay bestie, so you can pass GSS_C_NO_CREDENTIAL as the credential handle to gss_init_sec_context and gss_accept_sec_context 💅 That special handle basically says "I just want to act as the default principal" ✨ Each GSS-API implementation gets to decide what default behavior means for its own mechanism, but for portability, the following default behavior by these routines is recommended. 🫶
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
(iv) A user-configurable default identity shall be used. 💜
The whole point of these rules is letting the initiator and the acceptor both use default behavior wherever it's possible 🦋 Apps that ask for the default are usually more portable across mechanisms and platforms than apps that call GSS_Acquire_cred to request one specific identity, so it's giving "easy mode" ✨
1.1.2: Tokens 🧚
okay so tokens are the data elements that GSS-API callers pass to each other, and they come in two classes 🍓 Context-level tokens get swapped to set up and manage a security context between peers. Per-message tokens belong to a context that's already established, and they're exchanged to provide protective security services (data origin authentication, integrity, and optional confidentiality) for the data messages they go with. 🔥
The first context-level token that comes out of GSS_Init_sec_context() is required to indicate, right at its very beginning, a globally-interpretable mechanism identifier, which is an Object Identifier (OID) for the security mechanism. Everything after that in the first token, plus the entire contents of every other token, is specific to the underlying mechanism that supports the GSS-API. Section 3 of this document is for designers of GSS-API support mechanisms, and it describes the header of that first context-level token, which is then followed by mechanism-specific information. 👑
Tokens' contents are opaque from the viewpoint of GSS-API callers 🙈 They're generated inside the GSS-API implementation at one end system, handed to a GSS-API caller so they can be sent to the peer GSS-API caller at a remote end system, and then processed by the GSS-API implementation at that remote end. Tokens may be output by GSS-API calls, and they should be transferred to GSS-API peers, whether or not the calls' status indicators show successful completion. Token transfer can happen in-band, mixed into the same protocol stream the callers use for other data, or out-of-band, across a logically separate channel. ✨
Different GSS-API tokens serve different purposes (for example, context initiation, context acceptance, or protected message data on an established context), so it's the job of the receiving GSS-API caller to tell their types apart, link them to the right security contexts, and pass them to the correct GSS-API processing routines. Depending on the caller's protocol environment, this distinction can be made in several ways. 💅
The following examples show ways that 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.
Usually the data inside a token includes internal mechanism-specific tagging, so the mechanism-level processing modules can tell apart tokens that are used for different purposes inside the mechanism. This kind of internal mechanism-level tagging is recommended to mechanism designers, and it lets a mechanism figure out whether a caller has handed a particular token to an inappropriate GSS-API routine. 🦋
Okay, real talk: building GSS-API support primitives on a particular cryptographic technique and protocol (so, conforming to a specific GSS-API mechanism definition) doesn't automatically mean GSS-API callers using that mechanism can interoperate with peers that use the same technique and protocol outside the GSS-API paradigm. It also doesn't mean they'll work with peers using a different GSS-API mechanism built on the same underlying tech. The format of GSS-API tokens defined for a particular mechanism, and the techniques used to fit 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 get established between peers, using credentials that are set up locally with each peer or that peers receive through delegation. Multiple contexts can exist at the same time between a pair of peers, using the same or different sets of credentials. Having multiple contexts with different credentials is what allows a graceful rollover when credentials expire 🔄 Telling apart multiple contexts that share the same credentials lets applications separate different message streams in a security sense. 💖
The GSS-API doesn't depend on any particular underlying protocol or addressing structure, so it relies on its callers to transport the GSS-API-provided data elements. Because of that, it's the caller's responsibility to parse the messages it gets, separating GSS-API-related data elements from the caller-provided data. The GSS-API also doesn't care whether the underlying communications service is connection-oriented or connectionless. 🧚
No correlation between a security context and a communications protocol association is dictated. (The optional channel binding facility, discussed in Section 1.1.6 of this document, is an intentional exception to this rule, supporting additional protection features within GSS-API supporting mechanisms.) This separation lets the GSS-API work in a wide range of communications environments, and it also keeps the calling sequences of the individual calls simpler ✨ In many cases (depending on the underlying security protocol, the associated mechanism, and whether cached information is available), the state information needed for context setup can be sent concurrently with initial signed user data, without interposing additional message exchanges. 🍓
1.1.4: Mechanism Types 🦋
To successfully establish a security context with a target peer, you need to identify an appropriate underlying mechanism type (mech_type) that both the initiator and target peers support. A mechanism's definition covers not just the use of a particular cryptographic technology (or a hybrid, or a choice among alternative cryptographic technologies), but also the syntax and semantics of the data element exchanges that the mechanism uses to support security services. 💜
It is recommended that callers initiating contexts specify the "default" mech_type value. That lets system-specific functions within, or invoked by, the GSS-API implementation select the appropriate mech_type. Callers may still direct that a particular mech_type be employed when necessary. 👑
The ways to identify a shared mech_type for setting up a security context with a peer will vary across 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
- explicit negotiation between GSS-API callers in advance of security context setup
When mech_type specifiers are transferred between GSS-API peers (per Section 3, represented as Object Identifiers (OIDs)), they qualify the interpretation of the 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)".) Using hierarchically structured OIDs prevents ambiguous interpretation of mech_type specifiers. 🌸 For example, the OID representing the DASS MechType is 1.3.12.2.1011.7.5, and the Kerberos V5 mechanism's OID, once it's advanced to the level of Proposed Standard, will be 1.2.840.113554.1.2.2. ✨
1.1.5: Naming ✨
The GSS-API doesn't force any naming structure on you 🎀. The names passed across the interface to start and accept security contexts are treated as opaque objects, which is so iconic of it. The reason is that different mechanisms process and authenticate names in different forms, and the GSS-API wants to be implementable on top of a whole range of security mechanisms 💅. Generalized services that translate among arbitrary sets of naming environments are outside the GSS-API's scope 🙅♀️. Instead, it expects each end system to have local conversion functions for the naming formats it supports 🧚.
Names come in different classes, and each class goes with different GSS-API parameters:
- Internal form (called INTERNAL NAME in this document) is opaque to callers and is defined by each GSS-API implementation 🔮. Implementations that support more than one namespace type must keep internal tags so they can tell which interpretation a name has 🏷️. A Mechanism Name (MN) is a special case of INTERNAL NAME that is guaranteed to contain elements for one and only one mechanism. Calls that are guaranteed to emit MNs, or that need MNs as input, are labelled as such in this specification 💜.
- Contiguous string ("flat") form (called OCTET STRING in this document) comes with OID tags that identify the namespace it belongs to 🌸. Depending on the tag value, a flat name may or may not be a printable string that can be taken from or shown to users 🖨️. Tagging flat names lets GSS-API callers and mechanisms tell name types apart and check whether a name is a type they can handle. This avoids aliasing, which is when you misread a name of one type as another type and things go sideways 😭.
- The GSS-API Exported Name Object is a special case of flat name, marked with a reserved OID value. It carries a canonicalized form of a name that's suitable for binary comparisons 🦋.
Tagging names with types is great, but this specification also defines primitives that give a level of naming-environment independence for certain calling applications 🫶. For callers who don't need to interpret the internal syntax and semantics of names, the GSS-API defines 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()) 🎀. (These proposed GSS-API calls are expected to be implemented in many end systems on top of system-specific name manipulation primitives those systems already have. Putting them in the GSS-API gives callers a portable way to do specific operations on authenticated names, which helps with authorization and audit requirements ✨.)
GSS_Import_name() implementations can, where it makes sense, support more than one printable syntax for a given namespace. For example, X.500 Distinguished Names can have alternative printable representations. That gives callers flexibility to pick the one they like best 💖. GSS_Display_name() implementations output a printable syntax chosen to suit their operating environment, and that choice is a local matter 🏠. If you want your code to be portable across printable syntaxes, don't write comparisons based on printable name forms. Use GSS_Compare_name() to find out whether one internal-format name matches another instead 🙈.
The GSS_Canonicalize_name() and GSS_Export_name() calls let callers get and process Exported Name Objects, which have been canonicalized and translated according to the procedures of a particular GSS-API mechanism 🌈. Exported Name Objects can be fed back into GSS_Import_name() to get equivalent MNs. These facilities exist specifically so names can be stored and compared efficiently, for example in access control lists 💅.
The diagram below shows the intended dataflow among the 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 supports caller-provided channel binding ("chan_binding") information 🧷. Channel bindings make peer entity authentication during context establishment stronger. They do this by limiting how far an intercepted context establishment token can be reused by an attacker 🕵️♀️. Specifically, they let GSS-API callers bind a security context to relevant characteristics of the underlying communications channel (like addresses, or transformed representations of encryption keys), to the protection mechanisms applied to that channel, and to application-specific data 🦋.
The caller who starts a security context has to work out the right channel binding values to pass to the GSS_Init_sec_context() call. The context's target has to give GSS_Accept_sec_context() consistent values. That way, both peers' GSS-API mechanisms can check that the tokens they receive have the correct channel-related characteristics 🤝. Using the GSS-API channel binding facility, or not using it, is up to the caller 💁♀️. GSS-API mechanisms can work in an environment where NULL channel bindings are presented. Mechanism implementors are encouraged, but not required, to use caller-provided channel binding data inside their mechanisms 🌸. Callers shouldn't assume that the underlying mechanisms give confidentiality protection to channel binding information 😬.
When callers provide non-NULL channel bindings, some mechanisms can add real security value by interpreting what's in the bindings. Those mechanisms don't just carry the bindings, or integrity check values computed over them, inside tokens. Instead, they depend on specific data in a defined format 🧠. To that end, mechanism implementors are agreeing on conventional interpretations for what goes in channel binding arguments. That includes address specifiers, whose content depends on the communications protocol environment, for context initiators and acceptors 📋. (These conventions are being put into GSS-API mechanism specifications and into the GSS-API C language bindings specification 📚.) For GSS-API callers to be portable across multiple mechanisms and to get the full security functionality each mechanism can provide, it is strongly recommended that they provide channel bindings that follow these conventions and the conventions of the networking environment they operate in 🎀.
1.2. GSS-API Features and Issues 🌟
This section covers aspects of GSS-API operations and the security services the GSS-API provides. It also comments on design issues 💭.
1.2.1: Status Reporting 📣
Every GSS-API call gives back two status return values 🎁. Major_status values give a mechanism-independent indication of how the call went (for example GSS_S_COMPLETE, GSS_S_FAILURE, or GSS_S_CONTINUE_NEEDED). That's enough to steer the caller's control flow in a generic way 🧭. Table 1 sums up the defined major_status return codes in one handy spot 💖.
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)
detectedOkay so here's the status code table, and bestie, it's a whole lineup 🎀💅. The fatal ones are the "something went wrong, stop" codes, and the informatory ones are more like "hey, FYI, here's what's happening with your message" 🧚. Next up, minor_status gives you the detailed, more specific info, and it can include codes from the underlying security mechanism itself 🔍. The actual minor_status values aren't defined in this document, so don't go looking for them here, bestie 🙈.
Now the GSS_S_CONTINUE_NEEDED thing is honestly so clever ✨. Different mechanisms use different numbers of messages in their authentication sequences, and the app shouldn't have to write a separate code path for every single one 💖. So instead, you just keep making continuation calls to GSS_Init_sec_context() and GSS_Accept_sec_context() until you're done. Mutual authentication gets handled through that same mechanism inside the context initiation calls too 🫶.
Some mech_types need to talk to third-party servers before they can set up a security context, so those context establishment calls are allowed to block while that's happening ⏳.
BUT, and this is the lowkey tea 🍵, no GSS-API calls wait on serialized interactions with peer entities. That means your local status returns can't show unpredictable or asynchronous problems happening over at the remote peer 😭. Passing that info along is the caller's job, not GSS-API's. Not the vibe, but it's the rule 💀.
1.2.2. Per-Message Security Service Availability
Once a context is established, you get two flags back that tell you which per-message protection services are actually available on it 🦋.
- the
integ_availflag tells you whether per-message integrity and data origin authentication services are available 🔒 - the
conf_availflag tells you whether per-message confidentiality services are available, and it will never come backTRUEunlessinteg_availalso came backTRUE🫧
GSS-API callers who want per-message security services should check these flags at context establishment time, no skipping 🙅♀️. And you need to be aware that if integ_avail comes back FALSE, then calling GSS_GetMIC() or GSS_Wrap() on that context won't apply any cryptographic protection to your user data messages 😱. That's a big deal, bestie 🚨.
Okay, the vibe of the protection services: integrity and data origin authentication give the receiving caller assurance that protection was applied by the caller's peer on the security context, which is the entity you named at context initiation 🎀. Confidentiality gives the sending caller assurance that the message's content is protected from anyone other than that named peer 🤫.
These per-message protection primitives are built for protocol data units, so they work at that granularity 📦. They do their crypto on the data units, move the control info around in tokens, and GSS_Wrap() also wraps up the protected data unit ✨. Because of that, they're not really built for efficient protection of stream-paradigm protocols, like Telnet, if the crypto has to happen one octet at a time 🐢.
1.2.3. Per-Message Replay Detection and Sequencing
Some underlying mech_types can do replay detection and/or sequencing for the messages they carry on their contexts 🔁. These are optional protection features, and they're separate from the replay and sequencing stuff used for the context establishment operation itself 💅. Whether a context has those context-level features is totally up to the mechanism's capabilities. It's not something you pick or skip as a caller option 🙃.
The initiating caller passes in replay_det_req_flag and sequence_req_flag to say whether they want per-message replay detection and sequencing on the context being set up 🎯. The initiator's GSS-API implementation can figure out whether those features are supported (and whether they're optionally selectable) based on the mech_type alone, so it doesn't need to negotiate with the target first 🧠. When they're turned on, recipients get indicators from GSS-API processing of incoming messages, telling them if a message looked like a duplicate or came out of order 👀. But spotting these doesn't stop a suspicious message from reaching the recipient. What to do with it is up to the caller's policy 💜.
Here's what the replay detection and sequencing services look like from the GSS-API interface, as seen by its clients 🌸:
When replay_det_state is TRUE, the possible major_status returns for well-formed and correctly signed messages are:
GSS_S_COMPLETEmeans the message was inside the window (of time or sequence space) where replay events can be detected, and it wasn't a replay of a message already processed in that window 💖.GSS_S_DUPLICATE_TOKENmeans the cryptographic checkvalue was correct, but the message was spotted as a duplicate of one already processed 👯.GSS_S_OLD_TOKENmeans the cryptographic checkvalue was correct, but 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:
GSS_S_COMPLETEmeans the message was inside the window (of time or sequence space) where replay events can be detected, it wasn't a replay of a message already processed in that window, and no predecessor sequenced messages are missing relative to the last received message (if there is one) processed on the context with a correct cryptographic checkvalue 🏆.GSS_S_DUPLICATE_TOKENmeans the integrity check value was correct, but the message was recognized as a duplicate of one already processed 👯♀️.GSS_S_OLD_TOKENmeans the integrity check value was correct, but the token is too old to be checked for duplication 🕰️.GSS_S_UNSEQ_TOKENmeans the cryptographic checkvalue was correct, but the message comes earlier in a sequenced stream than a message already processed on the context 🔀. [Note: Mechanisms can be built 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 kind of support doesn't fit the GSS-API paradigm, where recipients receive all messages, in order or not, and hand them over one at a time, without intra-GSS-API message buffering, to GSS-API routines for validation. GSS-API facilities are there to help clients get strict message stream integrity efficiently, working together with sequencing provisions in communications protocols, but the GSS-API doesn't offer this level of message stream integrity service by itself 🧩.]GSS_S_GAP_TOKENmeans the cryptographic checkvalue was correct, but one or more predecessor sequenced messages haven't been successfully processed relative to the last received message (if there is one) processed on the context with a correct cryptographic checkvalue 🕳️.
Okay, so message stream integrity features (especially sequencing) can totally clash with some apps' communication style, and they're pretty resource intensive too 😩. That's why it is highly recommended that mech_types supporting these features let them be turned on selectively, when the initiator asks for it while the context is being set up 🙏. The initiator and target each get a matching indicator, replay_det_state and sequence_state, saying whether these features are active on that context 🚦.
Here's an example of how a mech_type that supports per-message replay detection could do it when replay_det_state is TRUE 🧁. The mechanism would stick timestamps into the data elements that come out of GSS_GetMIC() and GSS_Wrap() 🕒. Then, within a time-limited window, it would keep a cache (organized by originator-recipient pair) of the received data elements that have gone through GSS_VerifyMIC() and GSS_Unwrap() 🗂️. When this feature is active, GSS_VerifyMIC() or GSS_Unwrap() will return the exception statuses GSS_S_DUPLICATE_TOKEN or GSS_S_OLD_TOKEN whenever they get a message that's either a detected duplicate of a prior one, or too old to check against that cache of recently received messages 🚨✨.
1.2.4: Quality of Protection 🎛️
Okay so some mech_types let you dial the protection level for each individual message 💅 Callers can trade off security processing overhead against how much protection a given message actually needs. The per-message quality-of-protection parameter (basically the QOS vibe, but called QOP) picks which QOP option that mechanism supports. When context is set up for a multi-QOP mech_type, the context-level data gives you everything you need for a range of protection qualities. Iconic. ✨
Most callers won't want to touch mechanism-specific QOP control, so they'll just ask for the default QOP 🫶 Non-default QOP values are defined by each mechanism, and you can't assume that an ordered list of QOP values means the same thing across different mechanisms. So using non-default values well means you have to know the QOP definitions of the underlying mechanism (or mechanisms), which makes it a non-portable construct 🙃 The GSS_S_BAD_QOP major_status exists to say that a QOP value isn't supported for a security context, most likely because the underlying mechanism doesn't recognize it. 💀
1.2.5: Anonymity Support 🙈
Sometimes an app wants to authenticate a peer and/or protect messages with GSS-API per-message services without revealing who it is 🦋 Picture an app that gives read access to a research database and lets any random requestor run queries. A client might want to authenticate the service so it can trust the info it gets back, but it might not want to tell the service who it is for privacy reasons. Totally valid. 🌸
In normal GSS-API usage, the context initiator's identity gets shared with the context acceptor as part of context establishment. For anonymity support, there's a facility (input anon_req_flag to GSS_Init_sec_context()) that lets initiators ask for their identity not to be provided to the context acceptor. Mechanisms are not required to honor this request, but the caller will be told (through the returned anon_state from GSS_Init_sec_context()) whether or not it was honored. Also, authenticating as the anonymous principal does not automatically mean credentials aren't needed to establish a context 👀
Here's the Object Identifier that identifies anonymous names. You can compare against it to figure out, in a mechanism-independent way, 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 for this definition is GSS_C_NT_ANONYMOUS 🍓
There are four possible combos of anon_state and mutual_state, with these results:
anon_state == FALSE, mutual_state == FALSE: initiator
authenticated to target.
anon_state == FALSE, mutual_state == TRUE: initiator authenticated
to target, target authenticated to initiator.
anon_state == TRUE, mutual_state == FALSE: initiator authenticated
as anonymous principal to target.
anon_state == TRUE, mutual_state == TRUE: initiator authenticated
as anonymous principal to target, target authenticated to
initiator.1.2.6: Initialization 🌈
GSS-API doesn't define any initialization calls (the ones you have to run before using anything else in the interface) 🙌 Because of that, GSS-API implementations must be self-initializing. No pressure, but they really do have to handle it themselves. 💖
1.2.7: Per-Message Protection During Context Establishment 🛡️
GSS-V2 adds a facility for protecting and buffering data messages to send later while a security context is still in GSS_S_CONTINUE_NEEDED status. It's meant for when the caller already has the session key it needs for this 🔑 Specifically, there's a new state Boolean called prot_ready_state, which gets added to the info 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 (both initiators and acceptors) can assume that per-message protection (via GSS_Wrap(), GSS_Unwrap(), GSS_GetMIC() and GSS_VerifyMIC()) is available and ready to use if either prot_ready_state == TRUE, or major_status == GSS_S_COMPLETE. Mutual authentication (if requested) can't be guaranteed until GSS_S_COMPLETE gets returned, though 🥹
This gives full, transparent backward compatibility for GSS-API V1 callers. They don't even need to know prot_ready_state exists, and they'll get the expected behavior from GSS_S_COMPLETE. The only catch is that they can't use per-message protection before GSS_S_COMPLETE is returned 🫠
GSS-V2 mechanisms aren't required to ever return TRUE prot_ready_state before context establishment finishes. Some mechanisms won't evolve usable message protection keys (especially at the context acceptor) until establishment is complete, and that's fine 🤷♀️ It's expected, but not required, that GSS-V2 mechanisms return TRUE prot_ready_state when establishment completes, if they support per-message protection at all. GSS-V2 applications should not assume that TRUE prot_ready_state will always come back together with the GSS_S_COMPLETE major_status, because GSS-V2 implementations may still support GSS-V1 mechanism code, and that code will never return TRUE prot_ready_state 🙅♀️
When prot_ready_state is returned TRUE, mechanisms shall also set the context service indicator flags (deleg_state, mutual_state, replay_det_state, sequence_state, anon_state, trans_state, conf_avail, integ_avail) that show which facilities were confirmed, at that time, to be available on the context being established 📋 If prot_ready_state comes back before GSS_S_COMPLETE, more facilities might get confirmed and show up later, when GSS_S_COMPLETE is returned 👑
1.2.8: Implementation Robustness 💪
This section recommends some GSS-API implementation behavior for overall robustness 🧸
If a token is presented for processing on a GSS-API security context and that token turns out to be invalid for that context, the context's state should not be disrupted when it comes to processing later valid tokens. 🌷
Some local conditions at a GSS-API implementation (like running out of memory) might temporarily or permanently stop tokens on a GSS-API security context from being processed successfully. This usually shows up as GSS_S_FAILURE major_status returns, along with locally-significant minor_status. For robust operation under those conditions, these recommendations are made:
- Failing calls should free any memory they allocate, so callers can retry without causing further loss of resources. 🧹
- Failure of an individual call on an established context should not stop subsequent calls from succeeding on that same context. 🔁
- Whenever possible, GSS_Delete_sec_context() calls should be processed successfully even if other calls can't succeed, so context-related resources can still be released. 🗑️
2: Interface Descriptions 🎀
This section describes the GSS-API's service interface, sorting the calls into four groups. Credential management calls are about acquiring and releasing credentials as principals. Context-level calls manage security contexts between principals. Per-message calls protect individual messages on established security contexts. Support calls are ancillary functions that GSS-API callers find useful 💜 Table 2 groups and summarizes all the calls in one handy spot 💅
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
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 object2.1. Credential management calls ✨
okay so bestie, these GSS-API calls are all about managing credentials 🔐💖 Whether they're allowed to block while they wait on other network entities (think directories or authentication servers) depends on OS-specific stuff that lives outside GSS-API, so this doc doesn't pin it down. Not our drama 💅
GSS_Acquire_cred() exists so apps stay portable, and it's especially built for portable server applications 🖥️✨ Interactive users and server processes can get their credentials handled differently on some systems and mechanisms. The GSS-API implementation is responsible for telling those cases apart, and how it does that is a local matter 🫶
Here's the rest of the squad:
GSS_Release_cred()lets a caller tell GSS-API "I'm done with this credentials structure" 👋GSS_Inquire_cred()lets you look up info about a credentials structure 🔍GSS_Add_cred()lets you attach elements to an existing credential, so you can build a multi-mechanism credential one piece at a time 🧩GSS_Inquire_cred_by_mech()digs out per-mechanism info about 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-ONLYOutputs:
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
INDEFINITEReturn major_status codes:
GSS_S_COMPLETE🎉 means the requested credentials were successfully established. They're good for the duration inlifetime_rec, they're suitable for the usage incred_usage, they cover the mech_types listed inactual_mechs, and you can reference them later using the handle inoutput_cred_handle.GSS_S_BAD_MECH🙅 means a mech_type that the GSS-API implementation doesn't support got requested, so the credential establishment failed.GSS_S_BAD_NAMETYPE🙈 means thedesired_nameis either uninterpretable or a type that the underlying mechanism(s) don't support, so no credentials could be made for that name.GSS_S_BAD_NAME💀 means thedesired_namedoesn't match up internally with its own type specifier info, so again, no credentials for that name.GSS_S_FAILURE😭 means credential establishment failed for reasons GSS-API doesn't spell out. This also covers not being authorized to establish and use credentials tied to the identity named indesired_name.
GSS_Acquire_cred() gets credentials so a principal can initiate and/or accept security contexts (depending on cred_usage) under the identity in desired_name. When it succeeds, output_cred_handle is your handle for everything that comes after 🔑 Honestly, single-user client processes that just want default credential behavior usually don't even need this call, so don't stress 💅
If you pass NULL for desired_name, you're asking for credentials for whatever principal identity gets picked by default for you. How the implementation picks that identity is a local matter. Also, if several pre-established credentials exist for the same principal (like from multiple login sessions), how one gets chosen is also local 🤷♀️ The lifetime_req input can help the implementation make that call in a way that matches what you're after.
💅 Lifetime tea:lifetime_rectells you how long the credentials stay valid, as an offset from right now. A mechanism can return the reserved value INDEFINITE if it puts no limit on the lifetime. You can ask for a specific validity period withlifetime_req(counting from now), or just take the default. Postdated credentials aren't supported in GSS-API, so forget about those 🚫 Some mechanisms and implementations lock in validity periods before this call even happens (say, during user login). That means a non-defaultlifetime_reqwon't always be honored, so you need to be ready to work with credentials whose lifetimes differ from what you asked for, as shown inlifetime_rec.
You can either list the mech_types you want in desired_mechs, or leave it empty to get the system's default set. Going with the system default is recommended for application portability, which is super iconic 🦋 You can check actual_mechs to see exactly which mechanisms the returned credentials work with.
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 INTEGERReturn major_status codes:
GSS_S_COMPLETE✨ means the credentials referenced bycred_handlewere released, so the caller can't use them anymore. What happens to other authorized processes that share those credentials is a local matter.GSS_S_NO_CRED🚫 means nothing got released, either becausecred_handlewas invalid or because the caller isn't authorized to access those credentials.GSS_S_FAILURE💔 means the release failed for reasons GSS-API doesn't specify.
This call is how a caller explicitly says "release these credentials, I'm done" 🧹 Heads up, though: the system might have its own credential management going on too. For example, shared credentials could get deleted automatically once all the processes using them have ended, even if nobody called this 👀 Also, multiple callers can be authorized to access the same credentials, so calling GSS_Release_cred() can't be assumed to delete a given set of credentials system-wide 🙅♀️
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 queriedOutputs:
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 IDENTIFIERReturn major_status codes:
GSS_S_COMPLETE🥳 means the credentials referenced bycred_handlewere valid. The outputscred_name,lifetime_rec, andcred_usagethen tell you, respectively, the principal name, the remaining lifetime, and the usage modes that are suitable. Supported mechanism types come back too.GSS_S_NO_CRED🙅 means no info could be returned, either becausecred_handlewas invalid or because the caller isn't authorized to access those credentials.GSS_S_DEFECTIVE_CREDENTIAL🛠️ means the referenced credentials are invalid.GSS_S_CREDENTIALS_EXPIRED⌛ means the referenced credentials have expired. Time's up, bestie.GSS_S_FAILURE😵 means the operation failed for reasons GSS-API doesn't spell out.
GSS_Inquire_cred() is mainly for callers who use default credential behavior instead of acquiring credentials explicitly with GSS_Acquire_cred(). It tells you a credential structure's principal name, how much validity time it has left, whether it can be used to initiate and/or accept security contexts, and which mechanisms it supports 🔍
For a multi-mechanism credential, the lifetime value you get back is the shortest lifetime of any mechanism's element in the credential (for initiating or accepting, whichever applies). So it's the weakest link ⏳
GSS_Inquire_cred() should report INITIATE-AND-ACCEPT for cred_usage when both of these are true:
- The credential has an element that allows context initiation using some mechanism.
- The credential has an element that allows context acceptance using some mechanism. That mechanism can be one of the same ones from (1), but it doesn't have to be.
If (1) is true but (2) isn't, GSS_Inquire_cred() should report INITIATE-ONLY for cred_usage. If (2) is true but (1) isn't, it should report ACCEPT-ONLY for cred_usage 💜
If you need finer detail about the combos of lifetimes, usage modes, and mechanisms, call GSS_Inquire_cred_by_mech() and pass it one of the mech OIDs that GSS_Inquire_cred() gave you. That's the move 🦋
2.1.4: GSS_Add_cred call 💖
Inputs:
input_cred_handleCREDENTIAL HANDLE: handle to a credential structure created with a priorGSS_Acquire_cred()orGSS_Add_cred()call, or NULL to append elements to the set that are applied for the caller when default credential behavior is specified. 🎀desired_nameINTERNAL NAME: NULL requests the locally-determined default. ✨initiator_time_reqINTEGER: in seconds; 0 requests the default. ⏳acceptor_time_reqINTEGER: in seconds; 0 requests the default. ⏳desired_mechOBJECT IDENTIFIER 🦋cred_usageINTEGER: 0=INITIATE-AND-ACCEPT, 1=INITIATE-ONLY, 2=ACCEPT-ONLY 🌈
Outputs:
major_statusINTEGER 🌸minor_statusINTEGER 🌸output_cred_handleCREDENTIAL HANDLE: NULL to request that credential elements be added "in place" to the credential structure identified byinput_cred_handle, or a non-NULL pointer to request that a new credential structure and handle be created. 🧚actual_mechsSET OF OBJECT IDENTIFIER 🍓initiator_time_recINTEGER: in seconds, or the reserved value for INDEFINITE ⏳acceptor_time_recINTEGER: in seconds, or the reserved value for INDEFINITE ⏳cred_usageINTEGER: 0=INITIATE-AND-ACCEPT, 1=INITIATE-ONLY, 2=ACCEPT-ONLY 🌈mech_setSET OF OBJECT IDENTIFIER: the full set of mechanisms supported by the resulting credential. 👑
Return major_status codes:
GSS_S_COMPLETEmeans the credentials referenced by theinput_cred_handleargument were valid, and the resulting credential fromGSS_Add_cred()is valid for the durations indicated ininitiator_time_recandacceptor_time_rec, suitable for the usage requested incred_usage, and for the mechanisms indicated inactual_mechs. ✅GSS_S_DUPLICATE_ELEMENTmeans the inputdesired_mechspecified a mechanism for which the referenced credential already contained a credential element with overlappingcred_usageand validity time specifiers. 😭GSS_S_BAD_MECHmeans the inputdesired_mechspecified a mechanism the GSS-API implementation doesn't support, so theGSS_Add_cred()operation fails. 💀GSS_S_BAD_NAMETYPEmeans the provideddesired_nameis uninterpretable or of a type unsupported by the applicable underlying GSS-API mechanism(s), so theGSS_Add_cred()operation couldn't be performed for that name. 🙈GSS_S_BAD_NAMEmeans the provideddesired_nameis inconsistent in terms of its internally-incorporated type specifier information, so theGSS_Add_cred()operation couldn't be performed for that name. 🙈GSS_S_NO_CREDmeans theinput_cred_handlereferenced invalid or inaccessible credentials. 🔒GSS_S_FAILUREmeans the operation failed for reasons unspecified at the GSS-API level, including a lack of authorization to establish or use credentials representing the requested identity. 🚫
GSS_Add_cred() lets callers build credentials iteratively by adding credential elements in successive operations, one for each different mechanism. This is especially useful in multi-mechanism environments, because the major_status and minor_status values returned on each iteration are individually visible, so they can 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. 🫶
2.1.5: GSS_Inquire_cred_by_mech call 🔍
Inputs:
cred_handleCREDENTIAL HANDLE: NULL specifies that the credential elements used when default credential behavior is requested are to be queried. 🎀mech_typeOBJECT IDENTIFIER: the specific mechanism for which credentials are being queried. 🦋
Outputs:
major_statusINTEGER 🌸minor_statusINTEGER 🌸cred_nameINTERNAL NAME: guaranteed to be MN. 🍓lifetime_rec_initiateINTEGER: in seconds, or the reserved value for INDEFINITE ⏳lifetime_rec_acceptINTEGER: in seconds, or the reserved value for INDEFINITE ⏳cred_usageINTEGER: 0=INITIATE-AND-ACCEPT, 1=INITIATE-ONLY, 2=ACCEPT-ONLY 🌈
Return major_status codes:
GSS_S_COMPLETEmeans the credentials referenced by the inputcred_handleargument were valid, the mechanism indicated by the inputmech_typewas represented with elements within those credentials, and the outputcred_name,lifetime_rec_initiate,lifetime_rec_accept, andcred_usagevalues represent, respectively, the credentials' associated principal name, remaining lifetimes, and suitable usage modes. 👑GSS_S_NO_CREDmeans no information could be returned about the referenced credentials, either because the inputcred_handlewas invalid or because the caller lacks authorization to access them. 🔒GSS_S_DEFECTIVE_CREDENTIALmeans the referenced credentials are invalid. 💀GSS_S_CREDENTIALS_EXPIREDmeans the referenced credentials have expired. ⌛GSS_S_BAD_MECHmeans the referenced credentials don't contain elements for the requested mechanism. 🙈GSS_S_FAILUREmeans the operation failed for reasons unspecified at the GSS-API level. 🚫
The GSS_Inquire_cred_by_mech() call lets callers in multi-mechanism environments pull specific data about the available combinations of lifetimes, usage modes, and mechanisms within a credential structure. The lifetime_rec_initiate result shows the available lifetime for context initiation purposes, and the lifetime_rec_accept result shows the available lifetime for context acceptance purposes. 🧚💜
2.2: Context-level calls 🦋
This group of calls is all about establishing and managing security contexts between peers. A context's initiator calls GSS_Init_sec_context(), which generates a token that 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 the specified options, additional token exchanges may happen during context establishment. Those exchanges are handled 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 needed. 🧹 GSS_Process_context_token() processes received tokens that carry context-level control information. GSS_Context_time() lets a caller find out how long an established context will stay valid. ⏳ GSS_Inquire_context() returns status information describing the context's characteristics. GSS_Wrap_size_limit() lets a caller work out the size of a token that a GSS_Wrap() operation will generate. Finally, GSS_Export_sec_context() and GSS_Import_sec_context() make it possible to transfer active contexts between processes on an end system. 🚚✨
2.2.1: GSS_Init_sec_context call 🌷
Inputs:
claimant_cred_handleCREDENTIAL HANDLE: NULL specifies "use default". 🎀input_context_handleCONTEXT HANDLE: 0 specifies "none assigned yet". 🍓targ_nameINTERNAL NAME 🧚mech_typeOBJECT IDENTIFIER: a NULL parameter specifies "use default". 🦋deleg_req_flagBOOLEAN 💌mutual_req_flagBOOLEAN 💌replay_det_req_flagBOOLEAN 💌sequence_req_flagBOOLEAN 💌anon_req_flagBOOLEAN 💌lifetime_reqINTEGER: 0 specifies the default lifetime. ⏳chan_bindingsOCTET STRING 🔗input_tokenOCTET STRING: NULL, or a token received from the target. 📨
Outputs:
major_statusINTEGER 🌸minor_statusINTEGER 🌸output_context_handleCONTEXT HANDLE 🫧mech_typeOBJECT IDENTIFIER: the actual mechanism is always indicated, never NULL. 👑output_tokenOCTET STRING: NULL, or a token to pass to the context target. 📨deleg_stateBOOLEAN 💌mutual_stateBOOLEAN 💌replay_det_stateBOOLEAN 💌sequence_stateBOOLEAN 💌anon_stateBOOLEAN 💌trans_stateBOOLEAN 💌prot_ready_stateBOOLEAN: see Section 1.2.7. 🛡️conf_availBOOLEAN 💌integ_availBOOLEAN 💌lifetime_recINTEGER: in seconds, or the reserved value for INDEFINITE ⏳
This call may block while it waits on network interactions for those mech_type values where an authentication server or another network entity has to be consulted on behalf of the context initiator, so that an output_token suitable for presentation to a specified target can be generated. 🌐⏳
Return major_status codes:
GSS_S_COMPLETEmeans the context-level information was successfully initialized, and the returnedoutput_tokengives the target enough information to perform per-message processing on the newly-established context. 🎉GSS_S_CONTINUE_NEEDEDmeans the control information in the returnedoutput_tokenmust be sent to the target, and a reply must be received and passed as theinput_tokenargument to a continuation call toGSS_Init_sec_context()before per-message processing can happen with this context. 🔁GSS_S_DEFECTIVE_TOKENmeans the consistency checks performed on theinput_tokenfailed, so no further processing can be done based on that token. 💀GSS_S_DEFECTIVE_CREDENTIALmeans the consistency checks performed on the credential structure referenced byclaimant_cred_handlefailed, so no further processing can be done using that credential structure. 💀GSS_S_BAD_SIGmeans the receivedinput_tokencontains an incorrect integrity check, so context setup can't be completed. 🚨GSS_S_NO_CREDmeans no context was established, either because the inputcred_handlewas invalid, because the referenced credentials are valid for context acceptor use only, or because the caller lacks authorization to access the referenced credentials. 🔒GSS_S_CREDENTIALS_EXPIREDmeans the credentials provided through the inputclaimant_cred_handleargument are no longer valid, so context establishment can't be completed. ⌛GSS_S_BAD_BINDINGSmeans a mismatch was detected between the caller-providedchan_bindingsand those extracted from the inputinput_token. This is a security-relevant event and it prevents context establishment. (This result will be returned byGSS_Init_sec_contextonly for contexts wheremutual_stateis TRUE.) 🚨🙈GSS_S_OLD_TOKENmeans theinput_tokenis too old to be checked for integrity. This is a fatal error during context establishment. 💀GSS_S_DUPLICATE_TOKENmeans the input token has a correct integrity check but is a duplicate of a token that has already been processed. This is a fatal error during context establishment. 💀GSS_S_NO_CONTEXTmeans no valid context was recognized for the inputcontext_handleprovided. This major status will be returned only for successor calls followingGSS_S_CONTINUE_NEEDEDstatus returns. 🔍GSS_S_BAD_NAMETYPEmeans the providedtarg_nameis of a type that is uninterpretable or unsupported by the applicable underlying GSS-API mechanism(s), so context establishment can't be completed. 🙈GSS_S_BAD_NAMEmeans thetarg_nameyou gave is inconsistent with its own internally-incorporated type specifier info, so context establishment can't be completed 💀GSS_S_BAD_MECHmeans we got a context establishment token, or a caller request, that specifies a mechanism the local system doesn't support, or that your active credentials can't use 🙈GSS_S_FAILUREmeans context setup couldn't be completed for reasons GSS-API doesn't spell out, and there's no interface-defined recovery action available 😭
This routine is used by a context initiator, and it usually spits out one (or, for a multi-step exchange, more than one) output_token for the target, written in the selected mech_type's protocol 🎀 Using the info in the credentials structure referenced by claimant_cred_handle, GSS_Init_sec_context() sets up the data structures it needs to establish a security context with target targ_name ✨ The targ_name can be any valid INTERNAL NAME. It doesn't have to be an MN 🧚 The claimant_cred_handle has to point to the same valid credentials structure on the initial GSS_Init_sec_context() call and on any successor calls that come from GSS_S_CONTINUE_NEEDED status returns. Different protocol sequences modeled by the GSS_S_CONTINUE_NEEDED facility need access to credentials at different points in the context establishment sequence, so this matters a lot 🦋
The input_context_handle argument is 0, meaning "not yet assigned", on the first GSS_Init_sec_context() call for a given context 🌸 If it works (meaning it comes back with major_status GSS_S_COMPLETE or GSS_S_CONTINUE_NEEDED), and only if it works, that initial call returns a non-zero output_context_handle for future references to this context 💖 Once you've got a non-zero output_context_handle, GSS-API callers should call GSS_Delete_sec_context() to release context-related resources if errors happen in later phases of context establishment, or when an established context isn't needed anymore 🧹
When continuation attempts to GSS_Init_sec_context() are needed to finish context establishment, the previously-returned non-zero handle value goes into the input_context_handle argument, and it gets echoed back in the returned output_context_handle argument 🔁 On those continuation attempts (and only on those), the input_token value is used to pass along the token returned from the context's target 📨
The chan_bindings argument is how the caller provides info that binds the security context to security-related characteristics (like addresses and cryptographic keys) of the underlying communications channel 🔐 See Section 1.1.6 of this document for more discussion of how this argument gets used 📖
The input_token argument holds a message received from the target, and it only matters on a GSS_Init_sec_context() call that follows an earlier return with a GSS_S_CONTINUE_NEEDED major_status 💬
It's the caller's job to set up a communications path to the target, and to send any returned output_token to the target over that path, no matter what major_status came back with it 🛤️ The output_token can, however, ride along with the first application-provided input message handed to GSS_GetMIC() or GSS_Wrap() on a successfully-established context 🎀
The initiator can ask for 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 asks that replay detection features get applied to messages sent on the established context, and the sequence_req_flag asks that sequencing be enforced 🔥 (See Section 1.2.3 for more on replay detection and sequencing features.) The anon_req_flag requests that the initiator's identity not be transferred within tokens sent to the acceptor 🙈
Not every optional feature is available in every underlying mech_type 😅 The return state values deleg_state, mutual_state, replay_det_state, and sequence_state tell you, based on the mech_type's processing capabilities and the initiator's input flags, which features will actually be active on the context 👑 The returned trans_state value tells you whether the context can be transferred to other processes using GSS_Export_sec_context() 🦋 These state indicators are undefined unless the routine's major_status is GSS_S_COMPLETE, or unless TRUE prot_ready_state is returned along with a GSS_S_CONTINUE_NEEDED major_status. In that latter case, extra features that weren't confirmed or indicated along with the TRUE prot_ready_state might get confirmed and indicated later, when GSS_S_COMPLETE is returned 🌈
The returned anon_state and prot_ready_state values matter for both GSS_S_COMPLETE and GSS_S_CONTINUE_NEEDED major_status returns from GSS_Init_sec_context() 💜 When anon_state comes back TRUE, that means neither the current token nor its predecessors deliver, or have delivered, the initiator's identity 🙈 If you only want to do context establishment when anonymity support is provided, only send a returned token from GSS_Init_sec_context() to the peer when it's accompanied by a TRUE anon_state indicator 🫶 When prot_ready_state comes back TRUE alongside a GSS_S_CONTINUE_NEEDED major_status, per-message protection operations may be applied on the context. See Section 1.2.7 for more on this facility 🛡️
Failing to provide the exact set of features the caller asked for does not make context establishment fail. If the feature set you got isn't suitable for your use, it's your call to delete the context ✨
The returned mech_type value tells you the specific mechanism used on the context. It's only valid along with major_status GSS_S_COMPLETE, and it will never be the value for "default" 🎀 Heads up: for certain mechanisms that do their own negotiation, the returned mech_type may show a mechanism identified by an OID different from the one passed in the input mech_type argument 👀
The conf_avail return value says whether the context supports per-message confidentiality services. It tells the caller whether a request for encryption through the conf_req_flag input to GSS_Wrap() can be honored 🔒 In a similar way, the integ_avail return value says whether per-message integrity services are available (through either GSS_GetMIC() or GSS_Wrap()) on the established context ✅ These state indicators are undefined unless the routine's major_status is GSS_S_COMPLETE, or unless TRUE prot_ready_state is returned along with a GSS_S_CONTINUE_NEEDED major_status 🌸
The lifetime_req input specifies a desired upper bound for the lifetime of the context to be established. A value of 0 asks for a default lifetime ⏳ The lifetime_rec return value tells you how long the context will be valid, expressed as an offset from the present. Depending on mechanism capabilities, credential lifetimes, and local policy, it may not match the value requested in lifetime_req 🧃 If no constraints on context lifetime are imposed, that can be shown by returning a reserved value representing INDEFINITE lifetime_req. The value of lifetime_rec is undefined unless the routine's major_status is GSS_S_COMPLETE 💅
If the mutual_state is TRUE, this fact gets reflected within the output_token. A call to GSS_Accept_sec_context() at the target, in conjunction with such a context, returns a token. That token gets processed by a continuation call to GSS_Init_sec_context() to achieve mutual authentication 🤝🫶
2.2.2. GSS_Accept_sec_context call ✨
okay bestie, this is the receiving end of the handshake 💖 the context target calls this to check what the initiator sent. here's the signature, copied exactly because every field name matters 🎀
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 STRINGOutputs:
o major_status INTEGER,
o minor_status INTEGER,
o src_name INTERNAL NAME, -- guaranteed to be MN
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
initiatorThis call might block while waiting on network stuff for those mech_types where a directory service or some other network entity has to be checked, on behalf of the context acceptor, to validate the input_token it got 🌐
Return major_status codes:
GSS_S_COMPLETEmeans the context-level data structures got set up successfully, so per-message processing can now happen with this context 🎉GSS_S_CONTINUE_NEEDEDmeans the control info in the returned output_token has to go back to the initiator, and a response has to come in and be passed as the input_token to a continuation call toGSS_Accept_sec_context()before per-message processing can happen on this context 🔁GSS_S_DEFECTIVE_TOKENmeans the consistency checks on the input_token failed, so nothing else can be done based on that token 💀GSS_S_DEFECTIVE_CREDENTIALmeans the consistency checks on the credential structure referenced by acceptor_cred_handle failed, so that structure can't be used for further processing 🙈GSS_S_BAD_SIGmeans the input_token has an incorrect integrity check, so context setup can't happen 🚫GSS_S_DUPLICATE_TOKENmeans the integrity check passed, but the input_token got recognized as a duplicate of one already processed. no new context gets established 👯GSS_S_OLD_TOKENmeans the integrity check passed, but the input_token is too old to be checked for duplicates against the ones already processed. no new context gets established 🕰️GSS_S_NO_CREDmeans no context was established, either because the input cred_handle was invalid, because the referenced credentials are only valid for context initiator use, or because the caller isn't authorized to access those credentials 🔐GSS_S_CREDENTIALS_EXPIREDmeans the credentials given through the input acceptor_cred_handle are no longer valid, so context establishment can't be finished ⏰GSS_S_BAD_BINDINGSmeans the caller-provided chan_bindings don't match the ones pulled out of the input_token. that's a security-relevant event, and it stops context establishment 🚨GSS_S_NO_CONTEXTmeans no valid context was recognized for the input context_handle. this status only comes back on successor calls after aGSS_S_CONTINUE_NEEDEDreturn 🫥GSS_S_BAD_MECHmeans the context establishment token asks for a mechanism that the local system doesn't support, or that doesn't work with the caller's active credentials 🙅♀️GSS_S_FAILUREmeans context setup couldn't be done for reasons that aren't specified at the GSS-API level, and there's no interface-defined recovery action available 😭
The GSS_Accept_sec_context() routine is used by a context target. Using the information in the credentials structure referenced by the input acceptor_cred_handle, it checks the incoming input_token and, once a context establishment sequence has finished successfully, returns the authenticated src_name and the mech_type that was used. The returned src_name is guaranteed to be an MN, processed by the mechanism the context was established under 🦋 the acceptor_cred_handle has to point to the same valid credentials structure on the initial call to GSS_Accept_sec_context() and on every successor call that follows a GSS_S_CONTINUE_NEEDED return. different protocol sequences that go through the GSS_S_CONTINUE_NEEDED mechanism need access to credentials at different points in the context establishment sequence, so this matters a lot 💅
The input_context_handle argument is 0, which means "not yet assigned", on the first GSS_Accept_sec_context() call for a given context. if the call succeeds (meaning it comes with major_status GSS_S_COMPLETE or GSS_S_CONTINUE_NEEDED), and only then, the initial GSS_Accept_sec_context() call returns a non-zero output_context_handle to use for future references to this context ✨ once a non-zero output_context_handle has come back, GSS-API callers should call GSS_Delete_sec_context() to free up context-related resources if errors happen in later phases of context establishment, or when an established context isn't needed anymore 🧹
The chan_bindings argument is how the caller binds the security context to security-related characteristics (for example, addresses or cryptographic keys) of the underlying communications channel. see Section 1.1.6 of this document for more on how this argument gets used 🔗
The returned state results (deleg_state, mutual_state, replay_det_state, sequence_state, anon_state, trans_state, and prot_ready_state) mean the same thing they do for GSS_Init_sec_context(), and their values matter under the same return state conditions 🎀
The conf_avail return value tells the caller whether the context supports per-message confidentiality services. that means it tells you if a request for encryption through the conf_req_flag input to GSS_Wrap() can actually be honored 🔒 in a similar way, the integ_avail return value tells you whether per-message integrity services are available on the established context (through either GSS_GetMIC() or GSS_Wrap()). these values matter under the same return state conditions as described under GSS_Init_sec_context() 🧐
The lifetime_rec return value only matters alongside a GSS_S_COMPLETE major_status. it says how long the context will be valid, written as an offset from the present ⏳
The mech_type return value shows which specific mechanism got used on the context. it's only valid along with major_status GSS_S_COMPLETE, and it will never show the value for "default" 🙌
The delegated_cred_handle result only matters when deleg_state is TRUE, and it gives the target a way to reference the delegated credentials 🤝 the output_token result, when it isn't NULL, is a context-level token to send back to the context initiator so a multi-step context establishment sequence can keep going 🛤️ like with GSS_Init_sec_context(), any returned token should be transferred to the context's peer (in this case, the context initiator), no matter what the accompanying returned major_status is 📬
Note: a target has to be able to tell a context-level input_token (the stuff passed toGSS_Accept_sec_context()) apart from the per-message data elements passed toGSS_VerifyMIC()orGSS_Unwrap(). these data elements might show up in a single application message, andGSS_Accept_sec_context()must be done before per-message processing can work successfully 👀
2.2.3. GSS_Delete_sec_context call 🧹
this one's the cleanup crew 💜 it flushes the context info when you're done with it. here's the signature, verbatim 🎀
Input:
o context_handle CONTEXT HANDLEOutputs:
o major_status INTEGER,
o minor_status INTEGER,
o output_context_token OCTET STRINGReturn major_status codes:
GSS_S_COMPLETEmeans the context was recognized, and the relevant context-specific info got flushed. if the caller gives a non-null buffer to receive an output_context_token, and the mechanism puts a non-NULL token in that buffer, the returned output_context_token is ready to be transferred to the context's peer 📦GSS_S_NO_CONTEXTmeans no valid context was recognized for the input context_handle, so nothing got deleted 🫥GSS_S_FAILUREmeans the context was recognized, butGSS_Delete_sec_context()couldn't be done for reasons that aren't specified at the GSS-API level 😭
This call might block while waiting on network interactions for mech_types where a central server has to get actively notified when a security context is about to be deleted 🌐
Either peer in a security context can make this call to flush context-specific info 💁♀️ if the caller passes a non-null output_context_token parameter, an output_context_token may come back to the caller. if the caller gets an output_context_token, they can pass it to the context's peer so the peer's GSS-API implementation knows it can flush its matching context info too 🔁 (once a context is established, the peers are expected to keep cached credential and context-related info until its expiration time is reached, or until a GSS_Delete_sec_context() call happens 🕰️)
The facility for using a context_token to signal context deletion is kept around for compatibility with GSS-API Version 1. for current usage, it is recommended that both peers to a context call GSS_Delete_sec_context() independently, passing a null output_context_token buffer to show that no context_token is needed 🙌 implementations of GSS_Delete_sec_context() should delete the relevant locally-stored context info 🧼
Attempts to do per-message processing on a deleted context will return errors 🚫💅
2.2.4. GSS_Process_context_token call ✨
Let's talk about the GSS_Process_context_token call, bestie 💖 It's a context-level call, so it's all about what happens to a context once it already exists. Think of it as the "okay, I got a message from my bestie, let me update my notes" moment 🧚
Inputs:
context_handleCONTEXT HANDLE 🎀input_context_tokenOCTET STRING 💜
Outputs:
major_statusINTEGER 🌸minor_statusINTEGER 🦋
Return major_status codes:
GSS_S_COMPLETEmeans theinput_context_tokengot successfully processed alongside the context pointed to bycontext_handle✨ slay.GSS_S_DEFECTIVE_TOKENmeans the consistency checks on the received context_token failed 💀, so the token can't be processed any further. Not a vibe.GSS_S_NO_CONTEXTmeans no valid context got recognized for theinput_context_token/context_handleyou gave it 🙈. Literally nobody home.GSS_S_FAILUREmeans the context is recognized, but theGSS_Process_context_token()operation couldn't be performed for reasons that aren't specified at the GSS-API level 😭. Something went sideways, and the spec just doesn't say what.
So this call is used to process context_tokens received from a peer once a context has been established, and it has corresponding impact on the context-level state info 🫶. Iconic behavior, honestly.
One big use for this facility is processing the context_tokens generated by GSS_Delete_sec_context() 🍓. Important detail: GSS_Process_context_token() will not block pending network interactions for that purpose. No waiting around, it just does its thing ✨.
The other use is processing tokens that tell you about remote-peer context establishment failures, which can show up after the local GSS-API implementation has already said GSS_S_COMPLETE 👑. Plot twist, but it's giving realistic 💅.
2.2.5. GSS_Context_time call ⏰
Okay, bestie, this one is your "how much longer do I have?" check 💅 You hand it a context and it tells you how many seconds are left, or that it's INDEFINITE.
Input and outputs:
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
INDEFINITEReturn major_status codes:
GSS_S_COMPLETEmeans the context is valid and will stay valid for the amount of time inlifetime_rec✨GSS_S_CONTEXT_EXPIREDmeans the data items for that context have expired 💀GSS_S_CREDENTIALS_EXPIREDmeans the context is recognized, but its credentials have expired 🙈GSS_S_NO_CONTEXTmeans no valid context was recognized for thecontext_handleyou gave itGSS_S_FAILUREmeans the operation failed for reasons that aren't specified at the GSS-API level
This call is used to figure out how long an established context is going to keep working 🦋
2.2.6. GSS_Inquire_context call 🔍
This is the nosy-but-useful one. You pass in a context and it spills all the tea about it: who started it, who it's for, how long it lasts, and what it can do 🫶
Input and outputs:
Input:
o context_handle CONTEXT HANDLE,
Outputs:
o major_status INTEGER,
o minor_status INTEGER,
o src_name INTERNAL NAME, -- name of context initiator,
-- guaranteed to be MN
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 acceptorReturn major_status codes:
GSS_S_COMPLETEmeans the context is valid, andsrc_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, andlocally_initiatedall describe the matching characteristics of the context 👑GSS_S_CONTEXT_EXPIREDmeans thecontext_handleyou passed in is recognized, but the context has expired. Return values other thanmajor_statusandminor_statusare undefined.GSS_S_NO_CONTEXTmeans no valid context was recognized for thecontext_handleyou provided. Return values other thanmajor_statusandminor_statusare undefined.GSS_S_FAILUREmeans the operation failed for reasons that aren't specified at the GSS-API level. Return values other thanmajor_statusandminor_statusare undefined.
This call is used to pull out information that describes the characteristics of a security context 🎀
2.2.7. GSS_Wrap_size_limit call 📏
This one answers a really practical question: if I want my output to stay under a certain size, how big can my input be? 🧚
Inputs and outputs:
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 INTEGERReturn major_status codes:
GSS_S_COMPLETEmeans the token size was figured out successfully. An input message whose length in octets equals the returnedmax_input_sizevalue will, when passed toGSS_Wrap()on the context named bycontext_handleand with the quality of protection specifier fromqop, yield an output token no larger than the value of theoutput_sizeparameter you provided 🍓GSS_S_CONTEXT_EXPIREDmeans thecontext_handleyou provided is recognized, but the context has expired. Return values other thanmajor_statusandminor_statusare undefined.GSS_S_NO_CONTEXTmeans no valid context was recognized for thecontext_handleyou provided. Return values other thanmajor_statusandminor_statusare undefined.GSS_S_BAD_QOPmeans theqopvalue isn't recognized or supported for the context 🙅GSS_S_FAILUREmeans the operation failed for reasons that aren't specified at the GSS-API level. Return values other thanmajor_statusandminor_statusare undefined.
This call is used to find the biggest input you can pass to GSS_Wrap() without the output token getting bigger than a size you choose 💖
2.2.8. GSS_Export_sec_context call 📦
Okay, this is the "hand my context off to another process" move 🦋 It packs up a context into an interprocess token so another process on the same machine can take it over.
Input and outputs:
Inputs:
o context_handle CONTEXT HANDLE
Outputs:
o major_status INTEGER,
o minor_status INTEGER,
o interprocess_token OCTET STRINGReturn major_status codes:
GSS_S_COMPLETEmeans the context was successfully exported into theinterprocess_tokenand you can't use it anymore on your end 🫠GSS_S_UNAVAILABLEmeans the context export facility isn't available for the context. (This status should only happen for contexts wheretrans_stateis FALSE.) Return values other thanmajor_statusandminor_statusare undefined.GSS_S_CONTEXT_EXPIREDmeans thecontext_handleyou provided is recognized, but the context has expired. Return values other thanmajor_statusandminor_statusare undefined.GSS_S_NO_CONTEXTmeans no valid context was recognized for thecontext_handleyou provided. Return values other thanmajor_statusandminor_statusare undefined.GSS_S_FAILUREmeans the operation failed for reasons that aren't specified at the GSS-API level. Return values other thanmajor_statusandminor_statusare undefined.
This call makes an interprocess token for transfer to another process inside the same end system, so control of a security context can move over to that process. The recipient calls GSS_Import_sec_context() to accept the handoff 🎁 The GSS_Export_sec_context() operation is only meant for contexts that are fully and successfully established, meaning the ones where GSS_Init_sec_context() and GSS_Accept_sec_context() have returned a GSS_S_COMPLETE major_status.
Heads up, bestie: to keep things portable, a caller ofGSS_Export_sec_context()must not assume the context can keep being used after the export. Once it's exported, the context referenced by thecontext_handlecan't be assumed to still be valid. Portable callers also must not assume that a given interprocess token can be imported byGSS_Import_sec_context()more than once, which would create multiple copies of one context. GSS-API implementations may detect and reject repeated imports, but they aren't required to do so 🚫
The internal representation inside the interprocess token is an implementation-defined local matter. You can't assume interprocess tokens will transfer between different GSS-API implementations 🙈
It's recommended that GSS-API implementations adopt policies that fit their operating environment to decide which processes are allowed to import a context. The specific constraints here are local matters. Some examples are transfers between processes running for the same user identity, or processes that are part of a common job. However, it may be impossible to enforce these policies in some implementations.
To help with the goals above, implementations may protect the transferred context data with cryptography inside the interprocess token. They can also use interprocess tokens as references to local interprocess communication facilities, which are protected some other way, instead of storing the context data directly in the token 🔐
Transferring an open context may, for certain mechanisms and implementations, reveal data about the credential that was used to establish the context. So callers should be cautious about how trustworthy the processes they transfer contexts to are 👀 The GSS-API implementation may provide its own protections over the exported context, but the caller is responsible for protecting the interprocess token from disclosure and for making sure the context goes to an appropriate destination process. That's a whole lot of responsibility, iykyk 💅
2.2.9. GSS_Import_sec_context call 📥
This is the receiving end of the handoff. You give it an interprocess token and it makes the transferred context available to you 🫶
Inputs and outputs:
Inputs:
o interprocess_token OCTET STRING
Outputs:
o major_status INTEGER,
o minor_status INTEGER,
o context_handle CONTEXT HANDLEReturn major_status codes:
GSS_S_COMPLETEmeans the context represented by the inputinterprocess_tokenwas successfully transferred to you, and you can use it from now on through the outputcontext_handle✨GSS_S_CONTEXT_EXPIREDmeans the context represented by the inputinterprocess_tokenhas expired. Return values other thanmajor_statusandminor_statusare undefined.GSS_S_NO_CONTEXTmeans the context represented by the inputinterprocess_tokenwas invalid. Return values other thanmajor_statusandminor_statusare undefined.GSS_S_DEFECTIVE_TOKENmeans the inputinterprocess_tokenwas defective. Return values other thanmajor_statusandminor_statusare undefined.GSS_S_UNAVAILABLEmeans the context import facility isn't available for use on the referenced context. Return values other thanmajor_statusandminor_statusare undefined.GSS_S_UNAUTHORIZEDmeans the context represented by the inputinterprocess_tokenisn't authorized to be transferred to you. Return values other thanmajor_statusandminor_statusare undefined. 🚷GSS_S_FAILUREmeans the operation failed for reasons that aren't specified at the GSS-API level. Return values other thanmajor_statusandminor_statusare undefined.
This call processes an interprocess token that GSS_Export_sec_context() generated, and makes the transferred context available for the caller to use. After a successful GSS_Import_sec_context() operation, the imported context is ready for the importing process to use 🎀
For more on the security and authorization issues around this call, check out the discussion in Section 2.2.8. Seriously, read it, it's giving important 🙈
2.3. Per-message calls 🎀
Okay so this group of calls is all about per-message protection processing on a security context that's already established 💅 None of these calls block waiting on network interactions. They can be invoked by a context's initiator or by the context's target 🫶 The four members are really 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 with data items that let the underlying mechanisms provide the specified security services. The original message and the generated per-message token then go to the remote peer, and GSS_VerifyMIC() checks the message against that separate token 💜
GSS_Wrap() and GSS_Unwrap() add caller-requested confidentiality on top of the data origin authentication and data integrity services that GSS_GetMIC() and GSS_VerifyMIC() already give you 👑 GSS_Wrap() outputs a single data element that encapsulates optionally enciphered user data, plus its associated token data items. That element goes to the remote peer and gets processed by GSS_Unwrap() on that system. GSS_Unwrap() combines decipherment (as required) with validation of the data items related to authentication and integrity 🦋
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:
context_handle CONTEXT HANDLE,qop_req INTEGER,-0 specifies default QOPmessage OCTET STRING
Outputs:
major_status INTEGER,minor_status INTEGER,per_msg_token OCTET STRING
Return major_status codes:
GSS_S_COMPLETEindicates 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 ✅GSS_S_CONTEXT_EXPIREDindicates that context-related data items have expired, so the requested operation cannot be performed 💀GSS_S_CREDENTIALS_EXPIREDindicates that the context is recognized, but its associated credentials have expired, so the requested operation cannot be performed 🥀GSS_S_NO_CONTEXTindicates that no valid context was recognized for the input context_handle provided 🙈GSS_S_BAD_QOPindicates that the provided QOP value is not recognized or supported for the context 🍓GSS_S_FAILUREindicates that the context is recognized, but the requested operation could not be performed for reasons unspecified at the GSS-API level 😭
Using the security context referenced by context_handle, apply an integrity check to the input message (along with timestamps and/or other data included in support of mech_type-specific mechanisms) and return the result in per_msg_token. The qop_req parameter, whose interpretation 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 are 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:
context_handle CONTEXT HANDLE,message OCTET STRING,per_msg_token OCTET STRING
Outputs:
qop_state INTEGER,major_status INTEGER,minor_status INTEGER,
Return major_status codes:
GSS_S_COMPLETEindicates that the message was successfully verified 🎉GSS_S_DEFECTIVE_TOKENindicates that consistency checks performed on the received per_msg_token failed, preventing further processing from being performed with that token 🚫GSS_S_BAD_SIGindicates that the received per_msg_token contains an incorrect integrity check for the message 😤GSS_S_DUPLICATE_TOKEN,GSS_S_OLD_TOKEN,GSS_S_UNSEQ_TOKEN, andGSS_S_GAP_TOKENvalues appear in conjunction with the optional per-message replay detection features described in Section 1.2.3. Their semantics are described in that section 🔁GSS_S_CONTEXT_EXPIREDindicates that context-related data items have expired, so the requested operation cannot be performed 💀GSS_S_CREDENTIALS_EXPIREDindicates that the context is recognized, but its associated credentials have expired, so the requested operation cannot be performed 🥀GSS_S_NO_CONTEXTindicates that no valid context was recognized for the input context_handle provided 🙈GSS_S_FAILUREindicates that the context is recognized, but 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.
Inputs:
context_handle CONTEXT HANDLE,conf_req_flag BOOLEAN,qop_req INTEGER,-0 specifies default QOPinput_message OCTET STRING
Outputs:
major_status INTEGER,minor_status INTEGER,conf_state BOOLEAN,output_message OCTET STRING
Return major_status codes:
GSS_S_COMPLETEindicates that the input_message was successfully processed and that the output_message is ready for transmission 📦GSS_S_CONTEXT_EXPIREDindicates that context-related data items have expired, so the requested operation cannot be performed 💀GSS_S_CREDENTIALS_EXPIREDindicates that the context is recognized, but its associated credentials have expired, so the requested operation cannot be performed 🥀GSS_S_NO_CONTEXTindicates that no valid context was recognized for the input context_handle provided 🙈GSS_S_BAD_QOPindicates that the provided QOP value is not recognized or supported for the context 🍓GSS_S_FAILUREindicates that the context is recognized, but 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, it requests that confidentiality be applied to the input_message 🤫 Confidentiality may not be supported in all mech_types or by all implementations, so the returned conf_state flag tells you whether confidentiality was actually provided for the input_message. The qop_req parameter, whose interpretation 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:
context_handle CONTEXT HANDLE,input_message OCTET STRING
Outputs:
conf_state BOOLEAN,qop_state INTEGER,major_status INTEGER,minor_status INTEGER,output_message OCTET STRING
Return major_status codes:
GSS_S_COMPLETEindicates that the input_message was successfully processed and that the resulting output_message is available 🎀GSS_S_DEFECTIVE_TOKENindicates that consistency checks performed on the per_msg_token extracted from the input_message failed, preventing further processing from being performed 🚫GSS_S_BAD_SIGindicates that an incorrect integrity check was detected for the message 😤GSS_S_DUPLICATE_TOKEN,GSS_S_OLD_TOKEN,GSS_S_UNSEQ_TOKEN, andGSS_S_GAP_TOKENvalues appear in conjunction with the optional per-message replay detection features described in Section 1.2.3. Their semantics are described in that section 🔁GSS_S_CONTEXT_EXPIREDindicates that context-related data items have expired, so the requested operation cannot be performed 💀GSS_S_CREDENTIALS_EXPIREDindicates that the context is recognized, but its associated credentials have expired, so the requested operation cannot be performed 🥀GSS_S_NO_CONTEXTindicates that no valid context was recognized for the input context_handle provided 🙈GSS_S_FAILUREindicates that the context is recognized, but 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. It 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 🎀
okay so this group of calls is the support squad 💅 They're useful to GSS-API callers no matter what state any established contexts are in. Also, the original doesn't say anything about whether these calls block or don't block while talking to the network, so that part is just left unspecified 🤷♀️
2.4.1. GSS_Display_status call ✨
Inputs:
status_value INTEGER,-GSS-API major_status or minor_status return valuestatus_type INTEGER,-1 if major_status, 2 if minor_statusmech_type OBJECT IDENTIFIER-mech_type to be used for minor_status translation
Outputs:
major_status INTEGER,minor_status INTEGER,status_string_set SET OF OCTET STRING
Return major_status codes:
GSS_S_COMPLETEmeans you got a valid printable status representation ✅ It might cover more than one status event packed into thestatus_value, and it's sitting in the returnedstatus_string_set.GSS_S_BAD_MECHmeans you asked for translation under amech_typethat isn't supported, so the translation couldn't happen 😭GSS_S_BAD_STATUSmeans thestatus_valuewas invalid, or thestatus_typewas something other than 1 or 2. Either way, no translation 💀GSS_S_FAILUREmeans the operation couldn't be done, and the GSS-API level isn't going to tell you why 🫠
This call is how callers turn the major and minor status codes GSS-API hands back into printable strings. Main character energy for debugging 🦋
2.4.2. GSS_Indicate_mechs call 🌸
Input:
- (none)
Outputs:
major_status INTEGER,minor_status INTEGER,mech_set SET OF OBJECT IDENTIFIER
Return major_status codes:
GSS_S_COMPLETEmeans a set of available mechanisms came back inmech_set🍓GSS_S_FAILUREmeans the operation couldn't be done, and the GSS-API level won't say why 🫠
This one tells you which mechanism types exist on the local system. It's really for specialized callers who want a non-default mech_type set to hand to GSS_Acquire_cred(). Everyone else? You probably don't need it, bestie 💖
2.4.3. GSS_Compare_name call 🧚
Inputs:
name1 INTERNAL NAME,name2 INTERNAL NAME
Outputs:
major_status INTEGER,minor_status INTEGER,name_equal BOOLEAN
Return major_status codes:
GSS_S_COMPLETEmeansname1andname2were comparable, and thename_equalresult tells you whether they represent the same entity 👯GSS_S_BAD_NAMETYPEmeans one or both names had internal type specifiers that the underlying mechanism(s) can't interpret, OR the two types are different and can't be compared. Either way, the comparison didn't finish 🙈GSS_S_BAD_NAMEmeans one or both names were ill-formed in terms of their internal type specifier, so no comparison 💔GSS_S_FAILUREmeans the operation couldn't be done for reasons the GSS-API level doesn't spell out 😩
This call lets you compare two internal name representations and figure out if they point at the same entity. If either name passed to GSS_Compare_name() is an anonymous principal, GSS_Compare_name() SHALL indicate FALSE. Neither name1 nor name2 has to be an MN, and for some implementations and cases, GSS_S_BAD_NAMETYPE may be returned to say the names are incomparable when neither input is an MN. Not a bug, just how it works 🫶
2.4.4. GSS_Display_name call 🎀
Inputs:
name INTERNAL NAME
Outputs:
major_status INTEGER,minor_status INTEGER,name_string OCTET STRING,name_type OBJECT IDENTIFIER
Return major_status codes:
GSS_S_COMPLETEmeans a valid printable name representation is sitting inname_string✨GSS_S_BAD_NAMETYPEmeans the name's type is one the underlying mechanism(s) can't interpret, so no printable version could be made 😵GSS_S_BAD_NAMEmeans the name's contents don't match its internally indicated name type, so again, no printable version 💀GSS_S_FAILUREmeans the operation couldn't be done, and GSS-API won't tell you why 🫠
This call takes an internal name and turns it into a printable form with a namespace type descriptor attached. What the printable form looks like is a local matter, so the implementation gets to decide 💅
If the input name represents an anonymous identity, a reserved value (GSS_C_NT_ANONYMOUS) SHALL be returned for name_type. Anonymous names get their own special label, periodt 👑
2.4.5. GSS_Import_name call 🦋
Inputs:
input_name_string OCTET STRING,input_name_type OBJECT IDENTIFIER
Outputs:
major_status INTEGER,minor_status INTEGER,output_name INTERNAL NAME
Return major_status codes:
GSS_S_COMPLETEmeans a valid name representation came out inoutput_name, described by the type value inoutput_name_type✅GSS_S_BAD_NAMETYPEmeans theinput_name_typeisn't supported by the underlying mechanism(s), so the import couldn't finish 🙈GSS_S_BAD_NAMEmeans theinput_name_stringis ill-formed for theinput_name_type, so the import couldn't finish either 💔GSS_S_FAILUREmeans the operation couldn't be done for reasons the GSS-API level doesn't say 😩
This is the call where you hand over a name as a contiguous octet string, tell it what namespace to parse it in, and get back an internal form that the other GSS-API routines can use 🧚 The input_name_string syntax is tied to its name type. Depending on the type, it might be printable or it might not. Quick note: input_name_type only describes how to read input_name_string. It does NOT set the data type of the output_name you get back 👀
If a mechanism says it supports a particular name type, its GSS_Import_name() operation SHALL be able to accept every possible value that matches the external name syntax for that type. Those imported values might be:
- locally registered entities (you can acquire credentials for these),
- non-local entities (you can't get local credentials for these, but you can use them as targets of initiated security contexts or as initiators of accepted ones), or
- neither of the above.
Figuring out which of those three buckets a name falls into is NOT guaranteed to happen inside GSS_Import_name() 🤷♀️
The internal name from a GSS_Import_name() call may be a single-mechanism MN, and it's likely to be an MN in a single-mechanism implementation. Still, portable callers MUST NOT depend on that, and they MUST NOT assume the output of GSS_Import_name() can go straight into GSS_Export_name() without running it through GSS_Canonicalize_name() first. Do not skip the canonicalize step, bestie 🫶
2.4.6. GSS_Release_name call 🧹
Inputs:
name INTERNAL NAME
Outputs:
major_status INTEGER,minor_status INTEGER
Return major_status codes:
GSS_S_COMPLETEmeans the storage tied to the input name was released successfully 🫧GSS_S_BAD_NAMEmeans the input name argument didn't hold a valid name 💀GSS_S_FAILUREmeans the operation couldn't be done for unspecified GSS-API reasons 🫠
This call frees the storage behind an internal name representation. How it actually behaves depends on the language and environment the GSS-API implementation runs in, so the bindings specs have the details. In some bindings, where memory management is automatic, this call might be totally superfluous 🌈
2.4.7. GSS_Release_buffer call 🍓
Inputs:
buffer OCTET STRING
Outputs:
major_status INTEGER,minor_status INTEGER
Return major_status codes:
GSS_S_COMPLETEmeans the storage behind the input buffer was released successfully ✨GSS_S_FAILUREmeans the operation couldn't be done for unspecified GSS-API reasons 🫠
This one frees an OCTET STRING buffer that some other GSS-API call allocated. Same deal as before: the specific behaviour depends on the language and environment, so check the bindings specs. And yes, in bindings with automatic memory management it might be superfluous too 💅
2.4.8. GSS_Release_OID_set call 💜
Inputs:
buffer SET OF OBJECT IDENTIFIER
Outputs:
major_status INTEGER,minor_status INTEGER
Return major_status codes:
GSS_S_COMPLETEmeans the storage behind the input object identifier set was released successfully 🧹GSS_S_FAILUREmeans the operation couldn't be done for unspecified GSS-API reasons 🫠
This call frees an object identifier set that some other GSS-API call allocated. Its exact behaviour depends on the language and environment, so the bindings specifications cover it, and in bindings with automatic memory management it may be superfluous 🌸
2.4.9. GSS_Create_empty_OID_set call 🧚
Inputs:
- (none)
Outputs:
major_status INTEGER,minor_status INTEGER,oid_set SET OF OBJECT IDENTIFIER
Return major_status codes:
GSS_S_COMPLETEmeans it worked ✅GSS_S_FAILUREmeans the operation failed ❌
This call makes an object identifier set with zero object identifiers in it. After that, you can add members using GSS_Add_OID_set_member(). These routines are meant for building sets of mechanism OIDs to feed into GSS_Acquire_cred() 🦋
2.4.10. GSS_Add_OID_set_member call 💖
Inputs:
member_oid OBJECT IDENTIFIER,oid_set SET OF OBJECT IDENTIFIER
Outputs:
major_status INTEGER,minor_status INTEGER,
Return major_status codes:
GSS_S_COMPLETEmeans it worked ✅GSS_S_FAILUREmeans the operation failed ❌
This call adds an Object Identifier to an Object Identifier set. It's meant to go with GSS_Create_empty_OID_set() when you're putting together a set of mechanism OIDs for GSS_Acquire_cred() 🫶
2.4.11: GSS_Test_OID_set_member call ✨
okay bestie, this one is basically a bouncer 🔍 you hand it an OID and a set, and it tells you whether that OID is actually on the list 💅
Inputs:
memberOBJECT IDENTIFIER,setSET OF OBJECT IDENTIFIER
Outputs:
major_statusINTEGER,minor_statusINTEGER,presentBOOLEAN
Return major_status codes:
GSS_S_COMPLETEindicates successful completionGSS_S_FAILUREindicates that the operation failed
It pokes at an Object Identifier set to see if your member is in there 🫶 it's meant to be used with OID sets that come back from GSS_Indicate_mechs(), GSS_Acquire_cred(), and GSS_Inquire_cred(), iykyk 🌸
2.4.12: GSS_Release_OID call 🎀
Inputs:
oidOBJECT IDENTIFIER
Outputs:
major_statusINTEGER,minor_statusINTEGER
Return major_status codes:
GSS_S_COMPLETEindicates successful completionGSS_S_FAILUREindicates that the operation failed
this one lets the caller free up the storage behind an OBJECT IDENTIFIER buffer that some other GSS-API call allocated 🧹 how it actually works depends on the language and programming environment the GSS-API implementation lives in, so the details are in the applicable bindings specifications. honestly, this call may be superfluous within bindings where memory management is automatic 💜
2.4.13: GSS_OID_to_str call 🦋
Inputs:
oidOBJECT IDENTIFIER
Outputs:
major_statusINTEGER,minor_statusINTEGER,oid_strOCTET STRING
Return major_status codes:
GSS_S_COMPLETEindicates successful completionGSS_S_FAILUREindicates that the operation failed
so GSS_OID_to_str() gives you back a string showing the input OID in numeric ASN.1 syntax, wrapped in curly braces and space-delimited, like "{2 16 840 1 113687 1 2 1}" 🔢 you can release that string with GSS_Release_buffer(). if the input "oid" isn't a syntactically valid object identifier, you get GSS_S_FAILURE back and oid_str comes back as NULL 💀
2.4.14: GSS_Str_to_OID call 🧚
Inputs:
oid_strOCTET STRING
Outputs:
major_statusINTEGER,minor_statusINTEGER,oidOBJECT IDENTIFIER
Return major_status codes:
GSS_S_COMPLETEindicates successful completionGSS_S_FAILUREindicates that the operation failed
GSS_Str_to_OID() is the opposite move: it builds and returns an OID from its printable form ✨ implementations should be able to accept the numeric ASN.1 syntax form we just talked about in GSS_OID_to_str(), and that form should be used for portability. implementations may also accept other formats, like "1.2.3.3" 👀 the OID can be released with GSS_Release_OID(). if oid_str can't be translated into an OID, you get GSS_S_FAILURE and the "oid" result is NULL 😭
2.4.15: GSS_Inquire_names_for_mech call 🌈
Input:
input_mech_typeOBJECT IDENTIFIER, -- mechanism type
Outputs:
major_statusINTEGER,minor_statusINTEGER,name_type_setSET OF OBJECT IDENTIFIER
Return major_status codes:
GSS_S_COMPLETEindicates that the outputname_type_setcontains a list of name types which are supported by the locally available mechanism identified byinput_mech_type.GSS_S_BAD_MECHindicates that the mechanism identified byinput_mech_typewas unsupported within the local implementation, causing the query to fail.GSS_S_FAILUREindicates that the requested operation could not be performed for reasons unspecified at the GSS-API level.
this is how callers figure out which name types a specific, locally available mechanism can handle 🫶 main character energy for name types, honestly 👑
2.4.16: GSS_Inquire_mechs_for_name call 💖
Inputs:
input_nameINTERNAL NAME,
Outputs:
major_statusINTEGER,minor_statusINTEGER,mech_typesSET OF OBJECT IDENTIFIER
Return major_status codes:
GSS_S_COMPLETEindicates that a set of object identifiers, corresponding to the set of mechanisms suitable for processing theinput_name, is available inmech_types.GSS_S_BAD_NAMEindicates that theinput_namecould not be processed.GSS_S_BAD_NAMETYPEindicates that the type of theinput_nameis unsupported by the GSS-API implementation.GSS_S_FAILUREindicates that the requested operation could not be performed for reasons unspecified at the GSS-API level.
this one hands back the mechanism set that can process your input_name 🎯 once you're done with mech_types, the caller should free it with GSS_Release_OID_set(), no cap 🧼
Note: it is anticipated that implementations ofGSS_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 (viaGSS_Canonicalize_name()) a particular name. 🙈
2.4.17: GSS_Canonicalize_name call 💅
Inputs:
input_nameINTERNAL NAME,mech_typeOBJECT IDENTIFIER -- must be explicit mechanism, not "default" specifier
Outputs:
major_statusINTEGER,minor_statusINTEGER,output_nameINTERNAL NAME
Return major_status codes:
GSS_S_COMPLETEindicates that a mechanism-specific reduction of theinput_name, as processed by the mechanism identified bymech_type, is available inoutput_name.GSS_S_BAD_MECHindicates that the identified mechanism is unsupported.GSS_S_BAD_NAMETYPEindicates that the input name does not contain an element with suitable type for processing by the identified mechanism.GSS_S_BAD_NAMEindicates 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.GSS_S_FAILUREindicates that the requested operation could not be performed for reasons unspecified at the GSS-API level.
this routine takes a GSS-API internal name, which can hold elements for multiple mechanisms, and reduces it to a mechanism-specific Mechanism Name (MN) 🪄 it does this by applying the translations for whichever mechanism you pass in as mech_type. the mech_type has to be an explicit mechanism, not the "default" specifier 💜
2.4.18: GSS_Export_name call 🦋
Inputs:
input_nameINTERNAL NAME, -- required to be MN
Outputs:
major_statusINTEGER,minor_statusINTEGER,output_nameOCTET STRING
Return major_status codes:
GSS_S_COMPLETEindicates that a flat representation of the input name is available inoutput_name.GSS_S_NAME_NOT_MNindicates that the input name contained elements corresponding to multiple mechanisms, so cannot be exported into a single-mechanism flat form.GSS_S_BAD_NAMEindicates that the input name was an MN, but could not be processed.GSS_S_BAD_NAMETYPEindicates that the input name was an MN, but that its type is unsupported by the GSS-API implementation.GSS_S_FAILUREindicates that the requested operation could not be performed for reasons unspecified at the GSS-API level.
this routine makes a flat name representation from an internal-form Mechanism Name (MN), like the ones emitted by GSS_Canonicalize_name() or GSS_Accept_sec_context() 🫧 the result is suitable for bytewise comparison, or for feeding into GSS_Import_name() together with the reserved GSS-API Exported Name Object OID ✨ the flat name has to stay invariant over time within a particular installation, so the same MN always comes out the same 🔒
the emitted GSS-API Exported Name Object describes itself, so no parameter-level OID needs to be emitted by this call 🎀 the flat representation is a mechanism-independent wrapper layer, defined in Section 3.2 of this document, that encloses a mechanism-defined name representation 🌸
the GSS_S_NAME_NOT_MN status code is there so implementations can reject input names that aren't MNs. it isn't required for conformance, though, that all non-MN input names must necessarily be rejected 🙈
2.4.19: GSS_Duplicate_name call 🍓
Inputs:
src_nameINTERNAL NAME
Outputs:
major_statusINTEGER,minor_statusINTEGER,dest_nameINTERNAL NAME
Return major_status codes:
GSS_S_COMPLETEindicates thatdest_namereferences an internal name object containing the same name as passed tosrc_name.GSS_S_BAD_NAMEindicates that the input name was invalid.GSS_S_BAD_NAMETYPEindicates that the input name's type is unsupported by the GSS-API implementation.GSS_S_FAILUREindicates that the requested operation could not be performed for reasons unspecified at the GSS-API level.
this takes an internal name src_name and hands back another reference, dest_name, to that same name 🧚 the new reference can still be used even if src_name is freed later. (quick note: this might be done by copying, or with 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 💖 these are the shared shapes everybody agrees on, so the whole crew can talk to each other 🫶
3.1. Mechanism-Independent Token Format
okay bestie, this section is the wrapper 🎀 It's a mechanism-independent way to encapsulate the initial token of a GSS-API context establishment sequence. The wrapper includes an identifier for the mechanism type used on that context, so the tokens can be interpreted unambiguously by GSS-API peers 💅 This format is REQUIRED for initial context establishment tokens of Internet standards-track GSS-API mechanisms. Using it on non-initial tokens is OPTIONAL 🫶
The encoding is derived from ASN.1 and DER (see the illustrative ASN.1 syntax later in this subsection), but the concrete representation is defined directly in octets instead of at the ASN.1 level 🧚 That way you can get interoperable implementations without any general ASN.1 processing code. The token tag has these elements, in order:
0x60-- Tag for [APPLICATION 0] SEQUENCE; indicates that constructed form, definite length encoding follows.- 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).
- 2a. If the indicated value is less than 128, it SHALL be represented in a single octet with bit 8 (high order) set to
0x06-- Tag for OBJECT IDENTIFIER- 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.
- Object identifier octets -- variable number of octets, encoded per ASN.1 BER rules:
- 5a. The first octet contains the sum of two values: (1) the top-level object identifier component, multiplied by 40 (decimal), and (2) the second-level object identifier component. This special case is the only point within an object identifier encoding where a single octet represents contents of more than one component.
- 5b. Subsequent octets, if required, encode successively-lower components in the represented object identifier. A component's encoding may span multiple octets, encoding 7 bits per octet (most significant bits first) and with bit 8 set to
"1"on all but the final octet in the component's encoding. The minimum number of octets SHALL be used to encode each component (i.e., no octets representing leading zeros SHALL be included within a component's encoding).
(Note: In many implementations, elements 3-5 may be stored and referenced as a contiguous string constant.)
The token tag is immediately followed by a mechanism-defined token object. Note that no independent size specifier intervenes following the object identifier value to indicate the size of the mechanism-defined token object. While ASN.1 usage within mechanism-defined tokens is permitted, there is no requirement that the mechanism-specific innerContextToken, innerMsgToken, and sealedUserData data elements must employ ASN.1 BER/DER encoding conventions.
The following ASN.1 syntax is included for descriptive purposes only, to illustrate structural relationships among token and tag objects. For interoperability purposes, token and tag encoding SHALL be performed using the concrete encoding procedures described earlier in this subsection.
GSS-API DEFINITIONS ::=
BEGIN
MechType ::= OBJECT IDENTIFIER
-- data structure definitions
-- callers must be able to distinguish among
-- InitialContextToken, SubsequentContextToken,
-- PerMsgToken, and SealedMessage data elements
-- based on the usage in which they occur
InitialContextToken ::=
-- option indication (delegation, etc.) indicated within
-- mechanism-specific token
[APPLICATION 0] IMPLICIT SEQUENCE {
thisMech MechType,
innerContextToken ANY DEFINED BY thisMech
-- contents mechanism-specific
-- ASN.1 structure not required
}
SubsequentContextToken ::= innerContextToken ANY
-- interpretation based on predecessor InitialContextToken
-- ASN.1 structure not required
PerMsgToken ::=
-- as emitted by GSS_GetMIC and processed by GSS_VerifyMIC
-- ASN.1 structure not required
innerMsgToken ANY
SealedMessage ::=
-- as emitted by GSS_Wrap and processed by GSS_Unwrap
-- includes internal, mechanism-defined indicator
-- of whether or not encrypted
-- ASN.1 structure not required
sealedUserData ANY
END3.2. Mechanism-Independent Exported Name Object Format
this one's the name wrapper 🧚 It's a mechanism-independent way to encapsulate names exported via the GSS_Export_name() call, and it includes an object identifier for the mechanism that did the exporting. The format of the names inside this wrapper SHALL be defined within the individual mechanism drafts. Name objects of this type will be identified with this 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 format definition, since (depending on the 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 is the home of the name types that are defined at the GSS-API level, not inside each mechanism spec 💖 So these work the same no matter which mechanism you're using 👑
4.1. Host-Based Service Name Form
the OID for this name form is:
{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".
This name type is used to represent services associated with host computers. The name is built from two elements, "service" and "hostname", like this:
service@hostnameWhen a reference to a name of this type gets resolved, the "hostname" is canonicalized by attempting a DNS lookup and using the fully-qualified domain name that comes back. If the DNS lookup fails, the "hostname" is used as provided 🔥 The canonicalization step 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" defaulting 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:
username4.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 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 gives illustrative overviews of how various candidate mechanism types can support the GSS-API 🌸 These discussions are mainly for readers who already know specific security technologies, and they show how GSS-API functions can be used and implemented by candidate underlying mechanisms. They SHOULD NOT be treated as restrictive to implementations, and they SHOULD NOT be read as defining the only way GSS-API functions can be realized with a particular underlying technology. They also don't demonstrate every GSS-API feature with each technology 💜
5.1: Kerberos V5, single-TGT ✨
okay so the OS-specific login functions hand over a TGT from the local realm Kerberos server 🔑, and that TGT gets tucked into a credentials structure for the client 💖. Then the client calls GSS_Acquire_cred() to grab a cred_handle, which is how it points at those creds when it's setting up security contexts. no cap, it's giving organized 🗂️
The client calls GSS_Init_sec_context(). If the requested service lives in a different realm, GSS_Init_sec_context() goes and gets the TGT/key pairs needed to travel the path from the local realm to the target realm 🗺️, and those get stashed in the owner's TGT cache. After any remote realm resolution is sorted, GSS_Init_sec_context() yields a service ticket to the requested service with a corresponding session key, and those get stored alongside the context ✨. GSS-API code sends KRB_TGS_REQ request(s) and receives KRB_TGS_REP response(s) in the successful case, or a KRB_ERROR if things go sideways 😭.
Assuming it works out, GSS_Init_sec_context() builds a Kerberos-formatted KRB_AP_REQ message and returns it in output_token. The client sends that output_token to the service 🎀.
The service passes the received token as the input_token argument to GSS_Accept_sec_context(). It verifies the authenticator, gives the service the client's authenticated name, and returns an output_context_handle 💅.
Both parties now hold the session key tied to the service ticket, and they can use that key in later GSS_GetMIC(), GSS_VerifyMIC(), GSS_Wrap(), and GSS_Unwrap() operations 🫶.
5.2: Kerberos V5, double-TGT 🌸
TGT acquisition goes down exactly like we just saw 💅.
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() figures out that the double-TGT protocol should be used for the specified target 🧠. It returns a 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 a suitably long remaining lifetime already exists in a cache, it may be usable, so this step can be skipped 🙈.) The client passes the output_token to the service.
Note: this scenario shows a different use for the GSS_S_CONTINUE_NEEDED status return facility than the one used for mutual authentication. 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 a TGT. (Current Kerberos V5 defines no intra-protocol mechanism to represent such a request, ngl 💀.) GSS_Accept_sec_context() returns a GSS_S_CONTINUE_NEEDED major_status and provides the service's TGT in its output_token. The service sends that 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. It stores the returned service ticket and session key alongside the context. Then it builds a Kerberos-formatted authenticator, returns it in output_token along with a GSS_S_COMPLETE major_status, and the client sends that output_token to the service 🎀.
The 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, gives the service the client's authenticated name, and returns a major_status of GSS_S_COMPLETE 👑.
GSS_GetMIC(), GSS_VerifyMIC(), GSS_Wrap(), and GSS_Unwrap() work just like above 💖.
5.3: X.509 Authentication Framework 🔐
This example shows how the GSS-API gets used with public-key mechanisms, in line with the X.509 Directory Authentication Framework 🌈.
The GSS_Acquire_cred() call sets up a credentials structure, which makes the client's private key accessible for use on the client's behalf ✨.
The client calls GSS_Init_sec_context(), which asks the Directory to get (and validate) a chain of public-key certificates, and in doing so collects the service's public key. The certificate validation step confirms that suitable integrity checks were applied by trusted authorities and that the certificates haven't expired 📜. GSS_Init_sec_context() then generates a secret key for 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, goes into the output_token from GSS_Init_sec_context(). The output_token also carries a certification path, which is a certificate chain leading from the service to the client. A variant approach would defer this path resolution to the service instead of having the client assert it 🔄. The client application sends the output_token to the service.
The service passes the received token as the input_token argument to GSS_Accept_sec_context(). GSS_Accept_sec_context() validates the certification path and, as a result, determines a certified binding between the client's distinguished name and the client's public key 🪪. Given that public key, GSS_Accept_sec_context() can process the input_token's authenticator quantity and verify that the client's private key was used to sign the input_token. At this point the client is authenticated to the service 🎉. The service uses its private key to decipher the enciphered secret key it was given for per-message protection operations on the context.
The client calls GSS_GetMIC() or GSS_Wrap() on a data message, which applies per-message authentication, integrity, and (optional) confidentiality facilities to that message 🔒. The service uses the context's shared secret key to perform the corresponding GSS_VerifyMIC() and GSS_Unwrap() calls 💜.
6: Security Considerations 🚨
Security issues are discussed throughout this memo. bestie, I'm not kidding, read every single section for the security stuff 😭🔥
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 🧑💻.
APPENDIX A 🌟
MECHANISM DESIGN CONSTRAINTS 💅
The following constraints on GSS-API mechanism designs are adopted in response to observed caller protocol requirements, and adherence to them 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 🔁. Mechanisms offering neither of the latter will fail to satisfy recognized requirements of certain candidate caller protocols, so please don't skip this one 🙏.
Appendix B. Compatibility with GSS-V1 ✨
okay so bestie, this appendix is all about keeping things friendly with the older GSS-V1 (RFC-1508) crew 🫶. The whole point of this doc is an interface and procedures that keep GSS-V1 callers working with GSS-V2 providers 💅. Every GSS-V1 call is still here, and the goal was that GSS-V1 callers can run on top of GSS-V2 provider implementations. A few detailed changes fix omissions that were found in GSS-V1, and they're summarized here 🍓.
The following GSS-V1 constructs are still supported in GSS-V2, but they're deprecated 💀:
- Names for per-message processing routines:
GSS_Seal()is deprecated in favor ofGSS_Wrap()GSS_Sign()is deprecated in favor ofGSS_GetMIC()GSS_Unseal()is deprecated in favor ofGSS_Unwrap()GSS_Verify()is deprecated in favor ofGSS_VerifyMIC()
The GSS_Delete_sec_context() facility for context_token usage, which lets mechanisms signal context deletion, is kept around for GSS-V1 compatibility 🌸. For current usage, it is recommended that both peers to a context invoke GSS_Delete_sec_context() independently, passing a null output_context_token buffer to indicate that no context_token is required. Implementations of GSS_Delete_sec_context() should delete relevant locally-stored context information.
This GSS-V2 spec adds some calls that weren't in GSS-V1, and they're giving main character energy 👑:
- 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 spec also introduces three new facilities for security contexts 🦋. They're tracked with these context state values, which didn't exist 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 gives a summary of the GSS-V2 anonymity support facility, and support and use of it 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 gives a summary of the GSS-V2 facility that lets mechanisms selectively permit per-message protection during context establishment, and support and use of it is optional 🧚.trans_state, set TRUE to indicate that a context is transferable to another process using the GSS-V2GSS_Export_sec_context()facility 🎀.
These state values are represented (at the C bindings level) in positions within a bit vector that are unused in GSS-V1, so GSS-V1 callers can safely ignore them 🫧.
Compared to GSS-V1, GSS-V2 gives extra guidance to GSS-API implementors in these areas: implementation robustness, credential management, behavior in multi-mechanism configurations, naming support, and inclusion of optional sequencing services ✨. The token tagging facility in GSS-V2, Section 3.1, is now described directly in terms of octets, so you can build interoperable implementations without general ASN.1 processing code 🔥. The corresponding ASN.1 syntax is included for descriptive purposes and is unchanged from GSS-V1. To go with the new naming support facilities, there's a new Exported Name Object construct, and additional name types are introduced in Section 4 🌈.
This GSS-V2 spec adds these major_status values, which were 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)
detectedOut of all these added status codes, only two are allowed to be returned by calls that already existed in GSS-V1. GSS_S_BAD_QOP can be returned by GSS_GetMIC() and GSS_Wrap(), and GSS_S_GAP_TOKEN can be returned by GSS_VerifyMIC() and GSS_Unwrap() 💖.
Lastly, GSS-V2 updated the descriptions of some GSS-V1 calls so they can return additional major_status values from the set defined in GSS-V1 🍓. GSS_Inquire_cred() now has GSS_S_DEFECTIVE_CREDENTIAL and GSS_S_CREDENTIALS_EXPIRED defined as returnable. GSS_Init_sec_context() now has GSS_S_OLD_TOKEN, GSS_S_DUPLICATE_TOKEN, and GSS_S_BAD_MECH defined as returnable. And GSS_Accept_sec_context() now 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📦 where this page comes from
- ietf: rfc2078 1997-01
- 💖 girlified by claude-haiku-5-5 on : a language model's rewrite of the original, under its terms