Mailing-List: contact oak-commits-help@jackrabbit.apache.org; run by ezmlm
Precedence: bulk
Reply-To: oak-dev@jackrabbit.apache.org
Content-Type: text/plain; charset="utf-8"
MIME-Version: 1.0
Content-Transfer-Encoding: 7bit
Subject: svn commit: r1593060 - in /jackrabbit/oak/branches/1.0: ./ oak-doc/
 oak-doc/src/site/markdown/security/authentication.md
 oak-doc/src/site/markdown/security/privilege.md
 oak-doc/src/site/markdown/security/privilege/differences.md
Date: Wed, 07 May 2014 16:30:16 -0000
To: oak-commits@jackrabbit.apache.org
From: mduerig@apache.org
Message-Id: <20140507163016.A04CF2388868@eris.apache.org>

Author: mduerig
Date: Wed May  7 16:30:16 2014
New Revision: 1593060

URL: http://svn.apache.org/r1593060
Log:
OAK-301: Document Oak
Merged r1592787

Modified:
    jackrabbit/oak/branches/1.0/   (props changed)
    jackrabbit/oak/branches/1.0/oak-doc/   (props changed)
    jackrabbit/oak/branches/1.0/oak-doc/src/site/markdown/security/authentication.md
    jackrabbit/oak/branches/1.0/oak-doc/src/site/markdown/security/privilege.md
    jackrabbit/oak/branches/1.0/oak-doc/src/site/markdown/security/privilege/differences.md

Propchange: jackrabbit/oak/branches/1.0/
------------------------------------------------------------------------------
  Merged /jackrabbit/oak/trunk:r1592787

Propchange: jackrabbit/oak/branches/1.0/oak-doc/
------------------------------------------------------------------------------
  Merged /jackrabbit/oak/trunk/oak-doc:r1592787

Modified: jackrabbit/oak/branches/1.0/oak-doc/src/site/markdown/security/authentication.md
URL: http://svn.apache.org/viewvc/jackrabbit/oak/branches/1.0/oak-doc/src/site/markdown/security/authentication.md?rev=1593060&r1=1593059&r2=1593060&view=diff
==============================================================================
--- jackrabbit/oak/branches/1.0/oak-doc/src/site/markdown/security/authentication.md (original)
+++ jackrabbit/oak/branches/1.0/oak-doc/src/site/markdown/security/authentication.md Wed May  7 16:30:16 2014
@@ -151,7 +151,7 @@ upon commit():
 
 _todo_
 
-### Guest Login Module
+#### Guest Login Module
 
 _todo_
 

Modified: jackrabbit/oak/branches/1.0/oak-doc/src/site/markdown/security/privilege.md
URL: http://svn.apache.org/viewvc/jackrabbit/oak/branches/1.0/oak-doc/src/site/markdown/security/privilege.md?rev=1593060&r1=1593059&r2=1593060&view=diff
==============================================================================
--- jackrabbit/oak/branches/1.0/oak-doc/src/site/markdown/security/privilege.md (original)
+++ jackrabbit/oak/branches/1.0/oak-doc/src/site/markdown/security/privilege.md Wed May  7 16:30:16 2014
@@ -18,8 +18,146 @@
 Privilege Management
 --------------------------------------------------------------------------------
 
-_TODO_
+### Characteristics of the Privilege Management Implementation
 
-### Differences wrt Jackrabbit 2.x
+#### General Notes
+As of Oak the built-in and custom privileges are stored in the repository
+underneath `/jcr:system/rep:privileges`. Similar to other repository level date
+(node types, namespaces and versions) this location is shared by all workspaces
+present in the repository. The nodes and properties storing the privilege
+definitions are protected by their node type definition and cannot be modified
+using regular JCR write methods. In addition a specific `Validator` and `CommitHook`
+implementations assert the consistency of the privilege store. The built-in
+privileges are installed using a dedicated implementation of the `RepositoryInitializer`.
 
