RFC 2744
Generic Security Service API Version 2 : C-bindings
5.14. gss_export_sec_context
OM_uint32 gss_export_sec_context ( OM_uint32 *minor_status, gss_ctx_id_t *context_handle, gss_buffer_t interprocess_token) Purpose: Provided to support the sharing of work between multiple processes. This routine will typically be used by the context-acceptor, in an application where a single process receives incoming connection requests and accepts security contexts over them, then passes the established context to one or more other processes for message exchange. gss_export_sec_context() deactivates the security context for the calling process and creates an interprocess token which, when passed to gss_import_sec_context in another process, will re-activate the context in the second process. Only a single instantiation of a given context may be active at any one time; a subsequent attempt by a context exporter to access the exported security context will fail. The implementation may constrain the set of processes by which the interprocess token may be imported, either as a function of local security policy, or as a result of implementation decisions. For example, some implementations may constrain contexts to be passed only between processes that run under the same account, or which are part of the same process group. The interprocess token may contain security-sensitive information (for example cryptographic keys). While mechanisms are encouraged to either avoid placing such sensitive information within interprocess tokens, or to encrypt the token before returning it to the application, in a typical object-library GSS-API implementation this may not be possible. Thus the application must take care to protect the interprocess token, and ensure that any process to which the token is transferred is trustworthy. If creation of the interprocess token is successful, the implementation shall deallocate all process-wide resources associated with the security context, and set the context_handle to GSS_C_NO_CONTEXT. In the event of an error that makes it impossible to complete the export of the security context, the implementation must not return an interprocess token, and should strive to leave the security context referenced by the context_handle parameter untouched. If this is impossible, it is permissible for the implementation to delete the security context, providing it also sets the context_handle parameter to GSS_C_NO_CONTEXT.
Parameters:
minor_status Integer, modify
Mechanism specific status code
context_handle gss_ctx_id_t, modify
context handle identifying the context to
transfer.
interprocess_token buffer, opaque, modify
token to be transferred to target process.
Storage associated with this token 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 expired
GSS_S_NO_CONTEXT The context was invalid
GSS_S_UNAVAILABLE The operation is not supported.
5.15. gss_get_mic
OM_uint32 gss_get_mic (
OM_uint32 *minor_status,
const gss_ctx_id_t context_handle,
gss_qop_t qop_req,
const gss_buffer_t message_buffer,
gss_buffer_t msg_token)
Purpose:
Generates a cryptographic MIC for the supplied message, and places
the MIC in a token for transfer to the peer application. 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 derivation of MICs from zero-length messages.
Parameters:
minor_status Integer, modify
Implementation specific status code.
context_handle gss_ctx_id_t, read
identifies the context on which the message
will be sent
qop_req gss_qop_t, read, optional
Specifies requested quality of protection.
Callers are encouraged, on portability grounds,
to accept the default quality of protection
offered by the chosen mechanism, which may be
requested by specifying GSS_C_QOP_DEFAULT for
this parameter. If an unsupported protection
strength is requested, gss_get_mic will return a
major_status of GSS_S_BAD_QOP.
message_buffer buffer, opaque, read
message to be protected
msg_token buffer, opaque, modify
buffer to receive token. The application must
free storage associated with this buffer 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.16. gss_import_name
OM_uint32 gss_import_name (
OM_uint32 *minor_status,
const gss_buffer_t input_name_buffer,
const gss_OID input_name_type,
gss_name_t *output_name)
Purpose:
Convert a contiguous string name to internal form. In general, the
internal name returned (via the <output_name> parameter) will not be
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 name5.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
(page 75 continued on part 4)
