X-Git-Url: https://git.sur5r.net/?a=blobdiff_plain;f=doc%2Fman%2Fman5%2Fslapd.access.5;h=0b11805952ad1cf409ad4c948f1b93c538198aec;hb=c8c34cdd43d3603f3b64a56841b4425379c98f45;hp=b17c83afabfeaaf0d3022e24867b41277749683f;hpb=a9f2f12b9384541523ffdfcad3336e397e6658de;p=openldap

diff --git a/doc/man/man5/slapd.access.5 b/doc/man/man5/slapd.access.5
index b17c83afab..0b11805952 100644
--- a/doc/man/man5/slapd.access.5
+++ b/doc/man/man5/slapd.access.5
@@ -1,6 +1,7 @@
 .TH SLAPD.ACCESS 5 "RELEASEDATE" "OpenLDAP LDVERSION"
-.\" Copyright 1998-2004 The OpenLDAP Foundation All Rights Reserved.
+.\" Copyright 1998-2011 The OpenLDAP Foundation All Rights Reserved.
 .\" Copying restrictions apply.  See COPYRIGHT/LICENSE.
+.\" $OpenLDAP$
 .SH NAME
 slapd.access \- access configuration for slapd, the stand-alone LDAP daemon
 .SH SYNOPSIS
@@ -10,9 +11,7 @@ The
 .BR slapd.conf (5)
 file contains configuration information for the
 .BR slapd (8)
-daemon. This configuration file is also used by the
-.BR slurpd (8)
-replication daemon and by the SLAPD tools
+daemon. This configuration file is also used by the SLAPD tools
 .BR slapacl (8),
 .BR slapadd (8),
 .BR slapauth (8),
@@ -55,24 +54,75 @@ are then used.
 If no access controls are present, the default policy
 allows anyone and everyone to read anything but restricts
 updates to rootdn.  (e.g., "access to * by * read").
-The rootdn can always read and write EVERYTHING!
+.LP
+When dealing with an access list, because the global access list is 
+effectively appended to each per-database list, if the resulting 
+list is non-empty then the access list will end with an implicit 
+.B access to * by * none
+directive. If there are no access directives applicable to a backend, 
+then a default read is used.
+.LP
+.B Be warned: the rootdn can always read and write EVERYTHING!
 .LP
 For entries not held in any backend (such as a root DSE), the
-directives of the first backend (and any global directives) are
-used.
+global directives are used.
 .LP
 Arguments that should be replaced by actual text are shown in
 brackets <>.
 .SH THE ACCESS DIRECTIVE
 The structure of the access control directives is
 .TP
-.B access to <what> "[ by <who> <access> [ <control> ] ]+"
+.B access to <what> "[ by <who> [ <access> ] [ <control> ] ]+"
 Grant access (specified by 
 .BR <access> ) 
 to a set of entries and/or attributes (specified by 
 .BR <what> ) 
 by one or more requestors (specified by 
 .BR <who> ).
+
+.LP
+Lists of access directives are evaluated in the order they appear
+in \fIslapd.conf\fP.
+When a
+.B <what>
+clause matches the datum whose access is being evaluated, its
+.B <who>
+clause list is checked.
+When a
+.B <who>
+clause matches the accessor's properties, its
+.B <access>
+and
+.B <control>
+clauses are evaluated.
+Access control checking stops at the first match of the
+.B <what>
+and
+.B <who>
+clause, unless otherwise dictated by the
+.B <control>
+clause.
+Each
+.B <who>
+clause list is implicitly terminated by a
+.LP
+.nf
+	by * none stop
+.fi
+.LP
+clause that results in stopping the access control with no access 
+privileges granted.
+Each
+.B <what>
+clause list is implicitly terminated by a
+.LP
+.nf
+	access to *
+		by * none
+.fi
+.LP
+clause that results in granting no access privileges to an otherwise
+unspecified datum.
 .SH THE <WHAT> FIELD
 The field
 .BR <what>
