Tribblix: manual page: gss_export_sec

GSS_EXPORT_SEC_CONTEXT(3GSS) Generic Security Services API Library Functions

NAME

gss_export_sec_context - transfer a security context to another
process

SYNOPSIS

cc [ flag... ] file... -lgss [ library... ]
#include <gssapi/gssapi.h>

OM_uint32 gss_export_sec_context(OM_uint32 *minor_status,
gss_ctx_id_t *context_handle,gss_buffer_t interprocess_token);

DESCRIPTION

The gss_export_sec_context() function generates an interprocess token
for transfer to another process within an end system.
gss_export_sec_context() and gss_import_sec_context() allow a
security context to be transferred between processes on a single
machine.

The gss_export_sec_context() function supports the sharing of work
between multiple processes. This routine is typically 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, reactivates the context in the second process. Only a single
instantiation of a given context can be active at any one time; a
subsequent attempt by a context exporter to access the exported
security context will fail.

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
might 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 GSS-API deallocates all
process-wide resources associated with the security context and sets
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 function does not return an interprocess token and leaves the
security context referenced by the context_handle parameter
untouched.

Sun's implementation of gss_export_sec_context() does not encrypt the
interprocess token. The interprocess token is serialized before it is
transferred to another process.

PARAMETERS

The parameter descriptions for gss_export_sec_context() are as
follows:

minor_status
A mechanism-specific status code.

context_handle
Context handle identifying the context to
transfer.

interprocess_token
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(3GSS).

ERRORS

gss_export_sec_context() returns one of the following status codes:

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.

GSS_S_FAILURE
The underlying mechanism detected an error
for which no specific GSS status code is
defined. The mechanism-specific status code
reported by means of the minor_status
parameter details the error condition.