gss_init_sec_context man page on SunOS

Man page or keyword search:  
man Server   20652 pages
apropos Keyword Search (all sections)
Output format
SunOS logo
[printable version]

gss_init_sec_conGenericSSecurity Services API Librargss_init_sec_context(3GSS)

NAME
       gss_init_sec_context  - initiate a GSS-API security context with a peer
       application

SYNOPSIS
       cc [ flag... ] file... -lgss [ library... ]
       #include <gssapi/gssapi.h>

       OM_uint32    gss_init_sec_context(OM_uint32    *minor_status,	 const
       gss_cred_id_t   initiator_cred_handle,	gss_ctx_id_t  *context_handle,
       const  gss_name_t  *target_name,	 const	gss_OID	 mech_type,  OM_uint32
       req_flags,    OM_uint32	  time_req,    const	gss_channel_bindings_t
       input_chan_bindings,   const    gss_buffer_t    input_token,    gss_OID
       *actual_mech_type,  gss_buffer_t	 output_token,	OM_uint32  *ret_flags,
       OM_uint32 *time_rec);

PARAMETERS
       The parameter descriptions for gss_init_sec_context() follow:

       minor_status	       A mechanism specific status code.

       initiator_cred_handle   The handle for the credentials claimed.	Supply
			       GSS_C_NO_CREDENTIAL to act as a default initia‐
			       tor  principal.	If  no	default	 initiator  is
			       defined, the function returns GSS_S_NO_CRED.

       context_handle	       The  context  handle  for a new context. Supply
			       the value GSS_C_NO_CONTEXT for the first	 call,
			       and  use the value returned in any continuation
			       calls.  The  resources  associated  with	  con‐
			       text_handle must be released by the application
			       after use  by  a	 call  to  gss_delete_sec_con‐
			       text(3GSS).

       target_name	       The name of the context acceptor.

       mech_type	       The  object  ID	of  the	 desired mechanism. To
			       obtain a specific  default,  supply  the	 value
			       GSS_C_NO_ID.

       req_flags	       Contains	 independent flags, each of which will
			       request that the	 context  support  a  specific
			       service option. A symbolic name is provided for
			       each flag. Logically-OR the  symbolic  name  to
			       the  corresponding  required  flag  to form the
			       bit-mask value. req_flags may  contain  one  of
			       the following values:

			       GSS_C_DELEG_FLAG

				   If  true,  delegate credentials to a remote
				   peer. Do not delegate  the  credentials  if
				   the value is false.

			       GSS_C_MUTUAL_FLAG

				   If true, request that the peer authenticate
				   itself.  If	false,	authenticate  to   the
				   remote peer only.

			       GSS_C_REPLAY_FLAG

				   If  true,  enable replay detection for mes‐
				   sages  protected  with  gss_wrap(3GSS)   or
				   gss_get_mic(3GSS). Do not attempt to detect
				   replayed messages if false.

			       GSS_C_SEQUENCE_FLAG

				   If  true,  enable  detection	  of   out-of-
				   sequence protected messages. Do not attempt
				   to  detect  out-of-sequence	 messages   if
				   false.

			       GSS_C_CONF_FLAG

				   If  true, request that confidential service
				   be	made	available    by	   means    of
				   gss_wrap(3GSS).  If	false,	no per-message
				   confidential service is required.

			       GSS_C_INTEG_FLAG

				   If true, request that integrity service  be
				   made	 available  by means of gss_wrap(3GSS)
				   or gss_get_mic(3GSS). If false, no per-mes‐
				   sage integrity service is required.

			       GSS_C_ANON_FLAG

				   If  true,  do  not  reveal  the initiator's
				   identify to the acceptor. If false, authen‐
				   ticate normally.

       time_req		       The  number  of	seconds	 for which the context
			       will remain  valid.  Supply  a  zero  value  to
			       time_req to request a default validity period.

       input_chan_bindings     Optional application-specified bindings. Allows
			       application to securely bind channel  identifi‐
			       cation information to the security context. Set
			       to GSS_C_NO_CHANNEL_BINDINGS if you do not want
			       to use channel bindings.

       input_token	       Token  received	from  the peer application. On
			       the initial call, supply GSS_C_NO_BUFFER	 or  a
			       pointer	 to  a	buffer	containing  the	 value
			       GSS_C_EMPTY_BUFFER.

       actual_mech_type	       The actual mechanism used. The OID returned  by
			       means  of  this	parameter  will	 be pointer to
			       static storage that should be treated as	 read-
			       only.  The  application	should	not attempt to
			       free it. To obtain a specific  default,	supply
			       the  value  GSS_C_NO_ID.	 Specify  NULL	if the
			       parameter is not required.

       output_token	       The token to send to the peer  application.  If
			       the  length  field  of  the  returned buffer is
			       zero, no token need be sent to the peer	appli‐
			       cation.	After use storage associated with this
			       buffer must be freed by the  application	 by  a
			       call to gss_release_buffer(3GSS).

       ret_flags	       Contains	 various  independent  flags,  each of
			       which indicates that  the  context  supports  a
			       specific service option. If not needed, specify
			       NULL.  Test  the	 returned  bit-mask  ret_flags
			       value against its symbolic name to determine if
			       the given option is supported by	 the  context.
			       ret_flags may contain one of the following val‐
			       ues:

			       GSS_C_DELEG_FLAG

				   If true, credentials were delegated to  the
				   remote  peer. If false, no credentials were
				   delegated.

			       GSS_C_MUTUAL_FLAG

				   If  true,  the  remote  peer	 authenticated
				   itself.  If	false, the remote peer did not
				   authenticate itself.

			       GSS_C_REPLAY_FLAG

				   If true, replay of protected messages  will
				   be  detected.  If  false, replayed messages
				   will not be detected.

			       GSS_C_SEQUENCE_FLAG

				   If true, out of sequence protected messages
				   will	 be  detected. If false, they will not
				   be detected.

			       GSS_C_CONF_FLAG

				   If  true,  confidential  service   may   be
				   invoked  by calling the gss_wrap() routine.
				   If false,  no  confidentiality  service  is
				   available   by   means  of  gss_wrap(3GSS).
				   gss_wrap() will provide message  encapsula‐
				   tion,    data-origin	  authentication   and
				   integrity services only.

			       GSS_C_INTEG_FLAG

				   If true, integrity service may  be  invoked
				   by  calling	either	the  gss_wrap(3GSS) or
				   gss_get_mic(3GSS) routine. If  false,  per-
				   message integrity service is not available.

			       GSS_C_ANON_FLAG

				   If  true,  the initiator's identity has not
				   been revealed; it will not be  revealed  if
				   any	emitted	 token is passed to the accep‐
				   tor. If false, the initiator	 has  been  or
				   will be authenticated normally.

			       GSS_C_PROT_READY_FLAG

				   If  true, the protection services specified
				   by  the  states  of	 GSS_C_CONF_FLAG   and
				   GSS_C_INTEG_FLAG   are   available  if  the
				   accompanying major status return  value  is
				   either    GSS_S_COMPLETE    or   GSS_S_CON‐
				   TINUE_NEEDED. If false, the protection ser‐
				   vices  are available only if the accompany‐
				   ing major status return value is GSS_S_COM‐
				   PLETE.

			       GSS_C_TRANS_FLAG

				   If true, the resultant security context may
				   be transferred to other processes by	 means
				   of  a call to gss_export_sec_context(3GSS).
				   If false, the security  context  cannot  be
				   transferred.

       time_rec		       The  number  of	seconds	 for which the context
			       will remain valid. Specify NULL if the  parame‐
			       ter is not required.

