Provided by: liblcgdm-dev_1.8.7-3_amd64 bug

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