doc/html/_sources/plugindev/clpreauth.txt

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