Csec_api man page

CSEC_API(3) LCG Security Functions CSEC_API(3)

[1mNAME[0m
Csec_api - Provides authentication in LCG services

[1mSYNOPSIS[0m
Header file:

[1m#include <Csec_api.h>[0m

On the client side:

[1mint Csec_client_initContext(Csec_context_t *[4m[22mctx,[24m [1mint [4m[22mservice_type,[0m
[1mCsec_protocol *[4m[22mprotocols[24m[1m);[0m
[1mint Csec_client_establishContext(Csec_context_t *[4m[22mctx,[24m [1mint [4m[22msocket[24m[1m);[0m
[1mint Csec_client_setSecurityOpts(Csec_context_t *[4m[22mctx,[24m [1mint [4m[22mopt[24m[1m);[0m
[1mint Csec_client_setAuthorizationId(Csec_context_t *[4m[22mctx,[24m [1mconst char[0m
[1m*[4m[22mmech,[24m [1mconst char *[4m[22mname[24m[1m);[0m
[1mint Csec_client_setVOMS_data(Csec_context_t *[4m[22mctx,[24m [1mconst char *[4m[22mvoname,[0m
[1mchar **[4m[22mfqan,[24m [1mint [4m[22mnbfqan[24m[1m);[0m

On the server side:

[1mint Csec_server_initContext(Csec_context_t *[4m[22mctx,[24m [1mint [4m[22mservice_type[24m[1m,[0m
[1mCsec_protocol *[4m[22mprotocols[24m[1m);[0m
[1mint Csec_server_reinitContext (Csec_context_t *[4m[22mctx,[24m [1mint [4m[22mservice_type[24m[1m,[0m
[1mCsec_protocol *[4m[22mprotocols[24m[1m);[0m
[1mint Csec_server_establishContext (Csec_context_t *[4m[22mctx,[24m [1mint [4m[22msocket[24m[1m);[0m
[1mint Csec_server_getClientId(Csec_context_t *[4m[22mctx,[24m [1mchar **[4m[22mmech,[24m [1mchar[0m
[1m**[4m[22mname[24m[1m);[0m
[1mint Csec_server_getAuthorizationId(Csec_context_t *[4m[22mctx,[24m [1mchar **[4m[22mmech,[0m
[1mchar **[4m[22mname[24m[1m);[0m
[1mint Csec_server_getDelegatedCredentials(Csec_context_t *[4m[22mctx,[24m [1mchar[0m
[1m**[4m[22mmech,[24m [1mvoid ** [4m[22mbuf,[24m [1msize_t *[4m[22msize[24m[1m);[0m
[1mint Csec_server_setSecurityOpts(Csec_context_t *[4m[22mctx,[24m [1mint [4m[22mopt[24m[1m);[0m
[1mchar *Csec_server_get_client_ca(Csec_context_t *[4m[22mctx);[0m
[1mchar *Csec_server_get_client_vo(Csec_context_t *[4m[22mctx);[0m
[1mchar **Csec_server_get_client_fqans(Csec_context_t *[4m[22mctx,[24m [1mint *[4m[22mnbfqan);[0m

Common functions:

[1mint Csec_clearContext(Csec_context_t *[4m[22mctx[24m[1m);[0m
[1mint Csec_getErrorMessage();[0m
[1mint Csec_getErrorMessageSummary(size_t [4m[22mmaxlen[24m[1m);[0m
[1mint Csec_mapToLocalUser(const char *[4m[22mmech,[24m [1mconst char *[4m[22mname,[24m [1mchar *[4m[22muser-[0m
[4mname,[24m [1msize_t [4m[22musername_size,[24m [1muid_t *[4m[22muid,[24m [1mgid_t *[4m[22mgid[24m[1m);[0m
[1mCsec_context_t * Csec_get_default_context();[0m

[1mDESCRIPTION[0m
[1mCsec_api [22mfunctions allow for the implimentation of strong authentica-
tion mechanisms in LCG servers and clients. Csec_api is integrated with
the LCG framework for errors.

[1mCsec_client_initContext, Csec_server_initContext, Csec_server_reinit-[0m
[1mContext[0m
allow to initialize the [1mCsec_context_t [22mstructure. The service
type parameter defines which type of key will be used by the
service. Its value can be:

[1mCSEC_SERVICE_TYPE_HOST[0m
A normal host key (e.g. host/machine_name@DOMAIN for
KRB5) will be used

[1mCSEC_SERVICE_TYPE_CENTRAL[0m
A LCG Central host type key (e.g. castor-
central/machine_name@DOMAIN for KRB5) will be used

[1mCSEC_SERVICE_TYPE_DISK[0m
A LCG disk host type key (e.g. cas-
tordisk/machine_name@DOMAIN for KRB5) will be used

[1mCSEC_SERVICE_TYPE_TAPE[0m
A LCG tape host type key (e.g. castor-
tape/machine_name@DOMAIN for KRB5) will be used

[1mCsec_client_establishContext, Csec_server_establishContext[0m
Given an initialized context and an opened socket, establish a
security context according to the chosen security mechanism.

[1mCsec_client_setSecurityOpts, Csec_server_setSecurityOpts[0m
Given an initialized context, but one that has not yet been used
to establish a security context these functions allow the selec-
tion 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. (Cur-
rently only GSI)

CSEC_OPT_NODELEG_FLAG

This directs that client/server to disallow delegation. If
the other side requests delegation the establishing of a secu-
rity context will fail.

If neither side sets any options the default behaviour is to not
delegate a credential.

[1mCsec_server_getClientId[0m
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.

[1mCsec_client_setAuthorizationId, Csec_server_getAuthorizationId[0m
On the client side an 'AuthorizationId' may be set against an
initialized but not yet established context. The Authoriza-
tionId, consisting of the pair mech and name, may be treated as
any arbitrary pair of strings up to CA_MAXCSECPROTOLEN, CA_MAXC-
SECNAMELEN 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_getAu-
thorizationId() 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 man-
ually, 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.

[1mCsec_server_getDelegatedCredential[0m
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_setSecurity-
Opts(). 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.

[1mCsec_mapToLocalUser[0m
This function determines whether an ID (mechanism, name pair)
can be mapped to a local uid/gid and/or username. If the user-
name 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.

[1mCsec_clearContext[0m
Clears the context and deallocates the memory used.

[1mCsec_get_default_context[0m
Utility function that provides the applications with one default
per thread security context that can be used by the security
layer.

[1mERROR HANDLING[0m
In case of errors in the Csec_pai layer, the functions return -1 (or
NULL for the functions returning strings), the serrno is set accord-
ingly. It is possible to get the detailed error message by using the
[1mCsec_getErrorMessage() [22mor [1mCsec_getErrorMessageSummary() [22mfunctions. The
Csec_getErrorMessageSummary() function will return a summary message
that should need at most maxlen bytes of storage (including the termi-
nating null). The detail of the message may be cut in various ways to
reduce the length to fix in the specified length.

[1mENVIRONMENT[0m
[1mCSEC_MECH[0m
environment variable or [1mCSEC MECH [22mentry in [1m/etc/shift.conf[0m
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.

[1mCSEC_TRACE[0m
If defined switches the tracing on in the LCG security module.
Tracing information is sent to stderr, unless [1mCSEC_TRACEFILE is[0m
[1mdefined.[0m

[1mCSEC_TRACEFILE[0m
If defined, the LCG security tracing information is written to
afile which name is the value of this variable.

[1mSECURITY MECHANISMS[0m
The currently supported methods for authentication are:

[1mKRB5 [22mKerberos 5 mechanism

[1mKRB4 [22mKerberos 4 mechanism

[1mGSI [22mGlobus Security Infrastructure

[1mID [22mUnsecure protocol, should be used for testing only.

[1mNOTE ON THREAD SAFETY[0m
If the Csec_api library was compiled thread safe (eg. was built defin-
ing 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 underly-
ing 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 applica-
tion 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.

[1mAUTHOR[0m
[1mLCG Grid Deployment [22mTeam

LCG $Date: 2010-08-04 09:17:39 +0200 (Wed, 04 Aug 2010) $ CSEC_API(3)

Info