---
name: "cgsi_plugin.h"
section: "3"
platform: "linux"
package: "libcgsi-gsoap-doc"
version: "1.3.12-1"
release: "Debian 13 (Trixie)"
platforms: ["linux"]
url: "https://new.carta.tech/cgsi_plugin.h"
---

# cgsi\_plugin.h(3)

Header file for the GSI gSOAP plugin.

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