1 '\" te

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

     3 .TH gss_add_cred 3GSS "30 Jun 2005" "SunOS 5.12" "Generic Security Services API Library Functions"

     4 .SH NAME

     5 gss_add_cred \- add a credential-element to a credential

     6 .SH SYNOPSIS

     7 .LP

     8 .nf

     9 \fBcc\fR [ \fIflag\fR... ] \fIfile\fR... \fB-lgss\fR [ \fIlibrary\fR... ]

    10 #include <gssapi/gssapi.h>

    11 

    12 \fBOM_uint32\fR \fBgss_add_cred\fR(\fBOM_uint32 *\fR\fIminor_status\fR,

    13      \fBconst gss_cred_id_t\fR \fIinput_cred_handle\fR,

    14      \fBconst gss_name_t\fR \fIdesired_name\fR,

    15      \fBconst gss_OID\fR \fIdesired_mech\fR,

    16      \fBgss_cred_usage_t\fR \fIcred_usage\fR,

    17      \fBOM_uint32\fR \fIinitiator_time_req\fR,

    18      \fBOM_uint32\fR \fIacceptor_time_req\fR,

    19      \fBgss_cred_id_t *\fR\fIoutput_cred_handle\fR,

    20      \fBgss_OID_set *\fR\fIactual_mechs\fR,

    21      \fBOM_uint32 *\fR\fIinitiator_time_rec\fR,

    22      \fBOM_uint32 *\fR\fIacceptor_time_rec\fR);

    23 .fi

    24 

    25 .SH PARAMETERS

    26 .sp

    27 .LP

    28 The parameter descriptions for \fBgss_add_cred()\fR follow:

    29 .sp

    30 .ne 2

    31 .mk

    32 .na

    33 \fB\fIminor_status\fR\fR

    34 .ad

    35 .RS 22n

    36 .rt  

    37 Mechanism specific status code.

    38 .RE

    39 

    40 .sp

    41 .ne 2

    42 .mk

    43 .na

    44 \fB\fIinput_cred_handle\fR\fR

    45 .ad

    46 .RS 22n

    47 .rt  

    48 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.

    49 .RE

    50 

    51 .sp

    52 .ne 2

    53 .mk

    54 .na

    55 \fB\fIdesired_name\fR\fR

    56 .ad

    57 .RS 22n

    58 .rt  

    59 Name of the principal for which a credential should be acquired.

    60 .RE

    61 

    62 .sp

    63 .ne 2

    64 .mk

    65 .na

    66 \fB\fIdesired_mech\fR\fR

    67 .ad

    68 .RS 22n

    69 .rt  

    70 Underlying security mechanism with which the credential can be used. GSS_C_NULL_OID can be used to obtain a default.

    71 .RE

    72 

    73 .sp

    74 .ne 2

    75 .mk

    76 .na

    77 \fB\fIcred_usage\fR\fR

    78 .ad

    79 .RS 22n

    80 .rt  

    81 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.

    82 .RE

    83 

    84 .sp

    85 .ne 2

    86 .mk

    87 .na

    88 \fB\fIinitiator_time_req\fR\fR

    89 .ad

    90 .RS 22n

    91 .rt  

    92 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.

    93 .RE

    94 

    95 .sp

    96 .ne 2

    97 .mk

    98 .na

    99 \fB\fIacceptor_time_req\fR\fR

   100 .ad

   101 .RS 22n

   102 .rt  

   103 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.

   104 .RE

   105 

   106 .sp

   107 .ne 2

   108 .mk

   109 .na

   110 \fB\fIoutput_cred_handle\fR\fR

   111 .ad

   112 .RS 22n

   113 .rt  

   114 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.

   115 .sp

   116 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).

   117 .RE

   118 

   119 .sp

   120 .ne 2

   121 .mk

   122 .na

   123 \fB\fIactual_mechs\fR\fR

   124 .ad

   125 .RS 22n

   126 .rt  

   127 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.

   128 .RE

   129 

   130 .sp

   131 .ne 2

   132 .mk

   133 .na

   134 \fB\fIinitiator_time_rec\fR\fR

   135 .ad

   136 .RS 22n

   137 .rt  

   138 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.

   139 .RE

   140 

   141 .sp

   142 .ne 2

   143 .mk

   144 .na

   145 \fB\fIacceptor_time_rec\fR\fR

   146 .ad

   147 .RS 22n

   148 .rt  

   149 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.

   150 .RE

   151 

   152 .SH DESCRIPTION

   153 .sp

   154 .LP

   155 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.

   156 .sp

   157 .LP

   158 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.

   159 .sp

   160 .LP

   161 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:

   162 .RS +4

   163 .TP

   164 .ie t \(bu

   165 .el o

   166 \fBGSS_C_NO_NAME\fR

   167 .RE

   168 .RS +4

   169 .TP

   170 .ie t \(bu

   171 .el o

   172 Name produced by \fBgss_inquire_cred\fR(3GSS) applied to a valid credential

   173 .RE

   174 .RS +4

   175 .TP

   176 .ie t \(bu

   177 .el o

   178 Name produced by \fBgss_inquire_context\fR(3GSS) applied to an active context

   179 .RE

   180 .sp

   181 .LP

   182 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.

   183 .sp

   184 .LP

   185 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.

   186 .sp

   187 .LP

   188 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.

   189 .sp

   190 .LP

   191 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.

   192 .SH RETURN VALUES

   193 .sp

   194 .LP

   195 The \fBgss_add_cred()\fR function can return the following status codes:

   196 .sp

   197 .ne 2

   198 .mk

   199 .na

   200 \fB\fBGSS_S_COMPLETE\fR\fR

   201 .ad

   202 .RS 29n

   203 .rt  

   204 Successful completion.

   205 .RE

   206 

   207 .sp

   208 .ne 2

   209 .mk

   210 .na

   211 \fB\fBGSS_S_BAD_MECH\fR\fR

   212 .ad

   213 .RS 29n

   214 .rt  

   215 An unavailable mechanism has been requested.

   216 .RE

   217 

   218 .sp

   219 .ne 2

   220 .mk

   221 .na

   222 \fB\fBGSS_S_BAD_NAMETYPE\fR\fR

   223 .ad

   224 .RS 29n

   225 .rt  

   226 The type contained within the \fIdesired_name\fR parameter is not supported.

   227 .RE

   228 

   229 .sp

   230 .ne 2

   231 .mk

   232 .na

   233 \fB\fBGSS_S_BAD_NAME\fR\fR

   234 .ad

   235 .RS 29n

   236 .rt  

   237 The value supplied for \fIdesired_name\fR parameter is ill formed.

   238 .RE

   239 

   240 .sp

   241 .ne 2

   242 .mk

   243 .na

   244 \fB\fBGSS_S_DUPLICATE_ELEMENT\fR\fR

   245 .ad

   246 .RS 29n

   247 .rt  

   248 The credential already contains an element for the requested mechanism that has overlapping usage and validity period.

   249 .RE

   250 

   251 .sp

   252 .ne 2

   253 .mk

   254 .na

   255 \fB\fBGSS_S_CREDENTIALS_EXPIRED\fR\fR

   256 .ad

   257 .RS 29n

   258 .rt  

   259 The credentials could not be added because they have expired.

   260 .RE

   261 

   262 .sp

   263 .ne 2

   264 .mk

   265 .na

   266 \fB\fBGSS_S_NO_CRED\fR\fR

   267 .ad

   268 .RS 29n

   269 .rt  

   270 No credentials were found for the specified name.

   271 .RE

   272 

   273 .sp

   274 .ne 2

   275 .mk

   276 .na

   277 \fB\fBGSS_S_FAILURE\fR\fR

   278 .ad

   279 .RS 29n

   280 .rt  

   281 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.

   282 .RE

   283 

   284 .SH ATTRIBUTES

   285 .sp

   286 .LP

   287 See \fBattributes\fR(5) for descriptions of the following attributes:

   288 .sp

   289 

   290 .sp

   291 .TS

   292 tab() box;

   293 cw(2.75i) |cw(2.75i) 

   294 lw(2.75i) |lw(2.75i) 

   295 .

   296 ATTRIBUTE TYPEATTRIBUTE VALUE

   297 _

   298 MT-LevelSafe

   299 .TE

   300 

   301 .SH SEE ALSO

   302 .sp

   303 .LP

   304 \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)

   305 .sp

   306 .LP

   307 \fI\fR