1CSEC_API(3) LCG Security Functions
2CSEC_API(3)
3[1mNAME[0m
7 Csec_api ‐ Provides authentication in LCG services
8[1mSYNOPSIS[0m
10 Header file:
11 [1m#include <Csec_api.h>[0m
13 On the client side:
15 [1mint Csec_client_initContext(Csec_context_t
17*[4m[22mctx,[24m [1mint [4m[22mservice_type,[0m
18 [1mCsec_protocol *[4m[22mprotocols[24m[1m);[0m
19 [1mint Csec_client_establishContext(Csec_context_t
20*[4m[22mctx,[24m [1mint [4m[22msocket[24m[1m);[0m
21 [1mint Csec_client_setSecurityOpts(Csec_context_t
22*[4m[22mctx,[24m [1mint [4m[22mopt[24m[1m);[0m
23 [1mint Csec_client_setAuthorizationId(Csec_context_t
24*[4m[22mctx,[24m [1mconst char[0m
25 [1m*[4m[22mmech,[24m [1mconst char
26*[4m[22mname[24m[1m);[0m
27 [1mint Csec_client_setVOMS_data(Csec_context_t
28*[4m[22mctx,[24m [1mconst char *[4m[22mvoname,[0m
29 [1mchar **[4m[22mfqan,[24m [1mint
30[4m[22mnbfqan[24m[1m);[0m
31 On the server side:
33 [1mint Csec_server_initContext(Csec_context_t *[4m[22mc‐
35tx,[24m [1mint [4m[22mservice_type[24m[1m,[0m
36 [1mCsec_protocol *[4m[22mprotocols[24m[1m);[0m
37 [1mint Csec_server_reinitContext (Csec_context_t
38*[4m[22mctx,[24m [1mint [4m[22mservice_type[24m[1m,[0m
39 [1mCsec_protocol *[4m[22mprotocols[24m[1m);[0m
40 [1mint Csec_server_establishContext (Csec_context_t
41*[4m[22mctx,[24m [1mint [4m[22msocket[24m[1m);[0m
42 [1mint Csec_server_getClientId(Csec_context_t *[4m[22mc‐
43tx,[24m [1mchar **[4m[22mmech,[24m [1mchar[0m
44 [1m**[4m[22mname[24m[1m);[0m
45 [1mint Csec_server_getAuthorizationId(Csec_context_t
46*[4m[22mctx,[24m [1mchar **[4m[22mmech,[0m
47 [1mchar **[4m[22mname[24m[1m);[0m
48 [1mint Csec_server_getDelegatedCredentials(Csec_con‐
49text_t *[4m[22mctx,[24m [1mchar[0m
50 [1m**[4m[22mmech,[24m [1mvoid ** [4m[22mbuf,[24m [1msize_t
51*[4m[22msize[24m[1m);[0m
52 [1mint Csec_server_setSecurityOpts(Csec_context_t
53*[4m[22mctx,[24m [1mint [4m[22mopt[24m[1m);[0m
54 [1mchar *Csec_server_get_client_ca(Csec_context_t
55*[4m[22mctx);[0m
56 [1mchar *Csec_server_get_client_vo(Csec_context_t
57*[4m[22mctx);[0m
58 [1mchar **Csec_server_get_client_fqans(Csec_context_t
59*[4m[22mctx,[24m [1mint *[4m[22mnbfqan);[0m
60 Common functions:
62 [1mint Csec_clearContext(Csec_context_t *[4m[22mc‐
64tx[24m[1m);[0m
65 [1mint Csec_getErrorMessage();[0m
66 [1mint Csec_getErrorMessageSummary(size_t
67[4m[22mmaxlen[24m[1m);[0m
68 [1mint Csec_mapToLocalUser(const char *[4m[22mmech,[24m
69[1mconst char *[4m[22mname,[24m [1mchar *[4m[22muser‐[0m
70 [4mname,[24m [1msize_t [4m[22musername_size,[24m [1muid_t
71*[4m[22muid,[24m [1mgid_t *[4m[22mgid[24m[1m);[0m
72 [1mCsec_context_t * Csec_get_default_context();[0m
73[1mDESCRIPTION[0m
76 [1mCsec_api [22mfunctions allow for the implimentation of
77strong authentica‐
78 tion mechanisms in LCG servers and clients. Csec_api is
79integrated with
80 the LCG framework for errors.
81 [1mCsec_client_initContext, Csec_server_initContext,
84Csec_server_reinit‐[0m
85 [1mContext[0m
86 allow to initialize the [1mCsec_context_t
87[22mstructure. The service
88 type parameter defines which type of key will be
89used by the
90 service. Its value can be:
91 [1mCSEC_SERVICE_TYPE_HOST[0m
93 A normal host key (e.g. host/ma‐
94chine_name@DOMAIN for
95 KRB5) will be used
96 [1mCSEC_SERVICE_TYPE_CENTRAL[0m
98 A LCG Central host type key
99(e.g. castor‐
100 central/machine_name@DOMAIN for KRB5) will
101be used
102 [1mCSEC_SERVICE_TYPE_DISK[0m
104 A LCG disk host type key
105(e.g. cas‐
106 tordisk/machine_name@DOMAIN for KRB5) will
107be used
108 [1mCSEC_SERVICE_TYPE_TAPE[0m
110 A LCG tape host type key
111(e.g. castor‐
112 tape/machine_name@DOMAIN for KRB5) will be
113used
114 [1mCsec_client_establishContext, Csec_server_establishCon‐
116text[0m
117 Given an initialized context and an opened sock‐
118et, establish a
119 security context according to the chosen security
120mechanism.
121 [1mCsec_client_setSecurityOpts, Csec_server_setSecurity‐
123Opts[0m
124 Given an initialized context, but one that has not
125yet been used
126 to establish a security context these functions al‐
127low the selec‐
128 tion of various options. Currently supported are:
129 CSEC_OPT_DELEG_FLAG
131 Requests that delegated credentials from the
133client are
134 made available to the server. Either the client
135or server may
136 set this option and it will automaticaly limit the
137selection of
138 authentication method to one that supports del‐
139egation. (Cur‐
140 rently only GSI)
141 CSEC_OPT_NODELEG_FLAG
143 This directs that client/server to disallow
145delegation. If
146 the other side requests delegation the establish‐
147ing of a secu‐
148 rity context will fail.
149 If neither side sets any options the default behav‐
151iour is to not
152 delegate a credential.
153 [1mCsec_server_getClientId[0m
155 Allows a server to retrieve the authentication
156mechanism and
157 identification name (eg. principal or DN) from an
158established
159 context, ctx. If either of mech or name are NULL no
160pointer will
161 be returned. The strings that are returned are as‐
162sociated to the
163 context, ctx, so should only be used while the
164context ctx is
165 valid. If required they should be copied before the
166context is
167 reset or cleared.
168 [1mCsec_client_setAuthorizationId, Csec_server_getAutho‐
170rizationId[0m
171 On the client side an ’AuthorizationId’ may be
172set against an
173 initialized but not yet established context.
174The Authoriza‐
175 tionId, consisting of the pair mech and name, may
176be treated as
177 any arbitrary pair of strings up to CA_MAXCSECPRO‐
178TOLEN, CA_MAXC‐
179 SECNAMELEN in length. The strings will be made
180available to the
181 server. mech is supposed to represent the mecha‐
182nism type and
183 name should be an identifying string such as prin‐
184cipal or DN.
185 On the server side, the AuthorizationId may be
187retrieved after
188 the security context is established. If the client
189did not set
190 any id the server will receive an error when
191Csec_server_getAu‐
192 thorizationId() is called. Pointers to the mecha‐
193nism and the
194 name will be returned in mech and name. Either
195may be set to
196 NULL, in which case no pointer is returned. Up‐
197on successful
198 return the list of VOMS fqans and the VOMS voname
199available to
200 the server will also be reset to those which the
201client set man‐
202 ually, or will be emptied if the client did not
203set any. The
204 strings returned are associated with the context
205and should be
206 copied before the context is reset or cleared.
207 [1mCsec_server_getDelegatedCredential[0m
209 Allows a server to retrieve a copy of any dele‐
210gated credential
211 available from an established context, ctx. The
212credential is
213 returned in buf. The size of the data in the buf‐
214fer is returned
215 in size. The data should be treated as an opaque
216structure, the
217 meaning of which depends on the authentication
218scheme that was
219 used. The scheme name is returned in mech. Current‐
220ly only mech
221 ’GSI’ supports credential delegation and the
222client or server
223 must request delegation passing by setting the ap‐
224propriate flag
225 with Csec_client_setSecurityOpts() or Csec_serv‐
226er_setSecurity‐
227 Opts(). The GSI credential data is suitable for
228passing to
229 gss_import_cred(). mech and buf will point to
230data conatined
231 within the context, ctx, and should only be
232used while ctx
233 remains valid.
234 [1mCsec_mapToLocalUser[0m
236 This function determines whether an ID (mecha‐
237nism, name pair)
238 can be mapped to a local uid/gid and/or username.
239If the user‐
240 name is wanted a buffer should be passed in user‐
241name, the size
242 of which is indicated with username_size. If the
243uid/gid are
244 required uid and gid should be passed. Any of
245username, uid or
246 gid may be NULL in which case they are not re‐
247turned. If both uid
248 and gid are NULL and username is non‐NULL the
249mapped username is
250 not required to exist on the local system. ie. the
251function will
252 succeed as long as a mapping exists. If either of
253uid or gid are
254 non‐NULL the mapping and local username must ex‐
255ist, otherwise
256 Csec_mapToLocalUser() will return an error.
257 [1mCsec_clearContext[0m
259 Clears the context and deallocates the memory used.
260 [1mCsec_get_default_context[0m
262 Utility function that provides the applications
263with one default
264 per thread security context that can be used by
265the security
266 layer.
267[1mERROR HANDLING[0m
270 In case of errors in the Csec_pai layer, the functions
271return ‐1 (or
272 NULL for the functions returning strings), the serrno is
273set accord‐
274 ingly. It is possible to get the detailed error message
275by using the
276 [1mCsec_getErrorMessage() [22mor [1mCsec_getErrorMessage‐
277Summary() [22mfunctions. The
278 Csec_getErrorMessageSummary() function will return a
279summary message
280 that should need at most maxlen bytes of storage (includ‐
281ing the termi‐
282 nating null). The detail of the message may be cut in
283various ways to
284 reduce the length to fix in the specified length.
285[1mENVIRONMENT[0m
289 [1mCSEC_MECH[0m
290 environment variable or [1mCSEC MECH [22mentry in
291[1m/etc/shift.conf[0m
292 This environment variable contains the list of pro‐
293tocols to be
294 used for authentication. The variable has prece‐
295dence over the
296 LCG configuration file.
297 On the client side, this list is used to choose
298which security
299 mechanism should be used to address the server.
300On the server
301 side, this is is of list of mechanisms that should
302be accepted
303 by the server.
304 [1mCSEC_TRACE[0m
306 If defined switches the tracing on in the LCG se‐
307curity module.
308 Tracing information is sent to stderr, unless [1mC‐
309SEC_TRACEFILE is[0m
310 [1mdefined.[0m
311 [1mCSEC_TRACEFILE[0m
313 If defined, the LCG security tracing information
314is written to
315 afile which name is the value of this variable.
316[1mSECURITY MECHANISMS[0m
319 The currently supported methods for authentication are:
320 [1mKRB5 [22mKerberos 5 mechanism
322 [1mKRB4 [22mKerberos 4 mechanism
324 [1mGSI [22mGlobus Security Infrastructure
326 [1mID [22mUnsecure protocol, should be used for test‐
328ing only.
329[1mNOTE ON THREAD SAFETY[0m
332 If the Csec_api library was compiled thread safe (eg. was
333built defin‐
334 ing the _THREAD_SAFE macro, which is the standard way)
335then the library
336 should be thread safe. If the application using Csec_api
337also defines
338 _THREAD_SAFE, Csec attempts to use thread safe versions of
339any underly‐
340 ing security libraries that are used for the authentica‐
341tion service.
342 For instance, in the case of GSI the thread safe version
344of Globus may,
345 in areas other than security, sometimes create threads. If
346the applica‐
347 tion using Csec_api needs to link to the GSI libraries for
348its own use
349 then threading flavour should be consistent. There‐
350fore if the non
351 threaded Globus libraries are required then do not
352define the
353 _THREAD_SAFE macro.
354[1mAUTHOR[0m
357 [1mLCG Grid Deployment [22mTeam
358LCG $Date$
362CSEC_API(3)
363