[ViewVC] Diff of: cvs/JSON-XS/README

Comparing JSON-XS/README (file contents):
Revision 1.39 by root, Tue Oct 29 15:55:49 2013 UTC vs.
Revision 1.40 by root, Fri Feb 26 21:46:45 2016 UTC

…		…
350	white-space and comments are allowed.	350	white-space and comments are allowed.
351		351
352	[	352	[
353	1, # this comment not allowed in JSON	353	1, # this comment not allowed in JSON
354	# neither this one...	354	# neither this one...
		355	]
		356
		357	* literal ASCII TAB characters in strings
		358
		359	Literal ASCII TAB characters are now allowed in strings (and
		360	treated as "\t").
		361
		362	[
		363	"Hello\tWorld",
		364	"Hello<TAB>World", # literal <TAB> would not normally be allowed
355	]	365	]
356		366
357	$json = $json->canonical ([$enable])	367	$json = $json->canonical ([$enable])
358	$enabled = $json->get_canonical	368	$enabled = $json->get_canonical
359	If $enable is true (or missing), then the "encode" method will	369	If $enable is true (or missing), then the "encode" method will
…		…
622		632
623	This is useful if your JSON texts are not delimited by an outer	633	This is useful if your JSON texts are not delimited by an outer
624	protocol and you need to know where the JSON text ends.	634	protocol and you need to know where the JSON text ends.
625		635
626	JSON::XS->new->decode_prefix ("[1] the tail")	636	JSON::XS->new->decode_prefix ("[1] the tail")
627	=> ([], 3)	637	=> ([1], 3)
628		638
629	INCREMENTAL PARSING	639	INCREMENTAL PARSING
630	In some cases, there is the need for incremental parsing of JSON texts.	640	In some cases, there is the need for incremental parsing of JSON texts.
631	While this module always has to keep both JSON text and resulting Perl	641	While this module always has to keep both JSON text and resulting Perl
632	data structure in memory at one time, it does allow you to parse a JSON	642	data structure in memory at one time, it does allow you to parse a JSON
…		…
1429	to see whether you are vulnerable to some common attack vectors (which	1439	to see whether you are vulnerable to some common attack vectors (which
1430	really are browser design bugs, but it is still you who will have to	1440	really are browser design bugs, but it is still you who will have to
1431	deal with it, as major browser developers care only for features, not	1441	deal with it, as major browser developers care only for features, not
1432	about getting security right).	1442	about getting security right).
1433		1443
		1444	"OLD" VS. "NEW" JSON (RFC 4627 VS. RFC 7159)
		1445	TL;DR: Due to security concerns, JSON::XS will not allow scalar data in
		1446	JSON texts by default - you need to create your own JSON::XS object and
		1447	enable "allow_nonref":
		1448
		1449	my $json = JSON::XS->new->allow_nonref;
		1450
		1451	$text = $json->encode ($data);
		1452	$data = $json->decode ($text);
		1453
		1454	The long version: JSON being an important and supposedly stable format,
		1455	the IETF standardised it as RFC 4627 in 2006. Unfortunately, the
		1456	inventor of JSON, Dougles Crockford, unilaterally changed the definition
		1457	of JSON in javascript. Rather than create a fork, the IETF decided to
		1458	standardise the new syntax (apparently, so Iw as told, without finding
		1459	it very amusing).
		1460
		1461	The biggest difference between thed original JSON and the new JSON is
		1462	that the new JSON supports scalars (anything other than arrays and
		1463	objects) at the toplevel of a JSON text. While this is strictly
		1464	backwards compatible to older versions, it breaks a number of protocols
		1465	that relied on sending JSON back-to-back, and is a minor security
		1466	concern.
		1467
		1468	For example, imagine you have two banks communicating, and on one side,
		1469	trhe JSON coder gets upgraded. Two messages, such as 10 and 1000 might
		1470	then be confused to mean 101000, something that couldn't happen in the
		1471	original JSON, because niether of these messages would be valid JSON.
		1472
		1473	If one side accepts these messages, then an upgrade in the coder on
		1474	either side could result in this becoming exploitable.
		1475
		1476	This module has always allowed these messages as an optional extension,
		1477	by default disabled. The security concerns are the reason why the
		1478	default is still disabled, but future versions might/will likely upgrade
		1479	to the newer RFC as default format, so you are advised to check your
		1480	implementation and/or override the default with "->allow_nonref (0)" to
		1481	ensure that future versions are safe.
		1482
