an MN; the exception to this is if the <input_name_type> indicates
that the contiguous string provided via the <input_name_buffer>
parameter is of type GSS_C_NT_EXPORT_NAME, in which case the returned
internal name will be an MN for the mechanism that exported the name.
Parameters:
minor_status Integer, modify
Mechanism specific status code
input_name_buffer buffer, octet-string, read
buffer containing contiguous string name to convert
input_name_type Object ID, read, optional
Object ID specifying type of printable
name. Applications may specify either
GSS_C_NO_OID to use a mechanism-specific
default printable syntax, or an OID recognized
by the GSS-API implementation to name a
specific namespace.
output_name gss_name_t, modify
returned name in internal form. Storage
associated with this name must be freed
by the application after use with a call
to gss_release_name().
Function value: GSS status code
GSS_S_COMPLETE Successful completion
GSS_S_BAD_NAMETYPE The input_name_type was unrecognized
GSS_S_BAD_NAME The input_name parameter could not be interpreted
as a name of the specified type
GSS_S_BAD_MECH The input name-type was GSS_C_NT_EXPORT_NAME,
but the mechanism contained within the
input-name is not supported
5.17. gss_import_sec_context
OM_uint32 gss_import_sec_context (
OM_uint32 *minor_status,
const gss_buffer_t interprocess_token,
gss_ctx_id_t *context_handle)
Purpose:
Allows a process to import a security context established by another
process. A given interprocess token may be imported only once. See
gss_export_sec_context.
Parameters:
minor_status Integer, modify
Mechanism specific status code
interprocess_token buffer, opaque, modify
token received from exporting process
context_handle gss_ctx_id_t, modify
context handle of newly reactivated context.
Resources associated with this context handle
must be released by the application after use
with a call to gss_delete_sec_context().
Function value: GSS status code
GSS_S_COMPLETE Successful completion.
GSS_S_NO_CONTEXT The token did not contain a valid context
reference.
GSS_S_DEFECTIVE_TOKEN The token was invalid.
GSS_S_UNAVAILABLE The operation is unavailable.
GSS_S_UNAUTHORIZED Local policy prevents the import of this context
by the current process.
5.18. gss_indicate_mechs
OM_uint32 gss_indicate_mechs (
OM_uint32 *minor_status,
gss_OID_set *mech_set)
Purpose:
Allows an application to determine which underlying security
mechanisms are available.
Parameters:
minor_status Integer, modify
Mechanism specific status code.
mech_set set of Object IDs, modify
set of implementation-supported mechanisms.
The returned gss_OID_set value will be a
dynamically-allocated OID set, that should
be released by the caller after use with a
call to gss_release_oid_set().
Function value: GSS status code
GSS_S_COMPLETE Successful completion
5.19. gss_init_sec_context
OM_uint32 gss_init_sec_context (
OM_uint32 *minor_status,
const gss_cred_id_t initiator_cred_handle,
gss_ctx_id_t *context_handle,\
const gss_name_t target_name,
const gss_OID mech_type,
OM_uint32 req_flags,
OM_uint32 time_req,
const gss_channel_bindings_t input_chan_bindings,
const gss_buffer_t input_token
gss_OID *actual_mech_type,
gss_buffer_t output_token,
OM_uint32 *ret_flags,
OM_uint32 *time_rec )
Purpose:
Initiates the establishment of a security context between the
application and a remote peer. Initially, the input_token parameter
should be specified either as GSS_C_NO_BUFFER, or as a pointer to a
gss_buffer_desc object whose length field contains the value zero.
The routine may return a output_token which should be transferred to
the peer application, where the peer application will present it to
gss_accept_sec_context. If no token need be sent,
gss_init_sec_context will indicate this by setting the length field
of the output_token argument to zero. To complete the context
establishment, one or more reply tokens may be required from the peer
application; if so, gss_init_sec_context will return a status
containing the supplementary information bit GSS_S_CONTINUE_NEEDED.
In this case, gss_init_sec_context should be called again when the
reply token is received from the peer application, passing the reply
token to gss_init_sec_context via the input_token parameters.
Portable applications should be constructed to use the token length
and return status to determine whether a token needs to be sent or
waited for. Thus a typical portable caller should always invoke
gss_init_sec_context within a loop:
int context_established = 0;
gss_ctx_id_t context_hdl = GSS_C_NO_CONTEXT;
...
input_token->length = 0;
while (!context_established) {
maj_stat = gss_init_sec_context(&min_stat,
cred_hdl,
&context_hdl,
target_name,
desired_mech,
desired_services,
desired_time,
input_bindings,
input_token,
&actual_mech,
output_token,
&actual_services,
&actual_time);
if (GSS_ERROR(maj_stat)) {
report_error(maj_stat, min_stat);
};
if (output_token->length != 0) {
send_token_to_peer(output_token);
gss_release_buffer(&min_stat, output_token)
};
if (GSS_ERROR(maj_stat)) {
if (context_hdl != GSS_C_NO_CONTEXT)
gss_delete_sec_context(&min_stat,
&context_hdl,
GSS_C_NO_BUFFER);
break;
};
if (maj_stat & GSS_S_CONTINUE_NEEDED) {
receive_token_from_peer(input_token);
} else {
context_established = 1;
};
};
Whenever the routine returns a major status that includes the value
GSS_S_CONTINUE_NEEDED, the context is not fully established and the
following restrictions apply to the output parameters:
The value returned via the time_rec parameter is undefined Unless
the accompanying ret_flags parameter contains the bit
GSS_C_PROT_READY_FLAG, indicating that per-message services may be
applied in advance of a successful completion status, the value
returned via the actual_mech_type parameter is undefined until the
routine returns a major status value of GSS_S_COMPLETE.
The values of the GSS_C_DELEG_FLAG, GSS_C_MUTUAL_FLAG,
GSS_C_REPLAY_FLAG, GSS_C_SEQUENCE_FLAG, GSS_C_CONF_FLAG,
GSS_C_INTEG_FLAG and GSS_C_ANON_FLAG bits returned via the
ret_flags parameter should contain the values that the
implementation expects would be valid if context establishment
were to succeed. In particular, if the application has requested
a service such as delegation or anonymous authentication via the
req_flags argument, and such a service is unavailable from the
underlying mechanism, gss_init_sec_context should generate a token
that will not provide the service, and indicate via the ret_flags
argument that the service will not be supported. The application
may choose to abort the context establishment by calling
gss_delete_sec_context (if it cannot continue in the absence of
the service), or it may choose to transmit the token and continue
context establishment (if the service was merely desired but not
mandatory).
The values of the GSS_C_PROT_READY_FLAG and GSS_C_TRANS_FLAG bits
within ret_flags should indicate the actual state at the time
gss_init_sec_context returns, whether or not the context is fully
established.
GSS-API implementations that support per-message protection are
encouraged to set the GSS_C_PROT_READY_FLAG in the final ret_flags
returned to a caller (i.e. when accompanied by a GSS_S_COMPLETE
status code). However, applications should not rely on this
behavior as the flag was not defined in Version 1 of the GSS-API.
Instead, applications should determine what per-message services
are available after a successful context establishment according
to the GSS_C_INTEG_FLAG and GSS_C_CONF_FLAG values.
All other bits within the ret_flags argument should be set to
zero.
If the initial call of gss_init_sec_context() fails, the
implementation should not create a context object, and should leave
the value of the context_handle parameter set to GSS_C_NO_CONTEXT to
indicate this. In the event of a failure on a subsequent call, the
implementation is permitted to delete the "half-built" security
context (in which case it should set the context_handle parameter to
GSS_C_NO_CONTEXT), but the preferred behavior is to leave the
security context untouched for the application to delete (using
gss_delete_sec_context).
During context establishment, the informational status bits
GSS_S_OLD_TOKEN and GSS_S_DUPLICATE_TOKEN indicate fatal errors, and
GSS-API mechanisms should always return them in association with a
routine error of GSS_S_FAILURE. This requirement for pairing did not
exist in version 1 of the GSS-API specification, so applications that
wish to run over version 1 implementations must special-case these
codes.
Parameters:
minor_status Integer, modify
Mechanism specific status code.
initiator_cred_handle gss_cred_id_t, read, optional
handle for credentials claimed. Supply
GSS_C_NO_CREDENTIAL to act as a default
initiator principal. If no default
initiator is defined, the function will
return GSS_S_NO_CRED.
context_handle gss_ctx_id_t, read/modify
context handle for new context. Supply
GSS_C_NO_CONTEXT for first call; use value
returned by first call in continuation calls.
Resources associated with this context-handle
must be released by the application after use
with a call to gss_delete_sec_context().
target_name gss_name_t, read
Name of target
mech_type OID, read, optional
Object ID of desired mechanism. Supply
GSS_C_NO_OID to obtain an implementation
specific default
req_flags bit-mask, read
Contains various independent flags, each of
which requests that the context support a
specific service option. Symbolic
names are provided for each flag, and the
symbolic names corresponding to the required
flags should be logically-ORed
together to form the bit-mask value. The
flags are:
GSS_C_DELEG_FLAG
True - Delegate credentials to remote peer
False - Don't delegate
GSS_C_MUTUAL_FLAG
True - Request that remote peer
authenticate itself
False - Authenticate self to remote peer
only
GSS_C_REPLAY_FLAG
True - Enable replay detection for
messages protected with gss_wrap
or gss_get_mic
False - Don't attempt to detect
replayed messages
GSS_C_SEQUENCE_FLAG
True - Enable detection of out-of-sequence
protected messages
False - Don't attempt to detect
out-of-sequence messages
GSS_C_CONF_FLAG
True - Request that confidentiality service
be made available (via gss_wrap)
False - No per-message confidentiality service
is required.
GSS_C_INTEG_FLAG
True - Request that integrity service be
made available (via gss_wrap or
gss_get_mic)
False - No per-message integrity service
is required.
GSS_C_ANON_FLAG
True - Do not reveal the initiator's
identity to the acceptor.
False - Authenticate normally.
time_req Integer, read, optional
Desired number of seconds for which context
should remain valid. Supply 0 to request a
default validity period.
input_chan_bindings channel bindings, read, optional
Application-specified bindings. Allows
application to securely bind channel
identification information to the security
context. Specify GSS_C_NO_CHANNEL_BINDINGS
if channel bindings are not used.
input_token buffer, opaque, read, optional (see text)
Token received from peer application.
Supply GSS_C_NO_BUFFER, or a pointer to
a buffer containing the value GSS_C_EMPTY_BUFFER
on initial call.
actual_mech_type OID, modify, optional
Actual mechanism used. The OID returned via
this parameter will be a pointer to static
storage that should be treated as read-only;
In particular the application should not attempt
to free it. Specify NULL if not required.
output_token buffer, opaque, modify
token to be sent to peer application. If
the length field of the returned buffer is
zero, no token need be sent to the peer
application. Storage associated with this
buffer must be freed by the application
after use with a call to gss_release_buffer().
ret_flags bit-mask, modify, optional
Contains various independent flags, each of which
indicates that the context supports a specific
service option. Specify NULL if not
required. Symbolic names are provided
for each flag, and the symbolic names
corresponding to the required flags should be
logically-ANDed with the ret_flags value to test
whether a given option is supported by the
context. The flags are:
GSS_C_DELEG_FLAG
True - Credentials were delegated to
the remote peer
False - No credentials were delegated
GSS_C_MUTUAL_FLAG
True - The remote peer has authenticated
itself.
False - Remote peer has not authenticated
itself.
GSS_C_REPLAY_FLAG
True - replay of protected messages
will be detected
False - replayed messages will not be
detected
GSS_C_SEQUENCE_FLAG
True - out-of-sequence protected
messages will be detected
False - out-of-sequence messages will
not be detected
GSS_C_CONF_FLAG
True - Confidentiality service may be
invoked by calling gss_wrap routine
False - No confidentiality service (via
gss_wrap) available. gss_wrap will
provide message encapsulation,
data-origin authentication and
integrity services only.
GSS_C_INTEG_FLAG
True - Integrity service may be invoked by
calling either gss_get_mic or gss_wrap
routines.
False - Per-message integrity service
unavailable.
GSS_C_ANON_FLAG
True - The initiator's identity has not been
revealed, and will not be revealed if
any emitted token is passed to the
acceptor.
False - The initiator's identity has been or
will be authenticated normally.
GSS_C_PROT_READY_FLAG
True - Protection services (as specified
by the states of the GSS_C_CONF_FLAG
and GSS_C_INTEG_FLAG) are available for
use if the accompanying major status
return value is either GSS_S_COMPLETE or
GSS_S_CONTINUE_NEEDED.
False - Protection services (as specified
by the states of the GSS_C_CONF_FLAG
and GSS_C_INTEG_FLAG) are available
only if the accompanying major status
return value is GSS_S_COMPLETE.
GSS_C_TRANS_FLAG
True - The resultant security context may
be transferred to other processes via
a call to gss_export_sec_context().
False - The security context is not
transferable.
All other bits should be set to zero.
time_rec Integer, modify, optional
number of seconds for which the context
will remain valid. If the implementation does
not support context expiration, the value
GSS_C_INDEFINITE will be returned. Specify
NULL if not required.
Function value: GSS status code
GSS_S_COMPLETE Successful completion
GSS_S_CONTINUE_NEEDED Indicates that a token from the peer
application is required to complete the
context, and that gss_init_sec_context
must be called again with that token.
GSS_S_DEFECTIVE_TOKEN Indicates that consistency checks performed
on the input_token failed
GSS_S_DEFECTIVE_CREDENTIAL Indicates that consistency checks
performed on the credential failed.
GSS_S_NO_CRED The supplied credentials were not valid for
context initiation, or the credential handle
did not reference any credentials.
GSS_S_CREDENTIALS_EXPIRED The referenced credentials have expired
GSS_S_BAD_BINDINGS The input_token contains different channel
bindings to those specified via the
input_chan_bindings parameter
GSS_S_BAD_SIG The input_token contains an invalid MIC, or a MIC
that could not be verified
GSS_S_OLD_TOKEN The input_token was too old. This is a fatal
error during context establishment
GSS_S_DUPLICATE_TOKEN The input_token is valid, but is a duplicate
of a token already processed. This is a
fatal error during context establishment.
GSS_S_NO_CONTEXT Indicates that the supplied context handle did
not refer to a valid context
GSS_S_BAD_NAMETYPE The provided target_name parameter contained an
invalid or unsupported type of name
GSS_S_BAD_NAME The provided target_name parameter was ill-formed.
GSS_S_BAD_MECH The specified mechanism is not supported by the
provided credential, or is unrecognized by the
implementation.
5.20. gss_inquire_context
OM_uint32 gss_inquire_context (
OM_uint32 *minor_status,
const gss_ctx_id_t context_handle,
gss_name_t *src_name,
gss_name_t *targ_name,
OM_uint32 *lifetime_rec,
gss_OID *mech_type,
OM_uint32 *ctx_flags,
int *locally_initiated,
int *open )
Purpose:
Obtains information about a security context. The caller must
already have obtained a handle that refers to the context, although
the context need not be fully established.
Parameters:
minor_status Integer, modify
Mechanism specific status code
context_handle gss_ctx_id_t, read
A handle that refers to the security context.
src_name gss_name_t, modify, optional
The name of the context initiator.
If the context was established using anonymous
authentication, and if the application invoking
gss_inquire_context is the context acceptor,
an anonymous name will be returned. Storage
associated with this name must be freed by the
application after use with a call to
gss_release_name(). Specify NULL if not
required.
targ_name gss_name_t, modify, optional
The name of the context acceptor.
Storage associated with this name must be
freed by the application after use with a call
to gss_release_name(). If the context acceptor
did not authenticate itself, and if the initiator
did not specify a target name in its call to
gss_init_sec_context(), the value GSS_C_NO_NAME
will be returned. Specify NULL if not required.
lifetime_rec Integer, modify, optional
The number of seconds for which the context
will remain valid. If the context has
expired, this parameter will be set to zero.
If the implementation does not support
context expiration, the value
GSS_C_INDEFINITE will be returned. Specify
NULL if not required.
mech_type gss_OID, modify, optional
The security mechanism providing the
context. The returned OID will be a
pointer to static storage that should
be treated as read-only by the application;
in particular the application should not
attempt to free it. Specify NULL if not
required.
ctx_flags bit-mask, modify, optional
Contains various independent flags, each of
which indicates that the context supports
(or is expected to support, if ctx_open is
false) a specific service option. If not
needed, specify NULL. Symbolic names are
provided for each flag, and the symbolic names
corresponding to the required flags
should be logically-ANDed with the ret_flags
value to test whether a given option is
supported by the context. The flags are:
GSS_C_DELEG_FLAG
True - Credentials were delegated from
the initiator to the acceptor.
False - No credentials were delegated
GSS_C_MUTUAL_FLAG
True - The acceptor was authenticated
to the initiator
False - The acceptor did not authenticate
itself.
GSS_C_REPLAY_FLAG
True - replay of protected messages
will be detected
False - replayed messages will not be
detected
GSS_C_SEQUENCE_FLAG
True - out-of-sequence protected
messages will be detected
False - out-of-sequence messages will not
be detected
GSS_C_CONF_FLAG
True - Confidentiality service may be invoked
by calling gss_wrap routine
False - No confidentiality service (via
gss_wrap) available. gss_wrap will
provide message encapsulation,
data-origin authentication and
integrity services only.
GSS_C_INTEG_FLAG
True - Integrity service may be invoked by
calling either gss_get_mic or gss_wrap
routines.
False - Per-message integrity service
unavailable.
GSS_C_ANON_FLAG
True - The initiator's identity will not
be revealed to the acceptor.
The src_name parameter (if
requested) contains an anonymous
internal name.
False - The initiator has been
authenticated normally.
GSS_C_PROT_READY_FLAG
True - Protection services (as specified
by the states of the GSS_C_CONF_FLAG
and GSS_C_INTEG_FLAG) are available
for use.
False - Protection services (as specified
by the states of the GSS_C_CONF_FLAG
and GSS_C_INTEG_FLAG) are available
only if the context is fully
established (i.e. if the open parameter
is non-zero).
GSS_C_TRANS_FLAG
True - The resultant security context may
be transferred to other processes via
a call to gss_export_sec_context().
False - The security context is not
transferable.
locally_initiated Boolean, modify
Non-zero if the invoking application is the
context initiator.
Specify NULL if not required.
open Boolean, modify
Non-zero if the context is fully established;
Zero if a context-establishment token
is expected from the peer application.
Specify NULL if not required.
Function value: GSS status code
GSS_S_COMPLETE Successful completion
GSS_S_NO_CONTEXT The referenced context could not be accessed.
5.21. gss_inquire_cred
OM_uint32 gss_inquire_cred (
OM_uint32 *minor_status,
const gss_cred_id_t cred_handle,
gss_name_t *name,
OM_uint32 *lifetime,
gss_cred_usage_t *cred_usage,
gss_OID_set *mechanisms )
Purpose:
Obtains information about a credential.
Parameters:
minor_status Integer, modify
Mechanism specific status code
cred_handle gss_cred_id_t, read
A handle that refers to the target credential.
Specify GSS_C_NO_CREDENTIAL to inquire about
the default initiator principal.
name gss_name_t, modify, optional
The name whose identity the credential asserts.
Storage associated with this name should be freed
by the application after use with a call to
gss_release_name(). Specify NULL if not required.
lifetime Integer, modify, optional
The number of seconds for which the credential
will remain valid. If the credential has
expired, this parameter will be set to zero.
If the implementation does not support
credential expiration, the value
GSS_C_INDEFINITE will be returned. Specify
NULL if not required.
cred_usage gss_cred_usage_t, modify, optional
How the credential may be used. One of the
following:
GSS_C_INITIATE
GSS_C_ACCEPT
GSS_C_BOTH
Specify NULL if not required.
mechanisms gss_OID_set, modify, optional
Set of mechanisms supported by the credential.
Storage associated with this OID set must be
freed by the application after use with a call
to gss_release_oid_set(). Specify NULL if not
required.
Function value: GSS status code
GSS_S_COMPLETE Successful completion
GSS_S_NO_CRED The referenced credentials could not be accessed.
GSS_S_DEFECTIVE_CREDENTIAL The referenced credentials were invalid.
GSS_S_CREDENTIALS_EXPIRED The referenced credentials have expired.
If the lifetime parameter was not passed as NULL,
it will be set to 0.
5.22. gss_inquire_cred_by_mech
OM_uint32 gss_inquire_cred_by_mech (
OM_uint32 *minor_status,
const gss_cred_id_t cred_handle,
const gss_OID mech_type,
gss_name_t *name,
OM_uint32 *initiator_lifetime,
OM_uint32 *acceptor_lifetime,
gss_cred_usage_t *cred_usage )
Purpose:
Obtains per-mechanism information about a credential.
Parameters:
minor_status Integer, modify
Mechanism specific status code
cred_handle gss_cred_id_t, read
A handle that refers to the target credential.
Specify GSS_C_NO_CREDENTIAL to inquire about
the default initiator principal.
mech_type gss_OID, read
The mechanism for which information should be
returned.
name gss_name_t, modify, optional
The name whose identity the credential asserts.
Storage associated with this name must be
freed by the application after use with a call
to gss_release_name(). Specify NULL if not
required.
initiator_lifetime Integer, modify, optional
The number of seconds for which the credential
will remain capable of initiating security contexts
under the specified mechanism. If the credential
can no longer be used to initiate contexts, or if
the credential usage for this mechanism is
GSS_C_ACCEPT, this parameter will be set to zero.
If the implementation does not support expiration
of initiator credentials, the value
GSS_C_INDEFINITE will be returned. Specify NULL
if not required.
acceptor_lifetime Integer, modify, optional
The number of seconds for which the credential
will remain capable of accepting security contexts
under the specified mechanism. If the credential
can no longer be used to accept contexts, or if
the credential usage for this mechanism is
GSS_C_INITIATE, this parameter will be set to zero.
If the implementation does not support expiration
of acceptor credentials, the value GSS_C_INDEFINITE
will be returned. Specify NULL if not required.
cred_usage gss_cred_usage_t, modify, optional
How the credential may be used with the specified
mechanism. One of the following:
GSS_C_INITIATE
GSS_C_ACCEPT
GSS_C_BOTH
Specify NULL if not required.
Function value: GSS status code
GSS_S_COMPLETE Successful completion
GSS_S_NO_CRED The referenced credentials could not be accessed.
GSS_S_DEFECTIVE_CREDENTIAL The referenced credentials were invalid.
GSS_S_CREDENTIALS_EXPIRED The referenced credentials have expired.
If the lifetime parameter was not passed as NULL,
it will be set to 0.
5.23. gss_inquire_mechs_for_name
OM_uint32 gss_inquire_mechs_for_name (
OM_uint32 *minor_status,
const gss_name_t input_name,
gss_OID_set *mech_types )
Purpose:
Returns the set of mechanisms supported by the GSS-API implementation
that may be able to process the specified name.
Each mechanism returned will recognize at least one element within
the name. It is permissible for this routine to be implemented
within a mechanism-independent GSS-API layer, using the type
information contained within the presented name, and based on
registration information provided by individual mechanism
implementations. This means that the returned mech_types set may
indicate that a particular mechanism will understand the name when in
fact it would refuse to accept the name as input to
gss_canonicalize_name, gss_init_sec_context, gss_acquire_cred or
gss_add_cred (due to some property of the specific name, as opposed
to the name type). Thus this routine should be used only as a pre-
filter for a call to a subsequent mechanism-specific routine.
Parameters:
minor_status Integer, modify
Implementation specific status code.
input_name gss_name_t, read
The name to which the inquiry relates.
mech_types gss_OID_set, modify
Set of mechanisms that may support the
specified name. The returned OID set
must be freed by the caller after use
with a call to gss_release_oid_set().
Function value: GSS status code
GSS_S_COMPLETE Successful completion
GSS_S_BAD_NAME The input_name parameter was ill-formed.
GSS_S_BAD_NAMETYPE The input_name parameter contained an invalid or
unsupported type of name
5.24. gss_inquire_names_for_mech
OM_uint32 gss_inquire_names_for_mech (
OM_uint32 *minor_status,
const gss_OID mechanism,
gss_OID_set *name_types)
Purpose:
Returns the set of nametypes supported by the specified mechanism.
Parameters:
minor_status Integer, modify
Implementation specific status code.
mechanism gss_OID, read
The mechanism to be interrogated.
name_types gss_OID_set, modify
Set of name-types supported by the specified
mechanism. The returned OID set must be
freed by the application after use with a
call to gss_release_oid_set().
Function value: GSS status code
GSS_S_COMPLETE Successful completion
5.25. gss_process_context_token
OM_uint32 gss_process_context_token (
OM_uint32 *minor_status,
const gss_ctx_id_t context_handle,
const gss_buffer_t token_buffer)
Purpose:
Provides a way to pass an asynchronous token to the security service.
Most context-level tokens are emitted and processed synchronously by
gss_init_sec_context and gss_accept_sec_context, and the application
is informed as to whether further tokens are expected by the
GSS_C_CONTINUE_NEEDED major status bit. Occasionally, a mechanism
may need to emit a context-level token at a point when the peer
entity is not expecting a token. For example, the initiator's final
call to gss_init_sec_context may emit a token and return a status of
GSS_S_COMPLETE, but the acceptor's call to gss_accept_sec_context may
fail. The acceptor's mechanism may wish to send a token containing
an error indication to the initiator, but the initiator is not
expecting a token at this point, believing that the context is fully
established. Gss_process_context_token provides a way to pass such a
token to the mechanism at any time.
Parameters:
minor_status Integer, modify
Implementation specific status code.
context_handle gss_ctx_id_t, read
context handle of context on which token is to
be processed
token_buffer buffer, opaque, read
token to process
Function value: GSS status code
GSS_S_COMPLETE Successful completion
GSS_S_DEFECTIVE_TOKEN Indicates that consistency checks performed
on the token failed
GSS_S_NO_CONTEXT The context_handle did not refer to a valid context
5.26. gss_release_buffer
OM_uint32 gss_release_buffer (
OM_uint32 *minor_status,
gss_buffer_t buffer)
Purpose:
Free storage associated with a buffer. The storage must have been
allocated by a GSS-API routine. In addition to freeing the
associated storage, the routine will zero the length field in the
descriptor to which the buffer parameter refers, and implementations
are encouraged to additionally set the pointer field in the
descriptor to NULL. Any buffer object returned by a GSS-API routine
may be passed to gss_release_buffer (even if there is no storage
associated with the buffer).
Parameters:
minor_status Integer, modify
Mechanism specific status code
buffer buffer, modify
The storage associated with the buffer will be
deleted. The gss_buffer_desc object will not
be freed, but its length field will be zeroed.
Function value: GSS status code
GSS_S_COMPLETE Successful completion
5.27. gss_release_cred
OM_uint32 gss_release_cred (
OM_uint32 *minor_status,
gss_cred_id_t *cred_handle)
Purpose:
Informs GSS-API that the specified credential handle is no longer
required by the application, and frees associated resources.
Implementations are encouraged to set the cred_handle to
GSS_C_NO_CREDENTIAL on successful completion of this call.
Parameters:
cred_handle gss_cred_id_t, modify, optional
Opaque handle identifying credential
to be released. If GSS_C_NO_CREDENTIAL
is supplied, the routine will complete
successfully, but will do nothing.
minor_status Integer, modify
Mechanism specific status code.
Function value: GSS status code
GSS_S_COMPLETE Successful completion
GSS_S_NO_CRED Credentials could not be accessed.
5.28. gss_release_name
OM_uint32 gss_release_name (
OM_uint32 *minor_status,
gss_name_t *name)
Purpose:
Free GSSAPI-allocated storage associated with an internal-form name.
Implementations are encouraged to set the name to GSS_C_NO_NAME on
successful completion of this call.
Parameters:
minor_status Integer, modify
Mechanism specific status code
name gss_name_t, modify
The name to be deleted
Function value: GSS status code
GSS_S_COMPLETE Successful completion
GSS_S_BAD_NAME The name parameter did not contain a valid name
5.29. gss_release_oid_set
OM_uint32 gss_release_oid_set (
OM_uint32 *minor_status,
gss_OID_set *set)
Purpose:
Free storage associated with a GSSAPI-generated gss_OID_set object.
The set parameter must refer to an OID-set that was returned from a
GSS-API routine. gss_release_oid_set() will free the storage
associated with each individual member OID, the OID set's elements
array, and the gss_OID_set_desc.
Implementations are encouraged to set the gss_OID_set parameter to
GSS_C_NO_OID_SET on successful completion of this routine.
Parameters:
minor_status Integer, modify
Mechanism specific status code
set Set of Object IDs, modify
The storage associated with the gss_OID_set
will be deleted.
Function value: GSS status code
GSS_S_COMPLETE Successful completion
5.30. gss_test_oid_set_member
OM_uint32 gss_test_oid_set_member (
OM_uint32 *minor_status,
const gss_OID member,
const gss_OID_set set,
int *present)
Purpose:
Interrogate 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(), but will also work with user-generated sets.
Parameters:
minor_status Integer, modify
Mechanism specific status code
member Object ID, read
The object identifier whose presence
is to be tested.
set Set of Object ID, read
The Object Identifier set.
present Boolean, modify
non-zero if the specified OID is a member
of the set, zero if not.
Function value: GSS status code
GSS_S_COMPLETE Successful completion
5.31. gss_unwrap
OM_uint32 gss_unwrap (
OM_uint32 *minor_status,
const gss_ctx_id_t context_handle,
const gss_buffer_t input_message_buffer,
gss_buffer_t output_message_buffer,
int *conf_state,
gss_qop_t *qop_state)
Purpose:
Converts a message previously protected by gss_wrap back to a usable
form, verifying the embedded MIC. The conf_state parameter indicates
whether the message was encrypted; the qop_state parameter indicates
the strength of protection that was used to provide the
confidentiality and integrity services.
Since some application-level protocols may wish to use tokens emitted
by gss_wrap() to provide "secure framing", implementations must
support the wrapping and unwrapping of zero-length messages.
Parameters:
minor_status Integer, modify
Mechanism specific status code.
context_handle gss_ctx_id_t, read
Identifies the context on which the message
arrived
input_message_buffer buffer, opaque, read
protected message
output_message_buffer buffer, opaque, modify
Buffer to receive unwrapped message.
Storage associated with this buffer must
be freed by the application after use use
with a call to gss_release_buffer().
conf_state boolean, modify, optional
Non-zero - Confidentiality and integrity
protection were used
Zero - Integrity service only was used
Specify NULL if not required
qop_state gss_qop_t, modify, optional
Quality of protection provided.
Specify NULL if not required
Function value: GSS status code
GSS_S_COMPLETE Successful completion
GSS_S_DEFECTIVE_TOKEN The token failed consistency checks
GSS_S_BAD_SIG The MIC was incorrect
GSS_S_DUPLICATE_TOKEN The token was valid, and contained a correct
MIC for the message, but it had already been
processed
GSS_S_OLD_TOKEN The token was valid, and contained a correct MIC
for the message, but it is too old to check for
duplication.
GSS_S_UNSEQ_TOKEN The token was valid, and contained a correct MIC
for the message, but has been verified out of
sequence; a later token has already been
received.
GSS_S_GAP_TOKEN The token was valid, and contained a correct MIC
for the message, but has been verified out of
sequence; an earlier expected token has not yet
been received.
GSS_S_CONTEXT_EXPIRED The context has already expired
GSS_S_NO_CONTEXT The context_handle parameter did not identify
a valid context
5.32. gss_verify_mic
OM_uint32 gss_verify_mic (
OM_uint32 *minor_status,
const gss_ctx_id_t context_handle,
const gss_buffer_t message_buffer,
const gss_buffer_t token_buffer,
gss_qop_t *qop_state)
Purpose:
Verifies that a cryptographic MIC, contained in the token parameter,
fits the supplied message. The qop_state parameter allows a message
recipient to determine the strength of protection that was applied to
the message.
Since some application-level protocols may wish to use tokens emitted
by gss_wrap() to provide "secure framing", implementations must
support the calculation and verification of MICs over zero-length
messages.
Parameters:
minor_status Integer, modify
Mechanism specific status code.
context_handle gss_ctx_id_t, read
Identifies the context on which the message
arrived
message_buffer buffer, opaque, read
Message to be verified
token_buffer buffer, opaque, read
Token associated with message
qop_state gss_qop_t, modify, optional
quality of protection gained from MIC
Specify NULL if not required
Function value: GSS status code
GSS_S_COMPLETE Successful completion
GSS_S_DEFECTIVE_TOKEN The token failed consistency checks
GSS_S_BAD_SIG The MIC was incorrect
GSS_S_DUPLICATE_TOKEN The token was valid, and contained a correct
MIC for the message, but it had already been
processed
GSS_S_OLD_TOKEN The token was valid, and contained a correct MIC
for the message, but it is too old to check for
duplication.
GSS_S_UNSEQ_TOKEN The token was valid, and contained a correct MIC
for the message, but has been verified out of
sequence; a later token has already been received.
GSS_S_GAP_TOKEN The token was valid, and contained a correct MIC
for the message, but has been verified out of
sequence; an earlier expected token has not yet
been received.
GSS_S_CONTEXT_EXPIRED The context has already expired
GSS_S_NO_CONTEXT The context_handle parameter did not identify a
valid context
5.33. gss_wrap
OM_uint32 gss_wrap (
OM_uint32 *minor_status,
const gss_ctx_id_t context_handle,
int conf_req_flag,
gss_qop_t qop_req
const gss_buffer_t input_message_buffer,
int *conf_state,
gss_buffer_t output_message_buffer )
Purpose:
Attaches a cryptographic MIC and optionally encrypts the specified
input_message. The output_message contains both the MIC and the
message. The qop_req parameter allows a choice between several
cryptographic algorithms, if supported by the chosen mechanism.
Since some application-level protocols may wish to use tokens emitted
by gss_wrap() to provide "secure framing", implementations must
support the wrapping of zero-length messages.
Parameters:
minor_status Integer, modify
Mechanism specific status code.
context_handle gss_ctx_id_t, read
Identifies the context on which the message
will be sent
conf_req_flag boolean, read
Non-zero - Both confidentiality and integrity
services are requested
Zero - Only integrity service is requested
qop_req gss_qop_t, read, optional
Specifies required quality of protection. A
mechanism-specific default may be requested by
setting qop_req to GSS_C_QOP_DEFAULT. If an
unsupported protection strength is requested,
gss_wrap will return a major_status of
GSS_S_BAD_QOP.
input_message_buffer buffer, opaque, read
Message to be protected
conf_state boolean, modify, optional
Non-zero - Confidentiality, data origin
authentication and integrity
services have been applied
Zero - Integrity and data origin services only
has been applied.
Specify NULL if not required
output_message_buffer buffer, opaque, modify
Buffer to receive protected message.
Storage associated with this message must
be freed by the application after use with
a call to gss_release_buffer().
Function value: GSS status code
GSS_S_COMPLETE Successful completion
GSS_S_CONTEXT_EXPIRED The context has already expired
GSS_S_NO_CONTEXT The context_handle parameter did not identify a
valid context
GSS_S_BAD_QOP The specified QOP is not supported by the
mechanism.
5.34. gss_wrap_size_limit
OM_uint32 gss_wrap_size_limit (
OM_uint32 *minor_status,
const gss_ctx_id_t context_handle,
int conf_req_flag,
gss_qop_t qop_req,
OM_uint32 req_output_size,
OM_uint32 *max_input_size)
Purpose:
Allows an application to determine the maximum message size that, if
presented to gss_wrap with the same conf_req_flag and qop_req
parameters, will result in an output token containing no more than
req_output_size bytes.
This call is intended for use by applications that communicate over
protocols that impose a maximum message size. It enables the
application to fragment messages prior to applying protection.
GSS-API implementations are recommended but not required to detect
invalid QOP values when gss_wrap_size_limit() is called. This routine
guarantees only a maximum message size, not the availability of
specific QOP values for message protection.
Successful completion of this call does not guarantee that gss_wrap
will be able to protect a message of length max_input_size bytes,
since this ability may depend on the availability of system resources
at the time that gss_wrap is called. However, if the implementation
itself imposes an upper limit on the length of messages that may be
processed by gss_wrap, the implementation should not return a value
via max_input_bytes that is greater than this length.
Parameters:
minor_status Integer, modify
Mechanism specific status code
context_handle gss_ctx_id_t, read
A handle that refers to the security over
which the messages will be sent.
conf_req_flag Boolean, read
Indicates whether gss_wrap will be asked
to apply confidentiality protection in
addition to integrity protection. See
the routine description for gss_wrap
for more details.
qop_req gss_qop_t, read
Indicates the level of protection that
gss_wrap will be asked to provide. See
the routine description for gss_wrap for
more details.
req_output_size Integer, read
The desired maximum size for tokens emitted
by gss_wrap.
max_input_size Integer, modify
The maximum input message size that may
be presented to gss_wrap in order to
guarantee that the emitted token shall
be no larger than req_output_size bytes.
Function value: GSS status code
GSS_S_COMPLETE Successful completion
GSS_S_NO_CONTEXT The referenced context could not be accessed.
GSS_S_CONTEXT_EXPIRED The context has expired.
GSS_S_BAD_QOP The specified QOP is not supported by the
mechanism.
6. Security Considerations
This document specifies a service interface for security facilities
and services; as such, security considerations appear throughout the
specification. Nonetheless, it is appropriate to summarize certain
specific points relevant to GSS-API implementors and calling
applications. Usage of the GSS-API interface does not in itself
provide security services or assurance; instead, these attributes are
dependent on the underlying mechanism(s) which support a GSS-API
implementation. Callers must be attentive to the requests made to
GSS-API calls and to the status indicators returned by GSS-API, as
these specify the security service characteristics which GSS-API will
provide. When the interprocess context transfer facility is used,
appropriate local controls should be applied to constrain access to
interprocess tokens and to the sensitive data which they contain.
Appendix A. GSS-API C header file gssapi.h
C-language GSS-API implementations should include a copy of the
following header-file.
#ifndef GSSAPI_H_
#define GSSAPI_H_
/*
* First, include stddef.h to get size_t defined.
*/
#include <stddef.h>
/*
* If the platform supports the xom.h header file, it should be
* included here.
*/
#include <xom.h>
/*
* Now define the three implementation-dependent types.
*/
typedef <platform-specific> gss_ctx_id_t;
typedef <platform-specific> gss_cred_id_t;
typedef <platform-specific> gss_name_t;
/*
* The following type must be defined as the smallest natural
* unsigned integer supported by the platform that has at least
* 32 bits of precision.
*/
typedef <platform-specific> gss_uint32;
#ifdef OM_STRING
/*
* We have included the xom.h header file. Verify that OM_uint32
* is defined correctly.
*/
#if sizeof(gss_uint32) != sizeof(OM_uint32)
#error Incompatible definition of OM_uint32 from xom.h
#endif
typedef OM_object_identifier gss_OID_desc, *gss_OID;
#else
/*
* We can't use X/Open definitions, so roll our own.
*/
typedef gss_uint32 OM_uint32;
typedef struct gss_OID_desc_struct {
OM_uint32 length;
void *elements;
} gss_OID_desc, *gss_OID;
#endif
typedef struct gss_OID_set_desc_struct {
size_t count;
gss_OID elements;
} gss_OID_set_desc, *gss_OID_set;
typedef struct gss_buffer_desc_struct {
size_t length;
void *value;
} gss_buffer_desc, *gss_buffer_t;
typedef struct gss_channel_bindings_struct {
OM_uint32 initiator_addrtype;
gss_buffer_desc initiator_address;
OM_uint32 acceptor_addrtype;
gss_buffer_desc acceptor_address;
gss_buffer_desc application_data;
} *gss_channel_bindings_t;
/*
* For now, define a QOP-type as an OM_uint32
*/
typedef OM_uint32 gss_qop_t;
typedef int gss_cred_usage_t;
/*
* Flag bits for context-level services.
*/
#define GSS_C_DELEG_FLAG 1
#define GSS_C_MUTUAL_FLAG 2
#define GSS_C_REPLAY_FLAG 4
#define GSS_C_SEQUENCE_FLAG 8
#define GSS_C_CONF_FLAG 16
#define GSS_C_INTEG_FLAG 32
#define GSS_C_ANON_FLAG 64
#define GSS_C_PROT_READY_FLAG 128
#define GSS_C_TRANS_FLAG 256
/*
* Credential usage options
*/
#define GSS_C_BOTH 0
#define GSS_C_INITIATE 1
#define GSS_C_ACCEPT 2
/*
* Status code types for gss_display_status
*/
#define GSS_C_GSS_CODE 1
#define GSS_C_MECH_CODE 2
/*
* The constant definitions for channel-bindings address families
*/
#define GSS_C_AF_UNSPEC 0
#define GSS_C_AF_LOCAL 1
#define GSS_C_AF_INET 2
#define GSS_C_AF_IMPLINK 3
#define GSS_C_AF_PUP 4
#define GSS_C_AF_CHAOS 5
#define GSS_C_AF_NS 6
#define GSS_C_AF_NBS 7
#define GSS_C_AF_ECMA 8
#define GSS_C_AF_DATAKIT 9
#define GSS_C_AF_CCITT 10
#define GSS_C_AF_SNA 11
#define GSS_C_AF_DECnet 12
#define GSS_C_AF_DLI 13
#define GSS_C_AF_LAT 14
#define GSS_C_AF_HYLINK 15
#define GSS_C_AF_APPLETALK 16
#define GSS_C_AF_BSC 17
#define GSS_C_AF_DSS 18
#define GSS_C_AF_OSI 19
#define GSS_C_AF_X25 21
#define GSS_C_AF_NULLADDR 255
/*
* Various Null values
*/
#define GSS_C_NO_NAME ((gss_name_t) 0)
#define GSS_C_NO_BUFFER ((gss_buffer_t) 0)
#define GSS_C_NO_OID ((gss_OID) 0)
#define GSS_C_NO_OID_SET ((gss_OID_set) 0)
#define GSS_C_NO_CONTEXT ((gss_ctx_id_t) 0)
#define GSS_C_NO_CREDENTIAL ((gss_cred_id_t) 0)
#define GSS_C_NO_CHANNEL_BINDINGS ((gss_channel_bindings_t) 0)
#define GSS_C_EMPTY_BUFFER {0, NULL}
/*
* Some alternate names for a couple of the above
* values. These are defined for V1 compatibility.
*/
#define GSS_C_NULL_OID GSS_C_NO_OID
#define GSS_C_NULL_OID_SET GSS_C_NO_OID_SET
/*
* Define the default Quality of Protection for per-message
* services. Note that an implementation that offers multiple
* levels of QOP may define GSS_C_QOP_DEFAULT to be either zero
* (as done here) to mean "default protection", or to a specific
* explicit QOP value. However, a value of 0 should always be