RFC relevance of indicate

As per Relevance of the word indicate, we have this rfc below:

Network Working Group J.
Request for Comments: 1508 Geer Zolot
September 1993

Generic Security Service Application Program

Status of this

This RFC 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" for the standardization state and
of this protocol. Distribution of this memo is unlimited

This Generic Security Service Application Program Interface (GSS-API
definition provides security services to callers in a
fashion, supportable with a range of underlying mechanisms
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
be implemented in order to realize GSS-API services
particular security

Table of

1. GSS-API Characteristics and Concepts ....................... 2
1.1. GSS-API Constructs ....................................... 5
1.1.1. Credentials ........................................... 5
1.1.2. Tokens ................................................ 6
1.1.3. Security Contexts ..................................... 7
1.1.4. Mechanism Types ....................................... 8
1.1.5. Naming ................................................ 9
1.1.6. Channel Bindings ...................................... 10
1.2. GSS-API Features and Issues ............................. 11
1.2.1. Status Reporting ...................................... 11
1.2.2. Per-Message Security Service Availability ............. 12
1.2.3. Per-Message Replay Detection and Sequencing ........... 13
1.2.4. Quality of Protection ................................. 15

Linn [Page 1]

RFC 1508 Generic Security Interface September 1993

2. Interface Descriptions ..................................... 15
2.1. Credential management calls ............................. 17
2.1.1. GSS_Acquire_cred call ................................. 17
2.1.2. GSS_Release_cred call ................................. 19
2.1.3. GSS_Inquire_cred call ................................. 20
2.2. Context-level calls ..................................... 21
2.2.1. GSS_Init_sec_context call ............................. 21
2.2.2. GSS_Accept_sec_context call ........................... 26
2.2.3. GSS_Delete_sec_context call ........................... 29
2.2.4. GSS_Process_context_token call ........................ 30
2.2.5. GSS_Context_time call ................................. 31
2.3. Per-message calls ....................................... 32
2.3.1. GSS_Sign call ......................................... 32
2.3.2. GSS_Verify call ....................................... 33
2.3.3. GSS_Seal call ......................................... 35
2.3.4. GSS_Unseal call ....................................... 36
2.4. Support calls ........................................... 37
2.4.1. GSS_Display_status call ............................... 37
2.4.2. GSS_Indicate_mechs call ............................... 38
2.4.3. GSS_Compare_name call ................................. 38
2.4.4. GSS_Display_name call ................................. 39
2.4.5. GSS_Import_name call .................................. 40
2.4.6. GSS_Release_name call ................................. 41
2.4.7. GSS_Release_buffer call ............................... 41
2.4.8. GSS_Release_oid_set call .............................. 42
3. Mechanism-Specific Example Scenarios ....................... 42
3.1. Kerberos V5, single-TGT ................................. 43
3.2. Kerberos V5, double-TGT ................................. 43
3.3. X.509 Authentication Framework .......................... 44
4. Related Activities ......................................... 45
5. Acknowledgments ............................................ 46
6. Security Considerations .................................... 46
7. Author's Address ........................................... 46
Appendix A .................................................... 47
Appendix B .................................................... 48
Appendix C .................................................... 49

1. GSS-API Characteristics and

The operational paradigm in which GSS-API operates is as follows.
typical GSS-API caller is itself a communications protocol,
on GSS-API in order to protect its communications
authentication, integrity, and/or confidentiality security services
A GSS-API caller accepts tokens provided to it by its local GSS-
implementation and transfers the tokens to a peer on a remote system
that peer passes the received tokens to its local GSS-
implementation for processing. The security services
through GSS-API in this fashion are implementable (and have

Linn [Page 2]

RFC 1508 Generic Security Interface September 1993

implemented) over a range of underlying mechanisms based on secret
key and public-key cryptographic technologies

The GSS-API separates the operations of initializing a
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_Sign() and GSS_Verify() calls) for messages
transferred in conjunction with that context. Per-message GSS_Seal()
and GSS_Unseal() calls provide the data origin authentication
data integrity services which GSS_Sign() and GSS_Verify() offer,
also support selection of confidentiality services as a
option. Additional 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_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_COMPLETE status. The client sends the output_token to the server

The server passes the received token as the input_token parameter
GSS_Accept_sec_context(). GSS_Accept_sec_context
GSS_COMPLETE status, provides the client's authenticated identity
the src_name result, and provides an output_token to be passed to
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

