--- JSON-XS/README	2007/03/25 00:47:42	1.7
+++ JSON-XS/README	2007/03/25 22:11:06	1.8
@@ -4,12 +4,17 @@
 SYNOPSIS
      use JSON::XS;
 
-     # exported functions, croak on error
+     # exported functions, they croak on error
+     # and expect/generate UTF-8
 
      $utf8_encoded_json_text = to_json $perl_hash_or_arrayref;
      $perl_hash_or_arrayref  = from_json $utf8_encoded_json_text;
 
-     # oo-interface
+     # objToJson and jsonToObj aliases to to_json and from_json
+     # are exported for compatibility to the JSON module,
+     # but should not be used in new code.
+
+     # OO-interface
 
      $coder = JSON::XS->new->ascii->pretty->allow_nonref;
      $pretty_printed_unencoded = $coder->encode ($perl_scalar);
@@ -32,14 +37,15 @@
     vice versa.
 
   FEATURES
-    * correct handling of unicode issues
+    * correct unicode handling
         This module knows how to handle Unicode, and even documents how and
         when it does so.
 
     * round-trip integrity
         When you serialise a perl data structure using only datatypes
         supported by JSON, the deserialised data structure is identical on
-        the Perl level. (e.g. the string "2.0" doesn't suddenly become "2").
+        the Perl level. (e.g. the string "2.0" doesn't suddenly become "2"
+        just because it looks like a number).
 
     * strict checking of JSON correctness
         There is no guessing, no generating of illegal JSON texts by
@@ -57,9 +63,10 @@
     * reasonably versatile output formats
         You can choose between the most compact guarenteed single-line
         format possible (nice for simple line-based protocols), a pure-ascii
-        format (for when your transport is not 8-bit clean), or a
-        pretty-printed format (for when you want to read that stuff). Or you
-        can combine those features in whatever way you like.
+        format (for when your transport is not 8-bit clean, still supports
+        the whole unicode range), or a pretty-printed format (for when you
+        want to read that stuff). Or you can combine those features in
+        whatever way you like.
 
 FUNCTIONAL INTERFACE
     The following convinience methods are provided by this module. They are
@@ -254,6 +261,26 @@
         or floats internally (there is no difference on the Perl level),
         saving space.
 
+    $json = $json->max_depth ([$maximum_nesting_depth])
+        Sets the maximum nesting level (default 8192) accepted while
+        encoding or decoding. If the JSON text or Perl data structure has an
+        equal or higher nesting level then this limit, then the encoder and
+        decoder will stop and croak at that point.
+
+        Nesting level is defined by number of hash- or arrayrefs that the
+        encoder needs to traverse to reach a given point or the number of
+        "{" or "[" characters without their matching closing parenthesis
+        crossed to reach a given character in a string.
+
+        Setting the maximum depth to one disallows any nesting, so that
+        ensures that the object is only a single hash/object or array.
+
+        The argument to "max_depth" will be rounded up to the next nearest
+        power of two.
+
+        See SECURITY CONSIDERATIONS, below, for more info on why this is
+        useful.
+
     $json_text = $json->encode ($perl_scalar)
         Converts the given Perl data structure (a simple scalar or a
         reference to a hash or array) to its JSON representation. Simple
@@ -502,17 +529,38 @@
     refuse to decode or encode properly, so it was impossible to prepare a
     fair comparison table for that case.
 
-RESOURCE LIMITS
-    JSON::XS does not impose any limits on the size of JSON texts or Perl
-    values they represent - if your machine can handle it, JSON::XS will
-    encode or decode it. Future versions might optionally impose structure
-    depth and memory use resource limits.
+SECURITY CONSIDERATIONS
+    When you are using JSON in a protocol, talking to untrusted potentially
+    hostile creatures requires relatively few measures.
+
+    First of all, your JSON decoder should be secure, that is, should not
+    have any buffer overflows. Obviously, this module should ensure that and
+    I am trying hard on making that true, but you never know.
+
+    Second, you need to avoid resource-starving attacks. That means you
+    should limit the size of JSON texts you accept, or make sure then when
+    your resources run out, thats just fine (e.g. by using a separate
+    process that can crash safely). The size of a JSON text in octets or
+    characters is usually a good indication of the size of the resources
+    required to decode it into a Perl structure.
+
+    Third, JSON::XS recurses using the C stack when decoding objects and
+    arrays. The C stack is a limited resource: for instance, on my amd64
+    machine with 8MB of stack size I can decode around 180k nested arrays
+    but only 14k nested JSON objects. If that is exceeded, the program
+    crashes. Thats why the default nesting limit is set to 8192. If your
+    process has a smaller stack, you should adjust this setting accordingly
+    with the "max_depth" method.
+
+    And last but least, something else could bomb you that I forgot to think
+    of. In that case, you get to keep the pieces. I am alway sopen for
+    hints, though...
 
 BUGS
     While the goal of this module is to be correct, that unfortunately does
     not mean its bug-free, only that I think its design is bug-free. It is
-    still very young and not well-tested. If you keep reporting bugs they
-    will be fixed swiftly, though.
+    still relatively early in its development. If you keep reporting bugs
+    they will be fixed swiftly, though.
 
 AUTHOR
      Marc Lehmann <schmorp@schmorp.de>