doc: Add RFC documents

1 files changed, 2747 insertions, 0 deletions

diff --git a/doc/rfc/rfc1508.txt b/doc/rfc/rfc1508.txt
new file mode 100644
index 0000000..132b855
--- /dev/null
+++ b/doc/rfc/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