Linn [Page 3]

RFC 1508 Generic Security Interface September 1993

included in the token in order to achieve mutual authentication
the client's viewpoint. This call to GSS_Init_sec_context()
GSS_COMPLETE status, indicating successful mutual authentication
the completion of context establishment for this example

The client generates a data message and passes it to GSS_Seal().
GSS_Seal() performs data origin authentication, data integrity,
(optionally) confidentiality processing on the message
encapsulates the result into output_message, indicating GSS_
status. The client sends the output_message to the server

The server passes the received message to GSS_Unseal(). GSS_
inverts the encapsulation performed by GSS_Seal(), deciphers
message if the optional confidentiality feature was applied,
validates the data origin authentication and data integrity
quantities. GSS_Unseal() indicates successful validation
returning GSS_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. GSS_Delete_sec_context() returns
context_token for the server to pass to the client

The client passes the returned context_token
GSS_Process_context_token(), which returns GSS_COMPLETE status
deleting context-level information at the client system

The GSS-API design assumes and addresses several basic goals
including

Mechanism independence: The GSS-API defines an interface
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'

Linn [Page 4]

RFC 1508 Generic Security Interface September 1993

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.

Credentials structures provide the prerequisites enabling peers
establish security contexts with each other. A caller may
that its default credential be used for context establishment
without presenting an explicit handle to that credential
Alternately, those GSS-API callers which need to make
selection of particular credentials structures may make references
those credentials through GSS-API-provided credential
("cred_handles").

A single credential structure may be used for initiation of
contexts and acceptance of inbound contexts. Callers needing
operate in only one of these modes may designate this fact
credentials are acquired for use, allowing underlying mechanisms
optimize their processing and storage requirements. The
elements defined by a particular mechanism may contain
cryptographic keys, e.g., to enable authentication and
encryption to be performed with different algorithms

A single credential structure may accommodate credential
associated with multiple underlying mechanisms (mech_types);
credential structure's contents will vary depending on the set
mech_types supported by a particular GSS-API implementation
Commonly, a single mech_type will be used for all security
established by a particular initiator to a particular target;
primary motivation for supporting credential sets
multiple mech_types is to allow initiators on systems which

Linn [Page 5]

RFC 1508 Generic Security Interface September 1993

equipped to handle multiple types to initiate contexts to targets
other systems which can accommodate only a subset of the
supported at the initiator's system

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

as the default credentials installed on behalf of a

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 are exchanged in conjunction with an established context
provide protective security services for corresponding data messages
The internal contents of both classes of tokens are specific to
particular underlying mechanism used to support the GSS-API;
B of this document provides a uniform recommendation for designers
GSS-API support mechanisms, encapsulating mechanism-
information along with a globally-interpretable mechanism identifier

Linn [Page 6]

RFC 1508 Generic Security Interface September 1993

Tokens are opaque from the viewpoint of GSS-API callers. They
generated within the GSS-API implementation at an end system
provided to a GSS-API caller to be transferred to the peer GSS-
caller at a remote end system, and processed by the GSS-
implementation at that remote end system. Tokens may be output
GSS-API primitives (and are to be transferred to GSS-API peers
independent of the status indications which those
indicate. Token transfer may take place in an in-band manner
integrated into the same protocol stream used by the GSS-API
for other data transfers, or in an out-of-band manner across
logically separate channel

Development of GSS-API support primitives based on a
underlying cryptographic technique and protocol does not
imply that GSS-API callers invoking that GSS-API mechanism type
be able to interoperate with peers invoking the same technique
protocol outside the GSS-API paradigm. For example, 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 the same as those used by non-GSS-API
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
features within GSS-API supporting mechanisms.) This
allows the GSS-API to be used in a wide range of

Linn [Page 7]

RFC 1508 Generic Security Interface September 1993

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

explicit negotiation between GSS-API callers in advance
security context

