Access control list for object storage. More...

Public Member Functions
	__construct ()
	Create a new ACL.
	addAccount ($perm, $account, $user=NULL)
	Grant ACL access to an account.
	addReferrer ($perm, $host= '*')
	Allow (or deny) a hostname or host pattern.
	allowListings ()
	Allow hosts with READ permissions to list a container's content.
	rules ()
	Get the rules array for this ACL.
	headers ()
	Generate HTTP headers for this ACL.
	isNonPublic ()
	Check if the ACL marks this private.
	isPrivate ()
	Alias of isNonPublic().
	isPublic ()
	Check whether this object allows public reading.
	__toString ()
	Implements the magic __toString() PHP function.

Static Public Member Functions
static	makePublic ()
	Allow READ access to the public.
static	makeNonPublic ()
	Disallow all public access.
static	makePrivate ()
	Alias of ACL::makeNonPublic().
static	newFromHeaders ($headers)
	Given a list of headers, get the ACL info.
static	parseRule ($perm, $rule)
	Parse a rule.

Public Attributes
const	READ = 1
	Read flag.
const	WRITE = 2
	Write flag.
const	READ_WRITE = 3
	Flag for READ and WRITE.
const	HEADER_READ = 'X-Container-Read'
	Header string for a read flag.
const	HEADER_WRITE = 'X-Container-Write'
	Header string for a write flag.

Protected Member Functions
	addRule ($perm, $rule)
	Add a rule to the appropriate stack of rules.
	ruleToString ($perm, $rule)
	Convert a rule to a string.

Protected Attributes
	$rules = array()

Detailed Description

Access control list for object storage.

EXPERIMENTAL: This is bassed on a feature of Swift that is likely to change. Most of this is based on undocmented features of the API discovered both in the Python docs and in discussions by various members of the OpenStack community.

Swift access control rules are broken into two permissions: READ and WRITE. Read permissions grant the user the ability to access the file (using verbs like GET and HEAD), while WRITE permissions allow any modification operation. WRITE does not imply READ.

In the current implementation of Swift, access can be assigned based on two different factors:

Accounts: Access can be granted to specific accounts, and within those accounts, can be further specified to specific users. See the addAccount() method for details on this.
Referrers: Access can be granted based on host names or host name patterns. For example, only subdomains of *.example.com may be granted READ access to a particular object.

ACLs are transmitted within the HTTP headers for an object or container. Two headers are used: X-Container-Read for READ rules, and X-Container-Write for WRITE rules. Each header may have a chain of rules.

Examples

For most casual cases, only the static constructor functions are used. For example, an ACL that does not grant any public access can be created with a single call:

<?php
$acl = ACL::makeNonPublic();
?>

Public read access is granted like this:

<?php
$acl = ACL::makePublic();
?>

(Note that in both cases, what is returned is an instance of an ACL with all of the necessary configuration done.)

Sometimes you will need more sophisticated access control rules. The following grants READ access to anyone coming from an example.com domain, but grants WRITE access only to the account admins:

<?php
$acl = new ACL();
// Grant READ to example.com users.
$acl->addReferrer(ACL::READ, '*.example.com');
// Allow only people in the account 'admins' access to
// write.
$acl->addAccount(ACL::WRITE, 'admins');
// Allow example.com users to view the container
// listings:
$acl->allowListings();
?>

Notes

The current implementation does not do any validation of rules. This will likely change in the future.
There is discussion in OpenStack about providing a different or drastically improved ACL mechanism. This class would then be replaced by a new mechanism.

For a detailed description of the rules for ACL creation, see http://swift.openstack.org/misc.html#acls

Definition at line 115 of file ACL.php.

Constructor & Destructor Documentation

__construct ( )

Create a new ACL.

This creates an empty ACL with no permissions granted. When no permissions are granted, the file is effectively private (nonPublic()).

Use add* methods to add permissions.

Definition at line 294 of file ACL.php.

Member Function Documentation

__toString ( )

Implements the magic __toString() PHP function.

This allows you to print $acl and get back a pretty string.

Return values

string

Returns: string The ACL represented as a string.

Definition at line 580 of file ACL.php.

References ACL\headers().

addAccount	(	$perm,
		$account,
		$user = `NULL`
	)

Grant ACL access to an account.

Optionally, a user may be given to further limit access.

This is used to restrict access to a particular account and, if so specified, a specific user on that account.

If just an account is given, any user on that account will be automatically granted access.

If an account and a user is given, only that user of the account is granted access.

If $user is an array, every user in the array will be granted access under the provided account. That is, for each user in the array, an entry of the form account:user will be generated in the final ACL.

At this time there does not seem to be a way to grant global write access to an object.

Parameters

int	$perm	ACL::READ, ACL::WRITE or ACL::READ_WRITE (which is the same as ACL::READ\|ACL::WRITE).
string	$account	The name of the account.
mixed	$user	The name of the user, or optionally an indexed array of user names.

Return values

HPCloud::Storage::ObjectStorage::ACL

Returns: $this for current object so the method can be used in chaining.

Definition at line 331 of file ACL.php.

References $account, and ACL\addRule().

addReferrer	(	$perm,
		$host = `'*'`
	)

Allow (or deny) a hostname or host pattern.

In current Swift implementations, only READ rules can have host patterns. WRITE permissions cannot be granted to hostnames.

Formats:

Allow any host: '*'
Allow exact host: 'www.example.com'
Allow hosts in domain: '.example.com'
Disallow exact host: '-www.example.com'
Disallow hosts in domain: '-.example.com'