@@ -80,9 +130,9 @@ specifies the entity the access control directive applies to.
 It can have the forms
 .LP
 .nf
-	[dn[.<dnstyle>]=]<dnpattern>
+	dn[.<dnstyle>]=<dnpattern>
 	filter=<ldapfilter>
-	attrs=<attrlist>[ val[.<attrstyle>]=<attrval>]
+	attrs=<attrlist>[ val[/matchingRule][.<attrstyle>]=<attrval>]
 .fi
 .LP
 with
@@ -98,9 +148,6 @@ with
 The statement
 .B dn=<dnpattern>
 selects the entries based on their naming context.
-The 
-.B dn=
-part is optional.
 The
 .B <dnpattern>
 is a string representation of the entry's DN.
@@ -112,11 +159,7 @@ form is given.
 .LP
 The 
 .B <dnstyle> 
-is also optional; however, it is recommended to specify both the 
-.B dn=
-and the
-.B <dnstyle>
-to avoid ambiguities.
+is optional; however, it is recommended to specify it to avoid ambiguities.
 .B Base 
 (synonym of
 .BR baseObject ),
@@ -153,11 +196,11 @@ as detailed in
 and/or
 .BR re_format (7),
 matching a normalized string representation of the entry's DN.
-The regex form of the pattern does not (yet) support UTF\-8.
+The regex form of the pattern does not (yet) support UTF-8.
 .LP
 The statement
 .B filter=<ldapfilter>
-selects the entries based on a valid LDAP filter as described in RFC 2254.
+selects the entries based on a valid LDAP filter as described in RFC 4515.
 A filter of
 .B (objectClass=*)
 is implied if no
@@ -190,20 +233,19 @@ form is given,
 is implied, i.e. all attributes are addressed.
 .LP
 Using the form
-.B attrs=<attr> val[.<style>]=<attrval>
+.B attrs=<attr> val[/matchingRule][.<attrstyle>]=<attrval>
 specifies access to a particular value of a single attribute.
-In this case, only a single attribute type may be given. A value
-.B <style>
-of
+In this case, only a single attribute type may be given. The
+.B <attrstyle>
 .B exact
 (the default) uses the attribute's equality matching rule to compare the
-value. If the value
-.B <style>
+value, unless a different (and compatible) matching rule is specified. If the
+.B <attrstyle>
 is
 .BR regex ,
 the provided value is used as a POSIX (''extended'') regular
-expression pattern.  If the attribute has DN syntax, the value
-.B <style>
+expression pattern.  If the attribute has DN syntax, the 
+.B <attrstyle>
 can be any of
 .BR base ,
 .BR onelevel ,
@@ -215,6 +257,24 @@ resulting in base, onelevel, subtree or children match, respectively.
 The dn, filter, and attrs statements are additive; they can be used in sequence 
 to select entities the access rule applies to based on naming context,
 value and attribute type simultaneously.
+Submatches resulting from
+.B regex
+matching can be dereferenced in the
+.B <who>
+field using the syntax
+.IR ${v<n>} ,
+where
+.I <n>
+is the submatch number.
+The default syntax,
+.IR $<n> ,
+is actually an alias for
+.IR ${d<n>} ,
+that corresponds to dereferencing submatches from the
+.B dnpattern
+portion of the
+.B <what>
+field.
 .SH THE <WHO> FIELD
 The field
 .B <who>
@@ -230,10 +290,18 @@ It can have the forms
 	*
 	anonymous
 	users
-	self
+	self[.<selfstyle>]
 
 	dn[.<dnstyle>[,<modifier>]]=<DN>
 	dnattr=<attrname>
+
+	realanonymous
+	realusers
+	realself[.<selfstyle>]
+
+	realdn[.<dnstyle>[,<modifier>]]=<DN>
+	realdnattr=<attrname>
+
 	group[/<objectclass>[/<attrname>]]
 		[.<groupstyle>]=<group>
 	peername[.<peernamestyle>]=<peername>
