diff options
Diffstat (limited to 'crypto/heimdal/doc/standardisation/rfc1508.txt')
| -rw-r--r-- | crypto/heimdal/doc/standardisation/rfc1508.txt | 2747 |
1 files changed, 2747 insertions, 0 deletions
diff --git a/crypto/heimdal/doc/standardisation/rfc1508.txt b/crypto/heimdal/doc/standardisation/rfc1508.txt new file mode 100644 index 0000000..132b855 --- /dev/null +++ b/crypto/heimdal/doc/standardisation/rfc1508.txt @@ -0,0 +1,2747 @@ + + + + + + +Network Working Group J. Linn +Request for Comments: 1508 Geer Zolot Associates + September 1993 + + + Generic Security Service Application Program Interface + +Status of this Memo + + This RFC specifies an Internet standards track protocol for the + Internet community, and requests discussion and suggestions for + improvements. Please refer to the current edition of the "Internet + Official Protocol Standards" for the standardization state and status + of this protocol. Distribution of this memo is unlimited. + +Abstract + + This Generic Security Service Application Program Interface (GSS-API) + definition provides security services to callers in a generic + fashion, supportable with a range of underlying mechanisms and + technologies and hence allowing source-level portability of + applications to different environments. This specification defines + GSS-API services and primitives at a level independent of underlying + mechanism and programming language environment, and is to be + complemented by other, related specifications: + + documents defining specific parameter bindings for particular + language environments + + documents defining token formats, protocols, and procedures to + be implemented in order to realize GSS-API services atop + particular security mechanisms + +Table of Contents + + 1. GSS-API Characteristics and Concepts ....................... 2 + 1.1. GSS-API Constructs ....................................... 5 + 1.1.1. Credentials ........................................... 5 + 1.1.2. Tokens ................................................ 6 + 1.1.3. Security Contexts ..................................... 7 + 1.1.4. Mechanism Types ....................................... 8 + 1.1.5. Naming ................................................ 9 + 1.1.6. Channel Bindings ...................................... 10 + 1.2. GSS-API Features and Issues ............................. 11 + 1.2.1. Status Reporting ...................................... 11 + 1.2.2. Per-Message Security Service Availability ............. 12 + 1.2.3. Per-Message Replay Detection and Sequencing ........... 13 + 1.2.4. Quality of Protection ................................. 15 + + + +Linn [Page 1] + +RFC 1508 Generic Security Interface September 1993 + + + 2. Interface Descriptions ..................................... 15 + 2.1. Credential management calls ............................. 17 + 2.1.1. GSS_Acquire_cred call ................................. 17 + 2.1.2. GSS_Release_cred call ................................. 19 + 2.1.3. GSS_Inquire_cred call ................................. 20 + 2.2. Context-level calls ..................................... 21 + 2.2.1. GSS_Init_sec_context call ............................. 21 + 2.2.2. GSS_Accept_sec_context call ........................... 26 + 2.2.3. GSS_Delete_sec_context call ........................... 29 + 2.2.4. GSS_Process_context_token call ........................ 30 + 2.2.5. GSS_Context_time call ................................. 31 + 2.3. Per-message calls ....................................... 32 + 2.3.1. GSS_Sign call ......................................... 32 + 2.3.2. GSS_Verify call ....................................... 33 + 2.3.3. GSS_Seal call ......................................... 35 + 2.3.4. GSS_Unseal call ....................................... 36 + 2.4. Support calls ........................................... 37 + 2.4.1. GSS_Display_status call ............................... 37 + 2.4.2. GSS_Indicate_mechs call ............................... 38 + 2.4.3. GSS_Compare_name call ................................. 38 + 2.4.4. GSS_Display_name call ................................. 39 + 2.4.5. GSS_Import_name call .................................. 40 + 2.4.6. GSS_Release_name call ................................. 41 + 2.4.7. GSS_Release_buffer call ............................... 41 + 2.4.8. GSS_Release_oid_set call .............................. 42 + 3. Mechanism-Specific Example Scenarios ....................... 42 + 3.1. Kerberos V5, single-TGT ................................. 43 + 3.2. Kerberos V5, double-TGT ................................. 43 + 3.3. X.509 Authentication Framework .......................... 44 + 4. Related Activities ......................................... 45 + 5. Acknowledgments ............................................ 46 + 6. Security Considerations .................................... 46 + 7. Author's Address ........................................... 46 + Appendix A .................................................... 47 + Appendix B .................................................... 48 + Appendix C .................................................... 49 + +1. GSS-API Characteristics and Concepts + + The operational paradigm in which GSS-API operates is as follows. A + typical GSS-API caller is itself a communications protocol, calling + on GSS-API in order to protect its communications with + authentication, integrity, and/or confidentiality security services. + A GSS-API caller accepts tokens provided to it by its local GSS-API + implementation and transfers the tokens to a peer on a remote system; + that peer passes the received tokens to its local GSS-API + implementation for processing. The security services available + through GSS-API in this fashion are implementable (and have been + + + +Linn [Page 2] + +RFC 1508 Generic Security Interface September 1993 + + + implemented) over a range of underlying mechanisms based on secret- + key and public-key cryptographic technologies. + + The GSS-API separates the operations of initializing a security + context between peers, achieving peer entity authentication (This + security service definition, and other definitions used in this + document, corresponds to that provided in International Standard ISO + 7498-2-1988(E), Security Architecture.) (GSS_Init_sec_context() and + GSS_Accept_sec_context() calls), from the operations of providing + per-message data origin authentication and data integrity protection + (GSS_Sign() and GSS_Verify() calls) for messages subsequently + transferred in conjunction with that context. Per-message GSS_Seal() + and GSS_Unseal() calls provide the data origin authentication and + data integrity services which GSS_Sign() and GSS_Verify() offer, and + also support selection of confidentiality services as a caller + option. Additional calls provide supportive functions to the GSS- + API's users. + + The following paragraphs provide an example illustrating the + dataflows involved in use of the GSS-API by a client and server in a + mechanism-independent fashion, establishing a security context and + transferring a protected message. The example assumes that credential + acquisition has already been completed. The example assumes that the + underlying authentication technology is capable of authenticating a + client to a server using elements carried within a single token, and + of authenticating the server to the client (mutual authentication) + with a single returned token; this assumption holds for presently- + documented CAT mechanisms but is not necessarily true for other + cryptographic technologies and associated protocols. + + The client calls GSS_Init_sec_context() to establish a security + context to the server identified by targ_name, and elects to set the + mutual_req_flag so that mutual authentication is performed in the + course of context establishment. GSS_Init_sec_context() returns an + output_token to be passed to the server, and indicates + GSS_CONTINUE_NEEDED status pending completion of the mutual + authentication sequence. Had mutual_req_flag not been set, the + initial call to GSS_Init_sec_context() would have returned + GSS_COMPLETE status. The client sends the output_token to the server. + + The server passes the received token as the input_token parameter to + GSS_Accept_sec_context(). GSS_Accept_sec_context indicates + GSS_COMPLETE status, provides the client's authenticated identity in + the src_name result, and provides an output_token to be passed to the + client. The server sends the output_token to the client. + + The client passes the received token as the input_token parameter to + a successor call to GSS_Init_sec_context(), which processes data + + + +Linn [Page 3] + +RFC 1508 Generic Security Interface September 1993 + + + included in the token in order to achieve mutual authentication from + the client's viewpoint. This call to GSS_Init_sec_context() returns + GSS_COMPLETE status, indicating successful mutual authentication and + the completion of context establishment for this example. + + The client generates a data message and passes it to GSS_Seal(). + GSS_Seal() performs data origin authentication, data integrity, and + (optionally) confidentiality processing on the message and + encapsulates the result into output_message, indicating GSS_COMPLETE + status. The client sends the output_message to the server. + + The server passes the received message to GSS_Unseal(). GSS_Unseal + inverts the encapsulation performed by GSS_Seal(), deciphers the + message if the optional confidentiality feature was applied, and + validates the data origin authentication and data integrity checking + quantities. GSS_Unseal() indicates successful validation by + returning GSS_COMPLETE status along with the resultant + output_message. + + For purposes of this example, we assume that the server knows by + out-of-band means that this context will have no further use after + one protected message is transferred from client to server. Given + this premise, the server now calls GSS_Delete_sec_context() to flush + context-level information. GSS_Delete_sec_context() returns a + context_token for the server to pass to the client. + + The client passes the returned context_token to + GSS_Process_context_token(), which returns GSS_COMPLETE status after + deleting context-level information at the client system. + + The GSS-API design assumes and addresses several basic goals, + including: + + Mechanism independence: The GSS-API defines an interface to + cryptographically implemented strong authentication and other + security services at a generic level which is independent of + particular underlying mechanisms. For example, GSS-API-provided + services can be implemented by secret-key technologies (e.g., + Kerberos) or public-key approaches (e.g., X.509). + + Protocol environment independence: The GSS-API is independent of + the communications protocol suites with which it is employed, + permitting use in a broad range of protocol environments. In + appropriate environments, an intermediate implementation "veneer" + which is oriented to a particular communication protocol (e.g., + Remote Procedure Call (RPC)) may be interposed between + applications which call that protocol and the GSS-API, thereby + invoking GSS-API facilities in conjunction with that protocol's + + + +Linn [Page 4] + +RFC 1508 Generic Security Interface September 1993 + + + communications invocations. + + Protocol association independence: The GSS-API's security context + construct is independent of communications protocol association + constructs. This characteristic allows a single GSS-API + implementation to be utilized by a variety of invoking protocol + modules on behalf of those modules' calling applications. GSS-API + services can also be invoked directly by applications, wholly + independent of protocol associations. + + Suitability to a range of implementation placements: GSS-API + clients are not constrained to reside within any Trusted Computing + Base (TCB) perimeter defined on a system where the GSS-API is + implemented; security services are specified in a manner suitable + to both intra-TCB and extra-TCB callers. + +1.1. GSS-API Constructs + + This section describes the basic elements comprising the GSS-API. + +1.1.1. Credentials + + Credentials structures provide the prerequisites enabling peers to + establish security contexts with each other. A caller may designate + that its default credential be used for context establishment calls + without presenting an explicit handle to that credential. + Alternately, those GSS-API callers which need to make explicit + selection of particular credentials structures may make references to + those credentials through GSS-API-provided credential handles + ("cred_handles"). + + A single credential structure may be used for initiation of outbound + contexts and acceptance of inbound contexts. Callers needing to + operate in only one of these modes may designate this fact when + credentials are acquired for use, allowing underlying mechanisms to + optimize their processing and storage requirements. The credential + elements defined by a particular mechanism may contain multiple + cryptographic keys, e.g., to enable authentication and message + encryption to be performed with different algorithms. + + A single credential structure may accommodate credential information + associated with multiple underlying mechanisms (mech_types); a + credential structure's contents will vary depending on the set of + mech_types supported by a particular GSS-API implementation. + Commonly, a single mech_type will be used for all security contexts + established by a particular initiator to a particular target; the + primary motivation for supporting credential sets representing + multiple mech_types is to allow initiators on systems which are + + + +Linn [Page 5] + +RFC 1508 Generic Security Interface September 1993 + + + equipped to handle multiple types to initiate contexts to targets on + other systems which can accommodate only a subset of the set + supported at the initiator's system. + + It is the responsibility of underlying system-specific mechanisms and + OS functions below the GSS-API to ensure that the ability to acquire + and use credentials associated with a given identity is constrained + to appropriate processes within a system. This responsibility should + be taken seriously by implementors, as the ability for an entity to + utilize a principal's credentials is equivalent to the entity's + ability to successfully assert that principal's identity. + + Once a set of GSS-API credentials is established, the transferability + of that credentials set to other processes or analogous constructs + within a system is a local matter, not defined by the GSS-API. An + example local policy would be one in which any credentials received + as a result of login to a given user account, or of delegation of + rights to that account, are accessible by, or transferable to, + processes running under that account. + + The credential establishment process (particularly when performed on + behalf of users rather than server processes) is likely to require + access to passwords or other quantities which should be protected + locally and exposed for the shortest time possible. As a result, it + will often be appropriate for preliminary credential establishment to + be performed through local means at user login time, with the + result(s) cached for subsequent reference. These preliminary + credentials would be set aside (in a system-specific fashion) for + subsequent use, either: + + to be accessed by an invocation of the GSS-API GSS_Acquire_cred() + call, returning an explicit handle to reference that credential + + as the default credentials installed on behalf of a process + +1.1.2. Tokens + + Tokens are data elements transferred between GSS-API callers, and are + divided into two classes. Context-level tokens are exchanged in order + to establish and manage a security context between peers. Per-message + tokens are exchanged in conjunction with an established context to + provide protective security services for corresponding data messages. + The internal contents of both classes of tokens are specific to the + particular underlying mechanism used to support the GSS-API; Appendix + B of this document provides a uniform recommendation for designers of + GSS-API support mechanisms, encapsulating mechanism-specific + information along with a globally-interpretable mechanism identifier. + + + + +Linn [Page 6] + +RFC 1508 Generic Security Interface September 1993 + + + Tokens are opaque from the viewpoint of GSS-API callers. They are + generated within the GSS-API implementation at an end system, + provided to a GSS-API caller to be transferred to the peer GSS-API + caller at a remote end system, and processed by the GSS-API + implementation at that remote end system. Tokens may be output by + GSS-API primitives (and are to be transferred to GSS-API peers) + independent of the status indications which those primitives + indicate. Token transfer may take place in an in-band manner, + integrated into the same protocol stream used by the GSS-API callers + for other data transfers, or in an out-of-band manner across a + logically separate channel. + + Development of GSS-API support primitives based on a particular + underlying cryptographic technique and protocol does not necessarily + imply that GSS-API callers invoking that GSS-API mechanism type will + be able to interoperate with peers invoking the same technique and + protocol outside the GSS-API paradigm. For example, the format of + GSS-API tokens defined in conjunction with a particular mechanism, + and the techniques used to integrate those tokens into callers' + protocols, may not be the same as those used by non-GSS-API callers + of the same underlying technique. + +1.1.3. Security Contexts + + Security contexts are established between peers, using credentials + established locally in conjunction with each peer or received by + peers via delegation. Multiple contexts may exist simultaneously + between a pair of peers, using the same or different sets of + credentials. Coexistence of multiple contexts using different + credentials allows graceful rollover when credentials expire. + Distinction among multiple contexts based on the same credentials + serves applications by distinguishing different message streams in a + security sense. + + The GSS-API is independent of underlying protocols and addressing + structure, and depends on its callers to transport GSS-API-provided + data elements. As a result of these factors, it is a caller + responsibility to parse communicated messages, separating GSS-API- + related data elements from caller-provided data. The GSS-API is + independent of connection vs. connectionless orientation of the + underlying communications service. + + No correlation between security context and communications protocol + association is dictated. (The optional channel binding facility, + discussed in Section 1.1.6 of this document, represents an + intentional exception to this rule, supporting additional protection + features within GSS-API supporting mechanisms.) This separation + allows the GSS-API to be used in a wide range of communications + + + +Linn [Page 7] + +RFC 1508 Generic Security Interface September 1993 + + + environments, and also simplifies the calling sequences of the + individual calls. In many cases (depending on underlying security + protocol, associated mechanism, and availability of cached + information), the state information required for context setup can be + sent concurrently with initial signed user data, without interposing + additional message exchanges. + +1.1.4. Mechanism Types + + In order to successfully establish a security context with a target + peer, it is necessary to identify an appropriate underlying mechanism + type (mech_type) which both initiator and target peers support. The + definition of a mechanism embodies not only the use of a particular + cryptographic technology (or a hybrid or choice among alternative + cryptographic technologies), but also definition of the syntax and + semantics of data element exchanges which that mechanism will employ + in order to support security services. + + It is recommended that callers initiating contexts specify the + "default" mech_type value, allowing system-specific functions within + or invoked by the GSS-API implementation to select the appropriate + mech_type, but callers may direct that a particular mech_type be + employed when necessary. + + The means for identifying a shared mech_type to establish a security + context with a peer will vary in different environments and + circumstances; examples include (but are not limited to): + + use of a fixed mech_type, defined by configuration, within an + environment + + syntactic convention on a target-specific basis, through + examination of a target's name + + lookup of a target's name in a naming service or other database in + order to identify mech_types supported by that target + + explicit negotiation between GSS-API callers in advance of + security context setup + + When transferred between GSS-API peers, mech_type specifiers (per + Appendix B, represented as Object Identifiers (OIDs)) serve to + qualify the interpretation of associated tokens. (The structure and + encoding of Object Identifiers is defined in ISO/IEC 8824, + "Specification of Abstract Syntax Notation One (ASN.1)" and in + ISO/IEC 8825, "Specification of Basic Encoding Rules for Abstract + Syntax Notation One (ASN.1)".) Use of hierarchically structured OIDs + serves to preclude ambiguous interpretation of mech_type specifiers. + + + +Linn [Page 8] + +RFC 1508 Generic Security Interface September 1993 + + + The OID representing the DASS MechType, for example, is + 1.3.12.2.1011.7.5. + +1.1.5. Naming + + The GSS-API avoids prescription of naming structures, treating the + names transferred across the interface in order to initiate and + accept security contexts as opaque octet string quantities. This + approach supports the GSS-API's goal of implementability atop a range + of underlying security mechanisms, recognizing the fact that + different mechanisms process and authenticate names which are + presented in different forms. Generalized services offering + translation functions among arbitrary sets of naming environments are + outside the scope of the GSS-API; availability and use of local + conversion functions to translate among the naming formats supported + within a given end system is anticipated. + + Two distinct classes of name representations are used in conjunction + with different GSS-API parameters: + + a printable form (denoted by OCTET STRING), for acceptance from + and presentation to users; printable name forms are accompanied by + OID tags identifying the namespace to which they correspond + + an internal form (denoted by INTERNAL NAME), opaque to callers and + defined by individual GSS-API implementations; GSS-API + implementations supporting multiple namespace types are + responsible for maintaining internal tags to disambiguate the + interpretation of particular names + + Tagging of printable names allows GSS-API callers and underlying + GSS-API mechanisms to disambiguate name types and to determine + whether an associated name's type is one which they are capable of + processing, avoiding aliasing problems which could result from + misinterpreting a name of one type as a name of another type. + + In addition to providing means for names to be tagged with types, + this specification defines primitives to support a level of naming + environment independence for certain calling applications. To provide + basic services oriented towards the requirements of callers which + need not themselves interpret the internal syntax and semantics of + names, GSS-API calls for name comparison (GSS_Compare_name()), + human-readable display (GSS_Display_name()), input conversion + (GSS_Import_name()), and internal name deallocation + (GSS_Release_name()) functions are defined. (It is anticipated that + these proposed GSS-API calls will be implemented in many end systems + based on system-specific name manipulation primitives already extant + within those end systems; inclusion within the GSS-API is intended to + + + +Linn [Page 9] + +RFC 1508 Generic Security Interface September 1993 + + + offer GSS-API callers a portable means to perform specific + operations, supportive of authorization and audit requirements, on + authenticated names.) + + GSS_Import_name() implementations can, where appropriate, support + more than one printable syntax corresponding to a given namespace + (e.g., alternative printable representations for X.500 Distinguished + Names), allowing flexibility for their callers to select among + alternative representations. GSS_Display_name() implementations + output a printable syntax selected as appropriate to their + operational environments; this selection is a local matter. Callers + desiring portability across alternative printable syntaxes should + refrain from implementing comparisons based on printable name forms + and should instead use the GSS_Compare_name() call to determine + whether or not one internal-format name matches another. + +1.1.6. Channel Bindings + + The GSS-API accommodates the concept of caller-provided channel + binding ("chan_binding") information, used by GSS-API callers to bind + the establishment of a security context to relevant characteristics + (e.g., addresses, transformed representations of encryption keys) of + the underlying communications channel and of protection mechanisms + applied to that communications channel. Verification by one peer of + chan_binding information provided by the other peer to a context + serves to protect against various active attacks. The caller + initiating a security context must determine the chan_binding values + before making the GSS_Init_sec_context() call, and consistent values + must be provided by both peers to a context. Callers should not + assume that underlying mechanisms provide confidentiality protection + for channel binding information. + + Use or non-use of the GSS-API channel binding facility is a caller + option, and GSS-API supporting mechanisms can support operation in an + environment where NULL channel bindings are presented. When non-NULL + channel bindings are used, certain mechanisms will offer enhanced + security value by interpreting the bindings' content (rather than + simply representing those bindings, or signatures computed on them, + within tokens) and will therefore depend on presentation of specific + data in a defined format. To this end, agreements among mechanism + implementors are defining conventional interpretations for the + contents of channel binding arguments, including address specifiers + (with content dependent on communications protocol environment) for + context initiators and acceptors. (These conventions are being + incorporated into related documents.) In order for GSS-API callers to + be portable across multiple mechanisms and achieve the full security + functionality available from each mechanism, it is strongly + recommended that GSS-API callers provide channel bindings consistent + + + +Linn [Page 10] + +RFC 1508 Generic Security Interface September 1993 + + + with these conventions and those of the networking environment in + which they operate. + +1.2. GSS-API Features and Issues + + This section describes aspects of GSS-API operations, of the security + services which the GSS-API provides, and provides commentary on + design issues. + +1.2.1. Status Reporting + + Each GSS-API call provides two status return values. Major_status + values provide a mechanism-independent indication of call status + (e.g., GSS_COMPLETE, GSS_FAILURE, GSS_CONTINUE_NEEDED), sufficient to + drive normal control flow within the caller in a generic fashion. + Table 1 summarizes the defined major_status return codes in tabular + fashion. + + Table 1: GSS-API Major Status Codes + + FATAL ERROR CODES + + GSS_BAD_BINDINGS channel binding mismatch + GSS_BAD_MECH unsupported mechanism requested + GSS_BAD_NAME invalid name provided + GSS_BAD_NAMETYPE name of unsupported type provided + GSS_BAD_STATUS invalid input status selector + GSS_BAD_SIG token had invalid signature + GSS_CONTEXT_EXPIRED specified security context expired + GSS_CREDENTIALS_EXPIRED expired credentials detected + GSS_DEFECTIVE_CREDENTIAL defective credential detected + GSS_DEFECTIVE_TOKEN defective token detected + GSS_FAILURE failure, unspecified at GSS-API + level + GSS_NO_CONTEXT no valid security context specified + GSS_NO_CRED no valid credentials provided + + INFORMATORY STATUS CODES + + GSS_COMPLETE normal completion + GSS_CONTINUE_NEEDED continuation call to routine + required + GSS_DUPLICATE_TOKEN duplicate per-message token + detected + GSS_OLD_TOKEN timed-out per-message token + detected + GSS_UNSEQ_TOKEN out-of-order per-message token + detected + + + +Linn [Page 11] + +RFC 1508 Generic Security Interface September 1993 + + + Minor_status provides more detailed status information which may + include status codes specific to the underlying security mechanism. + Minor_status values are not specified in this document. + + GSS_CONTINUE_NEEDED major_status returns, and optional message + outputs, are provided in GSS_Init_sec_context() and + GSS_Accept_sec_context() calls so that different mechanisms' + employment of different numbers of messages within their + authentication sequences need not be reflected in separate code paths + within calling applications. Instead, such cases are accomodated with + sequences of continuation calls to GSS_Init_sec_context() and + GSS_Accept_sec_context(). The same mechanism is used to encapsulate + mutual authentication within the GSS-API's context initiation calls. + + For mech_types which require interactions with third-party servers in + order to establish a security context, GSS-API context establishment + calls may block pending completion of such third-party interactions. + On the other hand, no GSS-API calls pend on serialized interactions + with GSS-API peer entities. As a result, local GSS-API status + returns cannot reflect unpredictable or asynchronous exceptions + occurring at remote peers, and reflection of such status information + is a caller responsibility outside the GSS-API. + +1.2.2. Per-Message Security Service Availability + + When a context is established, two flags are returned to indicate the + set of per-message protection security services which will be + available on the context: + + the integ_avail flag indicates whether per-message integrity and + data origin authentication services are available + + the conf_avail flag indicates whether per-message confidentiality + services are available, and will never be returned TRUE unless the + integ_avail flag is also returned TRUE + + GSS-API callers desiring per-message security services should + check the values of these flags at context establishment time, and + must be aware that a returned FALSE value for integ_avail means + that invocation of GSS_Sign() or GSS_Seal() primitives on the + associated context will apply no cryptographic protection to user + data messages. + + The GSS-API per-message protection service primitives, as the + category name implies, are oriented to operation at the granularity + of protocol data units. They perform cryptographic operations on the + data units, transfer cryptographic control information in tokens, + and, in the case of GSS_Seal(), encapsulate the protected data unit. + + + +Linn [Page 12] + +RFC 1508 Generic Security Interface September 1993 + + + As such, these primitives are not oriented to efficient data + protection for stream-paradigm protocols (e.g., Telnet) if + cryptography must be applied on an octet-by-octet basis. + +1.2.3. Per-Message Replay Detection and Sequencing + + Certain underlying mech_types are expected to offer support for + replay detection and/or sequencing of messages transferred on the + contexts they support. These optionally-selectable protection + features are distinct from replay detection and sequencing features + applied to the context establishment operation itself; the presence + or absence of context-level replay or sequencing features is wholly a + function of the underlying mech_type's capabilities, and is not + selected or omitted as a caller option. + + The caller initiating a context provides flags (replay_det_req_flag + and sequence_req_flag) to specify whether the use of per-message + replay detection and sequencing features is desired on the context + being established. The GSS-API implementation at the initiator system + can determine whether these features are supported (and whether they + are optionally selectable) as a function of mech_type, without need + for bilateral negotiation with the target. When enabled, these + features provide recipients with indicators as a result of GSS-API + processing of incoming messages, identifying whether those messages + were detected as duplicates or out-of-sequence. Detection of such + events does not prevent a suspect message from being provided to a + recipient; the appropriate course of action on a suspect message is a + matter of caller policy. + + The semantics of the replay detection and sequencing services applied + to received messages, as visible across the interface which the GSS- + API provides to its clients, are as follows: + + When replay_det_state is TRUE, the possible major_status returns for + well-formed and correctly signed messages are as follows: + + 1. GSS_COMPLETE indicates that the message was within the window + (of time or sequence space) allowing replay events to be detected, + and that the message was not a replay of a previously-processed + message within that window. + + 2. GSS_DUPLICATE_TOKEN indicates that the signature on the + received message was correct, but that the message was recognized + as a duplicate of a previously-processed message. + + 3. GSS_OLD_TOKEN indicates that the signature on the received + message was correct, but that the message is too old to be checked + for duplication. + + + +Linn [Page 13] + +RFC 1508 Generic Security Interface September 1993 + + + When sequence_state is TRUE, the possible major_status returns for + well-formed and correctly signed messages are as follows: + + 1. GSS_COMPLETE indicates that the message was within the window + (of time or sequence space) allowing replay events to be detected, + and that the message was not a replay of a previously-processed + message within that window. + + 2. GSS_DUPLICATE_TOKEN indicates that the signature on the + received message was correct, but that the message was recognized + as a duplicate of a previously-processed message. + + 3. GSS_OLD_TOKEN indicates that the signature on the received + message was correct, but that the token is too old to be checked + for duplication. + + 4. GSS_UNSEQ_TOKEN indicates that the signature on the received + message was correct, but that it is earlier in a sequenced stream + than a message already processed on the context. [Note: + Mechanisms can be architected to provide a stricter form of + sequencing service, delivering particular messages to recipients + only after all predecessor messages in an ordered stream have been + delivered. This type of support is incompatible with the GSS-API + paradigm in which recipients receive all messages, whether in + order or not, and provide them (one at a time, without intra-GSS- + API message buffering) to GSS-API routines for validation. GSS- + API facilities provide supportive functions, aiding clients to + achieve strict message stream integrity in an efficient manner in + conjunction with sequencing provisions in communications + protocols, but the GSS-API does not offer this level of message + stream integrity service by itself.] + + As the message stream integrity features (especially sequencing) may + interfere with certain applications' intended communications + paradigms, and since support for such features is likely to be + resource intensive, it is highly recommended that mech_types + supporting these features allow them to be activated selectively on + initiator request when a context is established. A context initiator + and target are provided with corresponding indicators + (replay_det_state and sequence_state), signifying whether these + features are active on a given context. + + An example mech_type supporting per-message replay detection could + (when replay_det_state is TRUE) implement the feature as follows: The + underlying mechanism would insert timestamps in data elements output + by GSS_Sign() and GSS_Seal(), and would maintain (within a time- + limited window) a cache (qualified by originator-recipient pair) + identifying received data elements processed by GSS_Verify() and + + + +Linn [Page 14] + +RFC 1508 Generic Security Interface September 1993 + + + GSS_Unseal(). When this feature is active, exception status returns + (GSS_DUPLICATE_TOKEN, GSS_ OLD_TOKEN) will be provided when + GSS_Verify() or GSS_Unseal() is presented with a message which is + either a detected duplicate of a prior message or which is too old to + validate against a cache of recently received messages. + +1.2.4. Quality of Protection + + Some mech_types will provide their users with fine granularity + control over the means used to provide per-message protection, + allowing callers to trade off security processing overhead + dynamically against the protection requirements of particular + messages. A per-message quality-of-protection parameter (analogous to + quality-of-service, or QOS) selects among different QOP options + supported by that mechanism. On context establishment for a multi-QOP + mech_type, context-level data provides the prerequisite data for a + range of protection qualities. + + It is expected that the majority of callers will not wish to exert + explicit mechanism-specific QOP control and will therefore request + selection of a default QOP. Definitions of, and choices among, non- + default QOP values are mechanism-specific, and no ordered sequences + of QOP values can be assumed equivalent across different mechanisms. + Meaningful use of non-default QOP values demands that callers be + familiar with the QOP definitions of an underlying mechanism or + mechanisms, and is therefore a non-portable construct. + +2. Interface Descriptions + + This section describes the GSS-API's service interface, dividing the + set of calls offered into four groups. Credential management calls + are related to the acquisition and release of credentials by + principals. Context-level calls are related to the management of + security contexts between principals. Per-message calls are related + to the protection of individual messages on established security + contexts. Support calls provide ancillary functions useful to GSS-API + callers. Table 2 groups and summarizes the calls in tabular fashion. + + + + + + + + + + + + + + +Linn [Page 15] + +RFC 1508 Generic Security Interface September 1993 + + + 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 + + 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 + + PER-MESSAGE CALLS + + GSS_Sign apply signature, receive as token + separate from message + GSS_Verify validate signature token along with + message + GSS_Seal sign, optionally encrypt, + encapsulate + GSS_Unseal decapsulate, decrypt if needed, + validate signature + + 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_set free storage of OID set object + + + + + + + +Linn [Page 16] + +RFC 1508 Generic Security Interface September 1993 + + +2.1. Credential management calls + + These GSS-API calls provide functions related to the management of + credentials. Their characterization with regard to whether or not + they may block pending exchanges with other network entities (e.g., + directories or authentication servers) depends in part on OS-specific + (extra-GSS-API) issues, so is not specified in this document. + + The GSS_Acquire_cred() call is defined within the GSS-API in support + of application portability, with a particular orientation towards + support of portable server applications. It is recognized that (for + certain systems and mechanisms) credentials for interactive users may + be managed differently from credentials for server processes; in such + environments, it is the GSS-API implementation's responsibility to + distinguish these cases and the procedures for making this + distinction are a local matter. The GSS_Release_cred() call provides + a means for callers to indicate to the GSS-API that use of a + credentials structure is no longer required. The GSS_Inquire_cred() + call allows callers to determine information about a credentials + structure. + +2.1.1. GSS_Acquire_cred call + + Inputs: + + o desired_name INTERNAL NAME, -NULL requests locally-determined + default + + o lifetime_req INTEGER,-in seconds; 0 requests default + + o desired_mechs SET OF OBJECT IDENTIFIER,-empty set requests + system-selected default + + o cred_usage INTEGER-0=INITIATE-AND-ACCEPT, 1=INITIATE-ONLY, + 2=ACCEPT-ONLY + + Outputs: + + o major_status INTEGER, + + o minor_status INTEGER, + + o output_cred_handle OCTET STRING, + + o actual_mechs SET OF OBJECT IDENTIFIER, + + o lifetime_rec INTEGER -in seconds, or reserved value for + INDEFINITE + + + +Linn [Page 17] + +RFC 1508 Generic Security Interface September 1993 + + + Return major_status codes: + + o GSS_COMPLETE indicates that requested credentials were + successfully established, for the duration indicated in + lifetime_rec, suitable for the usage requested in cred_usage, for + the set of mech_types indicated in actual_mechs, and that those + credentials can be referenced for subsequent use with the handle + returned in output_cred_handle. + + o GSS_BAD_MECH indicates that a mech_type unsupported by the GSS-API + implementation type was requested, causing the credential + establishment operation to fail. + + o GSS_BAD_NAMETYPE indicates that the provided desired_name is + uninterpretable or of a type unsupported by the supporting GSS-API + implementation, so no credentials could be established for the + accompanying desired_name. + + o GSS_BAD_NAME indicates that the provided desired_name is + inconsistent in terms of internally-incorporated type specifier + information, so no credentials could be established for the + accompanying desired_name. + + o GSS_FAILURE indicates that credential establishment failed for + reasons unspecified at the GSS-API level, including lack of + authorization to establish and use credentials associated with the + identity named in the input desired_name argument. + + GSS_Acquire_cred() is used to acquire credentials so that a + principal can (as a function of the input cred_usage parameter) + initiate and/or accept security contexts under the identity + represented by the desired_name input argument. On successful + completion, the returned output_cred_handle result provides a handle + for subsequent references to the acquired credentials. Typically, + single-user client processes using only default credentials for + context establishment purposes will have no need to invoke this call. + + A caller may provide the value NULL for desired_name, signifying a + request for credentials corresponding to a default principal + identity. The procedures used by GSS-API implementations to select + the appropriate principal identity in response to this form of + request are local matters. It is possible that multiple pre- + established credentials may exist for the same principal identity + (for example, as a result of multiple user login sessions) when + GSS_Acquire_cred() is called; the means used in such cases to select + a specific credential are local matters. The input lifetime_req + argument to GSS_Acquire_cred() may provide useful information for + local GSS-API implementations to employ in making this disambiguation + + + +Linn [Page 18] + +RFC 1508 Generic Security Interface September 1993 + + + in a manner which will best satisfy a caller's intent. + + The lifetime_rec result indicates the length of time for which the + acquired credentials will be valid, as an offset from the present. A + mechanism may return a reserved value indicating INDEFINITE if no + constraints on credential lifetime are imposed. A caller of + GSS_Acquire_cred() can request a length of time for which acquired + credentials are to be valid (lifetime_req argument), beginning at the + present, or can request credentials with a default validity interval. + (Requests for postdated credentials are not supported within the + GSS-API.) Certain mechanisms and implementations may bind in + credential validity period specifiers at a point preliminary to + invocation of the GSS_Acquire_cred() call (e.g., in conjunction with + user login procedures). As a result, callers requesting non-default + values for lifetime_req must recognize that such requests cannot + always be honored and must be prepared to accommodate the use of + returned credentials with different lifetimes as indicated in + lifetime_rec. + + The caller of GSS_Acquire_cred() can explicitly specify a set of + mech_types which are to be accommodated in the returned credentials + (desired_mechs argument), or can request credentials for a system- + defined default set of mech_types. Selection of the system-specified + default set is recommended in the interests of application + portability. The actual_mechs return value may be interrogated by the + caller to determine the set of mechanisms with which the returned + credentials may be used. + +2.1.2. GSS_Release_cred call + + Input: + + o cred_handle OCTET STRING-NULL specifies default credentials + + Outputs: + + o major_status INTEGER, + + o minor_status INTEGER + + Return major_status codes: + + o GSS_COMPLETE indicates that the credentials referenced by the + input cred_handle were released for purposes of subsequent access + by the caller. The effect on other processes which may be + authorized shared access to such credentials is a local matter. + + + + + +Linn [Page 19] + +RFC 1508 Generic Security Interface September 1993 + + + o GSS_NO_CRED indicates that no release operation was performed, + either because the input cred_handle was invalid or because the + caller lacks authorization to access the referenced credentials. + + o GSS_FAILURE indicates that the release operation failed for + reasons unspecified at the GSS-API level. + + Provides a means for a caller to explicitly request that credentials + be released when their use is no longer required. Note that system- + specific credential management functions are also likely to exist, + for example to assure that credentials shared among processes are + properly deleted when all affected processes terminate, even if no + explicit release requests are issued by those processes. Given the + fact that multiple callers are not precluded from gaining authorized + access to the same credentials, invocation of GSS_Release_cred() + cannot be assumed to delete a particular set of credentials on a + system-wide basis. + +2.1.3. GSS_Inquire_cred call + + Input: + + o cred_handle OCTET STRING -NULL specifies default credentials + + Outputs: + + o major_status INTEGER, + + o minor_status INTEGER, + + o cred_name INTERNAL NAME, + + o lifetime_rec INTEGER -in seconds, or reserved value for + INDEFINITE + + o cred_usage INTEGER, -0=INITIATE-AND-ACCEPT, 1=INITIATE-ONLY, + 2=ACCEPT-ONLY + + o mech_set SET OF OBJECT IDENTIFIER + + Return major_status codes: + + o GSS_COMPLETE indicates that the credentials referenced by the + input cred_handle argument were valid, and that the output + cred_name, lifetime_rec, and cred_usage values represent, + respectively, the credentials' associated principal name, + remaining lifetime, suitable usage modes, and supported + mechanism types. + + + +Linn [Page 20] + +RFC 1508 Generic Security Interface September 1993 + + + o GSS_NO_CRED indicates that no information could be returned + about the referenced credentials, either because the input + cred_handle was invalid or because the caller lacks + authorization to access the referenced credentials. + + o GSS_FAILURE indicates that the release operation failed for + reasons unspecified at the GSS-API level. + + The GSS_Inquire_cred() call is defined primarily for the use of + those callers which make use of default credentials rather than + acquiring credentials explicitly with GSS_Acquire_cred(). It enables + callers to determine a credential structure's associated principal + name, remaining validity period, usability for security context + initiation and/or acceptance, and supported mechanisms. + +2.2. Context-level calls + + This group of calls is devoted to the establishment and management of + security contexts between peers. A context's initiator calls + GSS_Init_sec_context(), resulting in generation of a token which the + caller passes to the target. At the target, that token is passed to + GSS_Accept_sec_context(). Depending on the underlying mech_type and + specified options, additional token exchanges may be performed in the + course of context establishment; such exchanges are accommodated by + GSS_CONTINUE_NEEDED status returns from GSS_Init_sec_context() and + GSS_Accept_sec_context(). Either party to an established context may + invoke GSS_Delete_sec_context() to flush context information when a + context is no longer required. GSS_Process_context_token() is used + to process received tokens carrying context-level control + information. GSS_Context_time() allows a caller to determine the + length of time for which an established context will remain valid. + +2.2.1. GSS_Init_sec_context call + + Inputs: + + o claimant_cred_handle OCTET STRING, -NULL specifies "use + default" + + o input_context_handle INTEGER, -0 specifies "none assigned + yet" + + o targ_name INTERNAL NAME, + + o mech_type OBJECT IDENTIFIER, -NULL parameter specifies "use + default" + + o deleg_req_flag BOOLEAN, + + + +Linn [Page 21] + +RFC 1508 Generic Security Interface September 1993 + + + o mutual_req_flag BOOLEAN, + + o replay_det_req_flag BOOLEAN, + + o sequence_req_flag BOOLEAN, + + o lifetime_req INTEGER,-0 specifies default lifetime + + o chan_bindings OCTET STRING, + + o input_token OCTET STRING-NULL or token received from target + + Outputs: + + o major_status INTEGER, + + o minor_status INTEGER, + + o output_context_handle INTEGER, + + o mech_type OBJECT IDENTIFIER, -actual mechanism always + indicated, never NULL + + o output_token OCTET STRING, -NULL or token to pass to context + target + + o deleg_state BOOLEAN, + + o mutual_state BOOLEAN, + + o replay_det_state BOOLEAN, + + o sequence_state BOOLEAN, + + o conf_avail BOOLEAN, + + o integ_avail BOOLEAN, + + o lifetime_rec INTEGER - in seconds, or reserved value for + INDEFINITE + + This call may block pending network interactions for those mech_types + in which an authentication server or other network entity must be + consulted on behalf of a context initiator in order to generate an + output_token suitable for presentation to a specified target. + + Return major_status codes: + + + + +Linn [Page 22] + +RFC 1508 Generic Security Interface September 1993 + + + o GSS_COMPLETE indicates that context-level information was + successfully initialized, and that the returned output_token will + provide sufficient information for the target to perform per- + message processing on the newly-established context. + + o GSS_CONTINUE_NEEDED indicates that control information in the + returned output_token must be sent to the target, and that a reply + must be received and passed as the input_token argument to a + continuation call to GSS_Init_sec_context(), before per-message + processing can be performed in conjunction with this context. + + o GSS_DEFECTIVE_TOKEN indicates that consistency checks performed on + the input_token failed, preventing further processing from being + performed based on that token. + + o GSS_DEFECTIVE_CREDENTIAL indicates that consistency checks + performed on the credential structure referenced by + claimant_cred_handle failed, preventing further processing from + being performed using that credential structure. + + o GSS_BAD_SIG indicates that the received input_token contains an + incorrect signature, so context setup cannot be accomplished. + + o GSS_NO_CRED indicates that no context was established, either + because the input cred_handle was invalid, because the referenced + credentials are valid for context acceptor use only, or because + the caller lacks authorization to access the referenced + credentials. + + o GSS_CREDENTIALS_EXPIRED indicates that the credentials provided + through the input claimant_cred_handle argument are no longer + valid, so context establishment cannot be completed. + + o GSS_BAD_BINDINGS indicates that a mismatch between the caller- + provided chan_bindings and those extracted from the input_token + was detected, signifying a security-relevant event and preventing + context establishment. (This result will be returned by + GSS_Init_sec_context only for contexts where mutual_state is + TRUE.) + + o GSS_NO_CONTEXT indicates that no valid context was recognized for + the input context_handle provided; this major status will be + returned only for successor calls following GSS_CONTINUE_NEEDED + status returns. + + o GSS_BAD_NAMETYPE indicates that the provided targ_name is of a + type uninterpretable or unsupported by the supporting GSS-API + implementation, so context establishment cannot be completed. + + + +Linn [Page 23] + +RFC 1508 Generic Security Interface September 1993 + + + o GSS_BAD_NAME indicates that the provided targ_name is inconsistent + in terms of internally-incorporated type specifier information, so + context establishment cannot be accomplished. + + o GSS_FAILURE indicates that context setup could not be accomplished + for reasons unspecified at the GSS-API level, and that no + interface-defined recovery action is available. + + This routine is used by a context initiator, and ordinarily emits one + (or, for the case of a multi-step exchange, more than one) + output_token suitable for use by the target within the selected + mech_type's protocol. Using information in the credentials structure + referenced by claimant_cred_handle, GSS_Init_sec_context() + initializes the data structures required to establish a security + context with target targ_name. The claimant_cred_handle must + correspond to the same valid credentials structure on the initial + call to GSS_Init_sec_context() and on any successor calls resulting + from GSS_CONTINUE_NEEDED status returns; different protocol sequences + modeled by the GSS_CONTINUE_NEEDED mechanism will require access to + credentials at different points in the context establishment + sequence. + + The input_context_handle argument is 0, specifying "not yet + assigned", on the first GSS_Init_sec_context() call relating to a + given context. That call returns an output_context_handle for future + references to this context. When continuation attempts to + GSS_Init_sec_context() are needed to perform context establishment, + the previously-returned non-zero handle value is entered into the + input_context_handle argument and will be echoed in the returned + output_context_handle argument. On such continuation attempts (and + only on continuation attempts) the input_token value is used, to + provide the token returned from the context's target. + + The chan_bindings argument is used by the caller to provide + information binding the security context to security-related + characteristics (e.g., addresses, cryptographic keys) of the + underlying communications channel. See Section 1.1.6 of this document + for more discussion of this argument's usage. + + The input_token argument contains a message received from the target, + and is significant only on a call to GSS_Init_sec_context() which + follows a previous return indicating GSS_CONTINUE_NEEDED + major_status. + + It is the caller's responsibility to establish a communications path + to the target, and to transmit any returned output_token (independent + of the accompanying returned major_status value) to the target over + that path. The output_token can, however, be transmitted along with + + + +Linn [Page 24] + +RFC 1508 Generic Security Interface September 1993 + + + the first application-provided input message to be processed by + GSS_Sign() or GSS_Seal() in conjunction with a successfully- + established context. + + The initiator may request various context-level functions through + input flags: the deleg_req_flag requests delegation of access rights, + the mutual_req_flag requests mutual authentication, the + replay_det_req_flag requests that replay detection features be + applied to messages transferred on the established context, and the + sequence_req_flag requests that sequencing be enforced. (See Section + 1.2.3 for more information on replay detection and sequencing + features.) + + Not all of the optionally-requestable features will be available in + all underlying mech_types; the corresponding return state values + (deleg_state, mutual_state, replay_det_state, sequence_state) + indicate, as a function of mech_type processing capabilities and + initiator-provided input flags, the set of features which will be + active on the context. These state indicators' values are undefined + unless the routine's major_status indicates COMPLETE. Failure to + provide the precise set of features requested by the caller does not + cause context establishment to fail; it is the caller's prerogative + to delete the context if the feature set provided is unsuitable for + the caller's use. The returned mech_type value indicates the + specific mechanism employed on the context, and will never indicate + the value for "default". + + The conf_avail return value indicates whether the context supports + per-message confidentiality services, and so informs the caller + whether or not a request for encryption through the conf_req_flag + input to GSS_Seal() can be honored. In similar fashion, the + integ_avail return value indicates whether per-message integrity + services are available (through either GSS_Sign() or GSS_Seal()) on + the established context. + + The lifetime_req input specifies a desired upper bound for the + lifetime of the context to be established, with a value of 0 used to + request a default lifetime. The lifetime_rec return value indicates + the length of time for which the context will be valid, expressed as + an offset from the present; depending on mechanism capabilities, + credential lifetimes, and local policy, it may not correspond to the + value requested in lifetime_req. If no constraints on context + lifetime are imposed, this may be indicated by returning a reserved + value representing INDEFINITE lifetime_req. The values of conf_avail, + integ_avail, and lifetime_rec are undefined unless the routine's + major_status indicates COMPLETE. + + If the mutual_state is TRUE, this fact will be reflected within the + + + +Linn [Page 25] + +RFC 1508 Generic Security Interface September 1993 + + + output_token. A call to GSS_Accept_sec_context() at the target in + conjunction with such a context will return a token, to be processed + by a continuation call to GSS_Init_sec_context(), in order to achieve + mutual authentication. + +2.2.2. GSS_Accept_sec_context call + + Inputs: + + o acceptor_cred_handle OCTET STRING,-NULL specifies "use + default" + + o input_context_handle INTEGER, -0 specifies "not yet assigned" + + o chan_bindings OCTET STRING, + + o input_token OCTET STRING + + Outputs: + + o major_status INTEGER, + + o minor_status INTEGER, + + o src_name INTERNAL NAME, + + o mech_type OBJECT IDENTIFIER, + + o output_context_handle INTEGER, + + o deleg_state BOOLEAN, + + o mutual_state BOOLEAN, + + o replay_det_state BOOLEAN, + + o sequence_state BOOLEAN, + + o conf_avail BOOLEAN, + + o integ_avail BOOLEAN, + + o lifetime_rec INTEGER, - in seconds, or reserved value for + INDEFINITE + + o delegated_cred_handle OCTET STRING, + + o output_token OCTET STRING -NULL or token to pass to context + + + +Linn [Page 26] + +RFC 1508 Generic Security Interface September 1993 + + + initiator + + This call may block pending network interactions for those mech_types + in which a directory service or other network entity must be + consulted on behalf of a context acceptor in order to validate a + received input_token. + + Return major_status codes: + + o GSS_COMPLETE indicates that context-level data structures were + successfully initialized, and that per-message processing can now + be performed in conjunction with this context. + + o GSS_CONTINUE_NEEDED indicates that control information in the + returned output_token must be sent to the initiator, and that a + response must be received and passed as the input_token argument + to a continuation call to GSS_Accept_sec_context(), before per- + message processing can be performed in conjunction with this + context. + + o GSS_DEFECTIVE_TOKEN indicates that consistency checks performed on + the input_token failed, preventing further processing from being + performed based on that token. + + o GSS_DEFECTIVE_CREDENTIAL indicates that consistency checks + performed on the credential structure referenced by + acceptor_cred_handle failed, preventing further processing from + being performed using that credential structure. + + o GSS_BAD_SIG indicates that the received input_token contains an + incorrect signature, so context setup cannot be accomplished. + + o GSS_DUPLICATE_TOKEN indicates that the signature on the received + input_token was correct, but that the input_token was recognized + as a duplicate of an input_token already processed. No new context + is established. + + o GSS_OLD_TOKEN indicates that the signature on the received + input_token was correct, but that the input_token is too old to be + checked for duplication against previously-processed input_tokens. + No new context is established. + + o GSS_NO_CRED indicates that no context was established, either + because the input cred_handle was invalid, because the referenced + credentials are valid for context initiator use only, or because + the caller lacks authorization to access the referenced + credentials. + + + + +Linn [Page 27] + +RFC 1508 Generic Security Interface September 1993 + + + o GSS_CREDENTIALS_EXPIRED indicates that the credentials provided + through the input acceptor_cred_handle argument are no longer + valid, so context establishment cannot be completed. + + o GSS_BAD_BINDINGS indicates that a mismatch between the caller- + provided chan_bindings and those extracted from the input_token + was detected, signifying a security-relevant event and preventing + context establishment. + + o GSS_NO_CONTEXT indicates that no valid context was recognized for + the input context_handle provided; this major status will be + returned only for successor calls following GSS_CONTINUE_NEEDED + status returns. + + o GSS_FAILURE indicates that context setup could not be accomplished + for reasons unspecified at the GSS-API level, and that no + interface-defined recovery action is available. + + The GSS_Accept_sec_context() routine is used by a context target. + Using information in the credentials structure referenced by the + input acceptor_cred_handle, it verifies the incoming input_token and + (following the successful completion of a context establishment + sequence) returns the authenticated src_name and the mech_type used. + The acceptor_cred_handle must correspond to the same valid + credentials structure on the initial call to GSS_Accept_sec_context() + and on any successor calls resulting from GSS_CONTINUE_NEEDED status + returns; different protocol sequences modeled by the + GSS_CONTINUE_NEEDED mechanism will require access to credentials at + different points in the context establishment sequence. + + The input_context_handle argument is 0, specifying "not yet + assigned", on the first GSS_Accept_sec_context() call relating to a + given context. That call returns an output_context_handle for future + references to this context; when continuation attempts to + GSS_Accept_sec_context() are needed to perform context + establishment, that handle value will be entered into the + input_context_handle argument. + + The chan_bindings argument is used by the caller to provide + information binding the security context to security-related + characteristics (e.g., addresses, cryptographic keys) of the + underlying communications channel. See Section 1.1.6 of this document + for more discussion of this argument's usage. + + The returned state results (deleg_state, mutual_state, + replay_det_state, and sequence_state) reflect the same context state + values as returned to GSS_Init_sec_context()'s caller at the + initiator system. + + + +Linn [Page 28] + +RFC 1508 Generic Security Interface September 1993 + + + The conf_avail return value indicates whether the context supports + per-message confidentiality services, and so informs the caller + whether or not a request for encryption through the conf_req_flag + input to GSS_Seal() can be honored. In similar fashion, the + integ_avail return value indicates whether per-message integrity + services are available (through either GSS_Sign() or GSS_Seal()) on + the established context. + + The lifetime_rec return value indicates the length of time for which + the context will be valid, expressed as an offset from the present. + The values of deleg_state, mutual_state, replay_det_state, + sequence_state, conf_avail, integ_avail, and lifetime_rec are + undefined unless the accompanying major_status indicates COMPLETE. + + The delegated_cred_handle result is significant only when deleg_state + is TRUE, and provides a means for the target to reference the + delegated credentials. The output_token result, when non-NULL, + provides a context-level token to be returned to the context + initiator to continue a multi-step context establishment sequence. As + noted with GSS_Init_sec_context(), any returned token should be + transferred to the context's peer (in this case, the context + initiator), independent of the value of the accompanying returned + major_status. + + Note: A target must be able to distinguish a context-level + input_token, which is passed to GSS_Accept_sec_context(), from the + per-message data elements passed to GSS_Verify() or GSS_Unseal(). + These data elements may arrive in a single application message, and + GSS_Accept_sec_context() must be performed before per-message + processing can be performed successfully. + +2.2.3. GSS_Delete_sec_context call + + Input: + + o context_handle INTEGER + + Outputs: + + o major_status INTEGER, + + o minor_status INTEGER, + + o output_context_token OCTET STRING + + Return major_status codes: + + + + + +Linn [Page 29] + +RFC 1508 Generic Security Interface September 1993 + + + o GSS_COMPLETE indicates that the context was recognized, that + relevant context-specific information was flushed, and that the + returned output_context_token is ready for transfer to the + context's peer. + + o GSS_NO_CONTEXT indicates that no valid context was recognized for + the input context_handle provide, so no deletion was performed. + + o GSS_FAILURE indicates that the context is recognized, but that the + GSS_Delete_sec_context() operation could not be performed for + reasons unspecified at the GSS-API level. + + This call may block pending network interactions for mech_types in + which active notification must be made to a central server when a + security context is to be deleted. + + This call can be made by either peer in a security context, to flush + context-specific information and to return an output_context_token + which can be passed to the context's peer informing it that the + peer's corresponding context information can also be flushed. (Once a + context is established, the peers involved are expected to retain + cached credential and context-related information until the + information's expiration time is reached or until a + GSS_Delete_sec_context() call is made.) Attempts to perform per- + message processing on a deleted context will result in error returns. + +2.2.4. GSS_Process_context_token call + + Inputs: + + o context_handle INTEGER, + + o input_context_token OCTET STRING + + Outputs: + + o major_status INTEGER, + + o minor_status INTEGER, + + Return major_status codes: + + o GSS_COMPLETE indicates that the input_context_token was + successfully processed in conjunction with the context referenced + by context_handle. + + o GSS_DEFECTIVE_TOKEN indicates that consistency checks performed on + the received context_token failed, preventing further processing + + + +Linn [Page 30] + +RFC 1508 Generic Security Interface September 1993 + + + from being performed with that token. + + o GSS_NO_CONTEXT indicates that no valid context was recognized for + the input context_handle provided. + + o GSS_FAILURE indicates that the context is recognized, but that the + GSS_Process_context_token() operation could not be performed for + reasons unspecified at the GSS-API level. + + This call is used to process context_tokens received from a peer once + a context has been established, with corresponding impact on + context-level state information. One use for this facility is + processing of the context_tokens generated by + GSS_Delete_sec_context(); GSS_Process_context_token() will not block + pending network interactions for that purpose. Another use is to + process tokens indicating remote-peer context establishment failures + after the point where the local GSS-API implementation has already + indicated GSS_COMPLETE status. + +2.2.5. GSS_Context_time call + + Input: + + o context_handle INTEGER, + + Outputs: + + o major_status INTEGER, + + o minor_status INTEGER, + + o lifetime_rec INTEGER - in seconds, or reserved value for + INDEFINITE + + Return major_status codes: + + o GSS_COMPLETE indicates that the referenced context is valid, and + will remain valid for the amount of time indicated in + lifetime_rec. + + o GSS_CONTEXT_EXPIRED indicates that data items related to the + referenced context have expired. + + o GSS_CREDENTIALS_EXPIRED indicates that the context is recognized, + but that its associated credentials have expired. + + o GSS_NO_CONTEXT indicates that no valid context was recognized for + the input context_handle provided. + + + +Linn [Page 31] + +RFC 1508 Generic Security Interface September 1993 + + + o GSS_FAILURE indicates that the requested operation failed for + reasons unspecified at the GSS-API level. + + This call is used to determine the amount of time for which a + currently established context will remain valid. + +2.3. Per-message calls + + This group of calls is used to perform per-message protection + processing on an established security context. None of these calls + block pending network interactions. These calls may be invoked by a + context's initiator or by the context's target. The four members of + this group should be considered as two pairs; the output from + GSS_Sign() is properly input to GSS_Verify(), and the output from + GSS_Seal() is properly input to GSS_Unseal(). + + GSS_Sign() and GSS_Verify() support data origin authentication and + data integrity services. When GSS_Sign() is invoked on an input + message, it yields a per-message token containing data items which + allow underlying mechanisms to provide the specified security + services. The original message, along with the generated per-message + token, is passed to the remote peer; these two data elements are + processed by GSS_Verify(), which validates the message in + conjunction with the separate token. + + GSS_Seal() and GSS_Unseal() support caller-requested confidentiality + in addition to the data origin authentication and data integrity + services offered by GSS_Sign() and GSS_Verify(). GSS_Seal() outputs + a single data element, encapsulating optionally enciphered user data + as well as associated token data items. The data element output from + GSS_Seal() is passed to the remote peer and processed by + GSS_Unseal() at that system. GSS_Unseal() combines decipherment (as + required) with validation of data items related to authentication and + integrity. + +2.3.1. GSS_Sign call + + Inputs: + + o context_handle INTEGER, + + o qop_req INTEGER,-0 specifies default QOP + + o message OCTET STRING + + Outputs: + + o major_status INTEGER, + + + +Linn [Page 32] + +RFC 1508 Generic Security Interface September 1993 + + + o minor_status INTEGER, + + o per_msg_token OCTET STRING + + Return major_status codes: + + o GSS_COMPLETE indicates that a signature, suitable for an + established security context, was successfully applied and that + the message and corresponding per_msg_token are ready for + transmission. + + o GSS_CONTEXT_EXPIRED indicates that context-related data items have + expired, so that the requested operation cannot be performed. + + o GSS_CREDENTIALS_EXPIRED indicates that the context is recognized, + but that its associated credentials have expired, so that the + requested operation cannot be performed. + + o GSS_NO_CONTEXT indicates that no valid context was recognized for + the input context_handle provided. + + o GSS_FAILURE indicates that the context is recognized, but that the + requested operation could not be performed for reasons unspecified + at the GSS-API level. + + Using the security context referenced by context_handle, apply a + signature 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 allows quality- + of-protection control. The caller passes the message and the + per_msg_token to the target. + + The GSS_Sign() function completes before the message and + per_msg_token is sent to the peer; successful application of + GSS_Sign() does not guarantee that a corresponding GSS_Verify() has + been (or can necessarily be) performed successfully when the message + arrives at the destination. + +2.3.2. GSS_Verify call + + Inputs: + + o context_handle INTEGER, + + o message OCTET STRING, + + o per_msg_token OCTET STRING + + + + +Linn [Page 33] + +RFC 1508 Generic Security Interface September 1993 + + + Outputs: + + o qop_state INTEGER, + + o major_status INTEGER, + + o minor_status INTEGER, + + Return major_status codes: + + o GSS_COMPLETE indicates that the message was successfully verified. + + o GSS_DEFECTIVE_TOKEN indicates that consistency checks performed on + the received per_msg_token failed, preventing further processing + from being performed with that token. + + o GSS_BAD_SIG indicates that the received per_msg_token contains an + incorrect signature for the message. + + o GSS_DUPLICATE_TOKEN, GSS_OLD_TOKEN, and GSS_UNSEQ_TOKEN values + appear in conjunction with the optional per-message replay + detection features described in Section 1.2.3; their semantics are + described in that section. + + o GSS_CONTEXT_EXPIRED indicates that context-related data items have + expired, so that the requested operation cannot be performed. + + o GSS_CREDENTIALS_EXPIRED indicates that the context is recognized, + but that its associated credentials have expired, so that the + requested operation cannot be performed. + + o GSS_NO_CONTEXT indicates that no valid context was recognized for + the input context_handle provided. + + o GSS_FAILURE indicates that the context is recognized, but that the + GSS_Verify() 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 signature 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. + + + + + + + + +Linn [Page 34] + +RFC 1508 Generic Security Interface September 1993 + + +2.3.3. GSS_Seal call + + Inputs: + + o context_handle INTEGER, + + o conf_req_flag BOOLEAN, + + o qop_req INTEGER,-0 specifies default QOP + + o input_message OCTET STRING + + Outputs: + + o major_status INTEGER, + + o minor_status INTEGER, + + o conf_state BOOLEAN, + + o output_message OCTET STRING + + Return major_status codes: + + o GSS_COMPLETE indicates that the input_message was successfully + processed and that the output_message is ready for transmission. + + o GSS_CONTEXT_EXPIRED indicates that context-related data items have + expired, so that the requested operation cannot be performed. + + o GSS_CREDENTIALS_EXPIRED indicates that the context is recognized, + but that its associated credentials have expired, so that the + requested operation cannot be performed. + + o GSS_NO_CONTEXT indicates that no valid context was recognized for + the input context_handle provided. + + o GSS_FAILURE indicates that the context is recognized, but that the + GSS_Seal() operation could not be performed for reasons + unspecified at the GSS-API level. + + Performs the data origin authentication and data integrity functions + of GSS_Sign(). If the input conf_req_flag is TRUE, requests that + confidentiality be applied to the input_message. Confidentiality may + not be supported in all mech_types or by all implementations; the + returned conf_state flag indicates whether confidentiality was + provided for the input_message. The qop_req parameter allows + quality-of-protection control. + + + +Linn [Page 35] + +RFC 1508 Generic Security Interface September 1993 + + + In all cases, the GSS_Seal() call yields a single output_message + data element containing (optionally enciphered) user data as well as + control information. + +2.3.4. GSS_Unseal call + + Inputs: + + o context_handle INTEGER, + + o input_message OCTET STRING + + Outputs: + + o conf_state BOOLEAN, + + o qop_state INTEGER, + + o major_status INTEGER, + + o minor_status INTEGER, + + o output_message OCTET STRING + + Return major_status codes: + + o GSS_COMPLETE indicates that the input_message was successfully + processed and that the resulting output_message is available. + + o GSS_DEFECTIVE_TOKEN indicates that consistency checks performed on + the per_msg_token extracted from the input_message failed, + preventing further processing from being performed. + + o GSS_BAD_SIG indicates that an incorrect signature was detected for + the message. + + o GSS_DUPLICATE_TOKEN, GSS_OLD_TOKEN, and GSS_UNSEQ_TOKEN values + appear in conjunction with the optional per-message replay + detection features described in Section 1.2.3; their semantics are + described in that section. + + o GSS_CONTEXT_EXPIRED indicates that context-related data items have + expired, so that the requested operation cannot be performed. + + o GSS_CREDENTIALS_EXPIRED indicates that the context is recognized, + but that its associated credentials have expired, so that the + requested operation cannot be performed. + + + + +Linn [Page 36] + +RFC 1508 Generic Security Interface September 1993 + + + o GSS_NO_CONTEXT indicates that no valid context was recognized for + the input context_handle provided. + + o GSS_FAILURE indicates that the context is recognized, but that the + GSS_Unseal() operation could not be performed for reasons + unspecified at the GSS-API level. + + Processes a data element generated (and optionally enciphered) by + GSS_Seal(), provided as input_message. The returned conf_state value + indicates whether confidentiality was applied to the input_message. + If conf_state is TRUE, GSS_Unseal() deciphers the input_message. + Returns an indication of the quality-of-protection applied to the + processed message in the qop_state result. GSS_Seal() performs the + data integrity and data origin authentication checking functions of + GSS_Verify() on the plaintext data. Plaintext data is returned in + output_message. + +2.4. Support calls + + This group of calls provides support functions useful to GSS-API + callers, independent of the state of established contexts. Their + characterization with regard to blocking or non-blocking status in + terms of network interactions is unspecified. + +2.4.1. GSS_Display_status call + + Inputs: + + o status_value INTEGER,-GSS-API major_status or minor_status + return value + + o status_type INTEGER,-1 if major_status, 2 if minor_status + + o mech_type OBJECT IDENTIFIER-mech_type to be used for minor_ + status translation + + Outputs: + + o major_status INTEGER, + + o minor_status INTEGER, + + o status_string_set SET OF OCTET STRING + + Return major_status codes: + + o GSS_COMPLETE indicates that a valid printable status + representation (possibly representing more than one status event + + + +Linn [Page 37] + +RFC 1508 Generic Security Interface September 1993 + + + encoded within the status_value) is available in the returned + status_string_set. + + o GSS_BAD_MECH indicates that translation in accordance with an + unsupported mech_type was requested, so translation could not be + performed. + + o GSS_BAD_STATUS indicates that the input status_value was invalid, + or that the input status_type carried a value other than 1 or 2, + so translation could not be performed. + + o GSS_FAILURE indicates that the requested operation could not be + performed for reasons unspecified at the GSS-API level. + + Provides a means for callers to translate GSS-API-returned major and + minor status codes into printable string representations. + +2.4.2. GSS_Indicate_mechs call + + Input: + + o (none) + + Outputs: + + o major_status INTEGER, + + o minor_status INTEGER, + + o mech_set SET OF OBJECT IDENTIFIER + + Return major_status codes: + + o GSS_COMPLETE indicates that a set of available mechanisms has + been returned in mech_set. + + o GSS_FAILURE indicates that the requested operation could not + be performed for reasons unspecified at the GSS-API level. + + Allows callers to determine the set of mechanism types available on + the local system. This call is intended for support of specialized + callers who need to request non-default mech_type sets from + GSS_Acquire_cred(), and should not be needed by other callers. + +2.4.3. GSS_Compare_name call + + Inputs: + + + + +Linn [Page 38] + +RFC 1508 Generic Security Interface September 1993 + + + o name1 INTERNAL NAME, + + o name2 INTERNAL NAME + + Outputs: + + o major_status INTEGER, + + o minor_status INTEGER, + + o name_equal BOOLEAN + + Return major_status codes: + + o GSS_COMPLETE indicates that name1 and name2 were comparable, and + that the name_equal result indicates whether name1 and name2 were + equal or unequal. + + o GSS_BAD_NAMETYPE indicates that one or both of name1 and name2 + contained internal type specifiers uninterpretable by the + supporting GSS-API implementation, or that the two names' types + are different and incomparable, so the equality comparison could + not be completed. + + o GSS_BAD_NAME indicates that one or both of the input names was + ill-formed in terms of its internal type specifier, so the + equality comparison could not be completed. + + o GSS_FAILURE indicates that the requested operation could not be + performed for reasons unspecified at the GSS-API level. + + Allows callers to compare two internal name representations for + equality. + +2.4.4. GSS_Display_name call + + Inputs: + + o name INTERNAL NAME + + Outputs: + + o major_status INTEGER, + + o minor_status INTEGER, + + o name_string OCTET STRING, + + + + +Linn [Page 39] + +RFC 1508 Generic Security Interface September 1993 + + + o name_type OBJECT IDENTIFIER + + Return major_status codes: + + o GSS_COMPLETE indicates that a valid printable name representation + is available in the returned name_string. + + o GSS_BAD_NAMETYPE indicates that the provided name was of a type + uninterpretable by the supporting GSS-API implementation, so no + printable representation could be generated. + + o GSS_BAD_NAME indicates that the contents of the provided name were + inconsistent with the internally-indicated name type, so no + printable representation could be generated. + + o GSS_FAILURE indicates that the requested operation could not be + performed for reasons unspecified at the GSS-API level. + + Allows callers to translate an internal name representation into a + printable form with associated namespace type descriptor. The syntax + of the printable form is a local matter. + +2.4.5. GSS_Import_name call + + Inputs: + + o input_name_string OCTET STRING, + + o input_name_type OBJECT IDENTIFIER + + Outputs: + + o major_status INTEGER, + + o minor_status INTEGER, + + o output_name INTERNAL NAME + + Return major_status codes: + + o GSS_COMPLETE indicates that a valid name representation is output + in output_name and described by the type value in + output_name_type. + + o GSS_BAD_NAMETYPE indicates that the input_name_type is unsupported + by the GSS-API implementation, so the import operation could not + be completed. + + + + +Linn [Page 40] + +RFC 1508 Generic Security Interface September 1993 + + + o GSS_BAD_NAME indicates that the provided input_name_string is + ill-formed in terms of the input_name_type, so the import + operation could not be completed. + + o GSS_FAILURE indicates that the requested operation could not be + performed for reasons unspecified at the GSS-API level. + + Allows callers to provide a printable name representation, designate + the type of namespace in conjunction with which it should be parsed, + and convert that printable representation to an internal form + suitable for input to other GSS-API routines. The syntax of the + input_name is a local matter. + +2.4.6. GSS_Release_name call + + Inputs: + + o name INTERNAL NAME + + Outputs: + + o major_status INTEGER, + + o minor_status INTEGER + + Return major_status codes: + + o GSS_COMPLETE indicates that the storage associated with the input + name was successfully released. + + o GSS_BAD_NAME indicates that the input name argument did not + contain a valid name. + + o GSS_FAILURE indicates that the requested operation could not be + performed for reasons unspecified at the GSS-API level. + + Allows callers to release the storage associated with an internal + name representation. + +2.4.7. GSS_Release_buffer call + + Inputs: + + o buffer OCTET STRING + + Outputs: + + o major_status INTEGER, + + + +Linn [Page 41] + +RFC 1508 Generic Security Interface September 1993 + + + o minor_status INTEGER + + Return major_status codes: + + o GSS_COMPLETE indicates that the storage associated with the input + buffer was successfully released. + + o GSS_FAILURE indicates that the requested operation could not be + performed for reasons unspecified at the GSS-API level. + + Allows callers to release the storage associated with an OCTET STRING + buffer allocated by another GSS-API call. + +2.4.8. GSS_Release_oid_set call + + Inputs: + + o buffer SET OF OBJECT IDENTIFIER + + Outputs: + + o major_status INTEGER, + + o minor_status INTEGER + + Return major_status codes: + + o GSS_COMPLETE indicates that the storage associated with the input + object identifier set was successfully released. + + o GSS_FAILURE indicates that the requested operation could not be + performed for reasons unspecified at the GSS-API level. + + Allows callers to release the storage associated with an object + identifier set object allocated by another GSS-API call. + +3. Mechanism-Specific Example Scenarios + + This section provides illustrative overviews of the use of various + candidate mechanism types to support the GSS-API. These discussions + are intended primarily for readers familiar with specific security + technologies, demonstrating how GSS-API functions can be used and + implemented by candidate underlying mechanisms. They should not be + regarded as constrictive to implementations or as defining the only + means through which GSS-API functions can be realized with a + particular underlying technology, and do not demonstrate all GSS-API + features with each technology. + + + + +Linn [Page 42] + +RFC 1508 Generic Security Interface September 1993 + + +3.1. Kerberos V5, single-TGT + + OS-specific login functions yield a TGT to the local realm Kerberos + server; TGT is placed in a credentials structure for the client. + Client calls GSS_Acquire_cred() to acquire a cred_handle in order to + reference the credentials for use in establishing security contexts. + + Client calls GSS_Init_sec_context(). If the requested service is + located in a different realm, GSS_Init_sec_context() gets the + necessary TGT/key pairs needed to traverse the path from local to + target realm; these data are placed in the owner's TGT cache. After + any needed remote realm resolution, GSS_Init_sec_context() yields a + service ticket to the requested service with a corresponding session + key; these data are stored in conjunction with the context. GSS-API + code sends KRB_TGS_REQ request(s) and receives KRB_TGS_REP + response(s) (in the successful case) or KRB_ERROR. + + Assuming success, GSS_Init_sec_context() builds a Kerberos-formatted + KRB_AP_REQ message, and returns it in output_token. The client sends + the output_token to the service. + + The service passes the received token as the input_token argument to + GSS_Accept_sec_context(), which verifies the authenticator, provides + the service with the client's authenticated name, and returns an + output_context_handle. + + Both parties now hold the session key associated with the service + ticket, and can use this key in subsequent GSS_Sign(), GSS_Verify(), + GSS_Seal(), and GSS_Unseal() operations. + +3.2. Kerberos V5, double-TGT + + TGT acquisition as above. + + Note: To avoid unnecessary frequent invocations of error paths when + implementing the GSS-API atop Kerberos V5, it seems appropriate to + represent "single-TGT K-V5" and "double-TGT K-V5" with separate + mech_types, and this discussion makes that assumption. + + Based on the (specified or defaulted) mech_type, + GSS_Init_sec_context() determines that the double-TGT protocol + should be employed for the specified target. GSS_Init_sec_context() + returns GSS_CONTINUE_NEEDED major_status, and its returned + output_token contains a request to the service for the service's TGT. + (If a service TGT with suitably long remaining lifetime already + exists in a cache, it may be usable, obviating the need for this + step.) The client passes the output_token to the service. Note: this + scenario illustrates a different use for the GSS_CONTINUE_NEEDED + + + +Linn [Page 43] + +RFC 1508 Generic Security Interface September 1993 + + + status return facility than for support of mutual authentication; + note that both uses can coexist as successive operations within a + single context establishment operation. + + The service passes the received token as the input_token argument to + GSS_Accept_sec_context(), which recognizes it as a request for TGT. + (Note that current Kerberos V5 defines no intra-protocol mechanism to + represent such a request.) GSS_Accept_sec_context() returns + GSS_CONTINUE_NEEDED major_status and provides the service's TGT in + its output_token. The service sends the output_token to the client. + + The client passes the received token as the input_token argument to a + continuation of GSS_Init_sec_context(). GSS_Init_sec_context() caches + the received service TGT and uses it as part of a service ticket + request to the Kerberos authentication server, storing the returned + service ticket and session key in conjunction with the context. + GSS_Init_sec_context() builds a Kerberos-formatted authenticator, + and returns it in output_token along with GSS_COMPLETE return + major_status. The client sends the output_token to the service. + + Service passes the received token as the input_token argument to a + continuation call to GSS_Accept_sec_context(). + GSS_Accept_sec_context() verifies the authenticator, provides the + service with the client's authenticated name, and returns + major_status GSS_COMPLETE. + + GSS_Sign(), GSS_Verify(), GSS_Seal(), and GSS_Unseal() as above. + +3.3. X.509 Authentication Framework + + This example illustrates use of the GSS-API in conjunction with + public-key mechanisms, consistent with the X.509 Directory + Authentication Framework. + + The GSS_Acquire_cred() call establishes a credentials structure, + making the client's private key accessible for use on behalf of the + client. + + The client calls GSS_Init_sec_context(), which interrogates the + Directory to acquire (and validate) a chain of public-key + certificates, thereby collecting the public key of the service. The + certificate validation operation determines that suitable signatures + were applied by trusted authorities and that those certificates have + not expired. GSS_Init_sec_context() generates a secret key for use + in per-message protection operations on the context, and enciphers + that secret key under the service's public key. + + The enciphered secret key, along with an authenticator quantity + + + +Linn [Page 44] + +RFC 1508 Generic Security Interface September 1993 + + + signed with the client's private key, is included in the output_token + from GSS_Init_sec_context(). The output_token also carries a + certification path, consisting of a certificate chain leading from + the service to the client; a variant approach would defer this path + resolution to be performed by the service instead of being asserted + by the client. The client application sends the output_token to the + service. + + The service passes the received token as the input_token argument to + GSS_Accept_sec_context(). GSS_Accept_sec_context() validates the + certification path, and as a result determines a certified binding + between the client's distinguished name and the client's public key. + Given that public key, GSS_Accept_sec_context() can process the + input_token's authenticator quantity and verify that the client's + private key was used to sign the input_token. At this point, the + client is authenticated to the service. The service uses its private + key to decipher the enciphered secret key provided to it for per- + message protection operations on the context. + + The client calls GSS_Sign() or GSS_Seal() on a data message, which + causes per-message authentication, integrity, and (optional) + confidentiality facilities to be applied to that message. The service + uses the context's shared secret key to perform corresponding + GSS_Verify() and GSS_Unseal() calls. + +4. 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 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; such bindings + for the C language are available in an associated RFC. + + + + + + + + +Linn [Page 45] + +RFC 1508 Generic Security Interface September 1993 + + +5. Acknowledgments + + This proposal is the result of a collaborative effort. + Acknowledgments are due to the many members of the IETF Security Area + Advisory Group (SAAG) and the Common Authentication Technology (CAT) + Working Group for their contributions at meetings and by electronic + mail. Acknowledgments are also due to Kannan Alagappan, Doug Barlow, + Bill Brown, Cliff Kahn, Charlie Kaufman, Butler Lampson, Richard + Pitkin, Joe Tardo, and John Wray of Digital Equipment Corporation, + and John Carr, John Kohl, Jon Rochlis, Jeff Schiller, and Ted T'so of + MIT and Project Athena. Joe Pato and Bill Sommerfeld of HP/Apollo, + Walt Tuvell of OSF, and Bill Griffith and Mike Merritt of AT&T, + provided inputs which helped to focus and clarify directions. + Precursor work by Richard Pitkin, presented to meetings of the + Trusted Systems Interoperability Group (TSIG), helped to demonstrate + the value of a generic, mechanism-independent security service API. + +6. Security Considerations + + Security issues are discussed throughout this memo. + +7. Author's Address + + John Linn + Geer Zolot Associates + One Main St. + Cambridge, MA 02142 USA + + Phone: +1 617.374.3700 + Email: Linn@gza.com + + + + + + + + + + + + + + + + + + + + + +Linn [Page 46] + +RFC 1508 Generic Security Interface September 1993 + + +APPENDIX A + +PACS AND AUTHORIZATION SERVICES + + Consideration has been given to modifying the GSS-API service + interface to recognize and manipulate Privilege Attribute + Certificates (PACs) as in ECMA 138, carrying authorization data as a + side effect of establishing a security context, but no such + modifications have been incorporated at this time. This appendix + provides rationale for this decision and discusses compatibility + alternatives between PACs and the GSS-API which do not require that + PACs be made visible to GSS-API callers. + + Existing candidate mechanism types such as Kerberos and X.509 do not + incorporate PAC manipulation features, and exclusion of such + mechanisms from the set of candidates equipped to fully support the + GSS-API seems inappropriate. Inclusion (and GSS-API visibility) of a + feature supported by only a limited number of mechanisms could + encourage the development of ostensibly portable applications which + would in fact have only limited portability. + + The status quo, in which PACs are not visible across the GSS-API + interface, does not preclude implementations in which PACs are + carried transparently, within the tokens defined and used for certain + mech_types, and stored within peers' credentials and context-level + data structures. While invisible to API callers, such PACs could be + used by operating system or other local functions as inputs in the + course of mediating access requests made by callers. This course of + action allows dynamic selection of PAC contents, if such selection is + administratively-directed rather than caller-directed. + + In a distributed computing environment, authentication must span + different systems; the need for such authentication provides + motivation for GSS-API definition and usage. Heterogeneous systems in + a network can intercommunicate, with globally authenticated names + comprising the common bond between locally defined access control + policies. Access control policies to which authentication provides + inputs are often local, or specific to particular operating systems + or environments. If the GSS-API made particular authorization models + visible across its service interface, its scope of application would + become less general. The current GSS-API paradigm is consistent with + the precedent set by Kerberos, neither defining the interpretation of + authorization-related data nor enforcing access controls based on + such data. + + The GSS-API is a general interface, whose callers may reside inside + or outside any defined TCB or NTCB boundaries. Given this + characteristic, it appears more realistic to provide facilities which + + + +Linn [Page 47] + +RFC 1508 Generic Security Interface September 1993 + + + provide "value-added" security services to its callers than to offer + facilities which enforce restrictions on those callers. Authorization + decisions must often be mediated below the GSS-API level in a local + manner against (or in spite of) applications, and cannot be + selectively invoked or omitted at those applications' discretion. + Given that the GSS-API's placement prevents it from providing a + comprehensive solution to the authorization issue, the value of a + partial contribution specific to particular authorization models is + debatable. + +APPENDIX B + +MECHANISM-INDEPENDENT TOKEN FORMAT + + This appendix specifies a mechanism-independent level of + encapsulating representation for the initial token of a GSS-API + context establishment sequence, incorporating an identifier of the + mechanism type to be used on that context. Use of this format (with + ASN.1-encoded data elements represented in BER, constrained in the + interests of parsing simplicity to the Distinguished Encoding Rule + (DER) BER subset defined in X.509, clause 8.7) is recommended to the + designers of GSS-API implementations based on various mechanisms, so + that tokens can be interpreted unambiguously at GSS-API peers. There + is no requirement that the mechanism-specific innerContextToken, + innerMsgToken, and sealedUserData data elements be encoded in ASN.1 + BER. + + -- optional top-level token definitions to + -- frame different mechanisms + + 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 + + + +Linn [Page 48] + +RFC 1508 Generic Security Interface September 1993 + + + -- contents mechanism-specific + } + + SubsequentContextToken ::= innerContextToken ANY + -- interpretation based on predecessor InitialContextToken + + PerMsgToken ::= + -- as emitted by GSS_Sign and processed by GSS_Verify + innerMsgToken ANY + + SealedMessage ::= + -- as emitted by GSS_Seal and processed by GSS_Unseal + -- includes internal, mechanism-defined indicator + -- of whether or not encrypted + sealedUserData ANY + + END + +APPENDIX C + +MECHANISM DESIGN CONSTRAINTS + + The following constraints on GSS-API mechanism designs are adopted in + response to observed caller protocol requirements, and adherence + thereto is anticipated in subsequent descriptions of GSS-API + mechanisms to be documented in standards-track Internet + specifications. + + Use of the approach defined in Appendix B of this specification, + applying a mechanism type tag to the InitialContextToken, is + required. + + It is strongly recommended that mechanisms offering per-message + protection services also offer at least one of the replay detection + and sequencing services, as mechanisms offering neither of the latter + will fail to satisfy recognized requirements of certain candidate + caller protocols. + + + + + + + + + + + + + + +Linn [Page 49] +
\ No newline at end of file |
