.TH "cgsi_plugin.h" 3 "Sat Dec 24 2022" "Version 1.3.11" "CGSI_gSOAP" \" -*- nroff -*-
.ad l
.nh
.SH NAME
cgsi_plugin.h \- Header file for the GSI gSOAP plugin\&.  

.SH SYNOPSIS
.br
.PP
\fC#include <stdsoap2\&.h>\fP
.br

.SS "Macros"

.in +1c
.ti -1c
.RI "#define \fBCGSI_OPT_CLIENT\fP   0x1"
.br
.ti -1c
.RI "#define \fBCGSI_OPT_SERVER\fP   0x2"
.br
.ti -1c
.RI "#define \fBCGSI_OPT_DELEG_FLAG\fP   0x4"
.br
.ti -1c
.RI "#define \fBCGSI_OPT_SSL_COMPATIBLE\fP   0x8"
.br
.ti -1c
.RI "#define \fBCGSI_OPT_DISABLE_NAME_CHECK\fP   0x10"
.br
.ti -1c
.RI "#define \fBCGSI_OPT_KEEP_ALIVE\fP   0x20"
.br
.ti -1c
.RI "#define \fBCGSI_OPT_DISABLE_MAPPING\fP   0x40"
.br
.ti -1c
.RI "#define \fBCGSI_OPT_DISABLE_VOMS_CHECK\fP   0x80"
.br
.ti -1c
.RI "#define \fBCGSI_OPT_ALLOW_ONLY_SELF\fP   0x100"
.br
.in -1c
.SS "Functions"

.in +1c
.ti -1c
.RI "int \fBsoap_cgsi_init\fP (struct soap *soap, int cgsi_options)"
.br
.ti -1c
.RI "int \fBcgsi_plugin\fP (struct soap *soap, struct soap_plugin *plugin, void *arg)"
.br
.ti -1c
.RI "int \fBclient_cgsi_plugin\fP (struct soap *soap, struct soap_plugin *plugin, void *arg)"
.br
.ti -1c
.RI "int \fBserver_cgsi_plugin\fP (struct soap *soap, struct soap_plugin *plugin, void *arg)"
.br
.ti -1c
.RI "int \fBis_context_established\fP (struct soap *soap)"
.br
.ti -1c
.RI "int \fBget_client_dn\fP (struct soap *soap, char *dn, size_t dnlen)"
.br
.ti -1c
.RI "int \fBget_client_username\fP (struct soap *soap, char *username, size_t dnlen)"
.br
.ti -1c
.RI "int \fBget_delegated_credentials\fP (struct soap *soap, void **buffer, size_t *length)"
.br
.ti -1c
.RI "int \fBexport_delegated_credentials\fP (struct soap *soap, char *filename)"
.br
.ti -1c
.RI "int \fBhas_delegated_credentials\fP (struct soap *soap)"
.br
.ti -1c
.RI "int \fBset_default_proxy_file\fP (struct soap *soap, char *filename)"
.br
.ti -1c
.RI "void \fBclear_default_proxy_file\fP (int unlink_file)"
.br
.ti -1c
.RI "int \fBretrieve_voms_creds\fP (struct soap *soap)"
.br
.ti -1c
.RI "int \fBretrieve_userca_and_voms_creds\fP (struct soap *soap)"
.br
.ti -1c
.RI "char * \fBget_client_ca\fP (struct soap *soap)"
.br
.ti -1c
.RI "char * \fBget_client_voname\fP (struct soap *soap)"
.br
.ti -1c
.RI "char ** \fBget_client_roles\fP (struct soap *soap, int *nbfqans)"
.br
.ti -1c
.RI "int \fBcgsi_plugin_set_flags\fP (struct soap *soap, int is_server, int flags)"
.br
.ti -1c
.RI "int \fBcgsi_plugin_clr_flags\fP (struct soap *soap, int is_server, int flags)"
.br
.ti -1c
.RI "int \fBcgsi_plugin_get_flags\fP (struct soap *soap, int is_server)"
.br
.ti -1c
.RI "int \fBcgsi_plugin_set_credentials\fP (struct soap *soap, int is_server, const char *x509_cert, const char *x509_key)"
.br
.in -1c
.SH "Detailed Description"
.PP 
Header file for the GSI gSOAP plugin\&. 

