ITS#5555 - Correct documentation for SASL AuthzTo Check

This patch file is derived from OpenLDAP Software. All of the
modifications to OpenLDAP Software represented in the following patch(es)
were developed by Andrew Findlay <andrew.findlay@skills-1st.co.uk>.
I have not assigned rights and/or interest in this work to any party.

I, Andrew Findlay, hereby place the following modifications to OpenLDAP
Software (and only these modifications) into the public domain. Hence,
these modifications may be freely used and/or redistributed for any
purpose with or without attribution and/or other notice.

doc/guide/admin/access-control.sdf

@@ -852,6 +852,50 @@ The ACLs above will only allow binding using rootdn from localhost and
 192.168.0.0/24.
 
 
+H3: Controlling the LDAP Proxied Authorization Control
+
+The Proxied Authorization Control allows a client to request that an
+operation be processed under a provided authorization identity instead of
+under the current authentication identity associated with the connection.
+
+This facility is controlled by the {{EX:authz-policy}} configuration
+option and by the {{EX:authzTo}} and {{EX:authzFrom}} attributes.
+It can be further controlled by applying access control to those attributes.
+
+A client application might bind as cn=Client,o=MyOrganization whose entry
+looks like this:
+
+>    dn: cn=Client,o=MyOrganization
+>    cn: Client
+>    objectClass: organizationalRole
+>    objectClass: simpleSecurityObject
+>    objectClass: top
+>    userPassword: {SSHA}someSSHAdata
+>    authzTo: dn.regex:^cn=[^,]+,ou=People,o=MyOrganization$
+
+To make use of the proxy facility, the client needs at least {{EX:auth}}
+privilege on the {{EX:authzTo}} attribute:
+
+>    access to dn.exact=cn=Client,o=MyOrganization attr=authzTo
+>      by self auth
+>      by * break
+
+This access would be automatically granted if cn=Client,o=MyOrganization
+has {{EX:read}} privilege on its own entry.
+
+Now if you want to lock down the use of this powerful account, you might
+write an ACL like this:
+
+>    access to dn.exact=cn=Client,o=MyOrganization attr=authzTo
+>      by self peername.regex=192\.168\.0\..*  ssf=256 auth
+>      by * none
+
+Now, cn=Client,o=MyOrganization can only make use of the proxy authorization
+control if it has connected from an appropriate IP address using
+a sufficient level of cryptographic protection. No other IDs can even
+see the authzTo attribute.
+
+
 H3: Managing access with Groups
 
 There are a few ways to do this. One approach is illustrated here. Consider the

doc/guide/admin/sasl.sdf

@@ -560,6 +560,9 @@ into the LDAP database entries. By default, the authorization
 features are disabled, and must be explicitly configured by the
 LDAP administrator before use.
 
+The rules governing proxy authorization are not just used for SASL:
+they also control the use of the LDAP Proxied Authorization Control
+(RFC 4370).
 
 H3: Uses of Proxy Authorization
 
@@ -739,3 +742,18 @@ as anyone else.  As such, when using source rules, the
 {{EX:authzTo}} attribute should be protected with an ACL that
 only allows privileged users to set its values.
 
+H4: Access Control requirements
+
+When checking whether a particular DN may authorize as another DN,
+the server applies access control rules to the {{EX:authzTo}} and
+{{EX:authzFrom}} attributes. The {{EX:auth}} privilege is required
+for an attribute to be used.
+
+For example, suppose Alice has authenticated using her own ID and password,
+and wants to perform an LDAP operation using Bob's permissions.
+If authorization is granted by an {{EX:authzTo}} attribute in Alice's
+entry then Alice needs the {{EX:auth}} privilege on that attribute.
+Similarly, if authorization is granted by an {{EX:authzFrom}} attribute
+in Bob's entry then Alice needs the {{EX:auth}} privilege on that.
+Alice does not need any other access privilege to do a proxy operation.
+

doc/man/man5/slapd.access.5

@@ -1083,9 +1083,11 @@ attribute).
 Some internal operations and some
 .B controls
 require specific access privileges.
-The
+
+.LP
+The SASL
 .B authzID
-mapping and the 
+mapping and the LDAP
 .B proxyAuthz
 control require
 .B auth (=x)
@@ -1099,6 +1101,11 @@ privileges are also required on the
 attribute of the authorizing identity and/or on the 
 .B authzFrom
 attribute of the authorized identity.
+In both cases, it is the authorizing identity that requires the privileges
+(i.e. the identity that has authenticated and is now trying to do
+some operation using another entity's permissions).
+
+.LP
 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