1*7f2fe78bSCy SchubertClient preauthentication interface (clpreauth) 2*7f2fe78bSCy Schubert============================================== 3*7f2fe78bSCy Schubert 4*7f2fe78bSCy SchubertDuring an initial ticket request, a KDC may ask a client to prove its 5*7f2fe78bSCy Schubertknowledge of the password before issuing an encrypted ticket, or to 6*7f2fe78bSCy Schubertuse credentials other than a password. This process is called 7*7f2fe78bSCy Schubertpreauthentication, and is described in :rfc:`4120` and :rfc:`6113`. 8*7f2fe78bSCy SchubertThe clpreauth interface allows the addition of client support for 9*7f2fe78bSCy Schubertpreauthentication mechanisms beyond those included in the core MIT 10*7f2fe78bSCy Schubertkrb5 code base. For a detailed description of the clpreauth 11*7f2fe78bSCy Schubertinterface, see the header file ``<krb5/clpreauth_plugin.h>`` (or 12*7f2fe78bSCy Schubert``<krb5/preauth_plugin.h>`` before release 1.12). 13*7f2fe78bSCy Schubert 14*7f2fe78bSCy SchubertA clpreauth module is generally responsible for: 15*7f2fe78bSCy Schubert 16*7f2fe78bSCy Schubert* Supplying a list of preauth type numbers used by the module in the 17*7f2fe78bSCy Schubert **pa_type_list** field of the vtable structure. 18*7f2fe78bSCy Schubert 19*7f2fe78bSCy Schubert* Indicating what kind of preauthentication mechanism it implements, 20*7f2fe78bSCy Schubert with the **flags** method. In the most common case, this method 21*7f2fe78bSCy Schubert just returns ``PA_REAL``, indicating that it implements a normal 22*7f2fe78bSCy Schubert preauthentication type. 23*7f2fe78bSCy Schubert 24*7f2fe78bSCy Schubert* Examining the padata information included in a PREAUTH_REQUIRED or 25*7f2fe78bSCy Schubert MORE_PREAUTH_DATA_REQUIRED error and producing padata values for the 26*7f2fe78bSCy Schubert next AS request. This is done with the **process** method. 27*7f2fe78bSCy Schubert 28*7f2fe78bSCy Schubert* Examining the padata information included in a successful ticket 29*7f2fe78bSCy Schubert reply, possibly verifying the KDC identity and computing a reply 30*7f2fe78bSCy Schubert key. This is also done with the **process** method. 31*7f2fe78bSCy Schubert 32*7f2fe78bSCy Schubert* For preauthentication types which support it, recovering from errors 33*7f2fe78bSCy Schubert by examining the error data from the KDC and producing a padata 34*7f2fe78bSCy Schubert value for another AS request. This is done with the **tryagain** 35*7f2fe78bSCy Schubert method. 36*7f2fe78bSCy Schubert 37*7f2fe78bSCy Schubert* Receiving option information (supplied by ``kinit -X`` or by an 38*7f2fe78bSCy Schubert application), with the **gic_opts** method. 39*7f2fe78bSCy Schubert 40*7f2fe78bSCy SchubertA clpreauth module can create and destroy per-library-context and 41*7f2fe78bSCy Schubertper-request state objects by implementing the **init**, **fini**, 42*7f2fe78bSCy Schubert**request_init**, and **request_fini** methods. Per-context state 43*7f2fe78bSCy Schubertobjects have the type krb5_clpreauth_moddata, and per-request state 44*7f2fe78bSCy Schubertobjects have the type krb5_clpreauth_modreq. These are abstract 45*7f2fe78bSCy Schubertpointer types; a module should typically cast these to internal 46*7f2fe78bSCy Schuberttypes for the state objects. 47*7f2fe78bSCy Schubert 48*7f2fe78bSCy SchubertThe **process** and **tryagain** methods have access to a callback 49*7f2fe78bSCy Schubertfunction and handle (called a "rock") which can be used to get 50*7f2fe78bSCy Schubertadditional information about the current request, including the 51*7f2fe78bSCy Schubertexpected enctype of the AS reply, the FAST armor key, and the client 52*7f2fe78bSCy Schubertlong-term key (prompting for the user password if necessary). A 53*7f2fe78bSCy Schubertcallback can also be used to replace the AS reply key if the 54*7f2fe78bSCy Schubertpreauthentication mechanism computes one. 55