\fBcgsi_plugin\&.h\fP - Header file for the GSI gSOAP plugin
.PP
\fBAuthor\fP
.RS 4
Ben Couturier CERN, IT/ADC
.RE
.PP
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\&. 
.SH "Macro Definition Documentation"
.PP 
.SS "#define CGSI_OPT_ALLOW_ONLY_SELF   0x100"
Allow client and server to only connect together when they have the same identity 
.SS "#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\&. 
.SS "#define CGSI_OPT_DELEG_FLAG   0x4"
Initiate delegation over the HTTPG protocol\&. 
.SS "#define CGSI_OPT_DISABLE_MAPPING   0x40"
Disable DN->userid mapping via gridmap-file\&. 
.SS "#define CGSI_OPT_DISABLE_NAME_CHECK   0x10"
Disable comparing the server's host name with its certificate's CN\&. 
.SS "#define CGSI_OPT_DISABLE_VOMS_CHECK   0x80"
Disable connect time VOMS parsing for better error handling via an explicit call to \fBretrieve_voms_creds()\fP 
.SS "#define CGSI_OPT_KEEP_ALIVE   0x20"
Keep alive the HTTP connection\&. 
.SS "#define CGSI_OPT_SERVER   0x2"
The program acts as a server\&. 
.SS "#define CGSI_OPT_SSL_COMPATIBLE   0x8"
Using pure SSL protocol, for compatibility\&. 
.SH "Function Documentation"
.PP 
.SS "int cgsi_plugin (struct soap * soap, struct soap_plugin * plugin, void * arg)"
Generic contructor for the cgsi_plugin
.PP
\fBParameters\fP
.RS 4
\fIsoap\fP The soap structure for the request 
.br
\fIplugin\fP Pointer to the plugin data structure 
.br
\fIarg\fP The parameters for the plugin creation
.RE
.PP
\fBReturns\fP
.RS 4
0 if successful, -1 otherwise 
.RE
.PP

.SS "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\&.
.PP
\fBParameters\fP
.RS 4
\fIsoap\fP The soap structure from gSOAP
.br
\fIis_server\fP 0 if client, 1 if server
.br
\fIflags\fP Bitwise OR of the flags to be cleared\&.
.RE
.PP
\fBReturns\fP
.RS 4
0 on success, -1 on error\&. 
.RE
.PP

.SS "int cgsi_plugin_get_flags (struct soap * soap, int is_server)"
Discover the current set of flags that are in effect\&.
.PP
\fBParameters\fP
.RS 4
\fIsoap\fP The soap structure from gSOAP
.br
\fIis_server\fP 0 if client, 1 if server
.RE
.PP
\fBReturns\fP
.RS 4
the set of flags or -1 on error 
.RE
.PP

.SS "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
.PP
\fBParameters\fP
.RS 4
\fIsoap\fP The soap structure for the request 
.br
\fIis_server\fP 0 if client, 1 if server 
.br
\fIx509_cert\fP The certificate\&. If it is a proxy, you only need to specify this one 
.br
\fIx509_key\fP The key\&. Will be ignored if x509_cert is NULL!
.RE
.PP
\fBReturns\fP
.RS 4
0 on success, -1 on error\&. 
.RE
.PP

.SS "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\&.
.PP
\fBParameters\fP
.RS 4
\fIsoap\fP The soap structure from gSOAP
.br
\fIis_server\fP 0 if client, 1 if server
.br
\fIflags\fP Bitwise OR of the flags to be set\&.
.RE
.PP
\fBReturns\fP
.RS 4
0 on success, -1 on error\&. 
.RE
.PP

.SS "void clear_default_proxy_file (int unlink_file)"
Clears the env variable used by GSI to specify the proxy filename
.PP
\fBParameters\fP
.RS 4
\fIunlink_file\fP Set to 1 if you want to destroy the credential file as well 
.RE
.PP

.SS "int client_cgsi_plugin (struct soap * soap, struct soap_plugin * plugin, void * arg)"
Client contructor for the cgsi_plugin
.PP
\fBParameters\fP
.RS 4
\fIsoap\fP The soap structure for the request 
.br
\fIplugin\fP Pointer to the plugin data structure 
.br
\fIarg\fP The parameters for the plugin creation (CGSI_OPT_CLIENT assumed)
.RE
.PP
\fBReturns\fP
.RS 4
0 if successful, -1 otherwise 
.RE
.PP

.SS "int export_delegated_credentials (struct soap * soap, char * filename)"
Export the delegated credentials (if available) to a file
.PP
\fBParameters\fP
.RS 4
\fIsoap\fP The soap structure for the request 
.br
\fIfilename\fP Name of the file where the credentials are to be written
.RE
.PP
\fBReturns\fP
.RS 4
0 if successful, -1 otherwise 
.RE
.PP