@@ -247,20 +315,22 @@ It can have the forms
 	tls_ssf=<n>
 	sasl_ssf=<n>
 
-	aci=<attrname>
+	dynacl/<name>[/<options>][.<dynstyle>][=<pattern>]
 .fi
 .LP
 with
 .LP
 .nf
 	<style>={exact|regex|expand}
+	<selfstyle>={level{<n>}}
 	<dnstyle>={{exact|base(object)}|regex
-		|one(level)|sub(tree)|children}
+		|one(level)|sub(tree)|children|level{<n>}}
 	<groupstyle>={exact|expand}
-	<peernamestyle>={<style>|ip|path}
+	<peernamestyle>={<style>|ip|ipv6|path}
 	<domainstyle>={exact|regex|sub(tree)}
-	<setstyle>={exact|regex}
+	<setstyle>={exact|expand}
 	<modifier>={expand}
+	<name>=aci		<pattern>=<attrname>]
 .fi
 .LP
 They may be specified in combination.
@@ -272,6 +342,11 @@ The wildcard
 .B *
 refers to everybody.
 .LP
+The keywords prefixed by
+.B real
+act as their counterparts without prefix; the checking respectively occurs
+with the \fIauthentication\fP DN and the \fIauthorization\fP DN.
+.LP
 The keyword
 .B anonymous
 means access is granted to unauthenticated clients; it is mostly used 
@@ -287,6 +362,18 @@ The keyword
 .B self
 means access to an entry is allowed to the entry itself (e.g. the entry
 being accessed and the requesting entry must be the same).
+It allows the 
+.B level{<n>}
+style, where \fI<n>\fP indicates what ancestor of the DN 
+is to be used in matches.
+A positive value indicates that the <n>-th ancestor of the user's DN
+is to be considered; a negative value indicates that the <n>-th ancestor
+of the target is to be considered.
+For example, a "\fIby self.level{1} ...\fP" clause would match
+when the object "\fIdc=example,dc=com\fP" is accessed
+by "\fIcn=User,dc=example,dc=com\fP".
+A "\fIby self.level{-1} ...\fP" clause would match when the same user
+accesses the object "\fIou=Address Book,cn=User,dc=example,dc=com\fP".
 .LP
 The statement
 .B dn=<DN>
@@ -307,6 +394,10 @@ ranging from 0 to 9 (where 0 matches the entire string),
 or the form
 .BR ${<digit>+} ,
 for submatches higher than 9.
+Substring substitution from attribute value can
+be done in 
+using the form
+.BR ${v<digit>+} .
 Since the dollar character is used to indicate a substring replacement,
 the dollar character that is used to indicate match up to the end of
 the string must be escaped by a second dollar character, e.g.
@@ -361,7 +452,7 @@ the
 the
 .BR one(level) ,
 and the
-.B children
+.BR children
 forms provide
 .B $0
 as the match of the entire string.
@@ -370,7 +461,7 @@ The
 the
 .BR one(level) ,
 and the
-.B children
+.BR children
 forms also provide
 .B $1
 as the match of the rightmost part of the DN as defined in the
@@ -388,6 +479,14 @@ which means that only access to entries that appear in the DN of the
 .B <by>
 clause is allowed.
 .LP
+The 
+.BR level{<n>}
+form is an extension and a generalization of the
+.BR onelevel
+form, which matches all DNs whose <n>-th ancestor is the pattern.
+So, \fIlevel{1}\fP is equivalent to \fIonelevel\fP, 
+and \fIlevel{0}\fP is equivalent to \fIbase\fP.
+.LP
 It is perfectly useless to give any access privileges to a DN 
 that exactly matches the
 .B rootdn
@@ -414,6 +513,11 @@ The optional parameters
 and
 .B <attrname>
 define the objectClass and the member attributeType of the group entry.
+The defaults are
+.B groupOfNames
+and
+.BR member ,
+respectively.
 The optional style qualifier
 .B <style>
 can be
