From 9bb0cc8f7dbecd9faa2c0b8c80ccee8088f2204e Mon Sep 17 00:00:00 2001 From: dbu Date: Wed, 7 Mar 2012 15:53:10 +0100 Subject: [PATCH 1/2] add PrincipalInterface and cleanup docs --- .../Security/AccessControlEntryInterface.php | 14 +++--- src/PHPCR/Security/AccessControlException.php | 2 +- .../Security/AccessControlListInterface.php | 38 +++++++------- .../AccessControlManagerInterface.php | 31 ++++++------ .../Security/AccessControlPolicyInterface.php | 8 +-- src/PHPCR/Security/PrincipalInterface.php | 50 +++++++++++++++++++ src/PHPCR/Security/PrivilegeInterface.php | 6 --- 7 files changed, 96 insertions(+), 53 deletions(-) create mode 100644 src/PHPCR/Security/PrincipalInterface.php diff --git a/src/PHPCR/Security/AccessControlEntryInterface.php b/src/PHPCR/Security/AccessControlEntryInterface.php index 3864bda0..547d024a 100644 --- a/src/PHPCR/Security/AccessControlEntryInterface.php +++ b/src/PHPCR/Security/AccessControlEntryInterface.php @@ -25,13 +25,13 @@ namespace PHPCR\Security; /** - * An AccessControlEntry represents the association of one or more Privilege - * objects with a specific Principal. + * An AccessControlEntryInterface represents the association of one or more + * PrivilegeInterface objects with a specific principal. * * The \Traversable interface enables the implementation to be addressed with - * foreach. AccessControlEntry has to implement either \RecursiveIterator - * or \Iterator. - * The iterator is equivalent to getPrivileges() returning a list of + * foreach. Concrete AccessControlEntry have to implement either + * \RecursiveIterator or \Iterator. + * The iterator is equivalent to getPrivileges(), returning a list of * PrivilegeInterface. The iterator keys have no significant meaning. * * @package phpcr @@ -43,9 +43,7 @@ interface AccessControlEntryInterface extends \Traversable /** * Returns the principal associated with this access control entry. * - * @return java.security.Principal a Principal. - * - * @todo find replacement for java.security.Principal + * @return PrincipalInterface * * @api */ diff --git a/src/PHPCR/Security/AccessControlException.php b/src/PHPCR/Security/AccessControlException.php index 6ae2445f..f933ae39 100644 --- a/src/PHPCR/Security/AccessControlException.php +++ b/src/PHPCR/Security/AccessControlException.php @@ -28,7 +28,7 @@ * Exception thrown by access control related methods of AccessControlManager. * * @package phpcr - * @subpackage interfaces + * @subpackage exceptions * @api */ class AccessControlException extends \PHPCR\RepositoryException diff --git a/src/PHPCR/Security/AccessControlListInterface.php b/src/PHPCR/Security/AccessControlListInterface.php index 25e33a17..92ae7246 100644 --- a/src/PHPCR/Security/AccessControlListInterface.php +++ b/src/PHPCR/Security/AccessControlListInterface.php @@ -25,18 +25,19 @@ namespace PHPCR\Security; /** - * The AccessControlList is an AccessControlPolicy representing a list of - * access control entries. + * The AccessControlListInterface is an AccessControlPolicyInterface + * representing a list of access control entries. * - * It is mutable before being set to the AccessControlManager and consequently - * defines methods to read and mutate the list i.e. to get, add or remove - * individual entries. + * It is mutable before being set to the AccessControlManagerInterface and + * consequently defines methods to read and mutate the list i.e. to get, add or + * remove individual AccessControlEntryInterface instances. * * The \Traversable interface enables the implementation to be addressed with * foreach. AccessControlList has to implement either \RecursiveIterator * or \Iterator. - * The iterator is equivalent to getAccessControlEntries() returning a - * list of AccessControlEntry. The iterator keys have no significant meaning. + * The iterator is equivalent to getAccessControlEntries() returning + * AccessControlEntryInterface instances. The iterator keys have no significant + * meaning. * * @package phpcr * @subpackage interfaces @@ -45,14 +46,12 @@ interface AccessControlListInterface extends \PHPCR\Security\AccessControlPolicyInterface, \Traversable { /** - * Gets every registered access control entry. - * * Returns all access control entries present with this policy. - * This method is only guaranteed to return an AccessControlEntry if that - * AccessControlEntry has been assigned through this API. * - * @return array Lis of all AccessControlEntry objects present with this - * policy. + * This method is only guaranteed to return an access control entry object + * if that access control entry object has been assigned through this API. + * + * @return array all AccessControlEntry objects present with this policy. * * @throws \PHPCR\RepositoryException - if an error occurs. * @@ -74,10 +73,11 @@ function getAccessControlEntries(); * Principal can never remove a Privilege added by a previous call. * * The modification does not take effect until this policy has been set to - * a node by calling AccessControlManagerInterface::setPolicy() and save is - * performed. + * a node by calling AccessControlManagerInterface::setPolicy() and + * Session::save is performed. * - * @param ? $principal - a Principal. TODO: define a type for this. JCR has javax.security.Principal + * @param PrincipalInterface $principal the entity that should have this + * privilege * @param array $privileges - an array of Privileges. * * @return boolean true if this policy was modify; false otherwise. @@ -87,18 +87,16 @@ function getAccessControlEntries(); * access control related exception occurs. * @throws \PHPCR\RepositoryException - if another error occurs. * - * @todo find replacement for java.security.Principal - * * @api */ - function addAccessControlEntry($principal, array $privileges); + function addAccessControlEntry(PrincipalInterface $principal, array $privileges); /** * Removes the specified access control entry object from this policy. * * Only exactly those entries obtained through getAccessControlEntries can * be removed. This method does not take effect until this policy has been - * re-set to a node by calling AccessControlManagerInterface::setPolicy() + * re-assigned to a node by calling AccessControlManagerInterface::setPolicy() * and save is performed. * * @param \PHPCR\Security\AccessControlEntryInterface $ace the access diff --git a/src/PHPCR/Security/AccessControlManagerInterface.php b/src/PHPCR/Security/AccessControlManagerInterface.php index 46e77ecb..90fc774c 100644 --- a/src/PHPCR/Security/AccessControlManagerInterface.php +++ b/src/PHPCR/Security/AccessControlManagerInterface.php @@ -86,7 +86,7 @@ function privilegeFromName($privilegeName); * the set returned by calling PrivilegeInterface::getAggregatePrivileges() * for that privilege. * - * The results reported by the this method reflect the net effect of the + * The results reported by this method reflect the net effect of the * currently applied control mechanisms. It does not reflect unsaved access * control policies or unsaved access control entries. Changes to access * control status caused by these mechanisms only take effect on @@ -195,7 +195,7 @@ function getEffectivePolicies($absPath); * @param string $absPath The absolute path to the node of which privileges * are requested. * - * @return Iterator over the applicable access control policies + * @return \Iterator over the applicable access control policies * implementing SeekableIterator and Countable. Values * are the AccessControlPolicyInterface instances. Keys have no * meaning. Returns an empty iterator if no policies are applicable. @@ -214,18 +214,20 @@ function getApplicablePolicies($absPath); /** * Binds the policy to the node at absPath. * - * The behavior of the call $acm->setPolicy($absPath, $policy) differs + * The behavior of AccessControlManagerInterface::setPolicy() differs * depending on how the policy object was originally acquired. * - * If policy was acquired through $acm->getApplicablePolicies($absPath) - * then that policy object is added to the node at absPath. + * If the policy was acquired through + * AccessControlManagerInterface::getApplicablePolicies() then that policy + * object is added to the node at absPath. * - * On the other hand, if $policy was acquired through - * $acm->getPolicies(absPath) then that policy object (usually after being - * altered) replaces its former version on the node at $absPath. + * On the other hand, if the policy was acquired through + * AccessControlManagerInterface::getPolicies() then that policy object + * (usually after being altered) replaces its former version on the node at + * $absPath. * - * This is session-write method and therefore the access control policy - * is only dispatched on save() and will only take effect upon + * This is a session-write method and therefore the access control policy + * is only dispatched on Session::save() and will only take effect upon * persist. * * @param string $absPath The absolute path to the node of which privileges @@ -255,12 +257,12 @@ function getApplicablePolicies($absPath); function setPolicy($absPath, \PHPCR\Security\AccessControlPolicyInterface $policy); /** - * Removes the specified AccessControlPolicy from the node at $absPath. + * Removes the specified AccessControlPolicyInterface from the node at $absPath. * - * An AccessControlPolicy can only be removed if it was bound to the + * An AccessControlPolicyInterface can only be removed if it was bound to the * specified node through this API before. The effect of the removal only * takes place upon SessionInterface::save(). Note, that an implementation - * default or any other effective AccessControlPolicy that has not been + * default or any other effective AccessControlPolicyInterface that has not been * applied to the node before may never be removed using this method. * * @param string $absPath The absolute path to the node of which privileges @@ -273,7 +275,8 @@ function setPolicy($absPath, \PHPCR\Security\AccessControlPolicyInterface $polic * @throws \PHPCR\PathNotFoundException if no node at absPath exists or the * session does not have sufficent access to retrieve a node at that * location. - * @throws \PHPCR\Security\AccessControlException if no policy exists. + * @throws \PHPCR\Security\AccessControlException if the policy to remove + * does not exist at the node at absPath. * @throws \PHPCR\AccessDeniedException if the session lacks * MODIFY_ACCESS_CONTROL privilege for the absPath node. * @throws \PHPCR\Lock\LockException if a lock applies at the node at diff --git a/src/PHPCR/Security/AccessControlPolicyInterface.php b/src/PHPCR/Security/AccessControlPolicyInterface.php index 95e84711..fbd79c77 100644 --- a/src/PHPCR/Security/AccessControlPolicyInterface.php +++ b/src/PHPCR/Security/AccessControlPolicyInterface.php @@ -25,11 +25,11 @@ namespace PHPCR\Security; /** - * The AccessControlPolicy is a marker interface for all kind of access control - * policies. This API defines two subinterfaces: + * The AccessControlPolicyInterface is a marker interface for all kind of + * access control policies. This API defines two subinterfaces: * - * - NamedAccessControlPolicy - * - AccessControlList + * - NamedAccessControlPolicyInterface + * - AccessControlListInterface * * @package phpcr * @subpackage interfaces diff --git a/src/PHPCR/Security/PrincipalInterface.php b/src/PHPCR/Security/PrincipalInterface.php new file mode 100644 index 00000000..a39e01fa --- /dev/null +++ b/src/PHPCR/Security/PrincipalInterface.php @@ -0,0 +1,50 @@ + Date: Wed, 25 Jul 2012 11:13:17 +0200 Subject: [PATCH 2/2] changing hashCode method of principal to int to stay compatible with java, add methods to principal and document a bit --- doc/JCR_TO_PHPCR.txt | 23 ++++++++++++++----- src/PHPCR/Security/PrincipalInterface.php | 28 ++++++++++++++++++++--- 2 files changed, 42 insertions(+), 9 deletions(-) diff --git a/doc/JCR_TO_PHPCR.txt b/doc/JCR_TO_PHPCR.txt index b03a82aa..6b77a903 100644 --- a/doc/JCR_TO_PHPCR.txt +++ b/doc/JCR_TO_PHPCR.txt @@ -60,7 +60,7 @@ since Java 1.5.) Wherever the iterators are used, PHPCR requires iterators implementing SeekableIterator and Countable. Together, those iterators have the same -expressivnes as the JCR RangeIterator. +expressiveness as the JCR RangeIterator. Note: Plain PHP arrays would be even simpler than any interfaces, while still allowing to use foreach. But they would have the major drawback that no lazy @@ -282,9 +282,19 @@ backend (if the session is not yet in a transaction). Locking ******* -This is work in progress, as it is not yet implemented in any implementation. +This works exactly as with JCR. For no timeout, instead of the java +Long.MAX_VALUE we use PHP_MAX_INT. -For no timeout, the java Long.MAX_VALUE is changed to PHP_MAX_INT. + +Security +******** + +JCR provides an ACL model built on top of the java.security.Principal interface. +The interfaces have been ported to PHPCR, and we added a PrincipalInterface as +well, as there is no equivalent in PHPCR. + +This chapter has not been implemented yet and might still need to be adjusted +to fit PHP. Drawing the line @@ -312,9 +322,9 @@ At the time of this writing, some JCR features have not been implemented in any PHPCR implementation. In those areas, changes are more likely to happen, once implementation starts and people figure out what needs to be done. Those areas are: -* Lock -* Observation -* Retention + +* Observation (partially) +* Retention and Hold * Security @@ -338,3 +348,4 @@ Contributors: * Henri Bergius * Jordi Boggiano * Christian Stocker +* And others: https://github.com/phpcr/phpcr/graphs/contributors \ No newline at end of file diff --git a/src/PHPCR/Security/PrincipalInterface.php b/src/PHPCR/Security/PrincipalInterface.php index a39e01fa..e7dee9db 100644 --- a/src/PHPCR/Security/PrincipalInterface.php +++ b/src/PHPCR/Security/PrincipalInterface.php @@ -27,24 +27,46 @@ namespace PHPCR\Security; /** - * As there are no acl standard interfaces in PHP this interface provides the + * As there are no ACL standard interfaces in PHP this interface provides the * Principal interface similar to the java.security.Principal * * The Principal is any entity that can be assigned privileges. E.g. a person, * a role, a computer. * - * The reason to have this interface is that the phpcr implementation needs to + * The reason to have this interface is that the PHPCR implementation needs to * store the principals and use them on later requests. */ interface PrincipalInterface { + /** + * Compares this principal to the passed object. Returns true if both this + * principal and the passed object match the same thing. + * + * This is necessary, as the same hashCode does not guarantee equality, and + * the === operator is too strict, as there could be two instances of the + * same principal. + * + * @param mixed $object + * + * @return boolean true if the principal passed to the method is the same + * as this object + */ + function equals($object); + /** * The hash code must be the same for the same principal. * * However it should be unique inside your application for different * principals. * - * @return string a hashcode for this principal. + * @return int a hashcode for this principal. */ function hashCode(); + + /** + * Returns the name of this principal. + * + * @return string name of this principal + */ + function getName(); } \ No newline at end of file