[an error occurred while processing this directive]

HP OpenVMS Systems Documentation
Content starts here
HP Open Source Security for OpenVMS Volume 3: Kerberos > Chapter 5 GSSAPI (Generic Security Services Application Programming Interface)

gss_acquire_cred — Acquire credential handle

 » Table of Contents

 » Glossary

 » Index

spacerspacerspacer
spacer
spacer
  		 
 

C Prototype

OM_uint32 gss_acquire_cred(
        OM_uint32               * minor_status,
        gss_name_t                desired_name,
        OM_uint32                 time_req,
        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 );

Arguments

minor_status (output) 

The mechanism-specific status code.

desired_name (input) 

The name of the principal whose credential should be acquired.

time_req (input) 

The number of seconds that credentials should remain valid. Specify GSS_C_INDIFINITE to request that the credentials have the maximum permitted lifetime.

desired_mechs (input) 

The set of underlying security mechanisms that may be used. GSS_C_NULL_OID_SET may be used to obtain an implementation-specific default.

cred_usage (input) 

One of the following values:

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

GSS_C_INITIATE — Credentials will only be used to initiate security contexts.

GSS_C_ACCEPT — Credentials will only be used to accept security contexts.

output_cred_handle (output) 

The returned credential handle. Resources associated with this credential handle must be released by the application after use with a call to gss_release_cred.

actual_mechs (output) 

The set of mechanisms for which the credential is valid. Storage associated with the returned OID-set must be released by the application after use with a call to gss_release_oid_set. Specify NULL if not required.

time_rec (output) 

The actual number of seconds for which the returned credentials will remain valid. If the implementation does not support expiration of credentials, the value GSS_C_INDEFINITE will be returned. Specify NULL if not required.

Description

This routine allows an application to acquire a handle for a pre-existing credential by name. GSSAPI implementations must impose a local access-control policy on callers of this routine to prevent unauthorized callers from acquiring credentials to which they are not entitled. This routine is not intended to provide a "login to the network" function, as such a function would result in the creation of new credentials rather than merely acquiring a handle to existing credentials.

If desired_name is GSS_C_NO_NAME, the call is interpreted as a request for a credential handle that will invoke default behavior when passed to gss_init_sec_context (if cred_usage is GSS_C_INITIATE or GSS_C_BOTH) or gss_accept_sec_context (if cred_usage is GSS_C_ACCEPT or GSS_C_BOTH).

This routine is expected to be used primarily by context acceptors.

Return Values

This routine returns one of the following GSS status codes:

GSS_S_COMPLETE

Successful completion.
GSS_S_BAD_MECHUnavailable mechanism requested.
GSS_S_BAD_NAMETYPEThe type contained within the desired_name argument is not supported.
GSS_S_BAD_NAMEThe value supplied for the desired_name argument is ill formed.

GSS_S_NO_CRED

The supplied credentials were not valid for context acceptance, or the credential handle did not reference any credentials.

GSS_S_CREDENTIALS_EXPIRED

The referenced credentials have expired.



gss_accept_sec_context — Establish a security context
  		 


gss_add_cred — Construct credentials incrementally