@@ -457,7 +561,10 @@ The statements
 and
 .BR sockurl=<sockurl>
 mean that the contacting host IP (in the form 
-.BR "IP=<ip>:<port>" )
+.BR "IP=<ip>:<port>"
+for IPv4, or
+.BR "IP=[<ipv6>]:<port>"
+for IPv6)
 or the contacting host named pipe file name (in the form
 .B "PATH=<path>"
 if connecting through a named pipe) for
@@ -506,6 +613,9 @@ and
 are dotted digit representations of the IP and the mask, while
 .BR <n> ,
 delimited by curly brackets, is an optional port.
+The same applies to IPv6 addresses when the special
+.B ipv6
+style is used.
 When checking access privileges, the IP portion of the
 .BR peername 
 is extracted, eliminating the
@@ -515,10 +625,13 @@ prefix and the
 part, and it is compared against the
 .B <ip>
 portion of the pattern after masking with
-.BR <mask> .
+.BR <mask> :
+\fI((peername & <mask>) == <ip>)\fP.
 As an example, 
 .B peername.ip=127.0.0.1
-allows connections only from localhost,
+and
+.B peername.ipv6=::1
+allow connections only from localhost,
 .B peername.ip=192.168.1.0%255.255.255.0 
 allows connections from any IP in the 192.168.1 class C domain, and
 .B peername.ip=192.168.1.16%255.255.255.240{9009}
@@ -581,10 +694,32 @@ The statement
 is undocumented yet.
 .LP
 The statement
-.B aci=<attrname>
+.B dynacl/<name>[/<options>][.<dynstyle>][=<pattern>]
+means that access checking is delegated to the admin-defined method
+indicated by
+.BR <name> ,
+which can be registered at run-time by means of the
+.B moduleload
+statement.
+The fields
+.BR <options> ,
+.B <dynstyle>
+and
+.B <pattern>
+are optional, and are directly passed to the registered parsing routine.
+Dynacl is experimental; it must be enabled at compile time.
+.LP
+The statement
+.B dynacl/aci[=<attrname>]
 means that the access control is determined by the values in the
 .B attrname
 of the entry itself.
+The optional
+.B <attrname>
+indicates what attributeType holds the ACI information in the entry.
+By default, the 
+.B OpenLDAPaci
+operational attribute is used.
 ACIs are experimental; they must be enabled at compile time.
 .LP
 The statements
@@ -596,16 +731,16 @@ and
 set the minimum required Security Strength Factor (ssf) needed
 to grant access.  The value should be positive integer.
 .SH THE <ACCESS> FIELD
-The field
-.B <access> ::= [self]{<level>|<priv>}
+The optional field
+.B <access> ::= [[real]self]{<level>|<priv>}
 determines the access level or the specific access privileges the
 .B who 
 field will have.
 Its component are defined as
 .LP
 .nf
-	<level> ::= none|auth|compare|search|read|write
-	<priv> ::= {=|+|-}{w|r|s|c|x|0}+
+	<level> ::= none|disclose|auth|compare|search|read|{write|add|delete}|manage
+	<priv> ::= {=|+|\-}{0|d|x|c|s|r|{w|a|z}|m}+
 .fi
 .LP
 The modifier
@@ -613,11 +748,17 @@ The modifier
 allows special operations like having a certain access level or privilege
 only in case the operation involves the name of the user that's requesting
 the access.
-It implies the user that requests access is bound.
+It implies the user that requests access is authorized.
+The modifier
+.B realself
+refers to the authenticated DN as opposed to the authorized DN of the
+.B self
+modifier.
 An example is the
 .B selfwrite
 access to the member attribute of a group, which allows one to add/delete
-its own DN from the member list of a group, without affecting other members.
+its own DN from the member list of a group, while being not allowed
+to affect other members.
 .LP
 The 
 .B level 
@@ -625,20 +766,39 @@ access model relies on an incremental interpretation of the access
 privileges.
 The possible levels are
 .BR none ,
