gss_export_sec_context(3GSS)			  Generic Security Services API Library Functions		      gss_export_sec_context(3GSS)

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  con-
       text-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  con-
       text  for  the calling process and creates an interprocess token which, when passed to gss_import_sec_context() in another process, reacti-
       vates 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 inter-
       process token and ensure that any process to which the token is transferred is trustworthy. If creation of the interprocess token  is  suc-
       cessful,  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-spe-
				cific status code reported by means of the minor_status parameter details the error condition.

ATTRIBUTES

       See attributes(5) for descriptions of the following attributes:

       +-----------------------------+-----------------------------+
       |      ATTRIBUTE TYPE	     |	    ATTRIBUTE VALUE	   |
       +-----------------------------+-----------------------------+
       |Availability		     |SUNWgss (32-bit)		   |
       +-----------------------------+-----------------------------+
       |			     |SUNWgssx (64-bit) 	   |
       +-----------------------------+-----------------------------+
       |MT Level		     |Safe			   |
       +-----------------------------+-----------------------------+

SEE ALSO

       gss_accept_sec_context(3GSS), gss_import_sec_context(3GSS), gss_init_sec_context(3GSS), gss_release_buffer(3GSS), attributes(5)

       Solaris Security for Developers Guide

SunOS 5.11							    15 Jan 2003 				      gss_export_sec_context(3GSS)