-see the corresponding [documentation](privilege/differences.html).
\ No newline at end of file
+#### Differences wrt Jackrabbit 2.x
+A comprehensive list of changes compared to Jackrabbit 2.x can be found in the
+corresponding [documentation](privilege/differences.html).
+
+
+#### Built-in Privilege Definitions
+
+- All Privileges as defined by JSR 283
+
+        jcr:read (NOTE: Aggregate since Oak 1.0)
+        jcr:modifyProperties (NOTE: Aggregate since Oak 1.0)
+        jcr:addChildNodes
+        jcr:removeNode
+        jcr:removeChildNodes
+        jcr:readAccessControl
+        jcr:modifyAccessControl
+        jcr:lockManagement
+        jcr:versionManagement
+        jcr:nodeTypeManagement
+        jcr:retentionManagement (NOTE: retention management not yet implemented)
+        jcr:lifecycleManagement (NOTE: lifecycle management not yet implemented)
+        jcr:write
+        jcr:all
+
+- All Privileges defined by JSR 333
+
+        jcr:workspaceManagement (NOTE: wsp management not yet implemented)
+        jcr:nodeTypeDefinitionManagement
+        jcr:namespaceManagement
+
+- All Privileges defined by Jackrabbit 2.x
+
+        rep:write
+        rep:privilegeManagement
+
+- New Privileges defined by OAK 1.0:
+
+        rep:userManagement
+        rep:readNodes
+        rep:readProperties
+        rep:addProperties
+        rep:alterProperties
+        rep:removeProperties
+        rep:indexDefinitionManagement
+
+Please note the following differences with respect to Jackrabbit 2.x definitions:
+
+- `jcr:read` is now an aggregation of `rep:readNodes` and `rep:readProperties`
+- `jcr:modifyProperties` is now an aggregation of `rep:addProperties`, `rep:alterProperties` and `rep:removeProperties`
+
+##### New Privileges
+
+The new Privileges introduced with Oak 1.0 have the following effect:
+
+- `rep:userManagement`: Privilege required in order to write items that define user or group specific content.
+- `rep:readNodes`: Privilege used to allow/deny read access to nodes (aggregate of `jcr:read`)
+- `rep:readProperties`: Privilege used to allow/deny read access to properties (aggregate of `jcr:read`)
+- `rep:addProperties`: Privilege required in order to create new properties (aggreate of `jcr:modifyProperties`)
+- `rep:alterProperties`: Privilege required in order to change existing properties (aggreate of `jcr:modifyProperties`)
+- `rep:removeProperties`: Privilege required in order to remove existing properties (aggreate of `jcr:modifyProperties`)
+- `rep:indexDefinitionManagement`: Privilege required to create, modify or deleate index definitions.
+
+
+### Privilege Representation in the Repository
+
+As of Oak 1.0 all privilege definitions are stored in the repository itself
+underneath `/jcr:system/rep:privileges`. The following privilege related built-in
+node types have been added in OAK 1.0 in order to represent built-in and custom
+privilege definitions.
+
+    [rep:Privileges]
+      + * (rep:Privilege) = rep:Privilege protected ABORT
+      - rep:next (LONG) protected multiple mandatory
+
+    [rep:Privilege]
+      - rep:isAbstract (BOOLEAN) protected
+      - rep:aggregates (NAME) protected multiple
+      - rep:bits (LONG) protected multiple mandatory
+
+Note the protection status of all child items defined by these node type definitions
+as they prevent modification of the privilege definitions using regular JCR
+write operations.
+
+
+### API Extensions
+
+- [PrivilegeConfiguration] : Oak level entry point to retrieve `PrivilegeManager` and privilege related configuration options.
+- [PrivilegeConstants] : Constants related to privilege management such as Oak names of the built-in privileges.
+- [PrivilegeBitsProvider] : Internal provider to read `PrivilegeBits` from the repository content and map names to internal representation (and vice versa).
+- [PrivilegeBits]: Internal representation of JCR privileges.
+
+
+### Configuration
+
+The [PrivilegeConfiguration] is the Oak level entry point to obtain a new
+[PrivilegeManager] as well as privilege related configuration options. The default
+implementation of the [PrivilegeManager] interface is based on Oak API and can
+equally be used for privilege related tasks in the Oak layer.
+
+Please note: While it's in theory possible to replace the default privilege
+management implementation in Oak, this is only recommended if you have in depth
+knowledge and understanding of Jackrabbit/Oak internals and are familiar with
+the security risk associated with it.
+
+#### Examples
+
+##### Access PrivilegeManager in JCR
+
+    PrivilegeManager privilegeManager = session.getWorkspace().getPrivilegeManager();
+
+##### Access PrivilegeManager in Oak
+
+    Root root = contentSession.getLatestRoot();
+    PrivilegeConfiguration config = securityProvider.getConfiguration(PrivilegeConfiguration.class);
+    PrivilegeManager privilegeManage = config.getPrivilegeManager(root, namePathMapper));
+
+##### Register Custom Privilege
+
+    PrivilegeManager privilegeManager = session.getWorkspace().getPrivilegeManager();
+    String privilegeName = ...
+    boolean isAbstract = ...
+    String[] declaredAggregateNames = ...
+    // NOTE: workspace operation that doesn't require Session#save()
+    privilegeManager.registerPrivilege(privilegeName, isAbstract, declaredAggregateNames);
+
+<!-- references -->
+[PrivilegeConfiguration]: /oak/docs/apidocs/org/apache/jackrabbit/oak/spi/security/privilege/PrivilegeConfiguration.html
+[PrivilegeConstants]: /oak/docs/apidocs/org/apache/jackrabbit/oak/spi/security/privilege/PrivilegeConstants.html
+[PrivilegeBitsProvider]: /oak/docs/apidocs/org/apache/jackrabbit/oak/spi/security/privilege/PrivilegeBitsProvider.html
+[PrivilegeBits]: /oak/docs/apidocs/org/apache/jackrabbit/oak/spi/security/privilege/PrivilegeBits.html
+[PrivilegeManager]: http://svn.apache.org/repos/asf/jackrabbit/trunk/jackrabbit-api/src/main/java/org/apache/jackrabbit/api/security/authorization/PrivilegeManager.java
\ No newline at end of file

