You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@directory.apache.org by er...@apache.org on 2006/01/27 21:04:45 UTC
svn commit: r372962 [2/6] - in /directory/trunks/apacheds/src/site: ./ src/
src/site/ src/site/resources/ src/site/resources/developers/
src/site/resources/images/ src/site/resources/users/ src/site/xdoc/
src/site/xdoc/developers/ src/site/xdoc/drafts/...
Added: directory/trunks/apacheds/src/site/src/site/site.xml
URL: http://svn.apache.org/viewcvs/directory/trunks/apacheds/src/site/src/site/site.xml?rev=372962&view=auto
==============================================================================
--- directory/trunks/apacheds/src/site/src/site/site.xml (added)
+++ directory/trunks/apacheds/src/site/src/site/site.xml Fri Jan 27 12:02:21 2006
@@ -0,0 +1,59 @@
+<?xml version="1.0" encoding="UTF-8"?>
+
+<project>
+ <bannerLeft>
+ <src>images/apache-directory-logo.png</src>
+ <href>http://directory.apache.org/</href>
+ </bannerLeft>
+
+ <body>
+ <links>
+ <item name="ApacheDS" href="http://directory.apache.org/newsite/subprojects/apacheds/index.html"/>
+ <item name="Naming" href="http://directory.apache.org/subprojects/naming/index.html"/>
+ <item name="Network Layer (MINA)" href="http://directory.apache.org/newsite/subprojects/network/index.html"/>
+ <item name="Directory" href="http://directory.apache.org/newsite/index.html"/>
+ </links>
+ <menu name="Apache Directory Server">
+ <item name="Overview" href="/index.html"/>
+ <item name="Features" href="/features.html"/>
+ <item name="Roadmap" href="/roadmap.html"/>
+ <item name="User's Guide" href="/users/index.html" collapse="true">
+ <item name="Building" href="/users/building.html"/>
+ <item name="Authentication" href="/users/authentication.html"/>
+ <item name="Authorization" href="/users/authorization.html"/>
+ <item name="Subentries" href="/users/subentries.html"/>
+ <item name="Collective Attributes" href="/users/collective.html"/>
+ <item name="Configuration" href="/users/configuration.html"/>
+ <item name="Partitions" href="/users/partitions.html"/>
+ <item name="Maven Plugin" href="/users/plugin.html"/>
+ </item>
+ <item name="Developer's Guide" href="/developers/index.html" collapse="true">
+ <item name="Architecture" href="/developers/architecture.html"/>
+ <item name="Components" href="/developers/components.html"/>
+ <item name="Networking" href="/developers/networking.html"/>
+ <item name="Protocol" href="/developers/protocol.html"/>
+ <item name="Backend Subsystem" href="/developers/backend.html"/>
+ </item>
+ <item name="ApacheDS Projects" href="/projects/index.html"/>
+ </menu>
+
+ <!-- <menu name="Project Information">
+ <item name="Combined Javadocs" href="/apidocs/index.html"/>
+ <item name="Wiki" href="http://wiki.apache.org/directory"/>
+ <item name="Open Issues" href="http://issues.apache.org/jira/browse/DIREVE"/>
+ <item name="Source Repositories" href="http://svn.apache.org/viewcvs.cgi/directory/apacheds/trunk/?root=Apache-SVN"/>
+ <item name="Mailing Lists" href="/mailing-lists.html"/>
+ <item name="License" href="/license.html"/>
+ <item name="Notices" href="/notices.html"/>
+ </menu> -->
+
+ <!-- Commented out, still useful as a placeholder for the next event
+ <menu name="ApacheCon US 2005">
+ <item name="ApacheCon US 2005" href="http://www.apachecon.com/"
+ img="http://apache.org/images/ac2005us_blue_125x125.jpg" />
+ </menu>
+ -->
+ ${reports}
+ </body>
+
+</project>
Added: directory/trunks/apacheds/src/site/src/site/xdoc/developers/aci_aciitemabnf.xml
URL: http://svn.apache.org/viewcvs/directory/trunks/apacheds/src/site/src/site/xdoc/developers/aci_aciitemabnf.xml?rev=372962&view=auto
==============================================================================
--- directory/trunks/apacheds/src/site/src/site/xdoc/developers/aci_aciitemabnf.xml (added)
+++ directory/trunks/apacheds/src/site/src/site/xdoc/developers/aci_aciitemabnf.xml Fri Jan 27 12:02:21 2006
@@ -0,0 +1,198 @@
+<?xml version="1.0" encoding="UTF-8"?>
+
+<document>
+ <properties>
+ <author email="ersiner">ersiner</author>
+
+ </properties>
+ <body>
+ <p>
+The ABNF syntax for LDAP ACIItem is as
+follows:</p>
+ <source>ACIItem = "{" sp aci_identificationTag
+ sep sp aci-precedence
+ sep sp aci-authenticationLevel
+ sep sp aci-itemOrUserFirst sp "}"
+
+aci_identificationTag = id-identificationTag msp DirectoryString
+
+aci-precedence = id-precedence msp Precedence
+
+aci-authenticationLevel = id-authenticationLevel msp AuthenticationLevel
+
+aci-itemOrUserFirst = id-itemOrUserFirst msp aci-itemOrUserFirst
+
+aci-itemOrUserFirst = aci-itemFirst / aci-userFirst
+
+aci-itemFirst = id-itemFirst ":" ItemFirst
+
+aci-userFirst = id-userFirst ":" UserFirst
+
+ItemFirst = "{" sp aci-protectedItems
+ sep sp aci-itemPermissions sp "}"
+
+UserFirst = "{" sp aci-userClasses
+ sep sp aci-userPermissions sp "}"
+
+aci-protectedItems = id-protectedItems msp ProtectedItems
+
+aci-itemPermissions = id-itemPermissions msp ItemPermissions
+
+aci-userClasses = id-userClasses msp UserClasses
+
+aci-userPermissions = id-userPermissions msp UserPermissions
+
+ProtectedItems = "{" [ sp aci-entry]
+ [ sep sp aci-allUserAttributeTypes ]
+ [ sep sp aci-attributeType ]
+ [ sep sp aci-allAttributeValues ]
+ [ sep sp aci-allUserAttributeTypesAndValues ]
+ [ sep sp aci-attributeValue ]
+ [ sep sp aci-selfValue ]
+ [ sep sp aci-rangeOfValues ]
+ [ sep sp aci-maxValueCount ]
+ [ sep sp aci-maxImmSub ]
+ [ sep sp aci-restrictedBy ]
+ [ sep sp aci-classes ] sp "}"
+
+ItemPermissions = "{" [ sp ItemPermission
+ *( sep sp ItemPermission ) sp "}"
+
+ItemPermission = "{" [ sp aci-precedence ]
+ sep sp aci-userClasses
+ sep sp aci-grantsAndDenials sp "}"
+
+UserClasses = "{" [ sp aci-allUsers ]
+ [ sep sp aci-thisEntry ]
+ [ sep sp aci-Name ]
+ [ sep sp aci-userGroup ]
+ [ sep sp aci-subtree ] sp "}"
+
+UserPermissions = "{" [ sp UserPermission
+ *( sep sp UserPermission ) ] sp "}"
+
+UserPermission = "{" [ sp aci-precedence ]
+ sep sp aci-protectedItems
+ sep sp aci-grantsAndDenials sp "}"
+
+aci-entry = id-entry
+
+aci-allUserAttributeTypes = id-allUserAttributeTypes
+
+aci-attributeType = id-attributeType msp AttributeTypes
+
+aci-allAttributeValues = id-allAttributeValues msp AttributeTypes
+
+aci-allUserAttributeTypesAndValues = id-allUserAttributeTypesAndValues
+
+aci-attributeValue = id-attributeValue msp AttributeTypeAndValues
+
+aci-selfValue = id-selfValue msp AttributeTypes
+
+aci-rangeOfValues = id-rangeOfValues msp Filter
+
+aci-maxValueCount = id-maxValueCount msp MaxValueCount
+
+aci-maxImmSub = id-maxImmSub msp INTEGER
+
+aci-restrictedBy = id-restrictedBy msp RestrictedBy
+
+aci-classes = id-classes msp Refinement
+
+aci-grantsAndDenials = id-grantsAndDenials msp GrantsAndDenials
+
+aci-allUsers = id-allUsers
+
+aci-thisEntry = id-thisEntry
+
+aci-name = id-name msp DistinguishedNames
+
+aci-userGroup = id-userGroup msp DistinguishedNames
+
+aci-subtree = id-subtree msp SubtreeSpecifications
+
+AttributeTypes = "{" sp AttributeType
+ *( sep sp AttributeType ) sp "}"
+
+AttributeTypeAndValues = "{" sp AttributeTypeAndValue
+ *( sep sp AttributeTypeAndValue ) sp "}"
+
+MaxValueCount = "{" sp AttributeType
+ sep sp INTEGER sp "}"
+
+RestrictedBy = "{" sp RestrictedValue
+ *( sep sp RestrictedValue ) sp "}"
+
+GrantsAndDenials = "{" [ sp GrantAndDenialsBit
+ *( sep sp GrantAndDenialsBit ) ] sp "}"
+ ; WARNING: There SHALL NOT be any duplicates
+
+DistinguishedNames = "{" sp DistinguishedName
+ *( sep sp DistinguishedName ) sp "}"
+
+
+SubtreeSpecifications = "{" sp SubtreeSpecification
+ *( sep sp SubtreeSpecification ) sp "}"
+
+RestrictedValue = "{" sp aci-type
+ sep sp aci-valuesIn "}"
+
+aci-type = id-type msp AttributeType
+
+aci-valuesIn = id-valuesIn msp AttributeType
+
+Precedence = INTEGER(1..255) ; FIXME: How shall we show this ?
+
+AuthenticationLevel = id-none / id-simple / id-strong
+
+GrantAndDenialsBit = id-grantAdd
+ / id-denyAdd
+ / id-grantDiscloseOnError
+ / id-denyDiscloseOnError
+ / id-grantRead
+ / id-denyRead
+ / id-grantRemove
+ / id-denyRemove
+ / id-grantBrowse
+ / id-denyBrowse
+ / id-grantExport
+ / id-denyExport
+ / id-grantImport
+ / id-denyImport
+ / id-grantModify
+ / id-denyModify
+ / id-grantRename
+ / id-denyRename
+ / id-grantReturnDN
+ / id-denyReturnDN
+ / id-grantCompare
+ / id-denyCompare
+ / id-grantFilterMatch
+ / id-denyFilterMatch
+ / id-grantInvoke
+ / id-denyInvoke
+
+;MYRULE
+;id-X = "X"
+</source>
+ <table>
+ <tr>
+ <th>
+ <img src="http://docs.safehaus.org/images/icons/emoticons/information.png"/>
+ </th>
+ <th>
+ <center>The Apache Directory Server way...</center>
+ </th>
+ </tr>
+ <tr>
+ <td/>
+ <td>
+ <p>
+Apache Directory Server allows a fully flexible version of this grammar where
+order of named components and amount of spaces (where applicable) do not
+matter.</p>
+ </td>
+ </tr>
+ </table>
+ </body>
+</document>
Added: directory/trunks/apacheds/src/site/src/site/xdoc/developers/aci_aciitemasn1.xml
URL: http://svn.apache.org/viewcvs/directory/trunks/apacheds/src/site/src/site/xdoc/developers/aci_aciitemasn1.xml?rev=372962&view=auto
==============================================================================
--- directory/trunks/apacheds/src/site/src/site/xdoc/developers/aci_aciitemasn1.xml (added)
+++ directory/trunks/apacheds/src/site/src/site/xdoc/developers/aci_aciitemasn1.xml Fri Jan 27 12:02:21 2006
@@ -0,0 +1,546 @@
+<?xml version="1.0" encoding="UTF-8"?>
+
+<document>
+ <properties>
+ <author email="ersiner">ersiner</author>
+
+ </properties>
+ <body>
+ <section heading="h1" name="ACIItem grammar">
+ <subsection heading="h2" name="ASN.1 Grammar">
+ <p>
+The ASN.1 syntax for ACIItem of X.501 as given in the specificiation is as
+follows</p>
+ <source>ACIItem ::= SEQUENCE {
+ identificationTag DirectoryString { ub-tag },
+ precedence Precedence,
+ authenticationLevel AuthenticationLevel,
+ itemOrUserFirst CHOICE {
+ itemFirst [0] SEQUENCE {
+ protectedItems ProtectedItems,
+ itemPermissions SET OF ItemPermission },
+ userFirst [1] SEQUENCE {
+ userClasses UserClasses,
+ userPermissions SET OF UserPermission } } }
+
+Precedence ::= INTEGER (0..255)
+
+ProtectedItems ::= SEQUENCE {
+ entry [0] NULL OPTIONAL,
+ allUserAttributeTypes [1] NULL OPTIONAL,
+ attributeType [2] SET SIZE (1..MAX) OF AttributeType OPTIONAL,
+ allAttributeValues [3] SET SIZE (1..MAX) OF AttributeType OPTIONAL,
+ allUserAttributeTypesAndValues [4] NULL OPTIONAL,
+ attributeValue [5] SET SIZE (1..MAX) OF AttributeTypeAndValue OPTIONAL,
+ selfValue [6] SET SIZE (1..MAX) OF AttributeType OPTIONAL,
+ rangeOfValues [7] Filter OPTIONAL,
+ maxValueCount [8] SET SIZE (1..MAX) OF MaxValueCount OPTIONAL,
+ maxImmSub [9] INTEGER OPTIONAL,
+ restrictedBy [10] SET SIZE (1..MAX) OF RestrictedValue OPTIONAL,
+ contexts [11] SET SIZE (1..MAX) OF ContextAssertion OPTIONAL,
+ classes [12] Refinement OPTIONAL }
+
+MaxValueCount ::= SEQUENCE {
+ type AttributeType,
+ maxCount INTEGER }
+
+RestrictedValue ::= SEQUENCE {
+ type AttributeType,
+ valuesIn AttributeType }
+
+UserClasses ::= SEQUENCE {
+ allUsers [0] NULL OPTIONAL,
+ thisEntry [1] NULL OPTIONAL,
+ name [2] SET SIZE (1..MAX) OF NameAndOptionalUID OPTIONAL,
+ userGroup [3] SET SIZE (1..MAX) OF NameAndOptionalUID OPTIONAL,
+ -- dn component shall be the name of an
+ -- entry of GroupOfUniqueNames
+ subtree [4] SET SIZE (1..MAX) OF SubtreeSpecification OPTIONAL }
+
+ItemPermission ::= SEQUENCE {
+ precedence Precedence OPTIONAL,
+ -- defaults to precedence in ACIItem
+ userClasses UserClasses,
+ grantsAndDenials GrantsAndDenials }
+
+UserPermission ::= SEQUENCE {
+ precedence Precedence OPTIONAL,
+ -- defaults to precedence in ACIItem
+ protectedItems ProtectedItems,
+ grantsAndDenials GrantsAndDenials }
+
+AuthenticationLevel ::= CHOICE {
+ basicLevels SEQUENCE {
+ level ENUMERATED { none (0), simple (1), strong (2) },
+ localQualifier INTEGER OPTIONAL,
+ signed BOOLEAN DEFAULT FALSE },
+ other EXTERNAL }
+
+GrantsAndDenials ::= BIT STRING {
+ -- permissions that may be used in conjunction
+ -- with any component of ProtectedItems
+ grantAdd (0),
+ denyAdd (1),
+ grantDiscloseOnError (2),
+ denyDiscloseOnError (3),
+ grantRead (4),
+ denyRead (5),
+ grantRemove (6),
+ denyRemove (7),
+ -- permissions that may be used only in conjunction
+ -- with the entry component
+ grantBrowse (8),
+ denyBrowse (9),
+ grantExport (10),
+ denyExport (11),
+ grantImport (12),
+ denyImport (13),
+ grantModify (14),
+ denyModify (15),
+ grantRename (16),
+ denyRename (17),
+ grantReturnDN (18),
+ denyReturnDN (19),
+ -- permissions that may be used in conjunction
+ -- with any component, except entry, of ProtectedItems
+ grantCompare (20),
+ denyCompare (21),
+ grantFilterMatch (22),
+ denyFilterMatch (23),
+ grantInvoke (24),
+ denyInvoke (25) }
+
+AttributeTypeAndValue ::= SEQUENCE {
+ type ATTRIBUTE.&id ({SupportedAttributes}),
+ value ATTRIBUTE.&Type({SupportedAttributes}{@type}) }
+</source>
+ </subsection>
+ <subsection heading="h2" name="BNF grammar">
+ <p>
+Here is the BNF grammar of this ASN.1 grammar
+:</p>
+ <source><wrapperEntryPoint> ::= <theACIItem> EOF
+
+<theACIItem> ::=
+ '{'
+ <spse> <aci_identificationTag> <spse>
+ ',' <spse> <aci_precedence> <spse>
+ ',' <spse> <aci_authenticationLevel> <spse>
+ ',' <spse> <aci_itemOrUserFirst> <spse>
+ '}'
+
+<aci_identificationTag> ::= "identificationTag" <sps> SAFEUTF8STRING
+
+<aci_precedence> ::= "precedence" <sps> INTEGER
+
+<aci_authenticationLevel> ::= "authenticationLevel" <sps> <basicLevels>
+
+<basicLevels> ::= "basicLevels" <spse> ':' <spse> '{' <spse> <level> <spse> <level_follower> '}'
+
+<level> ::= "level" <sps> <levels>
+
+<levels> ::= "none" | "simple" | "strong"
+
+<level_follower> ::= ',' <spse> <localQualifier_signed> | e
+
+<localQualifier_signed> ::=
+ "localQualifier" <sps> INTEGER <spse> <signed_e>
+ | "signed" <sps> <booleanValue> <spse>
+
+<signed_e> ::= ',' <spse> "signed" <sps> <booleanValue> <spse> | e
+
+<booleanValue> ::= "FALSE" | "TRUE"
+
+<aci_itemOrUserFirst> ::= "itemOrUserFirst" <sps> <itemOrUserFirst>
+
+<itemOrUserFirst> ::= <itemFirst> | <userFirst>
+
+<itemFirst> ::= "itemFirst" ':' '{' <spse> <protectedItems> ',' <spse> <itemPermissions> <spse> '}'
+
+<userFirst> ::= "userFirst" ':' '{' <spse> <userClasses> ',' <spse> <userPermissions> <spse> '}'
+
+<protectedItems> ::= "protectedItems" <spse> '{' <spse> <protectedItems_e> <spse> '}'
+
+<protectedItems_e> ::= "entry" <entry_follower_e>
+ | "allUserAttributeTypes" <allUserAttributeTypes_follower_e>
+ | <attributeType> <attributeType_follower_e>
+ | <allAttributeValues> <allAttributeValues_follower_e>
+ | <allUserAttributeTypesAndValues> <allUserAttributeTypesAndValues_follower_>
+ | ATTRIBUTE_VALUE_CANDIDATE <attributeValue_follower_e>
+ | <selfValue> <selfValue_follower_e>
+ | RANGE_OF_VALUES_CANDIDATE <rangeOfValues_follower_e>
+ | <maxValueCount> <maxValueCount_follower_e>
+ | <maxImmSub> <maxImmSub_follower_e>
+ | <restrictedBy> <restrictedBy_follower_e>
+ | <classes>
+ | e
+
+<entry_follower_e> ::= ',' <spse> <entry_follower> | e
+
+<entry_follower> ::=
+ "allUserAttributeTypes" <allUserAttributeTypes_follower_e>
+ | <attributeType> <attributeType_follower_e>
+ | <allAttributeValues> <allAttributeValues_follower_e>
+ | <allUserAttributeTypesAndValues> <allUserAttributeTypesAndValues_follower_e>
+ | ATTRIBUTE_VALUE_CANDIDATE <attributeValue_follower_e>
+ | <selfValue> <selfValue_follower_e>
+ | RANGE_OF_VALUES_CANDIDATE <rangeOfValues_follower_e>
+ | <maxValueCount> <maxValueCount_follower_e>
+ | <maxImmSub> <maxImmSub_follower_e>
+ | <restrictedBy> <restrictedBy_follower_e>
+ | <classes>
+
+<allUserAttributeTypes_follower_e> ::= ',' <spse> <allUserAttributeTypes_follower> | e
+
+<allUserAttributeTypes_follower> ::=
+ <attributeType> <attributeType_follower_e>
+ | <allAttributeValues> <allAttributeValues_follower_e>
+ | <allUserAttributeTypesAndValues> <allUserAttributeTypesAndValues_follower_e>
+ | ATTRIBUTE_VALUE_CANDIDATE <attributeValue_follower_e>
+ | <selfValue> <selfValue_follower_e>
+ | RANGE_OF_VALUES_CANDIDATE <rangeOfValues_follower_e>
+ | <maxValueCount> <maxValueCount_follower_e>
+ | <maxImmSub> <maxImmSub_follower_e>
+ | <restrictedBy> <restrictedBy_follower_e>
+ | <classes>
+
+<attributeType_follower_e> ::= ',' <spse> <attributeType_follower> | e
+<attributeType_follower> ::=
+ <allAttributeValues> <allAttributeValues_follower_e>
+ | <allUserAttributeTypesAndValues> <allUserAttributeTypesAndValues_follower_e>
+ | ATTRIBUTE_VALUE_CANDIDATE <attributeValue_follower_e>
+ | <selfValue> <selfValue_follower_e>
+ | RANGE_OF_VALUES_CANDIDATE <rangeOfValues_follower_e>
+ | <maxValueCount> <maxValueCount_follower_e>
+ | <maxImmSub> <maxImmSub_follower_e>
+ | <restrictedBy< <restrictedBy_follower_e>
+ | <classes>
+
+<allAttributeValues_follower_e> ::= ',' <spse> <allAttributeValues_follower> | e
+
+<allAttributeValues_follower> ::=
+ <allUserAttributeTypesAndValues> <allUserAttributeTypesAndValues_follower_e>
+ | ATTRIBUTE_VALUE_CANDIDATE <attributeValue_follower_e>
+ | <selfValue> <selfValue_follower_e>
+ | RANGE_OF_VALUES_CANDIDATE <rangeOfValues_follower_e>
+ | <maxValueCount> <maxValueCount_follower_e>
+ | <maxImmSub> <maxImmSub_follower_e>
+ | <restrictedBy> <restrictedBy_follower_e>
+ | <classes>
+
+<allUserAttributeTypesAndValues_follower_e> ::= ',' <spse> <allUserAttributeTypesAndValues_follower> | e
+
+<allUserAttributeTypesAndValues_follower> ::=
+ ATTRIBUTE_VALUE_CANDIDATE <attributeValue_follower_e>
+ | <selfValue> <selfValue_follower_e>
+ | RANGE_OF_VALUES_CANDIDATE <rangeOfValues_follower_e>
+ | <maxValueCount> <maxValueCount_follower_e>
+ | <maxImmSub> <maxImmSub_follower_e>
+ | <restrictedBy> <restrictedBy_follower_e>
+ | <classes>
+
+<attributeValue_follower_e> ::= ',' <spse> <attributeValue_follower> | e
+
+<attributeValue_follower> ::=
+ <selfValue> <selfValue_follower_e>
+ | RANGE_OF_VALUES_CANDIDATE <rangeOfValues_follower_e>
+ | <maxValueCount> <maxValueCount_follower_e>
+ | <maxImmSub> <maxImmSub_follower_e>
+ | <restrictedBy> <restrictedBy_follower_e>
+ | <classes>
+
+<selfValue_follower> ::= ',' <spse> <selfValue_follower> | e
+
+<selfValue_follower> ::=
+ RANGE_OF_VALUES_CANDIDATE <rangeOfValues_follower_e>
+ | <maxValueCount> <maxValueCount_follower_e>
+ | <maxImmSub> <maxImmSub_follower_e>
+ | <restrictedBy> <restrictedBy_follower_e>
+ | <classes>
+
+<rangeOfValues_follower> ::= ',' <spse> <rangeOfValues_follower> | e
+
+<rangeOfValues_follower> ::=
+ <maxValueCount> <maxValueCount_follower_e>
+ | <maxImmSub> <maxImmSub_follower_e>
+ | <restrictedBy> <restrictedBy_follower_e>
+ | <classes>
+
+<maxValueCount_follower> ::= ',' <spse> <maxValueCount_follower> | e
+
+<maxValueCount_follower> ::=
+ <maxImmSub> <maxImmSub_follower_e>
+ | <restrictedBy> <restrictedBy_follower_e>
+ | <classes>
+
+<maxImmSub_follower> ::= ',' <spse> <maxImmSub_follower> | e
+
+<maxImmSub_follower> ::=
+ <restrictedBy> <restrictedBy_follower>
+ | <classes>
+
+<restrictedBy_follower> ::= ',' <spse> <classes> | e
+
+<attributeType> ::= "attributeType" <sps> <attributeTypeSet>
+
+<allAttributeValues> ::= "allAttributeValues" <sps> <attributeTypeSet>
+
+<allUserAttributeTypesAndValues> ::= "allUserAttributeTypesAndValues"
+
+<selfValue> ::= "selfValue" <sps> <attributeTypeSet>
+
+<maxValueCount> ::= "maxValueCount" <sps> '{' <spse> <aMaxValueCount> <spse> <aMaxValueCounts> '}'
+
+<aMaxValueCounts> ::= ',' <spse> <aMaxValueCount> <spse> <aMaxValueCounts> | e
+
+<aMaxValueCount> ::= '{' <spse> "type" <sps> <oid> <spse> ',' <spse> "maxCount" <sps> INTEGER <spse> '}'
+
+<maxImmSub> ::= "maxImmSub" <sps> INTEGER
+
+<restrictedBy> ::= "restrictedBy" <sps> '{' <spse> <restrictedValue> <spse> <restrictedValues> '}'
+
+<restrictedValues> ::= ',' <spse> <restrictedValue> <spse> <restrictedValues> | e
+
+<restrictedValue> ::= '{' <spse> "type" <sps> <oid> <spse> ',' <spse> "valuesIn" <sps> <oid> <spse> '}'
+
+<attributeTypeSet> ::= '{' <spse> <oid> <spse> <attributeTypeSets> '}'
+
+<attributeTypeSets> ::= ',' <spse> <oid> <spse> <attributeTypeSet> | e
+
+<classes> ::= "classes" <sps> <refinement>
+
+<itemPermissions> ::= "itemPermissions" <sps> '{' <spse> <itemPermission_e> '}'
+
+<itemPermission_e> ::= <itemPermission> <spse> <itemPermissions_e> | e
+
+<itemPermissions_e> ::= ',' <spse> <itemPermission> <spse> <itemPermissions_e> | e
+
+<itemPermission> ::= '{' <spse> <precedence_e> <spse> '}'
+
+<precedence_e> ::=
+ "precedence" <sps> INTEGER <spse> ',' <spse> <userClasses> <spse> ',' <spse> <grantsAndDenials>
+ | <userClasses> <spse> ',' <spse> <grantsAndDenials>
+
+<grantsAndDenials> ::= "grantsAndDenials" <sps> '{' <spse> <grantAndDenialsBit_e> '}'
+
+<grantAndDenialsBit_e> ::= <grantAndDenialsBit> <spse> <grantAndDenialsBits_e> | e
+
+<grantAndDenialsBits_e> ::= ',' <spse> <grantAndDenialsBit> <spse> <grantAndDenialsBits_e> | e
+
+<grantAndDenialsBit> ::=
+ "grantAdd" // (0),
+ | "denyAdd" // (1),
+ | "grantDiscloseOnError" // (2),
+ | "denyDiscloseOnError" // (3),
+ | "grantRead" // (4),
+ | "denyRead" // (5),
+ | "grantRemove" // (6),
+ | "denyRemove" // (7),
+ | "grantBrowse" // (8),
+ | "denyBrowse" // (9),
+ | "grantExport" // (10),
+ | "denyExport" // (11),
+ | "grantImport" // (12),
+ | "denyImport" // (13),
+ | "grantModify" // (14),
+ | "denyModify" // (15),
+ | "grantRename" // (16),
+ | "denyRename" // (17),
+ | "grantReturnDN" // (18),
+ | "denyReturnDN" // (19),
+ | "grantCompare" // (20),
+ | "denyCompare" // (21),
+ | "grantFilterMatch" // (22),
+ | "denyFilterMatch" // (23),
+ | "grantInvoke" // (24),
+ | "denyInvoke" // (25)
+
+<userClasses> ::= "userClasses" <sps> '{' <spse> <userClasses_e> '}'
+
+<userClasses_e> ::=
+ "allUsers" <allUsers_follower_e> <spse>
+ | "thisEntry" <thisEntry_follower_e> <spse>
+ | <name> <name_follower_e> <spse>
+ | <userGroup> <userGroup_follower_e> <spse>
+ | <subtree> <spse>
+ | e
+
+<allUsers_follower_e> ::= ',' <spse> <allUsers_follower> | e
+
+<allUsers_follower> ::=
+ "thisEntry" <thisEntry_follower_e>
+ | <name> <name_follower_e>
+ | <userGroup> <userGroup_follower_e>
+ | <subtree>
+
+<thisEntry_follower_e> ::= ',' <spse> <thisEntry_follower> | e
+
+<thisEntry_follower> ::=
+ <name> <name_follower_e>
+ | <userGroup> <userGroup_follower_e>
+ | <subtree
+
+<name_follower> ::= ',' <spse> <name_follower> | e
+
+<name_follower> ::=
+ <userGroup> <userGroup_follower_e>
+ | <subtree>
+
+<userGroup_follower_e> ::= ',' <spse> <subtree> | e
+
+<name> ::= "name" <sps> '{' <spse> SAFEUTF8STRING <spse> <names_e> '}'
+
+<names_e> ::= ',' <spse> SAFEUTF8STRING <spse> <names_e> | e
+
+<userGroup> ::= "userGroup" <sps> '{' <spse> SAFEUTF8STRING <spse> <userGroups_e> '}'
+
+<userGroups_e> ::= ',' <spse> SAFEUTF8STRING <spse> <userGroups_e> | e
+
+<subtree> ::= "subtree" <sps> '{' <spse> <subtreeSpecification> <spse> <subtrees_e> '}'
+
+<subtrees_e> ::= ',' <spse> <subtreeSpecification> <spse> <subtrees_e> | e
+
+<userPermissions> ::= "userPermissions" <sps> '{' <spse> <userPermissions_ee> '}'
+
+<userPermissions_ee> ::= <userPermission> <spse> <userPermissions_e> | e
+
+<userPermissions_e> ::= ',' <spse> <userPermission> <spse> <userPermissions_e> | e
+
+<userPermission> ::= '{' <spse> <precedence_ee> <spse> '}'
+
+<precedence_ee> ::=
+ "precedence" <sps> INTEGER <spse> ',' <spse> <protectedItems> <spse> ',' <spse> <grantsAndDenials>
+ | <protectedItems> <spse> ',' <spse> <grantsAndDenials>
+
+<subtreeSpecification> ::= '{' <spse> <subtreeSpecification_e> '}'
+
+<subtreeSpecification_e> ::=
+ <ss_base> <ss_base_follower_e> <spse>
+ | <ss_specificExclusions> <ss_specificExclusions_follower_e> <spse>
+ | <ss_minimum> <ss_minimum_follower_e> <spse>
+ | <ss_maximum> <ss_maximum_follower_e> <spse>
+ | <ss_specificationFilter> <spse>
+ | e
+
+<ss_base_follower_e> ::= ',' <spse> <ss_base_follower> | e
+
+<ss_base_follower> ::=
+ <ss_specificExclusions> <ss_specificExclusions_follower_e>
+ | <ss_minimum> <ss_minimum_follower_e>
+ | <ss_maximum> <ss_maximum_follower_e>
+ | <ss_specificationFilter>
+
+<ss_specificExclusions_follower_e> ::= ',' <spse> <ss_specificExclusions_follower> | e
+
+<ss_specificExclusions_follower> ::=
+ <ss_minimum> <ss_minimum_follower_e>
+ | <ss_maximum> <ss_maximum_follower_e>
+ | <ss_specificationFilter>
+
+<ss_minimum_follower_e> ::= ',' <spse> <ss_minimum_follower> | e
+
+<ss_minimum_follower> ::=
+ <ss_maximum> <ss_maximum_follower_e>
+ | <ss_specificationFilter>
+
+<ss_maximum_follower_e> ::= ',' <spse> <ss_specificationFilter> | e
+
+<ss_base> ::= "base" <sps> SAFEUTF8STRING
+
+<ss_specificExclusions> ::= "specificExclusions" <sps> <specificExclusions>
+
+<specificExclusions> ::= '{' <spse> <specificExclusions_e> '}'
+
+<specificExclusions_e> ::= <specificExclusion> <spse> <specificExclusions_ee> | e
+
+<specificExclusions_ee> ::= ',' <spse> <specificExclusion> <spse> <specificExclusions_ee> | e
+
+<specificExclusion> ::= "chopBefore" ':' SAFEUTF8STRING | "chopAfter" ':' SAFEUTF8STRING
+
+<ss_minimum> ::= "minimum" <sps> INTEGER
+
+<ss_maximum> ::= "maximum" <sps> INTEGER
+
+<ss_specificationFilter> ::= "specificationFilter" <sps> <refinement>
+
+<oid> ::= DESCR | NUMERICOID
+
+<refinement> ::= <item> | <and> | <or> | <not>
+
+<item> ::= "item" ':' <oid>
+
+<and> ::= "and" ':' <refinements>
+
+<or> ::= "or" ':' <refinements>
+
+<not> ::= "not" ':' <refinements>
+
+<refinements> ::= '{' <spse> <refinements_e> '}'
+
+<refinements_e> ::= <refinement> <spse> <refinements_ee> | e
+
+<refinements_ee> ::= ',' <spse> <refinement> <spse> <refinements_ee> | e
+
+<sps> ::= ' ' <spse>
+
+<spse> ::= ' ' <spse> | e
+
+
+
+
+// Lexer
+protected SAFEUTF8CHAR :
+ '\u0001'..'\u0021' |
+ '\u0023'..'\u007F' |
+ '\u00c0'..'\u00d6' |
+ '\u00d8'..'\u00f6' |
+ '\u00f8'..'\u00ff' |
+ '\u0100'..'\u1fff' |
+ '\u3040'..'\u318f' |
+ '\u3300'..'\u337f' |
+ '\u3400'..'\u3d2d' |
+ '\u4e00'..'\u9fff' |
+ '\uf900'..'\ufaff' ;
+
+',' : ',' ;
+
+' ' : ' ' ;
+
+':' : ':' ;
+
+protected DIGIT : '0' | LDIGIT ;
+
+protected LDIGIT : '1'..'9' ;
+
+protected ALPHA : 'A'..'Z' | 'a'..'z' ;
+
+protected INTEGER : DIGIT | ( LDIGIT ( DIGIT )+ ) ;
+
+protected HYPHEN : '-' ;
+
+protected NUMERICOID : INTEGER ( DOT INTEGER )+ ;
+
+protected DOT : '.' ;
+
+INTEGER_OR_NUMERICOID
+ :
+ ( INTEGER DOT ) => NUMERICOID
+ |
+ INTEGER
+ ;
+
+SAFEUTF8STRING : '"'! ( SAFEUTF8CHAR )* '"'! ;
+
+DESCR
+ :
+ ( "attributeValue" ( ' '! )+ '{' ) =>
+ "attributeValue"! ( ' '! )+ '{'! (options { greedy=false;}:. )* '}'!
+ | ( "rangeOfValues" ( ' '! )+ '(') =>
+ "rangeOfValues"! ( ' '! )+ '(' (options { greedy=false;}:. )* ')'
+ | ALPHA ( ALPHA | DIGIT | HYPHEN )*
+ ;
+</source>
+ </subsection>
+ </section>
+ </body>
+</document>
Added: directory/trunks/apacheds/src/site/src/site/xdoc/developers/aci_implnotes.xml
URL: http://svn.apache.org/viewcvs/directory/trunks/apacheds/src/site/src/site/xdoc/developers/aci_implnotes.xml?rev=372962&view=auto
==============================================================================
--- directory/trunks/apacheds/src/site/src/site/xdoc/developers/aci_implnotes.xml (added)
+++ directory/trunks/apacheds/src/site/src/site/xdoc/developers/aci_implnotes.xml Fri Jan 27 12:02:21 2006
@@ -0,0 +1,290 @@
+<?xml version="1.0" encoding="UTF-8"?>
+
+<document>
+ <properties>
+ <author email="akarasulu">akarasulu</author>
+
+ </properties>
+ <body>
+ <section heading="h2" name="Introduction">
+ <p>
+Do not take this document as the final description of how we implement access
+controls within ApacheDS (yet). It is just some notes that have been taken as
+we started implementing the access control subsystem. Eventually it can be
+compiled into developer documentation on how the access control subsystem is
+implemented.</p>
+ <p>
+\\</p>
+ <p>
+\\</p>
+ <p>
+Too follow the JIRA tasks that lead to this feature take a look
+at
+ <a href="http://issues.apache.org/jira/browse/DIREVE-204">DIREVE-204</a>
+.
+ </p>
+ </section>
+ <section heading="h2" name="Access Control Subentry Operational Attribute">
+ <p>
+Although two kinds of subentry types exist for access control administrative
+areas (accessControlSpecificAreas and accessControlInnerAreas) we will still be
+using a single operational attribute within entries to reference the subentries
+of these areas. We will use _accessControlSubentries_ as the identifier for the
+operational attribute containing the DN of subentries which the entry is within
+the scope of: meaning the subtreeSpecification associated with the referenced
+subentries select the entry. Below is the schema definition for this new
+operational attribute which we have assigned off of the apache OID
+space:</p>
+ <source>attributetype ( 1.2.6.1.4.1.18060.1.1.1.3.26 NAME 'accessControlSubentries'
+ DESC 'Used to track a subentry associated with access control areas'
+ SUP distinguishedName
+ EQUALITY distinguishedNameMatch
+ SYNTAX 1.3.6.1.4.1.1466.115.121.1.12
+ SINGLE-VALUE
+ NO-USER-MODIFICATION
+ USAGE directoryOperation )
+</source>
+ <p>
+The subentry subsystem will automatically handle the injection of this attribute
+into normal entries as new subentries are added and altered. This house keeping
+also tracks newly added normal entries making sure they have these operational
+attributes pointing to the appropriate
+subentries.</p>
+ </section>
+ <section heading="h2" name="Performance Considerations">
+ <p>
+An LDAP server should be read optimized. Hence we cannot expect to parse
+lengthy ACIs into ACIITems then transform them into ACITuples for evaluation
+during a search operation. This would considerably slow down search
+operations.</p>
+ <p>
+\\</p>
+ <p>
+\\</p>
+ <p>
+Instead of repeatedly preparing ACI information during search request processing
+the server will cache ACI information in the form of ACITuples. ACI Tuples are
+an intermediate representation of ACIItems designed for the sake of making
+access control decisions within the Access Control Decision Function
+(ACDF).</p>
+ <p>
+\\</p>
+ <p>
+\\</p>
+ <table>
+ <tr>
+ <td>
+ <img src="http://docs.safehaus.org/images/icons/emoticons/warning.png"/>
+ </td>
+ <td>
+ <p>
+A set of ACITuples are generated from an ACIItem. Sets of ACITuples can be
+mixed and evaluated together to represent the combined access control affects of
+one or more
+ACIItems.</p>
+ </td>
+ </tr>
+ </table>
+ <p>
+\\</p>
+ <p>
+\\</p>
+ <p>
+ApacheDS will use the multivalued perscriptiveACI attribute within access
+control subentries to contain multiple ACIItems. The server can generate and
+combine the ACITuple sets of these ACITems within a single subentry to represent
+the next access control effects of that subentry. This superset of ACITuples
+can be cached and associated with the DN of the subentry containing their
+respective ACIItems. Hence during solidstate operation prescriptive ACIItems
+need not be parsed or transformed into ACITuple sets. A simple lookup retrieves
+the ACITuple set for each access control subentry influencing an entry candidate
+to be returned to the client. The ACDF is invoked with this ACITuple set
+(possibly combined with entryACI Tuplesets) and other information to quickly
+determine whether or not access is allowed during any operation not just a
+search
+operation.</p>
+ </section>
+ <section heading="h2" name="Cache Initialization and Upkeep">
+ <p>
+On startup the server must populate the cache with the set of ACITuples from
+respective access control subentries. A search must be conducted for all access
+contol subentries in all namingContexts to discover the set of prescriptiveACIs
+defined within the
+server.</p>
+ <p>
+\\</p>
+ <p>
+\\</p>
+ <p>
+After initialization, during solid state operation, the cache must be kept up to
+date with prescriptiveACI deletions, modifications, and additions. With the
+current interceptor based architecture we can easily keep track of these
+alterations by trapping add, delete, and modify operations on access control
+subentries.</p>
+ <p>
+\\</p>
+ <p>
+\\</p>
+ <p>
+Check out the following JIRA issues and commits for more information on how this
+was
+implemented:</p>
+ <ul nesting="1">
+ <li>
+ <a href="http://svn.apache.org/viewcvs.cgi?view=rev&rev=290038">Commit 290038</a>
+ </li>
+ <li>
+ <a href="http://issues.apache.org/jira/browse/DIREVE-258">DIREVE-258</a>
+ </li>
+ <li>
+ <a href="http://issues.apache.org/jira/browse/DIREVE-259">DIREVE-259</a>
+ </li>
+ </ul>
+ </section>
+ <section heading="h2" name="Marker ObjectClass for Access Control Subentries">
+ <p>
+A marker objectClass is needed for tracking subentries containing
+prescriptiveACI attributes. Looking at various drafts, RFCs and the X.500
+specifications there was very little to go on. However we decided on the
+following
+objectClass:</p>
+ <p>
+\\</p>
+ <p>
+\\</p>
+ <source>objectclass ( 1.2.6.1.4.1.18060.1.1.1.4.100
+ NAME 'accessControlSubentry'
+ AUXILIARY
+ MUST prescriptiveACI )
+</source>
+ <p>
+\\</p>
+ <p>
+\\</p>
+ <p>
+We chose the name because it matches the pattern used
+in
+ <a href="http://www.faqs.org/rfcs/rfc3671.html">RFC 3671</a>
+where the operational attribute used was collectiveAttributeSubentries and the
+marker objectClass was collectiveAttributeSubentry. This makes the access
+control specific analogs consistent with this naming
+pattern.
+ </p>
+ <p>
+\\</p>
+ <p>
+\\</p>
+ <p>
+A perscriptiveACI attribute is included in the must list suggesting that at
+least one ACIItem must be contained by such an entry. This is consistent with
+X.501 where at least one ACIITem is required for an access control subentry.
+This leads us to have to define a prescriptiveACI
+attribute:</p>
+ <p>
+\\</p>
+ <p>
+\\</p>
+ <source>attributetype ( 1.2.6.1.4.1.18060.1.1.1.3.100 NAME 'prescriptiveACI'
+ DESC 'Access control information that applies to a set of entries'
+ EQUALITY directoryStringFirstComponentMatch
+ SYNTAX 1.3.6.1.4.1.1466.115.121.1.1
+ USAGE directoryOperation
+)
+</source>
+ <p>
+\\</p>
+ <p>
+\\</p>
+ <p>
+Note that in the above attributetype description for the prescriptiveACI we have
+to include the syntax for ACIItem. The syntax will need to be added to ApacheDS
+along with the new matching rule directoryStringFirstComponentMatch which is
+defined within section 2.6
+of
+ <a href="http://www.faqs.org/rfcs/rfc3698.html">RFC 3698</a>
+. Note that RFC 2251 presumes the ACI Item syntax is not human readable. We
+shall presume that it is human readable. Here's the JIRA issue and commit
+revision that added these schema objects to the
+server:
+ </p>
+ <p>
+ <a href="http://svn.apache.org/viewcvs.cgi?view=rev&rev=289953">Commit 289953</a>
+ </p>
+ <p>
+ <a href="http://issues.apache.org/jira/browse/DIREVE-257">DIREVE-257</a>
+ </p>
+ </section>
+ <section heading="h2" name="Adding Permission Check Guards to Interceptor Methods">
+ <p>
+To properly check access to an entry we must also check to see if the entry has
+ACIItems associated with it using the entryACI operational attribute. This
+means for each entry we must check for the presence of this attribute and
+perform checks accordingly. Entry ACIITems have tuples generated for them and
+those are combined to form s super ACITuple collection. This collection is fed
+into the ACDF engine to determine if permission is to be
+granted.</p>
+ <p>
+\\</p>
+ <p>
+\\</p>
+ <p>
+Another aspect to this is to determine which grants are required to grant
+permission to an operation. Unfortunately we loose some resolution regarding
+the correspondance of interceptor operations to protocol operations. There
+needs to be a way to correlate LDAP protocol operations when interceptor
+operations are invoked so we can make sure the proper permissions are checked
+for. Presently we have no way to do this. One thing to research is a means to
+stuff protocol operation information into the environment of each JNDI
+operation. There has even been some talk about using some sort of session
+object.</p>
+ </section>
+ <section heading="h2" name="UserGroup for ACI evaluation">
+ <p>
+Group membership is included in access control information and is taken into
+account within the ACDF. The group membership is with respect to the LDAP
+principal the operation is executing as. This means LDAP principals must either
+track this information or the Authorization subsystem must determine this
+information on the
+fly.</p>
+ <p>
+Question: Should we add group membership information to the LdapPrincipal class
+or should we just let the authorization subsystem track this
+info?</p>
+ <p>
+For the sake of performance it might be best to add group membership information
+to the LdapPrincipal so this information is not looked up every time access
+control decisions need to be made. Adding the info to the LdapPrincipal however
+will require Authenticator implementations to have to populate this information.
+A base class can automatically populate this information or some utility class
+can also be provided. Another potential problem is how to update the group
+membership information for LdapPrincipals while they are bound to the directory
+and updates to groups occur. This however is a problem that can be solved
+later.</p>
+ <p>
+If group membership information is cached and updated within
+the</p>
+ <p>
+authorization module these problems can be minimized. The interceptor can also
+update membership information as changes occur. Really there is no other place
+where this info needs to be accessed. It might not pay to put this fuctionality
+into the LdapPrincipal. It's cut to have it there but it may not be required
+anywhere but in the authz
+subsystem.</p>
+ </section>
+ <section heading="h2" name="Special User Handling: Administrator">
+ <p>
+It is very easy for users to lock out the administrator from being able to
+access the directory. This however is not that much of a problem if the access
+control mechanism can be turned off via the configuration. However note that
+most of the configuration of the server is being pushed back into the DIT
+itself. This may cause a problem. In general the administrator of the server
+should have special consideration. Meaning they should have full access and
+should bypass the access control
+mechanism.</p>
+ <p>
+This is why our implementation will detect this special user and bypass access
+control restrictions. In effect the admin can perform any
+operation.</p>
+ </section>
+ </body>
+</document>
Added: directory/trunks/apacheds/src/site/src/site/xdoc/developers/aci_notesfromx501
URL: http://svn.apache.org/viewcvs/directory/trunks/apacheds/src/site/src/site/xdoc/developers/aci_notesfromx501?rev=372962&view=auto
==============================================================================
--- directory/trunks/apacheds/src/site/src/site/xdoc/developers/aci_notesfromx501 (added)
+++ directory/trunks/apacheds/src/site/src/site/xdoc/developers/aci_notesfromx501 Fri Jan 27 12:02:21 2006
@@ -0,0 +1,166 @@
+<?xml version="1.0" encoding="UTF-8"?>
+
+<document>
+ <properties>
+ <author email="akarasulu">akarasulu</author>
+ <title>Access Control Notes from X.501</title>
+ </properties>
+ <body>
+ <section heading="h2" name="Access Control Scheme Operational Attribute: accessControlScheme">
+ <p>
+Below is a snipet from X.501 which talks about an accessControlScheme
+attribute:</p>
+ <p>
+The Directory provides a means for the access control scheme in force in a
+particular portion of the DIB to be identified through the use of the
+operational attribute accessControlScheme. The scope of such a scheme is defined
+by an Access Control Specific Area (ACSA), which is a specific administrative
+area that is the responsibility of the corresponding Security Authority. This
+attribute is placed in the Administrative Entry for the corresponding
+Administrative Point. Only administrative entries for Access Control Specific
+Points are allowed to contain an accessControlScheme
+attribute.</p>
+ <p>
+This translates to having an operational attribute, *accessControlScheme*,
+within the entry at the administrative point. This value of this attribute is
+an OID. The ASN.1 for the attribute is defined below within section 17.2.2. We
+specifically need an LDAP attributeType specification for this ASN.1 definition
+for the attribute so we can add it to the Administrative
+Point.</p>
+ <source>accessControlScheme ATTRIBUTE ::= {
+ WITH SYNTAX OBJECT IDENTIFIER
+ EQUALITY MATCHING RULE objectIdentifierMatch
+ SINGLE VALUE TRUE
+ USAGE directoryOperation
+ ID id-aca-accessControlScheme }
+</source>
+ <p>
+For basic access control the X.501 attribute will contains the value
+*basic-access-control*. However for LDAP we can represent the value as
+*basicAccessControl* and assign it an OID to specifically identify this value.
+Below is the definition for the LDAP
+attributeType:</p>
+ <source>attributetype ( 1.2.6.1.4.1.18060.1.1.1.3.14 NAME 'accessControlScheme'
+ DESC 'Access control scheme in force for a ACSA'
+ EQUALITY objectIdentifierMatch
+ SYNTAX 1.3.6.1.4.1.1466.115.121.1.38
+ USAGE directoryOperation )
+</source>
+ </section>
+ <section heading="h2" name="Protected Items">
+ <table>
+ <tr>
+ <th>
+Protected
+Items</th>
+ </tr>
+ <tr>
+ <td>
+Entries</td>
+ </tr>
+ <tr>
+ <td>
+Attributes</td>
+ </tr>
+ <tr>
+ <td>
+Attribute
+Values</td>
+ </tr>
+ <tr>
+ <td>
+Names</td>
+ </tr>
+ </table>
+ </section>
+ <section heading="h2" name="Aspects of permission categories">
+ <ol nesting="0">
+ <li>
+All operations except delete and modifyDn operations need both entry and
+attribute level
+access.</li>
+ <li>
+To perform Directory operations that require access to attributes or attribute
+values, it is necessary to have entry access permission to the entry or entries
+that contain those attributes or values. Note the removal of an entry or an
+attribute does not require access to the values of an
+attribute.</li>
+ <li>
+Without an explicit grant access is denied. Everything is closed from the
+start. Denials override grants if precedence is the
+same.</li>
+ </ol>
+ </section>
+ <section heading="h2" name="Permission Categories for Entry Access"/>
+ <section heading="h2" name="Subentry Access Control: subentryACI">
+ <p>
+The subentryACI operational attribute would reside within entries of
+administrative points and applies only to immediately subordinate subentries.
+This is specified within section 18.5.3 of
+X.501.</p>
+ <p>
+Conversely perscriptiveACIs in subentries never apply to subentries of the same
+administrative point however they may apply to the subentries of inner areas.
+See section 18.5.3 of X.501. This section is small enough to include
+here:</p>
+ <p>
+Subentry ACI attributes are defined as operational attributes of administrative
+entries, and provide access control information that applies to each of the
+subentries of the corresponding administrative point. Prescriptive ACI within
+the subentries of a particular administrative point never applies to the same or
+any other subentry of that administrative point, but can be applicable to the
+subentries of subordinate administrative points. Subentry ACI attributes are
+contained only in administrative points and do not affect any element of the DIT
+other than immediately subordinate
+subentries.</p>
+ <p>
+In evaluating access control for a specific subentry, the ACI that shall be
+considered
+is:</p>
+ <ul nesting="1">
+ <li>
+the entryACI within the subentry itself (if
+any);</li>
+ <li>
+the subentryACI within the associated administrative entry (if
+any);</li>
+ <li>
+prescriptiveACI associated with other relevant administrative points within the
+same access control specific area (if
+any).</li>
+ </ul>
+ <source>subentryACI ATTRIBUTE ::= {
+ WITH SYNTAX ACIItem
+ EQUALITY MATCHING RULE directoryStringFirstComponentMatch
+ USAGE directoryOperation
+ ID id-aca-subentryACI }
+</source>
+ <p>
+What this means is we have to process access controls differently for
+subentries. So for a subentry we apply the entryACI as we do with other entry
+types. Then we need to apply the subentyACI within the parent which is the
+administrative point
+entry.</p>
+ <p>
+Now how we apply perscriptiveACI to subentries is a bit ambiguous. The subentry
+subsystem does not inject operational attributes into subentries as it does for
+regular entries. Regular entries included by the subtree specification of
+subentries have the operational attributes associated with administrativeRoles
+added to the included entry. These opattrs hold a DN to the including subentry.
+This will not occur for entries that are subentries. At a cursory glance
+imposes some
+problems.</p>
+ <p>
+First of all, we cannot link a subentry A in an outter administrative point to a
+target subentry B included by the subtreeSpecification of the first subentry A.
+This however may not really be necesary to do. This is why the X.501 spec is
+somewhat ambiguous when things boil down to an implementation. Technically a
+subentry is at the same context as its superior administrative point. If that
+is the case, then all subentries including the administrative point also
+includes the subentries. Effectively for our implementation, this means that
+subentries can use the accessControlSubentries operational attribute (if
+present) within the administrative entry to discover perscriptiveACI's effecting
+subentries.</p>
+ </section>
+ </body>
+</document>
Added: directory/trunks/apacheds/src/site/src/site/xdoc/developers/architecture.xml
URL: http://svn.apache.org/viewcvs/directory/trunks/apacheds/src/site/src/site/xdoc/developers/architecture.xml?rev=372962&view=auto
==============================================================================
--- directory/trunks/apacheds/src/site/src/site/xdoc/developers/architecture.xml (added)
+++ directory/trunks/apacheds/src/site/src/site/xdoc/developers/architecture.xml Fri Jan 27 12:02:21 2006
@@ -0,0 +1,116 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<document>
+ <properties>
+ <author email="akarasulu@apache.org">Alex Karasulu</author>
+
+ </properties>
+
+ <body>
+ <section name="High Level Architecture">
+ <subsection name="A picture is worth a thousand words!">
+ <img src="../images/architecture.png"/>
+
+ <p>
+ The server is actually composed of two separable subsystems: the LDAP
+ protocol provider within the SEDA framework and the JNDI provider
+ (a.k.a. the backend subsystem).
+ </p>
+
+ <p>
+ Below we touch breifly on each major subsystem however a more detailed
+ presentation is available describing the server's architecture. It was an
+ ApacheCon presentation in 04 and is available
+<a href="https://karasulu.homeip.net/svn/akarasulu/apachecon/eve-presentation/eve-intro-long.ppt">here</a>.
+ </p>
+ </subsection>
+
+ <subsection name="LDAP Protocol Provider">
+ <p>
+ The LDAP protocol provider is an implementation of the SEDA protocol
+ provider interface. SEDA implements a provider architecture where
+ protocols snap into the framework like legos to service protocol
+ requests. A SEDA provider has no relation to a JNDI provider. Note
+ it can get confusing when talking about providers for SEDA or for
+ JNDI so we try our best to qualify which we refer to explicitly.
+ </p>
+
+ <p>
+ Other protocol providers may be added to a SEDA instance to service
+ multiple protocols on their respective service ports to share the same
+ plumbing. In the picture above we show the Kerberos SEDA provider
+ we've implemented along side the LDAP SEDA provider
+ </p>
+
+ <p>
+ The LDAP protocol provider contains request handlers for each LDAP
+ request PDU type. These handlers translate LDAP requests into
+ operations against an LDAP JNDI provider. This LDAP JNDI provider by
+ default is the JNDI provider. However the JNDI provider can be
+ switched using environment properties to use the SUN LDAP JNDI
+ provider. When using the SUN JNDI Provider the SEDA protocol provider
+ becomes an LDAP proxy server.
+ </p>
+
+ <p>
+ The LDAP protocol provider is extremely simple yet powerful. It
+ merely acts as an LDAP request PDU to JNDI operation transducer. On
+ the wire LDAP requests trigger calls against JNDI contexts through
+ handlers.
+ </p>
+ </subsection>
+
+ <subsection name="JNDI Provider">
+ <p>
+ The heart of the server resides within the backend subsystem or the
+ JNDI provider. The JNDI provider is a JNDI provider for the
+ LDAP namespace. However this provider does not talk LDAP on the wire,
+ it effects the internal backing stores of the server directly. Hence
+ the JNDI Provider is really the server side JNDI provider.
+ </p>
+
+ <p>
+ Fundamentally JNDI is used as the facade to the entire backend
+ subsystem. JNDI interfaces are used to operated upon server backing
+ stores this way. JNDI also serves as the integration API for
+ embedding the server. The ServerContextFactory starts up the backend
+ subsystem as well as the networking code when the first initial
+ context is requested. All other contexts do not incur startup costs.
+ This unique use of JNDI enables code to simply switch JNDI providers
+ to embed the server. It also makes data access code in stored
+ procedures that uses JNDI capable of running inside and outside of
+ the server which makes testing really easy.
+ </p>
+
+ <p>
+ The directory server's backend subsystem contains most of the guts of
+ the server. We want functionality like replication or triggers to be
+ present there regardless of whether the server is in standalone mode
+ or embedded within another application. Hence keeping it within the
+ backend made sense.
+ </p>
+
+ <p>
+ The server contains backing stores to store LDAP entries which really
+ are serialized javax.naming.directory.Attributes objects. These
+ entries live within database partitions attached to a naming context.
+ All entries within these contexts are contained within the partition
+ assigned to it. Several partitions can be present within the same
+ directory server instance. Operations against contexts are routed by
+ a Nexus based on the name (DN) of the entry associated with the
+ operation.
+ </p>
+
+ <p>
+ JNDI contexts hence translate relative operations to distinguished
+ operations against the Nexus which routes these calls to the
+ respective partition to add, delete, modify, search or move around
+ entries. Between calls from JNDI Contexts to the RootNexus an
+ interceptor framework intervenes to inject services like replication,
+ authorization and more.
+ </p>
+ </subsection>
+
+ </section>
+
+ </body>
+</document>
Added: directory/trunks/apacheds/src/site/src/site/xdoc/developers/backend.xml
URL: http://svn.apache.org/viewcvs/directory/trunks/apacheds/src/site/src/site/xdoc/developers/backend.xml?rev=372962&view=auto
==============================================================================
--- directory/trunks/apacheds/src/site/src/site/xdoc/developers/backend.xml (added)
+++ directory/trunks/apacheds/src/site/src/site/xdoc/developers/backend.xml Fri Jan 27 12:02:21 2006
@@ -0,0 +1,120 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<document>
+ <properties>
+ <author email="akarasulu@apache.org">Alex Karasulu</author>
+
+ </properties>
+
+ <body>
+ <section name="Backend Subsystem">
+ <p>
+ The backend subsystem is everything minus the networking layer and the
+ protocol handling layer. It is composed of several parts in itself: the
+ JNDI provider, interceptor framework, schema subsystem, and database
+ subsystem. Each sub-subsystem of the backend is described in the
+ sections to follow.
+ </p>
+
+
+ <subsection name="Database Subsystem">
+ <p>
+ The overall design to the database subsystem is described to some
+ degree within the partition documentation which can be found
+ <a href="../users/partition.html">here</a>. In summary this subsystem
+ is responsible for storing and accessing entries addressed by DN.
+ </p>
+
+ <p>
+ Eventually we intend to delve into the design of the database
+ subsystem by breaking down the search engine, optimizer and default
+ backing store design which uses JDBM BTrees.
+ </p>
+
+ <p>
+ For future reference below the RootNexus is the top level object or
+ facade of the database subsystem. It contains all context partitions
+ and routes calls to them based on the location of the context within
+ the namespace.
+ </p>
+ </subsection>
+
+
+ <subsection name="JNDI Provider">
+ <p>
+ The JNDI Provider is just an implementation of the
+ InitialContextFactory, Context, and other derived interfaces. The
+ factory is used to fire up the entire server if it has not been
+ started already to service the JNDI request. The contexts are simple
+ wrappers around the database subsystem which point to a specific entry
+ withing the namespace. More will be put here as time progresses ...
+ </p>
+ </subsection>
+
+
+ <subsection name="Interceptor Framework">
+ <p>
+ Calls to the RootNexus are made from within Context implementations
+ of the JNDI provider. Relative Context positions or names are
+ translated into (absolute) distinguished names and the appropriate
+ call is made on the RootNexus. The calls are intercepted using a
+ proxy and additional functionality is injected before, after and on
+ exception to calls made on the RootNexus.
+ </p>
+
+ <p>
+ A framework is built around this. The Context, parameters, return
+ values and any exceptions that may be thrown by the call are
+ encapsulated within an Invocation object. This object is passed to
+ a chain of interceptors that operate on the values it holds to
+ implement a service.
+ </p>
+
+ <p>
+ There are three separate types or stages of interceptors.
+ Interceptors can operate before a method invocation, after an
+ invocation and when an error results during any point in this process.
+ Separate chains of interceptors have been created for each stage. The
+ Invocation object is passed through this chain and each interceptor
+ operates upon it.
+ </p>
+
+ <p>
+ Not all interceptor chains are created equally! The before and after
+ chains are fail fast. Meaning the processing of an Invocation object
+ shorts the rest of the chain if one interceptor fails while processing
+ the invocation. This is not the case when processing exceptions in
+ the on error interceptor chain. Regardless of an interceptor's
+ success downstream, all interceptors are guaranteed a chance to
+ operate on the Invocation object. This makes the on-error chain an
+ excellent place to put cleanup code or code to handle failures.
+ </p>
+
+ <p>
+ When implementing a cross cutting service with the interceptor
+ framework one or more interceptors may be added to one or more
+ chains. Keep in mind this framework helps inject new functionality
+ but it can get conjested very quickly.
+ </p>
+ </subsection>
+
+
+ <subsection name="Schema Subsystem">
+ <p>
+ The schema subsystem manages LDAP schema objects. These objects
+ have a direct effect on how lookups and search operations are
+ conducted on the directory. The subsystem contains a set of
+ registries for each type of LDAP schema object based on OID.
+ </p>
+
+ <p>
+ Schema objects may reference one another by OID and so the system
+ is designed to dynamically resolve dependent objects by lookups on
+ these registries.
+ </p>
+ </subsection>
+
+
+ </section>
+
+ </body>
+</document>
Added: directory/trunks/apacheds/src/site/src/site/xdoc/developers/components.xml
URL: http://svn.apache.org/viewcvs/directory/trunks/apacheds/src/site/src/site/xdoc/developers/components.xml?rev=372962&view=auto
==============================================================================
--- directory/trunks/apacheds/src/site/src/site/xdoc/developers/components.xml (added)
+++ directory/trunks/apacheds/src/site/src/site/xdoc/developers/components.xml Fri Jan 27 12:02:21 2006
@@ -0,0 +1,153 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<document>
+ <properties>
+ <author email="akarasulu@apache.org">Alex Karasulu</author>
+
+ </properties>
+
+ <body>
+ <section name="Resources">
+ <p>
+ If the following sections sound a little cryptic you might want
+ to read a little about the IoC pattern. Below are some documents you
+ might find useful when translating some of this babble:
+ </p>
+
+ <ul>
+ <li><a href="http://wiki.apache.org/avalon/WhatIsIoC">
+ Inversion of Control Pattern</a></li>
+
+ <li><a href="http://wiki.apache.org/avalon/AvalonNoLogging?highlight=%28NoLogging%29">
+ Paul Hammant's use of Monitors instead of Loggers</a> is a technique we use.
+ </li>
+ </ul>
+ </section>
+
+ <section name="Components and Services">
+ <p>
+ The server is designed as a system of highly granular components.
+ Some components are a collection of other components with a facade to
+ form a subsystem of the server. Subsystems can contain other
+ subsystems and one component can depend on zero or more other
+ components.
+ </p>
+
+ <p>
+ A micro kernel or component container is required to run the server. By
+ default the server uses its oun glue rather than a container with all the
+ bells and whistles. However it can run in any micro kernel using
+ service wrappers. A micro kernel is a peice of code operating as a
+ component container providing services for that component and running
+ the component through a set of life-cycles. The server is designed to run
+ on any micro kernel using component wrappers. The subsystems and
+ components are designed as Plain Old Java Interfaces and Objects (POJIs
+ and POJOs) that can be wrapped to make them interoperate within
+ different containers.
+ </p>
+
+ <p>
+ Each component within the server has a public service interface which
+ declares what that component can do for its clients. It is always good
+ to keep the interfaces separate from any specific implementations. You
+ can have many implementations for the same service interface. Secondly
+ the classloader heirarchy in containers often puts implementation
+ classloaders under a classloader containing the service interface.
+ This allows containers to manage multiple implementations for the
+ same service without having conflicts. Also implementations can be
+ created and destroyed in separate classloaders without affecting one
+ another.
+ </p>
+ </section>
+
+ <section name="Container Independence">
+ <p>
+ One of the biggest impediments we've had to deal with while developing
+ the server and its precursors was having containers go in and out of
+ fashion. We lost several months of development time while switching
+ from Pheonix to Merlin for example. Today we use some custom glue
+ instead.
+ </p>
+
+ <p>
+ The server has been designed this time from the ground up to be
+ independent of any container. We are doing this by making the default
+ implementation of a service a Plain Old Java Object (POJO). Wrapper
+ implementation projects, one for each supported container, are used to
+ wrap these POJO components to introduce container specific lifecycles
+ and to encapsulate container idiosyncrasies.
+ </p>
+
+ <p>
+ This approach we have found has several advantagous side-effects. One
+ benefit was a nice separation of concerns. By separating out the
+ container specific code, configuration and build aspects, developers
+ no longer need to be aware of container details. They can focus on the
+ core implemenation as a simple class implementing an interface. Those
+ interested in making the server run in one container as opposed to
+ another can focus on their container wrapper without the clutter of
+ another container getting in the way. This reduces the complexity and
+ learning curve for all those involved in developing the directory
+ server's components and subsystems.
+ </p>
+ </section>
+
+ <section name="Monitors Verse Loggers">
+ <p>
+ Above we provided a link to Paul Hammant's concept of using Monitors
+ in place of Logging. Briefly without restating his wiki we'd like to
+ review how we use Monitors instead of Loggers alone.
+ </p>
+
+ <p>
+ Like any other server we need to log what goes on. But rather than log
+ we need to monitor. Logging is a specific type of monitoring for the
+ sake of archiving what we monitor. Paul proposed that every service
+ should propose a very specific Monitor interface. This is a good idea
+ because it is the responsibility of the service to announce those
+ interesting, and monitoring worthy events. The interface forces
+ signatures to explicitly describe what information is involved in the
+ monitoring of an event.
+ </p>
+
+ <p>
+ This makes the component implementation logging system independent
+ which is provided by a container implementation. Each wrapper
+ implementation can provide its own Monitor implementation
+ to interface with the Logging system of the target container.
+ </p>
+
+ <p>
+ We gain by becoming more container independent but more importantly we
+ are forced to consider what events in a service constitutes a
+ noteworthy event. This throught provoking aspect is perhaps the most
+ beneficial.
+ </p>
+ </section>
+
+ <section name="Configuration Beans">
+ <p>
+ Containers are neat because they give component developers a lot of
+ nice features out of the box and that's what they should do. The key
+ to maintaining container independence is to abstract away from these
+ features while still taking advantage of them. This usually translates
+ into a few extra interfaces and classes.
+ </p>
+
+ <p>
+ One benefit of containers is to provide a means to associate a
+ configuration with a component. Most allow for configurations to be
+ stored in properties files and/or XML files. Containers read and load
+ the configuration as a part of processing the lifecycles of components.
+ </p>
+
+ <p>
+ Rather than have POJO component implementations depend directly on
+ configuration interfaces specific to a container we explicitly define
+ configuration beans. POJO implementations are then designed to take
+ configuration beans as constructor arguments if the number of parameters
+ is large and putting so many parameters into a constructor would be
+ too cumbersome.
+ </p>
+ </section>
+ </body>
+</document>
\ No newline at end of file
Added: directory/trunks/apacheds/src/site/src/site/xdoc/developers/index.xml
URL: http://svn.apache.org/viewcvs/directory/trunks/apacheds/src/site/src/site/xdoc/developers/index.xml?rev=372962&view=auto
==============================================================================
--- directory/trunks/apacheds/src/site/src/site/xdoc/developers/index.xml (added)
+++ directory/trunks/apacheds/src/site/src/site/xdoc/developers/index.xml Fri Jan 27 12:02:21 2006
@@ -0,0 +1,78 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<document>
+ <properties>
+ <author email="akarasulu@apache.org">Alex Karasulu</author>
+
+ </properties>
+
+ <body>
+ <section name="Developer's Guide">
+ <p>
+ </p>
+
+ <table>
+ <tr>
+ <th>Topic</th>
+ <th>Description</th>
+ </tr>
+
+ <tr>
+ <td>
+ <a href="./architecture.html">Architecture</a>
+ </td>
+ <td>
+ The server's high level architecture.
+ </td>
+ </tr>
+
+ <tr>
+ <td>
+ <a href="./components.html">Components</a>
+ </td>
+ <td>
+ How we do components in the directory server.
+ </td>
+ </tr>
+
+ <tr>
+ <td>
+ <a href="./networking.html">Networking</a>
+ </td>
+ <td>
+ Describes the directory servers's networking code.
+ </td>
+ </tr>
+
+ <tr>
+ <td>
+ <a href="./protocol.html">Protocol</a>
+ </td>
+ <td>
+ The design of LDAP protocol layer.
+ </td>
+ </tr>
+
+ <tr>
+ <td>
+ <a href="./backend.html">Backend Subsystem</a>
+ </td>
+ <td>
+ Looks at the backend subsystem design in detail.
+ </td>
+ </tr>
+
+ <tr>
+ <td>
+ <a href="./.html"></a>
+ </td>
+ <td>
+
+ </td>
+ </tr>
+
+ </table>
+
+
+ </section>
+ </body>
+</document>
Added: directory/trunks/apacheds/src/site/src/site/xdoc/developers/interceptor_interactions.xml
URL: http://svn.apache.org/viewcvs/directory/trunks/apacheds/src/site/src/site/xdoc/developers/interceptor_interactions.xml?rev=372962&view=auto
==============================================================================
--- directory/trunks/apacheds/src/site/src/site/xdoc/developers/interceptor_interactions.xml (added)
+++ directory/trunks/apacheds/src/site/src/site/xdoc/developers/interceptor_interactions.xml Fri Jan 27 12:02:21 2006
@@ -0,0 +1,164 @@
+<?xml version="1.0" encoding="UTF-8"?>
+
+<document>
+ <properties>
+ <author email="akarasulu">akarasulu</author>
+
+ </properties>
+ <body>
+ <p>
+Interceptors will perform operations on behalf of the user/context making calls
+against the proxy. Interceptors will often need to access or alter the DIT.
+Interceptors have several options for DIT
+access/alteration.</p>
+ <ol nesting="0">
+ <li>
+operate directly against the
+nexus</li>
+ <li>
+operate against the nexus
+proxy</li>
+ <li>
+operate against the next Interceptor in the
+chain</li>
+ <li>
+operate against JNDI
+interfaces</li>
+ <li>
+operate against the nexus proxy with selective
+bypass</li>
+ <li>
+out of band support methods on
+Interceptors</li>
+ </ol>
+ <p>
+A combination of these approaches can be taken. Each one has side effects and
+ramifications when used. We will discuss the ramifications of each option as it
+relates to Interceptor interactions. Interceptor interactions (coupling)
+undermine the overall goal of having orthogonal independent
+services.</p>
+ <section heading="h2" name="Direct Operations Against the Nexus">
+ <p>
+Direct operations against the system nexus retrieves or alters raw entries
+stored within partitions. Sometimes this is absolutely necessary and sometimes
+it could lead to serious
+problems.</p>
+ <subsection heading="h3" name="Direct operations on the nexus bypass the Interceptor Mechanism">
+ <p>
+Direct operations on the nexus bypass the Interceptor mechanism. No Invocation
+object is pushed onto the InvocationStack, and no Interceptors intercept the
+call. If the Interceptor code calling the nexus relies on pre or post
+processing by any other Interceptor there will be a
+problem.</p>
+ <p>
+A good example is the reliance of upstream Interceptors on the Mitosis
+replication Interceptor. Upstream Interceptors ironically don't even know of
+the presence of the Mitosis Interceptor, nor that they rely on it. Mitosis does
+not actually delete entries but marks them deleted. The Mitosis Interceptor
+filters out deleted entries from searches and responds according with
+NameNotFoundExceptions when other operations are performed on entries marked for
+deletion. Interceptors before the Mitosis Interceptor don't have to worry about
+whether or not an entry is deleted because this is handled already. This is not
+the case for downstream Interceptors so positioning is critical. Direct access
+to the nexus however bypasses the Mitosis Interceptor along with all others and
+makes deleted entries
+reappear.</p>
+ </subsection>
+ <subsection heading="h3" name="Raw access to partition entries may be required">
+ <p>
+Raw access to partition entries should be done with extreme caution. But at
+times this access may be absolutely necessary. The Interceptor, it's position
+and the effects of bypassing other possibly unknown Interceptors must be taking
+into
+consideration.</p>
+ </subsection>
+ </section>
+ <section heading="h2" name="Operations on the Nexus Proxy">
+ <p>
+Interceptors that have intercepted an operation, may use the proxy to perform
+other operations. These other operations performed to satisfy the first
+intercepted operation will also traverse the
+InterceptorChain.</p>
+ <subsection heading="h3" name="There is a risk for infinate recursion">
+ <p>
+The danger here is an infinite recursion. Let's suppose the first intercepted
+operation, Invocation *A*, performs operations *A'* (that's A prime) and *B*
+against the nexus. Invocation *A'* by the way is the same operation as the
+intercepted operation but with different parameters. The same operation does not
+mean the same Invocation. In this case *A'* may incur another set of Invocation
+*A"* and *B'* all invoked within the same Interceptor. This chain reaction
+could continue unabated to blow out the stack without
+regulation.</p>
+ <p>
+A good example of an Interceptor prone to an infinite recursion is the
+AuthorizationService. It needs to lookup and search for other other entries to
+determine access rights to perform operations. Those lookup and search
+operations in turn trigger the AuthorizationService again to issue another set
+of lookup and search operations and so on. An infinate recursion is the
+result.</p>
+ <p>
+If the AuthorizationService could call lookup and search on the nexus proxy
+while bypassing itself then the recursion can be avoided. This raises the
+question of whether or not sub-operations excecuted by Interceptors are really
+considered to be performed by the user of the intercepted
+call.</p>
+ </subsection>
+ <subsection heading="h3" name="Effects on the InvocationStack">
+ <p>
+Calls against the nexus proxy are not presently possible. They can however be
+enabled. The foreseeable mechanism would be to just call the proxy object of
+the current intercepted operation. This could be done by peeking at the
+InvocationStack to get a handle on the Invocation object for the current
+operation. From there the calling Context can be accessed. An accessor in the
+Context implementation can expose access to the nexus proxy
+object.</p>
+ <p>
+Calling this nexus proxy will push a new Invocation object on top of the current
+operation's Invocation object. This is good even though the Context is used to
+issue yet another Invocation. The key advantage though is that we can
+diffentiate between the two Invocations even if the caller Context, operation
+and the parameters are the
+same.</p>
+ </subsection>
+ <subsection heading="h3" name="Identity Lock-in">
+ <p>
+Because the same Context object is used, the identity performing the operation
+is the same. This may be good and
+bad.</p>
+ <p>
+It's good because we are associating the sub-operations with the user performing
+the primary operation. Although if we peek onto the stack the bottom most
+Invocation tells us who the original Invocation was issued by. Even if
+sub-operations are performed as another user like the super-user we can tell who
+the original user was that this sub-operation was issued on behalf
+of.</p>
+ <p>
+There will be situations when we want a setUid like mechanism to access
+protected information on behalf of the current user. Even if the current user
+does not have access to protected resources, the Interceptor should be able to
+access these resources to satisfy the current intercepted operation. Meaning
+the Interceptor will need to perform operations as if it were the admin user to
+satisfy an operation on behalf of the current user. Doing this is no simple
+matter: authentication must be bypassed to enable an operation as the admin
+user. Otherwise we would need access to the admin's credentials. Plus
+re-authentication as the admin is unnecesary since the Interceptor is trusted
+with admin rights. If we trust the Interceptor and give it the ability to
+access the DIT as the admin, we must be sure this is done without compromising
+security.</p>
+ <p>
+Another alternative to access protected resources would be to disable access
+controls for select sub-operations performed by an Interceptor. Perhaps even if
+an operation's associated identity is unchanged, another parameter can be used
+to provide access as another user. This would be a special cue to the
+Authorization
+subsystem.</p>
+ <p>
+These limitations just show us that we're missing something in the design of the
+Interceptor Mechanism. Whether we need to handle sub-operations with special
+authorization measures, selectively bypass or require specific Interceptors
+something is
+required.</p>
+ </subsection>
+ </section>
+ </body>
+</document>
Added: directory/trunks/apacheds/src/site/src/site/xdoc/developers/interceptor_mechanism.xml
URL: http://svn.apache.org/viewcvs/directory/trunks/apacheds/src/site/src/site/xdoc/developers/interceptor_mechanism.xml?rev=372962&view=auto
==============================================================================
--- directory/trunks/apacheds/src/site/src/site/xdoc/developers/interceptor_mechanism.xml (added)
+++ directory/trunks/apacheds/src/site/src/site/xdoc/developers/interceptor_mechanism.xml Fri Jan 27 12:02:21 2006
@@ -0,0 +1,115 @@
+<?xml version="1.0" encoding="UTF-8"?>
+
+<document>
+ <properties>
+ <author email="akarasulu">akarasulu</author>
+
+ </properties>
+ <body>
+ <section heading="h2" name="What is it?">
+ <p>
+The mechanism is a means for injecting and isolating orthogonal services into
+calls against the nexus. The nexus is the hub used to route calls to partitions
+to perform CRUD operations upon entries. By injecting these services at this
+level, partition implementators need not duplicate fuctionality. Services such
+as authentication, authorization, schema checking, normalization, operational
+attribute maintenance and more are introduced using Interceptors. By using
+interceptors partition implementors need not be concerned with these aspects and
+can focus on raw CRUD operations against their backing stores what ever they may
+be.</p>
+ </section>
+ <section heading="h2" name="How does it work?">
+ <p>
+Before we talk more about interceptors we must quickly cover the JNDI provider
+implementation since it is somewhat
+related.</p>
+ <subsection heading="h3" name="JNDI Implementation">
+ <p>
+The JNDI implementation is composed of a set of JNDI Context implementations, a
+ContextFactory implementation and a set of helper
+classes.</p>
+ <ul nesting="1">
+ <li>
+DeadContext</li>
+ <li>
+JavaLdapSupport</li>
+ <li>
+ServerContext</li>
+ <li>
+ServerDirContext</li>
+ <li>
+ServerLdapContext</li>
+ <li>
+AbstractContextFactory</li>
+ <li>
+CoreContextFactory</li>
+ <li>
+ServerDirObjectFactory</li>
+ <li>
+ServerDirStateFactory</li>
+ </ul>
+ <p>
+Every JNDI Context implementation in the provider holds a dedicated reference to
+a nexus proxy object. This proxy contains all the operations that the nexus
+contains. The proxy object is at the heart of the mechanism. We will disuss
+it more after covering the rest of the JNDI
+provider.</p>
+ <p>
+Calls made against JNDI Contexts take relative names as arguments. These names
+are relative to the distinguished name of the JNDI Context. Within the Context
+implementations these relative names are transformed into absolute distinguished
+names. The transformed names are used to make calls against the
+proxy.</p>
+ <p>
+Additional processing may occur before or after a call is made by a context on
+its proxy to manage JNDI provider specific functions. One such example is the
+handling of Java objects for serialization and the use of object and state
+factories.</p>
+ </subsection>
+ <subsection heading="h3" name="The nexus proxy object">
+ <p>
+As mentioned above, each Context that is created has a nexus proxy. The proxy
+maintains a handle on the context as
+well.</p>
+ <p>
+The primary job of the proxy is to inject Interceptor based services. It does
+so by invoking a chain of Interceptors managed by the system. Interceptors
+mirror the methods that are intercepted on the nexus interface. When an
+intercepted method is invoked on the proxy, the proxy pushes an Invocation
+object on to the InvocationStack associated with the current executing Thread.
+The proxy then calls the same method on a chain of Interceptors. The results of
+the call are returned after the InvocationStack is
+popped.</p>
+ <p>
+The InvocationStack is used to track the calls being intercepted. Invocation
+objects pushed onto the stack track the context making the call to the proxy,
+the name of the intercepted call and its arguments. A stack is used because in
+the case of Triggers, stored procedures may be invoked which operate against the
+DIT using JNDI. These JNDI calls will also be intercepted. Their Invocation
+object will be stacked on top of the Invocation which raised the Trigger. This
+way identities and context of operations can be tracked and used by the Trigger
+management system to prevent runnaway cascades or to limit the cascade depth.
+There are other areas besides just triggers where this stack will serve a
+purpose.</p>
+ <p>
+The InterceptorChain is a container of Interceptors which has the same or
+analogous methods as do Interceptors. These are for the interceptable methods.
+A call against the chain invokes the first Interceptor which then usually
+invokes the next interceptor in the chain. An Interceptor need not call the
+next interceptor however. It can raise an exception before making the call to
+the next interceptor or it can completely bypass the rest of the chain by just
+returning before calling the next Interceptor. Interceptors can preprocess the
+arguments, or perform other tasks before they invoke the next Interceptor. They
+can also catch exceptions raised by other downstream interceptors and respond to
+them to handle errors. Finally they can perform post processing operations on
+the results of returned values from downstream
+Interceptors.</p>
+ <p>
+One might ask when is the call made against the actual nexus. This happens
+using a special Interceptor which resides at the end of the chain. It actually
+makes the call against the nexus and returns the
+results.</p>
+ </subsection>
+ </section>
+ </body>
+</document>