'\" te
.\" Copyright (C) 2003, Sun Microsystems, Inc. All Rights Reserved
.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License").  You may not use this file except in compliance with the License.
.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.  See the License for the specific language governing permissions and limitations under the License.
.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE.  If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
.TH gss_acquire_cred 3GSS "14 Jan 2003" "SunOS 5.11" "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
\fISolaris Security for Developers Guide\fR