Index for Section 3

Alphabetical listing for G

Bottom of page

gss_acquire_cred(3)
NAME
  gss_acquire_cred - Acquire credentials for a specific internal name.

SYNOPSIS
  #include <gssapi/gssapi.h>

  OM_uint32 gss_acquire_cred (
	  OM_uint32 * minor_status,
	  const gss_name_t desired_name,
	  OM_uint32 time_req,
	  const gss_OID_set desired_mechs,
	  gss_cred_usage_t cred_usage,
	  gss_cred_id_t * output_cred_handle,
	  gss_OID_set * actual_mechs,
	  OM_uint32 * time_rec );

PARAMETERS
  minor_status
	  Kerberos 5 error code.

  desired_name
	  Name of the principal whose credentials are to be acquired. The
	  internal form name must be obtained beforehand using a call such as
	  gss_import_name().

	  If GSS_C_NO_NAME is specified, the call is interpreted as a request
	  for the credentials of the default principal. Description contains
	  an explanation of how Kerberos 5 handles default principals.

  time_req
	  Requested number of seconds that credentials remain valid. This
	  parameter is ignored by the HP implementation of the GSS-API
	  because it extracts from the credentials cache based on principal
	  identity, not longevity. Credentials lifetime is determined
	  external to GSS when the credentials are copied into the cache.

  desired_mechs
	  Object identifier (OID) set of security mechanisms that can be used
	  to acquire user credentials.	The HP implementation of the GSS-API
	  supports Kerberos 5.

	  Specify either rfc_krb5_c_OID_set for Kerberos 5 or
	  GSS_C_NO_OID_SET to obtain the default mechanism set that is the
	  same.

  cred_usage
	  Type of credentials to acquire. Typically, clients initiate and
	  servers accept. Credentials of type GSS_C_BOTH are used by servers
	  that also act as clients by contacting other servers.

	  GSS_C_BOTH
	      Credentials may be used to either initiate or accept security
	      contexts.

	  GSS_C_INITIATE
	      Credentials may be used only to initiate security contexts.

	  GSS_C_ACCEPT
	      Credentials may be used only to accept security contexts.

  output_cred_handle
	  The credentials that are returned for the principal name.

	  The resources associated with these credentials must be released by
	  the application after use with a call to gss_release_cred().

  actual_mechs
	  Security mechanisms for which the credentials are valid.

	  The storage associated with the returned OID set must be released
	  by the application after use with a call to gss_release_oid_set().

  time_rec
	  Actual number of seconds the returned credentials remain valid.

	  This parameter is valid only for initiator credentials. The HP
	  implementation of the GSS-API does not support credentials
	  expiration for acceptors. A value of GSS_C_INDEFINITE is always
	  returned for acceptors.

DESCRIPTION
  The gss_acquire_cred() function allows an application to acquire
  credentials by principal name. The credentials must already exist in a
  credentials cache created by a kinit command, HP Credentials Manager, or a
  csf_gss_acq_user() function call.  The resulting credentials allow a
  principal to initiate and/or accept security contexts (depending on the
  type of credential).

  Before calling this function, the application should call a function such
  as gss_import_name() to obtain the internal name of the principal.
  Otherwise, the default principal is used.

  To avoid memory leaks, the application must release the resources
  associated with the credentials with a call to gss_release_cred() after it
  is finished establishing security contexts. The storage associated with
  mechanisms OID set can be released anytime with a call to
  gss_release_oid_set().

  When a principal name is specified with gss_acquire_cred(), it is used to
  search the credentials cache for credentials. If valid credentials are not
  found, the service key table is searched. If no credentials are found, the
  gss_acquire_cred() function returns GSS_S_NO_CRED.

  If a principal name is not specified with this function, default Kerberos 5
  behavior is invoked:

    ·  For cred_usage of GSS_S_INITIATE and a desired_name of GSS_C_NO_NAME:

	 -- The credentials cache or the service key table are searched for a
	    default principal. If a default is found, it is then used to
	    search the credentials cache and service key table for initiator
	    credentials.

	 -- If a default principal name is not found, the user login name is
	    used to search the service key table for credentials.

	    For example, assume that user John Q. Public has the login ID of
	    john and that his UNIX uid is 112 and his realm is COMPANY.COM.
	    The name of John's default credentials cache would be derived
	    from his UNIX uid as /krb5/tmp/cc/krb5cc_112. Assuming John did
	    not specify an alternate principal when he executed the kinit
	    command or when the csf_gss_acq_user() function was called, the
	    cache's default principal would be john@COMPANY.COM. Therefore,
	    when John executes an application that calls gss_acquire_cred(),
	    setting cred_usage as GSS_C_INITIATE and desired_name as
	    GSS_C_NO_NAME, the principal name used is john@COMPANY.COM.

	    If there is no cache, the default name and realm are still used.
	    Assuming COMPANY.COM is the default realm, the principal name
	    used is john@COMPANY.COM.

    ·  For cred_usage of GSS_S_ACCEPT or GSS_C_BOTH and a desired_name of
       GSS_C_NO_NAME:

	 -- The principal name is formed from default values. The resulting
	    form uses host/FQDN@REALM, where FQDN is the host's fully
	    qualified domain name and REALM is the host's default realm. The
	    credentials cache and service key table are then searched for
	    credentials.

	 -- A common error that occurs when acquiring credentials of usage
	    GSS_S_ACCEPT or GSS_C_BOTH is that the service key table file is
	    not readable by the application.

       This function is optional if default credentials are used. For
       example, if an initiating application does not call gss_acquire_cred()
       before a gss_init_sec_context() call is made, credentials with the
       default name and usage GSS_C_INITIATE are acquired.  Similarly, if an
       accepting application does not call gss_acquire_cred() before a
       gss_accept_sec_context() call is made, credentials with the default
       name and usage GSS_C_ACCEPT are acquired.

RETURN VALUES
  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_FAILURE			  xx0Dxxxx
  GSS_S_NO_CRED			  xx07xxxx

SEE ALSO
  Functions:  csf_gss_acq_user(3), gss_accept_sec_context(3),
  gss_add_cred(3), gss_import_name(3), gss_init_sec_context(3),
  gss_inquire_cred(3), gss_inquire_cred_by_mech(3), gss_release_cred(3),
  gss_release_oid_set(3)

Index for Section 3

Alphabetical listing for G

Top of page