SYNOPSIS

Inside the Apache configuration file:

 <PAPI_...>
 . . .
 
 SPOCP_Server /tmp/myspocp
 SPOCP_Action access
 . . .

REQUIRES

A connection to a SPOCP server (see http://www.spocp.org/).

DESCRIPTION

This class permits a PAPI PoA take authorization decisions by querying a SPOCP server. SPOCP evaluates if a certain subject is authorized to perform a certain action on a certain resource, according to a set of rules. For more details on SPOCP, see http://www.spocp.org/.

Three configuration directives are related to SPOCP-based authorization:

SPOCP_Server serverSpec

Defines the location of the SPOCP server to be used. Two formats can be used to specify the server location: If serverSpec begins with the '/' character, an internal socket is assumed, and the SPOCP server will be contacted using it. Otherwise, a TCP connection is used, and the well-known format host:port is used to identify it.

SPOCP_Action actionName

Defines the name of the action to be used when querying the SPOCP server (by default, it takes the value accept). The PAPI PoA identifies the subject of the query by means of the attributes inside the assertion, and the resource by means of the service identifier defined for the PoA by means of the Service_ID directive.

SPOCP_Accept_If_Down [1|0]

If set to 1, a failure in connecting to the SPOCP server will be considered a positive response to any authorization query. If set to 0 (the default), a failure in connecting to the SPOCP server will cause the PoA to reject the solicited access.

METHODS

new PAPI::SPOCP($server)

Creates a new instance of a PAPI/SPOCP connection, initializes the internal data, and tries to connect to the server defined by its argument. Returns a reference to the newly created object, undef in case of failure.

Arguments:

$server: Definition of the server to be accessed. A definition beginning with the character '/' makes the object to initiate a internal socket connection. Otherwise, a TCP connection is attempted, assuming that the server connection is defined in the ``host:port'' format.

$spocp->connect

This method opens a connection to the SPOCP server. It is automatically called by new upon object instantiation. It can be called again on an object that has executed its close method in order to restart it.

$spocp->setTLS

This method initiates a TLS connection to the SPOCP server.

NOTE: TLS-based connections to the SPOCP server are not currently supported by PAPI PoAs.

$spocp->query($resource, $action, $subject)

This method performs a query on the SPOCP server. Queries made by PAPI PoAs use the service identification of the PoA (set by means of the Service_ID configuration directive) to name the resource, the string defined by the SPOCP_Action configuration directive to name the action, and a list of the user's attributes (derived from the assertion) as subject.

The method codes the SPOCP query using the following format:

 (papi (poa Service_ID) (action SPOCP_Action)
  (subject (Attr1 Attr1Value) . . . (AttrN AttrNValue)))

Rules at the SPOCP server must use a compatible structure.

Arguments:

$resource: Identifier for the resource in SPOCP (derived from the service identification of the PoA).

$action: Identifier for the action in SPOCP (derived from the value of the SPOCP_Action configuration directive).

$subject: Reference to an array containing a list of pairs attribute value (derived from the assertion).

$spocp->close

This methods performs a logout at the SPOCP server and shuts the socket it has been using down.

INTERNAL METHODS

$spocp->normalize($str)

This method returns a normalized version of a string, according to SPOCP native protocol specification.

Arguments:

$str: String to normalize. For example, the string

 "connect"

is normalized to:

 "7:connect"

$spocp->normalizeSubject($attrRef)

This methods returns a normalized SPOCP string representing the subject of a SPOCP query.

Arguments:

$attrRef: A reference to an array containing a list of pairs of attribute name and value. For example, the list:

 ("uid", "papiuser", "group", "users")

is normalized to:

 "(3:uid8:papiuser)(5:group5:users)"

SEE ALSO

PAPI Configuration

PAPI PoA for Apache