CR-7441 OPENDJ-2137 Document actual global ACIs

Mark Craig

30.08.2015 484b7f0d0bcbfb88967257eb6748e1421bc26bb0

CR-7441 OPENDJ-2137 Document actual global ACIs

This patch generates a table of default global ACIs from the source,
so as to ensure that the docs are current with respect to the code.

 opendj-sdk/opendj-doc-maven-plugin/src/main/java/org/forgerock/opendj/maven/doc/GenerateGlobalAcisTableMojo.java

New file
@@ -0,0 +1,164 @@
/*
 * CDDL HEADER START
 *
 * The contents of this file are subject to the terms of the
 * Common Development and Distribution License, Version 1.0 only
 * (the "License").  You may not use this file except in compliance
 * with the License.
 *
 * You can obtain a copy of the license at legal-notices/CDDLv1_0.txt
 * or http://forgerock.org/license/CDDLv1.0.html.
 * See the License for the specific language governing permissions
 * and limitations under the License.
 *
 * When distributing Covered Code, include this CDDL HEADER in each
 * file and include the License file at legal-notices/CDDLv1_0.txt.
 * If applicable, add the following below this CDDL HEADER, with the
 * fields enclosed by brackets "[]" replaced with your own identifying
 * information:
 *      Portions Copyright [yyyy] [name of copyright owner]
 *
 * CDDL HEADER END
 *
 *      Copyright 2015 ForgeRock AS.
 */
package org.forgerock.opendj.maven.doc;

import static org.forgerock.opendj.maven.doc.DocsMessages.*;
import static org.forgerock.opendj.maven.doc.Utils.applyTemplate;
import static org.forgerock.opendj.maven.doc.Utils.writeStringToFile;
import org.apache.maven.plugin.AbstractMojo;
import org.apache.maven.plugin.MojoExecutionException;
import org.apache.maven.plugin.MojoFailureException;
import org.apache.maven.plugins.annotations.Mojo;
import org.apache.maven.plugins.annotations.Parameter;
import org.forgerock.opendj.ldap.DN;
import org.forgerock.opendj.ldap.Entry;
import org.forgerock.opendj.ldif.LDIFEntryReader;

import java.io.File;
import java.io.FileInputStream;
import java.io.IOException;
import java.text.SimpleDateFormat;
import java.util.Date;
import java.util.HashMap;
import java.util.LinkedList;
import java.util.List;
import java.util.Map;
import java.util.regex.Matcher;
import java.util.regex.Pattern;

/**
 * Generates documentation source table listing global ACIs.
 */
@Mojo(name = "generate-global-acis-table")
public class GenerateGlobalAcisTableMojo extends AbstractMojo {
    /** The locale for which to generate the documentation. */
    @Parameter(defaultValue = "en")
    private String locale;

    /** The config.ldif file containing default global ACIs. **/
    @Parameter(defaultValue = "${basedir}/resource/config/config.ldif")
    private File configDotLdif;

    /** Output directory for source files. */
    @Parameter(defaultValue = "${project.build.directory}/docbkx-sources/shared")
    private File outputDirectory;

    /** Holds documentation for an ACI. */
    private class Aci {
        String description;
        String definition;
    }

    /** Holds the list of global ACIs. */
    private static List<Aci> allGlobalAcis = new LinkedList<>();

    /**
     * Writes documentation source table listing global ACIs.
     * @throws MojoExecutionException   Not used.
     * @throws MojoFailureException     Failed to read ACIs or to write the table file.
     */
    @Override
    public void execute() throws MojoExecutionException, MojoFailureException {
        try {
            readAcis();
        } catch (IOException e) {
            throw new MojoFailureException(e.getMessage(), e);
        }

        File table = new File(outputDirectory, "table-global-acis.xml");
        try {
            writeStringToFile(getGlobalAcisTable(), table);
        } catch (IOException e) {
            throw new MojoFailureException(e.getMessage(), e);
        }
    }

