PEP client API

PEP client used to send authorization request to the PEP daemon and receive authorization response with decision back. More...

Typedefs
typedef struct pep_handle	PEP
	PEP client handle.
typedef enum pep_option	pep_option_t
	PEP client configuration options.
Enumerations
enum	pep_option { PEP_OPTION_LOG_LEVEL, PEP_OPTION_LOG_STDERR, PEP_OPTION_LOG_HANDLER, PEP_OPTION_ENDPOINT_URL, PEP_OPTION_ENDPOINT_SSL_VALIDATION, PEP_OPTION_ENDPOINT_SERVER_CERT, PEP_OPTION_ENDPOINT_SERVER_CAPATH, PEP_OPTION_ENDPOINT_CLIENT_CERT, PEP_OPTION_ENDPOINT_CLIENT_KEY, PEP_OPTION_ENDPOINT_CLIENT_KEYPASSWORD, PEP_OPTION_ENDPOINT_TIMEOUT, PEP_OPTION_ENABLE_PIPS, PEP_OPTION_ENABLE_OBLIGATIONHANDLERS, PEP_OPTION_ENDPOINT_SSL_CIPHER_LIST }
	PEP client configuration options. More...
Functions
pep_error_t	pep_addobligationhandler (PEP pep, const pep_obligationhandler_t oh)
	Adds an Obligation Handler post-processor to the PEP client.
pep_error_t	pep_addpip (PEP pep, const pep_pip_t pip)
	Adds a PIP request pre-processor to the PEP client.
pep_error_t	pep_authorize (PEP pep, xacml_request_t request, xacml_response_t *response)
	Sends the XACML request to the PEP daemon and returns the XACML response.
void	pep_destroy (PEP *pep)
	Cleanups and destroys the PEP client.
int	pep_getid (PEP *pep)
	Returns the id of the PEP handle.
void	pep_global_cleanup (void)
	NOT THREAD SAFE.
pep_error_t	pep_global_init (void)
	NOT THREAD SAFE.
PEP *	pep_initialize (void)
	Creates and initializes a new PEP client handle.
pep_error_t	pep_setoption (PEP *pep, pep_option_t option,...)
	Sets a PEP client configuration option.
const char *	pep_version (void)
	Returns a human readable string with the version number of the PEP client API and some of its important components (like libcurl version).

Detailed Description

PEP client used to send authorization request to the PEP daemon and receive authorization response with decision back.

Typedef Documentation

typedef struct pep_handle PEP

PEP client handle.

Examples:: pep_client_example.c.

typedef enum pep_option pep_option_t

PEP client configuration options.

See also:: pep_setoption(pep,option, ...) to set a configuration option.

Enumeration Type Documentation

enum pep_option

PEP client configuration options.

See also:: pep_setoption(pep,option, ...) to set a configuration option.

Enumerator:

PEP_OPTION_LOG_LEVEL	Set log level (default PEP_LOGLEVEL_NONE).
PEP_OPTION_LOG_STDERR	Set log engine file descriptor: `stderr`, `stdout`, `NULL` (default `NULL`).
PEP_OPTION_LOG_HANDLER	Set the optional log handler callback function pointer (default `NULL`).
PEP_OPTION_ENDPOINT_URL	Set the mandatory PEP daemon endpoint URL.
PEP_OPTION_ENDPOINT_SSL_VALIDATION	Enable SSL validation: 0 or 1 (default 1).
PEP_OPTION_ENDPOINT_SERVER_CERT	PEP daemon server SSL certificate (PEM format): absolute filename.
PEP_OPTION_ENDPOINT_SERVER_CAPATH	Directory holding CA certificates (hashed filenames in PEM format) to verify the PEP daemon: absolute directory name.
PEP_OPTION_ENDPOINT_CLIENT_CERT	PEP client SSL certificate (PEM format) for client authN: absolute filename.
PEP_OPTION_ENDPOINT_CLIENT_KEY	PEP client SSL private key (PEM format) for client authN: absolute filename.
PEP_OPTION_ENDPOINT_CLIENT_KEYPASSWORD	PEP client SSL private key password for client authN: string.
PEP_OPTION_ENDPOINT_TIMEOUT	Timeout for the connection to endpoint URL in second (default 30s).
PEP_OPTION_ENABLE_PIPS	Enable PIPs pre-processing: 0 or 1 (default 1).
PEP_OPTION_ENABLE_OBLIGATIONHANDLERS	Enable OHs post-processing: 0 or 1 (default 1).
PEP_OPTION_ENDPOINT_SSL_CIPHER_LIST	PEP client list of ciphers to use for the SSL connection: string.

Function Documentation

pep_error_t pep_addobligationhandler	(	PEP *	pep,
		const pep_obligationhandler_t *	oh
	)

Adds an Obligation Handler post-processor to the PEP client.

The OH init() function is be called in this method.

See Obligation Handler (OH) and PIP and Obligation Handler Profile Adapters for more info.

Parameters:

	pep	pointer to the handle of the PEP client.
	oh	pointer to the pep_obligationhandler_t to add.

Returns:: pep_error_t PEP_OK on success or an error code.

pep_error_t pep_addpip	(	PEP *	pep,
		const pep_pip_t *	pip
	)

Adds a PIP request pre-processor to the PEP client.

The PIP init() function is called in this method.

See Policy Information Point (PIP) and PIP and Obligation Handler Profile Adapters for more info.

Parameters:

	pep	pointer to the handle of the PEP client.
	pip	pointer to the pep_pip_t to add.

