protection for stream-paradigm protocols (e.g., Telnet) if
cryptography must be applied on an octet-by-octet basis.
1.2.3: Per-Message Replay Detection and Sequencing
Certain underlying mech_types offer support for replay detection
and/or sequencing of messages transferred on the contexts they
support. These optionally-selectable protection features are distinct
from replay detection and sequencing features applied to the context
establishment operation itself; the presence or absence of context-
level replay or sequencing features is wholly a function of the
underlying mech_type's capabilities, and is not selected or omitted
as a caller option.
The caller initiating a context provides flags (replay_det_req_flag
and sequence_req_flag) to specify whether the use of per-message
replay detection and sequencing features is desired on the context
being established. The GSS-API implementation at the initiator system
can determine whether these features are supported (and whether they
are optionally selectable) as a function of the selected mechanism,
without need for bilateral negotiation with the target. When enabled,
these features provide recipients with indicators as a result of
GSS-API processing of incoming messages, identifying whether those
messages were detected as duplicates or out-of-sequence. Detection of
such events does not prevent a suspect message from being provided to
a recipient; the appropriate course of action on a suspect message is
a matter of caller policy.
The semantics of the replay detection and sequencing services applied
to received messages, as visible across the interface which the GSS-
API provides to its clients, are as follows:
When replay_det_state is TRUE, the possible major_status returns for
well-formed and correctly signed messages are as follows:
1. GSS_S_COMPLETE, without concurrent indication of
GSS_S_DUPLICATE_TOKEN or GSS_S_OLD_TOKEN, indicates that the
message was within the window (of time or sequence space) allowing
replay events to be detected, and that the message was not a
replay of a previously-processed message within that window.
2. GSS_S_DUPLICATE_TOKEN indicates that the cryptographic
checkvalue on the received message was correct, but that the
message was recognized as a duplicate of a previously-processed
message. In addition to identifying duplicated tokens originated
by a context's peer, this status may also be used to identify
reflected copies of locally-generated tokens; it is recommended
that mechanism designers include within their protocols facilities
to detect and report such tokens.
3. GSS_S_OLD_TOKEN indicates that the cryptographic checkvalue on
the received message was correct, but that the message is too old
to be checked for duplication.
When sequence_state is TRUE, the possible major_status returns for
well-formed and correctly signed messages are as follows:
1. GSS_S_COMPLETE, without concurrent indication of
GSS_S_DUPLICATE_TOKEN, GSS_S_OLD_TOKEN, GSS_S_UNSEQ_TOKEN, or
GSS_S_GAP_TOKEN, indicates that the message was within the window
(of time or sequence space) allowing replay events to be detected,
that the message was not a replay of a previously-processed
message within that window, and that no predecessor sequenced
messages are missing relative to the last received message (if
any) processed on the context with a correct cryptographic
checkvalue.
2. GSS_S_DUPLICATE_TOKEN indicates that the integrity check value
on the received message was correct, but that the message was
recognized as a duplicate of a previously-processed message. In
addition to identifying duplicated tokens originated by a
context's peer, this status may also be used to identify reflected
copies of locally-generated tokens; it is recommended that
mechanism designers include within their protocols facilities to
detect and report such tokens.
3. GSS_S_OLD_TOKEN indicates that the integrity check value on the
received message was correct, but that the token is too old to be
checked for duplication.
4. GSS_S_UNSEQ_TOKEN indicates that the cryptographic checkvalue
on the received message was correct, but that it is earlier in a
sequenced stream than a message already processed on the context.
[Note: Mechanisms can be architected to provide a stricter form of
sequencing service, delivering particular messages to recipients
only after all predecessor messages in an ordered stream have been
delivered. This type of support is incompatible with the GSS-API
paradigm in which recipients receive all messages, whether in
order or not, and provide them (one at a time, without intra-GSS-
API message buffering) to GSS-API routines for validation. GSS-
API facilities provide supportive functions, aiding clients to
achieve strict message stream integrity in an efficient manner in
conjunction with sequencing provisions in communications
protocols, but the GSS-API does not offer this level of message
stream integrity service by itself.]
5. GSS_S_GAP_TOKEN indicates that the cryptographic checkvalue on
the received message was correct, but that one or more predecessor
sequenced messages have not been successfully processed relative
to the last received message (if any) processed on the context
with a correct cryptographic checkvalue.
As the message stream integrity features (especially sequencing) may
interfere with certain applications' intended communications
paradigms, and since support for such features is likely to be
resource intensive, it is highly recommended that mech_types
supporting these features allow them to be activated selectively on
initiator request when a context is established. A context initiator
and target are provided with corresponding indicators
(replay_det_state and sequence_state), signifying whether these
features are active on a given context.
An example mech_type supporting per-message replay detection could
(when replay_det_state is TRUE) implement the feature as follows: The
underlying mechanism would insert timestamps in data elements output
by GSS_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() and
GSS_Unwrap(). When this feature is active, exception status returns
(GSS_S_DUPLICATE_TOKEN, GSS_S_OLD_TOKEN) will be provided when
GSS_VerifyMIC() or GSS_Unwrap() is presented with a message which is
either a detected duplicate of a prior message or which is too old to
validate against a cache of recently received messages.
1.2.4: Quality of Protection
Some mech_types provide their users with fine granularity control
over the means used to provide per-message protection, allowing
callers to trade off security processing overhead dynamically against
the protection requirements of particular messages. A per-message
quality-of-protection parameter (analogous to quality-of-service, or
QOS) selects among different QOP options supported by that mechanism.
On context establishment for a multi-QOP mech_type, context-level
data provides the prerequisite data for a range of protection
qualities.
It is expected that the majority of callers will not wish to exert
explicit mechanism-specific QOP control and will therefore request
selection of a default QOP. Definitions of, and choices among, non-
default QOP values are mechanism-specific, and no ordered sequences
of QOP values can be assumed equivalent across different mechanisms.
Meaningful use of non-default QOP values demands that callers be
familiar with the QOP definitions of an underlying mechanism or
mechanisms, and is therefore a non-portable construct. The
GSS_S_BAD_QOP major_status value is defined in order to indicate that
a provided QOP value is unsupported for a security context, most
likely because that value is unrecognized by the underlying
mechanism.
In the interests of interoperability, mechanisms which allow optional
support of particular QOP values shall satisfy one of the following
conditions. Either:
(i) All implementations of the mechanism are required to be
capable of processing messages protected using any QOP value,
regardless of whether they can apply protection corresponding to
that QOP, or
(ii) The set of mutually-supported receiver QOP values must be
determined during context establishment, and messages may be
protected by either peer using only QOP values from this
mutually-supported set.
NOTE: (i) is just a special-case of (ii), where implementations are
required to support all QOP values on receipt.
1.2.5: Anonymity Support
In certain situations or environments, an application may wish to
authenticate a peer and/or protect communications using GSS-API per-
message services without revealing its own identity. For example,
consider an application which provides read access to a research
database, and which permits queries by arbitrary requestors. A
client of such a service might wish to authenticate the service, to
establish trust in the information received from it, but might not
wish to disclose its identity to the service for privacy reasons.
In ordinary GSS-API usage, a context initiator's identity is made
available to the context acceptor as part of the context
establishment process. To provide for anonymity support, a facility
(input anon_req_flag to GSS_Init_sec_context()) is provided through
which context initiators may request that their identity not be
provided to the context acceptor. Mechanisms are not required to
honor this request, but a caller will be informed (via returned
anon_state indicator from GSS_Init_sec_context()) whether or not the
request is honored. Note that authentication as the anonymous
principal does not necessarily imply that credentials are not
required in order to establish a context.
Section 4.5 of this document defines the Object Identifier value used
to identify an anonymous principal.
Four possible combinations of anon_state and mutual_state are
possible, with the following results:
anon_state == FALSE, mutual_state == FALSE: initiator
authenticated to target.
anon_state == FALSE, mutual_state == TRUE: initiator authenticated
to target, target authenticated to initiator.
anon_state == TRUE, mutual_state == FALSE: initiator authenticated
as anonymous principal to target.
anon_state == TRUE, mutual_state == TRUE: initiator authenticated
as anonymous principal to target, target authenticated to
initiator.
1.2.6: Initialization
No initialization calls (i.e., calls which must be invoked prior to
invocation of other facilities in the interface) are defined in GSS-
API. As an implication of this fact, GSS-API implementations must
themselves be self-initializing.
1.2.7: Per-Message Protection During Context Establishment
A facility is defined in GSS-V2 to enable protection and buffering of
data messages for later transfer while a security context's
establishment is in GSS_S_CONTINUE_NEEDED status, to be used in cases
where the caller side already possesses the necessary session key to
enable this processing. Specifically, a new state Boolean, called
prot_ready_state, is added to the set of information returned by
GSS_Init_sec_context(), GSS_Accept_sec_context(), and
GSS_Inquire_context().
For context establishment calls, this state Boolean is valid and
interpretable when the associated major_status is either
GSS_S_CONTINUE_NEEDED, or GSS_S_COMPLETE. Callers of GSS-API (both
initiators and acceptors) can assume that per-message protection (via
GSS_Wrap(), GSS_Unwrap(), GSS_GetMIC() and GSS_VerifyMIC()) is
available and ready for use if either: prot_ready_state == TRUE, or
major_status == GSS_S_COMPLETE, though mutual authentication (if
requested) cannot be guaranteed until GSS_S_COMPLETE is returned.
Callers making use of per-message protection services in advance of
GSS_S_COMPLETE status should be aware of the possibility that a
subsequent context establishment step may fail, and that certain
context data (e.g., mech_type) as returned for subsequent calls may
change.
This approach achieves full, transparent backward compatibility for
GSS-API V1 callers, who need not even know of the existence of
prot_ready_state, and who will get the expected behavior from
GSS_S_COMPLETE, but who will not be able to use per-message
protection before GSS_S_COMPLETE is returned.
It is not a requirement that GSS-V2 mechanisms ever return TRUE
prot_ready_state before completion of context establishment (indeed,
some mechanisms will not evolve usable message protection keys,
especially at the context acceptor, before context establishment is
complete). It is expected but not required that GSS-V2 mechanisms
will return TRUE prot_ready_state upon completion of context
establishment if they support per-message protection at all (however
GSS-V2 applications should not assume that TRUE prot_ready_state will
always be returned together with the GSS_S_COMPLETE major_status,
since GSS-V2 implementations may continue to support GSS-V1 mechanism
code, which will never return TRUE prot_ready_state).
When prot_ready_state is returned TRUE, mechanisms shall also set
those context service indicator flags (deleg_state, mutual_state,
replay_det_state, sequence_state, anon_state, trans_state,
conf_avail, integ_avail) which represent facilities confirmed, at
that time, to be available on the context being established. In
situations where prot_ready_state is returned before GSS_S_COMPLETE,
it is possible that additional facilities may be confirmed and
subsequently indicated when GSS_S_COMPLETE is returned.
1.2.8: Implementation Robustness
This section recommends aspects of GSS-API implementation behavior in
the interests of overall robustness.
Invocation of GSS-API calls is to incur no undocumented side effects
visible at the GSS-API level.
If a token is presented for processing on a GSS-API security context
and that token generates a fatal error in processing or is otherwise
determined to be invalid for that context, the context's state should
not be disrupted for purposes of processing subsequent valid tokens.
Certain local conditions at a GSS-API implementation (e.g.,
unavailability of memory) may preclude, temporarily or permanently,
the successful processing of tokens on a GSS-API security context,
typically generating GSS_S_FAILURE major_status returns along with
locally-significant minor_status. For robust operation under such
conditions, the following recommendations are made:
Failing calls should free any memory they allocate, so that
callers may retry without causing further loss of resources.
Failure of an individual call on an established context should not
preclude subsequent calls from succeeding on the same context.
Whenever possible, it should be possible for
GSS_Delete_sec_context() calls to be successfully processed even
if other calls cannot succeed, thereby enabling context-related
resources to be released.
A failure of GSS_GetMIC() or GSS_Wrap() due to an attempt to use an
unsupported QOP will not interfere with context validity, nor shall
such a failure impact the ability of the application to subsequently
invoke GSS_GetMIC() or GSS_Wrap() using a supported QOP. Any state
information concerning sequencing of outgoing messages shall be
unchanged by an unsuccessful call of GSS_GetMIC() or GSS_Wrap().
1.2.9: Delegation
The GSS-API allows delegation to be controlled by the initiating
application via a Boolean parameter to GSS_Init_sec_context(), the
routine that establishes a security context. Some mechanisms do not
support delegation, and for such mechanisms attempts by an
application to enable delegation are ignored.
The acceptor of a security context for which the initiator enabled
delegation will receive (via the delegated_cred_handle parameter of
GSS_Accept_sec_context()) a credential handle that contains the
delegated identity, and this credential handle may be used to
initiate subsequent GSS-API security contexts as an agent or delegate
of the initiator. If the original initiator's identity is "A" and
the delegate's identity is "B", then, depending on the underlying
mechanism, the identity embodied by the delegated credential may be
either "A" or "B acting for A".
For many mechanisms that support delegation, a simple Boolean does
not provide enough control. Examples of additional aspects of
delegation control that a mechanism might provide to an application
are duration of delegation, network addresses from which delegation
is valid, and constraints on the tasks that may be performed by a
delegate. Such controls are presently outside the scope of the GSS-
API. GSS-API implementations supporting mechanisms offering
additional controls should provide extension routines that allow
these controls to be exercised (perhaps by modifying the initiator's
GSS-API credential prior to its use in establishing a context).
However, the simple delegation control provided by GSS-API should
always be able to over-ride other mechanism-specific delegation
controls; if the application instructs GSS_Init_sec_context() that
delegation is not desired, then the implementation must not permit
delegation to occur. This is an exception to the general rule that a
mechanism may enable services even if they are not requested;
delegation may only be provided at the explicit request of the
application.
1.2.10: Interprocess Context Transfer
GSS-API V2 provides routines (GSS_Export_sec_context() and
GSS_Import_sec_context()) which allow a security context to be
transferred between processes on a single machine. The most common
use for such a feature is a client-server design where the server is
implemented as a single process that accepts incoming security
contexts, which then launches child processes to deal with the data
on these contexts. In such a design, the child processes must have
access to the security context data structure created within the
parent by its call to GSS_Accept_sec_context() so that they can use
per-message protection services and delete the security context when
the communication session ends.
Since the security context data structure is expected to contain
sequencing information, it is impractical in general to share a
context between processes. Thus GSS-API provides a call
(GSS_Export_sec_context()) that the process which currently owns the
context can call to declare that it has no intention to use the
context subsequently, and to create an inter-process token containing
information needed by the adopting process to successfully import the
context. After successful completion of this call, the original
security context is made inaccessible to the calling process by GSS-
API, and any context handles referring to this context are no longer
valid. The originating process transfers the inter-process token to
the adopting process, which passes it to GSS_Import_sec_context(),
and a fresh context handle is created such that it is functionally
identical to the original context.
The inter-process token may contain sensitive data from the original
security context (including cryptographic keys). Applications using
inter-process tokens to transfer security contexts must take
appropriate steps to protect these tokens in transit.
Implementations are not required to support the inter-process
transfer of security contexts. The ability to transfer a security
context is indicated when the context is created, by
GSS_Init_sec_context() or GSS_Accept_sec_context() indicating a TRUE
trans_state return value.
2: Interface Descriptions
This section describes the GSS-API's service interface, dividing the
set of calls offered into four groups. Credential management calls
are related to the acquisition and release of credentials by
principals. Context-level calls are related to the management of
security contexts between principals. Per-message calls are related
to the protection of individual messages on established security
contexts. Support calls provide ancillary functions useful to GSS-API
callers. Table 2 groups and summarizes the calls in tabular fashion.
Table 2: GSS-API Calls
CREDENTIAL MANAGEMENT
GSS_Acquire_cred acquire credentials for use
GSS_Release_cred release credentials after use
GSS_Inquire_cred display information about
credentials
GSS_Add_cred construct credentials incrementally
GSS_Inquire_cred_by_mech display per-mechanism credential
information
CONTEXT-LEVEL CALLS
GSS_Init_sec_context initiate outbound security context
GSS_Accept_sec_context accept inbound security context
GSS_Delete_sec_context flush context when no longer needed
GSS_Process_context_token process received control token on
context
GSS_Context_time indicate validity time remaining on
context
GSS_Inquire_context display information about context
GSS_Wrap_size_limit determine GSS_Wrap token size limit
GSS_Export_sec_context transfer context to other process
GSS_Import_sec_context import transferred context
PER-MESSAGE CALLS
GSS_GetMIC apply integrity check, receive as
token separate from message
GSS_VerifyMIC validate integrity check token
along with message
GSS_Wrap sign, optionally encrypt,
encapsulate
GSS_Unwrap decapsulate, decrypt if needed,
validate integrity check
SUPPORT CALLS
GSS_Display_status translate status codes to printable
form
GSS_Indicate_mechs indicate mech_types supported on
local system
GSS_Compare_name compare two names for equality
GSS_Display_name translate name to printable form
GSS_Import_name convert printable name to
normalized form
GSS_Release_name free storage of normalized-form
name
GSS_Release_buffer free storage of general GSS-allocated
object
GSS_Release_OID_set free storage of OID set object
GSS_Create_empty_OID_set create empty OID set
GSS_Add_OID_set_member add member to OID set
GSS_Test_OID_set_member test if OID is member of OID set
GSS_Inquire_names_for_mech indicate name types supported by
mechanism
GSS_Inquire_mechs_for_name indicates mechanisms supporting name
type
GSS_Canonicalize_name translate name to per-mechanism form
GSS_Export_name externalize per-mechanism name
GSS_Duplicate_name duplicate name object
2.1: Credential management calls
These GSS-API calls provide functions related to the management of
credentials. Their characterization with regard to whether or not
they may block pending exchanges with other network entities (e.g.,
directories or authentication servers) depends in part on OS-specific
(extra-GSS-API) issues, so is not specified in this document.
The GSS_Acquire_cred() call is defined within the GSS-API in support
of application portability, with a particular orientation towards
support of portable server applications. It is recognized that (for
certain systems and mechanisms) credentials for interactive users may
be managed differently from credentials for server processes; in such
environments, it is the GSS-API implementation's responsibility to
distinguish these cases and the procedures for making this
distinction are a local matter. The GSS_Release_cred() call provides
a means for callers to indicate to the GSS-API that use of a
credentials structure is no longer required. The GSS_Inquire_cred()
call allows callers to determine information about a credentials
structure. The GSS_Add_cred() call enables callers to append
elements to an existing credential structure, allowing iterative
construction of a multi-mechanism credential. The
GSS_Inquire_cred_by_mech() call enables callers to extract per-
mechanism information describing a credentials structure.
2.1.1: GSS_Acquire_cred call
Inputs:
o desired_name INTERNAL NAME, -- NULL requests locally-determined
-- default
o lifetime_req INTEGER, -- in seconds; 0 requests default
o desired_mechs SET OF OBJECT IDENTIFIER, -- NULL requests
-- system-selected default
o cred_usage INTEGER -- 0=INITIATE-AND-ACCEPT, 1=INITIATE-ONLY,
-- 2=ACCEPT-ONLY
Outputs:
o major_status INTEGER,
o minor_status INTEGER,
o output_cred_handle CREDENTIAL HANDLE, -- if returned non-NULL,
-- caller must release with GSS_Release_cred()
o actual_mechs SET OF OBJECT IDENTIFIER, -- if returned non-NULL,
-- caller must release with GSS_Release_oid_set()
o lifetime_rec INTEGER -- in seconds, or reserved value for
-- INDEFINITE
Return major_status codes:
o GSS_S_COMPLETE indicates that requested credentials were
successfully established, for the duration indicated in lifetime_rec,
suitable for the usage requested in cred_usage, for the set of
mech_types indicated in actual_mechs, and that those credentials can
be referenced for subsequent use with the handle returned in
output_cred_handle.
o GSS_S_BAD_MECH indicates that a mech_type unsupported by the GSS-
API implementation type was requested, causing the credential
establishment operation to fail.
o GSS_S_BAD_NAMETYPE indicates that the provided desired_name is
uninterpretable or of a type unsupported by the applicable underlying
GSS-API mechanism(s), so no credentials could be established for the
accompanying desired_name.
o GSS_S_BAD_NAME indicates that the provided desired_name is
inconsistent in terms of internally-incorporated type specifier
information, so no credentials could be established for the
accompanying desired_name.
o GSS_S_CREDENTIALS_EXPIRED indicates that underlying credential
elements corresponding to the requested desired_name have expired, so
requested credentials could not be established.
o GSS_S_NO_CRED indicates that no credential elements corresponding
to the requested desired_name and usage could be accessed, so
requested credentials could not be established. In particular, this
status should be returned upon temporary user-fixable conditions
preventing successful credential establishment and upon lack of
authorization to establish and use credentials associated with the
identity named in the input desired_name argument.
o GSS_S_FAILURE indicates that credential establishment failed for
reasons unspecified at the GSS-API level.
GSS_Acquire_cred() is used to acquire credentials so that a principal
can (as a function of the input cred_usage parameter) initiate and/or
accept security contexts under the identity represented by the
desired_name input argument. On successful completion, the returned
output_cred_handle result provides a handle for subsequent references
to the acquired credentials. Typically, single-user client processes
requesting that default credential behavior be applied for context
establishment purposes will have no need to invoke this call.
A caller may provide the value NULL (GSS_C_NO_NAME) for desired_name,
which will be interpreted as a request for a credential handle that
will invoke default behavior when passed to GSS_Init_sec_context(),
if cred_usage is GSS_C_INITIATE or GSS_C_BOTH, or
GSS_Accept_sec_context(), if cred_usage is GSS_C_ACCEPT or
GSS_C_BOTH. It is possible that multiple pre-established credentials
may exist for the same principal identity (for example, as a result
of multiple user login sessions) when GSS_Acquire_cred() is called;
the means used in such cases to select a specific credential are
local matters. The input lifetime_req argument to GSS_Acquire_cred()
may provide useful information for local GSS-API implementations to
employ in making this disambiguation in a manner which will best
satisfy a caller's intent.
This routine is expected to be used primarily by context acceptors,
since implementations are likely to provide mechanism-specific ways
of obtaining GSS-API initiator credentials from the system login
process. Some implementations may therefore not support the
acquisition of GSS_C_INITIATE or GSS_C_BOTH credentials via
GSS_Acquire_cred() for any name other than GSS_C_NO_NAME, or a name
resulting from applying GSS_Inquire_context() to an active context,
or a name resulting from applying GSS_Inquire_cred() against a
credential handle corresponding to default behavior. It is important
to recognize that the explicit name which is yielded by resolving a
default reference may change over time, e.g., as a result of local
credential element management operations outside GSS-API; once
resolved, however, the value of such an explicit name will remain
constant.
The lifetime_rec result indicates the length of time for which the
acquired credentials will be valid, as an offset from the present. A
mechanism may return a reserved value indicating INDEFINITE if no
constraints on credential lifetime are imposed. A caller of
GSS_Acquire_cred() can request a length of time for which acquired
credentials are to be valid (lifetime_req argument), beginning at the
present, or can request credentials with a default validity interval.
(Requests for postdated credentials are not supported within the
GSS-API.) Certain mechanisms and implementations may bind in
credential validity period specifiers at a point preliminary to
invocation of the GSS_Acquire_cred() call (e.g., in conjunction with
user login procedures). As a result, callers requesting non-default
values for lifetime_req must recognize that such requests cannot
always be honored and must be prepared to accommodate the use of
returned credentials with different lifetimes as indicated in
lifetime_rec.
The caller of GSS_Acquire_cred() can explicitly specify a set of
mech_types which are to be accommodated in the returned credentials
(desired_mechs argument), or can request credentials for a system-
defined default set of mech_types. Selection of the system-specified
default set is recommended in the interests of application
portability. The actual_mechs return value may be interrogated by the
caller to determine the set of mechanisms with which the returned
credentials may be used.
2.1.2: GSS_Release_cred call
Input:
o cred_handle CREDENTIAL HANDLE -- if GSS_C_NO_CREDENTIAL
-- is specified, the call will complete successfully, but
-- will have no effect; no credential elements will be
-- released.
Outputs:
o major_status INTEGER,
o minor_status INTEGER
Return major_status codes:
o GSS_S_COMPLETE indicates that the credentials referenced by the
input cred_handle were released for purposes of subsequent access by
the caller. The effect on other processes which may be authorized
shared access to such credentials is a local matter.
o GSS_S_NO_CRED indicates that no release operation was performed,
either because the input cred_handle was invalid or because the
caller lacks authorization to access the referenced credentials.
o GSS_S_FAILURE indicates that the release operation failed for
reasons unspecified at the GSS-API level.
Provides a means for a caller to explicitly request that credentials
be released when their use is no longer required. Note that system-
specific credential management functions are also likely to exist,
for example to assure that credentials shared among processes are
properly deleted when all affected processes terminate, even if no
explicit release requests are issued by those processes. Given the
fact that multiple callers are not precluded from gaining authorized
access to the same credentials, invocation of GSS_Release_cred()
cannot be assumed to delete a particular set of credentials on a
system-wide basis.
2.1.3: GSS_Inquire_cred call
Input:
o cred_handle CREDENTIAL HANDLE -- if GSS_C_NO_CREDENTIAL
-- is specified, default initiator credentials are queried
Outputs:
o major_status INTEGER,
o minor_status INTEGER,
o cred_name INTERNAL NAME, -- caller must release with
-- GSS_Release_name()
o lifetime_rec INTEGER -- in seconds, or reserved value for
-- INDEFINITE
o cred_usage INTEGER, -- 0=INITIATE-AND-ACCEPT, 1=INITIATE-ONLY,
-- 2=ACCEPT-ONLY
o mech_set SET OF OBJECT IDENTIFIER -- caller must release
-- with GSS_Release_oid_set()
Return major_status codes:
o GSS_S_COMPLETE indicates that the credentials referenced by the
input cred_handle argument were valid, and that the output cred_name,
lifetime_rec, and cred_usage values represent, respectively, the
credentials' associated principal name, remaining lifetime, suitable
usage modes, and supported mechanism types.
o GSS_S_NO_CRED indicates that no information could be returned
about the referenced credentials, either because the input
cred_handle was invalid or because the caller lacks authorization to
access the referenced credentials.
o GSS_S_DEFECTIVE_CREDENTIAL indicates that the referenced
credentials are invalid.
o GSS_S_CREDENTIALS_EXPIRED indicates that the referenced
credentials have expired.
o GSS_S_FAILURE indicates that the operation failed for reasons
unspecified at the GSS-API level.
The GSS_Inquire_cred() call is defined primarily for the use of those
callers which request use of default credential behavior rather than
acquiring credentials explicitly with GSS_Acquire_cred(). It enables
callers to determine a credential structure's associated principal
name, remaining validity period, usability for security context
initiation and/or acceptance, and supported mechanisms.
For a multi-mechanism credential, the returned "lifetime" specifier
indicates the shortest lifetime of any of the mechanisms' elements in
the credential (for either context initiation or acceptance
purposes).
GSS_Inquire_cred() should indicate INITIATE-AND-ACCEPT for
"cred_usage" if both of the following conditions hold:
(1) there exists in the credential an element which allows context
initiation using some mechanism
(2) there exists in the credential an element which allows context
acceptance using some mechanism (allowably, but not necessarily,
one of the same mechanism(s) qualifying for (1)).
If condition (1) holds but not condition (2), GSS_Inquire_cred()
should indicate INITIATE-ONLY for "cred_usage". If condition (2)
holds but not condition (1), GSS_Inquire_cred() should indicate
ACCEPT-ONLY for "cred_usage".
Callers requiring finer disambiguation among available combinations
of lifetimes, usage modes, and mechanisms should call the
GSS_Inquire_cred_by_mech() routine, passing that routine one of the
mech OIDs returned by GSS_Inquire_cred().
2.1.4: GSS_Add_cred call
Inputs:
o input_cred_handle CREDENTIAL HANDLE -- handle to credential
-- structure created with prior GSS_Acquire_cred() or
-- GSS_Add_cred() call; see text for definition of behavior
-- when GSS_C_NO_CREDENTIAL provided.
o desired_name INTERNAL NAME
o initiator_time_req INTEGER -- in seconds; 0 requests default
o acceptor_time_req INTEGER -- in seconds; 0 requests default
o desired_mech OBJECT IDENTIFIER
o cred_usage INTEGER -- 0=INITIATE-AND-ACCEPT, 1=INITIATE-ONLY,
-- 2=ACCEPT-ONLY
Outputs:
o major_status INTEGER,
o minor_status INTEGER,
o output_cred_handle CREDENTIAL HANDLE, -- NULL to request that
-- credential elements be added "in place" to the credential
-- structure identified by input_cred_handle,
-- non-NULL pointer to request that
-- a new credential structure and handle be created.
-- if credential handle returned, caller must release with
-- GSS_Release_cred()
o actual_mechs SET OF OBJECT IDENTIFIER, -- if returned, caller must
-- release with GSS_Release_oid_set()
o initiator_time_rec INTEGER -- in seconds, or reserved value for
-- INDEFINITE
o acceptor_time_rec INTEGER -- in seconds, or reserved value for
-- INDEFINITE
o cred_usage INTEGER, -- 0=INITIATE-AND-ACCEPT, 1=INITIATE-ONLY,
-- 2=ACCEPT-ONLY
o mech_set SET OF OBJECT IDENTIFIER -- full set of mechanisms
-- supported by resulting credential.
Return major_status codes:
o GSS_S_COMPLETE indicates that the credentials referenced by the
input_cred_handle argument were valid, and that the resulting
credential from GSS_Add_cred() is valid for the durations indicated
in initiator_time_rec and acceptor_time_rec, suitable for the usage
requested in cred_usage, and for the mechanisms indicated in
actual_mechs.
o GSS_S_DUPLICATE_ELEMENT indicates that the input desired_mech
specified a mechanism for which the referenced credential already
contained a credential element with overlapping cred_usage and
validity time specifiers.
o GSS_S_BAD_MECH indicates that the input desired_mech specified a
mechanism unsupported by the GSS-API implementation, causing the
GSS_Add_cred() operation to fail.
o GSS_S_BAD_NAMETYPE indicates that the provided desired_name is
uninterpretable or of a type unsupported by the applicable underlying
GSS-API mechanism(s), so the GSS_Add_cred() operation could not be
performed for that name.
o GSS_S_BAD_NAME indicates that the provided desired_name is
inconsistent in terms of internally-incorporated type specifier
information, so the GSS_Add_cred() operation could not be performed
for that name.
o GSS_S_NO_CRED indicates that the input_cred_handle referenced
invalid or inaccessible credentials. In particular, this status
should be returned upon temporary user-fixable conditions preventing
successful credential establishment or upon lack of authorization to
establish or use credentials representing the requested identity.
o GSS_S_CREDENTIALS_EXPIRED indicates that referenced credential
elements have expired, so the GSS_Add_cred() operation could not be
performed.
o GSS_S_FAILURE indicates that the operation failed for reasons
unspecified at the GSS-API level.
GSS_Add_cred() enables callers to construct credentials iteratively
by adding credential elements in successive operations, corresponding
to different mechanisms. This offers particular value in multi-
mechanism environments, as the major_status and minor_status values
returned on each iteration are individually visible and can therefore
be interpreted unambiguously on a per-mechanism basis. A credential
element is identified by the name of the principal to which it
refers. GSS-API implementations must impose a local access control
policy on callers of this routine to prevent unauthorized callers
from acquiring credential elements to which they are not entitled.
This routine is not intended to provide a "login to the network"
function, as such a function would involve the creation of new
mechanism-specific authentication data, rather than merely acquiring
a GSS-API handle to existing data. Such functions, if required,
should be defined in implementation-specific extension routines.
If credential acquisition is time-consuming for a mechanism, the
mechanism may choose to delay the actual acquisition until the
credential is required (e.g. by GSS_Init_sec_context() or
GSS_Accept_sec_context()). Such mechanism-specific implementation
decisions should be invisible to the calling application; thus a call
of GSS_Inquire_cred() immediately following the call of
GSS_Acquire_cred() must return valid credential data, and may
therefore incur the overhead of a deferred credential acquisition.
If GSS_C_NO_CREDENTIAL is specified as input_cred_handle, a non-NULL
output_cred_handle must be supplied. For the case of
GSS_C_NO_CREDENTIAL as input_cred_handle, GSS_Add_cred() will create
the credential referenced by its output_cred_handle based on default
behavior. That is, the call will have the same effect as if the
caller had previously called GSS_Acquire_cred(), specifying the same
usage and passing GSS_C_NO_NAME as the desired_name parameter
(thereby obtaining an explicit credential handle corresponding to
default behavior), had passed that credential handle to
GSS_Add_cred(), and had finally called GSS_Release_cred() on the
credential handle received from GSS_Acquire_cred().
This routine is expected to be used primarily by context acceptors,
since implementations are likely to provide mechanism-specific ways
of obtaining GSS-API initiator credentials from the system login
process. Some implementations may therefore not support the
acquisition of GSS_C_INITIATE or GSS_C_BOTH credentials via
GSS_Acquire_cred() for any name other than GSS_C_NO_NAME, or a name
resulting from applying GSS_Inquire_context() to an active context,
or a name resulting from applying GSS_Inquire_cred() against a
credential handle corresponding to default behavior. It is important
to recognize that the explicit name which is yielded by resolving a
default reference may change over time, e.g., as a result of local
credential element management operations outside GSS-API; once
resolved, however, the value of such an explicit name will remain
constant.
A caller may provide the value NULL (GSS_C_NO_NAME) for desired_name,
which will be interpreted as a request for a credential handle that
will invoke default behavior when passed to GSS_Init_sec_context(),
if cred_usage is GSS_C_INITIATE or GSS_C_BOTH, or
GSS_Accept_sec_context(), if cred_usage is GSS_C_ACCEPT or
GSS_C_BOTH.
The same input desired_name, or default reference, should be used on
all GSS_Acquire_cred() and GSS_Add_cred() calls corresponding to a
particular credential.
2.1.5: GSS_Inquire_cred_by_mech call
Inputs:
o cred_handle CREDENTIAL HANDLE -- if GSS_C_NO_CREDENTIAL
-- specified, default initiator credentials are queried
o mech_type OBJECT IDENTIFIER -- specific mechanism for
-- which credentials are being queried
Outputs:
o major_status INTEGER,
o minor_status INTEGER,
o cred_name INTERNAL NAME, -- guaranteed to be MN; caller must
-- release with GSS_Release_name()
o lifetime_rec_initiate INTEGER -- in seconds, or reserved value for
-- INDEFINITE
o lifetime_rec_accept INTEGER -- in seconds, or reserved value for
-- INDEFINITE
o cred_usage INTEGER, -- 0=INITIATE-AND-ACCEPT, 1=INITIATE-ONLY,
-- 2=ACCEPT-ONLY
Return major_status codes:
o GSS_S_COMPLETE indicates that the credentials referenced by the
input cred_handle argument were valid, that the mechanism indicated
by the input mech_type was represented with elements within those
credentials, and that the output cred_name, lifetime_rec_initiate,
lifetime_rec_accept, and cred_usage values represent, respectively,
the credentials' associated principal name, remaining lifetimes, and
suitable usage modes.
o GSS_S_NO_CRED indicates that no information could be returned
about the referenced credentials, either because the input
cred_handle was invalid or because the caller lacks authorization to
access the referenced credentials.
o GSS_S_DEFECTIVE_CREDENTIAL indicates that the referenced
credentials are invalid.
o GSS_S_CREDENTIALS_EXPIRED indicates that the referenced
credentials have expired.
o GSS_S_BAD_MECH indicates that the referenced credentials do not
contain elements for the requested mechanism.
o GSS_S_FAILURE indicates that the operation failed for reasons
unspecified at the GSS-API level.
The GSS_Inquire_cred_by_mech() call enables callers in multi-
mechanism environments to acquire specific data about available
combinations of lifetimes, usage modes, and mechanisms within a
credential structure. The lifetime_rec_initiate result indicates the
available lifetime for context initiation purposes; the
lifetime_rec_accept result indicates the available lifetime for
context acceptance purposes.
2.2: Context-level calls
This group of calls is devoted to the establishment and management of
security contexts between peers. A context's initiator calls
GSS_Init_sec_context(), resulting in generation of a token which the
caller passes to the target. At the target, that token is passed to
GSS_Accept_sec_context(). Depending on the underlying mech_type and
specified options, additional token exchanges may be performed in the
course of context establishment; such exchanges are accommodated by
GSS_S_CONTINUE_NEEDED status returns from GSS_Init_sec_context() and
GSS_Accept_sec_context().
Either party to an established context may invoke
GSS_Delete_sec_context() to flush context information when a context
is no longer required. GSS_Process_context_token() is used to process
received tokens carrying context-level control information.
GSS_Context_time() allows a caller to determine the length of time
for which an established context will remain valid.
GSS_Inquire_context() returns status information describing context
characteristics. GSS_Wrap_size_limit() allows a caller to determine
the size of a token which will be generated by a GSS_Wrap()
operation. GSS_Export_sec_context() and GSS_Import_sec_context()
enable transfer of active contexts between processes on an end
system.
2.2.1: GSS_Init_sec_context call
Inputs:
o claimant_cred_handle CREDENTIAL HANDLE, -- NULL specifies "use
-- default"
o input_context_handle CONTEXT HANDLE, -- 0
-- (GSS_C_NO_CONTEXT) specifies "none assigned yet"
o targ_name INTERNAL NAME,
o mech_type OBJECT IDENTIFIER, -- NULL parameter specifies "use
-- default"
o deleg_req_flag BOOLEAN,
o mutual_req_flag BOOLEAN,
o replay_det_req_flag BOOLEAN,
o sequence_req_flag BOOLEAN,
o anon_req_flag BOOLEAN,
o conf_req_flag BOOLEAN,
o integ_req_flag BOOLEAN,
o lifetime_req INTEGER, -- 0 specifies default lifetime
o chan_bindings OCTET STRING,
o input_token OCTET STRING -- NULL or token received from target
Outputs:
o major_status INTEGER,
o minor_status INTEGER,
o output_context_handle CONTEXT HANDLE, -- once returned non-NULL,
-- caller must release with GSS_Delete_sec_context()
o mech_type OBJECT IDENTIFIER, -- actual mechanism always
-- indicated, never NULL; caller should treat as read-only
-- and should not attempt to release
o output_token OCTET STRING, -- NULL or token to pass to context
-- target; caller must release with GSS_Release_buffer()
o deleg_state BOOLEAN,
o mutual_state BOOLEAN,
o replay_det_state BOOLEAN,
o sequence_state BOOLEAN,
o anon_state BOOLEAN,
o trans_state BOOLEAN,
o prot_ready_state BOOLEAN, -- see Section 1.2.7
o conf_avail BOOLEAN,
o integ_avail BOOLEAN,
o lifetime_rec INTEGER -- in seconds, or reserved value for
-- INDEFINITE
This call may block pending network interactions for those mech_types
in which an authentication server or other network entity must be
consulted on behalf of a context initiator in order to generate an
output_token suitable for presentation to a specified target.
Return major_status codes:
o GSS_S_COMPLETE indicates that context-level information was
successfully initialized, and that the returned output_token will
provide sufficient information for the target to perform per-message
processing on the newly-established context.
o GSS_S_CONTINUE_NEEDED indicates that control information in the
returned output_token must be sent to the target, and that a reply
must be received and passed as the input_token argument
to a continuation call to GSS_Init_sec_context(), before per-message
processing can be performed in conjunction with this context (unless
the prot_ready_state value is concurrently returned TRUE).
o GSS_S_DEFECTIVE_TOKEN indicates that consistency checks performed
on the input_token failed, preventing further processing from being
performed based on that token.
o GSS_S_DEFECTIVE_CREDENTIAL indicates that consistency checks
performed on the credential structure referenced by
claimant_cred_handle failed, preventing further processing from being
performed using that credential structure.
o GSS_S_BAD_SIG (GSS_S_BAD_MIC) indicates that the received
input_token contains an incorrect integrity check, so context setup
cannot be accomplished.
o GSS_S_NO_CRED indicates that no context was established, either
because the input cred_handle was invalid, because the referenced