DESCRIPTION
       The  gss_init_sec_context()  function  initiates the establishment of a
       security context between the application and a remote peer.  Initially,
       the  input_token	 parameter should be specified either as GSS_C_NO_BUF‐
       FER, or as a pointer to a gss_buffer_desc object with  a	 length	 field
       that  contains  a  zero	value.	The routine may return a output_token,
       which should be transferred to the peer application, which will present
       it   to	 gss_accept_sec_context(3GSS).	If  no	token  need  be	 sent,
       gss_init_sec_context() will indicate this by setting the	 length	 field
       of  the	output_token  argument to zero. To complete context establish‐
       ment, one or more reply tokens may be required from the	peer  applica‐
       tion; if so, gss_init_sec_context() will return a status code that con‐
       tains the supplementary information bit GSS_S_CONTINUE_NEEDED. In  this
       case,  make another call to gss_init_sec_context() when the reply token
       is received from the peer application  and  pass	 the  reply  token  to
       gss_init_sec_context() by means of the input_token parameter.

       Construct portable applications to use the token length and return sta‐
       tus to determine whether to send or wait for a token.

       Whenever the routine returns a major status  that  includes  the	 value
       GSS_S_CONTINUE_NEEDED,  the  context  is not fully established, and the
       following restrictions apply to the output parameters:

	 ·  The value returned by means of the	time_rec  parameter  is	 unde‐
	    fined.  Unless  the	 accompanying ret_flags parameter contains the
	    bit GSS_C_PROT_READY_FLAG, which indicates that  per-message  ser‐
	    vices may be applied in advance of a successful completion status,
	    the value returned by means of the actual_mech_type	 parameter  is
	    undefined  until  the  routine  returns  a	major  status value of
	    GSS_S_COMPLETE.

	 ·  The	  values   of	the    GSS_C_DELEG_FLAG,    GSS_C_MUTUAL_FLAG,
	    GSS_C_REPLAY_FLAG,	    GSS_C_SEQUENCE_FLAG,      GSS_C_CONF_FLAG,
	    GSS_C_INTEG_FLAG  and  GSS_C_ANON_FLAG  bits   returned   by   the
	    ret_flags  parameter  contain values that will be valid if context
	    establishment succeeds. For example, if the application requests a
	    service such as delegation or anonymous authentication by means of
	    the req_flags argument, and the service is	unavailable  from  the
	    underlying	mechanism,  gss_init_sec_context()  generates  a token
	    that will not provide the service, and it indicate by means of the
	    ret_flags  argument	 that  the  service will not be supported. The
	    application may choose to abort context establishment  by  calling
	    gss_delete_sec_context(3GSS)  if  it  cannot  continue without the
	    service, or if the service was merely desired but  not  mandatory,
	    it may transmit the token and continue context establishment.

	 ·  The	 values of the GSS_C_PROT_READY_FLAG and GSS_C_TRANS_FLAG bits
	    within  ret_flags  indicate	 the  actual   state   at   the	  time
	    gss_init_sec_context()  returns,  whether  or  not	the context is
	    fully established.

	 ·  The GSS-API sets the GSS_C_PROT_READY_FLAG in the final  ret_flags
	    returned   to  a  caller,  for  example,  when  accompanied	 by  a
	    GSS_S_COMPLETE status code. However, applications should not  rely
	    on	this behavior, as the flag was not defined in Version 1 of the
	    GSS-API.  Instead, applications should determine what  per-message
	    services  are  available  after a successful context establishment
	    according to the GSS_C_INTEG_FLAG and GSS_C_CONF_FLAG values.

	 ·  All other bits within the ret_flags argument are set to zero.

       If the initial call of gss_init_sec_context() fails, the	 GSS-API  does
       not  create a context object; it leaves the value of the context_handle
       parameter set to GSS_C_NO_CONTEXT to indicate this.  In	the  event  of
       failure	on  a subsequent call, the GSS-API leaves the security context
       untouched for  the  application	to  delete  using  gss_delete_sec_con‐
       text(3GSS).

       During	context	  establishment,   the	 informational	 status	  bits
       GSS_S_OLD_TOKEN and GSS_S_DUPLICATE_TOKEN indicate  fatal  errors,  and
       GSS-API mechanisms should always return them in association with a sta‐
       tus code of GSS_S_FAILURE.
	This pairing requirement was not part of  Version  1  of  the  GSS-API
       specification,  so applications that wish to run on Version 1 implemen‐
       tations must special-case these codes.

