gss_init_sec_context man page on DigitalUNIX

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

gss_init_sec_context(3)				       gss_init_sec_context(3)

NAME
       gss_init_sec_context  - Initiate a security context between an applica‐
       tion and its peer.

SYNOPSIS
       #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
       Kerberos 5 error code.  Credentials  for	 the  initiating  application.
       Specify GSS_C_NO_CREDENTIAL to use default credentials. If default cre‐
       dentials cannot be obtained, GSS_S_NO_CRED is returned.

	      If credentials for the initiating application are	 not  provided
	      and  default  credentials	 cannot be obtained from a credentials
	      cache, this function attempts to use the login name of the user.
	      gss_acquire_cred()  contains more information.  Security context
	      to be initiated. Specify GSS_C_NO_CONTEXT for first call and use
	      the value returned by the first call in continuation calls.

	      Resources	 associated  with this context must be released by the
	      application after use with a call	 to  gss_delete_sec_context().
	      Name  of	peer  application accepting the security context. This
	      name is an internal form name. The application must  obtain  the
	      internal	 form	name   beforehand   using   a	call  such  as
	      gss_import_name().  Object identifier (OID) of the desired secu‐
	      rity  mechanism.	Specify	 GSS_C_NO_OID to obtain the Kerberos 5
	      default.	Flags requesting that specific service options be sup‐
	      ported  by the security context. Symbolic names are provided for
	      each flag. The symbolic names need to be bitwise	ORed  together
	      to form the bit mask input value.

	      The flags are: CSF_GSS_C_DES_FLAG

	      True -- Request DES encryption.

	      False -- Do not request DES encryption.  CSF_GSS_C_DES3_FLAG

	      True -- Request DES3 encryption.

	      False -- Do not request DES3 encryption.

					    Note

	      DES3 and DES encryption are mutually exclusive and unique to the
	      HP implementation of the GSS-API.	 GSS_C_ANON_FLAG

	      Since the HP Application Security SDK does not support anonymous
	      authentication, this bit is ignored.  GSS_C_DELEG_FLAG

	      True -- Delegate credentials to the accepting application.

	      Set  this flag as true to allow the application to forward tick‐
	      ets. The user must also have a forwardable TGT.

	      False -- Do not delegate credentials.  GSS_C_MUTUAL_FLAG

	      True -- Request  that  the  accepting  application  authenticate
	      itself.

	      False -- Request one way authentication only.  GSS_C_REPLAY_FLAG

	      True -- Enable replay detection for protected messages.

	      False -- Do not attempt to detect replayed messages.

	      Replay  detection	 contains  more	 information  about the replay
	      cache.  GSS_C_SEQUENCE_FLAG

	      True -- Enable detection of out-of-sequence protected messages.

	      False -- Do  not	attempt	 to  detect  out-of-sequence  messages
	      Desired  number of seconds for which the security context should
	      remain valid. Since the HP implementation of  the	 GSS-API  does
	      not  support  security  context  expiration,  this  parameter is
	      ignored.	Application-specified bindings that allow the applica‐
	      tion  to securely bind channel identification information to the
	      security context. Specify GSS_C_NO_CHANNEL_BINDINGS  if  channel
	      bindings are not used.  Token received from the accepting appli‐
	      cation. Specify GSS_C_NO_BUFFER, or a pointer to a  buffer  con‐
	      taining  the  value  GSS_C_EMPTY_BUFFER, on the initial call. If
	      multiple invocations of this function are used  to  establish  a
	      context, the token will be different each time.  Security mecha‐
	      nism used that, in the HP implementation of GSS-API, is Kerberos
	      5.  Specify NULL if this information is not required.

	      The  storage associated with this OID set should be freed by the
	      application after use  with  a  call  to	gss_release_oid_set().
	      Token  to	 be  sent  to the accepting application. If a token is
	      created, it must be sent to the accepting application even if  a
	      return  code  indicates an error. The only exception is when the
	      length field of the returned token  buffer  is  zero,  in	 which
	      case, the token does not need to be sent to the accepting appli‐
	      cation.

	      The application must free storage associated  with  this	buffer
	      after use with a call to gss_release_buffer().  Flags indicating
	      the service options supported by the security context.  If  this
	      information is not needed, specify NULL.

	      Symbolic	names  are  provided  for each flag. (See Context Flag
	      Constants for the definitions.) The symbolic names  need	to  be
	      bitwise  ANDed with the value of the ret_flags parameter to test
	      whether a given option is supported by the context. Unused  bits
	      are set to zero.

					    Note

	      To check whether the requested encryption is being used (DES3 or
	      DES), call csf_gss_get_context_options().

	      The flags are: GSS_C_ANON_FLAG -- Since the HP Application Secu‐
	      rity  SDK	 does not support anonymous authentication, this value
	      is always set to false.  GSS_C_CONF_FLAG

	      True -- Confidentiality service may be invoked  by  calling  the
	      gss_wrap() function.

	      False -- No confidentiality service via gss_wrap() is available.
	      The gss_wrap() function  provides	 message  encapsulation,  data
	      origin	authentication,	   and	  integrity   services	 only.
	      GSS_C_DELEG_FLAG

	      True -- Credentials were delegated to the accepting application.

	      False -- No credentials were delegated.  GSS_C_INTEG_FLAG

	      True -- Integrity service	 may  be  invoked  by  calling	either
	      gss_get_mic() or gss_wrap().

	      False   --   Per-message	 integrity   service  is  unavailable.
	      GSS_C_MUTUAL_FLAG

	      True -- The remote peer that, in this  case,  is	the  accepting
	      application, requested mutual authentication.

	      False  -- The remote peer did not request mutual authentication.
	      GSS_C_PROT_READY_FLAG -- The value of  this  bit	indicates  the
	      actual  state  at	 the  time  gss_accept_sec_context()  returns,
	      whether or not the context is fully established.

	      True -- Protection services  (as	specified  by  the  states  of
	      GSS_C_CONF_FLAG and GSS_C_INTEG_FLAG) are available for use.

	      False  --	 Protection  services  (as  specified by the states of
	      GSS_C_CONF_FLAG and GSS_C_INTEG_FLAG) are available only if  the
	      security context is established.	GSS_C_REPLAY_FLAG

	      True -- Replay of protected messages will be detected.

	      False   --   Replay   of	 messages   will   not	 be  detected.
	      GSS_C_SEQUENCE_FLAG

	      True -- Out-of-sequence protected messages will be detected.

	      False  --	 Out-of-sequence  messages  will  not	be   detected.
	      GSS_C_TRANS_FLAG	--  The value of this bit indicates the actual
	      state at the time gss_accept_sec_context() returns,  whether  or
	      not the context is fully established.

	      True  --	The  resulting	security context may be transferred to
	      other processes via a call to gss_export_sec_context().

	      False -- The security context is not  transferable.   Number  of
	      seconds  for which the security context remains valid. Since the
	      HP implementation of the GSS-API does not support security  con‐
	      text  expiration, the value GSS_C_INDEFINITE is always returned.
	      Specify NULL if this information is not required.

