path: root/usr/src/man/man3gss/gss_add_cred.3gss

'\" te
.\" Copyright (c) 2007, 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_add_cred 3GSS "30 Jun 2005" "SunOS 5.11" "Generic Security Services API Library Functions"
.SH NAME
gss_add_cred \- add a credential-element to a credential
.SH SYNOPSIS
.LP
.nf
\fBcc\fR [ \fIflag\fR... ] \fIfile\fR... \fB-lgss\fR [ \fIlibrary\fR... ]
#include <gssapi/gssapi.h>

\fBOM_uint32\fR \fBgss_add_cred\fR(\fBOM_uint32 *\fR\fIminor_status\fR,
     \fBconst gss_cred_id_t\fR \fIinput_cred_handle\fR,
     \fBconst gss_name_t\fR \fIdesired_name\fR,
     \fBconst gss_OID\fR \fIdesired_mech\fR,
     \fBgss_cred_usage_t\fR \fIcred_usage\fR,
     \fBOM_uint32\fR \fIinitiator_time_req\fR,
     \fBOM_uint32\fR \fIacceptor_time_req\fR,
     \fBgss_cred_id_t *\fR\fIoutput_cred_handle\fR,
     \fBgss_OID_set *\fR\fIactual_mechs\fR,
     \fBOM_uint32 *\fR\fIinitiator_time_rec\fR,
     \fBOM_uint32 *\fR\fIacceptor_time_rec\fR);
.fi

.SH PARAMETERS
.sp
.LP
The parameter descriptions for \fBgss_add_cred()\fR follow:
.sp
.ne 2
.mk
.na
\fB\fIminor_status\fR\fR
.ad
.RS 22n
.rt  
Mechanism specific status code.
.RE

.sp
.ne 2
.mk
.na
\fB\fIinput_cred_handle\fR\fR
.ad
.RS 22n
.rt  
Credential to which the credential-element is added. If
\fBGSS_C_NO_CREDENTIAL\fR is specified, the function composes the new
credential based on default behavior. While the credential-handle is not
modified by \fBgss_add_cred()\fR, the underlying credential is modified if
\fIoutput_credential_handle\fR is \fBNULL\fR.
.RE

.sp
.ne 2
.mk
.na
\fB\fIdesired_name\fR\fR
.ad
.RS 22n
.rt  
Name of the principal for which a credential should be acquired.
.RE

.sp
.ne 2
.mk
.na
\fB\fIdesired_mech\fR\fR
.ad
.RS 22n
.rt  
Underlying security mechanism with which the credential can be used.
GSS_C_NULL_OID can be used to obtain a default.
.RE

.sp
.ne 2
.mk
.na
\fB\fIcred_usage\fR\fR
.ad
.RS 22n
.rt  
Flag that indicates how a credential is used to initiate or accept security
credentials. If the flag is \fBGSS_C_ACCEPT\fR, the credentials are used only
to accept security credentials. If the flag is \fBGSS_C_INITIATE\fR, the
credentials are used only to initiate security credentials. If the flag is
GSS_C_BOTH, the credentials can be used to either initiate or accept security
contexts.
.RE

.sp
.ne 2
.mk
.na
\fB\fIinitiator_time_req\fR\fR
.ad
.RS 22n
.rt  
Number of seconds that the credential may remain valid for initiating security
contexts. This argument is ignored if the composed credentials are of the
\fBGSS_C_ACCEPT\fR type. Specify \fBGSS_C_INDEFINITE\fR to request that the
credentials have the maximum permitted initiator lifetime.
.RE

.sp
.ne 2
.mk
.na
\fB\fIacceptor_time_req\fR\fR
.ad
.RS 22n
.rt  
Number of seconds that the credential may remain valid for accepting security
contexts. This argument is ignored if the composed credentials are of the
\fBGSS_C_INITIATE\fR type. Specify \fBGSS_C_INDEFINITE\fR to request that the
credentials have the maximum permitted initiator lifetime.
.RE

.sp
.ne 2
.mk
.na
\fB\fIoutput_cred_handle\fR\fR
.ad
.RS 22n
.rt  
Returned credential handle that contains the new credential-element and all the
credential-elements from \fIinput_cred_handle\fR. If a valid pointer to a
\fBgss_cred_id_t\fR is supplied for this parameter, \fBgss_add_cred()\fR
creates a new credential handle that contains all credential-elements from
\fIinput_cred_handle\fR and the newly acquired credential-element. If
\fBNULL\fR is specified for this parameter, the newly acquired
credential-element is added to the credential identified by
\fIinput_cred_handle\fR.
.sp
The resources associated with any credential handle returned by means of this
parameter must be released by the application after use by a call to
\fBgss_release_cred\fR(3GSS).
.RE

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

.sp
.ne 2
.mk
.na
\fB\fIinitiator_time_rec\fR\fR
.ad
.RS 22n
.rt  
Actual number of seconds for which the returned credentials remain valid for
initiating contexts using the specified mechanism. If a mechanism does not
support expiration of credentials, the value \fBGSS_C_INDEFINITE\fR is
returned. Specify \fBNULL\fR if this parameter is not required.
.RE