Note that a simple minus sign ('-') is illegal, though it seems it should be "disallow all hosts."

Parameters

string	$perm	The permission being granted. One of ACL:READ, ACL::WRITE, or ACL::READ_WRITE.
string	$host	A host specification string as described above.

Return values

HPCloud::Storage::ObjectStorage::ACL

Returns: $this for current object so the method can be used in chaining.

Definition at line 368 of file ACL.php.

References ACL\addRule().

addRule	(	$perm,
		$rule
	)

protected

Add a rule to the appropriate stack of rules.

Parameters

int	$perm	One of the predefined permission constants.
array	$rule	A rule array.

Return values

HPCloud::Storage::ObjectStorage::ACL

Returns: $this for current object so the method can be used in chaining.

Definition at line 386 of file ACL.php.

References ACL\rules().

Referenced by ACL\addAccount(), and ACL\addReferrer().

allowListings ( )

Allow hosts with READ permissions to list a container's content.

By default, granting READ permission on a container does not grant permission to list the contents of a container. Setting the ACL::allowListings() permission will allow matching hosts to also list the contents of a container.

In the current Swift implementation, there is no mechanism for allowing some hosts to get listings, while denying others.

Return values

HPCloud::Storage::ObjectStorage::ACL

Returns: $this for current object so the method can be used in chaining.

Definition at line 409 of file ACL.php.

References ACL\rules().

headers ( )

Generate HTTP headers for this ACL.

If this is called on an empty object, an empty set of headers is returned.

Definition at line 436 of file ACL.php.

References ACL\rules(), and ACL\ruleToString().

Referenced by ACL\__toString().

isNonPublic ( )

Check if the ACL marks this private.

This returns TRUE only if this ACL does not grant any permissions at all.

Return values

boolean

Returns: boolean TRUE if this is private (non-public), FALSE if any permissions are granted via this ACL.

Definition at line 532 of file ACL.php.

References ACL\rules().

Referenced by ACL\isPrivate().

isPrivate ( )

Alias of isNonPublic().

Definition at line 539 of file ACL.php.

References ACL\isNonPublic().

isPublic ( )

Check whether this object allows public reading.

This will return TRUE the ACL allows (a) any host to access the item, and (b) it allows container listings.

This checks whether the object allows public reading, not whether it is ONLY allowing public reads.

See ACL::makePublic().

Definition at line 554 of file ACL.php.

References ACL\rules().

static makeNonPublic ( )

static

Disallow all public access.

Non-public is the same as private. Private, however, is a reserved word in PHP.

This does not grant any permissions. OpenStack interprets an object with no permissions as a private object.

Return values

HPCloud::Storage::ObjectStorage::ACL

Returns: an ACL object with the appopriate permissions set.

Definition at line 179 of file ACL.php.

static makePrivate ( )

static

Alias of ACL::makeNonPublic().

Definition at line 187 of file ACL.php.

static makePublic ( )

static

Allow READ access to the public.

This grants the following:

READ to any host, with container listings.

Return values

HPCloud::Storage::ObjectStorage::ACL

Returns: an ACL object with the appopriate permissions set.

Definition at line 158 of file ACL.php.

static newFromHeaders ( $headers )

static

Given a list of headers, get the ACL info.

This is a utility for processing headers and discovering any ACLs embedded inside the headers.

Parameters

array $headers An associative array of headers.

Return values

HPCloud::Storage::ObjectStorage::ACL

Returns: A new ACL.

Definition at line 203 of file ACL.php.

References ACL\$rules.

Referenced by Container\loadExtraData(), and Container\newFromResponse().

static parseRule	(	$perm,
		$rule
	)

static

Parse a rule.

This attempts to parse an ACL rule. It is not particularly fault-tolerant.

Parameters

int	$perm	The permission (ACL::READ, ACL::WRITE).
string	$rule	The string rule to parse.

Return values

array

Returns: array The rule as an array.

Definition at line 251 of file ACL.php.

rules ( )

Get the rules array for this ACL.

Return values

array

Returns: array An array of associative arrays of rules.

Definition at line 426 of file ACL.php.

Referenced by ACL\addRule(), ACL\allowListings(), ACL\headers(), ACL\isNonPublic(), and ACL\isPublic().

ruleToString	(	$perm,
		$rule
	)

protected

Convert a rule to a string.

Parameters

int	$perm	The permission for which to generate the rule.
array	$rule	A rule array.

Definition at line 480 of file ACL.php.

Referenced by ACL\headers().

Member Data Documentation

$rules = array()

protected

Definition at line 145 of file ACL.php.

Referenced by ACL\newFromHeaders().

const HEADER_READ = 'X-Container-Read'

Header string for a read flag.

Definition at line 139 of file ACL.php.

const HEADER_WRITE = 'X-Container-Write'

Header string for a write flag.

Definition at line 143 of file ACL.php.

const READ = 1

Read flag.

This is for an ACL of the READ type.

Definition at line 122 of file ACL.php.

const READ_WRITE = 3

Flag for READ and WRITE.

This is equivalent to ACL::READ | ACL::WRITE

Definition at line 134 of file ACL.php.

const WRITE = 2

Write flag.

This is for an ACL of the WRITE type.

Definition at line 128 of file ACL.php.

The documentation for this class was generated from the following file:

src/HPCloud/Storage/ObjectStorage/ACL.php

Public Member Functions

Static Public Member Functions

Public Attributes

Protected Member Functions

Protected Attributes

Detailed Description

Constructor & Destructor Documentation

Member Function Documentation

Member Data Documentation