DESCRIPTION
       The gss_init_sec_context() function initiates the  establishment	 of  a
       security	 context  between an application and its peer. A security con‐
       text must be established prior to exchanging secured messages.

       The initiating application may require  multiple	 invocations  of  this
       function	 to  establish a security context between it and the accepting
       application: If the gss_init_sec_context() function returns a  non-zero
       length  token  when  it is called, the token must be transferred to the
       accepting application even if an error is indicated.  When the  accept‐
       ing  application	 receives the token, it calls gss_accept_sec_context()
       and passes the token to it.  If the function returns a status  flag  of
       GSS_S_CONTINUE_NEEDED, a non-zero length output token is also returned.
       The token must be returned to the initiating  application  even	if  an
       error  is indicated.  If the function returns a major status containing
       GSS_C_COMPLETE, the security context is fully  established.   When  the
       initiating  application	receives the token, it calls gss_init_sec_con‐
       text() again, passing  the  token  to  it.   If	gss_init_sec_context()
       returns	a  major  status  containing  GSS_C_CONTINUE_NEEDED, the cycle
       repeats.	 If gss_init_sec_context() returns a major  status  containing
       GSS_C_COMPLETE, the security context is fully established.

	      When  multiple  iterations  are needed to establish the security
	      context, parameter values from the current call should  be  used
	      on subsequent calls.  The only exception is the input_token_buf‐
	      fer parameter whose value changes each time.

	      If the initial call of gss_init_sec_context() fails,  a  context
	      is  not created and the value of the context_handle parameter is
	      set to GSS_C_NO_CONTEXT to indicate this.

					    Note

	      Because of the way sequence numbers are incremented in  security
	      contexts,	 each  initiating  application needs a unique security
	      context with an accepting application. A single security context
	      must not be used with multiple initiating and accepting applica‐
	      tions.

	      Credential delegation (specified with  GSS_C_DELEG_FLAG  parame‐
	      ter)  should  be used judiciously, and only when necessary. When
	      credentials are delegated, the initial credential	 (the  ticket-
	      granting ticket, or TGT) from the initiator of the security con‐
	      text is forwarded to the acceptor.  This	results	 in  an	 extra
	      ticket  in  the acceptor's credentials cache that occupies addi‐
	      tional storage. Therefore, HP recommends, for both security  and
	      resource	reasons,  using credential delegation only when neces‐
	      sary. Credentials delegation requires that one of the  following
	      conditions   be	true:	The  target_name  input	 parameter  to
	      gss_init_sec_context()  must  be	 of   type   GSS_KRB5_NT_HOST‐
	      BASED_SERVICE_NAME.    Channel  bindings	must  be  provided  to
	      gss_init_sec_context()   and   gss_accept_sec_context()	 using
	      address type GSS_C_AF_INET.

       Before  calling this function, the application must obtain the internal
       form  name  of  the  accepting  application  using  a  call   such   as
       gss_import_name().

       When  the initiating application is finished using the context, it must
       release the resources associated with context_handle  with  a  call  to
       gss_delete_sec_context(). Storage associated with the following parame‐
       ters must also be freed when the data is	 no  longer  needed:  src_name
       with  a	call  to  gss_release_name() after the context is fully estab‐
       lished.	output_token with a call to  gss_release_buffer()  after  each
       invocation  of  gss_init_sec_context().	 delegated_cred_handle	with a
       call to gss_release_cred() after the context is fully established.

