Header file for the GSI gSOAP plugin. More...

#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 authentification and encryption on top of gSOAP. The globus GSI bundle is necessary for the plugin to compile and run.

Macro Definition Documentation

§ CGSI_OPT_ALLOW_ONLY_SELF

#define CGSI_OPT_ALLOW_ONLY_SELF 0x100

Allow client and server to only connect together when they have the same identity

§ CGSI_OPT_CLIENT

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

§ CGSI_OPT_DELEG_FLAG

#define CGSI_OPT_DELEG_FLAG 0x4

Initiate delegation over the HTTPG protocol.

§ CGSI_OPT_DISABLE_MAPPING

#define CGSI_OPT_DISABLE_MAPPING 0x40

Disable DN->userid mapping via gridmap-file.

§ CGSI_OPT_DISABLE_NAME_CHECK

#define CGSI_OPT_DISABLE_NAME_CHECK 0x10

Disable comparing the server's host name with its certificate's CN.

§ CGSI_OPT_DISABLE_VOMS_CHECK

#define CGSI_OPT_DISABLE_VOMS_CHECK 0x80

Disable connect time VOMS parsing for better error handling via an explicit call to retrieve_voms_creds()

§ CGSI_OPT_KEEP_ALIVE

#define CGSI_OPT_KEEP_ALIVE 0x20

Keep alive the HTTP connection.

§ CGSI_OPT_SERVER

#define CGSI_OPT_SERVER 0x2

The program acts as a server.

§ CGSI_OPT_SSL_COMPATIBLE

#define CGSI_OPT_SSL_COMPATIBLE 0x8

Using pure SSL protocol, for compatibility.

Function Documentation

§ cgsi_plugin()

int cgsi_plugin	(	struct soap *	soap,
		struct soap_plugin *	plugin,
		void *	arg
	)

Generic contructor 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

§ cgsi_plugin_clr_flags()

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.

§ cgsi_plugin_get_flags()

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

§ cgsi_plugin_set_credentials()

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.

§ cgsi_plugin_set_flags()

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.

§ clear_default_proxy_file()

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

§ client_cgsi_plugin()

int client_cgsi_plugin	(	struct soap *	soap,
		struct soap_plugin *	plugin,
		void *	arg
	)

Client contructor 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

§ export_delegated_credentials()

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

§ get_client_ca()

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

§ get_client_dn()

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

§ get_client_roles()

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

§ get_client_username()

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

§ get_client_voname()

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

§ get_delegated_credentials()

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

§ has_delegated_credentials()

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

§ is_context_established()

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

§ retrieve_userca_and_voms_creds()

int retrieve_userca_and_voms_creds ( struct soap * soap )

§ retrieve_voms_creds()

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.

§ server_cgsi_plugin()

int server_cgsi_plugin	(	struct soap *	soap,
		struct soap_plugin *	plugin,
		void *	arg
	)

Server contructor 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

§ set_default_proxy_file()

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

§ soap_cgsi_init()

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

Macros

Functions

Detailed Description

Macro Definition Documentation

§ CGSI_OPT_ALLOW_ONLY_SELF

§ CGSI_OPT_CLIENT

§ CGSI_OPT_DELEG_FLAG

§ CGSI_OPT_DISABLE_MAPPING

§ CGSI_OPT_DISABLE_NAME_CHECK

§ CGSI_OPT_DISABLE_VOMS_CHECK

§ CGSI_OPT_KEEP_ALIVE

§ CGSI_OPT_SERVER

§ CGSI_OPT_SSL_COMPATIBLE

Function Documentation

§ cgsi_plugin()

§ cgsi_plugin_clr_flags()

§ cgsi_plugin_get_flags()

§ cgsi_plugin_set_credentials()

§ cgsi_plugin_set_flags()

§ clear_default_proxy_file()

§ client_cgsi_plugin()

§ export_delegated_credentials()

§ get_client_ca()

§ get_client_dn()

§ get_client_roles()

§ get_client_username()

§ get_client_voname()

§ get_delegated_credentials()

§ has_delegated_credentials()

§ is_context_established()

§ retrieve_userca_and_voms_creds()

§ retrieve_voms_creds()

§ server_cgsi_plugin()

§ set_default_proxy_file()

§ soap_cgsi_init()