returned to the caller. If an output_context_token is provided to
the caller, it can be passed to the context's peer to inform the
peer's GSS-API implementation that the peer's corresponding context
information can also be flushed. (Once a context is established, the
peers involved are expected to retain cached credential and context-
related information until the information's expiration time is
reached or until a GSS_Delete_sec_context() call is made.)
The facility for context_token usage to signal context deletion is
retained for compatibility with GSS-API Version 1. For current
usage, it is recommended that both peers to a context invoke
GSS_Delete_sec_context() independently, passing a null
output_context_token buffer to indicate that no context_token is
required. Implementations of GSS_Delete_sec_context() should delete
relevant locally-stored context information.
Attempts to perform per-message processing on a deleted context will
result in error returns.
2.2.4: GSS_Process_context_token call
Inputs:
o context_handle CONTEXT HANDLE,
o input_context_token OCTET STRING
Outputs:
o major_status INTEGER,
o minor_status INTEGER,
Return major_status codes:
o GSS_S_COMPLETE indicates that the input_context_token was
successfully processed in conjunction with the context
referenced by context_handle.
o GSS_S_DEFECTIVE_TOKEN indicates that consistency checks
performed on the received context_token failed, preventing
further processing from being performed with that token.
o GSS_S_NO_CONTEXT indicates that no valid context was recognized
for the input context_handle provided.
o GSS_S_FAILURE indicates that the context is recognized, but
that the GSS_Process_context_token() operation could not be
performed for reasons unspecified at the GSS-API level.
This call is used to process context_tokens received from a peer once
a context has been established, with corresponding impact on
context-level state information. One use for this facility is
processing of the context_tokens generated by
GSS_Delete_sec_context(); GSS_Process_context_token() will not block
pending network interactions for that purpose. Another use is to
process tokens indicating remote-peer context establishment failures
after the point where the local GSS-API implementation has already
indicated GSS_S_COMPLETE status.
2.2.5: GSS_Context_time call
Input:
o context_handle CONTEXT HANDLE,
Outputs:
o major_status INTEGER,
o minor_status INTEGER,
o lifetime_rec INTEGER - in seconds, or reserved value for
INDEFINITE
Return major_status codes:
o GSS_S_COMPLETE indicates that the referenced context is valid,
and will remain valid for the amount of time indicated in
lifetime_rec.
o GSS_S_CONTEXT_EXPIRED indicates that data items related to the
referenced context have expired.
o GSS_S_CREDENTIALS_EXPIRED indicates that the context is
recognized, but that its associated credentials have expired.
o GSS_S_NO_CONTEXT indicates that no valid context was recognized
for the input context_handle provided.
o GSS_S_FAILURE indicates that the requested operation failed for
reasons unspecified at the GSS-API level.
This call is used to determine the amount of time for which a
currently established context will remain valid.
2.2.6: GSS_Inquire_context call
Input:
o context_handle CONTEXT HANDLE,
Outputs:
o major_status INTEGER,
o minor_status INTEGER,
o src_name INTERNAL NAME, -- name of context initiator,
-- guaranteed to be MN
o targ_name INTERNAL NAME, -- name of context target,
-- guaranteed to be MN
o lifetime_rec INTEGER -- in seconds, or reserved value for
INDEFINITE,
o mech_type OBJECT IDENTIFIER, -- the mechanism supporting this
security context
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,
o conf_avail BOOLEAN,
o integ_avail BOOLEAN,
o locally_initiated BOOLEAN, -- TRUE if initiator, FALSE if acceptor
Return major_status codes:
o GSS_S_COMPLETE indicates that the referenced context is valid
and that src_name, targ_name, lifetime_rec, mech_type, deleg_state,
mutual_state, replay_det_state, sequence_state, anon_state,
trans_state, prot_ready_state, conf_avail, integ_avail, and
locally_initiated return values describe the corresponding
characteristics of the context.
o GSS_S_CONTEXT_EXPIRED indicates that the provided input
context_handle is recognized, but that the referenced context
has expired. Return values other than major_status and
minor_status are undefined.
o GSS_S_NO_CONTEXT indicates that no valid context was recognized
for the input context_handle provided. Return values other than
major_status and minor_status are undefined.
o GSS_S_FAILURE indicates that the requested operation failed for
reasons unspecified at the GSS-API level. Return values other than
major_status and minor_status are undefined.
This call is used to extract information describing characteristics
of a security context.
2.2.7: GSS_Wrap_size_limit call
Inputs:
o context_handle CONTEXT HANDLE,
o qop INTEGER,
o output_size INTEGER
Outputs:
o major_status INTEGER,
o minor_status INTEGER,
o max_input_size INTEGER
Return major_status codes:
o GSS_S_COMPLETE indicates a successful token size determination:
an input message with a length in octets equal to the
returned max_input_size value will, when passed to GSS_Wrap()
for processing on the context identified by the context_handle
parameter and with the quality of protection specifier provided
in the qop parameter, yield an output token no larger than the
value of the provided output_size parameter.
o GSS_S_CONTEXT_EXPIRED indicates that the provided input
context_handle is recognized, but that the referenced context
has expired. Return values other than major_status and
minor_status are undefined.
o GSS_S_NO_CONTEXT indicates that no valid context was recognized
for the input context_handle provided. Return values other than
major_status and minor_status are undefined.
o GSS_S_BAD_QOP indicates that the provided QOP value is not
recognized or supported for the context.
o GSS_S_FAILURE indicates that the requested operation failed for
reasons unspecified at the GSS-API level. Return values other than
major_status and minor_status are undefined.
This call is used to determine the largest input datum which may be
passed to GSS_Wrap() without yielding an output token larger than a
caller-specified value.
2.2.8: GSS_Export_sec_context call
Inputs:
o context_handle CONTEXT HANDLE
Outputs:
o major_status INTEGER,
o minor_status INTEGER,
o interprocess_token OCTET STRING
Return major_status codes:
o GSS_S_COMPLETE indicates that the referenced context has been
successfully exported to a representation in the interprocess_token,
and is no longer available for use by the caller.
o GSS_S_UNAVAILABLE indicates that the context export facility
is not available for use on the referenced context. (This status
should occur only for contexts for which the trans_state value is
FALSE.) Return values other than major_status and minor_status are
undefined.
o GSS_S_CONTEXT_EXPIRED indicates that the provided input
context_handle is recognized, but that the referenced context has
expired. Return values other than major_status and minor_status are
undefined.
o GSS_S_NO_CONTEXT indicates that no valid context was recognized
for the input context_handle provided. Return values other than
major_status and minor_status are undefined.
o GSS_S_FAILURE indicates that the requested operation failed for
reasons unspecified at the GSS-API level. Return values other than
major_status and minor_status are undefined.
This call generates an interprocess token for transfer to another
process within an end system, in order to transfer control of a
security context to that process. The recipient of the interprocess
token will call GSS_Import_sec_context() to accept the transfer. The
GSS_Export_sec_context() operation is defined for use only with
security contexts which are fully and successfully established (i.e.,
those for which GSS_Init_sec_context() and GSS_Accept_sec_context()
have returned GSS_S_COMPLETE major_status).
To ensure portability, a caller of GSS_Export_sec_context() must not
assume that a context may continue to be used once it has been
exported; following export, the context referenced by the
context_handle cannot be assumed to remain valid. Further, portable
callers must not assume that a given interprocess token can be
imported by GSS_Import_sec_context() more than once, thereby creating
multiple instantiations of a single context. GSS-API implementations
may detect and reject attempted multiple imports, but are not
required to do so.
The internal representation contained within the interprocess token
is an implementation-defined local matter. Interprocess tokens
cannot be assumed to be transferable across different GSS-API
implementations.
It is recommended that GSS-API implementations adopt policies suited
to their operational environments in order to define the set of
processes eligible to import a context, but specific constraints in
this area are local matters. Candidate examples include transfers
between processes operating on behalf of the same user identity, or
processes comprising a common job. However, it may be impossible to
enforce such policies in some implementations.
In support of the above goals, implementations may protect the
transferred context data by using cryptography to protect data within
the interprocess token, or by using interprocess tokens as a means to
reference local interprocess communication facilities (protected by
other means) rather than storing the context data directly within the
tokens.
Transfer of an open context may, for certain mechanisms and
implementations, reveal data about the credential which was used to
establish the context. Callers should, therefore, be cautious about
the trustworthiness of processes to which they transfer contexts.
Although the GSS-API implementation may provide its own set of
protections over the exported context, the caller is responsible for
protecting the interprocess token from disclosure, and for taking
care that the context is transferred to an appropriate destination
process.
2.2.9: GSS_Import_sec_context call
Inputs:
o interprocess_token OCTET STRING
Outputs:
o major_status INTEGER,
o minor_status INTEGER,
o context_handle CONTEXT HANDLE
Return major_status codes:
o GSS_S_COMPLETE indicates that the context represented by the
input interprocess_token has been successfully transferred to
the caller, and is available for future use via the output
context_handle.
o GSS_S_CONTEXT_EXPIRED indicates that the context represented by
the input interprocess_token has expired. Return values other
than major_status and minor_status are undefined.
o GSS_S_NO_CONTEXT indicates that the context represented by the
input interprocess_token was invalid. Return values other than
major_status and minor_status are undefined.
o GSS_S_DEFECTIVE_TOKEN indicates that the input interprocess_token
was defective. Return values other than major_status and
minor_status are undefined.
o GSS_S_UNAVAILABLE indicates that the context import facility
is not available for use on the referenced context. Return values
other than major_status and minor_status are undefined.
o GSS_S_UNAUTHORIZED indicates that the context represented by
the input interprocess_token is unauthorized for transfer to the
caller. Return values other than major_status and minor_status
are undefined.
o GSS_S_FAILURE indicates that the requested operation failed for
reasons unspecified at the GSS-API level. Return values other than
major_status and minor_status are undefined.
This call processes an interprocess token generated by
GSS_Export_sec_context(), making the transferred context available
for use by the caller. After a successful GSS_Import_sec_context()
operation, the imported context is available for use by the importing
process.
For further discussion of the security and authorization issues
regarding this call, please see the discussion in Section 2.2.8.
2.3: Per-message calls
This group of calls is used to perform per-message protection
processing on an established security context. None of these calls
block pending network interactions. These calls may be invoked by a
context's initiator or by the context's target. The four members of
this group should be considered as two pairs; the output from
GSS_GetMIC() is properly input to GSS_VerifyMIC(), and the output
from GSS_Wrap() is properly input to GSS_Unwrap().
GSS_GetMIC() and GSS_VerifyMIC() support data origin authentication
and data integrity services. When GSS_GetMIC() is invoked on an
input message, it yields a per-message token containing data items
which allow underlying mechanisms to provide the specified security
services. The original message, along with the generated per-message
token, is passed to the remote peer; these two data elements are
processed by GSS_VerifyMIC(), which validates the message in
conjunction with the separate token.
GSS_Wrap() and GSS_Unwrap() support caller-requested confidentiality
in addition to the data origin authentication and data integrity
services offered by GSS_GetMIC() and GSS_VerifyMIC(). GSS_Wrap()
outputs a single data element, encapsulating optionally enciphered
user data as well as associated token data items. The data element
output from GSS_Wrap() is passed to the remote peer and processed by
GSS_Unwrap() at that system. GSS_Unwrap() combines decipherment (as
required) with validation of data items related to authentication and
integrity.
2.3.1: GSS_GetMIC call
Note: This call is functionally equivalent to the GSS_Sign call as
defined in previous versions of this specification. In the interests
of backward compatibility, it is recommended that implementations
support this function under both names for the present; future
references to this function as GSS_Sign are deprecated.
Inputs:
o context_handle CONTEXT HANDLE,
o qop_req INTEGER,-0 specifies default QOP
o message OCTET STRING
Outputs:
o major_status INTEGER,
o minor_status INTEGER,
o per_msg_token OCTET STRING
Return major_status codes:
o GSS_S_COMPLETE indicates that an integrity check, suitable for an
established security context, was successfully applied and
that the message and corresponding per_msg_token are ready
for transmission.
o GSS_S_CONTEXT_EXPIRED indicates that context-related data
items have expired, so that the requested operation cannot be
performed.
o GSS_S_CREDENTIALS_EXPIRED indicates that the context is recognized,
but that its associated credentials have expired, so
that the requested operation cannot be performed.
o GSS_S_NO_CONTEXT indicates that no valid context was recognized
for the input context_handle provided.
o GSS_S_BAD_QOP indicates that the provided QOP value is not
recognized or supported for the context.
o GSS_S_FAILURE indicates that the context is recognized, but
that the requested operation could not be performed for
reasons unspecified at the GSS-API level.
Using the security context referenced by context_handle, apply an
integrity check to the input message (along with timestamps and/or
other data included in support of mech_type-specific mechanisms) and
return the result in per_msg_token. The qop_req parameter,
interpretation of which is discussed in Section 1.2.4, allows
quality-of-protection control. The caller passes the message and the
per_msg_token to the target.
The GSS_GetMIC() function completes before the message and
per_msg_token is sent to the peer; successful application of
GSS_GetMIC() does not guarantee that a corresponding GSS_VerifyMIC()
has been (or can necessarily be) performed successfully when the
message arrives at the destination.
Mechanisms which do not support per-message protection services
should return GSS_S_FAILURE if this routine is called.
2.3.2: GSS_VerifyMIC call
Note: This call is functionally equivalent to the GSS_Verify call as
defined in previous versions of this specification. In the interests
of backward compatibility, it is recommended that implementations
support this function under both names for the present; future
references to this function as GSS_Verify are deprecated.
Inputs:
o context_handle CONTEXT HANDLE,
o message OCTET STRING,
o per_msg_token OCTET STRING
Outputs:
o qop_state INTEGER,
o major_status INTEGER,
o minor_status INTEGER,
Return major_status codes:
o GSS_S_COMPLETE indicates that the message was successfully
verified.
o GSS_S_DEFECTIVE_TOKEN indicates that consistency checks performed
on the received per_msg_token failed, preventing
further processing from being performed with that token.
o GSS_S_BAD_SIG indicates that the received per_msg_token contains
an incorrect integrity check for the message.
o GSS_S_DUPLICATE_TOKEN, GSS_S_OLD_TOKEN, GSS_S_UNSEQ_TOKEN,
and GSS_S_GAP_TOKEN values appear in conjunction with the
optional per-message replay detection features described
in Section 1.2.3; their semantics are described in that section.
o GSS_S_CONTEXT_EXPIRED indicates that context-related data
items have expired, so that the requested operation cannot be
performed.
o GSS_S_CREDENTIALS_EXPIRED indicates that the context is
recognized,
but that its associated credentials have expired, so
that the requested operation cannot be performed.
o GSS_S_NO_CONTEXT indicates that no valid context was recognized
for the input context_handle provided.
o GSS_S_FAILURE indicates that the context is recognized, but
that the GSS_VerifyMIC() operation could not be performed for
reasons unspecified at the GSS-API level.
Using the security context referenced by context_handle, verify that
the input per_msg_token contains an appropriate integrity check for
the input message, and apply any active replay detection or
sequencing features. Return an indication of the quality-of-
protection applied to the processed message in the qop_state result.
Since the GSS_VerifyMIC() routine never provides a confidentiality
service, its implementations should not return non-zero values in the
confidentiality fields of the output qop_state.
Mechanisms which do not support per-message protection services
should return GSS_S_FAILURE if this routine is called.
2.3.3: GSS_Wrap call
Note: This call is functionally equivalent to the GSS_Seal call as
defined in previous versions of this specification. In the interests
of backward compatibility, it is recommended that implementations
support this function under both names for the present; future
references to this function as GSS_Seal are deprecated.
Inputs:
o context_handle CONTEXT HANDLE,
o conf_req_flag BOOLEAN,
o qop_req INTEGER,-0 specifies default QOP
o input_message OCTET STRING
Outputs:
o major_status INTEGER,
o minor_status INTEGER,
o conf_state BOOLEAN,
o output_message OCTET STRING
Return major_status codes:
o GSS_S_COMPLETE indicates that the input_message was successfully
processed and that the output_message is ready for
transmission.
o GSS_S_CONTEXT_EXPIRED indicates that context-related data
items have expired, so that the requested operation cannot be
performed.
o GSS_S_CREDENTIALS_EXPIRED indicates that the context is
recognized,
but that its associated credentials have expired, so
that the requested operation cannot be performed.
o GSS_S_NO_CONTEXT indicates that no valid context was recognized
for the input context_handle provided.
o GSS_S_BAD_QOP indicates that the provided QOP value is not
recognized or supported for the context.
o GSS_S_FAILURE indicates that the context is recognized, but
that the GSS_Wrap() operation could not be performed for
reasons unspecified at the GSS-API level.
Performs the data origin authentication and data integrity functions
of GSS_GetMIC(). If the input conf_req_flag is TRUE, requests that
confidentiality be applied to the input_message. Confidentiality may
not be supported in all mech_types or by all implementations; the
returned conf_state flag indicates whether confidentiality was
provided for the input_message. The qop_req parameter, interpretation
of which is discussed in Section 1.2.4, allows quality-of-protection
control.
In all cases, the GSS_Wrap() call yields a single output_message
data element containing (optionally enciphered) user data as well as
control information.
Mechanisms which do not support per-message protection services
should return GSS_S_FAILURE if this routine is called.
2.3.4: GSS_Unwrap call
Note: This call is functionally equivalent to the GSS_Unseal call as
defined in previous versions of this specification. In the interests
of backward compatibility, it is recommended that implementations
support this function under both names for the present; future
references to this function as GSS_Unseal are deprecated.
Inputs:
o context_handle CONTEXT HANDLE,
o input_message OCTET STRING
Outputs:
o conf_state BOOLEAN,
o qop_state INTEGER,
o major_status INTEGER,
o minor_status INTEGER,
o output_message OCTET STRING
Return major_status codes:
o GSS_S_COMPLETE indicates that the input_message was
successfully processed and that the resulting output_message is
available.
o GSS_S_DEFECTIVE_TOKEN indicates that consistency checks performed
on the per_msg_token extracted from the input_message
failed, preventing further processing from being performed.
o GSS_S_BAD_SIG indicates that an incorrect integrity check was
detected
for the message.
o GSS_S_DUPLICATE_TOKEN, GSS_S_OLD_TOKEN, GSS_S_UNSEQ_TOKEN,
and GSS_S_GAP_TOKEN values appear in conjunction with the
optional per-message replay detection features described
in Section 1.2.3; their semantics are described in that section.
o GSS_S_CONTEXT_EXPIRED indicates that context-related data
items have expired, so that the requested operation cannot be
performed.
o GSS_S_CREDENTIALS_EXPIRED indicates that the context is
recognized,
but that its associated credentials have expired, so
that the requested operation cannot be performed.
o GSS_S_NO_CONTEXT indicates that no valid context was recognized
for the input context_handle provided.
o GSS_S_FAILURE indicates that the context is recognized, but
that the GSS_Unwrap() operation could not be performed for
reasons unspecified at the GSS-API level.
Processes a data element generated (and optionally enciphered) by
GSS_Wrap(), provided as input_message. The returned conf_state value
indicates whether confidentiality was applied to the input_message.
If conf_state is TRUE, GSS_Unwrap() deciphers the input_message.
Returns an indication of the quality-of-protection applied to the
processed message in the qop_state result. GSS_Wrap() performs the
data integrity and data origin authentication checking functions of
GSS_VerifyMIC() on the plaintext data. Plaintext data is returned in
output_message.
Mechanisms which do not support per-message protection services
should return GSS_S_FAILURE if this routine is called.
2.4: Support calls
This group of calls provides support functions useful to GSS-API
callers, independent of the state of established contexts. Their
characterization with regard to blocking or non-blocking status in
terms of network interactions is unspecified.
2.4.1: GSS_Display_status call
Inputs:
o status_value INTEGER,-GSS-API major_status or minor_status
return value
o status_type INTEGER,-1 if major_status, 2 if minor_status
o mech_type OBJECT IDENTIFIER-mech_type to be used for minor_
status translation
Outputs:
o major_status INTEGER,
o minor_status INTEGER,
o status_string_set SET OF OCTET STRING
Return major_status codes:
o GSS_S_COMPLETE indicates that a valid printable status
representation (possibly representing more than one status event
encoded within the status_value) is available in the returned
status_string_set.
o GSS_S_BAD_MECH indicates that translation in accordance with an
unsupported mech_type was requested, so translation could not
be performed.
o GSS_S_BAD_STATUS indicates that the input status_value was
invalid, or that the input status_type carried a value other
than 1 or 2, so translation could not be performed.
o GSS_S_FAILURE indicates that the requested operation could not
be performed for reasons unspecified at the GSS-API level.
Provides a means for callers to translate GSS-API-returned major and
minor status codes into printable string representations.
2.4.2: GSS_Indicate_mechs call
Input:
o (none)
Outputs:
o major_status INTEGER,
o minor_status INTEGER,
o mech_set SET OF OBJECT IDENTIFIER
Return major_status codes:
o GSS_S_COMPLETE indicates that a set of available mechanisms has
been returned in mech_set.
o GSS_S_FAILURE indicates that the requested operation could not
be performed for reasons unspecified at the GSS-API level.
Allows callers to determine the set of mechanism types available on
the local system. This call is intended for support of specialized
callers who need to request non-default mech_type sets from
GSS_Acquire_cred(), and should not be needed by other callers.
2.4.3: GSS_Compare_name call
Inputs:
o name1 INTERNAL NAME,
o name2 INTERNAL NAME
Outputs:
o major_status INTEGER,
o minor_status INTEGER,
o name_equal BOOLEAN
Return major_status codes:
o GSS_S_COMPLETE indicates that name1 and name2 were comparable,
and that the name_equal result indicates whether name1 and
name2 represent the same entity.
o GSS_S_BAD_NAMETYPE indicates that one or both of name1 and
name2 contained internal type specifiers uninterpretable
by the applicable underlying GSS-API mechanism(s), or that
the two names' types are different and incomparable, so that
the comparison operation could not be completed.
o GSS_S_BAD_NAME indicates that one or both of the input names
was ill-formed in terms of its internal type specifier, so
the comparison operation could not be completed.
o GSS_S_FAILURE indicates that the call's operation could not
be performed for reasons unspecified at the GSS-API level.
Allows callers to compare two internal name representations to
determine whether they refer to the same entity. If either name
presented to GSS_Compare_name() denotes an anonymous principal,
GSS_Compare_name() shall indicate FALSE. It is not required that
either or both inputs name1 and name2 be MNs; for some
implementations and cases, GSS_S_BAD_NAMETYPE may be returned,
indicating name incomparability, for the case where neither input
name is an MN.
2.4.4: GSS_Display_name call
Inputs:
o name INTERNAL NAME
Outputs:
o major_status INTEGER,
o minor_status INTEGER,
o name_string OCTET STRING,
o name_type OBJECT IDENTIFIER
Return major_status codes:
o GSS_S_COMPLETE indicates that a valid printable name
representation is available in the returned name_string.
o GSS_S_BAD_NAMETYPE indicates that the provided name was of a
type uninterpretable by the applicable underlying GSS-API
mechanism(s), so no printable representation could be generated.
o GSS_S_BAD_NAME indicates that the contents of the provided name
were inconsistent with the internally-indicated name type, so
no printable representation could be generated.
o GSS_S_FAILURE indicates that the requested operation could not
be performed for reasons unspecified at the GSS-API level.
Allows callers to translate an internal name representation into a
printable form with associated namespace type descriptor. The syntax
of the printable form is a local matter.
If the input name represents an anonymous identity, a reserved value
(GSS_C_NT_ANONYMOUS) shall be returned for name_type.
2.4.5: GSS_Import_name call
Inputs:
o input_name_string OCTET STRING,
o input_name_type OBJECT IDENTIFIER
Outputs:
o major_status INTEGER,
o minor_status INTEGER,
o output_name INTERNAL NAME
Return major_status codes:
o GSS_S_COMPLETE indicates that a valid name representation is
output in output_name and described by the type value in
output_name_type.
o GSS_S_BAD_NAMETYPE indicates that the input_name_type is unsupported
by the applicable underlying GSS-API mechanism(s), so the import
operation could not be completed.
o GSS_S_BAD_NAME indicates that the provided input_name_string
is ill-formed in terms of the input_name_type, so the import
operation could not be completed.
o GSS_S_FAILURE indicates that the requested operation could not
be performed for reasons unspecified at the GSS-API level.
Allows callers to provide a name representation as a contiguous octet
string, designate the type of namespace in conjunction with which it
should be parsed, and convert that representation to an internal form
suitable for input to other GSS-API routines. The syntax of the
input_name_string is defined in conjunction with its associated name
type; depending on the input_name_type, the associated
input_name_string may or may not be a printable string. Note: The
input_name_type argument serves to describe and qualify the
interpretation of the associated input_name_string; it does not
specify the data type of the returned output_name.
If a mechanism claims support for a particular name type, its
GSS_Import_name() operation shall be able to accept all possible
values conformant to the external name syntax as defined for that
name type. These imported values may correspond to:
(1) locally registered entities (for which credentials may be
acquired),
(2) non-local entities (for which local credentials cannot be
acquired, but which may be referenced as targets of initiated
security contexts or initiators of accepted security contexts), or
to
(3) neither of the above.
Determination of whether a particular name belongs to class (1), (2),
or (3) as described above is not guaranteed to be performed by the
GSS_Import_name() function.
The internal name generated by a GSS_Import_name() operation may be a
single-mechanism MN, and is likely to be an MN within a single-
mechanism implementation, but portable callers must not depend on
this property (and must not, therefore, assume that the output from
GSS_Import_name() can be passed directly to GSS_Export_name() without
first being processed through GSS_Canonicalize_name()).
2.4.6: GSS_Release_name call
Inputs:
o name INTERNAL NAME
Outputs:
o major_status INTEGER,
o minor_status INTEGER
Return major_status codes:
o GSS_S_COMPLETE indicates that the storage associated with the
input name was successfully released.
o GSS_S_BAD_NAME indicates that the input name argument did not
contain a valid name.
o GSS_S_FAILURE indicates that the requested operation could not
be performed for reasons unspecified at the GSS-API level.
Allows callers to release the storage associated with an internal
name representation. This call's specific behavior depends on the
language and programming environment within which a GSS-API
implementation operates, and is therefore detailed within applicable
bindings specifications; in particular, this call may be superfluous
within bindings where memory management is automatic.
2.4.7: GSS_Release_buffer call
Inputs:
o buffer OCTET STRING
Outputs:
o major_status INTEGER,
o minor_status INTEGER
Return major_status codes:
o GSS_S_COMPLETE indicates that the storage associated with the
input buffer was successfully released.
o GSS_S_FAILURE indicates that the requested operation could not
be performed for reasons unspecified at the GSS-API level.
Allows callers to release the storage associated with an OCTET STRING
buffer allocated by another GSS-API call. This call's specific
behavior depends on the language and programming environment within
which a GSS-API implementation operates, and is therefore detailed
within applicable bindings specifications; in particular, this call
may be superfluous within bindings where memory management is
automatic.
2.4.8: GSS_Release_OID_set call
Inputs:
o buffer SET OF OBJECT IDENTIFIER
Outputs:
o major_status INTEGER,
o minor_status INTEGER
Return major_status codes:
o GSS_S_COMPLETE indicates that the storage associated with the
input object identifier set was successfully released.
o GSS_S_FAILURE indicates that the requested operation could not
be performed for reasons unspecified at the GSS-API level.
Allows callers to release the storage associated with an object
identifier set object allocated by another GSS-API call. This call's
specific behavior depends on the language and programming environment
within which a GSS-API implementation operates, and is therefore
detailed within applicable bindings specifications; in particular,
this call may be superfluous within bindings where memory management
is automatic.
2.4.9: GSS_Create_empty_OID_set call
Inputs:
o (none)
Outputs:
o major_status INTEGER,
o minor_status INTEGER,
o oid_set SET OF OBJECT IDENTIFIER
Return major_status codes:
o GSS_S_COMPLETE indicates successful completion
o GSS_S_FAILURE indicates that the operation failed
Creates an object identifier set containing no object identifiers, to
which members may be subsequently added using the
GSS_Add_OID_set_member() routine. These routines are intended to be
used to construct sets of mechanism object identifiers, for input to
GSS_Acquire_cred().
2.4.10: GSS_Add_OID_set_member call
Inputs:
o member_oid OBJECT IDENTIFIER,
o oid_set SET OF OBJECT IDENTIFIER
Outputs:
o major_status INTEGER,
o minor_status INTEGER,
Return major_status codes:
o GSS_S_COMPLETE indicates successful completion
o GSS_S_FAILURE indicates that the operation failed
Adds an Object Identifier to an Object Identifier set. This routine
is intended for use in conjunction with GSS_Create_empty_OID_set()
when constructing a set of mechanism OIDs for input to
GSS_Acquire_cred().
2.4.11: GSS_Test_OID_set_member call
Inputs:
o member OBJECT IDENTIFIER,
o set SET OF OBJECT IDENTIFIER
Outputs:
o major_status INTEGER,
o minor_status INTEGER,
o present BOOLEAN
Return major_status codes:
o GSS_S_COMPLETE indicates successful completion
o GSS_S_FAILURE indicates that the operation failed
Interrogates an Object Identifier set to determine whether a
specified Object Identifier is a member. This routine is intended to
be used with OID sets returned by GSS_Indicate_mechs(),
GSS_Acquire_cred(), and GSS_Inquire_cred().
2.4.12: GSS_Release_OID call
Inputs:
o oid OBJECT IDENTIFIER
Outputs:
o major_status INTEGER,
o minor_status INTEGER
Return major_status codes:
o GSS_S_COMPLETE indicates successful completion
o GSS_S_FAILURE indicates that the operation failed
Allows the caller to release the storage associated with an OBJECT
IDENTIFIER buffer allocated by another GSS-API call. This call's
specific behavior depends on the language and programming environment
within which a GSS-API implementation operates, and is therefore
detailed within applicable bindings specifications; in particular,
this call may be superfluous within bindings where memory management
is automatic.
2.4.13: GSS_OID_to_str call
Inputs:
o oid OBJECT IDENTIFIER
Outputs:
o major_status INTEGER,
o minor_status INTEGER,
o oid_str OCTET STRING
Return major_status codes:
o GSS_S_COMPLETE indicates successful completion
o GSS_S_FAILURE indicates that the operation failed
The function GSS_OID_to_str() returns a string representing the input
OID in numeric ASN.1 syntax format (curly-brace enclosed, space-
delimited, e.g., "{2 16 840 1 113687 1 2 1}"). The string is
releasable using GSS_Release_buffer(). If the input "oid" does not
represent a syntactically valid object identifier, GSS_S_FAILURE
status is returned and the returned oid_str result is NULL.
2.4.14: GSS_Str_to_OID call
Inputs:
o oid_str OCTET STRING
Outputs:
o major_status INTEGER,
o minor_status INTEGER,
o oid OBJECT IDENTIFIER
Return major_status codes:
o GSS_S_COMPLETE indicates successful completion
o GSS_S_FAILURE indicates that the operation failed
The function GSS_Str_to_OID() constructs and returns an OID from its
printable form; implementations should be able to accept the numeric
ASN.1 syntax form as described for GSS_OID_to_str(), and this form
should be used for portability, but implementations of this routine
may also accept other formats (e.g., "1.2.3.3"). The OID is suitable
for release using the function GSS_Release_OID(). If the input
oid_str cannot be translated into an OID, GSS_S_FAILURE status is
returned and the "oid" result is NULL.
2.4.15: GSS_Inquire_names_for_mech call
Input:
o input_mech_type OBJECT IDENTIFIER, -- mechanism type
Outputs:
o major_status INTEGER,
o minor_status INTEGER,
o name_type_set SET OF OBJECT IDENTIFIER
Return major_status codes:
o GSS_S_COMPLETE indicates that the output name_type_set contains
a list of name types which are supported by the locally available
mechanism identified by input_mech_type.
o GSS_S_BAD_MECH indicates that the mechanism identified by
input_mech_type was unsupported within the local implementation,
causing the query to fail.
o GSS_S_FAILURE indicates that the requested operation could not
be performed for reasons unspecified at the GSS-API level.
Allows callers to determine the set of name types which are
supportable by a specific locally-available mechanism.
2.4.16: GSS_Inquire_mechs_for_name call
Inputs:
o input_name INTERNAL NAME,
Outputs:
o major_status INTEGER,
o minor_status INTEGER,
o mech_types SET OF OBJECT IDENTIFIER
Return major_status codes:
o GSS_S_COMPLETE indicates that a set of object identifiers,
corresponding to the set of mechanisms suitable for processing
the input_name, is available in mech_types.
o GSS_S_BAD_NAME indicates that the input_name could not be
processed.
o GSS_S_BAD_NAMETYPE indicates that the type of the input_name
is unsupported by the GSS-API implementation.
o GSS_S_FAILURE indicates that the requested operation could not
be performed for reasons unspecified at the GSS-API level.
This routine returns the mechanism set with which the input_name may
be processed. After use, the mech_types object should be freed by
the caller via the GSS_Release_OID_set() call. Note: it is
anticipated that implementations of GSS_Inquire_mechs_for_name() will
commonly operate based on type information describing the
capabilities of available mechanisms; it is not guaranteed that all
identified mechanisms will necessarily be able to canonicalize (via
GSS_Canonicalize_name()) a particular name.
2.4.17: GSS_Canonicalize_name call
Inputs:
o input_name INTERNAL NAME,
o mech_type OBJECT IDENTIFIER -- must be explicit mechanism,
not "default" specifier
Outputs:
o major_status INTEGER,
o minor_status INTEGER,
o output_name INTERNAL NAME
Return major_status codes:
o GSS_S_COMPLETE indicates that a mechanism-specific reduction of
the input_name, as processed by the mechanism identified by
mech_type, is available in output_name.
o GSS_S_BAD_MECH indicates that the identified mechanism is
unsupported.
o GSS_S_BAD_NAMETYPE indicates that the input name does not
contain an element with suitable type for processing by the
identified mechanism.
o GSS_S_BAD_NAME indicates that the input name contains an
element with suitable type for processing by the identified
mechanism, but that this element could not be processed
successfully.
o GSS_S_FAILURE indicates that the requested operation could not
be performed for reasons unspecified at the GSS-API level.
This routine reduces a GSS-API internal name, which may in general
contain elements corresponding to multiple mechanisms, to a
mechanism-specific Mechanism Name (MN) by applying the translations
corresponding to the mechanism identified by mech_type.
2.4.18: GSS_Export_name call
Inputs:
o input_name INTERNAL NAME, -- required to be MN
Outputs:
o major_status INTEGER,
o minor_status INTEGER,
o output_name OCTET STRING
Return major_status codes:
o GSS_S_COMPLETE indicates that a flat representation of the
input name is available in output_name.
o GSS_S_NAME_NOT_MN indicates that the input name contained
elements corresponding to multiple mechanisms, so cannot
be exported into a single-mechanism flat form.
o GSS_S_BAD_NAME indicates that the input name was an MN,
but could not be processed.
o GSS_S_BAD_NAMETYPE indicates that the input name was an MN,
but that its type is unsupported by the GSS-API implementation.
o GSS_S_FAILURE indicates that the requested operation could not
be performed for reasons unspecified at the GSS-API level.
This routine creates a flat name representation, suitable for
bytewise comparison or for input to GSS_Import_name() in conjunction
with the reserved GSS-API Exported Name Object OID, from a internal-
form Mechanism Name (MN) as emitted, e.g., by GSS_Canonicalize_name()
or GSS_Accept_sec_context().
The emitted GSS-API Exported Name Object is self-describing; no
associated parameter-level OID need be emitted by this call. This
flat representation consists of a mechanism-independent wrapper
layer, defined in Section 3.2 of this document, enclosing a
mechanism-defined name representation.
In all cases, the flat name output by GSS_Export_name() to correspond
to a particular input MN must be invariant over time within a
particular installation.
The GSS_S_NAME_NOT_MN status code is provided to enable
implementations to reject input names which are not MNs. It is not,
however, required for purposes of conformance to this specification
that all non-MN input names must necessarily be rejected.
2.4.19: GSS_Duplicate_name call
Inputs:
o src_name INTERNAL NAME
Outputs:
o major_status INTEGER,
o minor_status INTEGER,
o dest_name INTERNAL NAME
Return major_status codes:
o GSS_S_COMPLETE indicates that dest_name references an internal
name object containing the same name as passed to src_name.
o GSS_S_BAD_NAME indicates that the input name was invalid.
o GSS_S_BAD_NAMETYPE indicates that the input name's type
is unsupported by the GSS-API implementation.
o GSS_S_FAILURE indicates that the requested operation could not
be performed for reasons unspecified at the GSS-API level.
This routine takes input internal name src_name, and returns another
reference (dest_name) to that name which can be used even if src_name
is later freed. (Note: This may be implemented by copying or through
use of reference counts.)
3: Data Structure Definitions for GSS-V2 Usage
Subsections of this section define, for interoperability and
portability purposes, certain data structures for use with GSS-V2.
3.1: Mechanism-Independent Token Format
This section specifies a mechanism-independent level of encapsulating
representation for the initial token of a GSS-API context
establishment sequence, incorporating an identifier of the mechanism
type to be used on that context and enabling tokens to be interpreted
unambiguously at GSS-API peers. Use of this format is required for
initial context establishment tokens of Internet standards-track
GSS-API mechanisms; use in non-initial tokens is optional.
The encoding format for the token tag is derived from ASN.1 and DER
(per illustrative ASN.1 syntax included later within this
subsection), but its concrete representation is defined directly in
terms of octets rather than at the ASN.1 level in order to facilitate
interoperable implementation without use of general ASN.1 processing
code. The token tag consists of the following elements, in order:
1. 0x60 -- Tag for [APPLICATION 0] SEQUENCE; indicates that
constructed form, definite length encoding follows.
2. Token length octets, specifying length of subsequent data
(i.e., the summed lengths of elements 3-5 in this list, and of the
mechanism-defined token object following the tag). This element
comprises a variable number of octets:
2a. If the indicated value is less than 128, it shall be
represented in a single octet with bit 8 (high order) set to "0"
and the remaining bits representing the value.
2b. If the indicated value is 128 or more, it shall be represented
in two or more octets, with bit 8 of the first octet set to "1"
and the remaining bits of the first octet specifying the number of
additional octets. The subsequent octets carry the value, 8 bits
per octet, most significant digit first. The minimum number of
octets shall be used to encode the length (i.e., no octets
representing leading zeros shall be included within the length
encoding).
3. 0x06 -- Tag for OBJECT IDENTIFIER
4. Object identifier length -- length (number of octets) of the
encoded object identifier contained in element 5, encoded per
rules as described in 2a. and 2b. above.
5. Object identifier octets -- variable number of octets, encoded
per ASN.1 BER rules:
5a. The first octet contains the sum of two values: (1) the top-
level object identifier component, multiplied by 40 (decimal), and
(2) the second-level object identifier component. This special
case is the only point within an object identifier encoding where
a single octet represents contents of more than one component.
5b. Subsequent octets, if required, encode successively-lower
components in the represented object identifier. A component's
encoding may span multiple octets, encoding 7 bits per octet (most
significant bits first) and with bit 8 set to "1" on all but the
final octet in the component's encoding. The minimum number of
octets shall be used to encode each component (i.e., no octets
representing leading zeros shall be included within a component's
encoding).
(Note: In many implementations, elements 3-5 may be stored and
referenced as a contiguous string constant.)
The token tag is immediately followed by a mechanism-defined token
object. Note that no independent size specifier intervenes following
the object identifier value to indicate the size of the mechanism-
defined token object. While ASN.1 usage within mechanism-defined
tokens is permitted, there is no requirement that the mechanism-
specific innerContextToken, innerMsgToken, and sealedUserData data
elements must employ ASN.1 BER/DER encoding conventions.
The following ASN.1 syntax is included for descriptive purposes only,