'\" te

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

.TH gss_add_cred 3GSS "30 Jun 2005" "SunOS 5.12" "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

\fI\fR