Argus PEP Client Library: C API

Documentation

The Doxygen documentation for the Argus PEP client library describes the C API and have an example.

API: http://argus-authz.github.com/argus-pep-api-c/doc/modules.html

PEP XACML Object Model

../_images/Argus_PEP_ObjectModel.png

Basic Example

Basically, to use the Argus PEP client API, you will have to the following steps.

First, import the header with

#include "argus/pep.h"

Create and initialize the PEP client handle with

PEP * pep = pep_initialize()

Set the PEP Server URL with

pep_setoption(pep,PEP_OPTION_ENDPOINT_URL,"https://pepd.example.org:8154/authz")

If the PEP Server URL is protected by HTTPS with client authentication (the default), you must also configure the client certificate or proxy with

pep_setoption(pep,PEP_OPTION_ENDPOINT_CLIENT_CERT,"/tmp/x509up_u500")

The client private key or proxy key with

pep_setoption(pep,PEP_OPTION_ENDPOINT_CLIENT_KEY,"/tmp/x509up_u500")

And the server CA trust anchors path with

pep_setoption(pep,PEP_OPTION_ENDPOINT_SERVER_CAPATH,"/etc/grid-security/certificates")

Optionally, you can register some Policy Information Points (PIP) and Obligation Handlers (OH) of your own with

pep_addpip(...)

and

pep_addobligationhandler(...)

Create a XACML Request and add the required Subject, Resource, Action and Environment to it with

xacml_request_create()
xacml_request_addsubject(request,subject)

and so on. See the PEP XACML Object Model for the complete API.

Submit the request and get the response:

pep_authorize(pep,&request,&response)

Process the response (if not already done by your obligation handlers). Release the PEP client handle with

pep_destroy(pep)

Complex Example

A more detailed PEP client example is available http://argus-authz.github.com/argus-pep-api-c/doc/pep_client_example_8c-example.html

Multi-threaded Programming

The Argus PEP client library is thread-friendly, but you are not allowed to share a PEP handle among multiple threads.

Each thread have to create its own PEP handle:

/* Each thread creates its own PEP handle */
PEP * pep= pep_initialize();

Within a thread you can reuse the PEP handle (multiple pep_authorize(..) calls).

If your threads are object (OO programming, …), it is recommended you to create (pep_initialize) the PEP handle in the constructor, and release it (pep_destroy) in the destructor.

Processing Authorization Decision

The PEP client MUST abide by the authorization decision as described in here:

  • If the decision is Permit, then the PEP client SHALL permit access. If obligations accompany the decision, then the PEP client SHALL permit access only if it understands and it can and will enforce those obligations.
  • If the decision is Deny, then the PEP client SHALL deny access.
  • If the decision is NotApplicable, meaning that no policy apply, then the PEP client SHALL deny access.
  • If the decision is Inderterminate, then the PEP client SHALL deny access. The decision status message and status code should be used to produce an error message. Example:
...
xacml_result_t * result= xacml_response_getresult(response,i);
fprintf(stdout,"response.result[%d].decision= %s\n", i, decision_tostring(xacml_result_getdecision(result)));
fprintf(stdout,"response.result[%d].resourceid= %s\n", i, xacml_result_getresourceid(result));
if (xacml_result_getdecision(result) == XACML_DECISION_INDETERMINATE) {
   xacml_status_t * status= xacml_result_getstatus(result);
   fprintf(stdout,"response.result[%d].status.message= %s\n", i, xacml_status_getmessage(status));
   statuscode= xacml_status_getcode(status);
   fprintf(stdout,"response.result[%d].status.code.value= %s\n", i, xacml_statuscode_getvalue(statuscode));
}
...