paa.h File Reference

#include <stdlib.h>
#include "apr.h"
#include "apr_pools.h"
#include "paa-http-server-facade.h"
#include "paa-http-client.h"
#include "paa-config.h"
#include "paa-cache.h"
#include "paa-log.h"
#include "paa-util.h"

Go to the source code of this file.

Classes
struct	paa_header_item_struct
struct	paa_msg_body_item_struct

Macros
#define	APR_PAA_REQ_ALLOWED   (APR_PAA_MODULE_START + 0)
#define	APR_PAA_REQ_DENIED   (APR_PAA_MODULE_START + 1)
#define	APR_PAA_REQ_AGAIN   (APR_PAA_MODULE_START + 2)
#define	APR_PAA_CACHE_HIT   (APR_PAA_MODULE_START + 3)
#define	APR_PAA_CACHE_MISS   (APR_PAA_MODULE_START + 4)

Typedefs
typedef struct paa_header_iter_struct	paa_header_iter
typedef struct paa_header_item_struct	paa_header_item
typedef struct paa_msg_body_iter_struct	paa_msg_body_iter
typedef struct paa_msg_body_item_struct	paa_msg_body_item

Functions
const char *	paa_get_version ()
const char *	paa_get_paap_version ()
apr_status_t	paa_cache_lookup (apr_pool_t *request_pool, const paa_cache *cache, const paa_client_request *client_req, const paa_agent_response **agent_resp)
void	paa_agent_resp_get_status (const paa_agent_response *agent_resp, int *status, const char **reason)
apr_status_t	paa_agent_resp_headers_begin (const paa_agent_response *agent_resp, apr_pool_t *request_pool, paa_header_iter **iter)
apr_status_t	paa_headers_next (paa_header_iter *iter, paa_header_item *output)
apr_status_t	paa_agent_resp_body_begin (const paa_agent_response *agent_resp, apr_pool_t *request_pool, paa_msg_body_iter **iter)
apr_status_t	paa_msg_body_next (paa_msg_body_iter *iter, paa_msg_body_item *output)
apr_status_t	paa_configure_agent_request (apr_pool_t *request_pool, const paa_config *config, const paa_client_request *client_req, const paa_agent_response *agent_resp, const paa_http_request *request)
apr_status_t	paa_process_agent_response (apr_pool_t *request_pool, const paa_http_response *raw_response, const paa_cache *cache, const paa_client_request *client_req, const paa_agent_response *last_resp, const paa_agent_response **agent_resp)
int	paa_agent_response_req_allowed (const paa_agent_response *resp)
int	paa_agent_response_modifies_request (const paa_agent_response *resp)
apr_status_t	paa_client_request_modify (apr_pool_t *request_pool, const paa_client_request *req, const paa_agent_response *resp)
int	paa_agent_response_modifies_response (const paa_agent_response *resp)
apr_status_t	paa_client_response_modify (apr_pool_t *request_pool, const paa_client_response *client_resp, const paa_agent_response *agent_resp)
apr_status_t	paa_submit_agent_request (apr_pool_t *request_pool, const paa_http_client *http_client, const paa_config *config, const paa_cache *cache, const paa_client_request *client_req, const paa_client_response *client_resp, const paa_agent_response **agent_resp)

Detailed Description

Header for the PAA SDK

Macro Definition Documentation

#define APR_PAA_CACHE_HIT   (APR_PAA_MODULE_START + 3)

indicates that a cache hit occurred

#define APR_PAA_CACHE_MISS   (APR_PAA_MODULE_START + 4)

indicates that a cache miss occurred

#define APR_PAA_REQ_AGAIN   (APR_PAA_MODULE_START + 2)

indicates that a policy decision could not be made for the request

#define APR_PAA_REQ_ALLOWED   (APR_PAA_MODULE_START + 0)

indicates that a request is allowed

#define APR_PAA_REQ_DENIED   (APR_PAA_MODULE_START + 1)

