svn commit: r1737932 - in /jackrabbit/oak/trunk/oak-doc/src/site/markdown/security: accesscontrol/editing.md permission.md permission/permissionsandprivileges.md

[an...@apache.org]

Author: angela
Date: Wed Apr  6 07:42:18 2016
New Revision: 1737932

URL: http://svn.apache.org/viewvc?rev=1737932&view=rev
Log:
minor improvement: security documentation

Added:
    jackrabbit/oak/trunk/oak-doc/src/site/markdown/security/permission/permissionsandprivileges.md
Modified:
    jackrabbit/oak/trunk/oak-doc/src/site/markdown/security/accesscontrol/editing.md
    jackrabbit/oak/trunk/oak-doc/src/site/markdown/security/permission.md

Modified: jackrabbit/oak/trunk/oak-doc/src/site/markdown/security/accesscontrol/editing.md
URL: http://svn.apache.org/viewvc/jackrabbit/oak/trunk/oak-doc/src/site/markdown/security/accesscontrol/editing.md?rev=1737932&r1=1737931&r2=1737932&view=diff
==============================================================================
--- jackrabbit/oak/trunk/oak-doc/src/site/markdown/security/accesscontrol/editing.md (original)
+++ jackrabbit/oak/trunk/oak-doc/src/site/markdown/security/accesscontrol/editing.md Wed Apr  6 07:42:18 2016
@@ -47,6 +47,10 @@ principals is actually allowed to perfor
 use `Session.hasPermission(String, String)` and either pass the actions strings
 defined by JCR or the names of the Oak permissions.
 
+See section [Permissions vs Privileges](../permission/permissionsandprivileges.html) for an
+comprehensive overview on the differences between testing permissions on `Session`
+and privileges on `AccessControlManager`.
+
 
 #### Reading Policies
 

Modified: jackrabbit/oak/trunk/oak-doc/src/site/markdown/security/permission.md
URL: http://svn.apache.org/viewvc/jackrabbit/oak/trunk/oak-doc/src/site/markdown/security/permission.md?rev=1737932&r1=1737931&r2=1737932&view=diff
==============================================================================
--- jackrabbit/oak/trunk/oak-doc/src/site/markdown/security/permission.md (original)
+++ jackrabbit/oak/trunk/oak-doc/src/site/markdown/security/permission.md Wed Apr  6 07:42:18 2016
@@ -44,6 +44,9 @@ The actions are expected to be a comma s
 **Note**: As of Oak 1.0 the these methods also handle the names of the permissions
 defined by Oak (see `Permissions#getString(long permissions)`).
 
+See also section [Permissions vs Privileges](permission/permissionsandprivileges.html) for 
+a comparison of these permission checks and testing privileges on the `AccessControlManager`. 
+
 ##### Examples
 ###### Test if session has permission to add a new node
 
@@ -283,6 +286,7 @@ The supported configuration options of t
 <a name="further_reading"/>
 ### Further Reading
 
+- [Permissions vs Privileges](permission/permissionsandprivileges.html)
 - [Differences wrt Jackrabbit 2.x](permission/differences.html)
 - [Permissions : The Default Implementation](permission/default.html)
 - [Permission Evaluation in Detail](permission/evaluation.html)

Added: jackrabbit/oak/trunk/oak-doc/src/site/markdown/security/permission/permissionsandprivileges.md
URL: http://svn.apache.org/viewvc/jackrabbit/oak/trunk/oak-doc/src/site/markdown/security/permission/permissionsandprivileges.md?rev=1737932&view=auto
==============================================================================
--- jackrabbit/oak/trunk/oak-doc/src/site/markdown/security/permission/permissionsandprivileges.md (added)
+++ jackrabbit/oak/trunk/oak-doc/src/site/markdown/security/permission/permissionsandprivileges.md Wed Apr  6 07:42:18 2016
@@ -0,0 +1,95 @@
+<!--
+   Licensed to the Apache Software Foundation (ASF) under one or more
+   contributor license agreements.  See the NOTICE file distributed with
+   this work for additional information regarding copyright ownership.
+   The ASF licenses this file to You under the Apache License, Version 2.0
+   (the "License"); you may not use this file except in compliance with
+   the License.  You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.
+-->
+
+Permissions vs Privileges
+--------------------------------------------------------------------------------
+
+### General Notes
+
+Usually it is not required for a application to check the privileges/permissions
+of a given session (or set of principals) as this evaluation can be left
+to the repository.
+
+For rare cases where the application needs to understand if a given session is 
+actually allowed to perform a given action, it is recommend to use `Session.hasPermission(String, String)`.
+
+In order to test permissions that are not reflected in the action constants
+defined on `Session` or `JackrabbitSession`, the default implementation also allows
+to pass the names of the Oak internal permission. 
+
+Alternatively, `AccessControlManager.hasPrivileges(String, Privilege[])` can be used.
+
+The subtle differences between the permission-testing `Session`  and the evaluation
+of privileges on `AccessControlManager` are listed below.
+
+### Testing Permissions
+
+#### Variants
+
+- `Session.hasPermission(String absPath, String actions)`
+- `Session.checkPermission(String absPath, String actions)`
+
+Where
+
+- `absPath` is an absolute path pointing to an existing or non-existing item (node or property)
+- `actions` defines a comma-separated string of the actions defined on `Session` and `JackrabbitSession`. 
+  With the default implementation also Oak internal permission names are allowed ( _Note:_ permission names != privilege names)
+
+#### Characteristics
+
+- API call always supported even if access control management is not part of the feature set (see corresponding repository descriptor).
+- _Note:_ `ACTION_ADD_NODE` is evaluating if the node at the specified absPath can be added; i.e. the path points to the non-existing node you want to add
+- Not possible to evaluate custom privileges with this method as those are not respected by the default permission evaluation.
+- Restrictions will be respected as possible with the given (limited) information 
+
+
+### Testing Privileges
+
+#### Variants
+
+- `AccessControlManager.hasPrivileges(String absPath, Privilege[] privileges)`
+- `AccessControlManager.getPrivileges(String absPath)`
+
+Where
+
+- `absPath` must point to an existing Node (i.e. existing and accessible to the editing session)
+- `privileges` represent an array of supported privileges (see corresponding API calls)
+
+For testing purpose the Jackrabbit extension further allows to verify the privileges 
+granted to a given combination of principals, which may or may not reflect the actual 
+principal-set assigned to a given `Subject`. These calls (see below) however
+requires the ability to read access control content on the target path.
+
+- `JackrabbitAccessControlManager.hasPrivileges(String absPath, Set<Principal> principals, Privilege[] privileges)`
+- `JackrabbitAccessControlManager.getPrivileges(String absPath, Set<Principal> principals)`
+
+#### Characteristics
+
+- Only available if access control management is part of the supported feature set of the JCR repository.
+- Built-in and/or custom privileges can be tested
+- `jcr:addChildNode` evaluates if any child can be added at the parent node identify by the specified absPath. The name of child is not known here! 
+- Restrictions may or may not be respected
+- Default implementation close to real permission evaluation (not exactly following the specification)
+
+<a name="further_reading"/>
+### Further Reading
+
+- [Mapping Privileges to Items](../privilege/mappingtoitems.html)
+- [Mapping API Calls to Privileges](../privilege/mappingtoprivileges.html)
+
+
+