csf_gss_acq_user man page on DigitalUNIX

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

csf_gss_acq_user(3)					   csf_gss_acq_user(3)

NAME
       csf_gss_acq_user	 -  acquire a user's credentials prior to initiating a
       security context

SYNOPSIS
       #include <gssapi/gssapi.h>

       OM_uint32 csf_gss_acq_user (
	       OM_uint32 * minor_status,
	       const gss_name_t user_name,
	       const gss_OID_set desired_mechs,
	       const csf_gss_opts_t options,
	       const gss_buffer_t user_response,
	       csf_gss_user_t * user,
	       gss_buffer_t user_prompt,
	       gss_buffer_t user_label,
	       i_32 * prompt_state,
	       gss_OID * prompting_mech,
	       time_t * pwd_exp_time );

PARAMETERS
       Kerberos 5 error code.  Internal form name of the user for whom creden‐
       tials  are  being acquired. This name must be obtained beforehand using
       gss_import_name().

	      Specify GSS_C_NO_NAME to obtain the default that is  either  the
	      default  principal  in the credentials cache or the user's login
	      name.  Object identifier (OID) list of security mechanisms  that
	      can  be  used  to	 acquire  user	credentials.  The user must be
	      authorized to use the requested mechanisms. The  HP  implementa‐
	      tion of the GSS-API supports Kerberos 5.

	      Specify	GSS_C_NO_OID_SET  to  select  the  default  mechanism.
	      Options  that  determine	how  user  credentials	are  acquired.
	      Description  contains  information on storing and invoking these
	      options. Specify CSF_GSS_C_ACQ_USER_OPT_NONE to request a ticket
	      with no special options.

	      The following options require an associated value: Specifies the
	      credentials cache file name in string format.

	      Environment variables (CSFC5CCNAME on UNIX) or registry settings
	      (CredCache  key on Windows) can affect the location of this file
	      for the entire application. For more information on  these  set‐
	      tings  and  the required syntax for this parameter, see the Con‐
	      figuration section of the	 Developer  Pack  Installation	Guide.
	      Specifies the service key table file name in string format.

	      Environment variables (CSFC5KTNAME on UNIX) or registry settings
	      (KeyTab key on Windows) can affect the location of this file for
	      the  entire  application. For more information on these settings
	      and the required syntax for this parameter, see  the  Configura‐
	      tion  section  of the Developer Pack Installation Guide.	Speci‐
	      fies the credential's lifetime  in  string  format:  #w#d#h#m#s,
	      where # is the integer value, w is weeks, d is days, h is hours,
	      m is minutes, and s is seconds.  No spaces are  allowed  in  the
	      lifetime	string.	  Specifies  renewable	credentials,  with the
	      renew time in string format: #w#d#h#m#s, where # is the  integer
	      value, w is weeks, d is days, h is hours, m is minutes, and s is
	      seconds.	No spaces are allowed in the renew-time string.

	      For Kerberos credentials, use  this  option  to  request	either
	      renewable TGT or service ticket.

	      The following options do not require an associated value: Forces
	      csf_gss_acq_user()  to  obtain  new  credentials	regardless  of
	      whether valid credentials exist at the time of the call. If this
	      option is set, an application must prompt the user for  a	 pass‐
	      word  and other authentication information, using the prompt and
	      label information returned.  Specifies the use of	 DES3  encryp‐
	      tion  for	 obtaining  user  credentials.	 ActiveTRUST  Security
	      Server must be configured appropriately or an error may  result.
	      Specifies forwardable credentials.

	      For  Kerberos credentials, use this option to request a forward‐
	      able TGT.	 Skips preauthentication when  obtaining  credentials.
	      Specifies proxiable credentials.

	      For  Kerberos  credentials,  use this option to request either a
	      proxiable TGT or a proxy service	ticket.	  Obtains  credentials
	      using a key in the service key table file, rather than prompting
	      for a password.

	      This option may not be used with CSF_GSS_C_ACQ_USER_OPT_ENCTYPE.
	      Buffer  used  to return an application response to a user prompt
	      from the Kerberos 5 security mechanism. Make sure	 to  overwrite
	      the  data	 in the response buffer after use, because it can con‐
	      tain a password that could be compromised.

	      The application must specify GSS_C_NO_BUFFER on the  first  call
	      to csf_gss_acq_user().  User context being acquired.  The appli‐
	      cation  must  initialize	the  value  of	 this	parameter   to
	      CSF_GSS_C_NO_USER on the first call.

	      The  application	must  release the storage associated with this
	      parameter with a call to csf_gss_release_user().	Buffer used by
	      the  Kerberos 5 security mechanism to pass prompts to the appli‐
	      cation. Any information returned must be displayed to the	 user.
	      This buffer is empty if no prompting is occurring.

	      The  application	must  release  this  buffer  with  a  call  to
	      gss_release_buffer()  after  each	 call  to  csf_gss_acq_user().
	      Buffer  used by the Kerberos 5 security mechanism to pass infor‐
	      mation regarding the prompting process to the  application.  Any
	      information  returned must be displayed to the user. This buffer
	      is empty if no prompting is occurring.

	      The  application	must  release  this  buffer  with  a  call  to
	      gss_release_buffer()  after  each	 call  to  csf_gss_acq_user().
	      Pointer to an integer used by the	 security  mechanism  to  pass
	      prompt  state  information  to  the application. The information
	      contained in this parameter can be used by  the  application  to
	      make decisions about the prompting that may need to occur.

	      On  the  first  call,  initialize the value of this parameter to
	      CSF_GSS_C_USER_STATE_NULL. Do not pass in a NULL	value.	As  an
	      example, initialize this parameter as:

	      int prompt_state=CSF_GSS_C_USER_STATE_NULL

	      The  possible  return  states are: Indicates that the Kerberos 5
	      mechanism requires a response to a challenge, and that the  user
	      response should be echoed as it is entered.

	      This state can be used for hardware authentication challenge and
	      response systems.	  Indicates  that  the	Kerberos  5  mechanism
	      requires	a  response to a challenge, and that the user response
	      should not be echoed as it is entered.  Indicates that the mech‐
	      anism  requires  a  password,  and  the  user response should be
	      echoed as it is entered.	Indicates that the Kerberos  5	mecha‐
	      nism  requires a password, and that the user response should not
	      be echoed as it is entered.  Indicates that the Kerberos 5 mech‐
	      anism has an associated one-time password (OTP) hardware authen‐
	      tication token issuing a request for information, and  that  the
	      user response should be echoed as it is entered.	Indicates that
	      the Kerberos 5 mechanism has  an	associated  one-time  password
	      hardware authentication token issuing a request for information,
	      and that the user	 response  should  not	be  echoed  as	it  is
	      entered.	 Security  mechanism issuing the prompt. The HP imple‐
	      mentation of the GSS-API supports Kerberos 5.

	      The OID is allocated from static memory and must not be released
	      by  the  application.   Expiration  time of the user's password,
	      expressed in seconds. This information can be processed  by  the
	      application and displayed to the user in an application-specific
	      format. For example, when coding in C, ctime() can  be  used  to
	      convert the value of this parameter to a date string.

	      Password	expiration information is returned only if a user does
	      not have valid credentials. If new credentials are required, the
	      password expiration time is returned. If the user has valid cre‐
	      dentials, a value of -1 is returned. To force the return of  the
	      expiration	  time,		use	    the		option
	      CSF_GSS_ACQ_USER_OPT_ALWAYS_FETCH.

