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 84331b1ae0306440a96368015bcd94694403edf0..0ec8fb6d666dfe3c31c009bcf7d2cd8a6219839c 100644 (file)
--- 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 f6012f778c9154cbf3c4cf90d077ab07f85c6446..1fc81d19bb77ac9469dec684f8ce7fbb9a3ba7b1 100644 (file)
--- 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
 ----------------