diff options
Diffstat (limited to 'doc/portability.rst')
| -rw-r--r-- | doc/portability.rst | 37 |
1 files changed, 34 insertions, 3 deletions
diff --git a/doc/portability.rst b/doc/portability.rst index dc6c5eb..272e46a 100644 --- a/doc/portability.rst +++ b/doc/portability.rst @@ -2,13 +2,14 @@ Portability *********** +.. _portability-thread-safety: + Thread safety ------------- Jansson is thread safe and has no mutable global state. The only -exception are the memory allocation functions, that should be set at -most once, and only on program startup. See -:ref:`apiref-custom-memory-allocation`. +exceptions are the hash function seed and memory allocation functions, +see below. There's no locking performed inside Jansson's code, so a multithreaded program must perform its own locking if JSON values are shared by @@ -30,6 +31,36 @@ contained values with another array or object. If you want to make sure that two JSON value hierarchies do not contain shared values, use :func:`json_deep_copy()` to make copies. + +Hash function seed +================== + +To prevent an attacker from intentionally causing large JSON objects +with specially crafted keys to perform very slow, the hash function +used by Jansson is randomized using a seed value. The seed is +automatically generated on the first explicit or implicit call to +:func:`json_object()`, if :func:`json_object_seed()` has not been +called beforehand. + +The seed is generated by using operating system's entropy sources if +they are available (``/dev/urandom``, ``CryptGenRandom()``). The +initialization is done in as thread safe manner as possible, by using +architecture specific lockless operations if provided by the platform +or the compiler. + +If you're using threads, it's recommended to autoseed the hashtable +explicitly before spawning any threads by calling +``json_object_seed(0)`` , especially if you're unsure whether the +initialization is thread safe on your platform. + + +Memory allocation functions +=========================== + +Memory allocation functions should be set at most once, and only on +program startup. See :ref:`apiref-custom-memory-allocation`. + + Locale ------ |