indicates that a request is denied

Typedef Documentation

typedef struct paa_header_item_struct paa_header_item

An item returned by a paa_header_iter

typedef struct paa_header_iter_struct paa_header_iter

Opaque iterator for accessing the header fields from an HTTP message stored in memory

typedef struct paa_msg_body_item_struct paa_msg_body_item

An item returned by a paa_msg_body_iter

typedef struct paa_msg_body_iter_struct paa_msg_body_iter

Opaque iterator for accessing the data of a HTTP message body stored in memory

Function Documentation

apr_status_t paa_agent_resp_body_begin	(	const paa_agent_response *	agent_resp,
		apr_pool_t *	request_pool,
		paa_msg_body_iter **	iter
	)

Create an iterator for the cached agent response body

Parameters

agent_resp	the agent response
request_pool	the pool in which to allocate data
iter	the iterator populated on success

Returns

APR_SUCCESS on success

otherwise the iterator could not be created

void paa_agent_resp_get_status	(	const paa_agent_response *	agent_resp,
		int *	status,
		const char **	reason
	)

Retrieve the status and reason from the cached agent response

Parameters

agent_resp	the agent response
status	the status of the status line of the response
reason	the reason in the status line of the response

apr_status_t paa_agent_resp_headers_begin	(	const paa_agent_response *	agent_resp,
		apr_pool_t *	request_pool,
		paa_header_iter **	iter
	)

Create an iterator for the cached agent response headers. Each iterator element corresponds to a single HTTP header field.

Parameters

agent_resp	the agent response
request_pool	the pool in which to allocate data
iter	the iterator populated on success

Returns

APR_SUCCESS on success

otherwise error

int paa_agent_response_modifies_request

(

const paa_agent_response *

resp

)

Parameters

resp	the agent response

Returns

non-zero if the agent response contains directives to modify the request

int paa_agent_response_modifies_response

(

const paa_agent_response *

resp

)

Parameters

resp	the agent response

Returns

non-zero if the agent response contains directives to modify the response

int paa_agent_response_req_allowed

(

const paa_agent_response *

resp

)

Parameters

resp	the handle

Returns

non-zero if the response indicates the request is allowed

apr_status_t paa_cache_lookup	(	apr_pool_t *	request_pool,
		const paa_cache *	cache,
		const paa_client_request *	client_req,
		const paa_agent_response **	agent_resp
	)

Performs a lookup for an existing paa_agent_response, using the specified incoming client request

Parameters

request_pool	the pool in which to allocate request-scoped memory
cache	the cache handle
client_req	the client request handle
agent_resp	always populated. On cache hit, the agent response contains the policy decision for the specified request. On cache miss, the agent response should be passed to paa_configure_agent_request.

Returns

APR_PAA_CACHE_HIT when lookup produced a paa_agent_response

APR_PAA_CACHE_MISS when lookup did not find a paa_agent_response

apr_status_t paa_client_request_modify	(	apr_pool_t *	request_pool,
		const paa_client_request *	req,
		const paa_agent_response *	resp
	)

Modify the client request according to the content of the agent response

Parameters

request_pool	the allocation pool for the current request
req	the request
resp	the response

Returns

APR_SUCCESS on successful modification of the request

otherwise the request could not be modified and SDK consumers should deny the incoming request with a 5xx response.

apr_status_t paa_client_response_modify	(	apr_pool_t *	request_pool,
		const paa_client_response *	client_resp,
		const paa_agent_response *	agent_resp
	)

Modify the client response according to the content of the agent response. This function will only modify headers, it will not replace the client response if the agent response indicates that the client response should be the agent response.

Parameters

request_pool	the request pool
client_resp	the client response to modify
agent_resp	the agent response

Returns

APR_SUCCESS on successful modification of the response

otherwise the response could not be modified and SDK consumers should replace the response with a 5xx response.

