As per Relevance of the word indicate, we have this rfc below:
Network Working Group J.
Request for Comments: 2743 RSA
Obsoletes: 2078 January 2000
Category: Standards
Generic Security Service Application Program
Version 2, Update 1
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
Copyright
Copyright (C) The Internet Society (2000). All Rights Reserved
The Generic Security Service Application Program Interface (GSS-API),
Version 2, as defined in [RFC-2078], provides security services
callers in a generic fashion, supportable with a range of
mechanisms and technologies and hence allowing source-
portability of applications to different environments.
specification defines GSS-API services and primitives at a
independent of underlying mechanism and programming
environment, and is to be complemented by other,
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 obsoletes [RFC-2078], making specific, incremental
in 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
Linn Standards Track [Page 1]
RFC 2743 GSS-API January 2000
TABLE OF
1: GSS-API Characteristics and Concepts . . . . . . . . . . . . 4
1.1: GSS-API Constructs . . . . . . . . . . . . . . . . . . . . 6
1.1.1: Credentials . . . . . . . . . . . . . . . . . . . . . . 6
1.1.1.1: Credential Constructs and Concepts . . . . . . . . . . 6
1.1.1.2: Credential Management . . . . . . . . . . . . . . . . 7
1.1.1.3: Default Credential Resolution . . . . . . . . . . . . 8
1.1.2: Tokens . . . . . . . . . . . . . . . . . . . . . . . . . 9
1.1.3: Security Contexts . . . . . . . . . . . . . . . . . . . 11
1.1.4: Mechanism Types . . . . . . . . . . . . . . . . . . . . 12
1.1.5: Naming . . . . . . . . . . . . . . . . . . . . . . . . 13
1.1.6: Channel Bindings . . . . . . . . . . . . . . . . . . . 16
1.2: GSS-API Features and Issues . . . . . . . . . . . . . . . 17
1.2.1: Status Reporting and Optional Service Support . . . . 17
1.2.1.1: Status Reporting . . . . . . . . . . . . . . . . . . . 17
1.2.1.2: Optional Service Support . . . . . . . . . . . . . . . 19
1.2.2: Per-Message Security Service Availability . . . . . . . 20
1.2.3: Per-Message Replay Detection and Sequencing . . . . . . 21
1.2.4: Quality of Protection . . . . . . . . . . . . . . . . . 24
1.2.5: Anonymity Support . . . . . . . . . . . . . . . . . . . 25
1.2.6: Initialization . . . . . . . . . . . . . . . . . . . . . 25
1.2.7: Per-Message Protection During Context Establishment . . 26
1.2.8: Implementation Robustness . . . . . . . . . . . . . . . 27
1.2.9: Delegation . . . . . . . . . . . . . . . . . . . . . . . 28
1.2.10: Interprocess Context Transfer . . . . . . . . . . . . . 28
2: Interface Descriptions . . . . . . . . . . . . . . . . . . 29
2.1: Credential management calls . . . . . . . . . . . . . . . 31
2.1.1: GSS_Acquire_cred call . . . . . . . . . . . . . . . . . 31
2.1.2: GSS_Release_cred call . . . . . . . . . . . . . . . . . 34
2.1.3: GSS_Inquire_cred call . . . . . . . . . . . . . . . . . 35
2.1.4: GSS_Add_cred call . . . . . . . . . . . . . . . . . . . 37
2.1.5: GSS_Inquire_cred_by_mech call . . . . . . . . . . . . . 40
2.2: Context-level calls . . . . . . . . . . . . . . . . . . . 41
2.2.1: GSS_Init_sec_context call . . . . . . . . . . . . . . . 42
2.2.2: GSS_Accept_sec_context call . . . . . . . . . . . . . . 49
2.2.3: GSS_Delete_sec_context call . . . . . . . . . . . . . . 53
2.2.4: GSS_Process_context_token call . . . . . . . . . . . . 54
2.2.5: GSS_Context_time call . . . . . . . . . . . . . . . . . 55
2.2.6: GSS_Inquire_context call . . . . . . . . . . . . . . . 56
2.2.7: GSS_Wrap_size_limit call . . . . . . . . . . . . . . . 57
2.2.8: GSS_Export_sec_context call . . . . . . . . . . . . . . 59
2.2.9: GSS_Import_sec_context call . . . . . . . . . . . . . . 61
2.3: Per-message calls . . . . . . . . . . . . . . . . . . . . 62
2.3.1: GSS_GetMIC call . . . . . . . . . . . . . . . . . . . . 63
2.3.2: GSS_VerifyMIC call . . . . . . . . . . . . . . . . . . 64
2.3.3: GSS_Wrap call . . . . . . . . . . . . . . . . . . . . . 65
2.3.4: GSS_Unwrap call . . . . . . . . . . . . . . . . . . . . 66
Linn Standards Track [Page 2]
RFC 2743 GSS-API January 2000
2.4: Support calls . . . . . . . . . . . . . . . . . . . . . . 68
2.4.1: GSS_Display_status call . . . . . . . . . . . . . . . . 68
2.4.2: GSS_Indicate_mechs call . . . . . . . . . . . . . . . . 69
2.4.3: GSS_Compare_name call . . . . . . . . . . . . . . . . . 70
2.4.4: GSS_Display_name call . . . . . . . . . . . . . . . . . 71
2.4.5: GSS_Import_name call . . . . . . . . . . . . . . . . . 72
2.4.6: GSS_Release_name call . . . . . . . . . . . . . . . . . 73
2.4.7: GSS_Release_buffer call . . . . . . . . . . . . . . . . 74
2.4.8: GSS_Release_OID_set call . . . . . . . . . . . . . . . 74
2.4.9: GSS_Create_empty_OID_set call . . . . . . . . . . . . . 75
2.4.10: GSS_Add_OID_set_member call . . . . . . . . . . . . . . 76
2.4.11: GSS_Test_OID_set_member call . . . . . . . . . . . . . 76
2.4.12: GSS_Inquire_names_for_mech call . . . . . . . . . . . . 77
2.4.13: GSS_Inquire_mechs_for_name call . . . . . . . . . . . . 77
2.4.14: GSS_Canonicalize_name call . . . . . . . . . . . . . . 78
2.4.15: GSS_Export_name call . . . . . . . . . . . . . . . . . 79
2.4.16: GSS_Duplicate_name call . . . . . . . . . . . . . . . . 80
3: Data Structure Definitions for GSS-V2 Usage . . . . . . . . 81
3.1: Mechanism-Independent Token Format . . . . . . . . . . . . 81
3.2: Mechanism-Independent Exported Name Object Format . . . . 84
4: Name Type Definitions . . . . . . . . . . . . . . . . . . . 85
4.1: Host-Based Service Name Form . . . . . . . . . . . . . . . 85
4.2: User Name Form . . . . . . . . . . . . . . . . . . . . . . 86
4.3: Machine UID Form . . . . . . . . . . . . . . . . . . . . . 87
4.4: String UID Form . . . . . . . . . . . . . . . . . . . . . 87
4.5: Anonymous Nametype . . . . . . . . . . . . . . . . . . . . 87
4.6: GSS_C_NO_OID . . . . . . . . . . . . . . . . . . . . . . . 88
4.7: Exported Name Object . . . . . . . . . . . . . . . . . . . 88
4.8: GSS_C_NO_NAME . . . . . . . . . . . . . . . . . . . . . . 88
5: Mechanism-Specific Example Scenarios . . . . . . . . . . . 88
5.1: Kerberos V5, single-TGT . . . . . . . . . . . . . . . . . 89
5.2: Kerberos V5, double-TGT . . . . . . . . . . . . . . . . . 89
5.3: X.509 Authentication Framework . . . . . . . . . . . . . 90
6: Security Considerations . . . . . . . . . . . . . . . . . . 91
7: Related Activities . . . . . . . . . . . . . . . . . . . . 92
8: Referenced Documents . . . . . . . . . . . . . . . . . . . 93
Appendix A: Mechanism Design Constraints . . . . . . . . . . . 94
Appendix B: Compatibility with GSS-V1 . . . . . . . . . . . . . 94
Appendix C: Changes Relative to RFC-2078 . . . . . . . . . . . 96
Author's Address . . . . . . . . . . . . . . . . . . . . . . .100
Full Copyright Statement . . . . . . . . . . . . . . . . . . .101
Linn Standards Track [Page 3]
RFC 2743 GSS-API January 2000
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
(GSS_Init_sec_context() and GSS_Accept_sec_context() calls), from
operations of providing per-message data origin authentication
data integrity protection (GSS_GetMIC() and GSS_VerifyMIC() calls
for messages subsequently transferred in conjunction with
context. (The definition for the peer entity authentication service
and other definitions used in this document, corresponds to
provided in [ISO-7498-2].) When establishing a security context,
GSS-API enables a context initiator to optionally permit
credentials to be delegated, meaning that the context acceptor
initiate further security contexts on behalf of the
caller. Per-message GSS_Wrap() and GSS_Unwrap() calls provide
data origin authentication and data integrity services
GSS_GetMIC() and GSS_VerifyMIC() offer, and also support selection
confidentiality services as a caller option. Additional calls
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 also
that the underlying authentication technology is capable
authenticating a client to a server using elements carried within
single token, and of authenticating the server to the client (
authentication) with a single returned token; this assumption
for some presently-documented CAT mechanisms but is not
true for other 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
Linn Standards Track [Page 4]
RFC 2743 GSS-API January 2000
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
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 by
GSS_S_COMPLETE status along with the resultant 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
Linn Standards Track [Page 5]
RFC 2743 GSS-API January 2000
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 have been implemented using secret-key
(e.g., Kerberos, per [RFC-1964]) and with public-key
(e.g., SPKM, per [RFC-2025]).
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 may
interposed between applications which call that protocol and
GSS-API (e.g., as defined in [RFC-2203] for Open Network
Remote Procedure Call (RPC)), thereby invoking GSS-API
in conjunction with that protocol's communications invocations
Protocol association independence: The GSS-API's security
construct is independent of communications protocol
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
Linn Standards Track [Page 6]
RFC 2743 GSS-API January 2000
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,
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
Linn Standards Track [Page 7]
RFC 2743 GSS-API January 2000
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
1.1.1.3: Default Credential
The GSS_Init_sec_context() and GSS_Accept_sec_context()
allow the value GSS_C_NO_CREDENTIAL to be specified as
credential handle parameter. This special credential
indicates a desire by the application to act as a default principal
In support of application portability, support for the
resolution behavior described below for initiator
(GSS_Init_sec_context() usage) is mandated; support for the
resolution behavior described below for acceptor
(GSS_Accept_sec_context() usage) is recommended. If
credential resolution fails, GSS_S_NO_CRED status is to be returned
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,
Linn Standards Track [Page 8]
RFC 2743 GSS-API January 2000
(ii) If the platform maintains a concept of a default network
identity, and if the application is authorized to act on
of that identity for the purpose of initiating
contexts, then the principal corresponding to that
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
on behalf of the network-identity image of the default
identity for the purpose of initiating security contexts,
the 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
shall be used,
(ii) If the mechanism can determine the identity of the
principal by examining the context-establishment token, and
the accepting application is authorized to act as
principal for the purpose of accepting security contexts,
that principal 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,
(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
Linn Standards Track [Page 9]
RFC 2743 GSS-API January 2000
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.1 of
document provides, for designers of GSS-API 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
Context-level tokens may be output by GSS-API calls (and should
transferred to GSS-API peers) whether or not the calls'
indicators indicate successful completion. Per-message tokens,
contrast, are to be returned only upon successful completion of per
message calls. Zero-length tokens are never returned by GSS
for transfer to a peer. Token transfer may take place in an in-
manner, integrated into the same protocol stream used by the GSS-
callers for other data transfers, or in an out-of-band manner
a logically separate 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
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),
Linn Standards Track [Page 10]
RFC 2743 GSS-API January 2000
- 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 mechanisms based on a particular
cryptographic technique and protocol (i.e., conformant to a
GSS-API mechanism definition) does not necessarily imply that GSS-
callers using that GSS-API mechanism will be able to
with peers invoking the same technique and protocol outside the GSS
API paradigm, or with peers implementing a different GSS-
mechanism based on the same underlying technology. The format
GSS-API tokens defined in conjunction with a particular mechanism
and the techniques used to integrate those tokens into callers
protocols, may not be interoperable with the tokens used by non-GSS
API callers of the same underlying technique
1.1.3: Security
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
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
Linn Standards Track [Page 11]
RFC 2743 GSS-API January 2000
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. Messages may be protected
transferred in both directions on an established GSS-API
context concurrently; protection of messages in one direction
not interfere with protection of messages in the reverse direction
GSS-API implementations are expected to retain inquirable
data on a context until the context is released by a caller,
after the context has expired, although underlying cryptographic
elements may be deleted after expiration in order to limit
exposure
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
For GSS-API purposes, the phrase "negotiating mechanism" refers to
mechanism which itself performs negotiation in order to select
concrete mechanism which is shared between peers and is then used
context establishment. Only those mechanisms which are defined
their specifications as negotiating mechanisms are to yield
mechanisms with different identifier values than the value which
input by a GSS-API caller, except for the case of a caller
the "default" mech_type
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):
Linn Standards Track [Page 12]
RFC 2743 GSS-API January 2000
use of a fixed mech_type, defined by configuration, within
syntactic convention on a target-specific basis,
examination of a target's name lookup of a target's name in
naming service or other database in order to identify mech_
supported by that
explicit negotiation between GSS-API callers in advance
security context
use of a negotiating
When transferred between GSS-API peers, mech_type specifiers (
Section 3 of this document, represented as Object Identifiers (OIDs))
serve to qualify the interpretation of associated tokens. (
structure and encoding of Object Identifiers is defined in [ISOIEC
8824] and [ISOIEC-8825].) Use of hierarchically structured
serves to preclude ambiguous interpretation of mech_type specifiers
The OID representing the DASS ([RFC-1507]) MechType, for example,
1.3.12.2.1011.7.5, and that of the Kerberos V5 mechanism ([RFC
1964]), having been advanced to the level of Proposed Standard,
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
Linn Standards Track [Page 13]
RFC 2743 GSS-API January 2000
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
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
Linn Standards Track [Page 14]
RFC 2743 GSS-API January 2000
When used in large access control lists, the overhead of
GSS_Import_name() and GSS_Compare_name() on each name from the
may be prohibitive. As an alternative way of supporting this case
GSS-API defines a special form of the contiguous string name
may be compared directly (e.g., with memcmp()). Contiguous
suitable for comparison are generated by the GSS_Export_name()
routine, which requires an MN as input. Exported names may be re
imported by the GSS_Import_name() routine, and the resulting
name will also be an MN. The symbolic constant GSS_C_NT_EXPORT_
identifies the "export name" type. Structurally, an exported
object consists of a header containing an OID identifying
mechanism that authenticated the name, and a trailer containing
name itself, where the syntax of the trailer is defined by
individual mechanism specification. The precise format of
exported name is defined in Section 3.2 of this specification
Note that the results obtained by using GSS_Compare_name() will
general be different from those obtained by
GSS_Canonicalize_name() and GSS_Export_name(), and then comparing
exported names. The first series of operations determines
two (unauthenticated) names identify the same principal; the
whether a particular mechanism would authenticate them as the
principal. These two operations will in general give the
results only for MNs
The following diagram illustrates the intended dataflow among name
related GSS-API processing routines
Linn Standards Track [Page 15]
RFC 2743 GSS-API January 2000
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
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
Linn Standards Track [Page 16]
RFC 2743 GSS-API January 2000
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 Reporting and Optional Service
1.2.1.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
Sequencing-related informatory major_status
(GSS_S_DUPLICATE_TOKEN, GSS_S_OLD_TOKEN, GSS_S_UNSEQ_TOKEN,
GSS_S_GAP_TOKEN) can be indicated in conjunction with
GSS_S_COMPLETE or GSS_S_FAILURE status for GSS-API per-message calls
For context establishment calls, these sequencing-related codes
be indicated only in conjunction with GSS_S_FAILURE status (never
Linn Standards Track [Page 17]
RFC 2743 GSS-API January 2000
conjunction with GSS_S_COMPLETE or GSS_S_CONTINUE_NEEDED), and
therefore, always correspond to fatal failures if encountered
the context establishment phase
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_BAD_MIC preferred alias for GSS_S_BAD_
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
Linn Standards Track [Page 18]
RFC 2743 GSS-API January 2000
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
with sequences of continuation calls to GSS_Init_sec_context()
GSS_Accept_sec_context(). The same facility 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.1.2: Optional Service
A context initiator may request various optional services at
establishment time. Each of these services is requested by setting
flag in the req_flags input parameter to GSS_Init_sec_context().
The optional services currently defined are
- Delegation - The (usually temporary) transfer of rights
initiator to acceptor, enabling the acceptor to
itself as an agent of the initiator
- Mutual Authentication - In addition to the
authenticating its identity to the context acceptor, the
acceptor should also authenticate itself to the initiator
- Replay detection - In addition to providing message
services, GSS_GetMIC() and GSS_Wrap() should include
numbering information to enable GSS_VerifyMIC() and GSS_Unwrap()
to detect if a message has been duplicated
- Out-of-sequence detection - In addition to providing
integrity services, GSS_GetMIC() and GSS_Wrap() should
message sequencing information to enable GSS_VerifyMIC()
GSS_Unwrap() to detect if a message has been received out
sequence
Linn Standards Track [Page 19]
RFC 2743 GSS-API January 2000
- Anonymous authentication - The establishment of the
context should not reveal the initiator's identity to the
acceptor
- Available per-message confidentiality - requests that per
message confidentiality services be available on the context
- Available per-message integrity - requests that per-
integrity services be available on the context
Any currently undefined bits within such flag arguments should
ignored by GSS-API implementations when presented by an application
and should be set to zero when returned to the application by
GSS-API implementation
Some mechanisms may not support all optional services, and
mechanisms may only support some services in conjunction with others
Both GSS_Init_sec_context() and GSS_Accept_sec_context() inform
applications which services will be available from the context
the establishment phase is complete, via the ret_flags
parameter. In general, if the security mechanism is capable
providing a requested service, it should do so, even if
services must be enabled in order to provide the requested service
If the mechanism is incapable of providing a requested service,
should proceed without the service, leaving the application to
the context establishment process if it considers the
service to be mandatory
Some mechanisms may specify that support for some services
optional, and that implementors of the mechanism need not provide it
This is most commonly true of the confidentiality service,
because of legal restrictions on the use of data-encryption, but
apply to any of the services. Such mechanisms are required to
at least one token from acceptor to initiator during
establishment when the initiator indicates a desire to use such
service, so that the initiating GSS-API can correctly
whether the service is supported by the acceptor's 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
Linn Standards Track [Page 20]
RFC 2743 GSS-API January 2000
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 should
the values of these flags at context establishment time, and must
aware that a returned FALSE value for integ_avail means
invocation of GSS_GetMIC() or GSS_Wrap() primitives on the
context will apply no cryptographic protection to user 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
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 the selected mechanism
without need for bilateral negotiation with the target. When enabled
these features provide recipients with indicators as a result
GSS-API processing of incoming messages, identifying whether
messages were detected as duplicates or out-of-sequence. Detection
Linn Standards Track [Page 21]
RFC 2743 GSS-API January 2000
such events does not prevent a suspect message from being provided
a recipient; the appropriate course of action on a suspect message
a 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, without concurrent indication
GSS_S_DUPLICATE_TOKEN or GSS_S_OLD_TOKEN, indicates that
message was within the window (of time or sequence space)
replay events to be detected, and that the message was not
replay of a previously-processed message within that window
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. In addition to identifying duplicated tokens
by a context's peer, this status may also be used to
reflected copies of locally-generated tokens; it is
that mechanism designers include within their protocols
to detect and report such tokens
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, without concurrent indication
GSS_S_DUPLICATE_TOKEN, GSS_S_OLD_TOKEN, GSS_S_UNSEQ_TOKEN,
GSS_S_GAP_TOKEN, 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.
addition to identifying duplicated tokens originated by
context's peer, this status may also be used to identify
Linn Standards Track [Page 22]
RFC 2743 GSS-API January 2000
copies of locally-generated tokens; it is recommended
mechanism designers include within their protocols facilities
detect and report such tokens
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.]
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
Linn Standards Track [Page 23]
RFC 2743 GSS-API January 2000
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.
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
In the interests of interoperability, mechanisms which allow
support of particular QOP values shall satisfy one of the
conditions. Either
(i) All implementations of the mechanism are required to
capable of processing messages protected using any QOP value
regardless of whether they can apply protection corresponding
that QOP,
(ii) The set of mutually-supported 