1434	INTEROPERABILITY WITH OTHER MODULES	1483	INTEROPERABILITY WITH OTHER MODULES
1435	"JSON::XS" uses the Types::Serialiser module to provide boolean	1484	"JSON::XS" uses the Types::Serialiser module to provide boolean
1436	constants. That means that the JSON true and false values will be	1485	constants. That means that the JSON true and false values will be
1437	comaptible to true and false values of iother modules that do the same,	1486	comaptible to true and false values of iother modules that do the same,
1438	such as JSON::PP and CBOR::XS.	1487	such as JSON::PP and CBOR::XS.
1439		1488
		1489	INTEROPERABILITY WITH OTHER JSON DECODERS
		1490	As long as you only serialise data that can be directly expressed in
		1491	JSON, "JSON::XS" is incapable of generating invalid JSON output (modulo
		1492	bugs, but "JSON::XS" has found more bugs in the official JSON testsuite
		1493	(1) than the official JSON testsuite has found in "JSON::XS" (0)).
		1494
		1495	When you have trouble decoding JSON generated by this module using other
		1496	decoders, then it is very likely that you have an encoding mismatch or
		1497	the other decoder is broken.
		1498
		1499	When decoding, "JSON::XS" is strict by default and will likely catch all
		1500	errors. There are currently two settings that change this: "relaxed"
		1501	makes "JSON::XS" accept (but not generate) some non-standard extensions,
		1502	and "allow_tags" will allow you to encode and decode Perl objects, at
		1503	the cost of not outputting valid JSON anymore.
		1504
		1505	TAGGED VALUE SYNTAX AND STANDARD JSON EN/DECODERS
		1506	When you use "allow_tags" to use the extended (and also nonstandard and
		1507	invalid) JSON syntax for serialised objects, and you still want to
		1508	decode the generated When you want to serialise objects, you can run a
		1509	regex to replace the tagged syntax by standard JSON arrays (it only
		1510	works for "normal" packagesnames without comma, newlines or single
		1511	colons). First, the readable Perl version:
		1512
		1513	# if your FREEZE methods return no values, you need this replace first:
		1514	$json =~ s/$ \s* (" (?: [^\\":,]+\|\\.\|::)* ") \s* $ \s* \[\s*\]/[$1]/gx;
		1515
		1516	# this works for non-empty constructor arg lists:
		1517	$json =~ s/$ \s* (" (?: [^\\":,]+\|\\.\|::)* ") \s* $ \s* \[/[$1,/gx;
		1518
		1519	And here is a less readable version that is easy to adapt to other
		1520	languages:
		1521
		1522	$json =~ s/$\s("([^\\":,]+\|\\.\|::)")\s$\s\[/[$1,/g;
		1523
		1524	Here is an ECMAScript version (same regex):
		1525
		1526	json = json.replace (/$\s("([^\\":,]+\|\\.\|::)")\s$\s\[/g, "[$1,");
		1527
		1528	Since this syntax converts to standard JSON arrays, it might be hard to
		1529	distinguish serialised objects from normal arrays. You can prepend a
		1530	"magic number" as first array element to reduce chances of a collision:
		1531
		1532	$json =~ s/$\s("([^\\":,]+\|\\.\|::)")\s$\s\[/["XU1peReLzT4ggEllLanBYq4G9VzliwKF",$1,/g;
		1533
		1534	And after decoding the JSON text, you could walk the data structure
		1535	looking for arrays with a first element of
		1536	"XU1peReLzT4ggEllLanBYq4G9VzliwKF".
		1537
		1538	The same approach can be used to create the tagged format with another
		1539	encoder. First, you create an array with the magic string as first
		1540	member, the classname as second, and constructor arguments last, encode
		1541	it as part of your JSON structure, and then:
		1542
		1543	$json =~ s/\[\s"XU1peReLzT4ggEllLanBYq4G9VzliwKF"\s,\s("([^\\":,]+\|\\.\|::)")\s*,/($1)[/g;
		1544
		1545	Again, this has some limitations - the magic string must not be encoded
		1546	with character escapes, and the constructor arguments must be non-empty.
		1547
		1548	RFC7159
		1549	Since this module was written, Google has written a new JSON RFC, RFC
		1550	7159 (and RFC7158). Unfortunately, this RFC breaks compatibility with
		1551	both the original JSON specification on www.json.org and RFC4627.
		1552
		1553	As far as I can see, you can get partial compatibility when parsing by
		1554	using "->allow_nonref". However, consider thew security implications of
		1555	doing so.
		1556
		1557	I haven't decided yet when to break compatibility with RFC4627 by
		1558	default (and potentially leave applications insecure) and change the
		1559	default to follow RFC7159, but application authors are well advised to
		1560	call "->allow_nonref(0)" even if this is the current default, if they
		1561	cannot handle non-reference values, in preparation for the day when the4
		1562	default will change.
		1563
1440	THREADS	1564	THREADS
1441	This module is not guaranteed to be thread safe and there are no plans	1565	This module is not guaranteed to be thread safe and there are no plans
1442	to change this until Perl gets thread support (as opposed to the	1566	to change this until Perl gets thread support (as opposed to the
1443	horribly slow so-called "threads" which are simply slow and bloated	1567	horribly slow so-called "threads" which are simply slow and bloated
1444	process simulations - use fork, it's much faster, cheaper, better).	1568	process simulations - use fork, it's much faster, cheaper, better).

Diff Legend

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

Comparing JSON-XS/README (file contents): Revision 1.39 by root, Tue Oct 29 15:55:49 2013 UTC vs. Revision 1.40 by root, Fri Feb 26 21:46:45 2016 UTC

Diff Legend

Comparing JSON-XS/README (file contents):
Revision 1.39 by root, Tue Oct 29 15:55:49 2013 UTC vs.
Revision 1.40 by root, Fri Feb 26 21:46:45 2016 UTC