'\" 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 "Jan 14, 2003"
.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
.na
\fB\fIdesired_name\fR\fR
.ad
.RS 22n
The name of the principal for which a credential should be acquired.
.RE

.sp
.ne 2
.na
\fB\fItime_req\fR\fR
.ad
.RS 22n
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
.na
\fB\fIdesired_mechs\fR\fR
.ad
.RS 22n
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
.na
\fB\fIcred_usage\fR\fR
.ad
.RS 22n
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
.na
\fB\fIoutput_cred_handle\fR\fR
.ad
.RS 22n
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
.na
\fB\fIactual_mechs\fR\fR
.ad
.RS 22n
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
.na
\fB\fItime_rec\fR\fR
.ad
.RS 22n
Actual number of seconds for which the returned credentials will remain valid.
Specify \fBNULL\fR if not required.
.RE

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

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

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

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

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

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

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

.sp
.ne 2
.na
\fB\fBGSS_S_FAILURE\fR\fR
.ad
.RS 29n
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
box;
c | c
l | l .
ATTRIBUTE TYPE	ATTRIBUTE VALUE
_
MT-Level	Safe
.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