1gss_add_cred(3GSSG)eneric Security Services API Library Functiognsss_add_cred(3GSS)
2
3
4

NAME

6       gss_add_cred - add a credential-element to a credential
7

SYNOPSIS

9       cc [ flag... ] file... -lgss [ library... ]
10       #include <gssapi/gssapi.h>
11
12       OM_uint32 gss_add_cred(OM_uint32 *minor_status,
13            const gss_cred_id_t input_cred_handle,
14            const gss_name_t desired_name,
15            const gss_OID desired_mech,
16            gss_cred_usage_t cred_usage,
17            OM_uint32 initiator_time_req,
18            OM_uint32 acceptor_time_req,
19            gss_cred_id_t *output_cred_handle,
20            gss_OID_set *actual_mechs,
21            OM_uint32 *initiator_time_rec,
22            OM_uint32 *acceptor_time_rec);
23
24

PARAMETERS

26       The parameter descriptions for gss_add_cred() follow:
27
28       minor_status          Mechanism specific status code.
29
30
31       input_cred_handle     Credential  to  which  the  credential-element is
32                             added. If GSS_C_NO_CREDENTIAL is  specified,  the
33                             function  composes  the  new  credential based on
34                             default behavior. While the credential-handle  is
35                             not  modified  by  gss_add_cred(), the underlying
36                             credential is modified if  output_credential_han‐
37                             dle is NULL.
38
39
40       desired_name          Name  of  the  principal  for  which a credential
41                             should be acquired.
42
43
44       desired_mech          Underlying security mechanism with which the cre‐
45                             dential  can  be used. GSS_C_NULL_OID can be used
46                             to obtain a default.
47
48
49       cred_usage            Flag that indicates how a credential is  used  to
50                             initiate  or  accept security credentials. If the
51                             flag is GSS_C_ACCEPT, the  credentials  are  used
52                             only  to accept security credentials. If the flag
53                             is GSS_C_INITIATE, the credentials are used  only
54                             to  initiate security credentials. If the flag is
55                             GSS_C_BOTH, the credentials can be used to either
56                             initiate or accept security contexts.
57
58
59       initiator_time_req    Number  of seconds that the credential may remain
60                             valid  for  initiating  security  contexts.  This
61                             argument  is  ignored if the composed credentials
62                             are   of   the   GSS_C_ACCEPT    type.    Specify
63                             GSS_C_INDEFINITE  to request that the credentials
64                             have the maximum permitted initiator lifetime.
65
66
67       acceptor_time_req     Number of seconds that the credential may  remain
68                             valid for accepting security contexts. This argu‐
69                             ment is ignored if the composed  credentials  are
70                             of the GSS_C_INITIATE type. Specify GSS_C_INDEFI‐
71                             NITE to request that  the  credentials  have  the
72                             maximum permitted initiator lifetime.
73
74
75       output_cred_handle    Returned  credential handle that contains the new
76                             credential-element and  all  the  credential-ele‐
77                             ments  from input_cred_handle. If a valid pointer
78                             to a gss_cred_id_t is supplied for  this  parame‐
79                             ter, gss_add_cred() creates a new credential han‐
80                             dle that contains  all  credential-elements  from
81                             input_cred_handle  and the newly acquired creden‐
82                             tial-element.  If  NULL  is  specified  for  this
83                             parameter,  the newly acquired credential-element
84                             is  added  to  the   credential   identified   by
85                             input_cred_handle.
86
87                             The resources associated with any credential han‐
88                             dle returned by means of this parameter  must  be
89                             released  by  the application after use by a call
90                             to gss_release_cred(3GSS).
91
92
93       actual_mechs          Complete set of mechanisms for which the new cre‐
94                             dential  is  valid. Storage for the returned OID-
95                             set must be freed by the application after use by
96                             a call to gss_release_oid_set(3GSS). Specify NULL
97                             if this parameter is not required.
98
99
100       initiator_time_rec    Actual number of seconds for which  the  returned
101                             credentials  remain valid for initiating contexts
102                             using the specified  mechanism.  If  a  mechanism
103                             does  not  support expiration of credentials, the
104                             value GSS_C_INDEFINITE is returned. Specify  NULL
105                             if this parameter is not required.
106
107
108       acceptor_time_rec     Actual  number  of seconds for which the returned
109                             credentials remain valid for  accepting  security
110                             contexts  using  the  specified  mechanism.  If a
111                             mechanism does not support expiration of  creden‐
112                             tials,  the  value  GSS_C_INDEFINITE is returned.
113                             Specify NULL if this parameter is not required.
114
115

DESCRIPTION

