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.152 by root, Wed Oct 30 22:11:01 2013 UTC vs.
Revision 1.157 by root, Fri Feb 26 21:46:45 2016 UTC

… …
101 101
102package JSON::XS; 102package JSON::XS;
103 103
104use common::sense; 104use common::sense;
105 105
106our $VERSION = 3.01; 106our $VERSION = 3.02;
107our @ISA = qw(Exporter); 107our @ISA = qw(Exporter);
108 108
109our @EXPORT = qw(encode_json decode_json); 109our @EXPORT = qw(encode_json decode_json);
110 110
111use Exporter; 111use Exporter;
… …
402character, after which more white-space and comments are allowed. 402character, after which more white-space and comments are allowed.
403 403
404 [ 404 [
405 1, # this comment not allowed in JSON 405 1, # this comment not allowed in JSON
406 # neither this one... 406 # neither this one...
407 ]
408
409=item * literal ASCII TAB characters in strings
410
411Literal ASCII TAB characters are now allowed in strings (and treated as
412C<\t>).
413
414 [
415 "Hello\tWorld",
416 "Hello<TAB>World", # literal <TAB> would not normally be allowed
407 ] 417 ]
408 418
409=back 419=back
410 420
411=item $json = $json->canonical ([$enable]) 421=item $json = $json->canonical ([$enable])
… …
687 697
688This is useful if your JSON texts are not delimited by an outer protocol 698This is useful if your JSON texts are not delimited by an outer protocol
689and you need to know where the JSON text ends. 699and you need to know where the JSON text ends.
690 700
691 JSON::XS->new->decode_prefix ("[1] the tail") 701 JSON::XS->new->decode_prefix ("[1] the tail")
692 => ([], 3) 702 => ([1], 3)
693 703
694=back 704=back
695 705
696 706
697=head1 INCREMENTAL PARSING 707=head1 INCREMENTAL PARSING
… …
1553are browser design bugs, but it is still you who will have to deal with 1563are browser design bugs, but it is still you who will have to deal with
1554it, as major browser developers care only for features, not about getting 1564it, as major browser developers care only for features, not about getting
1555security right). 1565security right).
1556 1566
1557 1567
1568=head1 "OLD" VS. "NEW" JSON (RFC 4627 VS. RFC 7159)
1569
1570TL;DR: Due to security concerns, JSON::XS will not allow scalar data in
1571JSON texts by default - you need to create your own JSON::XS object and
1572enable C<allow_nonref>:
1573
1574
1575 my $json = JSON::XS->new->allow_nonref;
1576
1577 $text = $json->encode ($data);
1578 $data = $json->decode ($text);
1579
1580The long version: JSON being an important and supposedly stable format,
1581the IETF standardised it as RFC 4627 in 2006. Unfortunately, the inventor
1582of JSON, Dougles Crockford, unilaterally changed the definition of JSON in
1583javascript. Rather than create a fork, the IETF decided to standardise the
1584new syntax (apparently, so Iw as told, without finding it very amusing).
1585
1586The biggest difference between thed original JSON and the new JSON is that
1587the new JSON supports scalars (anything other than arrays and objects) at
1588the toplevel of a JSON text. While this is strictly backwards compatible
1589to older versions, it breaks a number of protocols that relied on sending
1590JSON back-to-back, and is a minor security concern.
1591
1592For example, imagine you have two banks communicating, and on one side,
1593trhe JSON coder gets upgraded. Two messages, such as C<10> and C<1000>
1594might then be confused to mean C<101000>, something that couldn't happen
1595in the original JSON, because niether of these messages would be valid
1596JSON.
1597
1598If one side accepts these messages, then an upgrade in the coder on either
1599side could result in this becoming exploitable.
1600
1601This module has always allowed these messages as an optional extension, by
1602default disabled. The security concerns are the reason why the default is
1603still disabled, but future versions might/will likely upgrade to the newer
1604RFC as default format, so you are advised to check your implementation
1605and/or override the default with C<< ->allow_nonref (0) >> to ensure that
1606future versions are safe.
1607
1608
1558=head1 INTEROPERABILITY WITH OTHER MODULES 1609=head1 INTEROPERABILITY WITH OTHER MODULES
1559 1610
1560C<JSON::XS> uses the L<Types::Serialiser> module to provide boolean 1611C<JSON::XS> uses the L<Types::Serialiser> module to provide boolean
1561constants. That means that the JSON true and false values will be 1612constants. That means that the JSON true and false values will be
1562comaptible to true and false values of iother modules that do the same, 1613comaptible to true and false values of iother modules that do the same,
… …
1612 1663
1613And after decoding the JSON text, you could walk the data 1664And after decoding the JSON text, you could walk the data
1614structure looking for arrays with a first element of 1665structure looking for arrays with a first element of
1615C<XU1peReLzT4ggEllLanBYq4G9VzliwKF>. 1666C<XU1peReLzT4ggEllLanBYq4G9VzliwKF>.
1616 1667
1617The same approach cna be used to create the tagged format with another 1668The same approach can be used to create the tagged format with another
1618encoder. First, you create an array with the magic string as first member, 1669encoder. First, you create an array with the magic string as first member,
1619the classname as second, and constructor arguments last, encode it as part 1670the classname as second, and constructor arguments last, encode it as part
1620of your JSON structure, and then: 1671of your JSON structure, and then:
1621 1672
1622 $json =~ s/\[\s*"XU1peReLzT4ggEllLanBYq4G9VzliwKF"\s*,\s*("([^\\":,]+|\\.|::)*")\s*,/($1)[/g; 1673 $json =~ s/\[\s*"XU1peReLzT4ggEllLanBYq4G9VzliwKF"\s*,\s*("([^\\":,]+|\\.|::)*")\s*,/($1)[/g;
1623 1674
1624Again, this has some limitations - the magic string must not be encoded 1675Again, this has some limitations - the magic string must not be encoded
1625with character escapes, and the constructor arguments must be non-empty. 1676with character escapes, and the constructor arguments must be non-empty.
1677
1678
1679=head1 RFC7159
1680
1681Since this module was written, Google has written a new JSON RFC, RFC 7159
1682(and RFC7158). Unfortunately, this RFC breaks compatibility with both the
1683original JSON specification on www.json.org and RFC4627.
1684
1685As far as I can see, you can get partial compatibility when parsing by
1686using C<< ->allow_nonref >>. However, consider thew security implications
1687of doing so.
1688
1689I haven't decided yet when to break compatibility with RFC4627 by default
1690(and potentially leave applications insecure) and change the default to
1691follow RFC7159, but application authors are well advised to call C<<
1692->allow_nonref(0) >> even if this is the current default, if they cannot
1693handle non-reference values, in preparation for the day when the4 default
1694will change.
1695
1626 1696
1627=head1 THREADS 1697=head1 THREADS
1628 1698
1629This module is I<not> guaranteed to be thread safe and there are no 1699This module is I<not> guaranteed to be thread safe and there are no
1630plans to change this until Perl gets thread support (as opposed to the 1700plans to change this until Perl gets thread support (as opposed to the

Diff Legend

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