'\" te
.\" Copyright (c) 2003, 2011, Oracle and/or its affiliates. All rights reserved.
.TH gss_acquire_cred 3GSS "22 Aug 2011" "SunOS 5.12" "Generic Security Services API Library Functions"
.SH NAME
gss_acquire_cred \- acquire a handle for a pre-existing credential by name
.SH SYNOPSIS
.LP
.nf
\fBcc\fR [ \fIflag\fR... ] \fIfile\fR... \fB-lgss\fR  [ \fIlibrary\fR... ] 
#include <gssapi/gssapi.h>

\fBOM_uint32\fR \fBgss_acquire_cred\fR(\fBOM_uint32 *\fR\fIminor_status\fR,
     \fBconst gss_name_t\fR \fIdesired_name\fR, \fBOM_uint32\fR \fItime_req\fR,
     \fBconst gss_OID_set\fR \fIdesired_mech\fR, \fBgss_cred_usage_t\fR \fIcred_usage\fR,
     \fBgss_cred_id_t *\fR\fIoutput_cred_handle\fR, \fBgss_OID_set *\fR\fIactual_mechs\fR,
     \fBOM_uint32 *\fR\fItime_rec\fR);
.fi

.SH DESCRIPTION
.sp
.LP
The \fBgss_acquire_cred()\fR function allows an application to acquire a handle for a pre-existing credential by name. This routine is not intended as a function to login to the network; a function for login to the network would involve creating new credentials rather than merely acquiring a handle to existing credentials.
.sp
.LP
If \fIdesired_name\fR is \fBGSS_C_NO_NAME\fR, the call is interpreted as a request for a credential handle that will invoke default behavior when passed to \fBgss_init_sec_context\fR(3GSS) (if \fIcred_usage\fR is \fBGSS_C_INITIATE\fR or \fBGSS_C_BOTH\fR) or \fBgss_accept_sec_context\fR(3GSS) (if \fIcred_usage\fR is \fBGSS_C_ACCEPT\fR or \fBGSS_C_BOTH\fR). 
.sp
.LP
Normally \fBgss_acquire_cred()\fR returns a credential that is valid only for the mechanisms requested by the \fIdesired_mechs\fR argument. However, if multiple mechanisms can share a single credential element, the function returns all the mechanisms for which the credential is valid in the \fIactual_mechs\fR argument.
.sp
.LP
\fBgss_acquire_cred()\fR is intended to be used primarily by context  acceptors, since the \fBGSS-API\fR routines obtain initiator credentials through the system login process. Accordingly, you may not acquire \fBGSS_C_INITIATE\fR or \fBGSS_C_BOTH\fR credentials by means of \fBgss_acquire_cred()\fR for any name other than \fBGSS_C_NO_NAME\fR. Alternatively, you may acquire \fBGSS_C_INITIATE\fR or \fBGSS_C_BOTH\fR credentials for a name produced when \fBgss_inquire_cred\fR(3GSS) is applied to a valid credential, or when \fBgss_inquire_context\fR(3GSS) is applied to an active context. 
.sp
.LP
If credential acquisition is time-consuming for a mechanism, the mechanism may choose to delay the actual acquisition until the credential is required, for example, by \fBgss_init_sec_context\fR(3GSS) or by \fBgss_accept_sec_context\fR(3GSS).  Such mechanism-specific implementations are, however, invisible to the calling application; thus a call of \fBgss_inquire_cred\fR(3GSS) immediately following the call of \fBgss_acquire_cred()\fR will return valid credential data and incur the overhead of a deferred credential acquisition.  
.SH PARAMETERS
.sp
.LP
The parameter descriptions for \fBgss_acquire_cred()\fR follow:
.sp
.ne 2
.mk
.na
\fB\fIdesired_name\fR\fR
.ad
.RS 22n
.rt  
The name of the principal for which a credential should be acquired.
.RE

.sp
.ne 2
.mk
.na
\fB\fItime_req\fR\fR
.ad
.RS 22n
.rt  
The number of seconds that credentials remain valid. Specify \fBGSS_C_INDEFINITE\fR  to request that the credentials have the maximum permitted lifetime
.RE