+.BR disclose ,
 .BR auth ,
 .BR compare ,
 .BR search ,
 .BR read ,
+.BR write ,
 and
-.BR write .
+.BR manage .
 Each access level implies all the preceding ones, thus 
-.B write
-access will imply all accesses.
-While
-.B none
-is trivial, 
+.B manage
+grants all access including administrative access.
+The 
+.BR write
+access is actually the combination of
+.BR add
+and
+.BR delete ,
+which respectively restrict the write privilege to add or delete
+the specified
+.BR <what> .
+
+.LP
+The
+.B none 
+access level disallows all access including disclosure on error.
+.LP
+The
+.B disclose
+access level allows disclosure of information on error.
+.LP
+The 
 .B auth
-access means that one is allowed access to an attribute to perform
+access level means that one is allowed access to an attribute to perform
 authentication/authorization operations (e.g.
 .BR bind )
 with no other access.
@@ -656,23 +816,38 @@ access privileges will be only those defined by the clause.
 The 
 .B +
 and
-.B -
+.B \-
 signs add/remove access privileges to the existing ones.
 The privileges are
+.B m
+for manage,
 .B w
 for write,
+.B a
+for add,
+.B z
+for delete,
 .B r
 for read,
 .B s 
 for search,
 .B c 
-for compare, and
+for compare,
 .B x
-for authentication.
+for authentication, and
+.B d
+for disclose.
 More than one of the above privileges can be added in one statement.
 .B 0
 indicates no privileges and is used only by itself (e.g., +0).
-.LP
+Note that
+.B +az
+is equivalent to
+.BR +w .
+.LP
+If no access is given, it defaults to 
+.BR +0 .
+.SH THE <CONTROL> FIELD
 The optional field
 .B <control>
 controls the flow of access rule application.
@@ -723,23 +898,58 @@ or the (even more silly) example
 .LP
 which grants everybody search and compare privileges, and adds read
 privileges to authenticated clients.
+.LP
+One useful application is to easily grant write privileges to an
+.B updatedn
+that is different from the
+.BR rootdn .
+In this case, since the
+.B updatedn
+needs write access to (almost) all data, one can use
+.LP
+.nf
+	access to *
+		by dn.exact="cn=The Update DN,dc=example,dc=com" write
+		by * break
+.fi
+.LP
+as the first access rule.
+As a consequence, unless the operation is performed with the 
+.B updatedn
+identity, control is passed straight to the subsequent rules.
+
 .SH OPERATION REQUIREMENTS
 Operations require different privileges on different portions of entries.
 The following summary applies to primary database backends such as
-the LDBM, BDB, and HDB backends.   Requirements for other backends may
+the BDB and HDB backends.   Requirements for other backends may
 (and often do) differ.
+
 .LP
 The
 .B add
 operation requires
-.B write (=w)
+.B add (=a)
 privileges on the pseudo-attribute 
 .B entry
 of the entry being added, and 
-.B write (=w)
+.B add (=a)
 privileges on the pseudo-attribute
 .B children
 of the entry's parent.
+When adding the suffix entry of a database,
+.B add
+access to
+.B children
+of the empty DN ("") is required. Also if
+Add content ACL checking has been configured on
+the database (see the
+.BR slapd.conf (5)
+or
+.BR slapd\-config (5)
+manual page),
+.B add (=a)
+will be required on all of the attributes being added.
+
 .LP
 The 
 .B bind
@@ -747,30 +957,46 @@ operation, when credentials are stored in the directory, requires
 .B auth (=x)
 privileges on the attribute the credentials are stored in (usually
 .BR userPassword ).
+
 .LP
 The
 .B compare
 operation requires 
 .B compare (=c)
 privileges on the attribute that is being compared.
+
 .LP
 The
 .B delete
 operation requires
-.B write (=w)
+.B delete (=z)
 privileges on the pseudo-attribute
 .B entry 
 of the entry being deleted, and
