svn commit: r1729681 - in /jackrabbit/oak/trunk/oak-doc/src/site/markdown/security: accesscontrol/editing.md authorization/cug.md principal.md

[an...@apache.org]

Author: angela
Date: Wed Feb 10 18:08:10 2016
New Revision: 1729681

URL: http://svn.apache.org/viewvc?rev=1729681&view=rev
Log:
OAK-3946 : Document oak-authorization-cug
minor improvement: documenting oak security (improve structure and readibility)

Modified:
    jackrabbit/oak/trunk/oak-doc/src/site/markdown/security/accesscontrol/editing.md
    jackrabbit/oak/trunk/oak-doc/src/site/markdown/security/authorization/cug.md
    jackrabbit/oak/trunk/oak-doc/src/site/markdown/security/principal.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=1729681&r1=1729680&r2=1729681&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 Feb 10 18:08:10 2016
@@ -54,7 +54,6 @@ defined by JCR or the names of the Oak p
     - `getApplicablePolicies(String)`
     - `getPolicies(String)`
 
-
 - `JackrabbitAccessControlManager`
     - `getApplicablePolicies(Principal)`
     - `getPolicies(Principal)`

Modified: jackrabbit/oak/trunk/oak-doc/src/site/markdown/security/authorization/cug.md
URL: http://svn.apache.org/viewvc/jackrabbit/oak/trunk/oak-doc/src/site/markdown/security/authorization/cug.md?rev=1729681&r1=1729680&r2=1729681&view=diff
==============================================================================
--- jackrabbit/oak/trunk/oak-doc/src/site/markdown/security/authorization/cug.md (original)
+++ jackrabbit/oak/trunk/oak-doc/src/site/markdown/security/authorization/cug.md Wed Feb 10 18:08:10 2016
@@ -15,7 +15,7 @@
    limitations under the License.
 -->
 
-Managing Access with Closed User Groups (CUG)
+Managing Access with "Closed User Groups" (CUG)
 --------------------------------------------------------------------------------
 
 ### General
@@ -25,7 +25,14 @@ _todo_
 <a name="jackrabbit_api"/>
 ### Jackrabbit API
 
-_todo: PrincipalSetPolicy_
+The Jackrabbit API defines an extension of the JCR [AccessControlPolicy] interface 
+intended to grant the ability to perform certain actions to a set of
+[Principal]s:
+
+- `PrincipalSetPolicy`
+
+See [Jackrabbit API](http://svn.apache.org/repos/asf/jackrabbit/trunk/jackrabbit-api/src/main/java/org/apache/jackrabbit/api/security/authorization/PrincipalSetPolicy.java) 
+for details and the methods exposed by the interface.
 
 <a name="api_extensions"/>
 ### API Extensions
@@ -33,11 +40,11 @@ _todo: PrincipalSetPolicy_
 _todo: CugPolicy_
 _todo: CugExclude_
 
-### Characteristics of the default CUG Implementation
+### Implementation Details
 
 _todo_
 
-#### CUG Representation in the Repository
+### Representation in the Repository
 
 CUG policies defined by this module in a dedicate node name `rep:cugPolicy` of 
 type `rep:CugPolicy`. This node is defined by a dedicate mixin type 
@@ -53,7 +60,7 @@ access in the restricted area:
       - rep:principalNames (STRING) multiple protected mandatory IGNORE
 
 <a name="validation"/>
-##### Validation
+### Validation
 
 The consistency of this content structure both on creation and modification is
 asserted by a dedicated `CugValidatorProvider`. The corresponding error are
@@ -69,6 +76,8 @@ all of type `AccessControl` with the fol
 <a name="configuration"/>
 ### Configuration
 
+_todo_
+
 #### Configuration Parameters
 
 The implementation supports the following configuration parameters:
@@ -90,4 +99,6 @@ _todo: customize cug-authorization by pr
 
 _todo_
 
-<!-- references -->
\ No newline at end of file
+<!-- hidden references -->
+[Principal]: http://docs.oracle.com/javase/7/docs/api/java/security/Principal.html
+[AccessControlPolicy]: http://www.day.com/specs/javax.jcr/javadocs/jcr-2.0/javax/jcr/security/AccessControlPolicy.html
\ No newline at end of file

Modified: jackrabbit/oak/trunk/oak-doc/src/site/markdown/security/principal.md
URL: http://svn.apache.org/viewvc/jackrabbit/oak/trunk/oak-doc/src/site/markdown/security/principal.md?rev=1729681&r1=1729680&r2=1729681&view=diff
==============================================================================
--- jackrabbit/oak/trunk/oak-doc/src/site/markdown/security/principal.md (original)
+++ jackrabbit/oak/trunk/oak-doc/src/site/markdown/security/principal.md Wed Feb 10 18:08:10 2016
@@ -22,8 +22,9 @@ Principal Management
 ### JCR API
 
 JCR itself doesn't come with a dedicated principal management API. Nevertheless
-the specification mentions `java.security.Principal` as key feature for
-access control management but leaves the discovery of principals to the implementation.
+the specification mentions `java.security.Principal` as key feature for access 
+control management but leaves the discovery of principals to the implementation 
+(see [Section 16.5.7](http://www.day.com/specs/jcr/2.0/16_Access_Control_Management.html#16.5.7%20Principal%20Discovery)).
 
 Therefore an API for principal management has been defined as part of the
 extensions present with Jackrabbit API.
@@ -37,7 +38,7 @@ are missing in JCR. The relevant interfa
 
 - `PrincipalManager`
 - `PrincipalIterator`
-- `JackrabbitPrincipal`
+- `JackrabbitPrincipal` extends [Principal](http://docs.oracle.com/javase/7/docs/api/java/security/Principal.html)
     - `ItemBasedPrincipal`
 
 #### Differences wrt Jackrabbit 2.x