Modified: jackrabbit/oak/branches/1.0/oak-doc/src/site/markdown/security/privilege/differences.md
URL: http://svn.apache.org/viewvc/jackrabbit/oak/branches/1.0/oak-doc/src/site/markdown/security/privilege/differences.md?rev=1593060&r1=1593059&r2=1593060&view=diff
==============================================================================
--- jackrabbit/oak/branches/1.0/oak-doc/src/site/markdown/security/privilege/differences.md (original)
+++ jackrabbit/oak/branches/1.0/oak-doc/src/site/markdown/security/privilege/differences.md Wed May  7 16:30:16 2014
@@ -16,103 +16,24 @@
   -->
 ### Privilege Management : Differences wrt Jackrabbit 2.x
 
-#### 1. Characteristics of the Privilege Management Implementation
+#### Registration of Custom Privileges
+As far as registration of custom privileges the Oak implementation behaves
+different to Jackrabbit 2.x in the following two aspects:
 
-##### General Notes
-As of OAK the built-in and custom privileges are stored in the repository 
-underneath `/jcr:system/rep:privileges`. Similar to other repository level date
-(node types, namespaces and versions) this location is shared by all workspaces
-present in the repository. The nodes and properties storing the privilege
-definitions are protected by their node type definition.  In addition a specific
-privilege `Validator` and `CommitHook` implementations assert the consistency of
-the privilege store. The built-in privileges are installed using a dedicated
-implementation of the `RepositoryInitializer` [0].
-
-##### Registration of Custom Privileges
-As far as registration of custom privileges the OAK implementation behaves
-different to Jackrabbit 2.x in the following aspects:
 - Registration of new privileges fails with `IllegalStateException` if the editing session has pending changes.
