NAME

       gss_export_sec_context - API function

SYNOPSIS

       #include <gss.h>

       OM_uint32  gss_export_sec_context(OM_uint32 * minor_status, gss_ctx_id_t * context_handle,
       gss_buffer_t interprocess_token);

ARGUMENTS

       OM_uint32 * minor_status
                   (Integer, modify) Mechanism specific status code.

       gss_ctx_id_t * context_handle
                   (gss_ctx_id_t, modify) Context handle identifying
                     the context to transfer.

       gss_buffer_t interprocess_token
                   (buffer, opaque, modify) 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().

DESCRIPTION

       Provided to support the sharing of work between multiple  processes.   This  routine  will
       typically  be  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.
       gss_export_sec_context() deactivates the security context  for  the  calling  process  and
       creates  an  interprocess  token  which,  when passed to gss_import_sec_context in another
       process, will re-activate the context in the second process. Only a  single  instantiation
       of  a  given  context  may  be  active  at any one time; a subsequent attempt by a context
       exporter to access the exported security context will fail.

       The implementation may constrain the set of processes by which the interprocess token  may
       be  imported,  either  as  a  function  of  local  security  policy,  or  as  a  result of
       implementation decisions.  For example, some implementations may constrain contexts to  be
       passed  only  between  processes that run under the same account, or which are part of the
       same process group.

       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 may 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 implementation shall deallocate
       all  process-wide  resources  associated  with  the  security   context,   and   set   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  implementation  must  not  return  an
       interprocess  token,  and  should  strive  to leave the security context referenced by the
       context_handle parameter untouched.  If this is impossible,  it  is  permissible  for  the
       implementation  to  delete the security context, providing it also sets the context_handle
       parameter to GSS_C_NO_CONTEXT.

RETURN VALUE

       `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.

REPORTING BUGS

       Report  bugs  to   <bug-gss@gnu.org>.    GNU   Generic   Security   Service   home   page:
       http://www.gnu.org/software/gss/      General      help      using      GNU      software:
       http://www.gnu.org/gethelp/

COPYRIGHT

       Copyright © 2003-2013 Simon Josefsson.
       Copying and distribution of this file, with or without modification, are permitted in  any
       medium without royalty provided the copyright notice and this notice are preserved.

SEE ALSO

       The  full  documentation  for  gss is maintained as a Texinfo manual.  If the info and gss
       programs are properly installed at your site, the command

              info gss

       should give you access to the complete manual.