apr_status_t paa_configure_agent_request	(	apr_pool_t *	request_pool,
		const paa_config *	config,
		const paa_client_request *	client_req,
		const paa_agent_response *	agent_resp,
		const paa_http_request *	request
	)

Configures a paa_http_request as an agent request to be sent to PingAccess to obtain a policy decision for the specified client request.

Parameters

request_pool	the pool in which to allocate request-scoped memory
config	the configuration handle
client_req	the client request handle
agent_resp	should be one of the following: the paa_agent_response from the preceding paa_cache_lookup, the paa_agent_response from a paa_process_agent_response call that returned APR_PAA_REQ_AGAIN, or NULL if the cache is not used and this is the first call to paa_configure_agent_request for a particular request.
request	the handle to the request to be configured

Returns

APR_SUCCESS on success

otherwise the request could not be configured and SDK consumers should deny the incoming request with an appropriate 5xx response.

const char* paa_get_paap_version

(

)

Returns

the version of the PingAccess Agent Protocol (PAAP) supported by the SDK

const char* paa_get_version

(

)

Returns

the version of the SDK

apr_status_t paa_headers_next	(	paa_header_iter *	iter,
		paa_header_item *	output
	)

Advances the iterator, returning the current item in output

Parameters

iter	the iterator
output	the current item, populated on success

Returns

APR_SUCCESS if the iterator points to an item

APR_EOF if the iterator is complete

apr_status_t paa_msg_body_next	(	paa_msg_body_iter *	iter,
		paa_msg_body_item *	output
	)

Advances the iterator, returning the current item in output

Parameters

iter	the iterator
output	the current item, populated on success

Returns

APR_SUCCESS if the iterator points to an item

APR_EOF if the iterator is complete

apr_status_t paa_process_agent_response	(	apr_pool_t *	request_pool,
		const paa_http_response *	raw_response,
		const paa_cache *	cache,
		const paa_client_request *	client_req,
		const paa_agent_response *	last_resp,
		const paa_agent_response **	agent_resp
	)

Processes an agent response. The returned result indicates how to proceed further.

Parameters

request_pool	the pool in which to allocate request-scoped memory
raw_response	the raw HTTP response handle
cache	the cache handle
client_req	the client request handle
last_resp	the last agent response if this is not the first time this function has been invoked for a particular request
agent_resp	populated on APR_PAA_REQ_ALLOWED, APR_PAA_REQ_AGAIN, and APR_PAA_REQ_DENIED.

Returns

APR_PAA_REQ_ALLOWED the request is allowed access to the application

APR_PAA_REQ_DENIED the request is not allowed access to the application. The raw_response from PingAccess should be returned to the client. This function will have removed any PingAccess Agent Protocol headers.

APR_PAA_REQ_AGAIN the request did not have enough information to make the policy decision. Send another request to PingAccess, configured with the context of the produced paa_agent_response.

otherwise a 5xx error should be returned to the client

apr_status_t paa_submit_agent_request	(	apr_pool_t *	request_pool,
		const paa_http_client *	http_client,
		const paa_config *	config,
		const paa_cache *	cache,
		const paa_client_request *	client_req,
		const paa_client_response *	client_resp,
		const paa_agent_response **	agent_resp
	)

Obtains an access control decision, as represented by the paa_agent_response, for the specified incoming client request.

This function can be used in place of paa_cache_lookup, paa_configure_agent_request and paa_process_agent_response when using the paa_http_client interface. It effectively encapsulates all the logic required to obtain a policy decision for a request. It also will take care of writing an agent response as the client response if instructed to do so by PingAccess.

Parameters

request_pool	the allocation pool for the current request
http_client	the HTTP client handle
config	the configuration handle
cache	the cache handle
client_req	the request handle
client_resp	the response handle used to modify the paa_client_response if the agent response represents a non-277 agent response
agent_resp	the agent response – populated on success

Returns

APR_SUCCESS the access control decision is available in the paa_agent_response

otherwise, a generic 5xx response should be returned to the client