*nix Documentation Project
·  Home
 +   man pages
·  Linux HOWTOs
·  FreeBSD Tips
·  *niX Forums

  man pages->Tru64 Unix man pages -> gss_acquire_cred (3)              
Title
Content
Arch
Section
 

gss_acquire_cred(3)

Contents


NAME    [Toc]    [Back]

       gss_acquire_cred  -  Acquire  credentials  for  a specific
       internal name.

SYNOPSIS    [Toc]    [Back]

       #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    [Toc]    [Back]

       Kerberos 5 error code.  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.
              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.   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.   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.  Credentials may be used  to  either
              initiate  or accept security contexts.  Credentials
              may be used only  to  initiate  security  contexts.
              Credentials  may  be  used  only to accept security
              contexts.  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().  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().  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    [Toc]    [Back]

       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    [Toc]    [Back]

       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    [Toc]    [Back]

      
      
       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)



                                              gss_acquire_cred(3)
[ Back ]
 Similar pages
Name OS Title
csf_gss_acq_user Tru64 acquire a user's credentials prior to initiating a security context
gss_inquire_cred_by_mech Tru64 obtain information about credentials for a specific security mechanism
SSL_CTX_get_ex_new_index Tru64 Internal application specific data functions
SSL_CTX_get_ex_data Tru64 Internal application specific data functions
SSL_CTX_set_ex_data OpenBSD internal application specific data functions
SSL_CTX_get_ex_new_index OpenBSD internal application specific data functions
SSL_SESSION_set_ex_data OpenBSD internal application specific data functions
CRYPTO_get_ex_data Tru64 Internal application specific data functions
SSL_get_ex_new_index NetBSD internal application specific data functions
SSL_SESSION_get_ex_new_index NetBSD internal application specific data functions
Copyright © 2004-2005 DeniX Solutions SRL
newsletter delivery service