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)