FGCOM/jansson
2
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Document json_object_seed()

Browse Source
This commit is contained in:
Petri Lehtinen 2014-02-11 09:24:42 +02:00
parent 8f80c2d838
commit 492feb26ce
2 changed files with 60 additions and 3 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

26
doc/apiref.rst
View File

@ -717,6 +717,32 @@ The iteration protocol can be used for example as follows::
iter = json_object_iter_next(obj, iter);
}
.. function:: void json_object_seed(size_t seed)
Seed the hash function used in Jansson's hashtable implementation.
The seed is used to randomize the hash function so that an
attacker cannot control its output.
If *seed* is 0, Jansson generates the seed itselfy by reading
random data from the operating system's entropy sources. If no
entropy sources are available, falls back to using a combination
of the current timestamp (with microsecond precision if possible)
and the process ID.
If called at all, this function must be called before any calls to
:func:`json_object()`, either explicit or implicit. If this
function is not called by the user, the first call to
:func:`json_object()` (either explicit or implicit) seeds the hash
function. See :ref:`portability-thread-safety` for notes on thread
safety.
If repeatable results are required, for e.g. unit tests, the hash
function can be "unrandomized" by calling :func:`json_object_seed`
with a constant value on program startup, e.g.
``json_object_seed(1)``.
.. versionadded:: 2.6
Error reporting
===============

37
doc/portability.rst
View File

@ -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
------