.SS "char * get_client_ca (struct soap * soap)"
Returns the client CA
.PP
\fBParameters\fP
.RS 4
\fIsoap\fP The soap structure for the request
.RE
.PP
\fBReturns\fP
.RS 4
The client CA is allocated in the soap structure (DON'T free), NULL otherwise 
.RE
.PP

.SS "int get_client_dn (struct soap * soap, char * dn, size_t dnlen)"
Gets the Distinguished name (DN) of the client
.PP
\fBParameters\fP
.RS 4
\fIsoap\fP The soap structure for the request 
.br
\fIdn\fP Pointer to a buffer where the DN is to be written 
.br
\fIdnlen\fP The length of the buffer
.RE
.PP
\fBReturns\fP
.RS 4
0 if successful, -1 otherwise 
.RE
.PP

.SS "char ** get_client_roles (struct soap * soap, int * nbfqans)"
Returns the client VO roles if they were provided in the certificate
.PP
\fBParameters\fP
.RS 4
\fIsoap\fP The soap structure for the request
.br
\fInbfqans\fP The number of returned Fully Qualified Attribute Names
.RE
.PP
\fBReturns\fP
.RS 4
The client roles are malloced in the soap structure (DON'T free), NULL otherwise 
.RE
.PP

.SS "int get_client_username (struct soap * soap, char * username, size_t dnlen)"
Gets the username (DN) of the client
.PP
\fBParameters\fP
.RS 4
\fIsoap\fP The soap structure for the request 
.br
\fIusername\fP Pointer to a buffer where the username is to be written 
.br
\fIdnlen\fP The length of the buffer
.RE
.PP
\fBReturns\fP
.RS 4
0 if successful, -1 otherwise 
.RE
.PP

.SS "char * get_client_voname (struct soap * soap)"
Returns the client VO name if it was provided in the certificate
.PP
\fBParameters\fP
.RS 4
\fIsoap\fP The soap structure for the request
.RE
.PP
\fBReturns\fP
.RS 4
The client voname is malloced in the soap structure (DON'T free), NULL otherwise 
.RE
.PP

.SS "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\&.
.PP
\fBParameters\fP
.RS 4
\fIsoap\fP The soap structure that is the target of the request 
.br
\fIbuffer\fP Pointer to a void pointer which will be set to reference the credential token\&. 
.br
\fIlength\fP Pointer to a length that will be set to the size of the credential token
.RE
.PP
\fBReturns\fP
.RS 4
0 if successful, -1 otherwise 
.RE
.PP

.SS "int has_delegated_credentials (struct soap * soap)"
Checks whether the client delegated credentials to the server
.PP
\fBParameters\fP
.RS 4
\fIsoap\fP The soap structure for the request
.RE
.PP
\fBReturns\fP
.RS 4
1 if there are some delegated credentials, 0 otherwise 
.RE
.PP

.SS "int is_context_established (struct soap * soap)"
Checks whether the security context has been established properly
.PP
\fBParameters\fP
.RS 4
\fIsoap\fP The soap structure for the request
.RE
.PP
\fBReturns\fP
.RS 4
1 if context established, 0 otherwise 
.RE
.PP

.SS "int retrieve_userca_and_voms_creds (struct soap * soap)"

.SS "int retrieve_voms_creds (struct soap * soap)"
Parses the optional VOMS extension of the peer certificate\&. It has to be called before \fBget_client_voname()\fP and \fBget_client_roles()\fP!
.PP
\fBParameters\fP
.RS 4
\fIsoap\fP The soap structure for the request
.RE
.PP
\fBReturns\fP
.RS 4
0 if successful, -1 otherwise SOAP Fault structure contains the detailed description\&. 
.RE
.PP

.SS "int server_cgsi_plugin (struct soap * soap, struct soap_plugin * plugin, void * arg)"
Server contructor for the cgsi_plugin
.PP
\fBParameters\fP
.RS 4
\fIsoap\fP The soap structure for the request 
.br
\fIplugin\fP Pointer to the plugin data structure 
.br
\fIarg\fP The parameters for the plugin creation (CGSI_OPT_SERVER assumed)
.RE
.PP
\fBReturns\fP
.RS 4
0 if successful, -1 otherwise 
.RE
.PP

.SS "int set_default_proxy_file (struct soap * soap, char * filename)"
Sets the env variable for GSI to use the proxy in the specified filename
.PP
\fBParameters\fP
.RS 4
\fIsoap\fP The soap structure for the request 
.br
\fIfilename\fP Name of the file where credentials are stored
.RE
.PP
\fBReturns\fP
.RS 4
0 if successful, -1 otherwise 
.RE
.PP

.SS "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\&.
.PP
\fBParameters\fP
.RS 4
\fIsoap\fP The soap structure for the request 
.br
\fIcgsi_options\fP The parameters for the plugin creation (bitwise or of the different options)\&.
.RE
.PP
\fBReturns\fP
.RS 4
0 if successful, -1 otherwise 
.RE
.PP

.SH "Author"
.PP 
Generated automatically by Doxygen for CGSI_gSOAP from the source code\&.