-- Any validation is performed by CommitHooks in order to make sure that modifications made on the OAK API directly is equally verified. Subsequently any violation (permission, privilege consistency) is only detected at the end of the registration process. The privilege manager itself does not perform any validation.
-
-#### 2. Built-in Privilege Definitions
-
-- All Privileges as defined by JSR 283
-    - jcr:read
-    - jcr:modifyProperties
-    - jcr:addChildNodes
-    - jcr:removeNode
-    - jcr:removeChildNodes
-    - jcr:readAccessControl
-    - jcr:modifyAccessControl
-    - jcr:lockManagement
-    - jcr:versionManagement
-    - jcr:nodeTypeManagement
-    - jcr:retentionManagement (NOTE: retention management not yet implemented)
-    - jcr:lifecycleManagement (NOTE: lifecycle management not yet implemented)
-    - jcr:write
-    - jcr:all
-
-
-- All Privileges defined by JSR 333
-    - jcr:workspaceManagement (NOTE: wsp management not yet implemented)
-    - jcr:nodeTypeDefinitionManagement
-    - jcr:namespaceManagement
-
-
-- All Privileges defined by Jackrabbit 2.x
-    - rep:write
-    - rep:privilegeManagement
-
-
-- New Privileges defined by OAK 1.0:
-    - rep:userManagement
-    - rep:readNodes
-    - rep:readProperties
-    - rep:addProperties
-    - rep:alterProperties
-    - rep:removeProperties
-    - rep:indexDefinitionManagement
-
-
-Note the following differences with respect to Jackrabbit 2.x definitions:
-- jcr:read is now an aggregation of rep:readNodes and rep:readProperties
-- jcr:modifyProperties is now an aggregation of rep:addProperties, rep:alterProperties and rep:removeProperties
-
-#### 3. Node Type Definitions
-
-The following privilege related built-in node types have been added in OAK 1.0.
-They are used to represent built-in and custom privilege definitions in the repository.
-
-    [rep:Privileges]
-      + * (rep:Privilege) = rep:Privilege protected ABORT
-      - rep:next (LONG) protected multiple mandatory
-
-    [rep:Privilege]
-      - rep:isAbstract (BOOLEAN) protected
-      - rep:aggregates (NAME) protected multiple
-      - rep:bits (LONG) protected multiple mandatory
-
-#### 4. API Extensions
-
-org.apache.jackrabbit.oak.spi.security.privilege
-
-- `PrivilegeBitsProvider` : Provider implementation to read `PrivilegeBits` from the repository content and map names to internal representation (and vice versa) [2].
-- `PrivilegeBits`: Internal representation of JCR privileges [3].
-
-#### 5. Configuration
-
-##### PrivilegeConfiguration [1]:
-- `getPrivilegeManager` -> returns a new instance of the `PrivilegeManager`
-   interface such as exposed by `JackrabbitWorkspace#getPrivilegeManager`.
-   Note that the default implementation is based on OAK API and can equally be
-   used for privilege related tasks in the OAK layer.
-
-#### 6. References
-
-[0] http://svn.apache.org/repos/asf/jackrabbit/oak/trunk/oak-core/src/main/java/org/apache/jackrabbit/oak/security/privilege/PrivilegeInitializer.java
-
-[1] http://svn.apache.org/repos/asf/jackrabbit/oak/trunk/oak-core/src/main/java/org/apache/jackrabbit/oak/spi/security/privilege/PrivilegeConfiguration.java
+- Any validation is performed by CommitHooks in order to make sure that modifications made on the Oak API directly is equally verified. Subsequently any violation (permission, privilege consistency) is only detected at the end of the registration process. The privilege manager itself does not perform any validation.
 
-[2] http://svn.apache.org/repos/asf/jackrabbit/oak/trunk/oak-core/src/main/java/org/apache/jackrabbit/oak/spi/security/privilege/PrivilegeBitsProvider.java
+#### Built-in Privilege Definitions
+The following changes have been made to built-in privilege definitions:
 
-[3] http://svn.apache.org/repos/asf/jackrabbit/oak/trunk/oak-core/src/main/java/org/apache/jackrabbit/oak/spi/security/privilege/PrivilegeBits.java
\ No newline at end of file
+- Modifications:
+    - `jcr:read` is now an aggregation of `rep:readNodes` and `rep:readProperties`
+    - `jcr:modifyProperties` is now an aggregation of `rep:addProperties`, `rep:alterProperties` and `rep:removeProperties`
+- New Privileges defined by Oak 1.0:
+    - `rep:userManagement`
+    - `rep:readNodes`
+    - `rep:readProperties`
+    - `rep:addProperties`
+    - `rep:alterProperties`
+    - `rep:removeProperties`
+    - `rep:indexDefinitionManagement`
\ No newline at end of file