When transferred between GSS-API peers, mech_type specifiers (
Appendix B, represented as Object Identifiers (OIDs)) serve
qualify the interpretation of associated tokens. (The structure
encoding of Object Identifiers is defined in ISO/IEC 8824,
"Specification of Abstract Syntax Notation One (ASN.1)" and
ISO/IEC 8825, "Specification of Basic Encoding Rules for
Syntax Notation One (ASN.1)".) Use of hierarchically structured
serves to preclude ambiguous interpretation of mech_type specifiers

Linn [Page 8]

RFC 1508 Generic Security Interface September 1993

The OID representing the DASS MechType, for example,
1.3.12.2.1011.7.5.

1.1.5.

The GSS-API avoids prescription of naming structures, treating
names transferred across the interface in order to initiate
accept security contexts as opaque octet string quantities.
approach supports the GSS-API's goal of implementability atop a
of underlying security mechanisms, recognizing the fact
different mechanisms process and authenticate names which
presented in different forms. Generalized services
translation functions among arbitrary sets of naming environments
outside the scope of the GSS-API; availability and use of
conversion functions to translate among the naming formats
within a given end system is anticipated

Two distinct classes of name representations are used in
with different GSS-API parameters

a printable form (denoted by OCTET STRING), for acceptance
and presentation to users; printable name forms are accompanied
OID tags identifying the namespace to which they

an internal form (denoted by INTERNAL NAME), opaque to callers
defined by individual GSS-API implementations; GSS-
implementations supporting multiple namespace types
responsible for maintaining internal tags to disambiguate
interpretation of particular

Tagging of printable names allows GSS-API callers and
GSS-API mechanisms to disambiguate name types and to
whether an associated name's type is one which they are capable
processing, avoiding aliasing problems which could result
misinterpreting a name of one type as a name of another type

In addition to providing means for names to be tagged with types
this specification defines primitives to support a level of
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()), and internal name
(GSS_Release_name()) functions are defined. (It is anticipated
these proposed GSS-API calls will be implemented in many end
based on system-specific name manipulation primitives already
within those end systems; inclusion within the GSS-API is intended

Linn [Page 9]

RFC 1508 Generic Security Interface September 1993

offer GSS-API callers a portable means to perform
operations, supportive of authorization and audit requirements,
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

1.1.6. Channel

The GSS-API accommodates the concept of caller-provided
binding ("chan_binding") information, used by GSS-API callers to
the establishment of a security context to relevant
(e.g., addresses, transformed representations of encryption keys)
the underlying communications channel and of protection
applied to that communications channel. Verification by one peer
chan_binding information provided by the other peer to a
serves to protect against various active attacks. The
initiating a security context must determine the chan_binding
before making the GSS_Init_sec_context() call, and consistent
must be provided by both peers to a context. Callers should
assume that underlying mechanisms provide confidentiality
for channel binding information

Use or non-use of the GSS-API channel binding facility is a
option, and GSS-API supporting mechanisms can support operation in
environment where NULL channel bindings are presented. When non-
channel bindings are used, certain mechanisms will offer
security value by interpreting the bindings' content (rather
simply representing those bindings, or signatures computed on them
within tokens) and will therefore depend on presentation of
data in a defined format. To this end, agreements among
implementors are defining conventional interpretations for
contents of channel binding arguments, including address
(with content dependent on communications protocol environment)
context initiators and acceptors. (These conventions are
incorporated into related documents.) In order for GSS-API callers
be portable across multiple mechanisms and achieve the full
functionality available from each mechanism, it is
recommended that GSS-API callers provide channel bindings

Linn [Page 10]

RFC 1508 Generic Security Interface September 1993

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_COMPLETE, GSS_FAILURE, GSS_CONTINUE_NEEDED), sufficient
drive normal control flow within the caller in a generic fashion
Table 1 summarizes the defined major_status return codes in
fashion

Table 1: GSS-API Major Status

FATAL ERROR

GSS_BAD_BINDINGS channel binding
GSS_BAD_MECH unsupported mechanism
GSS_BAD_NAME invalid name
GSS_BAD_NAMETYPE name of unsupported type
GSS_BAD_STATUS invalid input status
GSS_BAD_SIG token had invalid
GSS_CONTEXT_EXPIRED specified security context
GSS_CREDENTIALS_EXPIRED expired credentials
GSS_DEFECTIVE_CREDENTIAL defective credential
GSS_DEFECTIVE_TOKEN defective token
GSS_FAILURE failure, unspecified at GSS-

GSS_NO_CONTEXT no valid security context
GSS_NO_CRED no valid credentials

INFORMATORY STATUS

GSS_COMPLETE normal
GSS_CONTINUE_NEEDED continuation call to

GSS_DUPLICATE_TOKEN duplicate per-message

GSS_OLD_TOKEN timed-out per-message

GSS_UNSEQ_TOKEN out-of-order per-message

Linn [Page 11]

