krb5 commit: Document API for getting anonymous tickets

[Greg Hudson]

https://github.com/krb5/krb5/commit/9973812776fc69bc5fb8e3c7f85784cb295625f0
commit 9973812776fc69bc5fb8e3c7f85784cb295625f0
Author: Greg Hudson <ghudson at mit.edu>
Date:   Wed Dec 12 15:46:41 2012 -0500

    Document API for getting anonymous tickets
    
    In init_creds.rst, document how to get anonymous credentials from an
    application.
    
    ticket: 7496 (new)
    target_version: 1.11
    tags: pullup

 doc/admin/pkinit.rst      |    2 ++
 doc/appdev/init_creds.rst |   26 ++++++++++++++++++++++++++
 2 files changed, 28 insertions(+), 0 deletions(-)

diff --git a/doc/admin/pkinit.rst b/doc/admin/pkinit.rst
index 84331b1..0ec8fb6 100644
--- a/doc/admin/pkinit.rst
+++ b/doc/admin/pkinit.rst
@@ -181,6 +181,8 @@ If the KDC and client are properly configured, it should now be
 possible to run ``kinit username`` without entering a password.
 
 
+.. _anonymous_pkinit:
+
 Anonymous PKINIT
 ----------------
 
diff --git a/doc/appdev/init_creds.rst b/doc/appdev/init_creds.rst
index f6012f7..1fc81d1 100644
--- a/doc/appdev/init_creds.rst
+++ b/doc/appdev/init_creds.rst
@@ -34,6 +34,32 @@ 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.
 
+Getting anonymous credentials
+-----------------------------
+
+As of release 1.8, it is possible to obtain fully anonymous or
+partially anonymous (realm-exposed) credentials, if the KDC supports
+it.  The MIT KDC supports issuing fully anonymous credentials as of
+release 1.8 if configured appropriately (see :ref:`anonymous_pkinit`),
+but does not support issuing realm-exposed anonymous credentials at
+this time.
+
+To obtain fully anonymous credentials, call
+:c:func:`krb5_get_init_creds_opt_set_anonymous` on the options
+structure to set the anonymous flag, and specify a client principal
+with the KDC's realm and a single empty data component (the principal
+obtained by parsing ``@``\ *realmname*).  Authentication will take
+place using anonymous PKINIT; if successful, the client principal of
+the resulting tickets will be
+``WELLKNOWN/ANONYMOUS at WELLKNOWN:ANONYMOUS``.
+
+To obtain realm-exposed anonymous credentials, set the anonymous flag
+on the options structure as above, but specify a normal client
+principal in order to prove membership in the realm.  Authentication
+will take place as it normally does; if successful, the client
+principal of the resulting tickets will be ``WELLKNOWN/ANONYMOUS@``\
+*realmname*.
+
 User interaction
 ----------------