1 \input texinfo @c -*-texinfo-*-
3 @c Note: the above texinfo file must include the "doubleleftarrow"
4 @c definitions added by jcb.
7 @setfilename krb5-implement.info
8 @settitle Kerberos V5 Installation Guide
9 @setchapternewpage odd @c chapter begins on next odd page
10 @c @setchapternewpage on @c chapter begins on next page
11 @c @smallbook @c Format for 7" X 9.25" paper
19 @include definitions.texinfo
22 @finalout @c don't print black warning boxes
25 @title @value{PRODUCT} Implementor's Guide
26 @subtitle Release: @value{RELEASE}
27 @subtitle Document Edition: @value{EDITION}
28 @subtitle Last updated: @value{UPDATED}
29 @author @value{COMPANY}
32 @vskip 0pt plus 1filll
35 @include copyright.texinfo
39 @node Top, Introduction, (dir), (dir)
40 @comment node-name, next, previous, up
43 This file contains internal implementor's information for the
44 @value{RELEASE} release of @value{PRODUCT}.
46 @include copyright.texinfo
50 @c The master menu is updated using emacs19's M-x texinfo-all-menus-update
51 @c function. Don't forget to run M-x texinfo-every-node-update after
52 @c you add a new section or subsection, or after you've rearranged the
53 @c order of sections or subsections. Also, don't forget to add an @node
54 @c comand before each @section or @subsection! All you need to enter
57 @c @node New Section Name
59 @c @section New Section Name
61 @c M-x texinfo-every-node-update will take care of calculating the
62 @c node's forward and back pointers.
64 @c ---------------------------------------------------------------------
68 * Compiler and OS Requirements::
72 * Host Address Lookup::
77 @node Introduction, Compiler and OS Requirements, Top, Top
80 This file contains internal implementor's information for
81 @value{PRODUCT}. It is currently contains information that was removed
82 from install.texi; eventually it will have more detailed information on
83 the internals of the @value{PRODUCT}.
85 @node Compiler and OS Requirements, Socket API, Introduction, Top
86 @chapter Compiler and OS Requirements
88 The basic Kerberos libraries are entirely written in C.
89 However, we do assume full ANSI C (1989) support, typical 32- or
90 64-bit twos-complement architectures (@code{char} is 8 bits,
91 @code{short} is 16 bits, @code{int} is 32 bits, byte order is 1234 or
92 4321), and a few aspects of ISO C 1999:
96 support for inline functions, even if the keyword isn't @code{inline}
98 64-bit arithmetic types (needed for sequence numbers in GSSAPI)
101 These are handled through the internal header file
102 @file{k5-platform.h}.
104 We also conditionally tailor code for the GNU C compiler in a few
105 places where it helps performance or debugging, but the code should
106 still work fine with other C compilers.
108 On UNIX platforms, ... @i{(should outline what POSIX stuff we
111 See also @ref{Advanced Shared Library Requirements}, for UNIX and
114 Our makefiles are intended to support building from the top level with
115 a POSIX-compliant version of @code{make}, and parallel builds using
116 GNU @code{make}. This sometimes comes at the cost of efficiency with
117 non-GNU versions; for example, some targets in some directories will
118 always be rebuilt with certain versions of @code{make}, even though
119 the real dependencies are not out of date, because some versions of
120 @code{make} don't understand how we're using phony intermediate
121 targets to manage building in subdirectories in parallel builds.
122 (Actually, this is more my view of how we've been doing things than
123 official policy. ---Ken)
125 @node Socket API, IPv6 Support, Compiler and OS Requirements, Top
128 Someone should describe the API subset we're allowed to use with
129 sockets, how and when to use @code{SOCKET_ERRNO}, @i{etc}.
131 Note that all new code doing hostname and address translation should
132 use @code{getaddrinfo} and friends. (@xref{Host Address Lookup}.)
134 @node IPv6 Support, Local Addresses, Socket API, Top
135 @chapter IPv6 Support
137 Most of the IPv6 support is keyed on the macro @code{KRB5_USE_INET6}.
138 If this macro is not defined, there should be no references to
139 @code{AF_INET6}, @code{struct sockaddr_in6}, @i{etc}.
141 The @code{configure} scripts will check for the existence of various
142 functions, macros and structure types to decide whether to enable the
143 IPv6 support. You can also use the @samp{--enable-ipv6} or
144 @samp{--disable-ipv6} options to override this decision.
146 Regardless of the setting of @code{KRB5_USE_INET6}, some aspects of
147 the new APIs devised for IPv6 are used throughout the code, because it
148 would be too difficult maintain code for the IPv6 APIs and for the old
149 APIs at the same time. But for backwards compatibility, we try to
150 fake them if the system libraries don't provide them, at least for
151 now. This means we sometimes use slightly modified versions of the
152 APIs, but we try to keep the modifications as non-intrusive as
153 possible. Macros are used to rename struct tags and function names,
154 so don't @code{#undef} any of these names.
162 @itemx struct addrinfo
163 Always include the header file @file{fake-addrinfo.h} before using
164 these. If the native system doesn't provide them, the header file
165 will, using static functions that will call @code{gethostbyname} and
166 the like in the native libraries. (This also happens to be the way
167 the Winsock 2 headers work, depending on some of the predefined macros
168 indicating the target OS version.)
170 We also provide ``wrapper'' versions on some systems where a native
171 implementation exists but the data it returns is broken in some way.
173 So these may not always be thread-safe, and they may not always
174 provide IPv6 support, but the API will be consistent.
176 @item struct sockaddr_storage
178 These are provided by @file{socket-utils.h}, if the native headers
179 don't provide them. @code{sockaddr_storage} contains a
180 @code{sockaddr_in}, so by definition it's big enough to hold one; it
181 also has some extra padding which will probably make it big enough to
182 hold a @code{sockaddr_in6} if the resulting binary should get run on a
183 kernel with IPv6 support.
185 Question: Should these simply be moved into @file{port-sockets.h}?
189 IRIX 6.5.7 has no IPv6 support. Of the systems most actively in the
190 MIT's Athena environment (used by MIT's Kerberos UNIX developers),
191 this is the only one without built-in IPv6 support. In another year
192 or so we probably won't be using those systems any more, and we may
193 consider dropping support for systems without IPv6 support.
195 Somewhere between IRIX 6.5.14 and 6.5.16, partial IPv6 support was
196 introduced to the extent that the configuration system detects the
197 IPv6 support and attempts to use it. Code compiles, but then upon
198 linking, one discovers that ``in6addr_any'' is not defined in any
199 system library. A work around the header file @file{fake-addrinfo.h}
200 is provided by providing a static copy. This run time IPv6 code has
201 still not been tested.
203 Some utility functions or macros are also provided to give a
204 convenient shorthand for some operations, and to retain compile-time
205 type checking when possible (generally using inline functions but only
206 when compiling with GCC).
210 @item socklen(struct sockaddr *)
211 Returns the length of the @code{sockaddr} structure, by looking at the
212 @code{sa_len} field if it exists, or by returning the known sizes of
213 @code{AF_INET} and @code{AF_INET6} address structures.
215 @item sa2sin(struct sockaddr *)
216 @itemx sa2sin6(struct sockaddr *)
217 @itemx ss2sa(struct sockaddr_storage *)
218 @itemx ss2sin(struct sockaddr_storage *)
219 @itemx ss2sin6(struct sockaddr_storage *)
220 Pointer type conversions. Use these instead of plain casts, to get
221 type checking under GCC.
225 @node Local Addresses, Host Address Lookup, IPv6 Support, Top
226 @chapter Local Addresses
228 (Last update: 2002-03-13.)
230 Different systems have different ways of finding the local network
233 On Windows, @code{gethostbyname} is called on the local host name to get a
234 set of addresses. If that fails, a UDP socket is ``connected'' to a
235 particular IPv4 address, and the local socket name is retrieved, its
236 address being treated as the one local network address. Future
237 versions of the Windows code should be able to actually examine local
240 On Mac OS 9 and earlier, a Mac-specific interface is used to look up
241 local addresses. Presumably, on Mac OS X we'll use that or the
244 On (most?) UNIX systems, there is an @code{ioctl} called
245 @code{SIOCGIFCONF} which gets interface configuration information.
246 The behavior of this @code{ioctl} varies across UNIX systems though.
247 It takes as input a buffer to fill with data structures, but if the
248 buffer isn't big enough, the behavior isn't well defined. Sometimes
249 you get an error, sometimes you get incomplete data. Sometimes you
250 get a clear indication that more space was needed, sometimes not. A
251 couple of systems have additional @code{ioctl}s that can be used to
252 determine or at least estimate the correct size for the buffer.
253 Solaris has introduced @code{SIOCGLIFCONF} for querying IPv6
254 addresses, and restricts @code{SIOCGIFCONF} to IPv4 only. (** We
255 should actually check if that's true.)
257 We (Ken Raeburn in particular) ran some tests on various systems to
258 see what would happen with buffers of various sizes from much smaller
259 to much larger than needed for the actual data. The buffers were
260 filled with specific byte values, and then checked to see how much of
261 the buffer was actually written to. The "largest gap" values listed
262 below are the largest number of bytes we've seen left unused at the
263 end of the supplied buffer when there were more entries to return.
264 These values may of coures be dependent on the configurations of the
265 particular systems we wre testing with. (See
266 @file{lib/krb5/os/t_gifconf.c} for the test program.)
268 NetBSD 1.5-alpha: The returned @code{ifc_len} is the desired amount of
269 space, always. The returned list may be truncated if there isn't
270 enough room; no overrun. Largest gap: 43. However, NetBSD has
271 @code{getifaddrs}, which hides all the ugliness within the C library.
273 BSD/OS 4.0.1 (courtesy djm): The returned @code{ifc_len} is equal to
274 or less than the supplied @code{ifc_len}. Sometimes the entire buffer
275 is used; sometimes N-1 bytes; occasionally, the buffer must have quite
276 a bit of extra room before the next structure will be added. Largest
279 Solaris 7,8: Return @code{EINVAL} if the buffer space is too small for
280 all the data to be returned, including when @code{ifc_len} is 0.
281 Solaris is the only system I've found so far that actually returns an
282 error. No gap. However, @code{SIOCGIFNUM} may be used to query the
283 number of interfaces.
285 Linux 2.2.12 (Red Hat 6.1 distribution, x86), 2.4.9 (RH 7.1, x86): The
286 buffer is filled in with as many entries as will fit, and the size
287 used is returned in @code{ifc_len}. The list is truncated if needed,
288 with no indication. Largest gap: 31. @emph{However}, this interface
289 does not return any IPv6 addresses. They must be read from a file
290 under @file{/proc}. (This appears to be what the @samp{ifconfig}
293 IRIX 6.5.7: The buffer is filled in with as many entries as will fit
294 in N-1 bytes, and the size used is returned in @code{ifc_len}.
295 Providing exactly the desired number of bytes is inadequate; the
296 buffer must be @emph{bigger} than needed. (E.g., 32->0, 33->32.) The
297 returned @code{ifc_len} is always less than the supplied one. Largest
300 AIX 4.3.3: Sometimes the returned @code{ifc_len} is bigger than the
301 supplied one, but it may not be big enough for @emph{all} the
302 interfaces. Sometimes it's smaller than the supplied value, even if
303 the returned list is truncated. The list is filled in with as many
304 entries as will fit; no overrun. Largest gap: 143.
306 Older AIX: We're told by W. David Shambroom (DShambroom@@gte.com) in
307 PR krb5-kdc/919 that older versions of AIX have a bug in the
308 @code{SIOCGIFCONF} @code{ioctl} which can cause them to overrun the
309 supplied buffer. However, we don't yet have details as to which
310 version, whether the overrun amount was bounded (e.g., one
311 @code{ifreq}'s worth) or not, whether it's a real buffer overrun or
312 someone assuming it was because @code{ifc_len} was increased, etc.
313 Once we've got details, we can try to work around the problem.
315 Digital UNIX 4.0F: If input @code{ifc_len} is zero, return an
316 @code{ifc_len} that's big enough to include all entries. (Actually,
317 on our system, it appears to be larger than that by 32.) If input
318 @code{ifc_len} is nonzero, fill in as many entries as will fit, and
319 set @code{ifc_len} accordingly. (Tested only with buffer previously
322 Tru64 UNIX 5.1A: Like Digital UNIX 4.0F, except the ``extra'' space
323 indicated when the input @code{ifc_len} is zero is larger. (We got
324 400 out when 320 appeared to be needed.)
326 So... if the returned @code{ifc_len} is bigger than the supplied one,
327 we'll need at least that much space -- but possibly more -- to hold
328 all the results. If the returned value is smaller or the same, we may
329 still need more space.
331 The heuristic we're using on most systems now is to keep growing the
332 buffer until the unused space is larger than an @code{ifreq} structure
335 @node Host Address Lookup, Thread Safety, Local Addresses, Top
336 @chapter Host Address Lookup
338 The traditional @code{gethostbyname} function is not thread-safe, and
339 does not support looking up IPv6 addresses, both of which are becoming
340 more important. New standards have been in development that should
341 address both of these problems. The most promising is
342 @code{getaddrinfo} and friends, which is part of the Austin Group and
343 UNIX 98(?) specifications. Code in the MIT tree is gradually being
344 converted to use this interface.
347 (Question: What about @code{inet_ntop} and @code{inet_pton}? We're
348 not using them at the moment, but some bits of code would be
349 simplified if we were to do so, when plain addresses and not socket
350 addresses are already presented to us.)
353 The @code{getaddrinfo} function takes a host name and service name and
354 returns a linked list of structures indicating the address family,
355 length, and actual data in ``sockaddr'' form. (That is, it includes a
356 pointer to a @code{sockaddr_in} or @code{sockaddr_in6} structure.)
357 Depending on options set via the @code{hints} input argument, the results
358 can be limited to a single address family (@i{e.g.}, for IPv4
359 applications), and the canonical name of the indicated host can be
360 returned. Either the host or service can be a null pointer, in which
361 case only the other is looked up; they can also be expressed in
362 numeric form. This interface is extensible to additional address
363 families in the future. The returned linked list can be freed with
364 the @code{freeaddrinfo} function.
366 The @code{getnameinfo} function does the reverse -- given an address
367 in ``sockaddr'' form, it converts the address and port values into
370 Errors returned by either of these functions -- as return values, not
371 global variables -- can be translated into printable form with the
372 @code{gai_strerror} function.
374 Some vendors are starting to implement @code{getaddrinfo} and friends,
375 however, some of the implementations are deficient in one way or
381 As of AIX 4.3.3, @code{getaddrinfo} returns sockaddr structures
382 without the family and length fields filled in.
385 The GNU C library, used on GNU/Linux systems, has had a few problems
386 in this area. One version would drop some IPv4 addresses for some
387 hosts that had multiple IPv4 and IPv6 addresses.
389 In GNU libc 2.2.4, when the DNS is used, the name referred to by PTR
390 records for each of the addresses is looked up and stored in the
391 @code{ai_canonname} field, or the printed numeric form of the address
392 is, both of which are wrong.
395 No known bugs here, but as of IRIX 6.5.7, the version we're using at
396 MIT, these functions had not been implemented.
399 Two problems have been found with @code{getaddrinfo} on Mac OS X, at
400 least under version 10.3. First, while @code{gethostbyname} data is
401 cached to make multiple lookups of the same name (@i{e.g.}, by
402 different parts of the code that need to know about the same server
403 host), @code{getaddrinfo} results are not cached, so multiple queries
404 mean multiple DNS requests, which means more delays if the DNS servers
405 are not close by and fast to respond. We've implemented a cache of
406 our own to work around this, though it only applies to multiple
407 lookups in a short period of time within the same application process,
408 and it's only implemented for the Mac at the moment.
410 Second, the Mac libraries will generate a DNS SRV RR query; as far as
411 I [Ken] can tell this is a bug, but Apple seems to consider it a
412 feature. (Call @code{getaddrinfo("example.com", "telnet", ...)} and
413 you get a SRV record query, but the spec on SRV records says you must
414 not use them unless the specification for the service in question says
415 to.) Yet more network traffic for each name to look up.
418 As of NetBSD 1.5, this function is not thread-safe. In 1.5X
419 (intermediate code snapshot between 1.5 and 1.6 releases), the
420 @code{ai_canonname} field can be empty, even if the
421 @code{AI_CANONNAME} flag was passed. In particular, this can happen
422 if a numeric host address string is provided. Also, numeric service
423 names appear not to work unless the stream type is given; specifying
424 the TCP protocol is not enough.
427 In Tru64 UNIX 5.0, @code{getaddrinfo} is available, but requires that
428 @code{<netdb.h>} be included before its use; that header file defines
429 @code{getaddrinfo} as a macro expanding to either @code{ogetaddrinfo}
430 or @code{ngetaddrinfo}, and apparently the symbol @code{getaddrinfo}
431 is not present in the system library, causing the @code{configure}
432 test for it to fail. Technically speaking, I [Ken] think Compaq has
433 it wrong here, I think the symbol is supposed to be available even if
434 the application uses @code{#undef}, but I have not confirmed it in the
438 According to Windows documentation, the returned @code{ai_canonname}
439 field can be null even if the @code{AI_CANONNAME} flag is given.
443 For most systems where @code{getaddrinfo} returns incorrect data,
444 we've provided wrapper versions that call the system version and then
445 try to fix up the returned data.
447 For systems that don't provide these functions at all, we've provided
448 replacement versions that neither are thread-safe nor support IPv6,
449 but will allow us to convert the rest of our code to assume the
450 availability of @code{getaddrinfo}, rather than having to use two
451 branches everywhere, one for @code{getaddrinfo} and one for
452 @code{gethostbyname}. These replacement functions do use
453 @code{gethostbyname} and the like; for some systems it would be
454 possible to use @code{gethostbyname2} or @code{gethostbyname_r} or
455 other such functions, to provide thread safety or IPv6 support, but
456 this has not been a priority for us, since most modern systems have
457 these functions anyways. And if they don't, they probably don't have
458 real IPv6 support either.
460 Including @file{fake-addrinfo.h} will enable the wrapper or
461 replacement versions when needed. Depending on the system
462 configuration, this header file may define several static functions
463 (and declare them @code{inline} under GNU C), and leave it to the
464 compiler to discard any unused code. This may produce warnings on
465 some systems, and if the compiler isn't being too clever, may cause
466 several kilobytes of excess storage to be consumed on these backwards
469 Do not assume that @code{ai_canonname} will be set when the
470 @code{AI_CANONNAME} flag is set. Check for a null pointer before
473 @node Thread Safety, Shared Libraries, Host Address Lookup, Top
474 @chapter Thread Safety
476 Work is still needed as this section is being written. However, we've
477 made a lot of progress.
480 * Kerberos API Thread Safety::
481 * Thread System Requirements::
482 * Internal Thread API::
485 @node Kerberos API Thread Safety, Thread System Requirements, Thread Safety, Thread Safety
486 @section Kerberos API Thread Safety
488 We assume that a @code{krb5_context} or a @code{krb5_auth_context}
489 will be used in only one thread at a time, and any non-opaque object
490 clearly being modified by the application code (@i{e.g.}, a
491 @code{krb5_principal} having a field replaced) is not being used in
492 another thread at the same time.
494 A credentials cache, key table, or replay cache object, once the C
495 object is created, may be used in multiple threads simultaneously;
496 internal locking is done by the implementations of those objects. (We
497 assume that object destructors are invoked only when all other threads
498 are finished with the object.) @i{(Iterators? Probably okay now, but
499 needs review.)} However, this doesn't mean that we've fixed any
500 problems there may be regarding simultaneous access to on-disk files
501 from multiple processes, and in fact if a process opens a disk file
502 multiple times, the same problems may come up.
504 Any file locking issues may become worse, actually. UNIX file locking
505 with @code{flock} is done on a per-process basis, and closing a file
506 descriptor that was opened on a file releases any locks the process
507 may have on that file, even if they were obtained using other,
508 still-open file descriptors. UNIX file locks are used for credentials
509 caches and keytab files; the replay cache implementation is already
510 known to be unsafe in not using file locking.
512 We MAY implement --- but haven't yet --- a ``fix'' whereby open files
513 are tracked by name (and per object type), and a new attempt to open
514 one gets a handle that uses the same open file descriptor, even if it
515 appears as two objects to the application. This won't address the
516 problem of getting the same file via two names that look different,
517 but it may be ``good enough.''
521 Strictly speaking, the GSSAPI specification says nothing about thread
522 safety, so for best portability, a GSSAPI application probably should
523 not assume that a GSSAPI implementation is thread-safe in any way. On
524 the other hand, the GSSAPI specification doesn't explicitly say that
525 it's safe to use in a program that uses the Berkeley sockets API,
526 either; at some point, you have to start making some assumptions.
528 A GSSAPI security context, like a @code{krb5_context}, may be used
529 only in one thread at a time. The GSSAPI specification gives precise
530 definitions of C data structures for buffers, object identifiers, OID
531 sets, and channel bindings, that do not allow for the addition of a
532 mutex. Thus, these objects must not be modified by one thread while
533 in use by another. (All of the GSSAPI functions that modify these
534 types of objects should be obvious; they're listed as ``modify''
535 parameters in the specification. In fact, aside from the case of
536 @code{gss_add_oid_set_member}, they're generally output arguments,
537 with the previous value ignored.)
539 The function @code{gss_add_cred} can modify the
540 @code{input_cred_handle} object, if a null @code{output_cred_handle}
541 argument is supplied. Thus, all @code{gss_cred_id_t} objects must
542 have mutexes, and all accesses (except in the functions creating or
543 destroying them) must acquire the mutex first.
545 Note that the use of @code{const} in the GSSAPI C bindings is not a
546 useful guide to when an object might or might not be modified. In
547 most cases, @code{const} is applied to handle arguments, which are
548 defined as arithmetic or pointer types. It applies to the argument
549 itself, not the data pointed to @i{if} the type is a pointer; this
550 would mean that the GSSAPI function in question cannot modify the
551 value of its handle parameter, and puts no constraints on
552 modifications to the object indicated by the handle. And according to
553 the C type compatibility rules, the function definition can omit those
554 @code{const} qualifiers anyways.@footnote{If you're thinking that this
555 means the use of @code{const} in the GSSAPI C bindings is confusing
556 and/or useless, you're right.}
561 @node Thread System Requirements, Internal Thread API, Kerberos API Thread Safety, Thread Safety
562 @section Thread System Requirements
564 We support a few types of environments with regard to thread support:
569 Windows native threads. The objects used by the Windows thread
570 support functions generally need run-time initialization; this is done
571 through the library initialization function. (@xref{Advanced Shared
572 Library Requirements}.)
575 POSIX threads, with weak reference support so we can tell whether the
576 thread code was actually linked into the current executable. If the
577 functions aren't available, we assume the process is single-threaded
578 and ignore locks. (We do assume that the thread support functions
579 won't show up half-way through execution of the program.) In order to
580 support single-threaded programs wanting to load Kerberos or GSSAPI
581 modules through a plug-in mechanism, we don't list the pthread library
582 in the dependencies of our shared libraries.
585 POSIX threads, with the library functions always available, even if
586 they're stub versions that behave normally but don't permit the
587 creation of new threads.
589 On AIX 4.3.3, we do not get weak references or useful stub functions,
590 and calling @code{dlopen} apparently causes the pthread library to get
591 loaded, so we've decided to link against the pthread library always.
593 On Tru64 UNIX 5.1, we again do not get weak references or useful stub
594 functions. Rather than look for yet another approach for this one
595 platform, we decided to always link against the pthread library on
596 this platform as well. This may break single-threaded applications
597 that load the Kerberos libraries after startup. A clean solution,
598 even if platform-dependent, would be welcome.
601 Single-threaded. No locking is performed, any ``thread-local''
602 storage is in fact global, @i{etc}.
606 If @code{pthread_once} is not provided in functional form in the
607 default libraries, and weak references are not supported, we always
608 link against the pthread libraries. (Tru64, AIX.)
610 System routines: getaddrinfo (not always implemented thread-safe),
611 gethostbyname_r, gmtime_r, getpwnam_r, res_nsearch.
613 Unsafe system routines: setenv, setlocale.
615 @node Internal Thread API, , Thread System Requirements, Thread Safety
616 @section Internal Thread API
618 Some ideas were discussed on the @samp{krbdev} mailing list, and while
619 the current implementation does largely resemble the scheme Ken
622 The following macros in @file{k5-thread.h} implement a locking scheme
623 similar to POSIX threads, with fewer features.
625 @deftp {Data type} k5_mutex_t
626 This is the type of a mutex to be used by the Kerberos libraries. Any
627 object of this type needs initialization. If the object is
628 dynamically allocated, @code{k5_mutex_init} must be used; if the
629 object is allocated statically, it should be initialized at compile
630 time with @code{K5_MUTEX_PARTIAL_INITIALIZER} and then
631 @code{k5_mutex_finish_init} should be called at run time. (In
632 general, one of these will do the work, and the other will do nothing
633 interesting, depending on the platform. When the debugging code is
634 turned on, it will check that both were done. However, as far as I
635 know, it should work to use just @code{k5_mutex_init} on a mutex in
638 The mutex may be used only within the current process. It should not
639 be created in memory shared between processes. (Will it work in a
640 child process after @code{fork()}? I think so.)
642 Depending on compile-time options, the @code{k5_mutex_t} object may
643 contain more than an operating-system mutex; it may also contain
644 debugging information such as the file and line number in the Kerberos
645 code where the last mutex operation was performed, information for
646 gathering statistics on mutex usage, @i{etc}.
648 This type @emph{is not} a simple typedef for the native OS mutex
649 object, to prevent programmers from accidentally assuming that
650 arbitrary features of the native thread system will always be
651 available. (If someone wishes to make use of native thread system
652 features in random library code, they'll have to go further out of
653 their way to do it, and such changes probably won't be accepted in the
654 main Kerberos code base at MIT.)
657 @defvr Macro K5_MUTEX_PARTIAL_INITIALIZER
658 Value to be used for compile-time initialization of a mutex in static
662 @deftypefn Macro int k5_mutex_finish_init (k5_mutex_t *@var{m})
663 Finishes run-time initialization, if such is needed, of a mutex that
664 was initialized with @code{K5_MUTEX_PARTIAL_INITIALIZER}. This macro
665 must be called before the mutex can be locked; usually this is done
666 from library initialization functions.
669 @deftypefn Macro int k5_mutex_init (k5_mutex_t *@var{m})
673 @deftypefn Macro int k5_mutex_destroy (k5_mutex_t *@var{m})
674 Destroys a mutex, whether allocated in static or heap storage. All
675 mutexes should be destroyed before the containing storage is freed, in
676 case additional system resources have been allocated to manage them.
679 @deftypefn Macro int k5_mutex_lock (k5_mutex_t *@var{m})
680 @deftypefnx Macro int k5_mutex_unlock (k5_mutex_t *@var{m})
681 Lock or unlock a mutex, returning a system error code if an error
682 happened, or zero for success. (Typically, the return code from
683 @code{k5_mutex_unlock} is ignored.)
686 @deftypefn Macro void k5_mutex_assert_locked (k5_mutex_t *@var{m})
687 @deftypefnx Macro void k5_mutex_assert_unlocked (k5_mutex_t *@var{m})
688 These macros may be used in functions that require that a certain
689 mutex be locked by the current thread, or not, at certain points
690 (typically on entry to the function). They may generate error
691 messages or debugger traps, or abort the program, if the mutex is not
692 in the expected state. Or, they may simply do nothing.
694 It is not required that the OS mutex interface let the application
695 code determine the state of a mutex; hence these are not specified as
696 a single macro returning the current state, to be checked with
700 Mutexes are assumed not to be recursive (@i{i.e.}, if a thread has the
701 mutex locked already, attempting to lock it again is an error). There
702 is also no support assumed for ``trylock'' or ``lock with timeout''
705 The operating system interface is similar to the above interface, with
706 @code{k5_os_} names used for the OS mutex manipulation code. The type
707 and macros indicated above are wrappers that optionally add debugging
708 code and other stuff. So the Kerberos library code should use the
709 macros above, and ports to new thread systems should be done through
710 the @code{k5_os_} layer.
712 Thread-local storage is managed through another interface layer
714 @deftp {Enumerator} k5_key_t
715 This is an enumeration type which indicates which of the per-thread
716 data objects is to be referenced.
719 @deftypefn Macro int k5_key_register (k5_key_t @var{key}, void (*@var{destructor})(void*))
720 Registers a thread-local storage key and a function to destroy a
721 stored object if the thread exits. This function must be called
722 before @code{k5_setspecific} can be used. Currently @var{destructor}
723 must not be a null pointer; note, however, that the standard library
724 function @code{free} is of the correct type to be used here if the
725 allocated data doesn't require any special cleanup besides releasing
726 one block of storage.
729 @deftypefn Macro void *k5_getspecific (k5_key_t @var{key})
730 @deftypefnx Macro int k5_setspecific (k5_key_t @var{key}, void *@var{value})
731 As with the POSIX interface, retrieve or store the value for the
732 current thread. Storing a value may return an error indication. If
733 an error occurs retrieving a value, @code{NULL} is returned.
736 @deftypefn Macro int k5_key_delete (k5_key_t @var{key})
737 Called to indicate that the key value will no longer be used, for
738 example if the library is in the process of being unloaded. The
739 destructor function should be called on objects of this type currently
740 allocated in any thread. (XXX Not implemented yet.)
743 If support functions are needed to implement any of these macros,
744 they'll be in the Kerberos support library, and any exported symbols
745 will use the @code{krb5int_} prefix. The shorter @code{k5_} prefix is
746 just for convenience, and should not be visible to any application
749 @node Shared Libraries, , Thread Safety, Top
750 @chapter Shared Libraries
752 (These sections are old -- they should get updated.)
755 * Shared Library Theory::
756 * Advanced Shared Library Requirements::
757 * Operating System Notes for Shared Libraries::
760 @node Shared Library Theory, Advanced Shared Library Requirements, Shared Libraries, Shared Libraries
761 @section Theory of How Shared Libraries are Used
763 An explanation of how shared libraries are implemented on a given
764 platform is too broad a topic for this manual. Instead this will touch
765 on some of the issues that the Kerberos V5 tree uses to support version
766 numbering and alternate install locations.
768 Normally when one builds a shared library and then links with it, the
769 name of the shared library is stored in the object
770 (i.e. libfoo.so). Most operating systems allows one to change name that
771 is referenced and we have done so, placing the version number into the
772 shared library (i.e. libfoo.so.0.1). At link time, one would reference
773 libfoo.so, but when one executes the program, the shared library loader
774 would then look for the shared library with the alternate name. Hence
775 multiple versions of shared libraries may be supported relatively
776 easily. @footnote{Under AIX for the RISC/6000, multiple versions of
777 shared libraries are supported by combining two or more versions of the
778 shared library into one file. The Kerberos build procedure produces
779 shared libraries with version numbers in the internal module names, so
780 that the shared libraries are compatible with this scheme.
781 Unfortunately, combining two shared libraries requires internal
782 knowledge of the AIX shared library system beyond the scope of this
783 document. Practically speaking, only one version of AIX shared libraries
784 can be supported on a system, unless the multi-version library is
785 constructed by a programmer familiar with the AIX internals.}
787 All operating systems (that we have seen) provide a means for programs
788 to specify the location of shared libraries. On different operating
789 systems, this is either specified when creating the shared library, and
790 link time, or both.@footnote{Both are necessary sometimes as the shared
791 libraries are dependent on other shared libraries} The build process
792 will hardwire a path to the installed destination.
794 @node Advanced Shared Library Requirements, Operating System Notes for Shared Libraries, Shared Library Theory, Shared Libraries
795 @section Advanced Shared Library Requirements
797 In order to better support some multithreading models, and permit the
798 libraries to clean up internally maintained caches of information,
799 we've imposed new requirements on the OS shared library support.
801 Specifically, we want the ability to run certain bits of code in a
802 thread-safe manner at library load time, on multithreading platforms
803 not supporting @code{pthread_once}, and we want the ability to run
804 cleanup code when the library is unloaded.
806 In general, where platforms have initialization functions, we don't
807 always get an opportunity to return an error from them. However, the
808 system functions we call can return errors. So a framework has been
809 built that attempts to combine the @code{pthread_once} and load-time
810 initialization approaches, and add the ability to store an error code
811 indicating success or failure of the initialization routine.
813 The main implementation of this framework is in @file{k5-platform.h}.
814 Some additional information, specifically the names of the
815 initialization and finalization functions, are stored in the makefiles
816 used to generate each of the UNIX libraries, in @file{win_glue.c}, and
817 somewhere in the Mac OS X support (XXX not added yet?). How the
818 information is used depends on the platform:
823 On platforms without any thread support, a simple flag is used, on the
824 assumption that the library code will have sole control over the
825 process execution until the initialization function returns. (It's
826 generally a bad idea to call any ``interesting'' function like
827 @code{longjmp} or Kerberos functions from signal handlers; now it's a
828 slightly worse idea.)
831 On platforms supporting @code{pthread_once}, library initialization is
832 generally delayed until the point where the library code needs to
833 verify that the initialization succeeded. If @code{pthread_once} may
834 not have been linked into the executable and we can tell (for example,
835 with weak symbol references), this is combined with the simple-flag
839 On Windows, the library initialization function is run from
840 @file{win_glue.c} at load time; it should complete before the
841 library's symbol table is made accessible to the calling process.
845 The library finalization code is similarly platform-dependent. If the
846 compiler or linker lets us specify that a function should be called as
847 a finalization function (for example, @code{gcc}'s ``destructor''
848 attribute), we use it.
850 The internal interface currently used within the code of the Kerberos
851 libraries consists of four macros:
853 @defmac MAKE_INIT_FUNCTION (@var{fname})
854 Used at the top level of the file (@i{i.e.}, not within a function),
855 with a semicolon after it, declares @var{fname}, a function taking no
856 arguments and returning @code{int}, to be an initialization function.
857 This macro must be used before the function is declared, and it must
858 be defined in the current file as:
860 int @var{fname} (void) @{ ... @}
862 This macro will define additional data and possibly function objects,
863 and will declare @var{fname}, though it may or may not declare
864 @var{fname} as @code{static}. (Under C rules, the declaration above
865 is compatible with a declaration of the function as @code{static}, and
866 @code{static} does apply, as long as the @code{static} declaration
869 When the function is invoked, the return value --- zero or an error
870 code --- will be saved away, and returned any time
871 @code{CALL_INIT_FUNCTION} is used.
873 There may be only one initialization function declared this way in
874 each UNIX library, currently.
877 @defmac MAKE_FINI_FUNCTION (@var{fname})
878 This is similar to @code{MAKE_INIT_FUNCTION} except that @var{fname}
879 is to be a library finalization function, called when the library is
880 no longer in use and is being unloaded from the address space.
882 void @var{fname} (void) @{ ... @}
885 There may be only one finalization function declared this way in each
886 UNIX library, currently.
889 @deftypefn Macro int CALL_INIT_FUNCTION (@var{fname})
890 This macro ensures that the initialization function @var{fname} is
891 called at this point, if it has not been called already. The macro
892 returns an error code that indicates success (zero), an error in the
893 OS support (@i{e.g.}, if @code{pthread_once} returns an error), or an
894 error returned by the initialization function.
896 Currently, all uses of @code{CALL_INIT_FUNCTION} must be in the same
897 file as the use of @code{MAKE_INIT_FUNCTION}, and must come after it.
900 @deftypefn Macro int INITIALIZER_RAN (@var{fname})
901 This macro returns non-zero iff the initialization function designated
902 by @var{fname} (and previously declared in the current file with
903 @code{MAKE_INIT_FUNCTION}) has been run, and returned no error
906 Since the finalization function might always be invoked through linker
907 support and initialization functions only sometimes invoked via
908 @code{pthread_once} in other functions that may not ever be called,
909 finalization functions should check whether the objects to be
910 destroyed have actually been created. This macro provides one way of
914 Note that all of this assumes shared libraries. If static linking is
915 done, our options are a bit more limited. We assume
916 @code{pthread_once} is available if there is any thread support
917 (@i{i.e.}, we don't support static linking on Windows), and we assume
918 that finalization code would be called only when the process is
919 exiting, at which point all resources should be freed up anyways, so
920 it doesn't really matter whether our cleanup code gets called. In
921 fact, it should be more efficient if it does not.
923 While one of our goals is to be able to repeatedly load, use, and
924 unload the MIT Kerberos libraries under a plugin architecture without
925 memory or other resource leaks, the main goal was to provide hooks
926 through which the library threading support could be properly
927 initialized on various platforms. The hooks we've added should be
928 sufficient for each library to free up any internal caches of
929 information at unload time, and we have added some of that support,
930 but it is not complete at this time.
933 We have also started limiting the list of exported symbols from shared
934 libraries on some UNIX platforms, and intend to start doing symbol
935 versioning on platforms that support it. The symbol lists we use for
936 UNIX at the moment are fairly all-inclusive, because we need more
937 symbols exported than are in the lists used for Windows and Mac
938 platforms, and we have not yet narrowed them down. The current lists
939 should not be taken as an indication of what we intend to export and
940 support in the future; see @file{krb5.h} for that.
942 The export lists are stored in the directories in which each UNIX
943 library is built, and the commands set up at configuration time by
944 @file{shlib.conf} can specify any processing to be done on those files
945 (@i{e.g.}, insertion of leading underscores or linker command-line
950 @node Operating System Notes for Shared Libraries, , Advanced Shared Library Requirements, Shared Libraries
951 @section Operating System Notes for Shared Libraries
953 From time to time users or developers suggest using GNU @code{Libtool}
954 or some other mechanism to generate shared libraries. Experience
955 with other packages suggests that Libtool tends to be difficult to
956 debug and when it works incorrectly, patches are required to generated
957 scripts to work around problems. So far, the Kerberos shared library
958 build mechanism, which sets a variety of makefile variables based on
959 operating system type and then uses those variables in the build
960 process has proven to be easier to debug and adequate to the task of
961 building shared libraries for Kerberos.
964 * AIX Shared Library Support::
965 * Alpha OSF/1 Shared Library Support::
968 @node AIX Shared Library Support, Alpha OSF/1 Shared Library Support, Operating System Notes for Shared Libraries, Operating System Notes for Shared Libraries
969 @subsection AIX Shared Library Support
971 AIX specifies shared library versions by combining multiple
972 versions into a single file. Because of the complexity of this process,
973 no automatic procedure for building multi-versioned shared libraries is
974 provided. Therefore, supporting multiple versions of the Kerberos shared
975 libraries under AIX will require significant work on the part of a
976 programmer famiiliar with AIX internals.
978 AIX allows a single library to be used both as a static library
979 and as a shared library. For this reason, the @samp{--enable-shared}
980 switch to configure builds only shared libraries. On other operating
981 systems, both shared and static libraries are built when this switch is
982 specified. As with all other operating systems, only non-shared static
983 libraries are built when @samp{--enable-shared} is not specified.
985 The AIX 3.2.5 linker dumps core trying to build a shared
986 @samp{libkrb5.a} produced with the GNU C compiler. The native AIX
987 compiler works fine. In addition, the AIX 4.1 linker is able to build a
988 shared @samp{libkrb5.a} when GNU C is used.
991 @node Alpha OSF/1 Shared Library Support, , AIX Shared Library Support, Operating System Notes for Shared Libraries
992 @subsection Alpha OSF/1 Shared Library Support
994 Shared library support has been tested with V2.1 and higher of the
995 operating system. Shared libraries may be compiled both with GCC and the
998 One of the nice features on this platform is that the paths to the
999 shared libraries is specified in the library itself without requiring
1000 that one specify the same at link time.
1002 We are using the @samp{-rpath} option to @samp{ld} to place the library
1003 load path into the executables. The one disadvantage of this is during
1004 testing where we want to make sure that we are using the build tree
1005 instead of a possibly installed library. The loader uses the contents of
1006 @samp{-rpath} before LD_LIBRARY_PATH so we must specify a dummy _RLD_ROOT
1007 and complete LD_LIBRARY_PATH in our tests.
1009 The one disadvantage with the method we are using....