Massive reST content rename

All of rst_source/ is now just in doc/.
The krb_ prefix is stripped from the document sub-directories.
rst_tools are now just tools.

The section headers of kadmind, krb5kdc, and sserver match as conflict markers.
bigredbutton: whitespace

ticket: 7409

10 files changed, 0 insertions, 473 deletions

diff --git a/doc/rst_source/krb_plugindev/ccselect.rst b/doc/rst_source/krb_plugindev/ccselect.rst
deleted file mode 100644
index 00133d944..000000000
--- a/doc/rst_source/krb_plugindev/ccselect.rst
+++ /dev/null
@@ -1,26 +0,0 @@
-Credential cache selection interface (ccselect)
-===============================================
-
-The ccselect interface allows modules to control how credential caches
-are chosen when a GSSAPI client contacts a service.  For a detailed
-description of the ccselect interface, see the header file
-``<krb5/ccselect_plugin.h>``.
-
-The primary ccselect method is **choose**, which accepts a server
-principal as input and returns a ccache and/or principal name as
-output.  A module can use the krb5_cccol APIs to iterate over the
-cache collection in order to find an appropriate ccache to use.
-
-.. TODO: add reference to the admin guide for ccaches and cache
-   collections when we have appropriate sections.
-
-A module can create and destroy per-library-context state objects by
-implementing the **init** and **fini** methods.  State objects have
-the type krb5_ccselect_moddata, which is an abstract pointer type.  A
-module should typically cast this to an internal type for the state
-object.
-
-A module can have one of two priorities, "authoritative" or
-"heuristic".  Results from authoritative modules, if any are
-available, will take priority over results from heuristic modules.  A
-module communicates its priority as a result of the **init** method.
diff --git a/doc/rst_source/krb_plugindev/clpreauth.rst b/doc/rst_source/krb_plugindev/clpreauth.rst
deleted file mode 100644
index 68e56aa5f..000000000
--- a/doc/rst_source/krb_plugindev/clpreauth.rst
+++ /dev/null
@@ -1,53 +0,0 @@
-Client preauthentication interface (clpreauth)
-==============================================
-
-During an initial ticket request, a KDC may ask a client to prove its
-knowledge of the password before issuing an encrypted ticket, or to
-use credentials other than a password.  This process is called
-preauthentication, and is described in :rfc:`4120` and :rfc:`6113`.
-The clpreauth interface allows the addition of client support for
-preauthentication mechanisms beyond those included in the core MIT
-krb5 code base.  For a detailed description of the clpreauth
-interface, see the header file ``<krb5/preauth_plugin.h>``.
-
-A clpreauth module is generally responsible for:
-
-* Supplying a list of preauth type numbers used by the module in the
-  **pa_type_list** field of the vtable structure.
-
-* Indicating what kind of preauthentication mechanism it implements,
-  with the **flags** method.  In the most common case, this method
-  just returns ``PA_REAL``, indicating that it implements a normal
-  preauthentication type.
-
-* Examining the padata information included in the preauth_required
-  error and producing padata values for the next AS request.  This is
-  done with the **process** method.
-
-* Examining the padata information included in a successful ticket
-  reply, possibly verifying the KDC identity and computing a reply
-  key.  This is also done with the **process** method.
-
-* For preauthentication types which support it, recovering from errors
-  by examining the error data from the KDC and producing a padata
-  value for another AS request.  This is done with the **tryagain**
-  method.
-
-* Receiving option information (supplied by ``kinit -X`` or by an
-  application), with the **gic_opts** method.
-
-A clpreauth module can create and destroy per-library-context and
-per-request state objects by implementing the **init**, **fini**,
-**request_init**, and **request_fini** methods.  Per-context state
-objects have the type krb5_clpreauth_moddata, and per-request state
-objects have the type krb5_clpreauth_modreq.  These are abstract
-pointer types; a module should typically cast these to internal
-types for the state objects.
-
-The **process** and **tryagain** methods have access to a callback
-function and handle (called a "rock") which can be used to get
-additional information about the current request, including the
-expected enctype of the AS reply, the FAST armor key, and the client
-long-term key (prompting for the user password if necessary).  A
-callback can also be used to replace the AS reply key if the
-preauthentication mechanism computes one.
diff --git a/doc/rst_source/krb_plugindev/general.rst b/doc/rst_source/krb_plugindev/general.rst
deleted file mode 100644
index dff680762..000000000
--- a/doc/rst_source/krb_plugindev/general.rst
+++ /dev/null
@@ -1,98 +0,0 @@
-General plugin concepts
-=======================
-
-A krb5 dynamic plugin module is a Unix shared object or Windows DLL.
-Typically, the source code for a dynamic plugin module should live in
-its own project with a build system using automake_ and libtool_, or
-tools with similar functionality.
-
-A plugin module must define a specific symbol name, which depends on
-the pluggable interface and module name.  For most pluggable
-interfaces, the exported symbol is a function named
-``INTERFACE_MODULE_initvt``, where *INTERFACE* is the name of the
-pluggable interface and *MODULE* is the name of the module.  For these
-interfaces, it is possible for one shared object or DLL to implement
-multiple plugin modules, either for the same pluggable interface or
-for different ones.  For example, a shared object could implement both
-KDC and client preauthentication mechanisms, by exporting functions
-named ``kdcpreauth_mymech_initvt`` and ``clpreauth_mymech_initvt``.
-
-.. note: The profile, locate, and GSSAPI mechglue pluggable interfaces
-         follow different conventions.  See the documentation for
-         those interfaces for details.  The remainder of this section
-         applies to pluggable interfaces which use the standard
-         conventions.
-
-A plugin module implementation should include the header file
-``<krb5/INTERFACE_plugin.h>``, where *INTERFACE* is the name of the
-pluggable interface.  For instance, a ccselect plugin module
-implementation should use ``#include <krb5/ccselect_plugin.h>``.
-
-.. note: clpreauth and kdcpreauth module implementations should
-         include <krb5/preauth_plugin.h>.
-
-initvt functions have the following prototype::
-
-    krb5_error_code interface_modname_initvt(krb5_context context,
-                                             int maj_ver, int min_ver,
-                                             krb5_plugin_vtable vtable);
-
-and should do the following:
-
-1. Check that the supplied maj_ver argument is supported by the
-   module.  If it is not supported, the function should return
-   KRB5_PLUGIN_VER_NOTSUPP.
-
-2. Cast the supplied vtable pointer to the structure type
-   corresponding to the major version, as documented in the pluggable
-   interface header file.
-
-3. Fill in the structure fields with pointers to method functions and
-   static data, stopping at the field indicated by the supplied minor
-   version.  Fields for unimplemented optional methods can be left
-   alone; it is not necessary to initialize them to NULL.
-
-In most cases, the context argument will not be used.  The initvt
-function should not allocate memory; think of it as a glorified
-structure initializer.  Each pluggable interface defines methods for
-allocating and freeing module state if doing so is necessary for the
-interface.
-
-Pluggable interfaces typically include a **name** field in the vtable
-structure, which should be filled in with a pointer to a string
-literal containing the module name.
-
-Here is an example of what an initvt function might look like for a
-fictional pluggable interface named fences, for a module named
-"wicker"::
-
-    krb5_error_code
-    fences_wicker_initvt(krb5_context context, int maj_ver,
-                         int min_ver, krb5_plugin_vtable vtable)
-    {
-        krb5_ccselect_vtable vt;
-
-        if (maj_ver == 1) {
-            krb5_fences_vtable vt = (krb5_fences_vtable)vtable;
-            vt->name = "wicker";
-            vt->slats = wicker_slats;
-            vt->braces = wicker_braces;
-        } else if (maj_ver == 2) {
-            krb5_fences_vtable_v2 vt = (krb5_fences_vtable_v2)vtable;
-            vt->name = "wicker";
-            vt->material = wicker_material;
-            vt->construction = wicker_construction;
-            if (min_ver < 2)
-                return 0;
-            vt->footing = wicker_footing;
-            if (min_ver < 3)
-                return 0;
-            vt->appearance = wicker_appearance;
-        } else {
-            return KRB5_PLUGIN_VER_NOTSUPP;
-        }
-        return 0;
-    }
-
-.. _automake: http://www.gnu.org/software/automake/
-.. _libtool: http://www.gnu.org/software/libtool/
diff --git a/doc/rst_source/krb_plugindev/index.rst b/doc/rst_source/krb_plugindev/index.rst
deleted file mode 100644
index e913810bb..000000000
--- a/doc/rst_source/krb_plugindev/index.rst
+++ /dev/null
@@ -1,32 +0,0 @@
-For plugin module developers
-============================
-
-Kerberos plugin modules allow increased control over MIT krb5 library
-and server behavior.  This guide describes how to create dynamic
-plugin modules and the currently available pluggable interfaces.
-
-See :ref:`plugin_config` for information on how to register dynamic
-plugin modules and how to enable and disable modules via
-:ref:`krb5.conf(5)`.
-
-.. TODO: update the above reference when we have a free-form section
-   in the admin guide about plugin configuration
-
-
-Contents
---------
-
-.. toctree::
-   :maxdepth: 2
-
-   general.rst
-   clpreauth.rst
-   kdcpreauth.rst
-   ccselect.rst
-   pwqual.rst
-   kadm5_hook.rst
-   locate.rst
-   profile.rst
-   internal.rst
-
-.. TODO: GSSAPI mechanism plugins
diff --git a/doc/rst_source/krb_plugindev/internal.rst b/doc/rst_source/krb_plugindev/internal.rst
deleted file mode 100644
index 99e30bb79..000000000
--- a/doc/rst_source/krb_plugindev/internal.rst
+++ /dev/null
@@ -1,32 +0,0 @@
-Internal pluggable interfaces
-=============================
-
-Following are brief discussions of pluggable interfaces which have not
-yet been made public.  These interfaces are functional, but the
-interfaces are likely to change in incompatible ways from release to
-release.  In some cases, it may be necessary to copy header files from
-the krb5 source tree to use an internal interface.  Use these with
-care, and expect to need to update your modules for each new release
-of MIT krb5.
-
-
-Kerberos database interface (KDB)
----------------------------------
-
-A KDB module implements a database back end for KDC principal and
-policy information, and can also control many aspects of KDC behavior.
-For a full description of the interface, see the header file
-``<kdb.h>``.
-
-The KDB pluggable interface is often referred to as the DAL (Database
-Access Layer).
-
-
-Authorization data interface (authdata)
----------------------------------------
-
-The authdata interface allows a module to provide (from the KDC) or
-consume (in application servers) authorization data of types beyond
-those handled by the core MIT krb5 code base.  The interface is
-defined in the header file ``<krb5/authdata_plugin.h>``, which is not
-installed by the build.
diff --git a/doc/rst_source/krb_plugindev/kadm5_hook.rst b/doc/rst_source/krb_plugindev/kadm5_hook.rst
deleted file mode 100644
index 01d330e8e..000000000
--- a/doc/rst_source/krb_plugindev/kadm5_hook.rst
+++ /dev/null
@@ -1,24 +0,0 @@
-KADM5 hook interface (kadm5_hook)
-=================================
-
-The kadm5_hook interface allows modules to perform actions when
-changes are made to the Kerberos database through :ref:`kadmin(1)`.
-For a detailed description of the kadm5_hook interface, see the header
-file ``<krb5/kadm5_hook_plugin.h>``.
-
-The kadm5_hook interface has four primary methods: **chpass**,
-**create**, **modify**, and **remove**.  Each of these methods is
-called twice when the corresponding administrative action takes place,
-once before the action is committed and once afterwards.  A module can
-prevent the action from taking place by returning an error code during
-the pre-commit stage.
-
-A module can create and destroy per-process state objects by
-implementing the **init** and **fini** methods.  State objects have
-the type kadm5_hook_modinfo, which is an abstract pointer type.  A
-module should typically cast this to an internal type for the state
-object.
-
-Because the kadm5_hook interface is tied closely to the kadmin
-interface (which is explicitly unstable), it may not remain as stable
-across versions as other public pluggable interfaces.
diff --git a/doc/rst_source/krb_plugindev/kdcpreauth.rst b/doc/rst_source/krb_plugindev/kdcpreauth.rst
deleted file mode 100644
index e6ba9e531..000000000
--- a/doc/rst_source/krb_plugindev/kdcpreauth.rst
+++ /dev/null
@@ -1,61 +0,0 @@
-KDC preauthentication interface (kdcpreauth)
-============================================
-
-The kdcpreauth interface allows the addition of KDC support for
-preauthentication mechanisms beyond those included in the core MIT
-krb5 code base.  For a detailed description of the kdcpreauth
-interface, see the header file ``<krb5/preauth_plugin.h>``.
-
-A kdcpreauth module is generally responsible for:
-
-* Supplying a list of preauth type numbers used by the module in the
-  **pa_type_list** field of the vtable structure.
-
-* Indicating what kind of preauthentication mechanism it implements,
-  with the **flags** method.  If the mechanism computes a new reply
-  key, it must specify the ``PA_REPLACES_KEY`` flag.  If the mechanism
-  is generally only used with hardware tokens, the ``PA_HARDWARE``
-  flag allows the mechanism to work with principals which have the
-  **requires_hwauth** flag set.
-
-* Producing a padata value to be sent with a preauth_required error,
-  with the **edata** method.
-
-* Examining a padata value sent by a client and verifying that it
-  proves knowledge of the appropriate client credential information.
-  This is done with the **verify** method.
-
-* Producing a padata response value for the client, and possibly
-  computing a reply key.  This is done with the **return_padata**
-  method.
-
-A module can create and destroy per-KDC state objects by implementing
-the **init** and **fini** methods.  Per-KDC state objects have the
-type krb5_kdcpreauth_moddata, which is an abstract pointer types.  A
-module should typically cast this to an internal type for the state
-object.
-
-A module can create a per-request state object by returning one in the
-**verify** method, receiving it in the **return_padata** method, and
-destroying it in the **free_modreq** method.  Note that these state
-objects only apply to the processing of a single AS request packet,
-not to an entire authentication exchange (since an authentication
-exchange may remain unfinished by the client or may involve multiple
-different KDC hosts).  Per-request state objects have the type
-krb5_kdcpreauth_modreq, which is an abstract pointer type.
-
-The **edata**, **verify**, and **return_padata** methods have access
-to a callback function and handle (called a "rock") which can be used
-to get additional information about the current request, including the
-maximum allowable clock skew, the client's long-term keys, the
-DER-encoded request body, the FAST armor key, string attributes on the
-client's database entry, and the client's database entry itself.
-
-The **edata** and **verify** methods can be implemented
-asynchronously.  Because of this, they do not return values directly
-to the caller, but must instead invoke responder functions with their
-results.  A synchronous implementation can invoke the responder
-function immediately.  An asynchronous implementation can use the
-callback to get an event context for use with the libverto_ API.
-
-.. _libverto: https://fedorahosted.org/libverto/
diff --git a/doc/rst_source/krb_plugindev/locate.rst b/doc/rst_source/krb_plugindev/locate.rst
deleted file mode 100644
index fca6a4da7..000000000
--- a/doc/rst_source/krb_plugindev/locate.rst
+++ /dev/null
@@ -1,32 +0,0 @@
-Server location interface (locate)
-==================================
-
-The locate interface allows modules to control how KDCs and similar
-services are located by clients.  For a detailed description of the
-ccselect interface, see the header file ``<krb5/locate_plugin.h>``.
-
-.. note: The locate interface does not follow the normal conventions
-         for MIT krb5 pluggable interfaces, because it was made public
-         before those conventions were established.
-
-A locate module exports a structure object of type
-krb5plugin_service_locate_ftable, with the name ``service_locator``.
-The structure contains a minor version and pointers to the module's
-methods.
-
-The primary locate method is **lookup**, which accepts a service type,
-realm name, desired socket type, and desired address family (which
-will be AF_UNSPEC if no specific address family is desired).  The
-method should invoke the callback function once for each server
-address it wants to return, passing a socket type (SOCK_STREAM for TCP
-or SOCK_DGRAM for UDP) and socket address.  The **lookup** method
-should return 0 if it has authoritatively determined the server
-addresses for the realm, KRB5_PLUGIN_NO_HANDLE if it wants to let
-other location mechanisms determine the server addresses, or another
-code if it experienced a failure which should abort the location
-process.
-
-A module can create and destroy per-library-context state objects by
-implementing the **init** and **fini** methods.  State objects have
-the type void \*, and should be cast to an internal type for the state
-object.
diff --git a/doc/rst_source/krb_plugindev/profile.rst b/doc/rst_source/krb_plugindev/profile.rst
deleted file mode 100644
index 671d4c18c..000000000
--- a/doc/rst_source/krb_plugindev/profile.rst
+++ /dev/null
@@ -1,92 +0,0 @@
-Configuration interface (profile)
-=================================
-
-The profile interface allows a module to control how krb5
-configuration information is obtained by the Kerberos library and
-applications.  For a detailed description of the profile interface,
-see the header file ``<profile.h>``.
-
-.. note:: The profile interface does not follow the normal conventions
-          for MIT krb5 pluggable interfaces, because it is part of a
-          lower-level component of the krb5 library.
-
-As with other types of plugin modules, a profile module is a Unix
-shared object or Windows DLL, built separately from the krb5 tree.
-The krb5 library will dynamically load and use a profile plugin module
-if it reads a ``module`` directive at the beginning of krb5.conf, as
-described in :ref:`profile_plugin_config`.
-
-A profile module exports a function named ``profile_module_init``
-matching the signature of the profile_module_init_fn type.  This
-function accepts a residual string, which may be used to help locate
-the configuration source.  The function fills in a vtable and may also
-create a per-profile state object.  If the module uses state objects,
-it should implement the **copy** and **cleanup** methods to manage
-them.
-
-A basic read-only profile module need only implement the
-**get_values** and **free_values** methods.  The **get_values** method
-accepts a null-terminated list of C string names (e.g., an array
-containing "libdefaults", "clockskew", and NULL for the **clockskew**
-variable in the :ref:`libdefaults` section) and returns a
-null-terminated list of values, which will be cleaned up with the
-**free_values** method when the caller is done with them.
-
-Iterable profile modules must also define the **iterator_create**,
-**iterator**, **iterator_free**, and **free_string** methods.  The
-core krb5 code does not require profiles to be iterable, but some
-applications may iterate over the krb5 profile object in order to
-present configuration interfaces.
-
-Writable profile modules must also define the **writable**,
-**modified**, **update_relation**, **rename_section**,
-**add_relation**, and **flush** methods.  The core krb5 code does not
-require profiles to be writable, but some applications may write to
-the krb5 profile in order to present configuration interfaces.
-
-The following is an example of a very basic read-only profile module
-which returns a hardcoded value for the **default_realm** variable in
-:ref:`libdefaults`, and provides no other configuration information.
-(For conciseness, the example omits code for checking the return
-values of malloc and strdup.) ::
-
-    #include <stdlib.h>
-    #include <string.h>
-    #include <profile.h>
-
-    static long
-    get_values(void *cbdata, const char *const *names, char ***values)
-    {
-        if (names[0] != NULL && strcmp(names[0], "libdefaults") == 0 &&
-            names[1] != NULL && strcmp(names[1], "default_realm") == 0) {
-            *values = malloc(2 * sizeof(char *));
-            (*values)[0] = strdup("ATHENA.MIT.EDU");
-            (*values)[1] = NULL;
-            return 0;
-        }
-        return PROF_NO_RELATION;
-    }
-
-    static void
-    free_values(void *cbdata, char **values)
-    {
-        char **v;
-
-        for (v = values; *v; v++)
-            free(*v);
-        free(values);
-    }
-
-    long
-    profile_module_init(const char *residual, struct profile_vtable *vtable,
-                        void **cb_ret);
-
-    long
-    profile_module_init(const char *residual, struct profile_vtable *vtable,
-                        void **cb_ret)
-    {
-        *cb_ret = NULL;
-        vtable->get_values = get_values;
-        vtable->free_values = free_values;
-        return 0;
-    }
diff --git a/doc/rst_source/krb_plugindev/pwqual.rst b/doc/rst_source/krb_plugindev/pwqual.rst
deleted file mode 100644
index a981e7903..000000000
--- a/doc/rst_source/krb_plugindev/pwqual.rst
+++ /dev/null
@@ -1,23 +0,0 @@
-Password quality interface (pwqual)
-===================================
-
-The pwqual interface allows modules to control what passwords are
-allowed when a user changes passwords.  For a detailed description of
-the pwqual interface, see the header file ``<krb5/pwqual_plugin.h>``.
-
-The primary pwqual method is **check**, which receives a password as
-input and returns success (0) or a ``KADM5_PASS_Q_`` failure code
-depending on whether the password is allowed.  The **check** method
-also receives the principal name and the name of the principal's
-password policy as input; although there is no stable interface for
-the module to obtain the fields of the password policy, it can define
-its own configuration or data store based on the policy name.
-
-A module can create and destroy per-process state objects by
-implementing the **open** and **close** methods.  State objects have
-the type krb5_pwqual_moddata, which is an abstract pointer type.  A
-module should typically cast this to an internal type for the state
-object.  The **open** method also receives the name of the realm's
-dictionary file (as configured by the **dict_file** variable in the
-:ref:`kdc_realms` section of :ref:`kdc.conf(5)`) if it wishes to use
-it.