Rename doc subdirectories

We like these names better, and they match the PDF document filenames.

admins -> admin
appldev -> appdev
users -> user

and catch up where the names are used elsewhere.

The relay/ directory has been removed, with its contents moved to the
top level in build_this.rst and a new about.rst.

The section headers for kadmind, krb5kdc, sserver, kpasswd, kswitch,
and sclient are misdetected as conflict markers.
bigredbutton: whitespace

ticket: 7433
tags: pullup

11 files changed, 1388 insertions, 0 deletions

diff --git a/doc/appdev/gssapi.rst b/doc/appdev/gssapi.rst
new file mode 100644
index 0000000000..29c06b565c
--- /dev/null
+++ b/doc/appdev/gssapi.rst
@@ -0,0 +1,220 @@
+Developing with GSSAPI
+======================
+
+The GSSAPI (Generic Security Services API) allows applications to
+communicate securely using Kerberos 5 or other security mechanisms.
+We recommend using the GSSAPI (or a higher-level framework which
+encompasses GSSAPI, such as SASL) for secure network communication
+over using the libkrb5 API directly.
+
+GSSAPIv2 is specified in :rfc:`2743` and :rfc:`2744`.  This
+documentation will describe how various ways of using GSSAPI will
+behave with the krb5 mechanism as implemented in MIT krb5, as well as
+krb5-specific extensions to the GSSAPI.
+
+
+Name types
+----------
+
+A GSSAPI application can name a local or remote entity by calling
+gss_import_name_, specifying a name type and a value.  The following
+name types are supported by the krb5 mechanism:
+
+* **GSS_C_NT_HOSTBASED_SERVICE**: The value should be a string of the
+  form ``service`` or ``service@hostname``.  This is the most common
+  way to name target services when initiating a security context, and
+  is the most likely name type to work across multiple mechanisms.
+
+* **GSS_KRB5_NT_PRINCIPAL_NAME**: The value should be a principal name
+  string.  This name type only works with the krb5 mechanism, and is
+  defined in the ``<gssapi_krb5.h>`` header.
+
+* **GSS_C_NT_USER_NAME** or **GSS_C_NULL_OID**: The value is treated
+  as an unparsed principal name string, as above.  These name types
+  may work with mechanisms other than krb5, but will have different
+  interpretations in those mechanisms.  **GSS_C_NT_USER_NAME** is
+  intended to be used with a local username, which will parse into a
+  single-component principal in the default realm.
+
+* **GSS_C_NT_ANONYMOUS**: The value is ignored.  The anonymous
+  principal is used, allowing a client to authenticate to a server
+  without asserting a particular identity (which may or may not be
+  allowed by a particular server or Kerberos realm).
+
+* **GSS_C_NT_MACHINE_UID_NAME**: The value is uid_t object.  On
+  Unix-like systems, the username of the uid is looked up in the
+  system user database and the resulting username is parsed as a
+  principal name.
+
+* **GSS_C_NT_STRING_UID_NAME**: As above, but the value is a decimal
+  string representation of the uid.
+
+* **GSS_C_NT_EXPORT_NAME**: The value must be the result of a
+  gss_export_name_ call.
+
+
+Initiator credentials
+---------------------
+
+A GSSAPI client application uses gss_init_sec_context_ to establish a
+security context.  The *initiator_cred_handle* parameter determines
+what tickets are used to establish the connection.  An application can
+either pass **GSS_C_NO_CREDENTIAL** to use the default client
+credential, or it can use gss_acquire_cred_ beforehand to acquire an
+initiator credential.  The call to gss_acquire_cred_ may include a
+*desired_name* parameter, or it may pass **GSS_C_NO_NAME** if it does
+not have a specific name preference.
+
+If the desired name for a krb5 initiator credential is a host-based
+name, it is converted to a principal name of the form
+``service/hostname`` in the local realm, where *hostname* is the local
+hostname if not specified.  The hostname will be canonicalized using
+forward name resolution, and possibly also using reverse name
+resolution depending on the value of the **rdns** variable in
+:ref:`libdefaults`.
+
+If a desired name is specified in the call to gss_acquire_cred_, the
+krb5 mechanism will attempt to find existing tickets for that client
+principal name in the default credential cache or collection.  If the
+default cache type does not support a collection, and the default
+cache contains credentials for a different principal than the desired
+name, a **GSS_S_CRED_UNAVAIL** error will be returned with a minor
+code indicating a mismatch.
+
+If no existing tickets are available for the desired name, but the
+name has an entry in the default client :ref:`keytab_definition`, the
+krb5 mechanism will acquire initial tickets for the name using the
+default client keytab.
+
+If no desired name is specified, credential acquisition will be
+deferred until the credential is used in a call to
+gss_init_sec_context_ or gss_inquire_cred_.  If the call is to
+gss_init_sec_context_, the target name will be used to choose a client
+principal name using the credential cache selection facility.  (This
+facility might, for instance, try to choose existing tickets for a
+client principal in the same realm as the target service).  If there
+are no existing tickets for the chosen principal, but it is present in
+the default client keytab, the krb5 mechanism will acquire initial
+tickets using the keytab.
+
+If the target name cannot be used to select a client principal
+(because the credentials are used in a call to gss_inquire_cred_), or
+if the credential cache selection facility cannot choose a principal
+for it, the default credential cache will be selected if it exists and
+contains tickets.
+
+If the default credential cache does not exist, but the default client
+keytab does, the krb5 mechanism will try to acquire initial tickets
+for the first principal in the default client keytab.
+
+If the krb5 mechanism acquires initial tickets using the default
+client keytab, the resulting tickets will be stored in the default
+cache or collection, and will be refreshed by future calls to
+gss_acquire_cred_ as they approach their expire time.
+
+
+Acceptor names
+--------------
+
+A GSSAPI server application uses gss_accept_sec_context_ to establish
+a security context based on tokens provided by the client.  The
+*acceptor_cred_handle* parameter determines what
+:ref:`keytab_definition` entries may be authenticated to by the
+client, if the krb5 mechanism is used.
+
+The simplest choice is to pass **GSS_C_NO_CREDENTIAL** as the acceptor
+credential.  In this case, clients may authenticate to any service
+principal in the default keytab (typically |keytab|, or the value of
+the **KRB5_KTNAME** environment variable).  This is the recommended
+approach if the server application has no specific requirements to the
+contrary.
+
+A server may acquire an acceptor credential with gss_acquire_cred_ and
+a *cred_usage* of **GSS_C_ACCEPT** or **GSS_C_BOTH**.  If the
+*desired_name* parameter is **GSS_C_NO_NAME**, then clients will be
+allowed to authenticate to any service principal in the default
+keytab, just as if no acceptor credential was supplied.
+
+If a server wishes to specify a *desired_name* to gss_acquire_cred_,
+the most common choice is a host-based name.  If the host-based
+*desired_name* contains just a *service*, then clients will be allowed
+to authenticate to any host-based service principal (that is, a
+principal of the form ``service/hostname@REALM``) for the named
+service, regardless of hostname or realm, as long as it is present in
+the default keytab.  If the input name contains both a *service* and a
+*hostname*, clients will be allowed to authenticate to any host-based
+principal for the named service and hostname, regardless of realm.
+
+.. note:: If a *hostname* is specified, it will be canonicalized
+          using forward name resolution, and possibly also using
+          reverse name resolution depending on the value of the
+          **rdns** variable in :ref:`libdefaults`.
+
+.. note:: If the **ignore_acceptor_hostname** variable in
+          :ref:`libdefaults` is enabled, then *hostname* will be
+          ignored even if one is specified in the input name.
+
+.. note:: In MIT krb5 versions prior to 1.10, and in Heimdal's
+          implementation of the krb5 mechanism, an input name with
+          just a *service* is treated like an input name of
+          ``service@localhostname``, where *localhostname* is the
+          string returned by gethostname().
+
+If the *desired_name* is a krb5 principal name or a local system name
+type which is mapped to a krb5 principal name, clients will only be
+allowed to authenticate to that principal in the default keytab.
+
+
+Importing and exporting credentials
+-----------------------------------
+
+The following GSSAPI extensions can be used to import and export
+credentials (declared in ``<gssapi/gssapi_ext.h>``)::
+
+    OM_uint32 gss_export_cred(OM_uint32 *minor_status,
+                              gss_cred_id_t cred_handle,
+                              gss_buffer_t token);
+
+    OM_uint32 gss_import_cred(OM_uint32 *minor_status,
+                              gss_buffer_t token,
+                              gss_cred_id_t *cred_handle);
+
+The first function serializes a GSSAPI credential handle into a
+buffer; the second unseralizes a buffer into a GSSAPI credential
+handle.  Serializing a credential does not destroy it.  If any of the
+mechanisms used in *cred_handle* do not support serialization,
+gss_export_cred will return **GSS_S_UNAVAILABLE**.  As with other
+GSSAPI serialization functions, these extensions are only intended to
+work with a matching implementation on the other side; they do not
+serialize credentials in a standardized format.
+
+A serialized credential may contain secret information such as ticket
+session keys.  The serialization format does not protect this
+information from eavesdropping or tampering.  The calling application
+must take care to protect the serialized credential when communicating
+it over an insecure channel or to an untrusted party.
+
+A krb5 GSSAPI credential may contain references to a credential cache,
+a client keytab, an acceptor keytab, and a replay cache.  These
+resources are normally serialized as references to their external
+locations (such as the filename of the credential cache).  Because of
+this, a serialized krb5 credential can only be imported by a process
+with similar privileges to the exporter.  A serialized credential
+should not be trusted if it originates from a source with lower
+privileges than the importer, as it may contain references to external
+credential cache, keytab, or replay cache resources not accessible to
+the originator.
+
+An exception to the above rule applies when a krb5 GSSAPI credential
+refers to a memory credential cache, as is normally the case for
+delegated credentials received by gss_accept_sec_context_.  In this
+case, the contents of the credential cache are serialized, so that the
+resulting token may be imported even if the original memory credential
+cache no longer exists.
+
+.. _gss_accept_sec_context: http://tools.ietf.org/html/rfc2744.html#section-5.1
+.. _gss_acquire_cred: http://tools.ietf.org/html/rfc2744.html#section-5.2
+.. _gss_export_name: http://tools.ietf.org/html/rfc2744.html#section-5.13
+.. _gss_import_name: http://tools.ietf.org/html/rfc2744.html#section-5.16
+.. _gss_init_sec_context: http://tools.ietf.org/html/rfc2744.html#section-5.19
+.. _gss_inquire_cred: http://tools.ietf.org/html/rfc2744.html#section-5.21
diff --git a/doc/appdev/h5l_mit_apidiff.rst b/doc/appdev/h5l_mit_apidiff.rst
new file mode 100644
index 0000000000..33da60211a
--- /dev/null
+++ b/doc/appdev/h5l_mit_apidiff.rst
@@ -0,0 +1,28 @@
+Differences between Heimdal and MIT Kerberos API
+================================================
+
+
+ ======================================== =================================================
+  :c:func:`krb5_auth_con_getaddrs()`       H5l: If either of the pointers to local_addr
+                                           and remote_addr is not NULL, it is freed
+                                           first and then reallocated before being
+                                           populated with the content of corresponding
+                                           address from authentication context.
+  :c:func:`krb5_auth_con_setaddrs()`       H5l: If either address is NULL, the previous
+                                           address remains in place
+  :c:func:`krb5_auth_con_setports()`       H5l: Not implemented as of version 1.3.3
+  :c:func:`krb5_auth_con_setrecvsubkey()`  H5l: If either port is NULL, the previous
+                                           port remains in place
+  :c:func:`krb5_auth_con_setsendsubkey()`  H5l: Not implemented as of version 1.3.3
+  :c:func:`krb5_cc_set_config()`           MIT: Before version 1.10 it was assumed that
+                                           the last argument *data* is ALWAYS non-zero.
+  :c:func:`krb5_cccol_last_change_time()`  H5l takes 3 arguments: krb5_context context,
+                                           const char \*type, krb5_timestamp \*change_time
+                                           MIT takes two arguments: krb5_context context,
+                                           krb5_timestamp \*change_time
+  :c:func:`krb5_set_default_realm()`       H5l: Caches the computed default realm context
+                                           field.  If the second argument is NULL,
+                                           it tries to retrieve it from libdefaults or DNS.
+                                           MIT: Computes the default realm each time
+                                           if it wasn't explicitly set in the context
+ ======================================== =================================================
diff --git a/doc/appdev/index.rst b/doc/appdev/index.rst
new file mode 100644
index 0000000000..3d62045ca8
--- /dev/null
+++ b/doc/appdev/index.rst
@@ -0,0 +1,15 @@
+For application developers
+==========================
+
+.. toctree::
+   :maxdepth: 1
+
+   gssapi.rst
+   h5l_mit_apidiff.rst
+   init_creds.rst
+   princ_handle.rst
+
+.. toctree::
+   :maxdepth: 1
+
+   refs/index.rst
diff --git a/doc/appdev/init_creds.rst b/doc/appdev/init_creds.rst
new file mode 100644
index 0000000000..f6012f778c
--- /dev/null
+++ b/doc/appdev/init_creds.rst
@@ -0,0 +1,144 @@
+Initial credentials
+===================
+
+Software that performs tasks such as logging users into a computer
+when they type their Kerberos password needs to get initial
+credentials (usually ticket granting tickets) from Kerberos.  Such
+software shares some behavior with the :ref:`kinit(1)` program.
+
+Whenever a program grants access to a resource (such as a local login
+session on a desktop computer) based on a user successfully getting
+initial Kerberos credentials, it must verify those credentials against
+a secure shared secret (e.g., a host keytab) to ensure that the user
+credentials actually originate from a legitimate KDC.  Failure to
+perform this verification is a critical vulnerability, because a
+malicious user can execute the "Zanarotti attack": the user constructs
+a fake response that appears to come from the legitimate KDC, but
+whose contents come from an attacker-controlled KDC.
+
+Some applications read a Kerberos password over the network (ideally
+over a secure channel), which they then verify against the KDC.  While
+this technique may be the only practical way to integrate Kerberos
+into some existing legacy systems, its use is contrary to the original
+design goals of Kerberos.
+
+The function :c:func:`krb5_get_init_creds_password` will get initial
+credentials for a client using a password.  An application that needs
+to verify the credentials can call :c:func:`krb5_verify_init_creds`.
+
+Options for get_init_creds
+--------------------------
+
+The function :c:func:`krb5_get_init_creds_password` takes an options
+parameter (which can be a null pointer).  Use the function
+:c:func:`krb5_get_init_creds_opt_alloc` to allocate an options
+structure, and :c:func:`krb5_get_init_creds_opt_free` to free it.
+
+User interaction
+----------------
+
+Authenticating a user usually requires the entry of secret
+information, such as a password.  A password can be supplied directly
+to :c:func:`krb5_get_init_creds_password` via the *password*
+parameter, or the application can supply prompter and/or responder
+callbacks instead.  If callbacks are used, the user can also be
+queried for other secret information such as a PIN, informed of
+impending password expiration, or prompted to change a password which
+has expired.
+
+Prompter callback
+~~~~~~~~~~~~~~~~~
+
+A prompter callback can be specified via the *prompter* and *data*
+parameters to :c:func:`krb5_get_init_creds_password`.  The prompter
+will be invoked each time the krb5 library has a question to ask or
+information to present.  When the prompter callback is invoked, the
+*banner* argument (if not null) is intended to be displayed to the
+user, and the questions to be answered are specified in the *prompts*
+array.  Each prompt contains a text question in the *prompt* field, a
+*hidden* bit to indicate whether the answer should be hidden from
+display, and a storage area for the answer in the *reply* field.  The
+callback should fill in each question's ``reply->data`` with the
+answer, up to a maximum number of ``reply->length`` bytes, and then
+reset ``reply->length`` to the length of the answer.
+
+A prompter callback can call :c:func:`krb5_get_prompt_types` to get an
+array of type constants corresponding to the prompts, to get
+programmatic information about the semantic meaning of the questions.
+:c:func:`krb5_get_prompt_types` may return a null pointer if no prompt
+type information is available.
+
+Text-based applications can use a built-in text prompter
+implementation by supplying :c:func:`krb5_prompter_posix` as the
+*prompter* parameter and a null pointer as the *data* parameter.
+
+Responder callback
+~~~~~~~~~~~~~~~~~~
+
+A responder callback can be specified through the init_creds options
+using the :c:func:`krb5_get_init_creds_opt_set_responder` function.
+Responder callbacks can present a more sophisticated user interface
+for authentication secrets.  The responder callback is usually invoked
+only once per authentication, with a list of questions produced by all
+of the allowed preauthentication mechanisms.
+
+When the responder callback is invoked, the *rctx* argument can be
+accessed to obtain the list of questions and to answer them.  The
+:c:func:`krb5_responder_list_questions` function retrieves an array of
+question types.  For each question type, the
+:c:func:`krb5_responder_get_challenge` function retrieves additional
+information about the question, if applicable, and the
+:c:func:`krb5_responder_set_answer` function sets the answer.
+
+Responder question types, challenges, and answers are UTF-8 strings.
+The question type is a well-known string; the meaning of the challenge
+and answer depend on the question type.  If an application does not
+understand a question type, it cannot interpret the challenge or
+provide an answer.  Failing to answer a question typically results in
+the prompter callback being used as a fallback.
+
+Password question
+#################
+
+The :c:macro:`KRB5_RESPONDER_QUESTION_PASSWORD` (or ``"password"``)
+question type requests the user's password.  This question does not
+have a challenge, and the response is simply the password string.
+
+One-time password question
+##########################
+
+The :c:macro:`KRB5_RESPONDER_QUESTION_OTP` (or ``"otp"``) question
+type requests a choice among one-time password tokens and the PIN and
+value for the chosen token.  The challenge and answer are JSON-encoded
+strings, but an application can use convenience functions to avoid
+doing any JSON processing itself.
+
+The :c:func:`krb5_responder_otp_get_challenge` function decodes the
+challenge into a krb5_responder_otp_challenge structure.  The
+:c:func:`krb5_responder_otp_set_answer` function selects one of the
+token information elements from the challenge and supplies the value
+and pin for that token.
+
+Verifying initial credentials
+-----------------------------
+
+Use the function :c:func:`krb5_verify_init_creds` to verify initial
+credentials.  It takes an options structure (which can be a null
+pointer).  Use :c:func:`krb5_verify_init_creds_opt_init` to initialize
+the caller-allocated options structure, and
+:c:func:`krb5_verify_init_creds_opt_set_ap_req_nofail` to set the
+"nofail" option.
+
+The confusingly named "nofail" option, when set, means that the
+verification must actually succeed in order for
+:c:func:`krb5_verify_init_creds` to indicate success.  The default
+state of this option (cleared) means that if there is no key material
+available to verify the user credentials, the verification will
+succeed anyway.  (The default can be changed by a configuration file
+setting.)
+
+This accommodates a use case where a large number of unkeyed shared
+desktop workstations need to allow users to log in using Kerberos.
+The security risks from this practice are mitigated by the absence of
+valuable state on the shared workstations---any valuable resources
+that the users would access reside on networked servers.
diff --git a/doc/appdev/princ_handle.rst b/doc/appdev/princ_handle.rst
new file mode 100644
index 0000000000..455f00a4b6
--- /dev/null
+++ b/doc/appdev/princ_handle.rst
@@ -0,0 +1,79 @@
+Principal manipulation and parsing
+==================================
+
+Kerberos principal structure
+
+..
+
+:c:type:`krb5_principal_data`
+
+:c:type:`krb5_principal`
+
+..
+
+Create and free principal
+
+..
+
+:c:func:`krb5_build_principal()`
+
+:c:func:`krb5_build_principal_alloc_va()`
+
+:c:func:`krb5_build_principal_ext()`
+
+:c:func:`krb5_copy_principal()`
+
+:c:func:`krb5_free_principal()`
+
+:c:func:`krb5_cc_get_principal()`
+
+..
+
+Comparing
+
+..
+
+:c:func:`krb5_principal_compare()`
+
+:c:func:`krb5_principal_compare_flags()`
+
+:c:func:`krb5_principal_compare_any_realm()`
+
+:c:func:`krb5_sname_match()`
+
+:c:func:`krb5_sname_to_principal()`
+
+..
+
+
+Parsing:
+
+..
+
+:c:func:`krb5_parse_name()`
+
+:c:func:`krb5_parse_name_flags()`
+
+:c:func:`krb5_unparse_name()`
+
+:c:func:`krb5_unparse_name_flags()`
+
+..
+
+Utilities:
+
+..
+
+:c:func:`krb5_is_config_principal()`
+
+:c:func:`krb5_kuserok()`
+
+:c:func:`krb5_set_password()`
+
+:c:func:`krb5_set_password_using_ccache()`
+
+:c:func:`krb5_set_principal_realm()`
+
+:c:func:`krb5_realm_compare()`
+
+..
diff --git a/doc/appdev/refs/api/index.rst b/doc/appdev/refs/api/index.rst
new file mode 100644
index 0000000000..b119165d1e
--- /dev/null
+++ b/doc/appdev/refs/api/index.rst
@@ -0,0 +1,397 @@
+krb5 API
+========
+
+
+Frequently used public interfaces
+----------------------------------
+
+.. toctree::
+   :maxdepth: 1
+
+   krb5_build_principal.rst
+   krb5_build_principal_alloc_va.rst
+   krb5_build_principal_ext.rst
+   krb5_cc_close.rst
+   krb5_cc_default.rst
+   krb5_cc_default_name.rst
+   krb5_cc_destroy.rst
+   krb5_cc_dup.rst
+   krb5_cc_get_name.rst
+   krb5_cc_get_principal.rst
+   krb5_cc_get_type.rst
+   krb5_cc_initialize.rst
+   krb5_cc_new_unique.rst
+   krb5_cc_resolve.rst
+   krb5_change_password.rst
+   krb5_chpw_message.rst
+   krb5_free_context.rst
+   krb5_free_error_message.rst
+   krb5_free_principal.rst
+   krb5_fwd_tgt_creds.rst
+   krb5_get_default_realm.rst
+   krb5_get_error_message.rst
+   krb5_get_host_realm.rst
+   krb5_get_credentials.rst
+   krb5_get_fallback_host_realm.rst
+   krb5_get_init_creds_keytab.rst
+   krb5_get_init_creds_opt_alloc.rst
+   krb5_get_init_creds_opt_free.rst
+   krb5_get_init_creds_opt_get_fast_flags.rst
+   krb5_get_init_creds_opt_set_address_list.rst
+   krb5_get_init_creds_opt_set_anonymous.rst
+   krb5_get_init_creds_opt_set_canonicalize.rst
+   krb5_get_init_creds_opt_set_change_password_prompt.rst
+   krb5_get_init_creds_opt_set_etype_list.rst
+   krb5_get_init_creds_opt_set_expire_callback.rst
+   krb5_get_init_creds_opt_set_fast_ccache.rst
+   krb5_get_init_creds_opt_set_fast_ccache_name.rst
+   krb5_get_init_creds_opt_set_fast_flags.rst
+   krb5_get_init_creds_opt_set_forwardable.rst
+   krb5_get_init_creds_opt_set_in_ccache.rst
+   krb5_get_init_creds_opt_set_out_ccache.rst
+   krb5_get_init_creds_opt_set_pa.rst
+   krb5_get_init_creds_opt_set_preauth_list.rst
+   krb5_get_init_creds_opt_set_proxiable.rst
+   krb5_get_init_creds_opt_set_renew_life.rst
+   krb5_get_init_creds_opt_set_responder.rst
+   krb5_get_init_creds_opt_set_salt.rst
+   krb5_get_init_creds_opt_set_tkt_life.rst
+   krb5_get_init_creds_password.rst
+   krb5_get_profile.rst
+   krb5_get_prompt_types.rst
+   krb5_get_renewed_creds.rst
+   krb5_get_validated_creds.rst
+   krb5_init_context.rst
+   krb5_init_secure_context.rst
+   krb5_is_config_principal.rst
+   krb5_is_thread_safe.rst
+   krb5_kt_close.rst
+   krb5_kt_client_default.rst
+   krb5_kt_default.rst
+   krb5_kt_default_name.rst
+   krb5_kt_get_name.rst
+   krb5_kt_get_type.rst
+   krb5_kt_resolve.rst
+   krb5_kuserok.rst
+   krb5_parse_name.rst
+   krb5_parse_name_flags.rst
+   krb5_principal_compare.rst
+   krb5_principal_compare_any_realm.rst
+   krb5_principal_compare_flags.rst
+   krb5_prompter_posix.rst
+   krb5_realm_compare.rst
+   krb5_responder_get_challenge.rst
+   krb5_responder_list_questions.rst
+   krb5_responder_set_answer.rst
+   krb5_responder_otp_get_challenge.rst
+   krb5_responder_otp_set_answer.rst
+   krb5_responder_otp_challenge_free.rst
+   krb5_set_default_realm.rst
+   krb5_set_password.rst
+   krb5_set_password_using_ccache.rst
+   krb5_set_principal_realm.rst
+   krb5_set_trace_callback.rst
+   krb5_set_trace_filename.rst
+   krb5_sname_match.rst
+   krb5_sname_to_principal.rst
+   krb5_unparse_name.rst
+   krb5_unparse_name_ext.rst
+   krb5_unparse_name_flags.rst
+   krb5_unparse_name_flags_ext.rst
+   krb5_us_timeofday.rst
+   krb5_verify_authdata_kdc_issued.rst
+
+Rarely used public interfaces
+--------------------------------
+
+.. toctree::
+   :maxdepth: 1
+
+   krb5_425_conv_principal.rst
+   krb5_524_conv_principal.rst
+   krb5_address_compare.rst
+   krb5_address_order.rst
+   krb5_address_search.rst
+   krb5_allow_weak_crypto.rst
+   krb5_aname_to_localname.rst
+   krb5_anonymous_principal.rst
+   krb5_anonymous_realm.rst
+   krb5_appdefault_boolean.rst
+   krb5_appdefault_string.rst
+   krb5_auth_con_free.rst
+   krb5_auth_con_genaddrs.rst
+   krb5_auth_con_get_checksum_func.rst
+   krb5_auth_con_getaddrs.rst
+   krb5_auth_con_getauthenticator.rst
+   krb5_auth_con_getflags.rst
+   krb5_auth_con_getkey.rst
+   krb5_auth_con_getkey_k.rst
+   krb5_auth_con_getlocalseqnumber.rst
+   krb5_auth_con_getrcache.rst
+   krb5_auth_con_getrecvsubkey.rst
+   krb5_auth_con_getrecvsubkey_k.rst
+   krb5_auth_con_getremoteseqnumber.rst
+   krb5_auth_con_getsendsubkey.rst
+   krb5_auth_con_getsendsubkey_k.rst
+   krb5_auth_con_init.rst
+   krb5_auth_con_set_checksum_func.rst
+   krb5_auth_con_set_req_cksumtype.rst
+   krb5_auth_con_setaddrs.rst
+   krb5_auth_con_setflags.rst
+   krb5_auth_con_setports.rst
+   krb5_auth_con_setrcache.rst
+   krb5_auth_con_setrecvsubkey.rst
+   krb5_auth_con_setrecvsubkey_k.rst
+   krb5_auth_con_setsendsubkey.rst
+   krb5_auth_con_setsendsubkey_k.rst
+   krb5_auth_con_setuseruserkey.rst
+   krb5_cc_cache_match.rst
+   krb5_cc_copy_creds.rst
+   krb5_cc_end_seq_get.rst
+   krb5_cc_get_config.rst
+   krb5_cc_get_flags.rst
+   krb5_cc_get_full_name.rst
+   krb5_cc_last_change_time.rst
+   krb5_cc_lock.rst
+   krb5_cc_move.rst
+   krb5_cc_next_cred.rst
+   krb5_cc_remove_cred.rst
+   krb5_cc_retrieve_cred.rst
+   krb5_cc_select.rst
+   krb5_cc_set_config.rst
+   krb5_cc_set_default_name.rst
+   krb5_cc_set_flags.rst
+   krb5_cc_start_seq_get.rst
+   krb5_cc_store_cred.rst
+   krb5_cc_support_switch.rst
+   krb5_cc_switch.rst
+   krb5_cc_unlock.rst
+   krb5_cccol_cursor_free.rst
+   krb5_cccol_cursor_new.rst
+   krb5_cccol_cursor_next.rst
+   krb5_cccol_have_content.rst
+   krb5_cccol_last_change_time.rst
+   krb5_cccol_lock.rst
+   krb5_cccol_unlock.rst
+   krb5_clear_error_message.rst
+   krb5_check_clockskew.rst
+   krb5_copy_addresses.rst
+   krb5_copy_authdata.rst
+   krb5_copy_authenticator.rst
+   krb5_copy_checksum.rst
+   krb5_copy_context.rst
+   krb5_copy_creds.rst
+   krb5_copy_data.rst
+   krb5_copy_error_message.rst
+   krb5_copy_keyblock.rst
+   krb5_copy_keyblock_contents.rst
+   krb5_copy_principal.rst
+   krb5_copy_ticket.rst
+   krb5_find_authdata.rst
+   krb5_free_addresses.rst
+   krb5_free_ap_rep_enc_part.rst
+   krb5_free_authdata.rst
+   krb5_free_authenticator.rst
+   krb5_free_cred_contents.rst
+   krb5_free_creds.rst
+   krb5_free_data.rst
+   krb5_free_data_contents.rst
+   krb5_free_default_realm.rst
+   krb5_free_error.rst
+   krb5_free_host_realm.rst
+   krb5_free_keyblock.rst
+   krb5_free_keyblock_contents.rst
+   krb5_free_keytab_entry_contents.rst
+   krb5_free_octet_data.rst
+   krb5_free_string.rst
+   krb5_free_ticket.rst
+   krb5_free_unparsed_name.rst
+   krb5_get_permitted_enctypes.rst
+   krb5_get_server_rcache.rst
+   krb5_get_time_offsets.rst
+   krb5_init_context_profile.rst
+   krb5_init_creds_free.rst
+   krb5_init_creds_get.rst
+   krb5_init_creds_get_creds.rst
+   krb5_init_creds_get_error.rst
+   krb5_init_creds_get_times.rst
+   krb5_init_creds_init.rst
+   krb5_init_creds_set_keytab.rst
+   krb5_init_creds_set_password.rst
+   krb5_init_creds_set_service.rst
+   krb5_init_creds_step.rst
+   krb5_init_keyblock.rst
+   krb5_is_referral_realm.rst
+   krb5_kt_add_entry.rst
+   krb5_kt_end_seq_get.rst
+   krb5_kt_get_entry.rst
+   krb5_kt_have_content.rst
+   krb5_kt_next_entry.rst
+   krb5_kt_read_service_key.rst
+   krb5_kt_remove_entry.rst
+   krb5_kt_start_seq_get.rst
+   krb5_make_authdata_kdc_issued.rst
+   krb5_merge_authdata.rst
+   krb5_mk_1cred.rst
+   krb5_mk_error.rst
+   krb5_mk_ncred.rst
+   krb5_mk_priv.rst
+   krb5_mk_rep.rst
+   krb5_mk_rep_dce.rst
+   krb5_mk_req.rst
+   krb5_mk_req_extended.rst
+   krb5_mk_safe.rst
+   krb5_os_localaddr.rst
+   krb5_pac_add_buffer.rst
+   krb5_pac_free.rst
+   krb5_pac_get_buffer.rst
+   krb5_pac_get_types.rst
+   krb5_pac_init.rst
+   krb5_pac_parse.rst
+   krb5_pac_sign.rst
+   krb5_pac_verify.rst
+   krb5_principal2salt.rst
+   krb5_rd_cred.rst
+   krb5_rd_error.rst
+   krb5_rd_priv.rst
+   krb5_rd_rep.rst
+   krb5_rd_rep_dce.rst
+   krb5_rd_req.rst
+   krb5_rd_safe.rst
+   krb5_read_password.rst
+   krb5_salttype_to_string.rst
+   krb5_server_decrypt_ticket_keytab.rst
+   krb5_set_default_tgs_enctypes.rst
+   krb5_set_error_message.rst
+   krb5_set_real_time.rst
+   krb5_string_to_cksumtype.rst
+   krb5_string_to_deltat.rst
+   krb5_string_to_enctype.rst
+   krb5_string_to_salttype.rst
+   krb5_string_to_timestamp.rst
+   krb5_timeofday.rst
+   krb5_timestamp_to_sfstring.rst
+   krb5_timestamp_to_string.rst
+   krb5_tkt_creds_free.rst
+   krb5_tkt_creds_get.rst
+   krb5_tkt_creds_get_creds.rst
+   krb5_tkt_creds_get_times.rst
+   krb5_tkt_creds_init.rst
+   krb5_tkt_creds_step.rst
+   krb5_verify_init_creds.rst
+   krb5_verify_init_creds_opt_init.rst
+   krb5_verify_init_creds_opt_set_ap_req_nofail.rst
+   krb5_vset_error_message.rst
+
+
+Public interfaces that should not be called directly
+-------------------------------------------------------
+
+.. toctree::
+   :maxdepth: 1
+
+   krb5_c_block_size.rst
+   krb5_c_checksum_length.rst
+   krb5_c_crypto_length.rst
+   krb5_c_crypto_length_iov.rst
+   krb5_c_decrypt.rst
+   krb5_c_decrypt_iov.rst
+   krb5_c_encrypt.rst
+   krb5_c_encrypt_iov.rst
+   krb5_c_encrypt_length.rst
+   krb5_c_enctype_compare.rst
+   krb5_c_free_state.rst
+   krb5_c_fx_cf2_simple.rst
+   krb5_c_init_state.rst
+   krb5_c_is_coll_proof_cksum.rst
+   krb5_c_is_keyed_cksum.rst
+   krb5_c_keyed_checksum_types.rst
+   krb5_c_keylengths.rst
+   krb5_c_make_checksum.rst
+   krb5_c_make_checksum_iov.rst
+   krb5_c_make_random_key.rst
+   krb5_c_padding_length.rst
+   krb5_c_prf.rst
+   krb5_c_prf_length.rst
+   krb5_c_random_add_entropy.rst
+   krb5_c_random_make_octets.rst
+   krb5_c_random_os_entropy.rst
+   krb5_c_random_to_key.rst
+   krb5_c_string_to_key.rst
+   krb5_c_string_to_key_with_params.rst
+   krb5_c_valid_cksumtype.rst
+   krb5_c_valid_enctype.rst
+   krb5_c_verify_checksum.rst
+   krb5_c_verify_checksum_iov.rst
+   krb5_cksumtype_to_string.rst
+   krb5_decode_authdata_container.rst
+   krb5_decode_ticket.rst
+   krb5_deltat_to_string.rst
+   krb5_encode_authdata_container.rst
+   krb5_enctype_to_name.rst
+   krb5_enctype_to_string.rst
+   krb5_free_checksum.rst
+   krb5_free_checksum_contents.rst
+   krb5_free_cksumtypes.rst
+   krb5_free_tgt_creds.rst
+   krb5_k_create_key.rst
+   krb5_k_decrypt.rst
+   krb5_k_decrypt_iov.rst
+   krb5_k_encrypt.rst
+   krb5_k_encrypt_iov.rst
+   krb5_k_free_key.rst
+   krb5_k_key_enctype.rst
+   krb5_k_key_keyblock.rst
+   krb5_k_make_checksum.rst
+   krb5_k_make_checksum_iov.rst
+   krb5_k_prf.rst
+   krb5_k_reference_key.rst
+   krb5_k_verify_checksum.rst
+   krb5_k_verify_checksum_iov.rst
+
+
+Legacy convenience interfaces
+------------------------------
+
+.. toctree::
+   :maxdepth: 1
+
+   krb5_recvauth.rst
+   krb5_recvauth_version.rst
+   krb5_sendauth.rst
+
+
+Deprecated public interfaces
+------------------------------
+
+.. toctree::
+   :maxdepth: 1
+
+   krb5_524_convert_creds.rst
+   krb5_auth_con_getlocalsubkey.rst
+   krb5_auth_con_getremotesubkey.rst
+   krb5_auth_con_initivector.rst
+   krb5_build_principal_va.rst
+   krb5_c_random_seed.rst
+   krb5_calculate_checksum.rst
+   krb5_checksum_size.rst
+   krb5_encrypt.rst
+   krb5_decrypt.rst
+   krb5_eblock_enctype.rst
+   krb5_encrypt_size.rst
+   krb5_finish_key.rst
+   krb5_finish_random_key.rst
+   krb5_cc_gen_new.rst
+   krb5_get_credentials_renew.rst
+   krb5_get_credentials_validate.rst
+   krb5_get_in_tkt_with_password.rst
+   krb5_get_in_tkt_with_skey.rst
+   krb5_get_in_tkt_with_keytab.rst
+   krb5_get_init_creds_opt_init.rst
+   krb5_init_random_key.rst
+   krb5_kt_free_entry.rst
+   krb5_random_key.rst
+   krb5_process_key.rst
+   krb5_string_to_key.rst
+   krb5_use_enctype.rst
+   krb5_verify_checksum.rst
diff --git a/doc/appdev/refs/index.rst b/doc/appdev/refs/index.rst
new file mode 100644
index 0000000000..6d28447169
--- /dev/null
+++ b/doc/appdev/refs/index.rst
@@ -0,0 +1,9 @@
+Complete reference - API and datatypes
+==========================================================
+
+.. toctree::
+   :maxdepth: 1
+
+   api/index.rst
+   types/index.rst
+   macros/index.rst
diff --git a/doc/appdev/refs/macros/index.rst b/doc/appdev/refs/macros/index.rst
new file mode 100644
index 0000000000..94b8244146
--- /dev/null
+++ b/doc/appdev/refs/macros/index.rst
@@ -0,0 +1,369 @@
+krb5 simple macros
+=========================
+
+Public
+-------
+
+.. toctree::
+   :maxdepth: 1
+
+   ADDRTYPE_ADDRPORT.rst
+   ADDRTYPE_CHAOS.rst
+   ADDRTYPE_DDP.rst
+   ADDRTYPE_INET.rst
+   ADDRTYPE_INET6.rst
+   ADDRTYPE_IPPORT.rst
+   ADDRTYPE_ISO.rst
+   ADDRTYPE_IS_LOCAL.rst
+   ADDRTYPE_NETBIOS.rst
+   ADDRTYPE_XNS.rst
+   AD_TYPE_EXTERNAL.rst
+   AD_TYPE_FIELD_TYPE_MASK.rst
+   AD_TYPE_REGISTERED.rst
+   AD_TYPE_RESERVED.rst
+   AP_OPTS_ETYPE_NEGOTIATION.rst
+   AP_OPTS_MUTUAL_REQUIRED.rst
+   AP_OPTS_RESERVED.rst
+   AP_OPTS_USE_SESSION_KEY.rst
+   AP_OPTS_USE_SUBKEY.rst
+   AP_OPTS_WIRE_MASK.rst
+   CKSUMTYPE_CMAC_CAMELLIA128.rst
+   CKSUMTYPE_CMAC_CAMELLIA256.rst
+   CKSUMTYPE_CRC32.rst
+   CKSUMTYPE_DESCBC.rst
+   CKSUMTYPE_HMAC_MD5_ARCFOUR.rst
+   CKSUMTYPE_HMAC_SHA1_96_AES128.rst
+   CKSUMTYPE_HMAC_SHA1_96_AES256.rst
+   CKSUMTYPE_HMAC_SHA1_DES3.rst
+   CKSUMTYPE_MD5_HMAC_ARCFOUR.rst
+   CKSUMTYPE_NIST_SHA.rst
+   CKSUMTYPE_RSA_MD4.rst
+   CKSUMTYPE_RSA_MD4_DES.rst
+   CKSUMTYPE_RSA_MD5.rst
+   CKSUMTYPE_RSA_MD5_DES.rst
+   ENCTYPE_AES128_CTS_HMAC_SHA1_96.rst
+   ENCTYPE_AES256_CTS_HMAC_SHA1_96.rst
+   ENCTYPE_ARCFOUR_HMAC.rst
+   ENCTYPE_ARCFOUR_HMAC_EXP.rst
+   ENCTYPE_CAMELLIA128_CTS_CMAC.rst
+   ENCTYPE_CAMELLIA256_CTS_CMAC.rst
+   ENCTYPE_DES3_CBC_ENV.rst
+   ENCTYPE_DES3_CBC_RAW.rst
+   ENCTYPE_DES3_CBC_SHA.rst
+   ENCTYPE_DES3_CBC_SHA1.rst
+   ENCTYPE_DES_CBC_CRC.rst
+   ENCTYPE_DES_CBC_MD4.rst
+   ENCTYPE_DES_CBC_MD5.rst
+   ENCTYPE_DES_CBC_RAW.rst
+   ENCTYPE_DES_HMAC_SHA1.rst
+   ENCTYPE_DSA_SHA1_CMS.rst
+   ENCTYPE_MD5_RSA_CMS.rst
+   ENCTYPE_NULL.rst
+   ENCTYPE_RC2_CBC_ENV.rst
+   ENCTYPE_RSA_ENV.rst
+   ENCTYPE_RSA_ES_OAEP_ENV.rst
+   ENCTYPE_SHA1_RSA_CMS.rst
+   ENCTYPE_UNKNOWN.rst
+   KDC_OPT_ALLOW_POSTDATE.rst
+   KDC_OPT_CANONICALIZE.rst
+   KDC_OPT_CNAME_IN_ADDL_TKT.rst
+   KDC_OPT_DISABLE_TRANSITED_CHECK.rst
+   KDC_OPT_ENC_TKT_IN_SKEY.rst
+   KDC_OPT_FORWARDABLE.rst
+   KDC_OPT_FORWARDED.rst
+   KDC_OPT_POSTDATED.rst
+   KDC_OPT_PROXIABLE.rst
+   KDC_OPT_PROXY.rst
+   KDC_OPT_RENEW.rst
+   KDC_OPT_RENEWABLE.rst
+   KDC_OPT_RENEWABLE_OK.rst
+   KDC_OPT_REQUEST_ANONYMOUS.rst
+   KDC_OPT_VALIDATE.rst
+   KDC_TKT_COMMON_MASK.rst
+   KRB5_ALTAUTH_ATT_CHALLENGE_RESPONSE.rst
+   KRB5_ANONYMOUS_PRINCSTR.rst
+   KRB5_ANONYMOUS_REALMSTR.rst
+   KRB5_AP_REP.rst
+   KRB5_AP_REQ.rst
+   KRB5_AS_REP.rst
+   KRB5_AS_REQ.rst
+   KRB5_AUTHDATA_AND_OR.rst
+   KRB5_AUTHDATA_ETYPE_NEGOTIATION.rst
+   KRB5_AUTHDATA_FX_ARMOR.rst
+   KRB5_AUTHDATA_IF_RELEVANT.rst
+   KRB5_AUTHDATA_INITIAL_VERIFIED_CAS.rst
+   KRB5_AUTHDATA_KDC_ISSUED.rst
+   KRB5_AUTHDATA_MANDATORY_FOR_KDC.rst
+   KRB5_AUTHDATA_OSF_DCE.rst
+   KRB5_AUTHDATA_SESAME.rst
+   KRB5_AUTHDATA_SIGNTICKET.rst
+   KRB5_AUTHDATA_WIN2K_PAC.rst
+   KRB5_AUTH_CONTEXT_DO_SEQUENCE.rst
+   KRB5_AUTH_CONTEXT_DO_TIME.rst
+   KRB5_AUTH_CONTEXT_GENERATE_LOCAL_ADDR.rst
+   KRB5_AUTH_CONTEXT_GENERATE_LOCAL_FULL_ADDR.rst
+   KRB5_AUTH_CONTEXT_GENERATE_REMOTE_ADDR.rst
+   KRB5_AUTH_CONTEXT_GENERATE_REMOTE_FULL_ADDR.rst
+   KRB5_AUTH_CONTEXT_PERMIT_ALL.rst
+   KRB5_AUTH_CONTEXT_RET_SEQUENCE.rst
+   KRB5_AUTH_CONTEXT_RET_TIME.rst
+   KRB5_AUTH_CONTEXT_USE_SUBKEY.rst
+   KRB5_CRED.rst
+   KRB5_CRYPTO_TYPE_CHECKSUM.rst
+   KRB5_CRYPTO_TYPE_DATA.rst
+   KRB5_CRYPTO_TYPE_EMPTY.rst
+   KRB5_CRYPTO_TYPE_HEADER.rst
+   KRB5_CRYPTO_TYPE_PADDING.rst
+   KRB5_CRYPTO_TYPE_SIGN_ONLY.rst
+   KRB5_CRYPTO_TYPE_STREAM.rst
+   KRB5_CRYPTO_TYPE_TRAILER.rst
+   KRB5_CYBERSAFE_SECUREID.rst
+   KRB5_DOMAIN_X500_COMPRESS.rst
+   KRB5_ENCPADATA_REQ_ENC_PA_REP.rst
+   KRB5_ERROR.rst
+   KRB5_FAST_REQUIRED.rst
+   KRB5_GC_CACHED.rst
+   KRB5_GC_CANONICALIZE.rst
+   KRB5_GC_CONSTRAINED_DELEGATION.rst
+   KRB5_GC_FORWARDABLE.rst
+   KRB5_GC_NO_STORE.rst
+   KRB5_GC_NO_TRANSIT_CHECK.rst
+   KRB5_GC_USER_USER.rst
+   KRB5_GET_INIT_CREDS_OPT_ADDRESS_LIST.rst
+   KRB5_GET_INIT_CREDS_OPT_ANONYMOUS.rst
+   KRB5_GET_INIT_CREDS_OPT_CANONICALIZE.rst
+   KRB5_GET_INIT_CREDS_OPT_CHG_PWD_PRMPT.rst
+   KRB5_GET_INIT_CREDS_OPT_ETYPE_LIST.rst
+   KRB5_GET_INIT_CREDS_OPT_FORWARDABLE.rst
+   KRB5_GET_INIT_CREDS_OPT_PREAUTH_LIST.rst
+   KRB5_GET_INIT_CREDS_OPT_PROXIABLE.rst
+   KRB5_GET_INIT_CREDS_OPT_RENEW_LIFE.rst
+   KRB5_GET_INIT_CREDS_OPT_SALT.rst
+   KRB5_GET_INIT_CREDS_OPT_TKT_LIFE.rst
+   KRB5_INIT_CONTEXT_SECURE.rst
+   KRB5_INIT_CONTEXT_KDC.rst
+   KRB5_INIT_CREDS_STEP_FLAG_CONTINUE.rst
+   KRB5_INT16_MAX.rst
+   KRB5_INT16_MIN.rst
+   KRB5_INT32_MAX.rst
+   KRB5_INT32_MIN.rst
+   KRB5_KEYUSAGE_AD_ITE.rst
+   KRB5_KEYUSAGE_AD_KDCISSUED_CKSUM.rst
+   KRB5_KEYUSAGE_AD_MTE.rst
+   KRB5_KEYUSAGE_AD_SIGNEDPATH.rst
+   KRB5_KEYUSAGE_APP_DATA_CKSUM.rst
+   KRB5_KEYUSAGE_APP_DATA_ENCRYPT.rst
+   KRB5_KEYUSAGE_AP_REP_ENCPART.rst
+   KRB5_KEYUSAGE_AP_REQ_AUTH.rst
+   KRB5_KEYUSAGE_AP_REQ_AUTH_CKSUM.rst
+   KRB5_KEYUSAGE_AS_REP_ENCPART.rst
+   KRB5_KEYUSAGE_AS_REQ.rst
+   KRB5_KEYUSAGE_AS_REQ_PA_ENC_TS.rst
+   KRB5_KEYUSAGE_ENC_CHALLENGE_CLIENT.rst
+   KRB5_KEYUSAGE_ENC_CHALLENGE_KDC.rst
+   KRB5_KEYUSAGE_FAST_ENC.rst
+   KRB5_KEYUSAGE_FAST_FINISHED.rst
+   KRB5_KEYUSAGE_FAST_REP.rst
+   KRB5_KEYUSAGE_FAST_REQ_CHKSUM.rst
+   KRB5_KEYUSAGE_GSS_TOK_MIC.rst
+   KRB5_KEYUSAGE_GSS_TOK_WRAP_INTEG.rst
+   KRB5_KEYUSAGE_GSS_TOK_WRAP_PRIV.rst
+   KRB5_KEYUSAGE_IAKERB_FINISHED.rst
+   KRB5_KEYUSAGE_KDC_REP_TICKET.rst
+   KRB5_KEYUSAGE_KRB_CRED_ENCPART.rst
+   KRB5_KEYUSAGE_KRB_ERROR_CKSUM.rst
+   KRB5_KEYUSAGE_KRB_PRIV_ENCPART.rst
+   KRB5_KEYUSAGE_KRB_SAFE_CKSUM.rst
+   KRB5_KEYUSAGE_PA_OTP_REQUEST.rst
+   KRB5_KEYUSAGE_PA_PKINIT_KX.rst
+   KRB5_KEYUSAGE_PA_REFERRAL.rst
+   KRB5_KEYUSAGE_PA_S4U_X509_USER_REPLY.rst
+   KRB5_KEYUSAGE_PA_S4U_X509_USER_REQUEST.rst
+   KRB5_KEYUSAGE_PA_SAM_CHALLENGE_CKSUM.rst
+   KRB5_KEYUSAGE_PA_SAM_CHALLENGE_TRACKID.rst
+   KRB5_KEYUSAGE_PA_SAM_RESPONSE.rst
+   KRB5_KEYUSAGE_TGS_REP_ENCPART_SESSKEY.rst
+   KRB5_KEYUSAGE_TGS_REP_ENCPART_SUBKEY.rst
+   KRB5_KEYUSAGE_TGS_REQ_AD_SESSKEY.rst
+   KRB5_KEYUSAGE_TGS_REQ_AD_SUBKEY.rst
+   KRB5_KEYUSAGE_TGS_REQ_AUTH.rst
+   KRB5_KEYUSAGE_TGS_REQ_AUTH_CKSUM.rst
+   KRB5_KPASSWD_ACCESSDENIED.rst
+   KRB5_KPASSWD_AUTHERROR.rst
+   KRB5_KPASSWD_BAD_VERSION.rst
+   KRB5_KPASSWD_HARDERROR.rst
+   KRB5_KPASSWD_INITIAL_FLAG_NEEDED.rst
+   KRB5_KPASSWD_MALFORMED.rst
+   KRB5_KPASSWD_SOFTERROR.rst
+   KRB5_KPASSWD_SUCCESS.rst
+   KRB5_LRQ_ALL_ACCT_EXPTIME.rst
+   KRB5_LRQ_ALL_LAST_INITIAL.rst
+   KRB5_LRQ_ALL_LAST_RENEWAL.rst
+   KRB5_LRQ_ALL_LAST_REQ.rst
+   KRB5_LRQ_ALL_LAST_TGT.rst
+   KRB5_LRQ_ALL_LAST_TGT_ISSUED.rst
+   KRB5_LRQ_ALL_PW_EXPTIME.rst
+   KRB5_LRQ_NONE.rst
+   KRB5_LRQ_ONE_ACCT_EXPTIME.rst
+   KRB5_LRQ_ONE_LAST_INITIAL.rst
+   KRB5_LRQ_ONE_LAST_RENEWAL.rst
+   KRB5_LRQ_ONE_LAST_REQ.rst
+   KRB5_LRQ_ONE_LAST_TGT.rst
+   KRB5_LRQ_ONE_LAST_TGT_ISSUED.rst
+   KRB5_LRQ_ONE_PW_EXPTIME.rst
+   KRB5_NT_ENTERPRISE_PRINCIPAL.rst
+   KRB5_NT_ENT_PRINCIPAL_AND_ID.rst
+   KRB5_NT_MS_PRINCIPAL.rst
+   KRB5_NT_MS_PRINCIPAL_AND_ID.rst
+   KRB5_NT_PRINCIPAL.rst
+   KRB5_NT_SMTP_NAME.rst
+   KRB5_NT_SRV_HST.rst
+   KRB5_NT_SRV_INST.rst
+   KRB5_NT_SRV_XHST.rst
+   KRB5_NT_UID.rst
+   KRB5_NT_UNKNOWN.rst
+   KRB5_NT_WELLKNOWN.rst
+   KRB5_NT_X500_PRINCIPAL.rst
+   KRB5_OLD_CRYPTO.rst
+   KRB5_PAC_CLIENT_INFO.rst
+   KRB5_PAC_CREDENTIALS_INFO.rst
+   KRB5_PAC_DELEGATION_INFO.rst
+   KRB5_PAC_LOGON_INFO.rst
+   KRB5_PAC_PRIVSVR_CHECKSUM.rst
+   KRB5_PAC_SERVER_CHECKSUM.rst
+   KRB5_PAC_UPN_DNS_INFO.rst
+   KRB5_PADATA_AFS3_SALT.rst
+   KRB5_PADATA_AP_REQ.rst
+   KRB5_PADATA_ENCRYPTED_CHALLENGE.rst
+   KRB5_PADATA_ENC_SANDIA_SECURID.rst
+   KRB5_PADATA_ENC_TIMESTAMP.rst
+   KRB5_PADATA_ENC_UNIX_TIME.rst
+   KRB5_PADATA_ETYPE_INFO.rst
+   KRB5_PADATA_ETYPE_INFO2.rst
+   KRB5_PADATA_FOR_USER.rst
+   KRB5_PADATA_FX_COOKIE.rst
+   KRB5_PADATA_FX_ERROR.rst
+   KRB5_PADATA_FX_FAST.rst
+   KRB5_PADATA_GET_FROM_TYPED_DATA.rst
+   KRB5_PADATA_NONE.rst
+   KRB5_PADATA_OSF_DCE.rst
+   KRB5_PADATA_OTP_CHALLENGE.rst
+   KRB5_PADATA_OTP_PIN_CHANGE.rst
+   KRB5_PADATA_OTP_REQUEST.rst
+   KRB5_PADATA_PAC_REQUEST.rst
+   KRB5_PADATA_PKINIT_KX.rst
+   KRB5_PADATA_PK_AS_REP.rst
+   KRB5_PADATA_PK_AS_REP_OLD.rst
+   KRB5_PADATA_PK_AS_REQ.rst
+   KRB5_PADATA_PK_AS_REQ_OLD.rst
+   KRB5_PADATA_PW_SALT.rst
+   KRB5_PADATA_REFERRAL.rst
+   KRB5_PADATA_S4U_X509_USER.rst
+   KRB5_PADATA_SAM_CHALLENGE.rst
+   KRB5_PADATA_SAM_CHALLENGE_2.rst
+   KRB5_PADATA_SAM_REDIRECT.rst
+   KRB5_PADATA_SAM_RESPONSE.rst
+   KRB5_PADATA_SAM_RESPONSE_2.rst
+   KRB5_PADATA_SESAME.rst
+   KRB5_PADATA_SVR_REFERRAL_INFO.rst
+   KRB5_PADATA_TGS_REQ.rst
+   KRB5_PADATA_USE_SPECIFIED_KVNO.rst
+   KRB5_PRINCIPAL_COMPARE_CASEFOLD.rst
+   KRB5_PRINCIPAL_COMPARE_ENTERPRISE.rst
+   KRB5_PRINCIPAL_COMPARE_IGNORE_REALM.rst
+   KRB5_PRINCIPAL_COMPARE_UTF8.rst
+   KRB5_PRINCIPAL_PARSE_ENTERPRISE.rst
+   KRB5_PRINCIPAL_PARSE_IGNORE_REALM.rst
+   KRB5_PRINCIPAL_PARSE_NO_REALM.rst
+   KRB5_PRINCIPAL_PARSE_REQUIRE_REALM.rst
+   KRB5_PRINCIPAL_UNPARSE_DISPLAY.rst
+   KRB5_PRINCIPAL_UNPARSE_NO_REALM.rst
+   KRB5_PRINCIPAL_UNPARSE_SHORT.rst
+   KRB5_PRIV.rst
+   KRB5_PROMPT_TYPE_NEW_PASSWORD.rst
+   KRB5_PROMPT_TYPE_NEW_PASSWORD_AGAIN.rst
+   KRB5_PROMPT_TYPE_PASSWORD.rst
+   KRB5_PROMPT_TYPE_PREAUTH.rst
+   KRB5_PVNO.rst
+   KRB5_REALM_BRANCH_CHAR.rst
+   KRB5_RECVAUTH_BADAUTHVERS.rst
+   KRB5_RECVAUTH_SKIP_VERSION.rst
+   KRB5_REFERRAL_REALM.rst
+   KRB5_RESPONDER_OTP_FLAGS_COLLECT_PIN.rst
+   KRB5_RESPONDER_OTP_FLAGS_COLLECT_TOKEN.rst
+   KRB5_RESPONDER_OTP_FLAGS_NEXTOTP.rst
+   KRB5_RESPONDER_OTP_FLAGS_SEPARATE_PIN.rst
+   KRB5_RESPONDER_OTP_FORMAT_ALPHANUMERIC.rst
+   KRB5_RESPONDER_OTP_FORMAT_DECIMAL.rst
+   KRB5_RESPONDER_OTP_FORMAT_HEXADECIMAL.rst
+   KRB5_RESPONDER_QUESTION_OTP.rst
+   KRB5_RESPONDER_QUESTION_PASSWORD.rst
+   KRB5_SAFE.rst
+   KRB5_SAM_MUST_PK_ENCRYPT_SAD.rst
+   KRB5_SAM_SEND_ENCRYPTED_SAD.rst
+   KRB5_SAM_USE_SAD_AS_KEY.rst
+   KRB5_TC_MATCH_2ND_TKT.rst
+   KRB5_TC_MATCH_AUTHDATA.rst
+   KRB5_TC_MATCH_FLAGS.rst
+   KRB5_TC_MATCH_FLAGS_EXACT.rst
+   KRB5_TC_MATCH_IS_SKEY.rst
+   KRB5_TC_MATCH_KTYPE.rst
+   KRB5_TC_MATCH_SRV_NAMEONLY.rst
+   KRB5_TC_MATCH_TIMES.rst
+   KRB5_TC_MATCH_TIMES_EXACT.rst
+   KRB5_TC_NOTICKET.rst
+   KRB5_TC_OPENCLOSE.rst
+   KRB5_TC_SUPPORTED_KTYPES.rst
+   KRB5_TGS_NAME.rst
+   KRB5_TGS_NAME_SIZE.rst
+   KRB5_TGS_REP.rst
+   KRB5_TGS_REQ.rst
+   KRB5_TKT_CREDS_STEP_FLAG_CONTINUE.rst
+   KRB5_VERIFY_INIT_CREDS_OPT_AP_REQ_NOFAIL.rst
+   KRB5_WELLKNOWN_NAMESTR.rst
+   LR_TYPE_INTERPRETATION_MASK.rst
+   LR_TYPE_THIS_SERVER_ONLY.rst
+   MAX_KEYTAB_NAME_LEN.rst
+   MSEC_DIRBIT.rst
+   MSEC_VAL_MASK.rst
+   SALT_TYPE_AFS_LENGTH.rst
+   SALT_TYPE_NO_LENGTH.rst
+   THREEPARAMOPEN.rst
+   TKT_FLG_ANONYMOUS.rst
+   TKT_FLG_ENC_PA_REP.rst
+   TKT_FLG_FORWARDABLE.rst
+   TKT_FLG_FORWARDED.rst
+   TKT_FLG_HW_AUTH.rst
+   TKT_FLG_INITIAL.rst
+   TKT_FLG_INVALID.rst
+   TKT_FLG_MAY_POSTDATE.rst
+   TKT_FLG_OK_AS_DELEGATE.rst
+   TKT_FLG_POSTDATED.rst
+   TKT_FLG_PRE_AUTH.rst
+   TKT_FLG_PROXIABLE.rst
+   TKT_FLG_PROXY.rst
+   TKT_FLG_RENEWABLE.rst
+   TKT_FLG_TRANSIT_POLICY_CHECKED.rst
+   VALID_INT_BITS.rst
+   VALID_UINT_BITS.rst
+   krb5_const.rst
+   krb5_princ_component.rst
+   krb5_princ_name.rst
+   krb5_princ_realm.rst
+   krb5_princ_set_realm.rst
+   krb5_princ_set_realm_data.rst
+   krb5_princ_set_realm_length.rst
+   krb5_princ_size.rst
+   krb5_princ_type.rst
+   krb5_roundup.rst
+   krb5_x.rst
+   krb5_xc.rst
+
+Deprecated macros
+------------------------------
+
+.. toctree::
+   :maxdepth: 1
+
+   krb524_convert_creds_kdc.rst
+   krb524_init_ets.rst
diff --git a/doc/appdev/refs/types/index.rst b/doc/appdev/refs/types/index.rst
new file mode 100644
index 0000000000..23d9d125fc
--- /dev/null
+++ b/doc/appdev/refs/types/index.rst
@@ -0,0 +1,103 @@
+krb5 types and structures
+=========================
+
+Public
+-------
+
+.. toctree::
+   :maxdepth: 1
+
+   krb5_address.rst
+   krb5_addrtype.rst
+   krb5_ap_req.rst
+   krb5_ap_rep.rst
+   krb5_ap_rep_enc_part.rst
+   krb5_authdata.rst
+   krb5_authdatatype.rst
+   krb5_authenticator.rst
+   krb5_boolean.rst
+   krb5_checksum.rst
+   krb5_const_pointer.rst
+   krb5_const_principal.rst
+   krb5_cred.rst
+   krb5_cred_enc_part.rst
+   krb5_cred_info.rst
+   krb5_creds.rst
+   krb5_crypto_iov.rst
+   krb5_cryptotype.rst
+   krb5_data.rst
+   krb5_deltat.rst
+   krb5_enc_data.rst
+   krb5_enc_kdc_rep_part.rst
+   krb5_enc_tkt_part.rst
+   krb5_encrypt_block.rst
+   krb5_enctype.rst
+   krb5_error.rst
+   krb5_error_code.rst
+   krb5_expire_callback_func.rst
+   krb5_flags.rst
+   krb5_get_init_creds_opt.rst
+   krb5_gic_opt_pa_data.rst
+   krb5_int32.rst
+   krb5_kdc_rep.rst
+   krb5_kdc_req.rst
+   krb5_keyblock.rst
+   krb5_keytab_entry.rst
+   krb5_keyusage.rst
+   krb5_kt_cursor.rst
+   krb5_kvno.rst
+   krb5_last_req_entry.rst
+   krb5_magic.rst
+   krb5_mk_req_checksum_func.rst
+   krb5_msgtype.rst
+   krb5_octet.rst
+   krb5_octet_data.rst
+   krb5_pa_pac_req.rst
+   krb5_pa_server_referral_data.rst
+   krb5_pa_svr_referral_data.rst
+   krb5_pa_data.rst
+   krb5_pointer.rst
+   krb5_preauthtype.rst
+   krb5_principal.rst
+   krb5_principal_data.rst
+   krb5_const_principal.rst
+   krb5_prompt.rst
+   krb5_prompt_type.rst
+   krb5_prompter_fct.rst
+   krb5_pwd_data.rst
+   krb5_responder_fn.rst
+   krb5_responder_otp_challenge.rst
+   krb5_responder_otp_tokeninfo.rst
+   krb5_response.rst
+   krb5_replay_data.rst
+   krb5_ticket.rst
+   krb5_ticket_times.rst
+   krb5_timestamp.rst
+   krb5_tkt_authent.rst
+   krb5_trace_callback.rst
+   krb5_trace_info.rst
+   krb5_transited.rst
+   krb5_typed_data.rst
+   krb5_ui_4.rst
+   krb5_verify_init_creds_opt.rst
+   passwd_phrase_element.rst
+
+
+Internal
+---------
+
+.. toctree::
+   :maxdepth: 1
+
+   krb5_auth_context.rst
+   krb5_cksumtype
+   krb5_context.rst
+   krb5_cc_cursor.rst
+   krb5_ccache.rst
+   krb5_cccol_cursor.rst
+   krb5_init_creds_context.rst
+   krb5_key.rst
+   krb5_keytab.rst
+   krb5_pac.rst
+   krb5_rcache.rst
+   krb5_tkt_creds_context.rst
diff --git a/doc/appdev/refs/types/krb5_int32.rst b/doc/appdev/refs/types/krb5_int32.rst
new file mode 100644
index 0000000000..2bc914b3cd
--- /dev/null
+++ b/doc/appdev/refs/types/krb5_int32.rst
@@ -0,0 +1,12 @@
+.. highlightlang:: c
+
+.. _krb5-int32-struct:
+
+krb5_int32
+==========
+
+..
+.. c:type:: krb5_int32
+..
+
+krb5_int32 is a signed 32-bit integer type
diff --git a/doc/appdev/refs/types/krb5_ui_4.rst b/doc/appdev/refs/types/krb5_ui_4.rst
new file mode 100644
index 0000000000..de79bafe19
--- /dev/null
+++ b/doc/appdev/refs/types/krb5_ui_4.rst
@@ -0,0 +1,12 @@
+.. highlightlang:: c
+
+.. _krb5-ui4-struct:
+
+krb5_ui_4
+==========
+
+..
+.. c:type:: krb5_ui_4
+..
+
+krb5_ui_4 is an unsigned 32-bit integer type.