Draft initial credentials API documentation

git-svn-id: svn://anonsvn.mit.edu/krb5/trunk@25835 dc483132-0cff-0310-8789-dd5450dbe970

2 files changed, 60 insertions, 0 deletions

diff --git a/doc/rst_source/krb_appldev/index.rst b/doc/rst_source/krb_appldev/index.rst
index dd0ec5388..3d62045ca 100644
--- a/doc/rst_source/krb_appldev/index.rst
+++ b/doc/rst_source/krb_appldev/index.rst
@@ -6,6 +6,7 @@ For application developers
 
    gssapi.rst
    h5l_mit_apidiff.rst
+   init_creds.rst
    princ_handle.rst
 
 .. toctree::
diff --git a/doc/rst_source/krb_appldev/init_creds.rst b/doc/rst_source/krb_appldev/init_creds.rst
new file mode 100644
index 000000000..0750bd82b
--- /dev/null
+++ b/doc/rst_source/krb_appldev/init_creds.rst
@@ -0,0 +1,59 @@
+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.
+
+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.