Projects/Trace logging

This is an early stage project for MIT Kerberos. It is being fleshed out by its proponents. Feel free to help flesh out the details of this project. After the project is ready, it will be presented for review and approval.

Background

Multiple users of Kerberos have expressed a desire for logging to assist in the diagnosis of configuration failures. As a secondary benefit, such a facility may also be useful for debugging work by Kerberos developers. Requirements include:

• It is sufficient to be able to be able to log to a file specified by an environment variable.
• It is important that it be possible to enable trace logging in a standard build, such as the one shipped by the operating system vendor, because it is generally not possible to substitute specially compiled code in a customer deployment.
• The facility must not compromise the security of setuid programs by allowing the invoking user to leak information or write log files using elevated privileges.
• The facility must have a minimal impact on performance when not enabled.
• It should be possible to explicitly disable the facility at compile-time for embedded deployments or kernel code.

User Interface

To turn on tracing, the user will set the KRB5_TRACE variable to a filename. This will not work for secure contexts.

To disable tracing at compile time, the builder will specify --disable-tracing to configure.

Design

The programmer interface will be through k5trace(), which has the following signature:

 void k5trace(krb5_context context, const char *fmt, ...)

Tracing calls will use a custom formatter, adapted from the debugging code previously in lib/krb5/os/sendto_kdc.c, to facilitate the display of principal names, krb5_data structures, and the like.

For performance reasons, k5trace() will be a macro (if variadic macros are supported by the compiler) or inline function which only calls the true back-end function krb5int_trace() when tracing is enabled in the context. If a macro is used, k5trace arguments will not be evaluated unless tracing is enabled, minimizing the runtime footprint.

The krb5_context structure will gain a new field trace_fd, which will have the value -1 if tracing is not enabled. The function krb5int_init_trace will initialize trace_fd if KRB5_TRACE is defined in the environment.