@end iftex
@include definitions.texinfo
-@set EDITION b7-1
+@c @set EDITION b7-1
+@set EDITION [working copy]
@finalout @c don't print black warning boxes
@c is:
@c
@c @node New Section Name
-
@c @section New Section Name
@c
@c M-x texinfo-every-node-update will take care of calculating the
@menu
* Introduction::
* Compiler and OS Requirements::
-* Socket API::
-* IPv6 Support::
-* Local Addresses::
-* Host Address Lookup::
+* Networking::
* Thread Safety::
* Shared Libraries::
+* Porting Issues::
@end menu
@node Introduction, Compiler and OS Requirements, Top, Top
from install.texi; eventually it will have more detailed information on
the internals of the @value{PRODUCT}.
-@node Compiler and OS Requirements, Socket API, Introduction, Top
+@node Compiler and OS Requirements, Networking, Introduction, Top
@chapter Compiler and OS Requirements
The basic Kerberos libraries are entirely written in C.
places where it helps performance or debugging, but the code should
still work fine with other C compilers.
+Inline functions should always be specified in the code as
+@code{static inline}, as the behavior of other forms vary across GCC
+versions and C and C++ language standards. We assume that static
+copies of inline functions will not be generated if they are not
+needed; under some compilers that behave otherwise (such as the
+current Sun compiler as of this writing) may produce executables and
+libraries much larger than they need to be.
+
On UNIX platforms, ... @i{(should outline what POSIX stuff we
require)}.
Our makefiles are intended to support building from the top level with
a POSIX-compliant version of @code{make}, and parallel builds using
-GNU @code{make}. This sometimes comes at the cost of efficiency with
+GNU @code{make}. The latter sometimes comes at the cost of efficiency with
non-GNU versions; for example, some targets in some directories will
always be rebuilt with certain versions of @code{make}, even though
the real dependencies are not out of date, because some versions of
(Actually, this is more my view of how we've been doing things than
official policy. ---Ken)
-@node Socket API, IPv6 Support, Compiler and OS Requirements, Top
-@chapter Socket API
+Some of our code uses the SUSv2/C99 functions @code{snprintf} and
+@code{vsnprintf}. Since the two specifications differ, we assume that
+either specification may be followed: If truncation occurs, the return
+value may be the untruncated output length, or it may be negative (or
+may be zero if a zero length was supplied). It is therefore not
+permitted in our code to call these functions with a zero output
+length in order to determine the desired buffer size. A NULL output
+pointer is not permitted. In the header @file{k5-platform.h} we
+provide inline definitions for some platforms where these functions do
+not exist.
+
+We also use the extension functions @code{asprintf} and
+@code{vasprintf}, available on modern GNU and BSD based systems. The
+behaviors of these functions on errors vary between the two system
+types -- BSD stores a NULL as the output pointer, and GNU doesn't set
+it. We assume either may be the case: The output pointer may be
+unchanged or may be overwritten with NULL, and our code should thus
+assume it may be garbage, and should be assigned to if the value
+matters after an error is detected. Again, @file{k5-platform.h}
+provides workarounds for systems where these functions are not
+defined.
+
+Using these functions instead of plain @code{sprintf} without length
+checking may make our code slightly less vulnerable to buffer
+overruns.
+
+If necessary, we may eventually use a @code{[v]asnprintf} interface
+like that of the GNU C library, but we have not done so yet. Do not
+write code using that interface.
+
+@node Networking, Thread Safety, Compiler and OS Requirements, Top
+@chapter Networking
+
+@menu
+* Socket API::
+* IPv6 Support::
+* Local Addresses::
+* Host Address Lookup::
+@end menu
+
+@node Socket API, IPv6 Support, Networking, Networking
+@section Socket API
Someone should describe the API subset we're allowed to use with
sockets, how and when to use @code{SOCKET_ERRNO}, @i{etc}.
Note that all new code doing hostname and address translation should
use @code{getaddrinfo} and friends. (@xref{Host Address Lookup}.)
-@node IPv6 Support, Local Addresses, Socket API, Top
-@chapter IPv6 Support
+@node IPv6 Support, Local Addresses, Socket API, Networking
+@section IPv6 Support
Most of the IPv6 support is keyed on the macro @code{KRB5_USE_INET6}.
If this macro is not defined, there should be no references to
@itemx struct addrinfo
Always include the header file @file{fake-addrinfo.h} before using
these. If the native system doesn't provide them, the header file
-will, using static functions that will call @code{gethostbyname} and
-the like in the native libraries. (This also happens to be the way
-the Winsock 2 headers work, depending on some of the predefined macros
-indicating the target OS version.)
+will, using support functions that will call @code{gethostbyname} and
+the like in the native libraries. (This is similar to how the Winsock
+2 headers work, depending on some of the predefined macros indicating
+the target OS version, though they define the support functions
+directly in the header, as our code used to do.)
We also provide ``wrapper'' versions on some systems where a native
implementation exists but the data it returns is broken in some way.
Somewhere between IRIX 6.5.14 and 6.5.16, partial IPv6 support was
introduced to the extent that the configuration system detects the
-IPv6 support and attempts to use it. Code compiles, but then upon
-linking, one discovers that ``in6addr_any'' is not defined in any
-system library. A work around the header file @file{fake-addrinfo.h}
-is provided by providing a static copy. This run time IPv6 code has
-still not been tested.
+IPv6 support and attempts to use it. Code compiles, but then upon
+linking, one discovers that @code{in6addr_any} is not defined in any
+system library. The header file @file{fake-addrinfo.h} provides a
+static copy as a workaround. This run time IPv6 code has still not
+been tested.
Some utility functions or macros are also provided to give a
convenient shorthand for some operations, and to retain compile-time
@end table
-@node Local Addresses, Host Address Lookup, IPv6 Support, Top
-@chapter Local Addresses
+@node Local Addresses, Host Address Lookup, IPv6 Support, Networking
+@section Local Addresses
-(Last update: 2002-03-13.)
+(Last update: 2005-04-21, but most of the information dates back to
+early 2002.)
Different systems have different ways of finding the local network
addresses.
versions of the Windows code should be able to actually examine local
interfaces.
-On Mac OS 9 and earlier, a Mac-specific interface is used to look up
-local addresses. Presumably, on Mac OS X we'll use that or the
-general UNIX code.
-
On (most?) UNIX systems, there is an @code{ioctl} called
@code{SIOCGIFCONF} which gets interface configuration information.
The behavior of this @code{ioctl} varies across UNIX systems though.
you get an error, sometimes you get incomplete data. Sometimes you
get a clear indication that more space was needed, sometimes not. A
couple of systems have additional @code{ioctl}s that can be used to
-determine or at least estimate the correct size for the buffer.
-Solaris has introduced @code{SIOCGLIFCONF} for querying IPv6
+determine or at least estimate the correct size for the buffer. In
+Solaris, Sun has introduced @code{SIOCGLIFCONF} for querying IPv6
addresses, and restricts @code{SIOCGIFCONF} to IPv4 only. (** We
-should actually check if that's true.)
+should actually check if that's true.) They also added
+@code{SIOCGIFNUM} and @code{SIOCGLIFNUM} for querying the number of
+interfaces. HP-UX 11 also has @code{SIOCGLIFCONF}, but it requires a
+different data structure, and we haven't finished that support yet.
We (Ken Raeburn in particular) ran some tests on various systems to
see what would happen with buffers of various sizes from much smaller
to much larger than needed for the actual data. The buffers were
filled with specific byte values, and then checked to see how much of
-the buffer was actually written to. The "largest gap" values listed
+the buffer was actually written to. The ``largest gap'' values listed
below are the largest number of bytes we've seen left unused at the
end of the supplied buffer when there were more entries to return.
These values may of coures be dependent on the configurations of the
a bit of extra room before the next structure will be added. Largest
gap: 39.
-Solaris 7,8: Return @code{EINVAL} if the buffer space is too small for
-all the data to be returned, including when @code{ifc_len} is 0.
+Solaris 7,8,9: Return @code{EINVAL} if the buffer space is too small
+for all the data to be returned, including when @code{ifc_len} is 0.
Solaris is the only system I've found so far that actually returns an
error. No gap. However, @code{SIOCGIFNUM} may be used to query the
number of interfaces.
the returned list is truncated. The list is filled in with as many
entries as will fit; no overrun. Largest gap: 143.
-Older AIX: We're told by W. David Shambroom (DShambroom@@gte.com) in
-PR krb5-kdc/919 that older versions of AIX have a bug in the
-@code{SIOCGIFCONF} @code{ioctl} which can cause them to overrun the
-supplied buffer. However, we don't yet have details as to which
-version, whether the overrun amount was bounded (e.g., one
-@code{ifreq}'s worth) or not, whether it's a real buffer overrun or
-someone assuming it was because @code{ifc_len} was increased, etc.
-Once we've got details, we can try to work around the problem.
+Older AIX: We're told by W. David Shambroom in RT ticket 919 that
+older versions of AIX have a bug in the @code{SIOCGIFCONF}
+@code{ioctl} which can cause them to overrun the supplied buffer.
+However, we don't yet have details as to which version, whether the
+overrun amount was bounded (e.g., one @code{ifreq}'s worth) or not,
+whether it's a real buffer overrun or someone assuming it was because
+@code{ifc_len} was increased, @i{etc}. Once we've got details, we can
+try to work around the problem.
Digital UNIX 4.0F: If input @code{ifc_len} is zero, return an
@code{ifc_len} that's big enough to include all entries. (Actually,
So... if the returned @code{ifc_len} is bigger than the supplied one,
we'll need at least that much space -- but possibly more -- to hold
-all the results. If the returned value is smaller or the same, we may
-still need more space.
+all the results. If the returned value is a little smaller or the
+same, we may still need more space.
The heuristic we're using on most systems now is to keep growing the
buffer until the unused space is larger than an @code{ifreq} structure
by some safe margin.
-@node Host Address Lookup, Thread Safety, Local Addresses, Top
-@chapter Host Address Lookup
+@node Host Address Lookup, , Local Addresses, Networking
+@section Host Address Lookup
The traditional @code{gethostbyname} function is not thread-safe, and
does not support looking up IPv6 addresses, both of which are becoming
more important. New standards have been in development that should
address both of these problems. The most promising is
@code{getaddrinfo} and friends, which is part of the Austin Group and
-UNIX 98(?) specifications. Code in the MIT tree is gradually being
+UNIX 98(?) specifications. Code in the MIT tree has mostly been
converted to use this interface.
@quotation
No known bugs here, but as of IRIX 6.5.7, the version we're using at
MIT, these functions had not been implemented.
+@item Mac OS X
+Two problems have been found with @code{getaddrinfo} on Mac OS X, at
+least under version 10.3. First, while @code{gethostbyname} data is
+cached to make multiple lookups of the same name (@i{e.g.}, by
+different parts of the code that need to know about the same server
+host), @code{getaddrinfo} results are not cached, so multiple queries
+mean multiple DNS requests, which means more delays if the DNS servers
+are not close by and fast to respond. We've implemented a cache of
+our own to work around this, though it only applies to multiple
+lookups in a short period of time within the same application process,
+and it's only implemented for the Mac at the moment.
+
+Second, the Mac libraries will generate a DNS SRV RR query; as far as
+I [Ken] can tell this is a bug, but Apple seems to consider it a
+feature. (Call @code{getaddrinfo("example.com", "telnet", ...)} and
+you get a SRV record query, but the spec on SRV records says you must
+not use them unless the specification for the service in question says
+to.) Yet more network traffic for each name to look up.
+
@item NetBSD
As of NetBSD 1.5, this function is not thread-safe. In 1.5X
(intermediate code snapshot between 1.5 and 1.6 releases), the
real IPv6 support either.
Including @file{fake-addrinfo.h} will enable the wrapper or
-replacement versions when needed. Depending on the system
-configuration, this header file may define several static functions
-(and declare them @code{inline} under GNU C), and leave it to the
-compiler to discard any unused code. This may produce warnings on
-some systems, and if the compiler isn't being too clever, may cause
-several kilobytes of excess storage to be consumed on these backwards
-systems.
+replacement versions when needed. The functions are actually defined
+in the support library in @file{src/util/support}, added in the 1.4
+release.
Do not assume that @code{ai_canonname} will be set when the
@code{AI_CANONNAME} flag is set. Check for a null pointer before
using it.
-@node Thread Safety, Shared Libraries, Host Address Lookup, Top
+@node Thread Safety, Shared Libraries, Networking, Top
@chapter Thread Safety
Work is still needed as this section is being written. However, we've
* Kerberos API Thread Safety::
* Thread System Requirements::
* Internal Thread API::
+* Thread Shim Layer Implementation::
@end menu
@node Kerberos API Thread Safety, Thread System Requirements, Thread Safety, Thread Safety
default libraries, and weak references are not supported, we always
link against the pthread libraries. (Tru64, AIX.)
-System routines: getaddrinfo (not always implemented thread-safe),
-gethostbyname_r, gmtime_r, getpwnam_r, res_nsearch.
+System routines: @code{getaddrinfo} (not always implemented
+thread-safe), @code{gethostbyname_r}, @code{gmtime_r},
+@code{getpwnam_r} (but interfaces vary, see @file{k5-platform.h}),
+@code{res_nsearch} (but watch for resource leaks).
-Unsafe system routines: setenv, setlocale.
+Unsafe system routines: @code{setenv}, @code{setlocale}.
-@node Internal Thread API, , Thread System Requirements, Thread Safety
+@node Internal Thread API, Thread Shim Layer Implementation, Thread System Requirements, Thread Safety
@section Internal Thread API
Some ideas were discussed on the @samp{krbdev} mailing list, and while
the current implementation does largely resemble the scheme Ken
-Raeburn proposed.
+Raeburn proposed, some details have changed.
The following macros in @file{k5-thread.h} implement a locking scheme
similar to POSIX threads, with fewer features.
be created in memory shared between processes. (Will it work in a
child process after @code{fork()}? I think so.)
-Depending on compile-time options, the @code{k5_mutex_t} object may
-contain more than an operating-system mutex; it may also contain
-debugging information such as the file and line number in the Kerberos
-code where the last mutex operation was performed, information for
-gathering statistics on mutex usage, @i{etc}.
+The @code{k5_mutex_t} object contains more than an operating-system
+mutex; it may also contain debugging information such as the file and
+line number in the Kerberos code where the last mutex operation was
+performed, information for gathering statistics on mutex usage,
+@i{etc}., depending on compile-time options.
This type @emph{is not} a simple typedef for the native OS mutex
object, to prevent programmers from accidentally assuming that
features in random library code, they'll have to go further out of
their way to do it, and such changes probably won't be accepted in the
main Kerberos code base at MIT.)
+
+If thread support is disabled, a simple flag will be stored in place
+of the operating-system mutex. This flag indicates the ``locked''
+state, and is checked in the @code{k5_mutex_lock} and
+@code{k5_mutex_unlock} macros so that we can detect some cases of
+improperly written code even if thread support is not built in. The
+other debugging fields will still be present as well.
+
+If POSIX thread support and weak references are available, both the
+POSIX mutex and a flag will be included; which one is used is
+determined at run time depending on whether the thread support
+routines are available.
@end deftp
@defvr Macro K5_MUTEX_PARTIAL_INITIALIZER
@code{assert}.
@end deftypefn
-Mutexes are assumed not to be recursive (@i{i.e.}, if a thread has the
-mutex locked already, attempting to lock it again is an error). There
-is also no support assumed for ``trylock'' or ``lock with timeout''
-operations.
+Mutexes should be assumed not to be recursive; if a thread has the
+mutex locked already, attempting to lock it again is an error and may
+have unpredictable results (error return, abort, data corruption).
+There is also no support assumed for ``trylock'' or ``lock with
+timeout'' operations.
-The operating system interface is similar to the above interface, with
-@code{k5_os_} names used for the OS mutex manipulation code. The type
-and macros indicated above are wrappers that optionally add debugging
-code and other stuff. So the Kerberos library code should use the
-macros above, and ports to new thread systems should be done through
-the @code{k5_os_} layer.
+Kerberos library code should use the macros above, and ports to new
+thread systems should be done through the @code{k5_os_} layer.
+(@xref{Thread Shim Layer Implementation}.)
-Thread-local storage is managed through another interface layer
+Thread-local storage is managed through another interface layer:
@deftp {Enumerator} k5_key_t
This is an enumeration type which indicates which of the per-thread
just for convenience, and should not be visible to any application
code.
-@node Shared Libraries, , Thread Safety, Top
+@node Thread Shim Layer Implementation, , Internal Thread API, Thread Safety
+@section Thread Shim Layer Implementation
+
+Each of the @code{k5_mutex_} macros has a corresponding
+@code{k5_os_mutex_} macro which incorporates the operating system's
+mutex object, a flag for non-threaded systems, or both if the use of
+the OS pthread support is left until run time. The @code{k5_mutex_}
+wrappers add debugging information like the file and line number of
+the last lock or unlock call, where the mutex was created, @i{etc}.
+There may also be statistical information gathered, such as how long a
+thread waits for a mutex or how long the mutex is held. This is all
+defined in @file{k5-thread.h}.
+
+The thread-specific storage support is defined as macros expanding to
+similar function names with the @code{krb5int_} prefix, which
+functions are defined in @file{util/support/threads.c}. POSIX,
+Windows, and non-threaded versions are defined so far.
+
+The code for collecting and reporting statistics is also mainly in
+that file. Macros defined in @file{k5-thread.h} will expand to
+include calls to these functions, if @code{DEBUG_THREADS_STATS} is
+defined, or do nothing.
+
+@node Shared Libraries, Porting Issues, Thread Safety, Top
@chapter Shared Libraries
(These sections are old -- they should get updated.)
constructed by a programmer familiar with the AIX internals.}
All operating systems (that we have seen) provide a means for programs
-to specify the location of shared libraries. On different operating
+to specify the location of shared libraries. On different operating
systems, this is either specified when creating the shared library, and
link time, or both.@footnote{Both are necessary sometimes as the shared
-libraries are dependent on other shared libraries} The build process
+libraries are dependent on other shared libraries.} The build process
will hardwire a path to the installed destination.
@node Advanced Shared Library Requirements, Operating System Notes for Shared Libraries, Shared Library Theory, Shared Libraries
@file{win_glue.c} at load time; it should complete before the
library's symbol table is made accessible to the calling process.
+Windows note: There are limitations on what @code{DllMain} should do
+in the initialization and finalization cases, and unfortunately we've
+found that we do some of these things (specifically, calling
+@code{WSAStartup} and @code{WSACleanup}, and loading other libraries
+which do so also). Until we can rectify this problem, there is a
+chance that explicitly unloading an MIT Kerberos library from an
+application (more specifically, from within the @code{DllMain} of
+another library) may cause a deadlock.
@end itemize
-The library finalization code is similarly platform-dependent. If the
-compiler or linker lets us specify that a function should be called as
-a finalization function (for example, @code{gcc}'s ``destructor''
-attribute), we use it.
+Library finalization is similarly dependent on the platform and
+configuration:
+
+@itemize @bullet
+
+@item
+In static-library builds, since the library will be unloaded only when
+the entire process calls @code{exit} or @code{exec} or otherwise
+ceases to exist in its current form, freeing up memory resources in
+the process, finalization can be skipped.
+
+@item
+On UNIX platforms with library finalization support in shared
+libraries, the (OS-level) finalization function is specified to run
+the library's (shim-level) finalization function. If @code{gcc}'s
+``destructor'' attribute appears to work, we use that.
+
+@item
+On UNIX platforms without library finalization function support,
+the finalization functions won't get called if the library is
+unloaded. Resources (probably just memory) will be leaked.
+
+@item
+On Windows, the finalization code is run out of @code{DllMain} in
+@file{win_glue.c} at unload time. See the warnings above.
+
+@end itemize
+
+If there are other limitations on what operations can be performed in
+shared library initialization and finalization routines on some
+systems, the MIT Kerberos team would appreciate specific information
+on these limitations.
The internal interface currently used within the code of the Kerberos
libraries consists of four macros:
@example
int @var{fname} (void) @{ ... @}
@end example
-This macro will define additional data and possibly function objects,
+This macro may define additional data and function objects,
and will declare @var{fname}, though it may or may not declare
@var{fname} as @code{static}. (Under C rules, the declaration above
is compatible with a declaration of the function as @code{static}, and
-@code{static} does apply, as long as the @code{static} declaration
+@code{static} linkage does apply, as long as the @code{static} declaration
comes first.)
When the function is invoked, the return value --- zero or an error
code --- will be saved away, and returned any time
@code{CALL_INIT_FUNCTION} is used.
-There may be only one initialization function declared this way in
-each UNIX library, currently.
+There can be multiple initialization functions defined this way in a
+library.
@end defmac
@defmac MAKE_FINI_FUNCTION (@var{fname})
void @var{fname} (void) @{ ... @}
@end example
-There may be only one finalization function declared this way in each
-UNIX library, currently.
+There may be multiple finalization functions defined for a library.
@end defmac
@deftypefn Macro int CALL_INIT_FUNCTION (@var{fname})
doing that.
@end deftypefn
+The @file{Makefile.in} for the library must define two variables,
+@code{LIBINITFUNC} and @code{LIBFINIFUNC}, containing a (possibly
+empty) list of the names of the initialization and finalization
+functions for the library as built under UNIX, ordered from
+lowest-level (initialized first, finalized last) to highest-level.
+(Windows and Mac OS X builds work differently.)
+
Note that all of this assumes shared libraries. If static linking is
done, our options are a bit more limited. We assume
@code{pthread_once} is available if there is any thread support
library is built, and the commands set up at configuration time by
@file{shlib.conf} can specify any processing to be done on those files
(@i{e.g.}, insertion of leading underscores or linker command-line
-arguments.
+arguments).
-(updated 7/20/2004)
+For some systems with somewhat non-trivial commands that need to be
+run to convert the export list into the proper form, file targets can be
+defined in @file{config/lib.in}.
@node Operating System Notes for Shared Libraries, , Advanced Shared Library Requirements, Shared Libraries
@section Operating System Notes for Shared Libraries
@menu
* AIX Shared Library Support::
* Alpha OSF/1 Shared Library Support::
+* ELF Shared Library Support::
@end menu
@node AIX Shared Library Support, Alpha OSF/1 Shared Library Support, Operating System Notes for Shared Libraries, Operating System Notes for Shared Libraries
shared @samp{libkrb5.a} when GNU C is used.
-@node Alpha OSF/1 Shared Library Support, , AIX Shared Library Support, Operating System Notes for Shared Libraries
+@node Alpha OSF/1 Shared Library Support, ELF Shared Library Support, AIX Shared Library Support, Operating System Notes for Shared Libraries
@subsection Alpha OSF/1 Shared Library Support
Shared library support has been tested with V2.1 and higher of the
@samp{-rpath} before LD_LIBRARY_PATH so we must specify a dummy _RLD_ROOT
and complete LD_LIBRARY_PATH in our tests.
-The one disadvantage with the method we are using....
+The one disadvantage with the method we are using.... [What?? This
+never got finished!]
+
+@node ELF Shared Library Support, , Alpha OSF/1 Shared Library Support, Operating System Notes for Shared Libraries
+@subsection ELF Shared Library Support
+
+It's tempting to add @samp{-Bsymbolic} to the commands for generating
+shared libraries. We don't explicitly support overriding our
+(internal or public) symbol names by applications, and binding at
+shared library creation time would result in smaller libraries that
+would load faster. However, it won't work. At least with the GNU and
+Solaris linkers and runtime environments, an executable using a data
+symbol exported by a shared library gets a copy of that data,
+initialized at run time by copying, and the program will only function
+properly if that definition can override the one present in the shared
+library. And, sadly, some of our shared libraries export variables
+that are directly referenced from programs.
+
+@node Porting Issues, , Shared Libraries, Top
+@chapter Porting Issues
+
+[Snipped from email from Ken Raeburn in reply to email asking about
+porting MIT Kerberos to pSOS; maybe it'll be of use to someone else.]
+
+> - Any Porting issues to be considered?
+
+Yes. Our build procedure currently assumes that the machine used for
+building is either a UNIX (or similar) system, or running Windows; it
+also assumes that it's a native compilation, not a cross compilation.
+I'm not familiar with pSOS, but assuming that you do cross compilation
+on another OS, how you deal with that depends on the host system.
+
+UNIX host: The configure script attempts to learn a bunch of
+attributes about the host system (program names, availability of
+header files and functions and libraries) and uses them to decide how
+to build the krb5 libraries and programs. Many attributes are tested
+by running the compiler with various options and test source files, so
+if you tell the configure script to run a cross compiler, it may come
+up with most of the right answers, if you can arrange for success and
+failure indications to be given at compile/link time. (This probably
+wouldn't work well for VxWorks, for example, where symbol resolution
+is done when the object code is loaded into the OS.)
+
+The configure script generates include/autoconf.h to influence
+whether certain calls are made or certain headers are included, and
+Makefile in each directory to indicate compilation options. Each
+source directory has a Makefile.in, and config/pre.in and
+config/post.in are incorporated into each generate Makefile. Various
+@@FOO@@ sequences are substituted based on the system attributes or
+configure options. (Aside from always using the config/ fragments,
+this is typical of GNU Autoconf based software configuration.)
+
+Windows host: The ``wconfig'' program generates the Makefiles in
+subdirectories, with config/win-pre.in and config/win-post.in used in
+combination with each Makefile.in, and lines starting @code{##WIN32##}
+are uncommented, but @code{@@FOO@@} substitutions are not done.
+Instead of generating @file{autoconf.h}, it's copied from
+@file{include/win-mac.h}, where we've hardcoded some of the parameters
+we care about, and just left a bunch of others out. If you work with
+a Windows host, you may want to provide your own makefile fragments,
+and a replacement for @file{win-mac.h} or some additional data to go
+into it conditionalized on some preprocessor symbol for pSOS.
+
+There are also places where we assume that certain header files or
+functions are available, because both (most) UNIX and Windows
+platforms (that we care about currently) provide them. And probably a
+handful of places where we check for @code{_WIN32} to decide between ``the
+Windows way'' and ``everything else'' (i.e., UNIX); you might need to add
+a third branch for pSOS. And some places where we've got hooks for
+Kerberos for Mac support, which you can probably ignore.
+
+Our build environment assumes that Perl is available, but it's only
+needed in the build process, not for run time. If Tcl is available,
+on UNIX, a few more programs may be built that are used for testing
+some interfaces, but a cross compiler should notice that it can't link
+against the native Tcl libraries, and configure should choose not to
+build those programs.
+
+In the current 1.4 beta code, our library wants to find routines for
+making DNS queries (SRV and TXT RR queries specifically) that are
+outside the scope of getaddrinfo and friends. We also look for
+@file{/dev/random} as a strong random number source, and text files
+for configuration information. Our code assumes that allocating and
+reallocating lots of little (or not so little) bits of memory isn't
+too horribly expensive, and we don't take any special pains to keep
+our stack size small. Depending how pSOS works, you may need to add
+to the thread support code. (The MIT code doesn't create threads, but
+will do locking and such to allow multiple threads to share global
+data. The code in @file{include/k5-thread.h} is, uh, kind of
+involved, and some pains have been taken to use macros whenever
+possible to allow @code{assert()} calls during debugging to report
+useful line numbers.) There are probably other minor issues to deal
+with, I'm just making some guesses.
+
+> - what type of Data formats exchanged between Client and Server?
+
+If you're aiming for a server implementation only, it'll depend on the
+exact protocol you wish to use, but typically the Kerberos application
+server needs to accept the AP-REQ message and generate the AP-REP
+message. Protection for the data to be transferred depends on on the
+application protocol. For example, Kerberos provides some message
+types for encapsulating application data with or without encryption;
+the Kerberos mechanism for GSSAPI uses the Kerberos session key to
+protect application data in a different message format.
+
+The server implementation would also need some secure means of getting
+the service principal's key stored away.
+
+If you want client code support as well under pSOS, then you may have
+to deal with DNS queries to find the KDC,
+AS-REQ/AS-REP/TGS-REQ/TGS-REP message exchanges, and generating AP-REQ
+and accepting AP-REP messages, etc.
@contents
@bye
projects / krb5.git / blobdiff