'\" te

.\" Copyright (c) 2003, 2011, Oracle and/or its affiliates. All rights reserved.

.TH gss_export_sec_context 3GSS "22 Aug 2011" "SunOS 5.12" "Generic Security Services API Library Functions"

.SH NAME

gss_export_sec_context \- transfer a security context to another process

.SH SYNOPSIS

.LP

.nf

\fBcc\fR [ \fIflag\fR... ] \fIfile\fR... \fB-lgss\fR  [ \fIlibrary\fR... ] 

#include <gssapi/gssapi.h>

\fBOM_uint32\fR \fBgss_export_sec_context\fR(\fBOM_uint32 *\fR\fIminor_status\fR,

     \fBgss_ctx_id_t *\fR\fIcontext_handle\fR,\fBgss_buffer_t\fR \fIinterprocess_token\fR);

.fi

.SH DESCRIPTION

.sp

.LP

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

.sp

.LP

The \fBgss_export_sec_context()\fR 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. \fBgss_export_sec_context()\fR deactivates the security context for the calling process and creates an interprocess token which, when passed to \fBgss_import_sec_context()\fR 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.

.sp

.LP

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 \fBGSS-API\fR 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 \fBGSS-API\fR deallocates all process-wide resources associated with the security context and sets the context_handle to \fBGSS_C_NO_CONTEXT\fR. 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 \fIcontext_handle\fR parameter untouched.

.sp

.LP

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

.SH PARAMETERS

.sp

.LP

The parameter descriptions for \fBgss_export_sec_context()\fR are as follows:

.sp

.ne 2

.mk

.na

\fB\fIminor_status\fR\fR

.ad

.RS 22n

.rt  

A mechanism-specific status code.

.RE

.sp

.ne 2

.mk

.na

\fB\fIcontext_handle\fR\fR

.ad

.RS 22n

.rt  

Context handle identifying the context to transfer.

.RE

.sp

.ne 2

.mk

.na

\fB\fIinterprocess_token\fR\fR

.ad

.RS 22n

.rt  

Token to be transferred to target process. Storage associated with this token must be freed by the application after use with a call to \fBgss_release_buffer\fR(3GSS).

.RE

.SH ERRORS

.sp

.LP

\fBgss_export_sec_context()\fR returns one of the following status codes:

.sp

.ne 2

.mk

.na

\fB\fBGSS_S_COMPLETE\fR\fR

.ad

.RS 25n

.rt  

Successful completion.

.RE

.sp

.ne 2

.mk

.na

\fB\fBGSS_S_CONTEXT_EXPIRED\fR\fR

.ad

.RS 25n

.rt  

The context has expired.

.RE

.sp

.ne 2

.mk

.na

\fB\fBGSS_S_NO_CONTEXT\fR\fR

.ad

.RS 25n

.rt  

The context was invalid.

.RE

.sp

.ne 2

.mk

.na

\fB\fBGSS_S_UNAVAILABLE\fR\fR

.ad

.RS 25n

.rt  

The operation is not supported.

.RE

.sp

.ne 2

.mk

.na

\fB\fBGSS_S_FAILURE\fR\fR

.ad

.RS 25n

.rt  

The underlying mechanism detected an error for which no specific \fBGSS\fR status code is defined.  The mechanism-specific status code reported by means of the \fIminor_status\fR parameter details the error condition.

.RE

.SH ATTRIBUTES

.sp

.LP

See \fBattributes\fR(5) for descriptions of the following attributes:

.sp

.sp

.TS

tab() box;

cw(2.75i) |cw(2.75i) 

lw(2.75i) |lw(2.75i) 

.

ATTRIBUTE TYPEATTRIBUTE VALUE

_

MT LevelSafe

.TE

.SH SEE ALSO

.sp

.LP

\fBgss_accept_sec_context\fR(3GSS), \fBgss_import_sec_context\fR(3GSS), \fBgss_init_sec_context\fR(3GSS), \fBgss_release_buffer\fR(3GSS), \fBattributes\fR(5)

.sp

.LP

\fI\fR