'\" te

.\" Copyright (c) 2003, 2011, Oracle and/or its affiliates. All rights reserved.

.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