ERRORS
       gss_init_sec_context() may return the following status codes:

       GSS_S_COMPLETE		       Successful completion.

       GSS_S_CONTINUE_NEEDED	       A token from the	 peer  application  is
				       required	 to  complete the context, and
				       gss_init_sec_context() must  be	called
				       again with that token.

       GSS_S_DEFECTIVE_TOKEN	       Consistency  checks  performed  on  the
				       input_token failed.

       GSS_S_DEFECTIVE_CREDENTIAL      Consistency  checks  performed  on  the
				       credential failed.

       GSS_S_NO_CRED		       The  supplied credentials are not valid
				       for context acceptance, or the  creden‐
				       tial handle does not reference any cre‐
				       dentials.

       GSS_S_CREDENTIALS_EXPIRED       The   referenced	   credentials	  have
				       expired.

       GSS_S_BAD_BINDINGS	       The   input_token   contains  different
				       channel bindings than  those  specified
				       by  means  of  the  input_chan_bindings
				       parameter.

       GSS_S_BAD_SIG		       The input_token contains an invalid MIC
				       or a MIC that cannot be verified.

       GSS_S_OLD_TOKEN		       The  input_token	 is too old. This is a
				       fatal error while establishing context.

       GSS_S_DUPLICATE_TOKEN	       The input_token is valid, but it	 is  a
				       duplicate of a token already processed.
				       This is a fatal error while  establish‐
				       ing context.

       GSS_S_NO_CONTEXT		       The  supplied  context  handle does not
				       refer to a valid context.

       GSS_S_BAD_NAMETYPE	       The provided target_name parameter con‐
				       tains  an  invalid  or unsupported name
				       type.

       GSS_S_BAD_NAME		       The supplied target_name	 parameter  is
				       ill-formed.

       GSS_S_BAD_MECH		       The  token  received specifies a mecha‐
				       nism  that  is  not  supported  by  the
				       implementation  or the provided creden‐
				       tial.

       GSS_S_FAILURE		       The underlying  mechanism  detected  an
				       error  for which no specific GSS status
				       code is defined. The mechanism-specific
				       status  code  reported  by means of the
				       minor_status  parameter	 details   the
				       error condition.

