From 0e5252ec1778d3421122f2ee95c88e8b1b77e383 Mon Sep 17 00:00:00 2001 From: Greg Hudson Date: Thu, 8 Mar 2012 22:38:58 +0000 Subject: Add pluggable interface RST documentation Create a new top-level section for plugin module developers. Document the general conventions for pluggable interfaces and an overview of each existing interface (except for GSSAPI mechanisms). Since we're not currently generating doxygen markup for plugin interface headers, refer to header files for detail-level documentation for now. git-svn-id: svn://anonsvn.mit.edu/krb5/trunk@25759 dc483132-0cff-0310-8789-dd5450dbe970 --- doc/rst_source/krb_plugindev/clpreauth.rst | 53 ++++++++++++++++++++++++++++++ 1 file changed, 53 insertions(+) create mode 100644 doc/rst_source/krb_plugindev/clpreauth.rst (limited to 'doc/rst_source/krb_plugindev/clpreauth.rst') diff --git a/doc/rst_source/krb_plugindev/clpreauth.rst b/doc/rst_source/krb_plugindev/clpreauth.rst new file mode 100644 index 000000000..68e56aa5f --- /dev/null +++ b/doc/rst_source/krb_plugindev/clpreauth.rst @@ -0,0 +1,53 @@ +Client preauthentication interface (clpreauth) +============================================== + +During an initial ticket request, a KDC may ask a client to prove its +knowledge of the password before issuing an encrypted ticket, or to +use credentials other than a password. This process is called +preauthentication, and is described in :rfc:`4120` and :rfc:`6113`. +The clpreauth interface allows the addition of client support for +preauthentication mechanisms beyond those included in the core MIT +krb5 code base. For a detailed description of the clpreauth +interface, see the header file ````. + +A clpreauth module is generally responsible for: + +* Supplying a list of preauth type numbers used by the module in the + **pa_type_list** field of the vtable structure. + +* Indicating what kind of preauthentication mechanism it implements, + with the **flags** method. In the most common case, this method + just returns ``PA_REAL``, indicating that it implements a normal + preauthentication type. + +* Examining the padata information included in the preauth_required + error and producing padata values for the next AS request. This is + done with the **process** method. + +* Examining the padata information included in a successful ticket + reply, possibly verifying the KDC identity and computing a reply + key. This is also done with the **process** method. + +* For preauthentication types which support it, recovering from errors + by examining the error data from the KDC and producing a padata + value for another AS request. This is done with the **tryagain** + method. + +* Receiving option information (supplied by ``kinit -X`` or by an + application), with the **gic_opts** method. + +A clpreauth module can create and destroy per-library-context and +per-request state objects by implementing the **init**, **fini**, +**request_init**, and **request_fini** methods. Per-context state +objects have the type krb5_clpreauth_moddata, and per-request state +objects have the type krb5_clpreauth_modreq. These are abstract +pointer types; a module should typically cast these to internal +types for the state objects. + +The **process** and **tryagain** methods have access to a callback +function and handle (called a "rock") which can be used to get +additional information about the current request, including the +expected enctype of the AS reply, the FAST armor key, and the client +long-term key (prompting for the user password if necessary). A +callback can also be used to replace the AS reply key if the +preauthentication mechanism computes one. -- cgit