RETURN VALUES
       GSS_S_BAD_BINDINGS	       xx04xxxx
       GSS_S_BAD_MECH		       xx01xxxx
       GSS_S_BAD_NAME		       xx02xxxx
       GSS_S_BAD_NAMETYPE	       xx03xxxx
       GSS_S_CALL_BAD_STRUCTURE	       03xxxxxx
       GSS_S_CALL_INACCESSIBLE_READ    01xxxxxx
       GSS_S_CALL_INACCESSIBLE_WRITE   02xxxxxx
       GSS_S_COMPLETE		       00000000
       GSS_S_CONTINUE_NEEDED	       xxxx0001
       GSS_S_CREDENTIALS_EXPIRED       xx0Bxxxx
       GSS_S_DEFECTIVE_CREDENTIAL      xx0Axxxx
       GSS_S_DEFECTIVE_TOKEN	       xx09xxxx
       GSS_S_DUPLICATE_TOKEN	       xxxx0002
       GSS_S_FAILURE		       xx0Dxxxx
       GSS_S_NO_CONTEXT		       xx08xxxx
       GSS_S_NO_CRED		       xx07xxxx
       GSS_S_OLD_TOKEN		       xxxx0004
       GSS_S_UNSEQ_TOKEN	       xxxx0008

PORTABILITY CONSIDERATIONS
       Portable applications should be constructed to use the token length  to
       determine  whether  a  token needs to be sent. Tokens of zero length do
       not need to be sent.

       Return status should be used to determine whether waiting for  a	 reply
       is  necessary.  Thus,  an  initiating  application should always invoke
       gss_init_sec_context() within a loop.

       Since the HP implementation of DES3 is an extension of the GSS-API,  it
       will not interoperate with other GSS-API vendors offering DES3.

       Application  Security  SDK does not support anonymous authentication or
       context expiration.

SEE ALSO
       Functions:  csf_gss_get_context_options(3),  gss_accept_sec_context(3),
       gss_acquire_cred(3),   gss_delete_sec_context(3),   gss_export_sec_con‐
       text(3), gss_get_mic(3), gss_import_name(3), gss_import_sec_context(3),
       gss_inquire_context(3),	gss_release_buffer(3), gss_release_oid_set(3),
       gss_wrap(3)

						       gss_init_sec_context(3)
[top]

List of man pages available for DigitalUNIX

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