NAME

       cgsi_plugin.h - Header file for the GSI gSOAP plugin.

SYNOPSIS

       #include <stdsoap2.h>

   Macros
       #define CGSI_OPT_CLIENT   0x1
       #define CGSI_OPT_SERVER   0x2
       #define CGSI_OPT_DELEG_FLAG   0x4
       #define CGSI_OPT_SSL_COMPATIBLE   0x8
       #define CGSI_OPT_DISABLE_NAME_CHECK   0x10
       #define CGSI_OPT_KEEP_ALIVE   0x20
       #define CGSI_OPT_DISABLE_MAPPING   0x40
       #define CGSI_OPT_DISABLE_VOMS_CHECK   0x80
       #define CGSI_OPT_ALLOW_ONLY_SELF   0x100

   Functions
       int soap_cgsi_init (struct soap *soap, int cgsi_options)
       int cgsi_plugin (struct soap *soap, struct soap_plugin *plugin, void *arg)
       int client_cgsi_plugin (struct soap *soap, struct soap_plugin *plugin, void *arg)
       int server_cgsi_plugin (struct soap *soap, struct soap_plugin *plugin, void *arg)
       int is_context_established (struct soap *soap)
       int get_client_dn (struct soap *soap, char *dn, size_t dnlen)
       int get_client_username (struct soap *soap, char *username, size_t dnlen)
       int get_delegated_credentials (struct soap *soap, void **buffer, size_t *length)
       int export_delegated_credentials (struct soap *soap, char *filename)
       int has_delegated_credentials (struct soap *soap)
       int set_default_proxy_file (struct soap *soap, char *filename)
       void clear_default_proxy_file (int unlink_file)
       int retrieve_voms_creds (struct soap *soap)
       int retrieve_userca_and_voms_creds (struct soap *soap)
       char * get_client_ca (struct soap *soap)
       char * get_client_voname (struct soap *soap)
       char ** get_client_roles (struct soap *soap, int *nbfqans)
       int cgsi_plugin_set_flags (struct soap *soap, int is_server, int flags)
       int cgsi_plugin_clr_flags (struct soap *soap, int is_server, int flags)
       int cgsi_plugin_get_flags (struct soap *soap, int is_server)
       int cgsi_plugin_set_credentials (struct soap *soap, int is_server, const char *x509_cert,
           const char *x509_key)

Detailed Description

       Header file for the GSI gSOAP plugin.

       cgsi_plugin.h - Header file for the GSI gSOAP plugin

       Author
           Ben Couturier CERN, IT/ADC

       This is a GSI plugin for gSOAP. It uses the globus GSI libraries to implement GSI secure
       authentication and encryption on top of gSOAP. The globus GSI bundle is necessary for the
       plugin to compile and run.

Macro Definition Documentation

   #define CGSI_OPT_ALLOW_ONLY_SELF   0x100
       Allow client and server to only connect together when they have the same identity

   #define CGSI_OPT_CLIENT   0x1
       Options that can be specified when initializing the cgsi_plugin (in the arg parameter):
       The program acts as a client.

   #define CGSI_OPT_DELEG_FLAG   0x4
       Initiate delegation over the HTTPG protocol.

   #define CGSI_OPT_DISABLE_MAPPING   0x40
       Disable DN->userid mapping via gridmap-file.

   #define CGSI_OPT_DISABLE_NAME_CHECK   0x10
       Disable comparing the server's host name with its certificate's CN.

   #define CGSI_OPT_DISABLE_VOMS_CHECK   0x80
       Disable connect time VOMS parsing for better error handling via an explicit call to
       retrieve_voms_creds()

   #define CGSI_OPT_KEEP_ALIVE   0x20
       Keep alive the HTTP connection.

   #define CGSI_OPT_SERVER   0x2
       The program acts as a server.

   #define CGSI_OPT_SSL_COMPATIBLE   0x8
       Using pure SSL protocol, for compatibility.

