ViewVC Help
View File | Revision Log | Show Annotations | Download File
/cvs/JSON-XS/XS.pm
(Generate patch)

Comparing JSON-XS/XS.pm (file contents):
Revision 1.168 by root, Thu Nov 15 20:13:03 2018 UTC vs.
Revision 1.169 by root, Thu Nov 15 20:49:12 2018 UTC

… …
202=over 4 202=over 4
203 203
204=item $json = new JSON::XS 204=item $json = new JSON::XS
205 205
206Creates a new JSON::XS object that can be used to de/encode JSON 206Creates a new JSON::XS object that can be used to de/encode JSON
207strings. All boolean flags described below are by default I<disabled>. 207strings. All boolean flags described below are by default I<disabled>
208(with the exception of C<allow_nonref>, which defaults to I<enabled> since
209version C<4.0>).
208 210
209The mutators for flags all return the JSON object again and thus calls can 211The mutators for flags all return the JSON object again and thus calls can
210be chained: 212be chained:
211 213
212 my $json = JSON::XS->new->utf8->space_after->encode ({a => [1,2]}) 214 my $json = JSON::XS->new->utf8->space_after->encode ({a => [1,2]})
… …
441 443
442=item $json = $json->allow_nonref ([$enable]) 444=item $json = $json->allow_nonref ([$enable])
443 445
444=item $enabled = $json->get_allow_nonref 446=item $enabled = $json->get_allow_nonref
445 447
448Unlike other boolean options, this opotion is enabled by default beginning
449with version C<4.0>. See L<SECURITY CONSIDERATIONS> for the gory details.
450
446If C<$enable> is true (or missing), then the C<encode> method can convert a 451If C<$enable> is true (or missing), then the C<encode> method can convert a
447non-reference into its corresponding string, number or null JSON value, 452non-reference into its corresponding string, number or null JSON value,
448which is an extension to RFC4627. Likewise, C<decode> will accept those JSON 453which is an extension to RFC4627. Likewise, C<decode> will accept those JSON
449values instead of croaking. 454values instead of croaking.
450 455
451If C<$enable> is false, then the C<encode> method will croak if it isn't 456If C<$enable> is false, then the C<encode> method will croak if it isn't
452passed an arrayref or hashref, as JSON texts must either be an object 457passed an arrayref or hashref, as JSON texts must either be an object
453or array. Likewise, C<decode> will croak if given something that is not a 458or array. Likewise, C<decode> will croak if given something that is not a
454JSON object or array. 459JSON object or array.
455 460
456Example, encode a Perl scalar as JSON value with enabled C<allow_nonref>, 461Example, encode a Perl scalar as JSON value without enabled C<allow_nonref>,
457resulting in an invalid JSON text: 462resulting in an error:
458 463
459 JSON::XS->new->allow_nonref->encode ("Hello, World!") 464 JSON::XS->new->allow_nonref (0)->encode ("Hello, World!")
460 => "Hello, World!" 465 => hash- or arrayref expected...
461 466
462=item $json = $json->allow_unknown ([$enable]) 467=item $json = $json->allow_unknown ([$enable])
463 468
464=item $enabled = $json->get_allow_unknown 469=item $enabled = $json->get_allow_unknown
465 470
… …
1567are browser design bugs, but it is still you who will have to deal with 1572are browser design bugs, but it is still you who will have to deal with
1568it, as major browser developers care only for features, not about getting 1573it, as major browser developers care only for features, not about getting
1569security right). 1574security right).
1570 1575
1571 1576
1572=head1 "OLD" VS. "NEW" JSON (RFC 4627 VS. RFC 7159) 1577=head2 "OLD" VS. "NEW" JSON (RFC 4627 VS. RFC 7159)
1573 1578
1574TL;DR: Due to security concerns, JSON::XS will not allow scalar data in 1579JSON originally required JSON texts to represent an array or object -
1575JSON texts by default - you need to create your own JSON::XS object and 1580scalar values were explicitly not allowed. This has changed, and versions
1576enable C<allow_nonref>: 1581of JSON::XS beginning with C<4.0> reflect this by allowing scalar values
1582by default.
1577 1583
1584One reason why one might not want this is that this removes a fundamental
1585property of JSON texts, namely that they are self-delimited and
1586self-contained, or in other words, you could take any number of "old"
1587JSON texts and paste them together, and the result would be unambiguously
1588parseable:
1578 1589
1590 [1,3]{"k":5}[][null] # four JSON texts, without doubt
1591
1592By allowing scalars, this property is lost: in the following example, is
1593this one JSON text (the number 12) or two JSON texts (the numbers 1 and
15942):
1595
1596 12 # could be 12, or 1 and 2
1597
1598Another lost property of "old" JSON is that no lookahead is required to
1599know the end of a JSON text, i.e. the JSON text definitely ended at the
1600last C<]> or C<}> character, there was no need to read extra characters.
1601
1602For example, a viable network protocol with "old" JSON was to simply
1603exchange JSON texts without delimiter. For "new" JSON, you have to use a
1604suitable delimiter (such as a newline) after every JSON text or ensure you
1605never encode/decode scalar values.
1606
1607Most protocols do work by only transferring arrays or objects, and the
1608easiest way to avoid problems with the "new" JSON definition is to
1609explicitly disallow scalar values in your encoder and decoder:
1610
1579 my $json = JSON::XS->new->allow_nonref; 1611 $json_coder = JSON::XS->new->allow_nonref (0)
1580 1612
1581 $text = $json->encode ($data); 1613This is a somewhat unhappy situation, and the blame can fully be put on
1582 $data = $json->decode ($text); 1614JSON's inmventor, Douglas Crockford, who unilaterally changed the format
1583 1615in 2006 without consulting the IETF, forcing the IETF to either fork the
1584The long version: JSON being an important and supposedly stable format, 1616format or go with it (as I was told, the IETF wasn't amused).
1585the IETF standardised it as RFC 4627 in 2006. Unfortunately, the inventor
1586of JSON, Dougles Crockford, unilaterally changed the definition of JSON in
1587javascript. Rather than create a fork, the IETF decided to standardise the
1588new syntax (apparently, so Iw as told, without finding it very amusing).
1589
1590The biggest difference between thed original JSON and the new JSON is that
1591the new JSON supports scalars (anything other than arrays and objects) at
1592the toplevel of a JSON text. While this is strictly backwards compatible
1593to older versions, it breaks a number of protocols that relied on sending
1594JSON back-to-back, and is a minor security concern.
1595
1596For example, imagine you have two banks communicating, and on one side,
1597trhe JSON coder gets upgraded. Two messages, such as C<10> and C<1000>
1598might then be confused to mean C<101000>, something that couldn't happen
1599in the original JSON, because niether of these messages would be valid
1600JSON.
1601
1602If one side accepts these messages, then an upgrade in the coder on either
1603side could result in this becoming exploitable.
1604
1605This module has always allowed these messages as an optional extension, by
1606default disabled. The security concerns are the reason why the default is
1607still disabled, but future versions might/will likely upgrade to the newer
1608RFC as default format, so you are advised to check your implementation
1609and/or override the default with C<< ->allow_nonref (0) >> to ensure that
1610future versions are safe.
1611 1617
1612 1618
1613=head1 INTEROPERABILITY WITH OTHER MODULES 1619=head1 INTEROPERABILITY WITH OTHER MODULES
1614 1620
1615C<JSON::XS> uses the L<Types::Serialiser> module to provide boolean 1621C<JSON::XS> uses the L<Types::Serialiser> module to provide boolean

Diff Legend

– Removed lines
+ Added lines
< Changed lines
> Changed lines