EXAMPLES
       Example 1: Invoking gss_init_sec_context() Within a Loop

       A  typical  portable caller should always invoke gss_init_sec_context()
       within a loop:

       int context_established = 0;
       gss_ctx_id_t context_hdl = GSS_C_NO_CONTEXT;
	      ...
       input_token->length = 0;

       while (!context_established) {
	 maj_stat = gss_init_sec_context(&min_stat,
					 cred_hdl,
					 &context_hdl,
					 target_name,
					 desired_mech,
					 desired_services,
					 desired_time,
					 input_bindings,
					 input_token,
					 &actual_mech,
					 output_token,
					 &actual_services,
					 &actual_time);
	 if (GSS_ERROR(maj_stat)) {
	   report_error(maj_stat, min_stat);
	 };

	 if (output_token->length != 0) {
	   send_token_to_peer(output_token);
	   gss_release_buffer(&min_stat, output_token)
	 };
	 if (GSS_ERROR(maj_stat)) {

	   if (context_hdl != GSS_C_NO_CONTEXT)
	     gss_delete_sec_context(&min_stat,
				    &context_hdl,
				    GSS_C_NO_BUFFER);
	   break;
	 };
	 if (maj_stat & GSS_S_CONTINUE_NEEDED) {
	   receive_token_from_peer(input_token);
	 } else {
	   context_established = 1;
	 };
       };

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

       ┌─────────────────────────────┬─────────────────────────────┐
       │      ATTRIBUTE TYPE	     │	    ATTRIBUTE VALUE	   │
       ├─────────────────────────────┼─────────────────────────────┤
       │MT-Level		     │Safe			   │
       └─────────────────────────────┴─────────────────────────────┘

SEE ALSO
       gss_delete_sec_context(3GSS),		 gss_export_sec_context(3GSS),
       gss_get_mic(3GSS), gss_wrap(3GSS), attributes(5)

       Solaris Security for Developers Guide

SunOS 5.10			  22 May 2006	    gss_init_sec_context(3GSS)
[top]

List of man pages available for SunOS

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Tweet
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
....................................................................
Vote for polarhome
Free Shell Accounts :: the biggest list on the net