    /**
     * Reads {@code ds-cfg-global-aci} values from {@code config.ldif} into the list of Acis.
     * @throws IOException  Failed to read the LDIF.
     */
    private void readAcis() throws IOException {
        LDIFEntryReader reader = new LDIFEntryReader(new FileInputStream(configDotLdif));
        reader.setIncludeBranch(DN.valueOf("cn=Access Control Handler,cn=config"));

        while (reader.hasNext()) {
            Entry entry = reader.readEntry();
            for (String attribute : entry.parseAttribute("ds-cfg-global-aci").asSetOfString()) {
                Aci aci = new Aci();
                aci.description = getDescription(attribute);
                aci.definition = attribute;
                allGlobalAcis.add(aci);
            }
        }
    }

    /**
     * Returns a DocBook XML table listing global ACIs.
     * @return A DocBook XML table listing global ACIs.
     */
    private String getGlobalAcisTable() {
        final Map<String, Object> map = new HashMap<>();
        map.put("year", new SimpleDateFormat("yyyy").format(new Date()));
        map.put("lang", locale);
        map.put("title", DOC_GLOBAL_ACIS_TABLE_TITLE.get());
        map.put("summary", DOC_GLOBAL_ACIS_TABLE_SUMMARY.get());
        map.put("descTitle", DOC_GLOBAL_ACIS_DESCRIPTION_COLUMN_TITLE.get());
        map.put("defTitle", DOC_GLOBAL_ACIS_DEFINITION_COLUMN_TITLE.get());
        map.put("acis", getDefaultGlobalAciList());
        return applyTemplate("table-global-acis.ftl", map);
    }

    /**
     * Returns a list of information about default global ACIs.
     * @return A list of information about default global ACIs.
     */
    private List<Map<String, Object>> getDefaultGlobalAciList() {
        final List<Map<String, Object>> globalAciList = new LinkedList<>();
        for (final Aci aci : allGlobalAcis) {
            final Map<String, Object> map = new HashMap<>();
            map.put("description", aci.description);
            map.put("definition", aci.definition);
            globalAciList.add(map);
        }
        return globalAciList;
    }

    /**
     * Returns the user-friendly description embedded in the ACI.
     * @param aci   The string representation of the ACI value.
     * @return  The user-friendly description embedded in the ACI,
     *          or an empty string if no description is found.
     */
    private String getDescription(String aci) {
        // Extract the user-friendly string in 
        // {@code ...version 3.0; acl "user-friendly string"...}.
        Pattern pattern = Pattern.compile(".+version 3.0; ?acl \"([^\"]+)\".+");
        Matcher matcher = pattern.matcher(aci);
        if (matcher.find()) {
            return matcher.group(1);
        }
        return "";
    }
}

 opendj-sdk/opendj-doc-maven-plugin/src/main/resources/org/forgerock/opendj/maven/doc/docs.properties

@@ -74,3 +74,9 @@
  such as those logged in                                       \
  <filename>/path/to/opendj/logs/errors</filename>, and         \
  <filename>/path/to/opendj/logs/replication</filename>.

DOC_GLOBAL_ACIS_TABLE_TITLE=Default Global ACIs
DOC_GLOBAL_ACIS_TABLE_SUMMARY=OpenDJ directory server defines \
  the following global ACIs by default.
DOC_GLOBAL_ACIS_DESCRIPTION_COLUMN_TITLE=Description
DOC_GLOBAL_ACIS_DEFINITION_COLUMN_TITLE=ACI Definition

 opendj-sdk/opendj-doc-maven-plugin/src/main/resources/templates/table-global-acis.ftl

New file
@@ -0,0 +1,63 @@
<?xml version="1.0" encoding="UTF-8"?>
<!--
  ! CCPL HEADER START
  !
  ! This work is licensed under the Creative Commons
  ! Attribution-NonCommercial-NoDerivs 3.0 Unported License.
  ! To view a copy of this license, visit
  ! http://creativecommons.org/licenses/by-nc-nd/3.0/
  ! or send a letter to Creative Commons, 444 Castro Street,
  ! Suite 900, Mountain View, California, 94041, USA.
  !
  ! You can also obtain a copy of the license at legal-notices/CC-BY-NC-ND.txt.
  ! See the License for the specific language governing permissions
  ! and limitations under the License.
  !
  ! If applicable, add the following below this CCPL HEADER, with the fields
  ! enclosed by brackets "[]" replaced with your own identifying information:
  !      Portions Copyright [yyyy] [name of copyright owner]
  !
  ! CCPL HEADER END
  !
  !      Copyright ${year} ForgeRock AS.
  !