117       The gss_add_cred() function adds a credential-element to a  credential.
118       The  credential-element  is  identified by the name of the principal to
119       which it refers. This function is not intended as a function  to  login
120       to  the network. A function for login to the network would involve cre‐
121       ating new mechanism-specific authentication data, rather than acquiring
122       a handle to existing data.
123
124
125       If  the value of desired_name is GSS_C_NO_NAME, the call is interpreted
126       as a request to add a credential-element  to  invoke  default  behavior
127       when passed to gss_init_sec_context(3GSS) if the value of cred_usage is
128       GSS_C_INITIATE or GSS_C_BOTH. The call is also interpreted as a request
129       to  add a credential-element to the invoke default behavior when passed
130       to  gss_accept_sec_context(3GSS)  if  the  value   of   cred_usage   is
131       GSS_C_ACCEPT or GSS_C_BOTH.
132
133
134       The gss_add_cred() function is expected to be used primarily by context
135       acceptors. The GSS-API provides mechanism-specific ways to obtain  GSS-
136       API  initiator  credentials  through  the  system login process. Conse‐
137       quently, the GSS-API  does  not  support  acquiring  GSS_C_INITIATE  or
138       GSS_C_BOTH  credentials by means of gss_acquire_cred(3GSS) for any name
139       other than the following:
140
141           o      GSS_C_NO_NAME
142
143           o      Name produced by gss_inquire_cred(3GSS) applied to  a  valid
144                  credential
145
146           o      Name  produced  by  gss_inquire_context(3GSS)  applied to an
147                  active context
148
149
150       If credential acquisition is time consuming for a mechanism, the mecha‐
151       nism can choose to delay the actual acquisition until the credential is
152       required   by   gss_init_sec_context(3GSS),   for   example,   or    by
153       gss_accept_sec_context(3GSS).  Such  mechanism-specific  implementation
154       decisions  are  invisible  to  the  calling  application.  A  call   to
155       gss_inquire_cred(3GSS)  immediately  following  the call gss_add_cred()
156       returns valid credential data as well  as  incurring  the  overhead  of
157       deferred credential acquisition.
158
159
160       The gss_add_cred() function can be used either to compose a new creden‐
161       tial that contains all credential-elements of the original in  addition
162       to the newly-acquired credential-element. The function can also be used
163       to add the new credential-element to an  existing  credential.  If  the
164       value  of the output_cred_handle parameter is NULL, the new credential-
165       element is added to the credential identified by input_cred_handle.  If
166       a  valid  pointer  is specified for the output_cred_handle parameter, a
167       new credential handle is created.
168
169
170       If  the  value  of  input_cred_handle   is   GSS_C_NO_CREDENTIAL,   the
171       gss_add_cred()  function  composes  a  credential  and  sets  the  out‐
172       put_cred_handle parameter based on the default behavior. The  call  has
173       the   same   effect  as  a  call  first  made  by  the  application  to
174       gss_acquire_cred(3GSS)  to  specify  the  same  usage   and   to   pass
175       GSS_C_NO_NAME  as  the desired_name parameter. Such an application call
176       obtains an explicit credential handle  that  incorporates  the  default
177       behaviors,  then  passes  the  credential handle to gss_add_cred(), and
178       finally calls gss_release_cred(3GSS) on the first credential handle.
179
180
181       If the value of the input_cred_handle parameter is GSS_C_NO_CREDENTIAL,
182       a non-NULL value must be supplied for the output_cred_handle parameter.
183

RETURN VALUES

185       The gss_add_cred() function can return the following status codes:
186
187       GSS_S_COMPLETE               Successful completion.
188
189
190       GSS_S_BAD_MECH               An    unavailable   mechanism   has   been
191                                    requested.
192
193
194       GSS_S_BAD_NAMETYPE           The type contained within the desired_name
195                                    parameter is not supported.
196
197
198       GSS_S_BAD_NAME               The value supplied for desired_name param‐
199                                    eter is ill formed.
200
201
202       GSS_S_DUPLICATE_ELEMENT      The credential already contains an element
203                                    for the requested mechanism that has over‐
204                                    lapping usage and validity period.
205
206
207       GSS_S_CREDENTIALS_EXPIRED    The credentials could not be added because
208                                    they have expired.
209
210
211       GSS_S_NO_CRED                No  credentials  were found for the speci‐
212                                    fied name.
213
214
215       GSS_S_FAILURE                The underlying mechanism detected an error
216                                    for  which  no specific GSS status code is
217                                    defined.  The  mechanism-specific   status
218                                    code reported by means of the minor_status
219                                    parameter details the error condition.
220
221

ATTRIBUTES

223       See attributes(5) for descriptions of the following attributes:
224
225
226
227
228       ┌─────────────────────────────┬─────────────────────────────┐
229       │      ATTRIBUTE TYPE         │      ATTRIBUTE VALUE        │
230       ├─────────────────────────────┼─────────────────────────────┤
231       │MT-Level                     │Safe                         │
232       └─────────────────────────────┴─────────────────────────────┘
233

SEE ALSO

235       gss_accept_sec_context(3GSS), gss_acquire_cred(3GSS), gss_init_sec_con‐
236       text(3GSS),      gss_inquire_context(3GSS),     gss_inquire_cred(3GSS),
237       gss_release_cred(3GSS),    gss_release_oid_set(3GSS),     libgss(3LIB),
238       attributes(5)
239
240
241       Solaris Security for Developers Guide
242
243
244
245SunOS 5.11                        30 Jun 2005               gss_add_cred(3GSS)
Impressum