Function Documentation

   int cgsi_plugin (struct soap * soap, struct soap_plugin * plugin, void * arg)
       Generic constructor for the cgsi_plugin

       Parameters
           soap The soap structure for the request
           plugin Pointer to the plugin data structure
           arg The parameters for the plugin creation

       Returns
           0 if successful, -1 otherwise

   int cgsi_plugin_clr_flags (struct soap * soap, int is_server, int flags)
       Adjust CGSI-plugin's behaviour by clearing one or more flags. If a flag is not present in
       args then it is unaffected by this operation. If a flag is currently cleared then
       attempting to clear it will have no effect.

       Parameters
           soap The soap structure from gSOAP
           is_server 0 if client, 1 if server
           flags Bitwise OR of the flags to be cleared.

       Returns
           0 on success, -1 on error.

   int cgsi_plugin_get_flags (struct soap * soap, int is_server)
       Discover the current set of flags that are in effect.

       Parameters
           soap The soap structure from gSOAP
           is_server 0 if client, 1 if server

       Returns
           the set of flags or -1 on error

   int cgsi_plugin_set_credentials (struct soap * soap, int is_server, const char * x509_cert,
       const char * x509_key)
       Set credentials without using environment variables

       Parameters
           soap The soap structure for the request
           is_server 0 if client, 1 if server
           x509_cert The certificate. If it is a proxy, you only need to specify this one
           x509_key The key. Will be ignored if x509_cert is NULL!

       Returns
           0 on success, -1 on error.

   int cgsi_plugin_set_flags (struct soap * soap, int is_server, int flags)
       Adjust CGSI-plugin's behaviour by setting one or more flags. If a flag is not present in
       args then that flag is unaffected by this operation. If a flag is currently set then
       attempting to set it will have no effect.

       Parameters
           soap The soap structure from gSOAP
           is_server 0 if client, 1 if server
           flags Bitwise OR of the flags to be set.

       Returns
           0 on success, -1 on error.

   void clear_default_proxy_file (int unlink_file)
       Clears the env variable used by GSI to specify the proxy filename

       Parameters
           unlink_file Set to 1 if you want to destroy the credential file as well

   int client_cgsi_plugin (struct soap * soap, struct soap_plugin * plugin, void * arg)
       Client constructor for the cgsi_plugin

       Parameters
           soap The soap structure for the request
           plugin Pointer to the plugin data structure
           arg The parameters for the plugin creation (CGSI_OPT_CLIENT assumed)

       Returns
           0 if successful, -1 otherwise

   int export_delegated_credentials (struct soap * soap, char * filename)
       Export the delegated credentials (if available) to a file

       Parameters
           soap The soap structure for the request
           filename Name of the file where the credentials are to be written

       Returns
           0 if successful, -1 otherwise

   char * get_client_ca (struct soap * soap)
       Returns the client CA

       Parameters
           soap The soap structure for the request

       Returns
           The client CA is allocated in the soap structure (DON'T free), NULL otherwise

   int get_client_dn (struct soap * soap, char * dn, size_t dnlen)
       Gets the Distinguished name (DN) of the client

       Parameters
           soap The soap structure for the request
           dn Pointer to a buffer where the DN is to be written
           dnlen The length of the buffer

       Returns
           0 if successful, -1 otherwise

   char ** get_client_roles (struct soap * soap, int * nbfqans)
       Returns the client VO roles if they were provided in the certificate

       Parameters
           soap The soap structure for the request
           nbfqans The number of returned Fully Qualified Attribute Names

       Returns
           The client roles are malloced in the soap structure (DON'T free), NULL otherwise

   int get_client_username (struct soap * soap, char * username, size_t dnlen)
       Gets the username (DN) of the client

       Parameters
           soap The soap structure for the request
           username Pointer to a buffer where the username is to be written
           dnlen The length of the buffer

       Returns
           0 if successful, -1 otherwise

   char * get_client_voname (struct soap * soap)
       Returns the client VO name if it was provided in the certificate

       Parameters
           soap The soap structure for the request

       Returns
           The client voname is malloced in the soap structure (DON'T free), NULL otherwise

   int get_delegated_credentials (struct soap * soap, void ** buffer, size_t * length)
       Make the delegated credential available as a token in memory. The soap structure retains
       ownership of the memory. The user should not free the pointer returned by this function,
       nor use it after the soap object becomes invalid.

       Parameters
           soap The soap structure that is the target of the request
           buffer Pointer to a void pointer which will be set to reference the credential token.
           length Pointer to a length that will be set to the size of the credential token

       Returns
           0 if successful, -1 otherwise

   int has_delegated_credentials (struct soap * soap)
       Checks whether the client delegated credentials to the server

       Parameters
           soap The soap structure for the request

       Returns
           1 if there are some delegated credentials, 0 otherwise

   int is_context_established (struct soap * soap)
       Checks whether the security context has been established properly

       Parameters
           soap The soap structure for the request

       Returns
           1 if context established, 0 otherwise

   int retrieve_userca_and_voms_creds (struct soap * soap)
   int retrieve_voms_creds (struct soap * soap)
       Parses the optional VOMS extension of the peer certificate. It has to be called before
       get_client_voname() and get_client_roles()!

       Parameters
           soap The soap structure for the request

       Returns
           0 if successful, -1 otherwise SOAP Fault structure contains the detailed description.

   int server_cgsi_plugin (struct soap * soap, struct soap_plugin * plugin, void * arg)
       Server constructor for the cgsi_plugin

       Parameters
           soap The soap structure for the request
           plugin Pointer to the plugin data structure
           arg The parameters for the plugin creation (CGSI_OPT_SERVER assumed)

       Returns
           0 if successful, -1 otherwise

   int set_default_proxy_file (struct soap * soap, char * filename)
       Sets the env variable for GSI to use the proxy in the specified filename

       Parameters
           soap The soap structure for the request
           filename Name of the file where credentials are stored

       Returns
           0 if successful, -1 otherwise

   int soap_cgsi_init (struct soap * soap, int cgsi_options)
       Helper function to create the gsoap object and the cgsi_plugin at the same time. This
       function assumes that a client plugin is specified, to create a server plugin, use the
       CGSI_OPT_SERVER option.

       Parameters
           soap The soap structure for the request
           cgsi_options The parameters for the plugin creation (bitwise or of the different
           options).

       Returns
           0 if successful, -1 otherwise

Author

       Generated automatically by Doxygen for CGSI_gSOAP from the source code.