1CSEC_API(3) LCG Security Functions CSEC_API(3)
2
6 Csec_api - Provides authentication in LCG services
7
9 Header file:
10 #include <Csec_api.h>
12 On the client side:
14 int Csec_client_initContext(Csec_context_t *ctx, int service_type,
16 Csec_protocol *protocols);
17 int Csec_client_establishContext(Csec_context_t *ctx, int socket);
18 int Csec_client_setSecurityOpts(Csec_context_t *ctx, int opt);
19 int Csec_client_setAuthorizationId(Csec_context_t *ctx, const char
20 *mech, const char *name);
21 int Csec_client_setVOMS_data(Csec_context_t *ctx, const char *voname,
22 char **fqan, int nbfqan);
23 On the server side:
25 int Csec_server_initContext(Csec_context_t *ctx, int service_type,
27 Csec_protocol *protocols);
28 int Csec_server_reinitContext (Csec_context_t *ctx, int service_type,
29 Csec_protocol *protocols);
30 int Csec_server_establishContext (Csec_context_t *ctx, int socket);
31 int Csec_server_getClientId(Csec_context_t *ctx, char **mech, char
32 **name);
33 int Csec_server_getAuthorizationId(Csec_context_t *ctx, char **mech,
34 char **name);
35 int Csec_server_getDelegatedCredentials(Csec_context_t *ctx, char
36 **mech, void ** buf, size_t *size);
37 int Csec_server_setSecurityOpts(Csec_context_t *ctx, int opt);
38 char *Csec_server_get_client_ca(Csec_context_t *ctx);
39 char *Csec_server_get_client_vo(Csec_context_t *ctx);
40 char **Csec_server_get_client_fqans(Csec_context_t *ctx, int *nbfqan);
41 Common functions:
43 int Csec_clearContext(Csec_context_t *ctx);
45 int Csec_getErrorMessage();
46 int Csec_getErrorMessageSummary(size_t maxlen);
47 int Csec_mapToLocalUser(const char *mech, const char *name, char *user‐
48 name, size_t username_size, uid_t *uid, gid_t *gid);
49 Csec_context_t * Csec_get_default_context();
50
53 Csec_api functions allow for the implimentation of strong authentica‐
54 tion mechanisms in LCG servers and clients. Csec_api is integrated with
55 the LCG framework for errors.
56 Csec_client_initContext, Csec_server_initContext, Csec_server_reinit‐
59 Context
60 allow to initialize the Csec_context_t structure. The service
61 type parameter defines which type of key will be used by the
62 service. Its value can be:
63 CSEC_SERVICE_TYPE_HOST
65 A normal host key (e.g. host/machine_name@DOMAIN for
66 KRB5) will be used
67 CSEC_SERVICE_TYPE_CENTRAL
69 A LCG Central host type key (e.g. castor‐
70 central/machine_name@DOMAIN for KRB5) will be used
71 CSEC_SERVICE_TYPE_DISK
73 A LCG disk host type key (e.g. cas‐
74 tordisk/machine_name@DOMAIN for KRB5) will be used
75 CSEC_SERVICE_TYPE_TAPE
77 A LCG tape host type key (e.g. castor‐
78 tape/machine_name@DOMAIN for KRB5) will be used
79 Csec_client_establishContext, Csec_server_establishContext
81 Given an initialized context and an opened socket, establish a
82 security context according to the chosen security mechanism.
83 Csec_client_setSecurityOpts, Csec_server_setSecurityOpts
85 Given an initialized context, but one that has not yet been used
86 to establish a security context these functions allow the selec‐
87 tion of various options. Currently supported are:
88 CSEC_OPT_DELEG_FLAG
90 Requests that delegated credentials from the client are
92 made available to the server. Either the client or server may
93 set this option and it will automaticaly limit the selection of
94 authentication method to one that supports delegation. (Cur‐
95 rently only GSI)
96 CSEC_OPT_NODELEG_FLAG
98 This directs that client/server to disallow delegation. If
100 the other side requests delegation the establishing of a secu‐
101 rity context will fail.
102 If neither side sets any options the default behaviour is to not
104 delegate a credential.
105 Csec_server_getClientId
107 Allows a server to retrieve the authentication mechanism and
108 identification name (eg. principal or DN) from an established
109 context, ctx. If either of mech or name are NULL no pointer will
110 be returned. The strings that are returned are associated to the
111 context, ctx, so should only be used while the context ctx is
112 valid. If required they should be copied before the context is
113 reset or cleared.
114 Csec_client_setAuthorizationId, Csec_server_getAuthorizationId
116 On the client side an 'AuthorizationId' may be set against an
117 initialized but not yet established context. The Authoriza‐
118 tionId, consisting of the pair mech and name, may be treated as
119 any arbitrary pair of strings up to CA_MAXCSECPROTOLEN, CA_MAXC‐
120 SECNAMELEN in length. The strings will be made available to the
121 server. mech is supposed to represent the mechanism type and
122 name should be an identifying string such as principal or DN.
123 On the server side, the AuthorizationId may be retrieved after
125 the security context is established. If the client did not set
126 any id the server will receive an error when Csec_server_getAu‐
127 thorizationId() is called. Pointers to the mechanism and the
128 name will be returned in mech and name. Either may be set to
129 NULL, in which case no pointer is returned. Upon successful
130 return the list of VOMS fqans and the VOMS voname available to
131 the server will also be reset to those which the client set man‐
132 ually, or will be emptied if the client did not set any. The
133 strings returned are associated with the context and should be
134 copied before the context is reset or cleared.
135 Csec_server_getDelegatedCredential
137 Allows a server to retrieve a copy of any delegated credential
138 available from an established context, ctx. The credential is
139 returned in buf. The size of the data in the buffer is returned
140 in size. The data should be treated as an opaque structure, the
141 meaning of which depends on the authentication scheme that was
142 used. The scheme name is returned in mech. Currently only mech
143 'GSI' supports credential delegation and the client or server
144 must request delegation passing by setting the appropriate flag
145 with Csec_client_setSecurityOpts() or Csec_server_setSecurity‐
146 Opts(). The GSI credential data is suitable for passing to
147 gss_import_cred(). mech and buf will point to data conatined
148 within the context, ctx, and should only be used while ctx
149 remains valid.
150 Csec_mapToLocalUser
152 This function determines whether an ID (mechanism, name pair)
153 can be mapped to a local uid/gid and/or username. If the user‐
154 name is wanted a buffer should be passed in username, the size
155 of which is indicated with username_size. If the uid/gid are
156 required uid and gid should be passed. Any of username, uid or
157 gid may be NULL in which case they are not returned. If both uid
158 and gid are NULL and username is non-NULL the mapped username is
159 not required to exist on the local system. ie. the function will
160 succeed as long as a mapping exists. If either of uid or gid are
161 non-NULL the mapping and local username must exist, otherwise
162 Csec_mapToLocalUser() will return an error.
163 Csec_clearContext
165 Clears the context and deallocates the memory used.
166 Csec_get_default_context
168 Utility function that provides the applications with one default
169 per thread security context that can be used by the security
170 layer.
171
174 In case of errors in the Csec_pai layer, the functions return -1 (or
175 NULL for the functions returning strings), the serrno is set accord‐
176 ingly. It is possible to get the detailed error message by using the
177 Csec_getErrorMessage() or Csec_getErrorMessageSummary() functions. The
178 Csec_getErrorMessageSummary() function will return a summary message
179 that should need at most maxlen bytes of storage (including the termi‐
180 nating null). The detail of the message may be cut in various ways to
181 reduce the length to fix in the specified length.
182
186 CSEC_MECH
187 environment variable or CSEC MECH entry in /etc/shift.conf
188 This environment variable contains the list of protocols to be
189 used for authentication. The variable has precedence over the
190 LCG configuration file.
191 On the client side, this list is used to choose which security
192 mechanism should be used to address the server. On the server
193 side, this is is of list of mechanisms that should be accepted
194 by the server.
195 CSEC_TRACE
197 If defined switches the tracing on in the LCG security module.
198 Tracing information is sent to stderr, unless CSEC_TRACEFILE is
199 defined.
200 CSEC_TRACEFILE
202 If defined, the LCG security tracing information is written to
203 afile which name is the value of this variable.
204
207 The currently supported methods for authentication are:
208 KRB5 Kerberos 5 mechanism
210 KRB4 Kerberos 4 mechanism
212 GSI Globus Security Infrastructure
214 ID Unsecure protocol, should be used for testing only.
216
219 If the Csec_api library was compiled thread safe (eg. was built defin‐
220 ing the _THREAD_SAFE macro, which is the standard way) then the library
221 should be thread safe. If the application using Csec_api also defines
222 _THREAD_SAFE, Csec attempts to use thread safe versions of any underly‐
223 ing security libraries that are used for the authentication service.
224 For instance, in the case of GSI the thread safe version of Globus may,
226 in areas other than security, sometimes create threads. If the applica‐
227 tion using Csec_api needs to link to the GSI libraries for its own use
228 then threading flavour should be consistent. Therefore if the non
229 threaded Globus libraries are required then do not define the
230 _THREAD_SAFE macro.
231
234 LCG Grid Deployment Team
235LCG $Date: 2010-08-04 09:17:39 +0200 (Wed, 04 Aug 2010) $ CSEC_API(3)