-->
<table xml:id="table-global-acis"
       xmlns="http://docbook.org/ns/docbook" version="5.0" xml:lang="${lang}"
       xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
       xsi:schemaLocation="http://docbook.org/ns/docbook
                           http://docbook.org/xml/5.0/xsd/docbook.xsd"
       pgwide="1">
 <title>${title}</title>

 <textobject>
  <para>
   ${summary}
  </para>
 </textobject>

 <tgroup cols="2">
  <colspec colnum="1" colwidth="1*"/>
  <colspec colnum="2" colwidth="2*" />

  <thead>
   <row>
    <entry>${descTitle}</entry>
    <entry>${defTitle}</entry>
   </row>
  </thead>

  <tbody>
   <#list acis?sort_by("description") as aci>
   <row valign="top">
    <entry>
     ${aci.description}<!-- In English in config.ldif by default -->
    </entry>
    <entry>
     <literal>${aci.definition}</literal>
    </entry>
   </row>
   </#list>
  </tbody>
 </tgroup>
</table>

 opendj-sdk/opendj-server-legacy/pom.xml

@@ -1921,6 +1921,14 @@
              </execution>

              <execution>
                <id>generate-global-acis-table-for-doc</id>
                <phase>prepare-package</phase>
                <goals>
                  <goal>generate-global-acis-table</goal>
                </goals>
              </execution>

              <execution>
                <id>generate-schema-reference-doc</id>
                <phase>prepare-package</phase>
                <goals>

 opendj-sdk/opendj-server-legacy/src/main/docbkx/admin-guide/chap-privileges-acis.xml

@@ -27,7 +27,8 @@
         xmlns:xsi='http://www.w3.org/2001/XMLSchema-instance'
         xsi:schemaLocation='http://docbook.org/ns/docbook
                             http://docbook.org/xml/5.0/xsd/docbook.xsd'
         xmlns:xlink='http://www.w3.org/1999/xlink'>
         xmlns:xlink='http://www.w3.org/1999/xlink'
         xmlns:xinclude='http://www.w3.org/2001/XInclude'>
 <title>Configuring Privileges &amp; Access Control</title>

 <para>OpenDJ supports two mechanisms to protect access to the directory,
@@ -1161,35 +1162,13 @@
    <secondary>Data access</secondary>
   </indexterm>

  <itemizedlist>
   <para>Default global ACIs set up the following access rules.</para>
   <listitem>
    <para>Users can employ LDAP controls and perform extended operations.</para>
   </listitem>
   <listitem>
    <para>Anonymous read access is allowed for most user data attributes.</para>
   </listitem>
   <listitem>
    <para>Users can read password values on their own entries after binding.
    (Also by default, password values are hashed.)</para>
   </listitem>
   <listitem>
    <para>Anonymous read access is allowed for schema-related operational
    attributes.</para>
   </listitem>
   <listitem>
    <para>Anonymous read access is allowed for root DSE attributes describing
    what the server supports.</para>
   </listitem>
   <listitem>
    <para>Anonymous read access is allowed for operational attributes related
    to entry updates and entry identification.</para>
   </listitem>
   <listitem>
    <para>Access to replication data is denied.</para>
   </listitem>
  </itemizedlist>
  
  <!-- Include generated table of global ACIs -->
  <xinclude:include href="../shared/table-global-acis.xml">
   <xinclude:fallback>
    <para>Error: failed to include global ACI table</para>
   </xinclude:fallback>
  </xinclude:include>

  <para>Users with write access to add ACIs and with the
  <literal>modify-acl</literal> privilege can use the
  <command>ldapmodify</command> command to change ACIs located in user