1.\" -*- nroff -*- 2.\" 3.\" Copyright (c) 2005 Doug Rabson 4.\" All rights reserved. 5.\" 6.\" Redistribution and use in source and binary forms, with or without 7.\" modification, are permitted provided that the following conditions 8.\" are met: 9.\" 1. Redistributions of source code must retain the above copyright 10.\" notice, this list of conditions and the following disclaimer. 11.\" 2. Redistributions in binary form must reproduce the above copyright 12.\" notice, this list of conditions and the following disclaimer in the 13.\" documentation and/or other materials provided with the distribution. 14.\" 15.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND 16.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 17.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 18.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE 19.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 20.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 21.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 22.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 23.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 24.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 25.\" SUCH DAMAGE. 26.\" 27.\" $FreeBSD$ 28.\" 29.\" Copyright (C) The Internet Society (2000). All Rights Reserved. 30.\" 31.\" This document and translations of it may be copied and furnished to 32.\" others, and derivative works that comment on or otherwise explain it 33.\" or assist in its implementation may be prepared, copied, published 34.\" and distributed, in whole or in part, without restriction of any 35.\" kind, provided that the above copyright notice and this paragraph are 36.\" included on all such copies and derivative works. However, this 37.\" document itself may not be modified in any way, such as by removing 38.\" the copyright notice or references to the Internet Society or other 39.\" Internet organizations, except as needed for the purpose of 40.\" developing Internet standards in which case the procedures for 41.\" copyrights defined in the Internet Standards process must be 42.\" followed, or as required to translate it into languages other than 43.\" English. 44.\" 45.\" The limited permissions granted above are perpetual and will not be 46.\" revoked by the Internet Society or its successors or assigns. 47.\" 48.\" This document and the information contained herein is provided on an 49.\" "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING 50.\" TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING 51.\" BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION 52.\" HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF 53.\" MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. 54.\" 55.\" The following commands are required for all man pages. 56.Dd November 12, 2005 57.Os 58.Dt GSS_EXPORT_SEC_CONTEXT 3 PRM 59.Sh NAME 60.Nm gss_export_sec_context 61.Nd Transfer a security context to another process 62.\" This next command is for sections 2 and 3 only. 63.\" .Sh LIBRARY 64.Sh SYNOPSIS 65.In "gssapi/gssapi.h" 66.Ft OM_uint32 67.Fo gss_export_sec_context 68.Fa "OM_uint32 *minor_status" 69.Fa "gss_ctx_id_t *context_handle" 70.Fa "gss_buffer_t interprocess_token" 71.Fc 72.Sh DESCRIPTION 73Provided to support the sharing of work between multiple processes. 74This routine will typically be used by the context-acceptor, 75in an application where a single process receives incoming connection 76requests and accepts security contexts over them, 77then passes the established context to one or more other processes for 78message exchange. 79.Fn gss_export_sec_context 80deactivates the security context for the calling process and creates 81an interprocess token which, 82when passed to 83.Fn gss_import_sec_context 84in another process, 85will re-activate the context in the second process. 86Only a single instantiation of a given context may be active at any 87one time; 88a subsequent attempt by a context exporter to access the exported security context will fail. 89.Pp 90The implementation may constrain the set of processes by which the 91interprocess token may be imported, 92either as a function of local security policy, 93or as a result of implementation decisions. 94For example, 95some implementations may constrain contexts to be passed only between 96processes that run under the same account, 97or which are part of the same process group. 98.Pp 99The interprocess token may contain security-sensitive information 100(for example cryptographic keys). 101While mechanisms are encouraged to either avoid placing such sensitive 102information within interprocess tokens, 103or to encrypt the token before returning it to the application, 104in a typical object-library GSS-API implementation this may not be 105possible. 106Thus the application must take care to protect the interprocess token, 107and ensure that any process to which the token is transferred is 108trustworthy. 109.Pp 110If creation of the interprocess token is successful, 111the implementation shall deallocate all process-wide resources 112associated with the security context, 113and set the context_handle to 114.Dv GSS_C_NO_CONTEXT . 115In the event of an error that makes it impossible to complete the 116export of the security context, 117the implementation must not return an interprocess token, 118and should strive to leave the security context referenced by the 119.Fa context_handle 120parameter untouched. 121If this is impossible, 122it is permissible for the implementation to delete the security 123context, 124providing it also sets the 125.Fa context_handle 126parameter to 127.Dv GSS_C_NO_CONTEXT . 128.Sh PARAMETERS 129.Bl -tag 130.It minor_status 131Mechanism specific status code. 132.It context_handle 133Context handle identifying the context to transfer. 134.It interprocess_token 135Token to be transferred to target process. 136Storage associated with this token must be freed by the application 137after use with a call to 138.Fn gss_release_buffer . 139.El 140.Sh RETURN VALUES 141.Bl -tag 142.It GSS_S_COMPLETE 143Successful completion 144.It GSS_S_CONTEXT_EXPIRED 145The context has expired 146.It GSS_S_NO_CONTEXT 147The context was invalid 148.It GSS_S_UNAVAILABLE 149The operation is not supported 150.El 151.Sh SEE ALSO 152.Xr gss_import_sec_context 3 , 153.Xr gss_release_buffer 3 154.Sh STANDARDS 155.Bl -tag 156.It RFC 2743 157Generic Security Service Application Program Interface Version 2, Update 1 158.It RFC 2744 159Generic Security Service API Version 2 : C-bindings 160.\" .Sh HISTORY 161.El 162.Sh HISTORY 163The 164.Nm 165manual page example first appeared in 166.Fx 7.0 . 167.Sh AUTHORS 168John Wray, Iris Associates 169