DESCRIPTION
       The csf_gss_acq_user() function is an extension that acquires user cre‐
       dentials	 using either secret-key or public-key authentication with DES
       or, optionally, DES3 encryption.

       This function constructs a credentials cache for the user  if  it  does
       not  exist.  If	the  credentials cache does exist but contains invalid
       credentials for the user, the cache is re-initialized. Credentials  are
       considered  invalid  if their characteristics do not match the criteria
       of the desired credentials (identity, lifetime, flags such as  forward‐
       able or renewable, and encryption type such as DES or DES3).

					Note

       Information  on	the types of Kerberos tickets (forwardable, proxiable,
       etc.) is provided in Security Server Administration Guide.

       If the credentials cache does contain valid credentials for  the	 user,
       it  is  not  changed  (unless  the  CSF_GSS_C_ACQ_USER_OPT_ALWAYS_FETCH
       option is selected).

					Note

       If the csf_gss_acq_user() function will destroy the credentials	cache,
       the  application must be aware of other applications on the same system
       and ensure that no other application is using the credentials cache.

       To use the csf_gss_acq_user() function with  Kerberos  5:  Specify  the
       rfc_krb5_c_OID_set  as  the security mechanism.	Select the appropriate
       acquisition options and, if necessary,  provide	an  associated	value.
       Respond	to prompts. The csf_gss_acq_user() function returns parameters
       that identify the  security  mechanism  issuing	a  prompt,  the	 state
       desired (how the prompt should be processed), and any user prompt.

       The  csf_gss_acq_user()	function may need to be called iteratively: If
       it returns GSS_S_COMPLETE, the function has completed its task.	If  it
       returns	GSS_S_CONTINUE_NEEDED,	one  or more prompts from the security
       mechanism must be satisfied. Values for the  user_name,	desired_mechs,
       user,  prompt_state, options, and prompting_mech parameters must be the
       same across multiple calls to the same function.

       An application can specify one or more options for acquiring user  cre‐
       dentials.

       The  following type definition shows the data structure used to store a
       single option.  typedef struct csf_gss_mech_opt_desc_struct {
	  gss_OID   mechOID;   /* Mech to specify option for */
	  OM_uint32 id;	       /* Identifier of option */
	  void *      val;     /* Value associated with option */
			       /* if appropriate */  }	csf_gss_mech_opt_desc,
       *csf_gss_opts_t;

       An array of these structures, one for each option desired, must be con‐
       structed.  Initialize the mechOID field of the last record of the array
       to GSS_C_NO_OID.

       The  following  example	C  code	 fragment  shows  how  to use options.
       csf_gss_opts_t	      opts; #define		  NUM_OPTS_SET	     3
       /*  *  Allocate	memory across mechanisms to set 2 options. Since you *
       must NULL-terminate the array, allocate one more array element  *  than
       that.	 */    opts    =    (csf_gss_opts_t)   malloc(NUM_OPTS_SET   *
       sizeof(csf_gss_mech_opt_desc)); /* * Since the first  occurrence	 of  a
       NULL  mechanism OID field signals * csf_gss_acq_user() to stop process‐
       ing options, initialize these * fields to GSS_C_NO_OID.	This  practice
       will help prevent the call * searching outside of the array bounds.  */
       for (i = 0; i < NUM_OPTS_SET; i++)
	 opts[i].mechOID = GSS_C_NO_OID; /* Set mechs  and  their  options  */
       opts[0].mechOID	=  rfc_krb5_c_OID;    /*  Kerb	5 mechanism options */
       opts[0].id  =  CSF_GSS_C_ACQ_USER_OPT_LIFETIME;	 /*  Set  lifetime  */
       opts[0].val = (void*)"9h"; opts[1].mechOID = rfc_krb5_c_OID; opts[1].id
       = CSF_GSS_C_ACQ_USER_OPT_FORWARDABLE; /* Make TGT forwardable*/	/*  No
       value associated with this option */

       /*  Acquire  the	 user  */ csf_gss_acq_user(..., opts,...); /* Free the
       memory */ free(opts);

       To avoid memory leaks, the application must: Release the storage	 asso‐
       ciated  with  the  user parameter with a call to csf_gss_release_user()
       Release the buffers associated  with  the  user_prompt  and  user_label
       parameters with gss_release_buffer() after each call.

RETURN VALUES
       GSS_S_BAD_MECH		       xx01xxxx
       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_FAILURE		       xx0Dxxxx

PORTABILITY CONSIDERATIONS
       This  function is an extension of the GSS-API standard that is not sup‐
       ported by other GSS-API implementations.

SEE ALSO
       Functions:  csf_gss_inq_user(3),		      csf_gss_release_user(3),
       gss_import_name(3), gss_release_buffer(3)

							   csf_gss_acq_user(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