Returns:: pep_error_t PEP_OK on success or an error code.

pep_error_t pep_authorize	(	PEP *	pep,
		xacml_request_t **	request,
		xacml_response_t **	response
	)

Sends the XACML request to the PEP daemon and returns the XACML response.

If some PIPs are present, they will be applied to the XACML request before submitting it to the PEPd. If some ObligationHandlers are present, they will be applied to the XACML response after the response is received from the PEPd.

After the call, the request parameter is the effective XACML request, as processed by the PEPd.

Parameters:

	pep	pointer to the handle of the PEP client.
	request	address of the pointer to the xacml_request_t to send.
	response	address of pointer to the xacml_response_t received.

Returns:: pep_error_t PEP_OK on success or an error code.

Examples:: pep_client_example.c.

void pep_destroy ( PEP * pep )

Cleanups and destroys the PEP client.

Any uses of the handle after this function has been called are illegal.

Parameters:

pep

pointer to the handle of the PEP client.

Returns:: none

Examples:: pep_client_example.c.

int pep_getid ( PEP * pep )

Returns the id of the PEP handle.

Parameters:

pep

pointer to the handle of the PEP client.

Returns:: the id >= 0 or a negative id on error.

void pep_global_cleanup ( void )

NOT THREAD SAFE.

You must not call it when any other thread in the program (i.e. a thread sharing the same memory) is running. This doesn't just mean no other thread that is using libcurl or the PEP client library.

Because this function wraps the libcurl curl_global_cleanup(), it calls functions of other libraries that are similarly thread unsafe, it could conflict with any other thread that uses these other libraries.

See the libcurl(3) man page for details of how to use these global functions.

pep_error_t pep_global_init ( void )

NOT THREAD SAFE.

You must not call it when any other thread in the program (i.e. a thread sharing the same memory) is running. This doesn't just mean no other thread that is using libcurl or the PEP client library.

Because this function wraps the libcurl curl_global_init(), it calls functions of other libraries that are similarly thread unsafe, it could conflict with any other thread that uses these other libraries.

See the libcurl(3) man page for details of how to use these global functions.

Returns:: pep_error_t PEP_OK on success or an error code.

PEP* pep_initialize ( void )

Creates and initializes a new PEP client handle.

This function must be the first function to call, and it returns a PEP client handle that you must use as input to other PEP client functions.

Returns:: the PEP client handle or null on error.

Examples:: pep_client_example.c.

pep_error_t pep_setoption	(	PEP *	pep,
		pep_option_t	option,
			...
	)

Sets a PEP client configuration option.

Parameters:

	pep	pointer to the handle of the PEP client.
	option	the PEP client option to set.
	...	argument(s) for the PEP client option.

Returns:: pep_error_t PEP_OK on success or an error code.

See also:: pep_option for available options.

Option PEP_OPTION_ENDPOINT_URL const char * argument:

   // set the PEP daemon endpoint URL
   pep_setoption(pep,PEP_OPTION_ENDPOINT_URL, (const char *)"https://pepd.switch.ch:8154/authz");

Option PEP_OPTION_ENDPOINT_SERVER_CAPATH const char * argument:

   // set the PEP daemon server CA directory for SSL/TLS validation
   pep_setoption(pep,PEP_OPTION_ENDPOINT_SERVER_CAPATH, (const char *)"/etc/grid-security/certificates");

Option PEP_OPTION_ENDPOINT_CLIENT_CERT const char * argument:

   // set the PEP client certificate for SSL/TLS client authentication
   pep_setoption(pep,PEP_OPTION_ENDPOINT_CLIENT_CERT, (const char *)"/tmp/x509up_u5000");

Option PEP_OPTION_ENDPOINT_CLIENT_KEY const char * argument:

   // set the PEP client private key for SSL/TLS client authentication
   pep_setoption(pep,PEP_OPTION_ENDPOINT_CLIENT_KEY, (const char *)"/tmp/x509up_u5000");

Option PEP_OPTION_LOG_LEVEL int argument:

   // set logging level to WARN (only ERROR + WARN messages shown)
   pep_setoption(pep,PEP_OPTION_LOG_LEVEL, (int)PEP_LOGLEVEL_WARN);

Option PEP_OPTION_LOG_STDERR FILE * argument:

   // set logging output to stderr
   pep_setoption(pep,PEP_OPTION_LOG_STDERR, (FILE *)stdout);

Option PEP_OPTION_LOG_HANDLER pep_log_handler_callback * argument:

   // override default logging handler with own logging callback function
   pep_setoption(pep,PEP_OPTION_LOG_HANDLER, (pep_log_handler_callback *)my_logging_callback);

Option PEP_OPTION_ENABLE_PIPS int (FALSE or TRUE) argument:

   // disable PIPs processing
   pep_setoption(pep,PEP_OPTION_ENABLE_PIPS, (int)0);

Option PEP_OPTION_ENABLE_OBLIGATIONHANDLERS int (FALSE or TRUE) argument:

   // already enabled by default, only for example purpose
   pep_setoption(pep,PEP_OPTION_ENABLE_OBLIGATIONHANDLERS, (int)1);

Examples:: pep_client_example.c.

const char* pep_version ( void )

Returns a human readable string with the version number of the PEP client API and some of its important components (like libcurl version).

Returns:: a null terminated string. e.g. "argus-pep-api-c/2.0.0 (libcurl/7.21.7 ...)"

Examples:: pep_client_example.c.

PEP client API

Typedefs

Enumerations

Functions

Detailed Description

Typedef Documentation

Enumeration Type Documentation

Function Documentation