Man Linux: Main Page and Category List


       Csec_api - Provides authentication in LCG services


       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);

       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
       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);

       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();


       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,
              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:

                     A  normal  host  key  (e.g.  host/machine_name@DOMAIN for
                     KRB5) will be used

                     A     LCG     Central     host     type     key     (e.g.
                     castorcentral/machine_name@DOMAIN for KRB5) will be used

                     A       LCG      disk     host     type     key     (e.g.
                     castordisk/machine_name@DOMAIN for KRB5) will be used

                     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:


                    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.

       Csec_client_setAuthorizationId, Csec_server_getAuthorizationId
              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 or

              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


       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 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.

              If defined switches the tracing on in the LCG  security  module.
              Tracing  information is sent to stderr, unless CSEC_TRACEFILE is

              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:

       KRB5   Kerberos 5 mechanism

       KRB4   Kerberos 4 mechanism

       GSI    Globus Security Infrastructure

       ID     Unsecure protocol, should be used for testing only.


       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

       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.


       LCG Grid Deployment Team