Document json_object_seed()

2 files changed, 60 insertions, 3 deletions

diff --git a/doc/apiref.rst b/doc/apiref.rst
index 8af0800..60ad48a 100644
--- a/doc/apiref.rst
+++ b/doc/apiref.rst
@@ -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
 ===============
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
 ------