RFC 1508 Generic Security Interface September 1993

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_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 accomodated
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_Sign() or GSS_Seal() primitives on
associated context will apply no cryptographic protection to
data messages

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_Seal(), encapsulate the protected data unit

Linn [Page 12]

RFC 1508 Generic Security Interface September 1993

As such, these primitives are not oriented to efficient
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 are expected to offer support
replay detection and/or sequencing of messages transferred on
contexts they support. These optionally-selectable
features are distinct from replay detection and sequencing
applied to the context establishment operation itself; the
or absence of context-level replay or sequencing features is wholly
function of the underlying mech_type's capabilities, and is
selected or omitted 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_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

2. GSS_DUPLICATE_TOKEN indicates that the signature on
received message was correct, but that the message was
as a duplicate of a previously-processed message

3. GSS_OLD_TOKEN indicates that the signature on the
message was correct, but that the message is too old to be
for duplication

Linn [Page 13]

RFC 1508 Generic Security Interface September 1993

When sequence_state is TRUE, the possible major_status returns
well-formed and correctly signed messages are as follows

1. GSS_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

2. GSS_DUPLICATE_TOKEN indicates that the signature on
received message was correct, but that the message was
as a duplicate of a previously-processed message

3. GSS_OLD_TOKEN indicates that the signature on the
message was correct, but that the token is too old to be
for duplication

