share/man/man3gss/gss_export_sec_context.3gss

   1 '\" te
   2 .\" Copyright (C) 2003, Sun Microsystems, Inc. All Rights Reserved
   3 .\" 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.
   4 .\" 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.
   5 .\" 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]
   6 .TH GSS_EXPORT_SEC_CONTEXT 3GSS "Jan 15, 2003"
   7 .SH NAME
   8 gss_export_sec_context \- transfer a security context to another process
   9 .SH SYNOPSIS
  10 .LP
  11 .nf
  12 \fBcc\fR [ \fIflag\fR... ] \fIfile\fR... \fB-lgss\fR  [ \fIlibrary\fR... ]
  13 #include <gssapi/gssapi.h>
  14
  15 \fBOM_uint32\fR \fBgss_export_sec_context\fR(\fBOM_uint32 *\fR\fIminor_status\fR,
  16      \fBgss_ctx_id_t *\fR\fIcontext_handle\fR,\fBgss_buffer_t\fR \fIinterprocess_token\fR);
  17 .fi
  18
  19 .SH DESCRIPTION
  20 .sp
  21 .LP
  22 The \fBgss_export_sec_context()\fR function generates an interprocess token for
  23 transfer to another process within an end system.
  24 \fBgss_export_sec_context()\fR and \fBgss_import_sec_context()\fR allow a
  25 security context to be transferred between processes on a single machine.
  26 .sp
  27 .LP
  28 The \fBgss_export_sec_context()\fR function supports the sharing of work
  29 between multiple processes. This routine is typically used by the
  30 context-acceptor, in an application where a single process receives incoming
  31 connection requests and accepts security contexts over them, then passes the
  32 established context to one or more other processes for message exchange.
  33 \fBgss_export_sec_context()\fR deactivates the security context for the calling
  34 process and creates an interprocess token which, when passed to
  35 \fBgss_import_sec_context()\fR in another process, reactivates the context in
  36 the second process. Only a single instantiation of a given context can be
  37 active at any one time; a subsequent attempt by a context exporter to access
  38 the exported security context will fail.
  39 .sp
  40 .LP
  41 The interprocess token may contain security-sensitive information, for example
  42 cryptographic keys.  While mechanisms are encouraged to either avoid placing
  43 such sensitive information within interprocess tokens or to encrypt the token
  44 before returning it to the application, in a typical object-library
  45 \fBGSS-API\fR implementation, this might not be possible. Thus, the application
  46 must take care to protect the interprocess token and ensure that any process to
  47 which the token is transferred is trustworthy. If creation of the interprocess
  48 token is successful, the \fBGSS-API\fR deallocates all process-wide resources
  49 associated with the security context and sets the context_handle to
  50 \fBGSS_C_NO_CONTEXT\fR. In the event of an error that makes it impossible to
  51 complete the export of the security context, the function does not return an
  52 interprocess token and leaves the security context referenced by the
  53 \fIcontext_handle\fR parameter untouched.
  54 .sp
  55 .LP
  56 Sun's implementation of \fBgss_export_sec_context()\fR does not encrypt the
  57 interprocess token. The interprocess token is serialized before it is
  58 transferred to another process.
  59 .SH PARAMETERS
  60 .sp
  61 .LP
  62 The parameter descriptions for \fBgss_export_sec_context()\fR are as follows:
  63 .sp
  64 .ne 2
  65 .na
  66 \fB\fIminor_status\fR\fR
  67 .ad
  68 .RS 22n
  69 A mechanism-specific status code.
  70 .RE
  71
  72 .sp
  73 .ne 2
  74 .na
  75 \fB\fIcontext_handle\fR\fR
  76 .ad
  77 .RS 22n
  78 Context handle identifying the context to transfer.
  79 .RE
  80
  81 .sp
  82 .ne 2
  83 .na
  84 \fB\fIinterprocess_token\fR\fR
  85 .ad
  86 .RS 22n
  87 Token to be transferred to target process. Storage associated with this token
  88 must be freed by the application after use with a call to
  89 \fBgss_release_buffer\fR(3GSS).
  90 .RE
  91
  92 .SH ERRORS
  93 .sp
  94 .LP
  95 \fBgss_export_sec_context()\fR returns one of the following status codes:
  96 .sp
  97 .ne 2
  98 .na
  99 \fB\fBGSS_S_COMPLETE\fR\fR
 100 .ad
 101 .RS 25n
 102 Successful completion.
 103 .RE
 104
 105 .sp
 106 .ne 2
 107 .na
 108 \fB\fBGSS_S_CONTEXT_EXPIRED\fR\fR
 109 .ad
 110 .RS 25n
 111 The context has expired.
 112 .RE
 113
 114 .sp
 115 .ne 2
 116 .na
 117 \fB\fBGSS_S_NO_CONTEXT\fR\fR
 118 .ad
 119 .RS 25n
 120 The context was invalid.
 121 .RE
 122
 123 .sp
 124 .ne 2
 125 .na
 126 \fB\fBGSS_S_UNAVAILABLE\fR\fR
 127 .ad
 128 .RS 25n
 129 The operation is not supported.
 130 .RE
 131
 132 .sp
 133 .ne 2
 134 .na
 135 \fB\fBGSS_S_FAILURE\fR\fR
 136 .ad
 137 .RS 25n
 138 The underlying mechanism detected an error for which no specific \fBGSS\fR
 139 status code is defined.  The mechanism-specific status code reported by means
 140 of the \fIminor_status\fR parameter details the error condition.
 141 .RE
 142
 143 .SH ATTRIBUTES
 144 .sp
 145 .LP
 146 See \fBattributes\fR(5) for descriptions of the following attributes:
 147 .sp
 148
 149 .sp
 150 .TS
 151 box;
 152 c | c
 153 l | l .
 154 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 155 _
 156 MT Level        Safe
 157 .TE
 158
 159 .SH SEE ALSO
 160 .sp
 161 .LP
 162 \fBgss_accept_sec_context\fR(3GSS), \fBgss_import_sec_context\fR(3GSS),
 163 \fBgss_init_sec_context\fR(3GSS), \fBgss_release_buffer\fR(3GSS),
 164 \fBattributes\fR(5)
 165 .sp
 166 .LP
 167 \fISolaris Security for Developers Guide\fR