gss_acquire_cred(3)                                     gss_acquire_cred(3)




 NAME    [Toc]    [Back]
      gss_acquire_cred() - allow an application to acquire a handle for an
      existing, named credential

 SYNOPSIS    [Toc]    [Back]
      #include <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,
                int cred_usage,
                gss_cred_id_t *output_cred_handle,
                gss_OID_set *actual_mechs,
                OM_int32 *time_rec );

 DESCRIPTION    [Toc]    [Back]
      The gss_acquire_cred() routine allows an application to obtain a
      handle for a pre-existing credential by name.  The credentials could
      be either an ACCEPT, INITIATE, or BOTH.  The application then passes
      the credential handle to either the gss_init_sec_context() or the
      gss_accept_sec_context() routine.  If desired_name is GSS_C_NO_NAME,
      the call is interpreted as a request for a credential handle that will
      invoke default behavior.

    Input Parameters    [Toc]    [Back]
      desired_name          Specifies the principal name to use for the
                            credential.

      time_req              Number of seconds that credentials remain valid.
                            Specify GSS_C_INDEFINITE to request that the
                            credentials have the maximum permitted lifetime.

      desired_mechs         Specifies the OID set for the security mechanism
                            to use with the credential.  To help ensure
                            portability of your application, request the
                            default security mechanism by specifying
                            GSS_C_NULL_OID_SET.

      cred_usage            Specify one of the following:

                            GSS_C_BOTH        Specifies credentials that the
                                              context initiator can use to
                                              either initiate or accept
                                              security contexts.

                            GSS_C_INITIATE    Specifies credentials that the
                                              context initiator can use only
                                              to initiate security contexts.




 Hewlett-Packard Company            - 1 -   HP-UX 11i Version 2: August 2003






 gss_acquire_cred(3)                                     gss_acquire_cred(3)




                            GSS_C_ACCEPT      Specifies credentials that the
                                              context initiator can use only
                                              to accept security contexts.

    Output Parameters    [Toc]    [Back]
      output_cred_handle    Returns the handle for the return credential.

      actual_mechs          Returns a set of mechanisms for which the
                            credential is valid.  This information is
                            optional.  If you do not want a set of
                            mechanisms returned, specify NULL.

      time_rec              Returns the actual number of seconds for which
                            the return credential remains valid.  This
                            information is optional.  If the actual number
                            of seconds is not required, specify NULL.

      minor_status          Returns a status code from the security
                            mechanism.

 STATUS CODES    [Toc]    [Back]
      The following list explains the GSS status codes that can be returned:

      GSS_S_COMPLETE           The routine was completed successfully.

      GSS_S_BAD_MECH           The requested security mechanism is
                               unsupported or unavailable.

      GSS_S_BAD_NAMETYPE       The name passed by the desired_name parameter
                               is unsupported.

      GSS_S_BAD_NAME           An invalid name was passed by the
                               desired_name parameter.

      GSS_S_CREDENTIALS_EXPIRED    [Toc]    [Back]
                               The credentials could not be acquired,
                               because they have expired.

      GSS_S_NO_CRED            No credentials were found for the specified
                               name.

      GSS_S_FAILURE            The routine failed. See the minor_status
                               parameter return value for more information.

 AUTHOR    [Toc]    [Back]
      gss_acquire_cred() was developed by Sun Microsystems, Inc.

 SEE ALSO    [Toc]    [Back]
      gss_init_sec_context(3).





 Hewlett-Packard Company            - 2 -   HP-UX 11i Version 2: August 2003






 gss_acquire_cred(3)                                     gss_acquire_cred(3)




      The manpages for DCE-GSSAPI are included with the DCE-CoreTools
      product.  To see those manpages add /opt/dce/share/man to MANPATH.


 Hewlett-Packard Company            - 3 -   HP-UX 11i Version 2: August 2003