Provided by: liblcgdm-dev_1.10.0-2_amd64 
NAME
Csec_api - Provides authentication in LCG services
SYNOPSIS
Header file:
#include <Csec_api.h>
On the client side:
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);
int Csec_client_setVOMS_data(Csec_context_t *ctx, const char *voname, char **fqan, int nbfqan);
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);
char *Csec_server_get_client_ca(Csec_context_t *ctx);
char *Csec_server_get_client_vo(Csec_context_t *ctx);
char **Csec_server_get_client_fqans(Csec_context_t *ctx, int *nbfqan);
Common functions:
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();
DESCRIPTION
Csec_api functions allow for the implimentation of strong authentication mechanisms in LCG servers and
clients. Csec_api is integrated with the LCG framework for errors.
Csec_client_initContext, Csec_server_initContext, Csec_server_reinitContext
allow to initialize the Csec_context_t structure. The service type parameter defines which type of
key will be used by the service. Its value can be:
CSEC_SERVICE_TYPE_HOST
A normal host key (e.g. host/machine_name@DOMAIN for KRB5) will be used
CSEC_SERVICE_TYPE_CENTRAL
A LCG Central host type key (e.g. castorcentral/machine_name@DOMAIN for KRB5) will be used
CSEC_SERVICE_TYPE_DISK
A LCG disk host type key (e.g. castordisk/machine_name@DOMAIN for KRB5) will be used
CSEC_SERVICE_TYPE_TAPE
A LCG tape host type key (e.g. castortape/machine_name@DOMAIN for KRB5) will be used
Csec_client_establishContext, Csec_server_establishContext
Given an initialized context and an opened socket, establish a security context according to the
chosen security mechanism.
Csec_client_setSecurityOpts, Csec_server_setSecurityOpts
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:
CSEC_OPT_DELEG_FLAG
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)
CSEC_OPT_NODELEG_FLAG
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.
Csec_server_getClientId
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.
Csec_client_setAuthorizationId, Csec_server_getAuthorizationId
On the client side an 'AuthorizationId' may be set against an initialized but not yet established
context. The AuthorizationId, consisting of the pair mech and name, may be treated as any
arbitrary pair of strings 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 or DN.
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.
Csec_server_getDelegatedCredential
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.
Csec_mapToLocalUser
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.
Csec_clearContext
Clears the context and deallocates the memory used.
Csec_get_default_context
Utility function that provides the applications with one default per thread security context that
can be used by the security layer.
ERROR HANDLING
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
Csec_getErrorMessage() or Csec_getErrorMessageSummary() 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
CSEC_MECH
environment variable or CSEC MECH entry in /etc/shift.conf
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.
CSEC_TRACE
If defined switches the tracing on in the LCG security module. Tracing information is sent to
stderr, unless CSEC_TRACEFILE is defined.
CSEC_TRACEFILE
If defined, the LCG security tracing information is written to afile which name is the value of
this variable.
SECURITY MECHANISMS
The currently supported methods for authentication are:
KRB5 Kerberos 5 mechanism
KRB4 Kerberos 4 mechanism
GSI Globus Security Infrastructure
ID 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.
AUTHOR
LCG Grid Deployment Team
LCG $Date: 2010-08-04 09:17:39 +0200 (Wed, 04 Aug 2010) $ CSEC_API(3)