.sp
.ne 2
.mk
.na
\fB\fIacceptor_time_rec\fR\fR
.ad
.RS 22n
.rt  
Actual number of seconds for which the returned credentials remain valid for
accepting security contexts using the specified mechanism. If a mechanism does
not support expiration of credentials, the value \fBGSS_C_INDEFINITE\fR is
returned. Specify \fBNULL\fR if this parameter is not required.
.RE

.SH DESCRIPTION
.sp
.LP
The \fBgss_add_cred()\fR function adds a credential-element to a credential.
The credential-element is identified by the name of the principal to which it
refers. This function is not intended as a function to login to the network. A
function for login to the network would involve creating new mechanism-specific
authentication data, rather than acquiring a handle to existing data.
.sp
.LP
If the value of \fIdesired_name\fR is \fBGSS_C_NO_NAME\fR, the call is
interpreted as a request to add a credential-element to invoke default behavior
when passed to \fBgss_init_sec_context\fR(3GSS) if the value of
\fIcred_usage\fR is \fBGSS_C_INITIATE\fR or \fBGSS_C_BOTH\fR. The call is also
interpreted as a request to add a credential-element to the invoke default
behavior when passed to \fBgss_accept_sec_context\fR(3GSS) if the value of
\fIcred_usage\fR is \fBGSS_C_ACCEPT\fR or \fBGSS_C_BOTH\fR.
.sp
.LP
The \fBgss_add_cred()\fR function is expected to be used primarily by context
acceptors. The \fBGSS-API\fR provides mechanism-specific ways to obtain
\fBGSS-API\fR initiator credentials through the system login process.
Consequently, the \fBGSS-API\fR does not support acquiring \fBGSS_C_INITIATE\fR
or \fBGSS_C_BOTH\fR credentials by means of \fBgss_acquire_cred\fR(3GSS) for
any name other than the following:
.RS +4
.TP
.ie t \(bu
.el o
\fBGSS_C_NO_NAME\fR
.RE
.RS +4
.TP
.ie t \(bu
.el o
Name produced by \fBgss_inquire_cred\fR(3GSS) applied to a valid credential
.RE
.RS +4
.TP
.ie t \(bu
.el o
Name produced by \fBgss_inquire_context\fR(3GSS) applied to an active context
.RE
.sp
.LP
If credential acquisition is time consuming for a mechanism, the mechanism can
choose to delay the actual acquisition until the credential is required by
\fBgss_init_sec_context\fR(3GSS), for example, or by
\fBgss_accept_sec_context\fR(3GSS). Such mechanism-specific implementation
decisions are invisible to the calling application. A call to
\fBgss_inquire_cred\fR(3GSS) immediately following the call
\fBgss_add_cred()\fR returns valid credential data as well as incurring the
overhead of deferred credential acquisition.
.sp
.LP
The \fBgss_add_cred()\fR function can be used either to compose a new
credential that contains all credential-elements of the original in addition to
the newly-acquired credential-element. The function can also be used to add the
new credential-element to an existing credential. If the value of the
\fIoutput_cred_handle\fR parameter is \fBNULL\fR, the new credential-element is
added to the credential identified by \fIinput_cred_handle\fR. If a valid
pointer is specified for the \fIoutput_cred_handle\fR parameter, a new
credential handle is created.
.sp
.LP
If the value of \fIinput_cred_handle\fR is \fBGSS_C_NO_CREDENTIAL\fR, the
\fBgss_add_cred()\fR function composes a credential and sets the
\fIoutput_cred_handle\fR parameter based on the default behavior. The call has
the same effect as a call first made by the application to
\fBgss_acquire_cred\fR(3GSS) to specify the same usage and to pass
\fBGSS_C_NO_NAME\fR as the \fIdesired_name\fR parameter. Such an application
call obtains an explicit credential handle that incorporates the default
behaviors, then passes the credential handle to \fBgss_add_cred()\fR, and
finally calls \fBgss_release_cred\fR(3GSS) on the first credential handle.
.sp
.LP
If the value of the \fIinput_cred_handle\fR parameter is
\fBGSS_C_NO_CREDENTIAL\fR, a non-\fBNULL\fR value must be supplied for the
\fIoutput_cred_handle\fR parameter.
.SH RETURN VALUES
.sp
.LP
The \fBgss_add_cred()\fR function can return the following status codes:
.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_DUPLICATE_ELEMENT\fR\fR
.ad
.RS 29n
.rt  
The credential already contains an element for the requested mechanism that has
overlapping usage and validity period.
.RE

.sp
.ne 2
.mk
.na
\fB\fBGSS_S_CREDENTIALS_EXPIRED\fR\fR
.ad
.RS 29n
.rt  
The credentials could not be added 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_acquire_cred\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), \fBlibgss\fR(3LIB), \fBattributes\fR(5)
.sp
.LP
\fISolaris Security for Developers Guide\fR