Debugging API for krb5

[Ken Raeburn]

The list below was originally entitled "some thoughts on logging", and 
I was going to work on it a bit more before sending it, but since Jeff 
has brought it up....

I agree with Sam that 32 flags might not be enough.  I think we could 
use an array and an offset into it, with each flag being the offset, 
not a mask.  Initially, it probably would only have one element, but we 
might expand it quickly.  libkrb5-tgs, libkrb5-as, libkrb5-ap, kdc-tgs, 
kdc-as, kdb, kdb-db2, kdb-mysql, krb524, krb4-tgs, krb4-as, krb4-ap, 
libkrb5-sendto, crypto, fake-getaddrinfo, gsssapi, pty, I'm sure we 
could come up with other cases where we want to debug only one aspect 
of the code.

The syslog approach of having a "level" orthogonal to the "facility" 
seems useful.  We could send serious problems (e.g., keytab format 
errors) to syslog by default, leave informational and debugging 
messages off unless requested.  Might we want another separate flag for 
whether or not hex dumps should be logged?

I think I'd like to have the option of a textual form for specifying 
the parts of code for which debugging is enabled.  Numeric is okay, but 
if we do only numeric, we should at least make sure to support a hex 
option, and support more than 32 flags.  (Arbitrary hex string to fill 
an array of unsigned char?)

Some other random thoughts:

  * A printf-like function that is Kerberos-aware would be handy.  I did 
something like that for sendto_kdc, with %E for krb5_error_code 
(displays as numeric and text), %m for an errno value (like syslog, but 
passed in instead of global), %F for select file descriptor set (a 
structure I set up in that code, in/out/except fd sets plus timeout), 
%s/%d/%p like printf but without widths, %t for struct timeval, %A for 
struct addrinfo, %D for krb5_data (raw dump).  Add more, like principal 
name display etc.

  * compile-time checking for the debug calls would be nice, but 
conflicts with the above

  * "dump out this block in hex and ascii"; I've written that some 3 or 
4 times now.  For non-ascii dumps, probably want two forms, one for 
short byte strings, all in one line, maybe without spaces, and another 
for big blocks, with line breaks and maybe offsets and such.

  * should be able to compile in by default, leaving it disabled (but we 
currently dump the enctype list in KDC requests?)

  * logging for administrative reporting and debugging are not the same 
thing, though they can probably use some of the same code.  (Perhaps we 
should log enctype lists separately from other data in KDC requests?)

  * switching between stderr and syslog and log file is a nice option; 
select through config file?

  * log file name and line number, maybe function name as well if 
available; try to do it through macros so as to require much less 
typing to instrument code; could be as easy as #define HERE 
__FILE__,__LINE__,__func__/NULL

  * annotate lots of error returns in libraries, especially when 
multiple causes are possible

  * be able to switch on and off logging for various parts of the code 
(crypto, kdc, libkrb5, gss, maybe finer control?).  maybe multiple flag 
variables, maybe multiple bits in a vector.  Probably test at call site 
via macro or inline function?

  * log "e-text" field in "generic error" case

  * short name for convenience, even if via macro, since we'll be typing 
it a lot, and calling it with long strings that don't look good when 
they wrap