.sp
.ne 2
.mk
.na
\fB\fIdesired_mechs\fR\fR
.ad
.RS 22n
.rt  
The set of underlying security mechanisms that may be used.  \fBGSS_C_NO_OID_SET\fR may be used to obtain a default.
.RE

.sp
.ne 2
.mk
.na
\fB\fIcred_usage\fR\fR
.ad
.RS 22n
.rt  
A flag that indicates how this credential should be used. If the flag is \fBGSS_C_ACCEPT\fR, then credentials will be used only to accept security credentials. \fBGSS_C_INITIATE\fR indicates that credentials will be used only to initiate security credentials. If the flag is \fBGSS_C_BOTH\fR, then credentials may be used either to initiate or accept security contexts. 
.RE

.sp
.ne 2
.mk
.na
\fB\fIoutput_cred_handle\fR\fR
.ad
.RS 22n
.rt  
The returned credential handle.  Resources associated with this credential handle must be released by the application after use with a call to \fBgss_release_cred\fR(3GSS)
.RE

.sp
.ne 2
.mk
.na
\fB\fIactual_mechs\fR\fR
.ad
.RS 22n
.rt  
The set of mechanisms for which the credential is valid.  Storage associated with the returned \fBOID\fR-set must be released by the application after use with a call to  \fBgss_release_oid_set\fR(3GSS).  Specify \fBNULL\fR if not required.
.RE

.sp
.ne 2
.mk
.na
\fB\fItime_rec\fR\fR
.ad
.RS 22n
.rt  
Actual number of seconds for which the returned credentials will remain valid. Specify \fBNULL\fR if not required.
.RE

.sp
.ne 2
.mk
.na
\fB\fIminor_status\fR\fR
.ad
.RS 22n
.rt  
Mechanism specific status code.
.RE

.SH ERRORS
.sp
.LP
\fBgss_acquire_cred()\fR may return the following status code:
.sp
.ne 2
.mk
.na
\fB\fBGSS_S_COMPLETE\fR\fR
.ad
.RS 29n
.rt  
Successful completion.
.RE

.sp
.ne 2
.mk
.na
\fB\fBGSS_S_BAD_MECH\fR\fR
.ad
.RS 29n
.rt  
An unavailable mechanism has been requested.
.RE

.sp
.ne 2
.mk
.na
\fB\fBGSS_S_BAD_NAMETYPE\fR\fR
.ad
.RS 29n
.rt  
The type contained within the \fIdesired_name\fR parameter is not supported.
.RE

.sp
.ne 2
.mk
.na
\fB\fBGSS_S_BAD_NAME\fR\fR
.ad
.RS 29n
.rt  
The value supplied for \fIdesired_name\fR parameter is ill formed.
.RE

.sp
.ne 2
.mk
.na
\fB\fBGSS_S_CREDENTIALS_EXPIRED\fR\fR
.ad
.RS 29n
.rt  
The credentials could not be acquired because they have expired.
.RE

.sp
.ne 2
.mk
.na
\fB\fBGSS_S_NO_CRED\fR\fR
.ad
.RS 29n
.rt  
No credentials were found for the specified name.
.RE

.sp
.ne 2
.mk
.na
\fB\fBGSS_S_FAILURE\fR\fR
.ad
.RS 29n
.rt  
The underlying mechanism detected an error for which no specific \fBGSS\fR status code is defined.  The mechanism-specific status code reported by means of the \fIminor_status\fR parameter details the error condition.
.RE

.SH ATTRIBUTES
.sp
.LP
See \fBattributes\fR(5)  for descriptions of the following attributes:
.sp

.sp
.TS
tab() box;
cw(2.75i) |cw(2.75i) 
lw(2.75i) |lw(2.75i) 
.
ATTRIBUTE TYPEATTRIBUTE VALUE
_
MT-LevelSafe
.TE

.SH SEE ALSO
.sp
.LP
\fBgss_accept_sec_context\fR(3GSS), \fBgss_init_sec_context\fR(3GSS), \fBgss_inquire_context\fR(3GSS), \fBgss_inquire_cred\fR(3GSS), \fBgss_release_cred\fR(3GSS), \fBgss_release_oid_set\fR(3GSS), \fBattributes\fR(5)
.sp
.LP