4. GSS_UNSEQ_TOKEN indicates that the signature on the
message was correct, but that it is earlier in a sequenced
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.]

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_Sign() and GSS_Seal(), and would maintain (within a time
limited window) a cache (qualified by originator-recipient pair
identifying received data elements processed by GSS_Verify()

Linn [Page 14]

RFC 1508 Generic Security Interface September 1993

GSS_Unseal(). When this feature is active, exception status
(GSS_DUPLICATE_TOKEN, GSS_ OLD_TOKEN) will be provided
GSS_Verify() or GSS_Unseal() 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 will provide their users with fine
control over the means used to provide per-message protection
allowing callers to trade off security processing
dynamically against the protection requirements of
messages. A per-message quality-of-protection parameter (analogous
quality-of-service, or QOS) selects among different QOP
supported by that mechanism. On context establishment for a multi-
mech_type, context-level data provides the prerequisite data for
range of protection 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

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
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

Linn [Page 15]

RFC 1508 Generic Security Interface September 1993

Table 2: GSS-API

CREDENTIAL

GSS_Acquire_cred acquire credentials for
GSS_Release_cred release credentials after
GSS_Inquire_cred display information

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

PER-MESSAGE

GSS_Sign apply signature, receive as
separate from
GSS_Verify validate signature token along

GSS_Seal sign, optionally encrypt

GSS_Unseal decapsulate, decrypt if needed
validate

SUPPORT

GSS_Display_status translate status codes to

GSS_Indicate_mechs indicate mech_types supported
local
GSS_Compare_name compare two names for
GSS_Display_name translate name to printable
GSS_Import_name convert printable name
normalized
GSS_Release_name free storage of normalized-

GSS_Release_buffer free storage of printable
GSS_Release_oid_set free storage of OID set

Linn [Page 16]

RFC 1508 Generic Security Interface September 1993

2.1. Credential management

These GSS-API calls provide functions related to the management
credentials. Their characterization with regard to whether or
they may block pending exchanges with other network entities (e.g.,
directories or authentication servers) depends in part on OS-
(extra-GSS-API) issues, so is not specified in this document

The GSS_Acquire_cred() call is defined within the GSS-API in
of application portability, with a particular orientation
support of portable server applications. It is recognized that (
certain systems and mechanisms) credentials for interactive users
be managed differently from credentials for server processes; in
environments, it is the GSS-API implementation's responsibility
distinguish these cases and the procedures for making
distinction are a local matter. The GSS_Release_cred() call
a means for callers to indicate to the GSS-API that use of
credentials structure is no longer required. The GSS_Inquire_cred()
call allows callers to determine information about a
structure

2.1.1. GSS_Acquire_cred

Inputs

o desired_name INTERNAL NAME, -NULL requests locally-

o lifetime_req INTEGER,-in seconds; 0 requests

o desired_mechs SET OF OBJECT IDENTIFIER,-empty set
system-selected

o cred_usage INTEGER-0=INITIATE-AND-ACCEPT, 1=INITIATE-ONLY
2=ACCEPT-

Outputs

o major_status INTEGER

o minor_status INTEGER

o output_cred_handle OCTET STRING

o actual_mechs SET OF OBJECT IDENTIFIER

o lifetime_rec INTEGER -in seconds, or reserved value

Linn [Page 17]

RFC 1508 Generic Security Interface September 1993

Return major_status codes

o GSS_COMPLETE indicates that requested credentials
successfully established, for the duration indicated
lifetime_rec, suitable for the usage requested in cred_usage,
the set of mech_types indicated in actual_mechs, and that
credentials can be referenced for subsequent use with the
returned in output_cred_handle

o GSS_BAD_MECH indicates that a mech_type unsupported by the GSS-
implementation type was requested, causing the
establishment operation to fail

o GSS_BAD_NAMETYPE indicates that the provided desired_name
uninterpretable or of a type unsupported by the supporting GSS-
implementation, so no credentials could be established for
accompanying desired_name

o GSS_BAD_NAME indicates that the provided desired_name
inconsistent in terms of internally-incorporated type
information, so no credentials could be established for
accompanying desired_name

o GSS_FAILURE indicates that credential establishment failed
reasons unspecified at the GSS-API level, including lack
authorization to establish and use credentials associated with
identity named in the input desired_name argument

GSS_Acquire_cred() is used to acquire credentials so that
principal can (as a function of the input cred_usage parameter
initiate and/or accept security contexts under the
represented by the desired_name input argument. On
completion, the returned output_cred_handle result provides a
for subsequent references to the acquired credentials. Typically
single-user client processes using only default credentials
context establishment purposes will have no need to invoke this call

A caller may provide the value NULL for desired_name, signifying
request for credentials corresponding to a default
identity. The procedures used by GSS-API implementations to
the appropriate principal identity in response to this form
request are local matters. It is possible that multiple pre
established credentials may exist for the same principal
(for example, as a result of multiple user login sessions)
GSS_Acquire_cred() is called; the means used in such cases to
a specific credential are local matters. The input lifetime_
argument to GSS_Acquire_cred() may provide useful information
local GSS-API implementations to employ in making this

Linn [Page 18]

RFC 1508 Generic Security Interface September 1993

in a manner which will best satisfy a caller's intent

The lifetime_rec result indicates the length of time for which
acquired credentials will be valid, as an offset from the present.
mechanism may return a reserved value indicating INDEFINITE if
constraints on credential lifetime are imposed. A caller
GSS_Acquire_cred() can request a length of time for which
credentials are to be valid (lifetime_req argument), beginning at
present, or can request credentials with a default validity interval
(Requests for postdated credentials are not supported within
GSS-API.) Certain mechanisms and implementations may bind
credential validity period specifiers at a point preliminary
invocation of the GSS_Acquire_cred() call (e.g., in conjunction
user login procedures). As a result, callers requesting non-
values for lifetime_req must recognize that such requests
always be honored and must be prepared to accommodate the use
returned credentials with different lifetimes as indicated
lifetime_rec

The caller of GSS_Acquire_cred() can explicitly specify a set
mech_types which are to be accommodated in the returned
(desired_mechs argument), or can request credentials for a system
defined default set of mech_types. Selection of the system-
default set is recommended in the interests of
portability. The actual_mechs return value may be interrogated by
caller to determine the set of mechanisms with which the
credentials may be used

2.1.2. GSS_Release_cred

Input

o cred_handle OCTET STRING-NULL specifies default

Outputs

o major_status INTEGER

o minor_status

Return major_status codes

o GSS_COMPLETE indicates that the credentials referenced by
input cred_handle were released for purposes of subsequent
by the caller. The effect on other processes which may
authorized shared access to such credentials is a local matter

Linn [Page 19]

RFC 1508 Generic Security Interface September 1993

o GSS_NO_CRED indicates that no release operation was performed
either because the input cred_handle was invalid or because
caller lacks authorization to access the referenced credentials

o GSS_FAILURE indicates that the release operation failed
reasons unspecified at the GSS-API level

Provides a means for a caller to explicitly request that
be released when their use is no longer required. Note that system
specific credential management functions are also likely to exist
for example to assure that credentials shared among processes
properly deleted when all affected processes terminate, even if
explicit release requests are issued by those processes. Given
fact that multiple callers are not precluded from gaining
access to the same credentials, invocation of GSS_Release_cred()
cannot be assumed to delete a particular set of credentials on
system-wide basis

2.1.3. GSS_Inquire_cred

Input

o cred_handle OCTET STRING -NULL specifies default

Outputs

o major_status INTEGER

o minor_status INTEGER

o cred_name INTERNAL NAME

o lifetime_rec INTEGER -in seconds, or reserved value

o cred_usage INTEGER, -0=INITIATE-AND-ACCEPT, 1=INITIATE-ONLY
2=ACCEPT-

o mech_set SET OF OBJECT

Return major_status codes

o GSS_COMPLETE indicates that the credentials referenced by
input cred_handle argument were valid, and that the
cred_name, lifetime_rec, and cred_usage values represent
respectively, the credentials' associated principal name
remaining lifetime, suitable usage modes, and
mechanism types

Linn [Page 20]

RFC 1508 Generic Security Interface September 1993

o GSS_NO_CRED indicates that no information could be
about the referenced credentials, either because the
cred_handle was invalid or because the caller
authorization to access the referenced credentials

o GSS_FAILURE indicates that the release operation failed
reasons unspecified at the GSS-API level

The GSS_Inquire_cred() call is defined primarily for the use
those callers which make use of default credentials rather
acquiring credentials explicitly with GSS_Acquire_cred(). It
callers to determine a credential structure's associated
name, remaining validity period, usability for security
initiation and/or acceptance, and supported mechanisms

2.2. Context-level

This group of calls is devoted to the establishment and management
security contexts between peers. A context's initiator
GSS_Init_sec_context(), resulting in generation of a token which
caller passes to the target. At the target, that token is passed
GSS_Accept_sec_context(). Depending on the underlying mech_type
specified options, additional token exchanges may be performed in
course of context establishment; such exchanges are accommodated
GSS_CONTINUE_NEEDED status returns from GSS_Init_sec_context()
GSS_Accept_sec_context(). Either party to an established context
invoke GSS_Delete_sec_context() to flush context information when
context is no longer required. GSS_Process_context_token() is
to process received tokens carrying context-level
information. GSS_Context_time() allows a caller to determine
length of time for which an established context will remain valid

2.2.1. GSS_Init_sec_context

Inputs

o claimant_cred_handle OCTET STRING, -NULL specifies "
default

o input_context_handle INTEGER, -0 specifies "none
yet

o targ_name INTERNAL NAME

o mech_type OBJECT IDENTIFIER, -NULL parameter specifies "
default

o deleg_req_flag BOOLEAN

Linn [Page 21]

RFC 1508 Generic Security Interface September 1993

o mutual_req_flag BOOLEAN

o replay_det_req_flag BOOLEAN

o sequence_req_flag BOOLEAN

o lifetime_req INTEGER,-0 specifies default

o chan_bindings OCTET STRING

o input_token OCTET STRING-NULL or token received from

Outputs

o major_status INTEGER

o minor_status INTEGER

o output_context_handle INTEGER

o mech_type OBJECT IDENTIFIER, -actual mechanism
indicated, never

o output_token OCTET STRING, -NULL or token to pass to

o deleg_state BOOLEAN

o mutual_state BOOLEAN

o replay_det_state BOOLEAN

o sequence_state BOOLEAN

o conf_avail BOOLEAN

o integ_avail BOOLEAN

o lifetime_rec INTEGER - in seconds, or reserved value

This call may block pending network interactions for those mech_
in which an authentication server or other network entity must
consulted on behalf of a context initiator in order to generate
output_token suitable for presentation to a specified target

Return major_status codes

Linn [Page 22]

RFC 1508 Generic Security Interface September 1993

o GSS_COMPLETE indicates that context-level information
successfully initialized, and that the returned output_token
provide sufficient information for the target to perform per
message processing on the newly-established context

o GSS_CONTINUE_NEEDED indicates that control information in
returned output_token must be sent to the target, and that a
must be received and passed as the input_token argument to
continuation call to GSS_Init_sec_context(), before per-
processing can be performed in conjunction with this context

o GSS_DEFECTIVE_TOKEN indicates that consistency checks performed
the input_token failed, preventing further processing from
performed based on that token

o GSS_DEFECTIVE_CREDENTIAL indicates that consistency
performed on the credential structure referenced
claimant_cred_handle failed, preventing further processing
being performed using that credential structure

o GSS_BAD_SIG indicates that the received input_token contains
incorrect signature, so context setup cannot be accomplished

o GSS_NO_CRED indicates that no context was established,
because the input cred_handle was invalid, because the
credentials are valid for context acceptor use only, or
the caller lacks authorization to access the
credentials

o GSS_CREDENTIALS_EXPIRED indicates that the credentials
through the input claimant_cred_handle argument are no
valid, so context establishment cannot be completed

o GSS_BAD_BINDINGS indicates that a mismatch between the caller
provided chan_bindings and those extracted from the input_
was detected, signifying a security-relevant event and
context establishment. (This result will be returned
GSS_Init_sec_context only for contexts where mutual_state
TRUE.)

o GSS_NO_CONTEXT indicates that no valid context was recognized
the input context_handle provided; this major status will
returned only for successor calls following GSS_CONTINUE_
status returns

o GSS_BAD_NAMETYPE indicates that the provided targ_name is of
type uninterpretable or unsupported by the supporting GSS-
implementation, so context establishment cannot be completed

Linn [Page 23]

RFC 1508 Generic Security Interface September 1993

o GSS_BAD_NAME indicates that the provided targ_name is
in terms of internally-incorporated type specifier information,
context establishment cannot be accomplished

o GSS_FAILURE indicates that context setup could not be
for reasons unspecified at the GSS-API level, and that
interface-defined recovery action is available

This routine is used by a context initiator, and ordinarily emits
(or, for the case of a multi-step exchange, more than one
output_token suitable for use by the target within the
mech_type's protocol. Using information in the credentials
referenced by claimant_cred_handle, GSS_Init_sec_context()
initializes the data structures required to establish a
context with target targ_name. The claimant_cred_handle
correspond to the same valid credentials structure on the
call to GSS_Init_sec_context() and on any successor calls
from GSS_CONTINUE_NEEDED status returns; different protocol
modeled by the GSS_CONTINUE_NEEDED mechanism will require access
credentials at different points in the context
sequence

The input_context_handle argument is 0, specifying "not
assigned", on the first GSS_Init_sec_context() call relating to
given context. That call returns an output_context_handle for
references to this context. When continuation attempts
GSS_Init_sec_context() are needed to perform context establishment
the previously-returned non-zero handle value is entered into
input_context_handle argument and will be echoed in the
output_context_handle argument. On such continuation attempts (
only on continuation attempts) the input_token value is used,
provide the token returned from the context's target

The chan_bindings argument is used by the caller to
information binding the security context to security-
characteristics (e.g., addresses, cryptographic keys) of
underlying communications channel. See Section 1.1.6 of this
for more discussion of this argument's usage

The input_token argument contains a message received from the target
and is significant only on a call to GSS_Init_sec_context()
follows a previous return indicating GSS_CONTINUE_
major_status

It is the caller's responsibility to establish a communications
to the target, and to transmit any returned output_token (
of the accompanying returned major_status value) to the target
that path. The output_token can, however, be transmitted along

Linn [Page 24]

RFC 1508 Generic Security Interface September 1993

the first application-provided input message to be processed
GSS_Sign() or GSS_Seal() in conjunction with a successfully
established context

The initiator may request various context-level functions
input flags: the deleg_req_flag requests delegation of access rights
the mutual_req_flag requests mutual authentication,
replay_det_req_flag requests that replay detection features
applied to messages transferred on the established context, and
sequence_req_flag requests that sequencing be enforced. (See
1.2.3 for more information on replay detection and
features.)

Not all of the optionally-requestable features will be available
all underlying mech_types; the corresponding return state
(deleg_state, mutual_state, replay_det_state, sequence_state
indicate, as a function of mech_type processing capabilities
initiator-provided input flags, the set of features which will
active on the context. These state indicators' values are
unless the routine's major_status indicates COMPLETE. Failure
provide the precise set of features requested by the caller does
cause context establishment to fail; it is the caller's
to delete the context if the feature set provided is unsuitable
the caller's use. The returned mech_type value indicates
specific mechanism employed on the context, and will never
the value for "default".

The conf_avail return value indicates whether the context
per-message confidentiality services, and so informs the
whether or not a request for encryption through the conf_req_
input to GSS_Seal() can be honored. In similar fashion,
integ_avail return value indicates whether per-message
services are available (through either GSS_Sign() or GSS_Seal())
the established context

The lifetime_req input specifies a desired upper bound for
lifetime of the context to be established, with a value of 0 used
request a default lifetime. The lifetime_rec return value
the length of time for which the context will be valid, expressed
an offset from the present; depending on mechanism capabilities
credential lifetimes, and local policy, it may not correspond to
value re