-.B write (=w)
+.B delete (=d)
 privileges on the
 .B children
 pseudo-attribute of the entry's parent.
+
 .LP
 The
 .B modify
 operation requires 
 .B write (=w)
-privileges on the attibutes being modified.
+privileges on the attributes being modified.
+In detail, 
+.B add (=a)
+is required to add new values,
+.B delete (=z)
+is required to delete existing values,
+and both
+.B delete
+and
+.BR "add (=az)" ,
+or
+.BR "write (=w)" ,
+are required to replace existing values.
+
 .LP
 The
 .B modrdn
@@ -779,24 +1005,35 @@ operation requires
 privileges on the pseudo-attribute
 .B entry
 of the entry whose relative DN is being modified,
-.B write (=w)
+.B delete (=z)
 privileges on the pseudo-attribute
 .B children
-of the old and new entry's parents, and
-.B write (=w)
+of the old entry's parents,
+.B add (=a)
+privileges on the pseudo-attribute
+.B children
+of the new entry's parents, and
+.B add (=a)
 privileges on the attributes that are present in the new relative DN.
-.B Write (=w)
+.B Delete (=z)
 privileges are also required on the attributes that are present 
 in the old relative DN if 
 .B deleteoldrdn
 is set to 1.
+
 .LP
 The
 .B search
-operation, for each entry, requires
+operation, requires 
+.B search (=s)
+privileges on the 
+.B entry
+pseudo-attribute of the searchBase
+(NOTE: this was introduced with OpenLDAP 2.4).
+Then, for each entry, it requires
 .B search (=s)
 privileges on the attributes that are defined in the filter.
-Then, the resulting entries are tested for 
+The resulting entries are finally tested for 
 .B read (=r)
 privileges on the pseudo-attribute
 .B entry
@@ -817,6 +1054,7 @@ access to the attribute holding the referral information
 (generally the
 .B ref
 attribute).
+
 .LP
 Some internal operations and some
 .B controls
@@ -837,6 +1075,26 @@ privileges are also required on the
 attribute of the authorizing identity and/or on the 
 .B authzFrom
 attribute of the authorized identity.
+In general, when an internal lookup is performed for authentication
+or authorization purposes, search-specific privileges (see the access
+requirements for the search operation illustrated above) are relaxed to
+.BR auth .
+
+.LP
+Access control to search entries is checked by the frontend,
+so it is fully honored by all backends; for all other operations
+and for the discovery phase of the search operation,
+full ACL semantics is only supported by the primary backends, i.e.
+.BR back\-bdb (5),
+and
+.BR back\-hdb (5).
+
+Some other backend, like
+.BR back\-sql (5),
+may fully support them; others may only support a portion of the 
+described semantics, or even differ in some aspects.
+The relevant details are described in the backend-specific man pages.
+
 .SH CAVEATS
 It is strongly recommended to explicitly use the most appropriate
 .B <dnstyle>
@@ -845,7 +1103,7 @@ in
 and
 .B <who>
 clauses, to avoid possible incorrect specifications of the access rules 
-as well as for performance (avoid unrequired regex matching when an exact
+as well as for performance (avoid unnecessary regex matching when an exact
 match suffices) reasons.
 .LP
 An administrator might create a rule of the form:
@@ -915,13 +1173,11 @@ ETCDIR/slapd.conf
 default slapd configuration file
 .SH SEE ALSO
 .BR slapd (8),
+.BR slapd\-* (5),
 .BR slapacl (8),
 .BR regex (7),
 .BR re_format (7)
 .LP
 "OpenLDAP Administrator's Guide" (http://www.OpenLDAP.org/doc/admin/)
 .SH ACKNOWLEDGEMENTS
-.B OpenLDAP
-is developed and maintained by The OpenLDAP Project (http://www.openldap.org/).
-.B OpenLDAP
-is derived from University of Michigan LDAP 3.3 Release.
+.so ../Project