From: Greg Hudson <ghudson@mit.edu>
Date: Wed, 12 Dec 2012 20:46:41 +0000 (-0500)
Subject: Document API for getting anonymous tickets
X-Git-Tag: krb5-1.12-alpha1~422
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=9973812776fc69bc5fb8e3c7f85784cb295625f0;p=thirdparty%2Fkrb5.git

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
---

diff --git a/doc/admin/pkinit.rst b/doc/admin/pkinit.rst
index 84331b1ae0..0ec8fb6d66 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 f6012f778c..1fc81d19bb 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@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
 ----------------