As per Relevance of the word indicate, we have this rfc below:
Network Working Group J.
Request for Comments: 2078 OpenVision
Category: Standards Track January 1997
Obsoletes: 1508
Generic Security Service Application Program Interface, Version 2
Status of this
This document specifies an Internet standards track protocol for
Internet community, and requests discussion and suggestions
improvements. Please refer to the current edition of the "
Official Protocol Standards" (STD 1) for the standardization
and status of this protocol. Distribution of this memo is unlimited
The Generic Security Service Application Program Interface (GSS-API),
as defined in RFC-1508, provides security services to callers in
generic fashion, supportable with a range of underlying
and technologies and hence allowing source-level portability
applications to different environments. This specification
GSS-API services and primitives at a level independent of
mechanism and programming language environment, and is to
complemented by other, related specifications
documents defining specific parameter bindings for
language
documents defining token formats, protocols, and procedures to
implemented in order to realize GSS-API services atop
security
This memo revises RFC-1508, making specific, incremental changes
response to implementation experience and liaison requests. It
intended, therefore, that this memo or a successor version
will become the basis for subsequent progression of the GSS-
specification on the standards track
Table of
1: GSS-API Characteristics and Concepts.......................... 3
1.1: GSS-API Constructs.......................................... 6
1.1.1: Credentials.............................................. 6
1.1.1.1: Credential Constructs and Concepts...................... 6
1.1.1.2: Credential Management................................... 7
1.1.1.3: Default Credential Resolution........................... 8
Linn Standards Track [Page 1]
RFC 2078 GSS-API January 1997
1.1.2: Tokens.................................................... 9
1.1.3: Security Contexts........................................ 10
1.1.4: Mechanism Types.......................................... 11
1.1.5: Naming................................................... 12
1.1.6: Channel Bindings......................................... 14
1.2: GSS-API Features and Issues................................ 15
1.2.1: Status Reporting......................................... 15
1.2.2: Per-Message Security Service Availability................. 17
1.2.3: Per-Message Replay Detection and Sequencing............... 18
1.2.4: Quality of Protection.................................... 20
1.2.5: Anonymity Support......................................... 21
1.2.6: Initialization............................................ 22
1.2.7: Per-Message Protection During Context Establishment....... 22
1.2.8: Implementation Robustness................................. 23
2: Interface Descriptions....................................... 23
2.1: Credential management calls................................ 25
2.1.1: GSS_Acquire_cred call.................................... 26
2.1.2: GSS_Release_cred call.................................... 28
2.1.3: GSS_Inquire_cred call.................................... 29
2.1.4: GSS_Add_cred call........................................ 31
2.1.5: GSS_Inquire_cred_by_mech call............................ 33
2.2: Context-level calls........................................ 34
2.2.1: GSS_Init_sec_context call................................ 34
2.2.2: GSS_Accept_sec_context call.............................. 40
2.2.3: GSS_Delete_sec_context call.............................. 44
2.2.4: GSS_Process_context_token call........................... 46
2.2.5: GSS_Context_time call.................................... 47
2.2.6: GSS_Inquire_context call................................. 47
2.2.7: GSS_Wrap_size_limit call................................. 49
2.2.8: GSS_Export_sec_context call.............................. 50
2.2.9: GSS_Import_sec_context call.............................. 52
2.3: Per-message calls.......................................... 53
2.3.1: GSS_GetMIC call.......................................... 54
2.3.2: GSS_VerifyMIC call....................................... 55
2.3.3: GSS_Wrap call............................................ 56
2.3.4: GSS_Unwrap call.......................................... 58
2.4: Support calls.............................................. 59
2.4.1: GSS_Display_status call.................................. 60
2.4.2: GSS_Indicate_mechs call.................................. 60
2.4.3: GSS_Compare_name call.................................... 61
2.4.4: GSS_Display_name call.................................... 62
2.4.5: GSS_Import_name call..................................... 63
2.4.6: GSS_Release_name call.................................... 64
2.4.7: GSS_Release_buffer call.................................. 65
2.4.8: GSS_Release_OID_set call................................. 65
2.4.9: GSS_Create_empty_OID_set call............................ 66
2.4.10: GSS_Add_OID_set_member call.............................. 67
2.4.11: GSS_Test_OID_set_member call............................. 67
Linn Standards Track [Page 2]
RFC 2078 GSS-API January 1997
2.4.12: GSS_Release_OID call..................................... 68
2.4.13: GSS_OID_to_str call...................................... 68
2.4.14: GSS_Str_to_OID call...................................... 69
2.4.15: GSS_Inquire_names_for_mech call.......................... 69
2.4.16: GSS_Inquire_mechs_for_name call.......................... 70
2.4.17: GSS_Canonicalize_name call............................... 71
2.4.18: GSS_Export_name call..................................... 72
2.4.19: GSS_Duplicate_name call.................................. 73
3: Data Structure Definitions for GSS-V2 Usage................... 73
3.1: Mechanism-Independent Token Format.......................... 74
3.2: Mechanism-Independent Exported Name Object Format........... 77
4: Name Type Definitions......................................... 77
4.1: Host-Based Service Name Form................................ 77
4.2: User Name Form.............................................. 78
4.3: Machine UID Form............................................ 78
4.4: String UID Form............................................. 79
5: Mechanism-Specific Example Scenarios......................... 79
5.1: Kerberos V5, single-TGT..................................... 79
5.2: Kerberos V5, double-TGT..................................... 80
5.3: X.509 Authentication Framework............................. 81
6: Security Considerations...................................... 82
7: Related Activities........................................... 82
Appendix A: Mechanism Design Constraints......................... 83
Appendix B: Compatibility with GSS-V1............................ 83
1: GSS-API Characteristics and
GSS-API operates in the following paradigm. A typical GSS-API
is itself a communications protocol, calling on GSS-API in order
protect its communications with authentication, integrity, and/
confidentiality security services. A GSS-API caller accepts
provided to it by its local GSS-API implementation and transfers
tokens to a peer on a remote system; that peer passes the
tokens to its local GSS-API implementation for processing.
security services available through GSS-API in this fashion
implementable (and have been implemented) over a range of
mechanisms based on secret-key and public-key
technologies
The GSS-API separates the operations of initializing a
context between peers, achieving peer entity authentication (
security service definition, and other definitions used in
document, corresponds to that provided in International Standard
7498-2-1988(E), Security Architecture.) (GSS_Init_sec_context()
GSS_Accept_sec_context() calls), from the operations of
per-message data origin authentication and data integrity
(GSS_GetMIC() and GSS_VerifyMIC() calls) for messages
transferred in conjunction with that context. When establishing
Linn Standards Track [Page 3]
RFC 2078 GSS-API January 1997
security context, the GSS-API enables a context initiator
optionally permit its credentials to be delegated, meaning that
context acceptor may initiate further security contexts on behalf
the initiating caller. Per-message GSS_Wrap() and GSS_Unwrap()
provide the data origin authentication and data integrity
which GSS_GetMIC() and GSS_VerifyMIC() offer, and also
selection of confidentiality services as a caller option.
calls provide supportive functions to the GSS-API's users
The following paragraphs provide an example illustrating
dataflows involved in use of the GSS-API by a client and server in
mechanism-independent fashion, establishing a security context
transferring a protected message. The example assumes that
acquisition has already been completed. The example assumes that
underlying authentication technology is capable of authenticating
client to a server using elements carried within a single token,
of authenticating the server to the client (mutual authentication
with a single returned token; this assumption holds for presently
documented CAT mechanisms but is not necessarily true for
cryptographic technologies and associated protocols
The client calls GSS_Init_sec_context() to establish a
context to the server identified by targ_name, and elects to set
mutual_req_flag so that mutual authentication is performed in
course of context establishment. GSS_Init_sec_context() returns
output_token to be passed to the server, and
GSS_S_CONTINUE_NEEDED status pending completion of the
authentication sequence. Had mutual_req_flag not been set,
initial call to GSS_Init_sec_context() would have
GSS_S_COMPLETE status. The client sends the output_token to
server
The server passes the received token as the input_token parameter
GSS_Accept_sec_context(). GSS_Accept_sec_context
GSS_S_COMPLETE status, provides the client's authenticated
in the src_name result, and provides an output_token to be passed
the client. The server sends the output_token to the client
The client passes the received token as the input_token parameter
a successor call to GSS_Init_sec_context(), which processes
included in the token in order to achieve mutual authentication
the client's viewpoint. This call to GSS_Init_sec_context()
GSS_S_COMPLETE status, indicating successful mutual
and the completion of context establishment for this example
The client generates a data message and passes it to GSS_Wrap().
GSS_Wrap() performs data origin authentication, data integrity,
(optionally) confidentiality processing on the message
Linn Standards Track [Page 4]
RFC 2078 GSS-API January 1997
encapsulates the result into output_message,
GSS_S_COMPLETE status. The client sends the output_message to
server
The server passes the received message to GSS_Unwrap(). GSS_Unwrap()
inverts the encapsulation performed by GSS_Wrap(), deciphers
message if the optional confidentiality feature was applied,
validates the data origin authentication and data integrity
quantities. GSS_Unwrap() indicates successful validation
returning GSS_S_COMPLETE status along with the
output_message
For purposes of this example, we assume that the server knows
out-of-band means that this context will have no further use
one protected message is transferred from client to server.
this premise, the server now calls GSS_Delete_sec_context() to
context-level information. Optionally, the server-side
may provide a token buffer to GSS_Delete_sec_context(), to receive
context_token to be transferred to the client in order to
that client-side context-level information be deleted
If a context_token is transferred, the client passes
context_token to GSS_Process_context_token(), which
GSS_S_COMPLETE status after deleting context-level information at
client system
The GSS-API design assumes and addresses several basic goals
including
Mechanism independence: The GSS-API defines an interface
cryptographically implemented strong authentication and
security services at a generic level which is independent
particular underlying mechanisms. For example, GSS-API-
services can be implemented by secret-key technologies (e.g.,
Kerberos) or public-key approaches (e.g., X.509).
Protocol environment independence: The GSS-API is independent
the communications protocol suites with which it is employed
permitting use in a broad range of protocol environments.
appropriate environments, an intermediate implementation "veneer
which is oriented to a particular communication protocol (e.g.,
Remote Procedure Call (RPC)) may be interposed
applications which call that protocol and the GSS-API,
invoking GSS-API facilities in conjunction with that protocol'
communications invocations
Protocol association independence: The GSS-API's security
construct is independent of communications protocol
Linn Standards Track [Page 5]
RFC 2078 GSS-API January 1997
constructs. This characteristic allows a single GSS-
implementation to be utilized by a variety of invoking
modules on behalf of those modules' calling applications. GSS-
services can also be invoked directly by applications,
independent of protocol associations
Suitability to a range of implementation placements: GSS-
clients are not constrained to reside within any Trusted
Base (TCB) perimeter defined on a system where the GSS-API
implemented; security services are specified in a manner
to both intra-TCB and extra-TCB callers
1.1: GSS-API
This section describes the basic elements comprising the GSS-API
1.1.1:
1.1.1.1: Credential Constructs and
Credentials provide the prerequisites which permit GSS-API peers
establish security contexts with each other. A caller may
that the credential elements which are to be applied for
initiation or acceptance be selected by default. Alternately,
GSS-API callers which need to make explicit selection of
credentials structures may make references to those
through GSS-API-provided credential handles ("cred_handles"). In
cases, callers' credential references are indirect, mediated by GSS
API implementations and not requiring callers to access the
credential elements
A single credential structure may be used to initiate
contexts and to accept inbound contexts. Callers needing to
in only one of these modes may designate this fact when
are acquired for use, allowing underlying mechanisms to
their processing and storage requirements. The credential
defined by a particular mechanism may contain multiple
keys, e.g., to enable authentication and message encryption to
performed with different algorithms
A GSS-API credential structure may contain multiple
elements, each containing mechanism-specific information for
particular underlying mechanism (mech_type), but the set of
within a given credential structure represent a common entity.
credential structure's contents will vary depending on the set
mech_types supported by a particular GSS-API implementation.
credential element identifies the data needed by its mechanism
order to establish contexts on behalf of a particular principal,
Linn Standards Track [Page 6]
RFC 2078 GSS-API January 1997
may contain separate credential references for use in
initiation and context acceptance. Multiple credential
within a given credential having overlapping combinations
mechanism, usage mode, and validity period are not permitted
Commonly, a single mech_type will be used for all security
established by a particular initiator to a particular target. A
motivation for supporting credential sets representing
mech_types is to allow initiators on systems which are equipped
handle multiple types to initiate contexts to targets on
systems which can accommodate only a subset of the set supported
the initiator's system
1.1.1.2: Credential
It is the responsibility of underlying system-specific mechanisms
OS functions below the GSS-API to ensure that the ability to
and use credentials associated with a given identity is
to appropriate processes within a system. This responsibility
be taken seriously by implementors, as the ability for an entity
utilize a principal's credentials is equivalent to the entity'
ability to successfully assert that principal's identity
Once a set of GSS-API credentials is established, the
of that credentials set to other processes or analogous
within a system is a local matter, not defined by the GSS-API.
example local policy would be one in which any credentials
as a result of login to a given user account, or of delegation
rights to that account, are accessible by, or transferable to
processes running under that account
The credential establishment process (particularly when performed
behalf of users rather than server processes) is likely to
access to passwords or other quantities which should be
locally and exposed for the shortest time possible. As a result,
will often be appropriate for preliminary credential establishment
be performed through local means at user login time, with
result(s) cached for subsequent reference. These
credentials would be set aside (in a system-specific fashion)
subsequent use, either
to be accessed by an invocation of the GSS-API GSS_Acquire_cred()
call, returning an explicit handle to reference that
to comprise default credential elements to be installed, and to
used when default credential behavior is requested on behalf of
Linn Standards Track [Page 7]
RFC 2078 GSS-API January 1997
1.1.1.3: Default Credential
The gss_init_sec_context and gss_accept_sec_context routines
the value GSS_C_NO_CREDENTIAL to be specified as their
handle parameter. This special credential-handle indicates a
by the application to act as a default principal. While
GSS-API implementations are free to determine such default
as appropriate to the mechanism, the following default behavior
these routines is recommended for portability
GSS_Init_sec_context
(i) If there is only a single principal capable of
security contexts that the application is authorized to act
behalf of, then that principal shall be used,
(ii) If the platform maintains a concept of a default network
identity, and if the application is authorized to act on behalf
that identity for the purpose of initiating security contexts
then the principal corresponding to that identity shall be used
(iii) If the platform maintains a concept of a default
identity, and provides a means to map local identities
network-identities, and if the application is authorized to act
behalf of the network-identity image of the default local
for the purpose of initiating security contexts, then
principal corresponding to that identity shall be used,
(iv) A user-configurable default identity should be used
GSS_Accept_sec_context
(i) If there is only a single authorized principal
capable of accepting security contexts, then that principal
be used,
(ii) If the mechanism can determine the identity of the
principal by examining the context-establishment token, and if
accepting application is authorized to act as that principal
the purpose of accepting security contexts, then that
identity shall be used,
(iii) If the mechanism supports context acceptance by
principal, and mutual authentication was not requested,
principal that the application is authorized to accept
contexts under may be used,
Linn Standards Track [Page 8]
RFC 2078 GSS-API January 1997
(iv) A user-configurable default identity shall be used
The purpose of the above rules is to allow security contexts to
established by both initiator and acceptor using the default
wherever possible. Applications requesting default behavior
likely to be more portable across mechanisms and platforms than
that use GSS_Acquire_cred to request a specific identity
1.1.2:
Tokens are data elements transferred between GSS-API callers, and
divided into two classes. Context-level tokens are exchanged in
to establish and manage a security context between peers. Per-
tokens relate to an established context and are exchanged to
protective security services (i.e., data origin authentication
integrity, and optional confidentiality) for corresponding
messages
The first context-level token obtained from GSS_Init_sec_context()
required to indicate at its very beginning a globally-
mechanism identifier, i.e., an Object Identifier (OID) of
security mechanism. The remaining part of this token as well as
whole content of all other tokens are specific to the
underlying mechanism used to support the GSS-API. Section 3 of
document provides, for designers of GSS-API support mechanisms,
description of the header of the first context-level token which
then followed by mechanism-specific information
Tokens' contents are opaque from the viewpoint of GSS-API callers
They are generated within the GSS-API implementation at an
system, provided to a GSS-API caller to be transferred to the
GSS-API caller at a remote end system, and processed by the GSS-
implementation at that remote end system. Tokens may be output
GSS-API calls (and should be transferred to GSS-API peers) whether
not the calls' status indicators indicate successful completion
Token transfer may take place in an in-band manner, integrated
the same protocol stream used by the GSS-API callers for other
transfers, or in an out-of-band manner across a logically
channel
Different GSS-API tokens are used for different purposes (e.g.,
context initiation, context acceptance, protected message data on
established context), and it is the responsibility of a GSS-
caller receiving tokens to distinguish their types, associate
with corresponding security contexts, and pass them to
GSS-API processing routines. Depending on the caller
environment, this distinction may be accomplished in several ways
Linn Standards Track [Page 9]
RFC 2078 GSS-API January 1997
The following examples illustrate means through which tokens'
may be distinguished
- implicit tagging based on state information (e.g., all tokens
a new association are considered to be context
tokens until context establishment is completed, at which
all tokens are considered to be wrapped data objects for
context),
- explicit tagging at the caller protocol level
- a hybrid of these approaches
Commonly, the encapsulated data within a token includes
mechanism-specific tagging information, enabling mechanism-
processing modules to distinguish tokens used within the
for different purposes. Such internal mechanism-level tagging
recommended to mechanism designers, and enables mechanisms
determine whether a caller has passed a particular token
processing by an inappropriate GSS-API routine
Development of GSS-API support primitives based on a
underlying cryptographic technique and protocol (i.e., conformant
a specific GSS-API mechanism definition) does not necessarily
that GSS-API callers using that GSS-API mechanism will be able
interoperate with peers invoking the same technique and
outside the GSS-API paradigm, or with peers implementing a
GSS-API mechanism based on the same underlying technology.
format of GSS-API tokens defined in conjunction with a
mechanism, and the techniques used to integrate those tokens
callers' protocols, may not be interoperable with the tokens used
non-GSS-API callers of the same underlying technique
1.1.3: Security
Security contexts are established between peers, using
established locally in conjunction with each peer or received
peers via delegation. Multiple contexts may exist
between a pair of peers, using the same or different sets
credentials. Coexistence of multiple contexts using
credentials allows graceful rollover when credentials expire
Distinction among multiple contexts based on the same
serves applications by distinguishing different message streams in
security sense
The GSS-API is independent of underlying protocols and
structure, and depends on its callers to transport GSS-API-
data elements. As a result of these factors, it is a
Linn Standards Track [Page 10]
RFC 2078 GSS-API January 1997
responsibility to parse communicated messages, separating GSS-API
related data elements from caller-provided data. The GSS-API
independent of connection vs. connectionless orientation of
underlying communications service
No correlation between security context and communications
association is dictated. (The optional channel binding facility
discussed in Section 1.1.6 of this document, represents
intentional exception to this rule, supporting additional
features within GSS-API supporting mechanisms.) This
allows the GSS-API to be used in a wide range of
environments, and also simplifies the calling sequences of
individual calls. In many cases (depending on underlying
protocol, associated mechanism, and availability of
information), the state information required for context setup can
sent concurrently with initial signed user data, without
additional message exchanges
1.1.4: Mechanism
In order to successfully establish a security context with a
peer, it is necessary to identify an appropriate underlying
type (mech_type) which both initiator and target peers support.
definition of a mechanism embodies not only the use of a
cryptographic technology (or a hybrid or choice among
cryptographic technologies), but also definition of the syntax
semantics of data element exchanges which that mechanism will
in order to support security services
It is recommended that callers initiating contexts specify
"default" mech_type value, allowing system-specific functions
or invoked by the GSS-API implementation to select the
mech_type, but callers may direct that a particular mech_type
employed when necessary
The means for identifying a shared mech_type to establish a
context with a peer will vary in different environments
circumstances; examples include (but are not limited to):
use of a fixed mech_type, defined by configuration, within
syntactic convention on a target-specific basis,
examination of a target's
lookup of a target's name in a naming service or other database
order to identify mech_types supported by that
Linn Standards Track [Page 11]
RFC 2078 GSS-API January 1997
explicit negotiation between GSS-API callers in advance
security context
When transferred between GSS-API peers, mech_type specifiers (
Section 3, represented as Object Identifiers (OIDs)) serve to
the interpretation of associated tokens. (The structure and
of Object Identifiers is defined in ISO/IEC 8824, "Specification
Abstract Syntax Notation One (ASN.1)" and in ISO/IEC 8825,
"Specification of Basic Encoding Rules for Abstract Syntax
One (ASN.1)".) Use of hierarchically structured OIDs serves
preclude ambiguous interpretation of mech_type specifiers. The
representing the DASS MechType, for example, is 1.3.12.2.1011.7.5,
and that of the Kerberos V5 mechanism, once advanced to the level
Proposed Standard, will be 1.2.840.113554.1.2.2.
1.1.5:
The GSS-API avoids prescribing naming structures, treating the
which are transferred across the interface in order to initiate
accept security contexts as opaque objects. This approach
the GSS-API's goal of implementability atop a range of
security mechanisms, recognizing the fact that different
process and authenticate names which are presented in
forms. Generalized services offering translation functions
arbitrary sets of naming environments are outside the scope of
GSS-API; availability and use of local conversion functions
translate among the naming formats supported within a given
system is anticipated
Different classes of name representations are used in
with different GSS-API parameters
- Internal form (denoted in this document by INTERNAL NAME),
opaque to callers and defined by individual GSS-
implementations. GSS-API implementations supporting
namespace types must maintain internal tags to disambiguate
interpretation of particular names. A Mechanism Name (MN) is
special case of INTERNAL NAME, guaranteed to contain
corresponding to one and only one mechanism; calls which
guaranteed to emit MNs or which require MNs as input are
identified within this specification
- Contiguous string ("flat") form (denoted in this document
OCTET STRING); accompanied by OID tags identifying the
to which they correspond. Depending on tag value, flat names
or may not be printable strings for direct acceptance from
presentation to users. Tagging of flat names allows GSS-
callers and underlying GSS-API mechanisms to disambiguate
Linn Standards Track [Page 12]
RFC 2078 GSS-API January 1997
types and to determine whether an associated name's type is
which they are capable of processing, avoiding aliasing
which could result from misinterpreting a name of one type as
name of another type
- The GSS-API Exported Name Object, a special case of flat
designated by a reserved OID value, carries a canonicalized
of a name suitable for binary comparisons
In addition to providing means for names to be tagged with types
this specification defines primitives to support a level of
environment independence for certain calling applications. To
basic services oriented towards the requirements of callers
need not themselves interpret the internal syntax and semantics
names, GSS-API calls for name comparison (GSS_Compare_name()),
human-readable display (GSS_Display_name()), input
(GSS_Import_name()), internal name deallocation (GSS_Release_name()),
and internal name duplication (GSS_Duplicate_name()) functions
defined. (It is anticipated that these proposed GSS-API calls will
implemented in many end systems based on system-specific
manipulation primitives already extant within those end systems
inclusion within the GSS-API is intended to offer GSS-API callers
portable means to perform specific operations, supportive
authorization and audit requirements, on authenticated names.)
GSS_Import_name() implementations can, where appropriate,
more than one printable syntax corresponding to a given
(e.g., alternative printable representations for X.500
Names), allowing flexibility for their callers to select
alternative representations. GSS_Display_name()
output a printable syntax selected as appropriate to
operational environments; this selection is a local matter.
desiring portability across alternative printable syntaxes
refrain from implementing comparisons based on printable name
and should instead use the GSS_Compare_name() call to
whether or not one internal-format name matches another
The GSS_Canonicalize_name() and GSS_Export_name() calls
callers to acquire and process Exported Name Objects,
and translated in accordance with the procedures of a
GSS-API mechanism. Exported Name Objects can, in turn, be input
GSS_Import_name(), yielding equivalent MNs. These facilities
designed specifically to enable efficient storage and comparison
names (e.g., for use in access control lists).
Linn Standards Track [Page 13]
RFC 2078 GSS-API January 1997
The following diagram illustrates the intended dataflow among name
related GSS-API processing routines
GSS-API library
|
|
V text,
text --------------> internal_name (IN) -----------> display
import_name() / display_name()
/
/
/
accept_sec_context() /
| /
| /
| / canonicalize_name()
| /
| /
| /
| /
| /
| |
V V <---------------------
single mechanism import_name() exported name:
internal_name (MN) binary "blob"
----------------------> for access
export_name()
1.1.6: Channel
The GSS-API accommodates the concept of caller-provided
binding ("chan_binding") information. Channel bindings are used
strengthen the quality with which peer entity authentication
provided during context establishment, by limiting the scope
which an intercepted context establishment token can be reused by
attacker. Specifically, they enable GSS-API callers to bind
establishment of a security context to relevant
(e.g., addresses, transformed representations of encryption keys)
the underlying communications channel, of protection
applied to that communications channel, and to application-
data
The caller initiating a security context must determine
appropriate channel binding values to provide as input to
GSS_Init_sec_context() call, and consistent values must be
to GSS_Accept_sec_context() by the context's target, in order
both peers' GSS-API mechanisms to validate that received
possess correct channel-related characteristics. Use or non-use
Linn Standards Track [Page 14]
RFC 2078 GSS-API January 1997
the GSS-API channel binding facility is a caller option. GSS-
mechanisms can operate in an environment where NULL channel
are presented; mechanism implementors are encouraged, but
required, to make use of caller-provided channel binding data
their mechanisms. Callers should not assume that
mechanisms provide confidentiality protection for channel
information
When non-NULL channel bindings are provided by callers,
mechanisms can offer enhanced security value by interpreting
bindings' content (rather than simply representing those bindings,
integrity check values computed on them, within tokens) and
therefore depend on presentation of specific data in a
format. To this end, agreements among mechanism implementors
defining conventional interpretations for the contents of
binding arguments, including address specifiers (with
dependent on communications protocol environment) for
initiators and acceptors. (These conventions are being
in GSS-API mechanism specifications and into the GSS-API C
bindings specification.) In order for GSS-API callers to be
across multiple mechanisms and achieve the full
functionality which each mechanism can provide, it is
recommended that GSS-API callers provide channel bindings
with these conventions and those of the networking environment
which they operate
1.2: GSS-API Features and
This section describes aspects of GSS-API operations, of the
services which the GSS-API provides, and provides commentary
design issues
1.2.1: Status
Each GSS-API call provides two status return values. Major_
values provide a mechanism-independent indication of call
(e.g., GSS_S_COMPLETE, GSS_S_FAILURE, GSS_S_CONTINUE_NEEDED),
sufficient to drive normal control flow within the caller in
generic fashion. Table 1 summarizes the defined major_status
codes in tabular fashion
Linn Standards Track [Page 15]
RFC 2078 GSS-API January 1997
Table 1: GSS-API Major Status
FATAL ERROR
GSS_S_BAD_BINDINGS channel binding
GSS_S_BAD_MECH unsupported mechanism
GSS_S_BAD_NAME invalid name
GSS_S_BAD_NAMETYPE name of unsupported type
GSS_S_BAD_STATUS invalid input status
GSS_S_BAD_SIG token had invalid integrity
GSS_S_CONTEXT_EXPIRED specified security context
GSS_S_CREDENTIALS_EXPIRED expired credentials
GSS_S_DEFECTIVE_CREDENTIAL defective credential
GSS_S_DEFECTIVE_TOKEN defective token
GSS_S_FAILURE failure, unspecified at GSS-
GSS_S_NO_CONTEXT no valid security context
GSS_S_NO_CRED no valid credentials
GSS_S_BAD_QOP unsupported QOP
GSS_S_UNAUTHORIZED operation
GSS_S_UNAVAILABLE operation
GSS_S_DUPLICATE_ELEMENT duplicate credential element
GSS_S_NAME_NOT_MN name contains multi-mechanism
INFORMATORY STATUS
GSS_S_COMPLETE normal
GSS_S_CONTINUE_NEEDED continuation call to
GSS_S_DUPLICATE_TOKEN duplicate per-message
GSS_S_OLD_TOKEN timed-out per-message
GSS_S_UNSEQ_TOKEN reordered (early) per-message
GSS_S_GAP_TOKEN skipped predecessor token(s
Minor_status provides more detailed status information which
include status codes specific to the underlying security mechanism
Minor_status values are not specified in this document
GSS_S_CONTINUE_NEEDED major_status returns, and optional
outputs, are provided in GSS_Init_sec_context()
GSS_Accept_sec_context() calls so that different mechanisms
employment of different numbers of messages within
authentication sequences need not be reflected in separate code
within calling applications. Instead, such cases are
Linn Standards Track [Page 16]
RFC 2078 GSS-API January 1997
with sequences of continuation calls to GSS_Init_sec_context()
GSS_Accept_sec_context(). The same mechanism is used to
mutual authentication within the GSS-API's context initiation calls
For mech_types which require interactions with third-party servers
order to establish a security context, GSS-API context
calls may block pending completion of such third-party interactions
On the other hand, no GSS-API calls pend on serialized
with GSS-API peer entities. As a result, local GSS-API
returns cannot reflect unpredictable or asynchronous
occurring at remote peers, and reflection of such status
is a caller responsibility outside the GSS-API
1.2.2: Per-Message Security Service
When a context is established, two flags are returned to indicate
set of per-message protection security services which will
available on the context
the integ_avail flag indicates whether per-message integrity
data origin authentication services are
the conf_avail flag indicates whether per-message
services are available, and will never be returned TRUE unless
integ_avail flag is also returned
GSS-API callers desiring per-message security services
check the values of these flags at context establishment time,
must be aware that a returned FALSE value for integ_avail
that invocation of GSS_GetMIC() or GSS_Wrap() primitives on
associated context will apply no cryptographic protection to
data messages
The GSS-API per-message integrity and data origin
services provide assurance to a receiving caller that protection
applied to a message by the caller's peer on the security context
corresponding to the entity named at context initiation. The GSS-
per-message confidentiality service provides assurance to a
caller that the message's content is protected from access
entities other than the context's named peer
Linn Standards Track [Page 17]
RFC 2078 GSS-API January 1997
The GSS-API per-message protection service primitives, as
category name implies, are oriented to operation at the
of protocol data units. They perform cryptographic operations on
data units, transfer cryptographic control information in tokens
and, in the case of GSS_Wrap(), encapsulate the protected data unit
As such, these primitives are not oriented to efficient
protection for stream-paradigm protocols (e.g., Telnet)
cryptography must be applied on an octet-by-octet basis
1.2.3: Per-Message Replay Detection and
Certain underlying mech_types offer support for replay
and/or sequencing of messages transferred on the contexts
support. These optionally-selectable protection features are
from replay detection and sequencing features applied to the
establishment operation itself; the presence or absence of context
level replay or sequencing features is wholly a function of
underlying mech_type's capabilities, and is not selected or
as a caller option
The caller initiating a context provides flags (replay_det_req_
and sequence_req_flag) to specify whether the use of per-
replay detection and sequencing features is desired on the
being established. The GSS-API implementation at the initiator
can determine whether these features are supported (and whether
are optionally selectable) as a function of mech_type, without
for bilateral negotiation with the target. When enabled,
features provide recipients with indicators as a result of GSS-
processing of incoming messages, identifying whether those
were detected as duplicates or out-of-sequence. Detection of
events does not prevent a suspect message from being provided to
recipient; the appropriate course of action on a suspect message is
matter of caller policy
The semantics of the replay detection and sequencing services
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
well-formed and correctly signed messages are as follows
1. GSS_S_COMPLETE indicates that the message was within the
(of time or sequence space) allowing replay events to be detected
and that the message was not a replay of a previously-
message within that window
Linn Standards Track [Page 18]
RFC 2078 GSS-API January 1997
2. GSS_S_DUPLICATE_TOKEN indicates that the
checkvalue on the received message was correct, but that
message was recognized as a duplicate of a previously-
message
3. GSS_S_OLD_TOKEN indicates that the cryptographic checkvalue
the received message was correct, but that the message is too
to be checked for duplication
When sequence_state is TRUE, the possible major_status returns
well-formed and correctly signed messages are as follows
1. GSS_S_COMPLETE indicates that the message was within the
(of time or sequence space) allowing replay events to be detected
that the message was not a replay of a previously-
message within that window, and that no predecessor
messages are missing relative to the last received message (
any) processed on the context with a correct
checkvalue
2. GSS_S_DUPLICATE_TOKEN indicates that the integrity check
on the received message was correct, but that the message
recognized as a duplicate of a previously-processed message
3. GSS_S_OLD_TOKEN indicates that the integrity check value on
received message was correct, but that the token is too old to
checked for duplication
4. GSS_S_UNSEQ_TOKEN indicates that the cryptographic
on the received message was correct, but that it is earlier in
sequenced stream than a message already processed on the context
[Note: Mechanisms can be architected to provide a stricter form
sequencing service, delivering particular messages to
only after all predecessor messages in an ordered stream have
delivered. This type of support is incompatible with the GSS-
paradigm in which recipients receive all messages, whether
order or not, and provide them (one at a time, without intra-GSS
API message buffering) to GSS-API routines for validation. GSS
API facilities provide supportive functions, aiding clients
achieve strict message stream integrity in an efficient manner
conjunction with sequencing provisions in
protocols, but the GSS-API does not offer this level of
stream integrity service by itself.]
Linn Standards Track [Page 19]
RFC 2078 GSS-API January 1997
5. GSS_S_GAP_TOKEN indicates that the cryptographic checkvalue
the received message was correct, but that one or more
sequenced messages have not been successfully processed
to the last received message (if any) processed on the
with a correct cryptographic checkvalue
As the message stream integrity features (especially sequencing)
interfere with certain applications' intended
paradigms, and since support for such features is likely to
resource intensive, it is highly recommended that mech_
supporting these features allow them to be activated selectively
initiator request when a context is established. A context
and target are provided with corresponding
(replay_det_state and sequence_state), signifying whether
features are active on a given context
An example mech_type supporting per-message replay detection
(when replay_det_state is TRUE) implement the feature as follows:
underlying mechanism would insert timestamps in data elements
by GSS_GetMIC() and GSS_Wrap(), and would maintain (within a time
limited window) a cache (qualified by originator-recipient pair
identifying received data elements processed by GSS_VerifyMIC()
GSS_Unwrap(). When this feature is active, exception status
(GSS_S_DUPLICATE_TOKEN, GSS_S_OLD_TOKEN) will be provided
GSS_VerifyMIC() or GSS_Unwrap() is presented with a message which
either a detected duplicate of a prior message or which is too old
validate against a cache of recently received messages
1.2.4: Quality of
Some mech_types provide their users with fine granularity
over the means used to provide per-message protection,
callers to trade off security processing overhead dynamically
the protection requirements of particular messages. A per-
quality-of-protection parameter (analogous to quality-of-service,
QOS) selects among different QOP options supported by that mechanism
On context establishment for a multi-QOP mech_type, context-
data provides the prerequisite data for a range of
qualities
It is expected that the majority of callers will not wish to
explicit mechanism-specific QOP control and will therefore
selection of a default QOP. Definitions of, and choices among, non
default QOP values are mechanism-specific, and no ordered
of QOP values can be assumed equivalent across different mechanisms
Meaningful use of non-default QOP values demands that callers
familiar with the QOP definitions of an underlying mechanism
mechanisms, and is therefore a non-portable construct.
Linn Standards Track [Page 20]
RFC 2078 GSS-API January 1997
GSS_S_BAD_QOP major_status value is defined in order to indicate
a provided QOP value is unsupported for a security context,
likely because that value is unrecognized by the
mechanism
1.2.5: Anonymity
In certain situations or environments, an application may wish
authenticate a peer and/or protect communications using GSS-API per
message services without revealing its own identity. For example
consider an application which provides read access to a
database, and which permits queries by arbitrary requestors.
client of such a service might wish to authenticate the service,
establish trust in the information received from it, but might
wish to disclose its identity to the service for privacy reasons
In ordinary GSS-API usage, a context initiator's identity is
available to the context acceptor as part of the
establishment process. To provide for anonymity support, a
(input anon_req_flag to GSS_Init_sec_context()) is provided
which context initiators may request that their identity not
provided to the context acceptor. Mechanisms are not required
honor this request, but a caller will be informed (via
anon_state indicator from GSS_Init_sec_context()) whether or not
request is honored. Note that authentication as the
principal does not necessarily imply that credentials are
required in order to establish a context
The following Object Identifier value is provided as a means
identify anonymous names, and can be compared against in order
determine, in a mechanism-independent fashion, whether a name
to an anonymous principal
{1(iso), 3(org), 6(dod), 1(internet), 5(security), 6(nametypes),
3(gss-anonymous-name)}
The recommended symbolic name corresponding to this definition
GSS_C_NT_ANONYMOUS
Four possible combinations of anon_state and mutual_state
possible, with the following results
anon_state == FALSE, mutual_state == FALSE:
authenticated to target
anon_state == FALSE, mutual_state == TRUE: initiator
to target, target authenticated to initiator
Linn Standards Track [Page 21]
RFC 2078 GSS-API January 1997
anon_state == TRUE, mutual_state == FALSE: initiator
as anonymous principal to target
anon_state == TRUE, mutual_state == TRUE: initiator
as anonymous principal to target, target authenticated
initiator
1.2.6:
No initialization calls (i.e., calls which must be invoked prior
invocation of other facilities in the interface) are defined in GSS
API. As an implication of this fact, GSS-API implementations
themselves be self-initializing
1.2.7: Per-Message Protection During Context
A facility is defined in GSS-V2 to enable protection and buffering
data messages for later transfer while a security context'
establishment is in GSS_S_CONTINUE_NEEDED status, to be used in
where the caller side already possesses the necessary session key
enable this processing. Specifically, a new state Boolean,
prot_ready_state, is added to the set of information returned
GSS_Init_sec_context(), GSS_Accept_sec_context(),
GSS_Inquire_context().
For context establishment calls, this state Boolean is valid
interpretable when the associated major_status is
GSS_S_CONTINUE_NEEDED, or GSS_S_COMPLETE. Callers of GSS-API (
initiators and acceptors) can assume that per-message protection (
GSS_Wrap(), GSS_Unwrap(), GSS_GetMIC() and GSS_VerifyMIC())
available and ready for use if either: prot_ready_state == TRUE,
major_status == GSS_S_COMPLETE, though mutual authentication (
requested) cannot be guaranteed until GSS_S_COMPLETE is returned
This achieves full, transparent backward compatibility for GSS-API V
callers, who need not even know of the existence of prot_ready_state
and who will get the expected behavior from GSS_S_COMPLETE, but
will not be able to use per-message protection before GSS_S_
is returned
It is not a requirement that GSS-V2 mechanisms ever return
prot_ready_state before completion of context establishment (indeed
some mechanisms will not evolve usable message protection keys
especially at the context acceptor, before context establishment
complete). It is expected but not required that GSS-V2
will return TRUE prot_ready_state upon completion of
establishment if they support per-message protection at all (
GSS-V2 applications should not assume that TRUE prot_ready_state
Linn Standards Track [Page 22]
RFC 2078 GSS-API January 1997
always be returned together with the GSS_S_COMPLETE major_status
since GSS-V2 implementations may continue to support GSS-V1
code, which will never return TRUE prot_ready_state).
When prot_ready_state is returned TRUE, mechanisms shall also
those context service indicator flags (deleg_state, mutual_state
replay_det_state, sequence_state, anon_state, trans_state
conf_avail, integ_avail) which represent facilities confirmed,
that time, to be available on the context being established.
situations where prot_ready_state is returned before GSS_S_COMPLETE
it is possible that additional facilities may be confirmed
subsequently indicated when GSS_S_COMPLETE is returned
1.2.8: Implementation
This section recommends aspects of GSS-API implementation behavior
the interests of overall robustness
If a token is presented for processing on a GSS-API security
and that token is determined to be invalid for that context,
context's state should not be disrupted for purposes of
subsequent valid tokens
Certain local conditions at a GSS-API implementation (e.g.,
unavailability of memory) may preclude, temporarily or permanently
the successful processing of tokens on a GSS-API security context
typically generating GSS_S_FAILURE major_status returns along
locally-significant minor_status. For robust operation under
conditions, the following recommendations are made
Failing calls should free any memory they allocate, so
callers may retry without causing further loss of resources
Failure of an individual call on an established context should
preclude subsequent calls from succeeding on the same context
Whenever possible, it should be possible
GSS_Delete_sec_context() calls to be successfully processed
if other calls cannot succeed, thereby enabling context-
resources to be released
2: Interface
This section describes the GSS-API's service interface, dividing
set of calls offered into four groups. Credential management
are related to the acquisition and release of credentials
principals. Context-level calls are related to the management
security contexts between principals. Per-message calls are
Linn Standards Track [Page 23]
RFC 2078 GSS-API January 1997
to the protection of individual messages on established
contexts. Support calls provide ancillary functions useful to GSS-
callers. Table 2 groups and summarizes the calls in tabular fashion
Table 2: GSS-API
CREDENTIAL
GSS_Acquire_cred acquire credentials for
GSS_Release_cred release credentials after
GSS_Inquire_cred display information
GSS_Add_cred construct credentials
GSS_Inquire_cred_by_mech display per-mechanism
CONTEXT-LEVEL
GSS_Init_sec_context initiate outbound security
GSS_Accept_sec_context accept inbound security
GSS_Delete_sec_context flush context when no longer
GSS_Process_context_token process received control token
GSS_Context_time indicate validity time remaining
GSS_Inquire_context display information about
GSS_Wrap_size_limit determine GSS_Wrap token size
GSS_Export_sec_context transfer context to other
GSS_Import_sec_context import transferred
PER-MESSAGE
GSS_GetMIC apply integrity check, receive
token separate from
GSS_VerifyMIC validate integrity check
along with
GSS_Wrap sign, optionally encrypt
GSS_Unwrap decapsulate, decrypt if needed
validate integrity
Linn Standards Track [Page 24]
RFC 2078 GSS-API January 1997
SUPPORT
GSS_Display_status translate status codes to
