'\" te
.\" Copyright (C) 2003, Sun Microsystems, Inc. All Rights Reserved
.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License").  You may not use this file except in compliance with the License.
.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.  See the License for the specific language governing permissions and limitations under the License.
.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE.  If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
.TH GSS_EXPORT_SEC_CONTEXT 3GSS "Jan 15, 2003"
.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
.na
\fB\fIminor_status\fR\fR
.ad
.RS 22n
A mechanism-specific status code.
.RE

.sp
.ne 2
.na
\fB\fIcontext_handle\fR\fR
.ad
.RS 22n
Context handle identifying the context to transfer.
.RE

.sp
.ne 2
.na
\fB\fIinterprocess_token\fR\fR
.ad
.RS 22n
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
.na
\fB\fBGSS_S_COMPLETE\fR\fR
.ad
.RS 25n
Successful completion.
.RE

.sp
.ne 2
.na
\fB\fBGSS_S_CONTEXT_EXPIRED\fR\fR
.ad
.RS 25n
The context has expired.
.RE

.sp
.ne 2
.na
\fB\fBGSS_S_NO_CONTEXT\fR\fR
.ad
.RS 25n
The context was invalid.
.RE

.sp
.ne 2
.na
\fB\fBGSS_S_UNAVAILABLE\fR\fR
.ad
.RS 25n
The operation is not supported.
.RE

.sp
.ne 2
.na
\fB\fBGSS_S_FAILURE\fR\fR
.ad
.RS 25n
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
box;
c | c
l | l .
ATTRIBUTE TYPE	ATTRIBUTE VALUE
_
MT Level	Safe
.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
\fISolaris Security for Developers Guide\fR