doc/kadm5-errmsg.txt

   1 Proposed approach for passing more detailed error messages across the
   2 kadm5 API:
   3
   4 We've already got too many init functions and too many options.
   5 Multiplying the number of init functions isn't feasible.
   6
   7 Create an (opaque to application) init-options type, create/destroy
   8 functions for it, set-creds/set-keytab/set-password functions, and a
   9 kadm5-init-with-options function.  (Optional: Reimplement the current
  10 init functions as wrappers around these.)
  11
  12 Add a set-context function which saves away in the init-options object
  13 a krb5_context to be used in the new server handle instead of creating
  14 a new one.  (Destroying a server handle with such a "borrowed" krb5
  15 context should probably not destroy the context.)  Calls within the
  16 library should store any error messages in the context contained in
  17 the server handle.  Error messages produced during initialization
  18 should also be stored in this context.
  19
  20 The caller of these functions can use krb5_get_error_message to
  21 extract the text of the error message from the supplied context.
  22
  23 Unless we determine it's safe, we should probably assert (for now)
  24 that each server handle must have a different context.  (That's aside
  25 from the thread safety issues.)
  26
  27 These contexts should have been created with kadm5_init_krb5_context,
  28 which will decide whether to look at the KDC config file depending on
  29 whether you're using the client-side or server-side version of the
  30 library.  (Same as for kadmin vs kadmin.local.)
  31
  32 Notes:
  33
  34  * The existing API must continue to work, without changes.  There is
  35    external code we need to continue to support.
  36
  37  * We considered a variant where the application could retrieve the
  38    error message from the server handle using a new
  39    kadm5_get_error_message function.  However, the initialization code
  40    is one likely place where the errors would occur (can't
  41    authenticate, etc), and in that case, there is no server handle
  42    from which to extract the context.
  43
  44    A function to retrieve the library-created krb5_context from the
  45    server handle would have the same problem.
  46
  47    Using a separate approach to deal with errors at initialization
  48    time, in combination with the above, might work.  But we still wind
  49    up either creating the init-with-options interface or adding
  50    error-message-return variants of multiple existing init functions.
  51
  52 To do:
  53
  54  * Write up specifics (including function names -- the names used here
  55    aren't meant to be definitive) and discuss on krbdev.
  56
  57  * Implement library part.
  58
  59  * Change kadmin and kdc to use it.