svn rev #25835: trunk/doc/rst_source/krb_appldev/

[tlyu@MIT.EDU]

http://src.mit.edu/fisheye/changelog/krb5/?cs=25835
Commit By: tlyu
Log Message:
Draft initial credentials API documentation


Changed Files:
U   trunk/doc/rst_source/krb_appldev/index.rst
A   trunk/doc/rst_source/krb_appldev/init_creds.rst
Modified: trunk/doc/rst_source/krb_appldev/index.rst
===================================================================
--- trunk/doc/rst_source/krb_appldev/index.rst	2012-04-27 17:13:23 UTC (rev 25834)
+++ trunk/doc/rst_source/krb_appldev/index.rst	2012-04-27 20:39:13 UTC (rev 25835)
@@ -6,6 +6,7 @@
 
    gssapi.rst
    h5l_mit_apidiff.rst
+   init_creds.rst
    princ_handle.rst
 
 .. toctree::

Added: trunk/doc/rst_source/krb_appldev/init_creds.rst
===================================================================
--- trunk/doc/rst_source/krb_appldev/init_creds.rst	                        (rev 0)
+++ trunk/doc/rst_source/krb_appldev/init_creds.rst	2012-04-27 20:39:13 UTC (rev 25835)
@@ -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.