"Fossies" - the Fresh Open Source Software Archive

Member "krb5-1.18/doc/thread-safe.txt" (12 Feb 2020, 8981 Bytes) of package /linux/misc/krb5-1.18.tar.gz:


As a special service "Fossies" has tried to format the requested text file into HTML format (style: standard) with prefixed line numbers. Alternatively you can here view or download the uninterpreted source code file. For more information about "thread-safe.txt" see the Fossies "Dox" file reference documentation.

    1 [May be out of date.  Last significant update: Jan 2005.]
    2 
    3 In general, it's assumed that the library initialization function (if
    4 initialization isn't delayed) and the library finalization function
    5 are run in some thread-safe fashion, with no other parts of the
    6 library in question in use.  (If dlopen or dlsym in one thread starts
    7 running the initializer, and then dlopen/dlsym in another thread
    8 returns and lets you start accessing functions or data in the library
    9 before the initializer is finished, that really seems like a
   10 dlopen/dlsym bug.)
   11 
   12 It's also assumed that if library A depends on library B, then library
   13 B's initializer runs first, and its finalizer last, whether loading
   14 dynamically at run time or at process startup/exit.  (It appears that
   15 AIX 4.3.3 may violate this, at least when we use gcc's
   16 constructor/destructor attributes in shared libraries.)
   17 
   18 Support for freeing the heap storage allocated by a library has NOT,
   19 in general, been written.  There are hooks, but often they ignore some
   20 of the library's local storage, mutexes, etc.
   21 
   22 If shared library finalization code doesn't get run at all at dlclose
   23 time, or if we can't use it because the execution order is wrong, then
   24 you'll get memory leaks.  Deal with it.
   25 
   26 Several debugging variables that are not part of our official API are
   27 not protected by mutexes.  In general, the only way to set them is by
   28 changing the sources and recompiling, which obviously has no run-time
   29 thread safety issues, or by stopping the process under a debugger,
   30 which we blithely assert is "safe enough".
   31 
   32 Debug code that we don't normally enable may be less thread safe than
   33 might be desired.  For example, multiple printf calls may be made,
   34 with the assumption that the output will not be intermixed with output
   35 from some other thread.  Offhand, I'm not aware of any cases where
   36 debugging code is "really" unsafe, as in likely to crash the program
   37 or produce insecure results.
   38 
   39 Various libraries may call assert() and abort().  This should only be
   40 for "can't happen" cases, and indicate programming errors.  In some
   41 cases, the compiler may be able to infer that the "can't happen" cases
   42 really can't happen, and drop the calls, but in many cases, this is
   43 not possible.
   44 
   45 There are cases (e.g., in the com_err library) where errors arising
   46 when dealing with other errors are handled by calling abort, for lack
   47 of anything better.  We should probably clean those up someday.
   48 
   49 Various libraries call getenv().  This is perfectly safe, as long as
   50 nothing is calling setenv or putenv or what have you, while multiple
   51 threads are executing.  Of course, that severely curtails the ability
   52 to control our libraries through that "interface".
   53 
   54 Various libraries call the ctype functions/macros (isupper, etc).  It
   55 is assumed that the program does not call setlocale, or does so only
   56 while the program is still single-threaded or while calls into the
   57 Kerberos libraries are not in progress.
   58 
   59 The Windows thread safety support is unfinished.
   60 
   61 I'm assuming that structure fields that are never written to (e.g.,
   62 after a structure has been initialized and *then* made possibly
   63 visible to multiple threads) are safe to read from one thread while
   64 another field is being updated by another thread.  If that's not the
   65 case, some more work is needed (and I'd like details on why it's not
   66 safe).
   67 
   68 ----------------
   69 
   70 libcom_err
   71 
   72 Issues:
   73 
   74 The callback hook support (set_com_err_hook, reset_com_err_hook, and
   75 calls to com_err and com_err_va) uses a mutex to protect the handle on
   76 the hook function.  As a side effect of this, if a callback function
   77 is registered which pops up a window and waits for the users'
   78 acknowledgement, then other errors cannot be reported by other threads
   79 until after the acknowledgement.  This could be fixed with
   80 multiple-reader-one-writer type locks, but that's a bit more
   81 complicated.
   82 
   83 The string returned by error_message may be per-thread storage.  It
   84 can be passed off between threads, but it shouldn't be in use by any
   85 thread by the time the originating thread calls error_message again.
   86 
   87 Error tables must no longer be in use (including pointers returned by
   88 error_message) when the library containing them is unloaded.
   89 
   90 Temporary: A flag variable has been created in error_message.c which
   91 is used to try to catch cases where remove_error_table is called after
   92 the library finalization function.  This generally indicates
   93 out-of-order execution of the library finalization functions.  The
   94 handling of this flag is not thread-safe, but if the finalization
   95 function is called, other threads should in theory be finished with
   96 this library anyways.
   97 
   98 Statics: error_message.c, com_err.c, covered above.
   99 
  100 ----------------
  101 
  102 libprofile (and its use in libkrb5)
  103 
  104 Does no checks to see if it's opened multiple instances of the same
  105 file under different names.  Does not guard against trying to open a
  106 file while another thread or process is in the process of replacing
  107 it, or two threads trying to update a file at the same time.  The
  108 former should be pretty safe on UNIX with atomic rename, but on
  109 Windows there's a race condition; there's a window (so to speak) where
  110 the filename does not correspond to an actual file.
  111 
  112 Statics: prof_file.c, a list of opened config files and their parse
  113 trees, and a mutex to protect it.
  114 
  115 ----------------
  116 
  117 libk5crypto
  118 
  119 Uses of the Yarrow code from the krb5 crypto interface are protected
  120 by a single mutex.  Initialization of the Yarrow state will be done
  121 once, the first time these routines are called.  Calls directly to the
  122 Yarrow functions are not protected.
  123 
  124 Uses ctype macros; what happens if the locale is changed in a
  125 multi-threaded program?
  126 
  127 Debug var in pbkdf2.c.
  128 
  129 Statics: pbkdf2.c: debug variable.
  130 
  131 Statics: prng.c: Global Yarrow data and mutex.
  132 
  133 Statics: crypto_libinit.c: library initializer aux data.
  134 
  135 ----------------
  136 
  137 libkrb5
  138 
  139 (TBD)
  140 
  141 Uses: ctype macros
  142 
  143 Uses: getaddrinfo, getnameinfo.  According to current specifications,
  144 getaddrinfo should be thread-safe; some implementations are not, and
  145 we're not attempting to figure out which ones.  NetBSD 1.6, for
  146 example, had an unsafe implementation.
  147 
  148 Uses: res_ninit, res_nsearch.  If these aren't available, the non-'n'
  149 versions will be used, and they are sometimes not thread-safe.
  150 
  151 Uses: mkstemp, mktemp -- Are these, or our uses of them, likely to be
  152 thread-safe?
  153 
  154 Uses: sigaction
  155 
  156 The use of sigaction is in the code prompting for a password; we try
  157 to catch the keyboard interrupt character being used and turn it into
  158 an error return from that function.  THIS IS NOT THREAD-SAFE.
  159 
  160 Uses: tcgetattr, tcsetattr.  This is also in the password-prompting
  161 code.  These are fine as long as no other threads are accessing the
  162 same terminal at the same time.
  163 
  164 Uses: fopen.  This is thread-safe, actually, but a multi-threaded
  165 server is likely to be using lots of file descriptors.  On 32-bit
  166 Solaris platforms, fopen will not work if the next available file
  167 descriptor number is 256 or higher.  This can cause the keytab code to
  168 fail.
  169 
  170 Statics: prompter.c: interrupt flag
  171 
  172 Statics: ccdefops.c: default operations table pointer
  173 
  174 Statics: ktdefname.c: variable to override default keytab name, NO
  175 LOCKING.  DON'T TOUCH THESE VARIABLES, at least in threaded programs.
  176 
  177 Statics: conv_creds.c: debug variable
  178 
  179 Statics: sendto_kdc.c: debug variable, in export list for KDC
  180 
  181 Statics: parse.c: default realm cache, changed to not cache
  182 
  183 Statics: krb5_libinit.c: lib init aux data
  184 
  185 Statics: osconfig.c: various internal variables, probably should be const
  186 
  187 Statics: init_ctx.c: "brand" string; not written.
  188 
  189 Statics: cc_memory.c: list of caches, with mutex.
  190 
  191 Statics: c_ustime.c: last timestamp, to implement "microseconds must
  192 always increment"
  193 
  194 Statics: ktbase.c, ccbase.c, rc_base.c: type registries and mutexes.
  195 
  196 ----------------
  197 
  198 libgssapi_krb5
  199 
  200 (TBD)
  201 
  202 Uses: ctype macros
  203 
  204 Statics: acquire_cred.c: name of keytab to use, and mutex.
  205 
  206 Statics: gssapi_krb5.c:
  207 
  208 Statics: init_sec_context.c:
  209 
  210 Statics: set_ccache.c:
  211 
  212 Statics: gssapi_generic.c: OID definitions, non-const by
  213 specification.  We probably could make them const anyways.
  214 
  215 The keytab name saved away by krb5_gss_register_acceptor_identity is
  216 global and protected by a mutex; the ccache name stored by
  217 gss_krb5_ccache_name is per-thread.  This inconsistency is due to the
  218 anticipated usage patterns.
  219 
  220 The old ccache name returned by gss_krb5_ccache_name if the last
  221 parameter is not a null pointer is also stored per-thread, and will be
  222 discarded at the next call to that routine from the same thread, or at
  223 thread termination.
  224 
  225 Needs work: check various objects for thread safety
  226 
  227 ----------------
  228 
  229 libgssrpc
  230 
  231 New version is in place.  Ignore it for now?
  232 
  233 ----------------
  234 
  235 libkadm5*
  236 libkdb5
  237 
  238 Skip these for now.  We may want the KDC libraries to be thread-safe
  239 eventually, so the KDC can take better advantage of hyperthreaded or
  240 multiprocessor systems.
  241 
  242 ----------------
  243 
  244 libapputils
  245 libss
  246 
  247 Used by single-threaded programs only (but see above re KDC).  Don't
  248 bother for now.