--- JSON-XS/XS.pm	2007/03/25 02:37:00	1.22
+++ JSON-XS/XS.pm	2007/03/25 21:19:13	1.23
@@ -131,6 +131,7 @@
 
 =back
 
+
 =head1 OBJECT-ORIENTED INTERFACE
 
 The object oriented interface lets you configure your own encoding or
@@ -303,6 +304,26 @@
 strings that look like integers or floats into integers or floats
 internally (there is no difference on the Perl level), saving space.
 
+=item $json = $json->max_depth ([$maximum_nesting_depth])
+
+Sets the maximum nesting level (default C<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 C<{> or C<[>
+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 C<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.
+
 =item $json_text = $json->encode ($perl_scalar)
 
 Converts the given Perl data structure (a simple scalar or a reference
@@ -323,6 +344,7 @@
 
 =back
 
+
 =head1 MAPPING
 
 This section describes how JSON::XS maps Perl values to JSON values and
@@ -443,6 +465,7 @@
 
 =back
 
+
 =head1 COMPARISON
 
 As already mentioned, this module was created because none of the existing
@@ -580,19 +603,42 @@
 to decode or encode properly, so it was impossible to prepare a fair
 comparison table for that case.
 
-=head1 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.
+=head1 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 C<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...
+
 
 =head1 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.
 
 =cut