int Csec_client_initContext(Csec_context_t *ctx,int service_type,Csec_protocol *protocols); int Csec_client_establishContext(Csec_context_t *ctx,int socket); int Csec_client_setSecurityOpts(Csec_context_t *ctx,int opt); int Csec_client_setAuthorizationId(Csec_context_t *ctx,const char *mech,const char *name);
On the server side:
int Csec_server_initContext(Csec_context_t *ctx,int service_type,Csec_protocol *protocols); int Csec_server_reinitContext (Csec_context_t *ctx,int service_type,Csec_protocol *protocols); int Csec_server_establishContext (Csec_context_t *ctx,int socket); int Csec_server_getClientId(Csec_context_t *ctx,char **mech,char **name); int Csec_server_getAuthorizationId(Csec_context_t *ctx,char **mech,char **name); int Csec_server_getDelegatedCredentials(Csec_context_t *ctx,char **mech, void ** buf, size_t *size); int Csec_server_setSecurityOpts(Csec_context_t *ctx,int opt);
int Csec_clearContext(Csec_context_t *ctx); int Csec_getErrorMessage(); int Csec_getErrorMessageSummary(size_t maxlen); int Csec_mapToLocalUser(const char *mech,const char *name,char *username,size_t username_size,uid_t *uid,gid_t *gid); Csec_context_t * Csec_get_default_context();
functions allow for the implimentation of strong authentication mechanisms in LCG servers and clients. Csec_api is integrated with the LCG
framework for errors.
Given an initialized context, but one that has not yet been used to establish a security context
these functions allow the selection of various options. Currently supported are:
Requests that delegated credentials from the client are made available to the server. Either the client or server may set this option and it will automaticaly limit the selection of authentication method to one that supports delegation. (Currently only GSI)
This directs that client/server to disallow delegation. If the other side requests delegation the establishing of a security context will fail.
If neither side sets any options the default behaviour is to not delegate a credential.
Allows a server to retrieve the authentication mechanism and identification name
(eg. principal or DN) from an established context, ctx. If either of mech or name
are NULL no pointer will be returned. The strings that are returned are associated
to the context, ctx, so should only be used while the context ctx is valid. If
required they should be copied before the context is reset or cleared.
On the client side an 'AuthorizationId' may be set against an initialized but
not yet establshed context. The AuthorizationId, consisting on the pair mech and name,
may be treated as any arbitrary pair of string up to CA_MAXCSECPROTOLEN, CA_MAXCSECNAMELEN
in length. The strings will be made available to the server. mech is supposed to
represent the mechanism type and name should be an identifying string such as principal
On the server side, the AuthorizationId may be retrieved after the security
context is established. If the client did not set any id the server will
receive an error when Csec_server_getAuthorizationId() is called. Pointers
to the mechanism and the name will be returned in mech and name. Either may
be set to NULL, in which case no pointer is returned. Upon successful return
the list of VOMS fqans and the VOMS voname available to the server will also
be reset to those which the client set manually, or will be emptied if the
client did not set any. The strings returned are associated with the context
and should be copied before the context is reset or cleared.
Allows a server to retrieve a copy of any delegated credential available
from an established context, ctx. The credential is returned in buf. The size
of the data in the buffer is returned in size. The data should be treated as an opaque structure, the meaning of
which depends on the authentication scheme that was used. The scheme name
is returned in mech. Currently only mech 'GSI' supports credential
delegation and the client or server must request delegation passing by
setting the appropriate flag with Csec_client_setSecurityOpts() or
Csec_server_setSecurityOpts(). The GSI credential data is suitable for passing to
gss_import_cred(). mech and buf will point to data conatined within the context, ctx,
and should only be used while ctx remains valid.
This function determines whether an ID (mechanism, name pair) can be mapped to a local uid/gid and/or username. If the username
is wanted a buffer should be passed in username, the size of which is indicated with username_size. If the uid/gid are required
uid and gid should be passed. Any of username, uid or gid may be NULL in which case they are not returned. If both uid and gid
are NULL and username is non-NULL the mapped username is not required to exist on the local system. ie. the function will succeed
as long as a mapping exists. If either of uid or gid are non-NULL the mapping and local username must exist, otherwise
Csec_mapToLocalUser() will return an error.
Clears the context and deallocates the memory used.
Utility function that provides the applications with one default per thread security context that can be used by the security layer.
In case of errors in the Csec_pai layer, the functions return -1 (or NULL for the functions returning strings), the serrno is set accordingly. It is possible to get the detailed error message by using the
functions. The Csec_getErrorMessageSummary() function will return a summary message that should need at most maxlen bytes
of storage (including the terminating null). The detail of the message may be cut in various ways to reduce the length
to fix in the specified length.
environment variable or
This environment variable contains the list of protocols to be used for authentication. The variable has precedence over the
LCG configuration file.
On the client side, this list is used to choose which security mechanism should be used to address the server.
On the server side, this is is of list of mechanisms that should be accepted by the server.
If defined switches the tracing on in the LCG security module. Tracing information is sent to stderr, unless
CSEC_TRACEFILE is defined.
If defined, the LCG security tracing information is written to afile which name is the value of this variable.
The currently supported methods for authentication are:
Kerberos 5 mechanism
Kerberos 4 mechanism
Globus Security Infrastructure
Unsecure protocol, should be used for testing only.
NOTE ON THREAD SAFETY
If the Csec_api library was compiled thread safe (eg. was built defining the _THREAD_SAFE
macro, which is the standard way) then the library should be thread safe. If the
application using Csec_api also defines _THREAD_SAFE, Csec attempts to use thread safe
versions of any underlying security libraries that are used for the authentication service.
For instance, in the case of GSI the thread safe version of Globus may, in areas other
than security, sometimes create threads. If the application using Csec_api needs to link
to the GSI libraries for its own use then threading flavour should be consistent. Therefore
if the non threaded Globus libraries are required then do not define the _THREAD_SAFE macro.