[Docs] [txt|pdf] [Tracker] [WG] [Email] [Diff1] [Diff2] [Nits]

Versions: 00 02 RFC 1508

                 Generic Security Service API: Internet-Draft: August 1992
                      Common Authentication Technology WG: John Linn (DEC)
       
       
                                      John Linn
                     Networking and Communications Architecture
                            Digital Equipment Corporation
                             550 King Street, LKG1-2/A19
                                 Littleton, MA 01460
                              Linn@erlang.enet.dec.com
       
          STATUS OF THIS MEMO
       
          This document is an Internet Draft. Internet Drafts are working
          documents of the Internet Engineering Task Force (IETF), its
          Areas, and its Working Groups. Note that other groups may also
          distribute working documents as Internet Drafts.
       
          Internet Drafts are draft documents valid for a maximum of six
          months. Internet Drafts may be updated, replaced, or obsoleted
          by other documents at any time. It is not appropriate to use
          Internet Drafts as reference material or to cite them other than
          as a "working draft" or "work in progress."
       
          Please check the I-D abstract listing contained in each Internet
          Draft directory to learn the current status of this or any other
          Internet Draft.
       
          1  GSS-API Characteristics and Concepts
       
          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 speci-
          fications:
       
          o  documents defining specific parameter bindings for particular
             language environments
       
                                  Document Expiration: 28 February 1993  1
       
       
       
       
          Generic Security Service API: Internet-Draft: August 1992
          Common Authentication Technology WG: John Linn (DEC)
       
       
          o  documents defining token formats, protocols, and procedures
             to be implemented in order to realize GSS-API services atop
             particular security mechanisms
       
       
       
          The operational paradigm in which GSS-API operates (also sum-
          marized in Figure 1 in the graphic version of this document)
          is as follows. A typical GSS-API caller is itself a communi-
          cations protocol, calling on GSS-API in order to protect its
          communications with authentication, integrity, and/or confi-
          dentiality security services. A GSS-API caller accepts tokens
          provided to it by its local GSS-API implementation and trans-
          fers the tokens to a peer on a remote system; that peer passes
          the received tokens to its local GSS-API implementation for
          processing. The security services available through GSS-API
          in this fashion are implementable (and have been implemented)
          over a range of underlying mechanisms based on secret-key and
          public-key cryptographic technologies.
       
          The GSS-API separates the operations of initializing a security
          context between peers, achieving peer entity authentication[1]
          (GSS_Init_sec_context()  and GSS_Accept_sec_context() calls),
          from the operations of providing per-message data origin au-
          thentication and data integrity protection (GSS_Sign()  and GSS_
          Verify()  calls) for messages subsequently transferred in con-
          junction 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.
       
       
          ___________________
        [1] This security service definition, and other definitions used
            in this document, corresponds to that provided in Interna-
       
            tional Standard ISO 7498-2-1988(E), Security Architecture.
       
          2  Document Expiration: 28 February 1993
       
       
       
       
                 Generic Security Service API: Internet-Draft: August 1992
                      Common Authentication Technology WG: John Linn (DEC)
       
       
          In the graphic version of this document, Figure 2 illustrates
          the dataflows involved in use of the GSS-API by a client and
          server in a mechanism-independent fashion, establishing a secu-
          rity context and transferring a protected message. The example
          assumes that credential acquisition has already been completed.
          Only a subset of parameter and result values are illustrated,
          for reasons of clarity in exposition. Further, it is assumed
          that the underlying authentication technology is capable of au-
          thenticating 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 as-
          sumption 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 per-
          formed 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 re-
          turned GSS_COMPLETE status. The client sends the output_token to
          the server.
       
          The server passes the received token as the input_token pa-
          rameter to GSS_Accept_sec_context().  GSS_Accept_sec_context
          indicates GSS_COMPLETE status, provides the client's authenti-
          cated 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.
       
       
       
       
       
       
                                  Document Expiration: 28 February 1993  3
       
       
       
       
          Generic Security Service API: Internet-Draft: August 1992
          Common Authentication Technology WG: John Linn (DEC)
       
       
          The client passes the received token as the input_token pa-
          rameter to a successor call to GSS_Init_sec_context(),  which
          processes data included in the token in order to achieve mu-
          tual 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, indi-
          cating 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(),  de-
          ciphers the message if the optional confidentiality feature was
          applied, and validates the data origin authentication and data
          integrity checking quantities. GSS_Unseal()  indicates success-
          ful 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 delet-
          ing context-level information at the client system.
       
          The GSS-API design assumes and addresses several basic goals,
          including:
       
          o  Mechanism independence: The GSS-API defines an interface
             to cryptographically implemented strong authentication and
       
          4  Document Expiration: 28 February 1993
       
       
       
       
                 Generic Security Service API: Internet-Draft: August 1992
                      Common Authentication Technology WG: John Linn (DEC)
       
       
             other security services at a generic level which is inde-
             pendent 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).
       
          o  Protocol environment independence: The GSS-API is indepen-
             dent of the communications protocol suites with which it is
             employed, permitting use in a broad range of protocol en-
             vironments. 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 proto-
             col and the GSS-API, thereby invoking GSS-API facilities in
             conjunction with that protocol's communications invocations.
       
          o  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 in-
             voking protocol modules on behalf of those modules' calling
             applications. GSS-API services can also be invoked directly
             by applications, wholly independent of protocol associations.
       
          o  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.
       
       
       
       
       
                                  Document Expiration: 28 February 1993  5
       
       
       
       
          Generic Security Service API: Internet-Draft: August 1992
          Common Authentication Technology WG: John Linn (DEC)
       
       
          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 es-
          tablishment 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 require-
          ments. The credential elements defined by a particular mechanism
          may contain multiple cryptographic keys, e.g., to enable authen-
          tication and message encryption to be performed with different
          algorithms.
       
          A single credential structure may accommodate credential in-
          formation 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 im-
          plementation. 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 cre-
          dential sets representing multiple mech_types is to allow ini-
          tiators on systems which are equipped to handle multiple types
          to initiate contexts to targets on other systems which can ac-
          commodate only a subset of the set supported at the initiator's
          system.
       
          It is the responsibility of underlying system-specific mech-
          anisms and OS functions below the GSS-API to ensure that the
          ability to acquire and use credentials associated with a given
       
       
          6  Document Expiration: 28 February 1993
       
       
       
       
                 Generic Security Service API: Internet-Draft: August 1992
                      Common Authentication Technology WG: John Linn (DEC)
       
       
          identity is constrained to appropriate processes within a sys-
          tem. This responsibility should be taken seriously by implemen-
          tors, as the ability for an entity to utilize a principal's cre-
          dentials is equivalent to the entity's ability to successfully
          assert that principal's identity.
       
          Once a set of GSS-API credentials is established, the transfer-
          ability 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 cre-
          dentials 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 per-
          formed 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 pre-
          liminary credential establishment to be performed through local
          means at user login time, with the result(s) cached for sub-
          sequent reference. These preliminary credentials would be set
          aside (in a system-specific fashion) for subsequent use, either:
       
          o  to be accessed by an invocation of the GSS-API GSS_Acquire_
             cred()  call, returning an explicit handle to reference that
             credential
       
          o  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 ex-
          changed 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 ser-
          vices for corresponding data messages. The internal contents of
          both classes of tokens are specific to the particular underlying
       
                                  Document Expiration: 28 February 1993  7
       
       
       
       
          Generic Security Service API: Internet-Draft: August 1992
          Common Authentication Technology WG: John Linn (DEC)
       
       
          mechanism used to support the GSS-API; Appendix B of this docu-
          ment provides a uniform recommendation for designers of GSS-API
          support mechanisms, encapsulating mechanism-specific information
          along with a globally-interpretable mechanism identifier.
       
          Tokens are opaque from the viewpoint of GSS-API callers. They
          are generated within the GSS-API implementation at an end sys-
          tem, 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 partic-
          ular 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 conjunc-
          tion 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 cre-
          dentials established locally in conjunction with each peer or
          received by peers via delegation. Multiple contexts may ex-
          ist simultaneously between a pair of peers, using the same or
          different sets of credentials. Coexistence of multiple con-
          texts using different credentials allows graceful rollover when
          credentials expire. Distinction among multiple contexts based
       
       
          8  Document Expiration: 28 February 1993
       
       
       
       
                 Generic Security Service API: Internet-Draft: August 1992
                      Common Authentication Technology WG: John Linn (DEC)
       
       
          on the same credentials serves applications by distinguishing
          different message streams in a security sense.
       
          The GSS-API is independent of underlying protocols and address-
          ing 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, separat-
          ing 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[ 2]. This separation allows
          the GSS-API to be used in a wide range of communications en-
          vironments, and also simplifies the calling sequences of the
          individual calls. In many cases (depending on underlying secu-
          rity 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 underly-
          ing 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.
       
          ___________________
       [ 2] The optional channel binding facility, discussed in Sec-
            tion 1.1.6 of this document, represents an intentional excep-
            tion to this rule, supporting additional protection features
       
            within GSS-API supporting mechanisms.
       
                                  Document Expiration: 28 February 1993  9
       
       
       
       
          Generic Security Service API: Internet-Draft: August 1992
          Common Authentication Technology WG: John Linn (DEC)
       
       
          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):
       
          o  use of a fixed mech_type, defined by configuration, within an
             environment
       
          o  syntactic convention on a target-specific basis, through
             examination of a target's name
       
          o  lookup of a target's name in a naming service or other
             database in order to identify mech_types supported by that
             target
       
          o  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 [3](OIDs))
          serve to qualify the interpretation of associated tokens. Use
          of hierarchically structured OIDs serves to preclude ambiguous
          interpretation of mech_type specifiers. The OID representing the
          DASS MechType, for example, is 1.3.12.2.1011.7.5.
       
       
       
       
          ___________________
        [3] 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)".
       
          10  Document Expiration: 28 February 1993
       
       
       
       
                 Generic Security Service API: Internet-Draft: August 1992
                      Common Authentication Technology WG: John Linn (DEC)
       
       
          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 antici-
          pated.
       
          Two distinct classes of name representations are used in con-
          junction with different GSS-API parameters:
       
          o  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
       
          o  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.
       
       
       
       
                                 Document Expiration: 28 February 1993  11
       
       
       
       
          Generic Security Service API: Internet-Draft: August 1992
          Common Authentication Technology WG: John Linn (DEC)
       
       
          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[4] 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.
       
          GSS_Import_name()  implementations can, where appropriate, sup-
          port 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 appropri-
          ate to their operational environments; this selection is a local
          matter. Callers desiring portability across alternative print-
          able 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.
       
       
       
       
       
       
       
          ___________________
        [4] It is anticipated that these proposed GSS-API calls will
            be implemented in many end systems based on system-specific
            name manipulation primitives already extant within those end
            systems; inclusion within the GSS-API is intended to offer
            GSS-API callers a portable means to perform specific opera-
            tions, supportive of authorization and audit requirements, on
       
            authenticated names.
       
          12  Document Expiration: 28 February 1993
       
       
       
       
                 Generic Security Service API: Internet-Draft: August 1992
                      Common Authentication Technology WG: John Linn (DEC)
       
       
          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 im-
          plementors are defining[ 5] conventional interpretations for
          the contents of channel binding arguments, including address
          specifiers (with content dependent on communications protocol
          environment) for context initiators and acceptors. 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 pro-
          vide channel bindings consistent with these conventions and
          those of the networking environment in which they operate.
       
          ___________________
       [ 5] These conventions are being incorporated into related
       
            documents.
       
                                 Document Expiration: 28 February 1993  13
       
       
       
       
          Generic Security Service API: Internet-Draft: August 1992
          Common Authentication Technology WG: John Linn (DEC)
       
       
          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
       
       
       
          14  Document Expiration: 28 February 1993
       
       
       
       
                 Generic Security Service API: Internet-Draft: August 1992
                      Common Authentication Technology WG: John Linn (DEC)
       
          ________________________________________________________________
       
          Table_1_(Cont.):__GSS-API_Major_Status_Codes____________________
       
          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 re-
                                       quired
       
          GSS_DUPLICATE_TOKEN          duplicate per-message token de-
                                       tected
       
          GSS_OLD_TOKEN                timed-out per-message token de-
                                       tected
       
          GSS_UNSEQ_TOKEN              out-of-order per-message token
          _____________________________detected___________________________
       
          Minor_status provides more detailed status information which may
          include status codes specific to the underlying security mecha-
          nism. 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
       
                                 Document Expiration: 28 February 1993  15
       
       
       
       
          Generic Security Service API: Internet-Draft: August 1992
          Common Authentication Technology WG: John Linn (DEC)
       
       
          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 encap-
          sulate mutual authentication within the GSS-API's context initi-
          ation calls. In the graphic version of this document, Figure 3
          illustrates a GSS-API continuation scenario.
       
       
          For mech_types which require interactions with third-party
          servers in order to establish a security context, GSS-API con-
          text 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 un-
          predictable 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 indi-
          cate the set of per-message protection security services which
          will be available on the context:
       
          o  the integ_avail flag indicates whether per-message integrity
             and data origin authentication services are available
       
          o  the conf_avail flag indicates whether per-message confiden-
             tiality 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.
       
       
          16  Document Expiration: 28 February 1993
       
       
       
       
                 Generic Security Service API: Internet-Draft: August 1992
                      Common Authentication Technology WG: John Linn (DEC)
       
       
          The GSS-API per-message protection service primitives, as the
          category name implies, are oriented to operation at the gran-
          ulatity 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(),  encap-
          sulate the protected data unit. As such, these primitives are
          not oriented to efficient data protection for stream-paradigm
          protocols (e.g., Telnet) if cryptography must be applied on an
          octet-by-octet basis.
       
          1.2.3  Per-Message Replay Detection and Sequencing
       
          Certain underlying mech_types are expected to offer support for
          replay detection and/or sequencing of messages transferred on
          the contexts they support. These optionally-selectable protec-
          tion 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.
       
       
       
       
                                 Document Expiration: 28 February 1993  17
       
       
       
       
          Generic Security Service API: Internet-Draft: August 1992
          Common Authentication Technology WG: John Linn (DEC)
       
       
          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 win-
             dow (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 re-
             ceived message was correct, but that the message was recog-
             nized 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.
       
          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 win-
             dow (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 re-
             ceived message was correct, but that the message was recog-
             nized 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.
       
       
       
       
          18  Document Expiration: 28 February 1993
       
       
       
       
                 Generic Security Service API: Internet-Draft: August 1992
                      Common Authentication Technology WG: John Linn (DEC)
       
       
          4. GSS_UNSEQ_TOKEN indicates that the signature on the received
             message was correct, but that it is earlier in a sequenced
             stream [6] than a message already processed on the context.
       
          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 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
       
          ___________________
        [6] Mechanisms can be architected to provide a stricter form of
            sequencing service, delivering particular messages to recipi-
            ents 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 mes-
            sages, whether in order or not, and provide them (one at a
            time, without intra-GSS-API message buffering) to GSS-API rou-
            tines for validation.  GSS-API facilities provide supportive
            functions, aiding clients to achieve strict message stream in-
            tegrity 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.
       
                                 Document Expiration: 28 February 1993  19
       
       
       
       
          Generic Security Service API: Internet-Draft: August 1992
          Common Authentication Technology WG: John Linn (DEC)
       
       
          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 dy-
          namically against the protection requirements of particular
          messages. A per-message quality-of-protection parameter (anal-
          ogous to quality-of-service, or QOS) selects among different
          QOP options supported by that mechanism. On context establish-
          ment 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.
       
       
       
          20  Document Expiration: 28 February 1993
       
       
       
       
                 Generic Security Service API: Internet-Draft: August 1992
                      Common Authentication Technology WG: John Linn (DEC)
       
       
          ________________________________________________________________
       
          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 creden-
                                       tials
       
          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, encapsu-
                                       late
       
       
                                 Document Expiration: 28 February 1993  21
       
       
       
       
          Generic Security Service API: Internet-Draft: August 1992
          Common Authentication Technology WG: John Linn (DEC)
       
          ________________________________________________________________
       
          Table_2_(Cont.):__GSS-API_Calls_________________________________
       
          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 normal-
                                       ized 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_____
       
       
          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.
       
       
          22  Document Expiration: 28 February 1993
       
       
       
       
                 Generic Security Service API: Internet-Draft: August 1992
                      Common Authentication Technology WG: John Linn (DEC)
       
       
          The GSS_Acquire_cred()  call is defined within the GSS-API in
          support of application portability, with a particular orien-
          tation towards support of portable server applications. It is
          recognized that (for certain systems and mechanisms) creden-
          tials 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 lo-
          cal 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  lifetime_rec INTEGER -in seconds, or reserved value for
             INDEFINITE
       
                                 Document Expiration: 28 February 1993  23
       
       
       
       
          Generic Security Service API: Internet-Draft: August 1992
          Common Authentication Technology WG: John Linn (DEC)
       
       
          Return major_status codes:
       
          o  GSS_COMPLETE indicates that requested credentials were suc-
             cessfully established, for the duration indicated in life-
             time_rec, suitable for the usage requested in cred_usage,
             and for all or a subset of the requested mech_types, 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 cre-
             dential 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 estab-
             lished for the accompanying desired_name.
       
          o  GSS_BAD_NAME indicates that the provided desired_name is in-
             consistent 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.
       
       
          24  Document Expiration: 28 February 1993
       
       
       
       
                 Generic Security Service API: Internet-Draft: August 1992
                      Common Authentication Technology WG: John Linn (DEC)
       
       
          A caller may provide the value NULL for desired_name, signifying
          a request for credentials corresponding to a default princi-
          pal 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 ses-
          sions) when GSS_Acquire_cred()  is called; the means used in
          such cases to select a specific credential are local matters[7].
       
          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 IN-
          DEFINITE 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 argu-
          ment), beginning at the present[8], or can request credentials
          with a default validity interval. Certain mechanisms and im-
          plementations 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.
       
        [7] The input lifetime_req argument to GSS_Acquire_cred() may
            provide useful information for local GSS-API implementations
            to employ in making this disambiguation in a manner which will
       
            best satisfy a caller's intent.
        [8] Requests for postdated credentials are not supported within
       
            the GSS-API.
       
                                 Document Expiration: 28 February 1993  25
       
       
       
       
          Generic Security Service API: Internet-Draft: August 1992
          Common Authentication Technology WG: John Linn (DEC)
       
       
          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.
       
          o  GSS_NO_CRED indicates that no release operation was per-
             formed, either because the input cred_handle was invalid or
             because the caller lacks authorization to access the refer-
             enced 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 cre-
          dentials 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 creden-
          tials, invocation of GSS_Release_cred()  cannot be assumed to
          delete a particular set of credentials on a system-wide basis.
       
          26  Document Expiration: 28 February 1993
       
       
       
       
                 Generic Security Service API: Internet-Draft: August 1992
                      Common Authentication Technology WG: John Linn (DEC)
       
       
          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 INDEF-
             INITE
       
          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.
       
          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 autho-
             rization 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 asso-
          ciated principal name, remaining validity period, usability for
       
                                 Document Expiration: 28 February 1993  27
       
       
       
       
          Generic Security Service API: Internet-Draft: August 1992
          Common Authentication Technology WG: John Linn (DEC)
       
       
          security context initiation and/or acceptance, and supported
          mechanisms.
       
       
          2.2  Context-level calls
       
          This group of calls is devoted to the establishment and manage-
          ment of security contexts between peers. A context's initiator
          calls GSS_Init_sec_context(),  resulting in generation of a to-
          ken 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 establish-
          ment; 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,
       
          o  mutual_req_flag BOOLEAN,
       
          28  Document Expiration: 28 February 1993
       
       
       
       
                 Generic Security Service API: Internet-Draft: August 1992
                      Common Authentication Technology WG: John Linn (DEC)
       
       
          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 indi-
             cated, 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.
       
                                 Document Expiration: 28 February 1993  29
       
       
       
       
          Generic Security Service API: Internet-Draft: August 1992
          Common Authentication Technology WG: John Linn (DEC)
       
       
          Return major_status codes:
       
          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 per-
             formed on the input_token failed, preventing further process-
             ing 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 con-
             tains an incorrect signature, so context setup cannot be
             accomplished.
       
          o  GSS_NO_CRED indicates that no context was established, ei-
             ther 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 pro-
             vided 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
       
          30  Document Expiration: 28 February 1993
       
       
       
       
                 Generic Security Service API: Internet-Draft: August 1992
                      Common Authentication Technology WG: John Linn (DEC)
       
       
             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.
       
          o  GSS_BAD_NAME indicates that the provided targ_name is incon-
             sistent in terms of internally-incorporated type specifier
             information, so context establishment cannot be accomplished.
       
          o  GSS_FAILURE indicates that context setup could not be ac-
             complished 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 creden-
          tials structure referenced by claimant_cred_handle, GSS_Init_
          sec_context()  initializes the data structures required to es-
          tablish a security context with target targ_name. The claimant_
          cred_handle must correspond to the same valid credentials struc-
          ture on the initial call to GSS_Init_sec_context()  and on any
          successor calls resulting from GSS_CONTINUE_NEEDED status re-
          turns; 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 as-
          signed", 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
       
                                 Document Expiration: 28 February 1993  31
       
       
       
       
          Generic Security Service API: Internet-Draft: August 1992
          Common Authentication Technology WG: John Linn (DEC)
       
       
          GSS_Init_sec_context()  are needed to perform context establish-
          ment, 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 the first application-provided input mes-
          sage 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 authenti-
          cation, 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.)
       
       
       
       
          32  Document Expiration: 28 February 1993
       
       
       
       
                 Generic Security Service API: Internet-Draft: August 1992
                      Common Authentication Technology WG: John Linn (DEC)
       
       
          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 capabil-
          ities 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 indi-
          cates 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 sup-
          ports 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 fash-
          ion, 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 INDEFI-
          NITE lifetime_req. The values of conf_avail, integ_avail, and
          lifetime_rec are undefined unless the routine's major_status
          indicates COMPLETE.
       
       
       
       
                                 Document Expiration: 28 February 1993  33
       
       
       
       
          Generic Security Service API: Internet-Draft: August 1992
          Common Authentication Technology WG: John Linn (DEC)
       
       
          If the mutual_state is TRUE, this fact will be reflected within
          the output_token. A call to GSS_Accept_sec_context()  at the
          target in conjunction with such a context will return a to-
          ken, 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 de-
             fault"
       
          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
       
          34  Document Expiration: 28 February 1993
       
       
       
       
                 Generic Security Service API: Internet-Draft: August 1992
                      Common Authentication Technology WG: John Linn (DEC)
       
       
          o  delegated_cred_handle OCTET STRING,
       
          o  output_token OCTET STRING -NULL or token to pass to context
             initiator
       
          This call may block pending network interactions for those
          mech_types in which a directory service or other network entity
          must be consulted on behalf of a context acceptor in order to
          validate a received input_token.
       
          Return major_status codes:
       
          o  GSS_COMPLETE indicates that context-level data structures
             were successfully initialized, and that per-message process-
             ing 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 per-
             formed on the input_token failed, preventing further process-
             ing 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 con-
             tains 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.
       
                                 Document Expiration: 28 February 1993  35
       
       
       
       
          Generic Security Service API: Internet-Draft: August 1992
          Common Authentication Technology WG: John Linn (DEC)
       
       
          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, ei-
             ther because the input cred_handle was invalid, because the
             referenced credentials are valid for context initiator use
             only, or because the caller lacks authorization to access the
             referenced credentials.
       
          o  GSS_CREDENTIALS_EXPIRED indicates that the credentials pro-
             vided 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 ac-
             complished 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 tar-
          get. Using information in the credentials structure referenced
          by the input acceptor_cred_handle, it verifies the incoming in-
          put_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
       
          36  Document Expiration: 28 February 1993
       
       
       
       
                 Generic Security Service API: Internet-Draft: August 1992
                      Common Authentication Technology WG: John Linn (DEC)
       
       
          to credentials at different points in the context establishment
          sequence.
       
          The input_context_handle argument is 0, specifying "not yet as-
          signed", 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 es-
          tablishment, 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.
       
          The conf_avail return value indicates whether the context sup-
          ports 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 fash-
          ion, 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.
       
       
       
                                 Document Expiration: 28 February 1993  37
       
       
       
       
          Generic Security Service API: Internet-Draft: August 1992
          Common Authentication Technology WG: John Linn (DEC)
       
       
          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 in-
          put_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 applica-
          tion 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:
       
          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.
       
          38  Document Expiration: 28 February 1993
       
       
       
       
                 Generic Security Service API: Internet-Draft: August 1992
                      Common Authentication Technology WG: John Linn (DEC)
       
       
          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 in-
          forming 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.) At-
          tempts 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 suc-
             cessfully processed in conjunction with the context refer-
             enced by context_handle.
       
          o  GSS_DEFECTIVE_TOKEN indicates that consistency checks per-
             formed on the received context_token failed, preventing
             further processing from being performed with that token.
       
                                 Document Expiration: 28 February 1993  39
       
       
       
       
          Generic Security Service API: Internet-Draft: August 1992
          Common Authentication Technology WG: John Linn (DEC)
       
       
          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.
       
          40  Document Expiration: 28 February 1993
       
       
       
       
                 Generic Security Service API: Internet-Draft: August 1992
                      Common Authentication Technology WG: John Linn (DEC)
       
       
          o  GSS_CREDENTIALS_EXPIRED indicates that the context is recog-
             nized, but that its associated credentials have expired.
       
          o  GSS_NO_CONTEXT indicates that no valid context was recognized
             for the input context_handle provided.
       
          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 confiden-
          tiality 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()
       
                                 Document Expiration: 28 February 1993  41
       
       
       
       
          Generic Security Service API: Internet-Draft: August 1992
          Common Authentication Technology WG: John Linn (DEC)
       
       
          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,
       
          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 recog-
             nized, 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.
       
          42  Document Expiration: 28 February 1993
       
       
       
       
                 Generic Security Service API: Internet-Draft: August 1992
                      Common Authentication Technology WG: John Linn (DEC)
       
       
          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
       
          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 per-
             formed 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 con-
             tains an incorrect signature for the message.
       
                                 Document Expiration: 28 February 1993  43
       
       
       
       
          Generic Security Service API: Internet-Draft: August 1992
          Common Authentication Technology WG: John Linn (DEC)
       
       
          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 recog-
             nized, 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.
       
          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,
       
          44  Document Expiration: 28 February 1993
       
       
       
       
                 Generic Security Service API: Internet-Draft: August 1992
                      Common Authentication Technology WG: John Linn (DEC)
       
       
          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 success-
             fully 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 recog-
             nized, 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.
       
          In all cases, the GSS_Seal()  call yields a single output_
          message data element containing (optionally enciphered) user
          data as well as control information.
       
                                 Document Expiration: 28 February 1993  45
       
       
       
       
          Generic Security Service API: Internet-Draft: August 1992
          Common Authentication Technology WG: John Linn (DEC)
       
       
          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 success-
             fully processed and that the resulting output_message is
             available.
       
          o  GSS_DEFECTIVE_TOKEN indicates that consistency checks per-
             formed 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 de-
             tected 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 recog-
             nized, but that its associated credentials have expired, so
             that the requested operation cannot be performed.
       
          46  Document Expiration: 28 February 1993
       
       
       
       
                 Generic Security Service API: Internet-Draft: August 1992
                      Common Authentication Technology WG: John Linn (DEC)
       
       
          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 ori-
          gin 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,
       
                                 Document Expiration: 28 February 1993  47
       
       
       
       
          Generic Security Service API: Internet-Draft: August 1992
          Common Authentication Technology WG: John Linn (DEC)
       
       
          o  status_string_set SET OF OCTET STRING
       
          Return major_status codes:
       
          o  GSS_COMPLETE indicates that a valid printable status repre-
             sentation (possibly representing more than one status event
             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.
       
          48  Document Expiration: 28 February 1993
       
       
       
       
                 Generic Security Service API: Internet-Draft: August 1992
                      Common Authentication Technology WG: John Linn (DEC)
       
       
          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 avail-
          able on the local system. This call is intended for support of
          specialized callers who need to request non-default mech_type
          sets from GSS_Acquire_cred(),  and should not be needed by other
          callers.
       
          2.4.3  GSS_Compare_name call
       
          Inputs:
       
          o  name1 INTERNAL NAME,
       
          o  name2 INTERNAL NAME,
       
          o  name2_type OBJECT IDENTIFIER
       
          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.
       
                                 Document Expiration: 28 February 1993  49
       
       
       
       
          Generic Security Service API: Internet-Draft: August 1992
          Common Authentication Technology WG: John Linn (DEC)
       
       
          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,
       
          o  name_type OBJECT IDENTIFIER
       
          Return major_status codes:
       
          o  GSS_COMPLETE indicates that a valid printable name represen-
             tation 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 implementa-
             tion, 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.
       
          50  Document Expiration: 28 February 1993
       
       
       
       
                 Generic Security Service API: Internet-Draft: August 1992
                      Common Authentication Technology WG: John Linn (DEC)
       
       
          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 unsup-
             ported by the GSS-API implementation, so the import operation
             could not be completed.
       
          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.
       
                                 Document Expiration: 28 February 1993  51
       
       
       
       
          Generic Security Service API: Internet-Draft: August 1992
          Common Authentication Technology WG: John Linn (DEC)
       
       
          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 inter-
          nal name representation.
       
          2.4.7  GSS_Release_buffer call
       
          Inputs:
       
          o  buffer OCTET STRING
       
          Outputs:
       
          o  major_status INTEGER,
       
          o  minor_status INTEGER
       
          Return major_status codes:
       
          o  GSS_COMPLETE indicates that the storage associated with the
             input buffer was successfully released.
       
          52  Document Expiration: 28 February 1993
       
       
       
       
                 Generic Security Service API: Internet-Draft: August 1992
                      Common Authentication Technology WG: John Linn (DEC)
       
       
          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 var-
          ious 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 underly-
          ing 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.
       
                                 Document Expiration: 28 February 1993  53
       
       
       
       
          Generic Security Service API: Internet-Draft: August 1992
          Common Authentication Technology WG: John Linn (DEC)
       
       
          3.1  Kerberos V5, single-TGT
       
          OS-specific login functions yield a TGT to the local realm Ker-
          beros 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 estab-
          lishing 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 conjunc-
          tion 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 argu-
          ment to GSS_Accept_sec_context(),  which verifies the authen-
          ticator, 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 ser-
          vice ticket, and can use this key in subsequent GSS_Sign(),
          GSS_Verify(),  GSS_Seal(), and GSS_Unseal() operations.
       
       
       
       
       
       
       
       
          54  Document Expiration: 28 February 1993
       
       
       
       
                 Generic Security Service API: Internet-Draft: August 1992
                      Common Authentication Technology WG: John Linn (DEC)
       
       
          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 appro-
          priate 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[9], 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.
       
          The service passes the received token as the input_token ar-
          gument 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
       
          ___________________
        [9] This scenario illustrates a different use for the GSS_
            CONTINUE_NEEDED status return facility than for support of
            mutual authentication; note that both uses can coexist as
            successive operations within a single context establishment
       
            operation.
       
                                 Document Expiration: 28 February 1993  55
       
       
       
       
          Generic Security Service API: Internet-Draft: August 1992
          Common Authentication Technology WG: John Linn (DEC)
       
       
          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 struc-
          ture, 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
          signed with the client's private key, is included in the out-
          put_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
       
          56  Document Expiration: 28 February 1993
       
       
       
       
                 Generic Security Service API: Internet-Draft: August 1992
                      Common Authentication Technology WG: John Linn (DEC)
       
       
          defer this path resolution to be performed by the service in-
          stead 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 ar-
          gument 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 en-
          ciphered secret key provided to it for per-message protection
          operations on the context.
       
          The client calls GSS_Sign()  or GSS_Seal() on a data mes-
          sage, 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:
       
          o  object identifiers must be assigned to candidate GSS-API
             mechanisms and the name types which they support
       
          o  concrete data element formats must be defined for candidate
             mechanisms (encapsulation within the mechanism-independent
             token format definition in Appendix B of this document is
             recommended to mechanism designers)
       
          Calling applications must implement formatting conventions which
          will enable them to distinguish GSS-API tokens from other data
          carried in their application protocols.
       
                                 Document Expiration: 28 February 1993  57
       
       
       
       
          Generic Security Service API: Internet-Draft: August 1992
          Common Authentication Technology WG: John Linn (DEC)
       
       
          Concrete language bindings are required for the programming en-
          vironments in which the GSS-API is to be employed; such bindings
          for the C language are available in an associated Internet-
          Draft.
       
       
          5  Acknowledgments
       
          This proposal is the result of a collaborative effort. Acknowl-
          edgments 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 Ala-
          gappan, 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.
       
       
       
       
       
       
       
       
       
       
       
       
       
       
       
       
          58  Document Expiration: 28 February 1993
       
       
       
       
       
       
       
       
       
       
       
       
                                     APPENDIX  A
       
       
                           PACS AND AUTHORIZATION SERVICES
       
       
          Consideration has been given to modifying the GSS-API service
          interface to recognize and manipulate Privilege Attribute Cer-
          tificates (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.
       
                                       PACs and Authorization Services  59
       
       
       
       
          Generic Security Service API: Internet-Draft: August 1992
          Common Authentication Technology WG: John Linn (DEC)
       
       
          In a distributed computing environment, authentication must
          span different systems; the need for such authentication pro-
          vides motivation for GSS-API definition and usage. Heterogeneous
          systems in a network can intercommunicate, with globally au-
          thenticated names comprising the common bond between locally
          defined access control policies. Access control policies to
          which authentication provides inputs are often local, or spe-
          cific 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 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.
       
       
       
       
       
       
       
       
       
       
       
       
          60  PACs and Authorization Services
       
       
       
       
       
       
       
       
       
       
       
       
                                     APPENDIX  B
       
       
                         MECHANISM-INDEPENDENT TOKEN FORMAT
       
       
          This appendix specifies a mechanism-independent level of en-
          capsulating 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 Dis-
          tinguished Encoding Rule (DER) BER subset defined in X.509,
          clause 8.7) is recommended to the designers of GSS-API imple-
          mentations based on various mechanisms, so that tokens can be
          interpreted unambiguously at GSS-API peers. There is no require-
          ment that the mechanism-specific innerContextToken, innerMs-
          gToken, 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
       
                                    Mechanism-Independent Token Format  61
       
       
       
       
          Generic Security Service API: Internet-Draft: August 1992
          Common Authentication Technology WG: John Linn (DEC)
       
       
               InitialContextToken ::=
               -- option indication (delegation, etc.) indicated within
               -- mechanism-specific token
               [APPLICATION 0] IMPLICIT SEQUENCE {
                       thisMech MechType,
                       innerContextToken ANY DEFINED BY thisMech
                          -- 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
       
       
       
       
       
       
       
       
       
       
       
       
       
       
       
       
          62  Mechanism-Independent Token Format
       

Html markup produced by rfcmarkup 1.108, available from http://tools.ietf.org/tools/rfcmarkup/