dsdb-acls: Add documentation

Add documentation on ACLs.

diff --git a/source4/dsdb/samdb/ldb_modules/acl_util.c b/source4/dsdb/samdb/ldb_modules/acl_util.c
index 1f64ab18658621db220483aff31abfea70342015..bc2a8f0704f535db619e8f4e22ade4c6475a16a0 100644 (file)
--- a/source4/dsdb/samdb/ldb_modules/acl_util.c
+++ b/source4/dsdb/samdb/ldb_modules/acl_util.c
@@ -91,6 +91,38 @@ int dsdb_module_check_access_on_dn(struct ldb_module *module,
                                                guid);
 }
 
+/**
+ * @brief Checks the current as the requested access on 1 attribute
+ *
+ * This function checks if a given trustee has the requested access
+ * on the specified attribute given the current security descriptor.
+ * The attribute can be NULL in this case the check will skip the
+ * OBJECT_ACE entries.
+ *
+ * @param[in]  module      A struct ldb_module object, security token
+ *                         for the current user are stored within the
+ *                         module object.
+ *
+ * @param[in]  mem_ctx     A talloc context object for memory allocation
+ *
+ * @param[in]  sd          A security descriptor for attr
+ *
+ * @param[in]  rp_sid      The SID of the domain, used for expanding
+ *                         trustee in ACE that are just a RID.
+ *
+ * @param[in]  access_mask An integer that represents the desired access
+ *                         that the security descriptor should grant to
+ *                         the user on the given attribute
+ *
+ * @param[in]  attr        A dsdb_attribute for which the checks should be
+ *                         performed.
+ *
+ * @return                 Returns LDB_SUCCESS on success, on error another
+ *                         ldb error code.
+ *                         If the requested rights are not granted
+ *                         LDB_ERR_INSUFFICIENT_ACCESS_RIGHTS will be returned.
+ *
+ */
 int acl_check_access_on_attribute(struct ldb_module *module,
                                  TALLOC_CTX *mem_ctx,
                                  struct security_descriptor *sd,
@@ -191,7 +223,33 @@ fail:
        return ldb_operr(ldb_module_get_ctx(module));
 }
 
-/* checks for validated writes */
+/**
+ * @brief Checks if a given extended right grants the desired access for a given user
+ *
+ * This function checks if a given user is granted the specified extended right
+ * with the requested access right.
+ *
+ * @param[in]  mem_ctx     A talloc context object for memory allocation
+ *
+ * @param[in]  sd          A security descriptor for attr
+ *
+ * @param[in]  token       The security token reprensenting the user
+ *
+ * @param[in]  ext_right   A string representation of the GUID of the extended
+ *                         right to test.
+ *
+ * @param[in]  right_typ   An integer that represents the desired access
+ *                         that the security descriptor should grant to
+ *                         the user for the specified extended access right
+ *
+ * @param[in]  dom_sid     The SID of the domain, used for expanding
+ *                         trustee in ACE that are just a RID.
+ *
+ * @return                 Returns LDB_SUCCESS on success, on error another
+ *                         ldb error code.
+ *                         If the requested rights are not granted
+ *                         LDB_ERR_INSUFFICIENT_ACCESS_RIGHTS will be returned.
+ */
 int acl_check_extended_right(TALLOC_CTX *mem_ctx,
                             struct security_descriptor *sd,
                             struct security_token *token,