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

Comparing CBOR-XS/README (file contents):
Revision 1.4 by root, Sat Oct 26 23:02:55 2013 UTC vs.
Revision 1.19 by root, Sun Nov 29 21:35:51 2020 UTC

…		…
8	$perl_value = decode_cbor $binary_cbor_data;	8	$perl_value = decode_cbor $binary_cbor_data;
9		9
10	# OO-interface	10	# OO-interface
11		11
12	$coder = CBOR::XS->new;	12	$coder = CBOR::XS->new;
13	#TODO	13	$binary_cbor_data = $coder->encode ($perl_value);
		14	$perl_value = $coder->decode ($binary_cbor_data);
		15
		16	# prefix decoding
		17
		18	my $many_cbor_strings = ...;
		19	while (length $many_cbor_strings) {
		20	my ($data, $length) = $cbor->decode_prefix ($many_cbor_strings);
		21	# data was decoded
		22	substr $many_cbor_strings, 0, $length, ""; # remove decoded cbor string
		23	}
14		24
15	DESCRIPTION	25	DESCRIPTION
16	WARNING! THIS IS A PRE-ALPHA RELEASE! IT WILL CRASH, CORRUPT YOUR DATA
17	AND EAT YOUR CHILDREN! (Actually, apart from being untested and a bit
18	feature-limited, it might already be useful).
19
20	This module converts Perl data structures to the Concise Binary Object	26	This module converts Perl data structures to the Concise Binary Object
21	Representation (CBOR) and vice versa. CBOR is a fast binary	27	Representation (CBOR) and vice versa. CBOR is a fast binary
22	serialisation format that aims to use a superset of the JSON data model,	28	serialisation format that aims to use an (almost) superset of the JSON
23	i.e. when you can represent something in JSON, you should be able to	29	data model, i.e. when you can represent something useful in JSON, you
24	represent it in CBOR.	30	should be able to represent it in CBOR.
25		31
26	This makes it a faster and more compact binary alternative to JSON.	32	In short, CBOR is a faster and quite compact binary alternative to JSON,
		33	with the added ability of supporting serialisation of Perl objects.
		34	(JSON often compresses better than CBOR though, so if you plan to
		35	compress the data later and speed is less important you might want to
		36	compare both formats first).
27		37
28	The primary goal of this module is to be correct and the secondary	38	The primary goal of this module is to be correct and the secondary
29	goal is to be fast. To reach the latter goal it was written in C.	39	goal is to be fast. To reach the latter goal it was written in C.
		40
		41	To give you a general idea about speed, with texts in the megabyte
		42	range, "CBOR::XS" usually encodes roughly twice as fast as Storable or
		43	JSON::XS and decodes about 15%-30% faster than those. The shorter the
		44	data, the worse Storable performs in comparison.
		45
		46	Regarding compactness, "CBOR::XS"-encoded data structures are usually
		47	about 20% smaller than the same data encoded as (compact) JSON or
		48	Storable.
		49
		50	In addition to the core CBOR data format, this module implements a
		51	number of extensions, to support cyclic and shared data structures (see
		52	"allow_sharing" and "allow_cycles"), string deduplication (see
		53	"pack_strings") and scalar references (always enabled).
30		54
31	See MAPPING, below, on how CBOR::XS maps perl values to CBOR values and	55	See MAPPING, below, on how CBOR::XS maps perl values to CBOR values and
32	vice versa.	56	vice versa.
33		57
34	FUNCTIONAL INTERFACE	58	FUNCTIONAL INTERFACE
…		…
53	disabled.	77	disabled.
54		78
55	The mutators for flags all return the CBOR object again and thus	79	The mutators for flags all return the CBOR object again and thus
56	calls can be chained:	80	calls can be chained:
57		81
58	#TODO my $cbor = CBOR::XS->new->encode ({a => [1,2]});	82	my $cbor = CBOR::XS->new->encode ({a => [1,2]});
		83
		84	$cbor = new_safe CBOR::XS
		85	Create a new, safe/secure CBOR::XS object. This is similar to "new",
		86	but configures the coder object to be safe to use with untrusted
		87	data. Currently, this is equivalent to:
		88
		89	my $cbor = CBOR::XS
		90	->new
		91	->forbid_objects
		92	->filter (\&CBOR::XS::safe_filter)
		93	->max_size (1e8);
		94
		95	But is more future proof (it is better to crash because of a change
		96	than to be exploited in other ways).
59		97
60	$cbor = $cbor->max_depth ([$maximum_nesting_depth])	98	$cbor = $cbor->max_depth ([$maximum_nesting_depth])
61	$max_depth = $cbor->get_max_depth	99	$max_depth = $cbor->get_max_depth
62	Sets the maximum nesting level (default 512) accepted while encoding	100	Sets the maximum nesting level (default 512) accepted while encoding
63	or decoding. If a higher nesting level is detected in CBOR data or a	101	or decoding. If a higher nesting level is detected in CBOR data or a
…		…
77		115
78	Note that nesting is implemented by recursion in C. The default	116	Note that nesting is implemented by recursion in C. The default
79	value has been chosen to be as large as typical operating systems	117	value has been chosen to be as large as typical operating systems
80	allow without crashing.	118	allow without crashing.
81		119
82	See SECURITY CONSIDERATIONS, below, for more info on why this is	120	See "SECURITY CONSIDERATIONS", below, for more info on why this is
83	useful.	121	useful.
84		122
85	$cbor = $cbor->max_size ([$maximum_string_size])	123	$cbor = $cbor->max_size ([$maximum_string_size])
86	$max_size = $cbor->get_max_size	124	$max_size = $cbor->get_max_size
87	Set the maximum length a CBOR string may have (in bytes) where	125	Set the maximum length a CBOR string may have (in bytes) where
…		…
91	exception. This setting has no effect on "encode" (yet).	129	exception. This setting has no effect on "encode" (yet).
92		130
93	If no argument is given, the limit check will be deactivated (same	131	If no argument is given, the limit check will be deactivated (same
94	as when 0 is specified).	132	as when 0 is specified).
95		133
96	See SECURITY CONSIDERATIONS, below, for more info on why this is	134	See "SECURITY CONSIDERATIONS", below, for more info on why this is
97	useful.	135	useful.
		136
		137	$cbor = $cbor->allow_unknown ([$enable])
		138	$enabled = $cbor->get_allow_unknown
		139	If $enable is true (or missing), then "encode" will not throw an
		140	exception when it encounters values it cannot represent in CBOR (for
		141	example, filehandles) but instead will encode a CBOR "error" value.
		142
		143	If $enable is false (the default), then "encode" will throw an
		144	exception when it encounters anything it cannot encode as CBOR.
		145
		146	This option does not affect "decode" in any way, and it is
		147	recommended to leave it off unless you know your communications
		148	partner.
		149
		150	$cbor = $cbor->allow_sharing ([$enable])
		151	$enabled = $cbor->get_allow_sharing
		152	If $enable is true (or missing), then "encode" will not
		153	double-encode values that have been referenced before (e.g. when the
		154	same object, such as an array, is referenced multiple times), but
		155	instead will emit a reference to the earlier value.
		156
		157	This means that such values will only be encoded once, and will not
		158	result in a deep cloning of the value on decode, in decoders
		159	supporting the value sharing extension. This also makes it possible
		160	to encode cyclic data structures (which need "allow_cycles" to be
		161	enabled to be decoded by this module).
		162
		163	It is recommended to leave it off unless you know your communication
		164	partner supports the value sharing extensions to CBOR
		165	(<http://cbor.schmorp.de/value-sharing>), as without decoder
		166	support, the resulting data structure might be unusable.
		167
		168	Detecting shared values incurs a runtime overhead when values are
		169	encoded that have a reference counter large than one, and might
		170	unnecessarily increase the encoded size, as potentially shared
		171	values are encoded as shareable whether or not they are actually
		172	shared.
		173
		174	At the moment, only targets of references can be shared (e.g.
		175	scalars, arrays or hashes pointed to by a reference). Weirder
		176	constructs, such as an array with multiple "copies" of the same
		177	string, which are hard but not impossible to create in Perl, are not
		178	supported (this is the same as with Storable).
		179
		180	If $enable is false (the default), then "encode" will encode shared
		181	data structures repeatedly, unsharing them in the process. Cyclic
		182	data structures cannot be encoded in this mode.
		183
		184	This option does not affect "decode" in any way - shared values and
		185	references will always be decoded properly if present.
		186
		187	$cbor = $cbor->allow_cycles ([$enable])
		188	$enabled = $cbor->get_allow_cycles
		189	If $enable is true (or missing), then "decode" will happily decode
		190	self-referential (cyclic) data structures. By default these will not
		191	be decoded, as they need manual cleanup to avoid memory leaks, so
		192	code that isn't prepared for this will not leak memory.
		193
		194	If $enable is false (the default), then "decode" will throw an error
		195	when it encounters a self-referential/cyclic data structure.
		196
		197	FUTURE DIRECTION: the motivation behind this option is to avoid
		198	real cycles - future versions of this module might chose to decode
		199	cyclic data structures using weak references when this option is
		200	off, instead of throwing an error.
		201
		202	This option does not affect "encode" in any way - shared values and
		203	references will always be encoded properly if present.
		204
		205	$cbor = $cbor->forbid_objects ([$enable])
		206	$enabled = $cbor->get_forbid_objects
		207	Disables the use of the object serialiser protocol.
		208
		209	If $enable is true (or missing), then "encode" will will throw an
		210	exception when it encounters perl objects that would be encoded
		211	using the perl-object tag (26). When "decode" encounters such tags,
		212	it will fall back to the general filter/tagged logic as if this were
		213	an unknown tag (by default resulting in a "CBOR::XC::Tagged"
		214	object).
		215
		216	If $enable is false (the default), then "encode" will use the
		217	Types::Serialiser object serialisation protocol to serialise objects
		218	into perl-object tags, and "decode" will do the same to decode such
		219	tags.
		220
		221	See "SECURITY CONSIDERATIONS", below, for more info on why
		222	forbidding this protocol can be useful.
		223
		224	$cbor = $cbor->pack_strings ([$enable])
		225	$enabled = $cbor->get_pack_strings
		226	If $enable is true (or missing), then "encode" will try not to
		227	encode the same string twice, but will instead encode a reference to
		228	the string instead. Depending on your data format, this can save a
		229	lot of space, but also results in a very large runtime overhead
		230	(expect encoding times to be 2-4 times as high as without).
		231
		232	It is recommended to leave it off unless you know your
		233	communications partner supports the stringref extension to CBOR
		234	(<http://cbor.schmorp.de/stringref>), as without decoder support,
		235	the resulting data structure might not be usable.
		236
		237	If $enable is false (the default), then "encode" will encode strings
		238	the standard CBOR way.
		239
		240	This option does not affect "decode" in any way - string references
		241	will always be decoded properly if present.
		242
		243	$cbor = $cbor->text_keys ([$enable])
		244	$enabled = $cbor->get_text_keys
		245	If $enabled is true (or missing), then "encode" will encode all perl
		246	hash keys as CBOR text strings/UTF-8 string, upgrading them as
		247	needed.
		248
		249	If $enable is false (the default), then "encode" will encode hash
		250	keys normally - upgraded perl strings (strings internally encoded as
		251	UTF-8) as CBOR text strings, and downgraded perl strings as CBOR
		252	byte strings.
		253
		254	This option does not affect "decode" in any way.
		255
		256	This option is useful for interoperability with CBOR decoders that
		257	don't treat byte strings as a form of text. It is especially useful
		258	as Perl gives very little control over hash keys.
		259
		260	Enabling this option can be slow, as all downgraded hash keys that
		261	are encoded need to be scanned and converted to UTF-8.
		262
		263	$cbor = $cbor->text_strings ([$enable])
		264	$enabled = $cbor->get_text_strings
		265	This option works similar to "text_keys", above, but works on all
		266	strings (including hash keys), so "text_keys" has no further effect
		267	after enabling "text_strings".
		268
		269	If $enabled is true (or missing), then "encode" will encode all perl
		270	strings as CBOR text strings/UTF-8 strings, upgrading them as
		271	needed.
		272
		273	If $enable is false (the default), then "encode" will encode strings
		274	normally (but see "text_keys") - upgraded perl strings (strings
		275	internally encoded as UTF-8) as CBOR text strings, and downgraded
		276	perl strings as CBOR byte strings.
		277
		278	This option does not affect "decode" in any way.
		279
		280	This option has similar advantages and disadvantages as "text_keys".
		281	In addition, this option effectively removes the ability to
		282	automatically encode byte strings, which might break some "FREEZE"
		283	and "TO_CBOR" methods that rely on this.
		284
		285	A workaround is to use explicit type casts, which are unaffected by
		286	this option.
		287
		288	$cbor = $cbor->validate_utf8 ([$enable])
		289	$enabled = $cbor->get_validate_utf8
		290	If $enable is true (or missing), then "decode" will validate that
		291	elements (text strings) containing UTF-8 data in fact contain valid
		292	UTF-8 data (instead of blindly accepting it). This validation
		293	obviously takes extra time during decoding.
		294
		295	The concept of "valid UTF-8" used is perl's concept, which is a
		296	superset of the official UTF-8.
		297
		298	If $enable is false (the default), then "decode" will blindly accept
		299	UTF-8 data, marking them as valid UTF-8 in the resulting data
		300	structure regardless of whether that's true or not.
		301
		302	Perl isn't too happy about corrupted UTF-8 in strings, but should
		303	generally not crash or do similarly evil things. Extensions might be
		304	not so forgiving, so it's recommended to turn on this setting if you
		305	receive untrusted CBOR.
		306
		307	This option does not affect "encode" in any way - strings that are
		308	supposedly valid UTF-8 will simply be dumped into the resulting CBOR
		309	string without checking whether that is, in fact, true or not.
		310
		311	$cbor = $cbor->filter ([$cb->($tag, $value)])
		312	$cb_or_undef = $cbor->get_filter
		313	Sets or replaces the tagged value decoding filter (when $cb is
		314	specified) or clears the filter (if no argument or "undef" is
		315	provided).
		316
		317	The filter callback is called only during decoding, when a
		318	non-enforced tagged value has been decoded (see "TAG HANDLING AND
		319	EXTENSIONS" for a list of enforced tags). For specific tags, it's
		320	often better to provide a default converter using the
		321	%CBOR::XS::FILTER hash (see below).
		322
		323	The first argument is the numerical tag, the second is the (decoded)
		324	value that has been tagged.
		325
		326	The filter function should return either exactly one value, which
		327	will replace the tagged value in the decoded data structure, or no
		328	values, which will result in default handling, which currently means
		329	the decoder creates a "CBOR::XS::Tagged" object to hold the tag and
		330	the value.
		331
		332	When the filter is cleared (the default state), the default filter
		333	function, "CBOR::XS::default_filter", is used. This function simply
		334	looks up the tag in the %CBOR::XS::FILTER hash. If an entry exists
		335	it must be a code reference that is called with tag and value, and
		336	is responsible for decoding the value. If no entry exists, it
		337	returns no values. "CBOR::XS" provides a number of default filter
		338	functions already, the the %CBOR::XS::FILTER hash can be freely
		339	extended with more.
		340
		341	"CBOR::XS" additionally provides an alternative filter function that
		342	is supposed to be safe to use with untrusted data (which the default
		343	filter might not), called "CBOR::XS::safe_filter", which works the
		344	same as the "default_filter" but uses the %CBOR::XS::SAFE_FILTER
		345	variable instead. It is prepopulated with the tag decoding functions
		346	that are deemed safe (basically the same as %CBOR::XS::FILTER
		347	without all the bignum tags), and can be extended by user code as
		348	wlel, although, obviously, one should be very careful about adding
		349	decoding functions here, since the expectation is that they are safe
		350	to use on untrusted data, after all.
		351
		352	Example: decode all tags not handled internally into
		353	"CBOR::XS::Tagged" objects, with no other special handling (useful
		354	when working with potentially "unsafe" CBOR data).
		355
		356	CBOR::XS->new->filter (sub { })->decode ($cbor_data);
		357
		358	Example: provide a global filter for tag 1347375694, converting the
		359	value into some string form.
		360
		361	$CBOR::XS::FILTER{1347375694} = sub {
		362	my ($tag, $value);
		363
		364	"tag 1347375694 value $value"
		365	};
		366
		367	Example: provide your own filter function that looks up tags in your
		368	own hash:
		369
		370	my %my_filter = (
		371	998347484 => sub {
		372	my ($tag, $value);
		373
		374	"tag 998347484 value $value"
		375	};
		376	);
		377
		378	my $coder = CBOR::XS->new->filter (sub {
		379	&{ $my_filter{$_[0]} or return }
		380	});
		381
		382	Example: use the safe filter function (see "SECURITY CONSIDERATIONS"
		383	for more considerations on security).
		384
		385	CBOR::XS->new->filter (\&CBOR::XS::safe_filter)->decode ($cbor_data);
98		386
99	$cbor_data = $cbor->encode ($perl_scalar)	387	$cbor_data = $cbor->encode ($perl_scalar)
100	Converts the given Perl data structure (a scalar value) to its CBOR	388	Converts the given Perl data structure (a scalar value) to its CBOR
101	representation.	389	representation.
102		390
…		…
110	will silently stop parsing there and return the number of characters	398	will silently stop parsing there and return the number of characters
111	consumed so far.	399	consumed so far.
112		400
113	This is useful if your CBOR texts are not delimited by an outer	401	This is useful if your CBOR texts are not delimited by an outer
114	protocol and you need to know where the first CBOR string ends amd	402	protocol and you need to know where the first CBOR string ends amd
115	the next one starts.	403	the next one starts - CBOR strings are self-delimited, so it is
		404	possible to concatenate CBOR strings without any delimiters or size
		405	fields and recover their data.
116		406
117	CBOR::XS->new->decode_prefix ("......")	407	CBOR::XS->new->decode_prefix ("......")
118	=> ("...", 3)	408	=> ("...", 3)
		409
		410	INCREMENTAL PARSING
		411	In some cases, there is the need for incremental parsing of JSON texts.
		412	While this module always has to keep both CBOR text and resulting Perl
		413	data structure in memory at one time, it does allow you to parse a CBOR
		414	stream incrementally, using a similar to using "decode_prefix" to see if
		415	a full CBOR object is available, but is much more efficient.
		416
		417	It basically works by parsing as much of a CBOR string as possible - if
		418	the CBOR data is not complete yet, the pasrer will remember where it
		419	was, to be able to restart when more data has been accumulated. Once
		420	enough data is available to either decode a complete CBOR value or raise
		421	an error, a real decode will be attempted.
		422
		423	A typical use case would be a network protocol that consists of sending
		424	and receiving CBOR-encoded messages. The solution that works with CBOR
		425	and about anything else is by prepending a length to every CBOR value,
		426	so the receiver knows how many octets to read. More compact (and
		427	slightly slower) would be to just send CBOR values back-to-back, as
		428	"CBOR::XS" knows where a CBOR value ends, and doesn't need an explicit
		429	length.
		430
		431	The following methods help with this:
		432
		433	@decoded = $cbor->incr_parse ($buffer)
		434	This method attempts to decode exactly one CBOR value from the
		435	beginning of the given $buffer. The value is removed from the
		436	$buffer on success. When $buffer doesn't contain a complete value
		437	yet, it returns nothing. Finally, when the $buffer doesn't start
		438	with something that could ever be a valid CBOR value, it raises an
		439	exception, just as "decode" would. In the latter case the decoder
		440	state is undefined and must be reset before being able to parse
		441	further.
		442
		443	This method modifies the $buffer in place. When no CBOR value can be
		444	decoded, the decoder stores the current string offset. On the next
		445	call, continues decoding at the place where it stopped before. For
		446	this to make sense, the $buffer must begin with the same octets as
		447	on previous unsuccessful calls.
		448
		449	You can call this method in scalar context, in which case it either
		450	returns a decoded value or "undef". This makes it impossible to
		451	distinguish between CBOR null values (which decode to "undef") and
		452	an unsuccessful decode, which is often acceptable.
		453
		454	@decoded = $cbor->incr_parse_multiple ($buffer)
		455	Same as "incr_parse", but attempts to decode as many CBOR values as
		456	possible in one go, instead of at most one. Calls to "incr_parse"
		457	and "incr_parse_multiple" can be interleaved.
		458
		459	$cbor->incr_reset
		460	Resets the incremental decoder. This throws away any saved state, so
		461	that subsequent calls to "incr_parse" or "incr_parse_multiple" start
		462	to parse a new CBOR value from the beginning of the $buffer again.
		463
		464	This method can be called at any time, but it must be called if
		465	you want to change your $buffer or there was a decoding error and
		466	you want to reuse the $cbor object for future incremental parsings.
119		467
120	MAPPING	468	MAPPING
121	This section describes how CBOR::XS maps Perl values to CBOR values and	469	This section describes how CBOR::XS maps Perl values to CBOR values and
122	vice versa. These mappings are designed to "do the right thing" in most	470	vice versa. These mappings are designed to "do the right thing" in most
123	circumstances automatically, preserving round-tripping characteristics	471	circumstances automatically, preserving round-tripping characteristics
…		…
131	integers	479	integers
132	CBOR integers become (numeric) perl scalars. On perls without 64 bit	480	CBOR integers become (numeric) perl scalars. On perls without 64 bit
133	support, 64 bit integers will be truncated or otherwise corrupted.	481	support, 64 bit integers will be truncated or otherwise corrupted.
134		482
135	byte strings	483	byte strings
136	Byte strings will become octet strings in Perl (the byte values	484	Byte strings will become octet strings in Perl (the Byte values
137	0..255 will simply become characters of the same value in Perl).	485	0..255 will simply become characters of the same value in Perl).
138		486
139	UTF-8 strings	487	UTF-8 strings
140	UTF-8 strings in CBOR will be decoded, i.e. the UTF-8 octets will be	488	UTF-8 strings in CBOR will be decoded, i.e. the UTF-8 octets will be
141	decoded into proper Unicode code points. At the moment, the validity	489	decoded into proper Unicode code points. At the moment, the validity
…		…
145	arrays, maps	493	arrays, maps
146	CBOR arrays and CBOR maps will be converted into references to a	494	CBOR arrays and CBOR maps will be converted into references to a
147	Perl array or hash, respectively. The keys of the map will be	495	Perl array or hash, respectively. The keys of the map will be
148	stringified during this process.	496	stringified during this process.
149		497
150	true, false	498	null
151	These CBOR values become "CBOR::XS::true" and "CBOR::XS::false",	499	CBOR null becomes "undef" in Perl.
		500
		501	true, false, undefined
		502	These CBOR values become "Types:Serialiser::true",
		503	"Types:Serialiser::false" and "Types::Serialiser::error",
152	respectively. They are overloaded to act almost exactly like the	504	respectively. They are overloaded to act almost exactly like the
153	numbers 1 and 0. You can check whether a scalar is a CBOR boolean by	505	numbers 1 and 0 (for true and false) or to throw an exception on
154	using the "CBOR::XS::is_bool" function.	506	access (for error). See the Types::Serialiser manpage for details.
155		507
156	null, undefined	508	tagged values
157	CBOR null and undefined values becomes "undef" in Perl (in the
158	future, Undefined may raise an exception or something else).
159
160	tags
161	Tagged items consists of a numeric tag and another CBOR value. The	509	Tagged items consists of a numeric tag and another CBOR value.
162	tag 55799 is ignored (this tag implements the magic header).
163		510
164	All other tags are currently converted into a CBOR::XS::Tagged	511	See "TAG HANDLING AND EXTENSIONS" and the description of "->filter"
165	object, which is simply a blessed array reference consistsing of the	512	for details on which tags are handled how.
166	numeric tag value followed by the (decoded) BOR value.
167		513
168	anything else	514	anything else
169	Anything else (e.g. unsupported simple values) will raise a decoding	515	Anything else (e.g. unsupported simple values) will raise a decoding
170	error.	516	error.
171		517
172	PERL -> CBOR	518	PERL -> CBOR
173	The mapping from Perl to CBOR is slightly more difficult, as Perl is a	519	The mapping from Perl to CBOR is slightly more difficult, as Perl is a
174	truly typeless language, so we can only guess which CBOR type is meant	520	typeless language. That means this module can only guess which CBOR type
175	by a Perl value.	521	is meant by a perl value.
176		522
177	hash references	523	hash references
178	Perl hash references become CBOR maps. As there is no inherent	524	Perl hash references become CBOR maps. As there is no inherent
179	ordering in hash keys (or CBOR maps), they will usually be encoded	525	ordering in hash keys (or CBOR maps), they will usually be encoded
180	in a pseudo-random order.	526	in a pseudo-random order. This order can be different each time a
		527	hash is encoded.
181		528
182	Currently, tied hashes will use the indefinite-length format, while	529	Currently, tied hashes will use the indefinite-length format, while
183	normal hashes will use the fixed-length format.	530	normal hashes will use the fixed-length format.
184		531
185	array references	532	array references
186	Perl array references become fixed-length CBOR arrays.	533	Perl array references become fixed-length CBOR arrays.
187		534
188	other references	535	other references
189	Other unblessed references are generally not allowed and will cause	536	Other unblessed references will be represented using the indirection
190	an exception to be thrown, except for references to the integers 0	537	tag extension (tag value 22098,
191	and 1, which get turned into false and true in CBOR.	538	<http://cbor.schmorp.de/indirection>). CBOR decoders are guaranteed
		539	to be able to decode these values somehow, by either "doing the
		540	right thing", decoding into a generic tagged object, simply ignoring
		541	the tag, or something else.
192		542
193	CBOR::XS::Tagged objects	543	CBOR::XS::Tagged objects
194	Objects of this type must be arrays consisting of a single "[tag,	544	Objects of this type must be arrays consisting of a single "[tag,
195	value]" pair. The (numerical) tag will be encoded as a CBOR tag, the	545	value]" pair. The (numerical) tag will be encoded as a CBOR tag, the
196	value will be encoded as appropriate for the value.	546	value will be encoded as appropriate for the value. You must use
		547	"CBOR::XS::tag" to create such objects.
197		548
198	CBOR::XS::true, CBOR::XS::false	549	Types::Serialiser::true, Types::Serialiser::false,
		550	Types::Serialiser::error
199	These special values become CBOR true and CBOR false values,	551	These special values become CBOR true, CBOR false and CBOR undefined
200	respectively. You can also use "\1" and "\0" directly if you want.	552	values, respectively. You can also use "\1", "\0" and "\undef"
		553	directly if you want.
201		554
202	blessed objects	555	other blessed objects
203	Other blessed objects currently need to have a "TO_CBOR" method. It	556	Other blessed objects are serialised via "TO_CBOR" or "FREEZE". See
204	will be called on every object that is being serialised, and must	557	"TAG HANDLING AND EXTENSIONS" for specific classes handled by this
205	return something that can be encoded in CBOR.	558	module, and "OBJECT SERIALISATION" for generic object serialisation.
206		559
207	simple scalars	560	simple scalars
208	TODO Simple Perl scalars (any scalar that is not a reference) are	561	Simple Perl scalars (any scalar that is not a reference) are the
209	the most difficult objects to encode: CBOR::XS will encode undefined	562	most difficult objects to encode: CBOR::XS will encode undefined
210	scalars as CBOR null values, scalars that have last been used in a	563	scalars as CBOR null values, scalars that have last been used in a
211	string context before encoding as CBOR strings, and anything else as	564	string context before encoding as CBOR strings, and anything else as
212	number value:	565	number value:
213		566
214	# dump as number	567	# dump as number
215	encode_cbor [2] # yields [2]	568	encode_cbor [2] # yields [2]
216	encode_cbor [-3.0e17] # yields [-3e+17]	569	encode_cbor [-3.0e17] # yields [-3e+17]
217	my $value = 5; encode_cbor [$value] # yields [5]	570	my $value = 5; encode_cbor [$value] # yields [5]
218		571
219	# used as string, so dump as string	572	# used as string, so dump as string (either byte or text)
220	print $value;	573	print $value;
221	encode_cbor [$value] # yields ["5"]	574	encode_cbor [$value] # yields ["5"]
222		575
223	# undef becomes null	576	# undef becomes null
224	encode_cbor [undef] # yields [null]	577	encode_cbor [undef] # yields [null]
…		…
227		580
228	my $x = 3.1; # some variable containing a number	581	my $x = 3.1; # some variable containing a number
229	"$x"; # stringified	582	"$x"; # stringified
230	$x .= ""; # another, more awkward way to stringify	583	$x .= ""; # another, more awkward way to stringify
231	print $x; # perl does it for you, too, quite often	584	print $x; # perl does it for you, too, quite often
		585
		586	You can force whether a string is encoded as byte or text string by
		587	using "utf8::upgrade" and "utf8::downgrade" (if "text_strings" is
		588	disabled).
		589
		590	utf8::upgrade $x; # encode $x as text string
		591	utf8::downgrade $x; # encode $x as byte string
		592
		593	More options are available, see "TYPE CASTS", below, and the
		594	"text_keys" and "text_strings" options.
		595
		596	Perl doesn't define what operations up- and downgrade strings, so if
		597	the difference between byte and text is important, you should up- or
		598	downgrade your string as late as possible before encoding. You can
		599	also force the use of CBOR text strings by using "text_keys" or
		600	"text_strings".
232		601
233	You can force the type to be a CBOR number by numifying it:	602	You can force the type to be a CBOR number by numifying it:
234		603
235	my $x = "3"; # some variable containing a string	604	my $x = "3"; # some variable containing a string
236	$x += 0; # numify it, ensuring it will be dumped as a number	605	$x += 0; # numify it, ensuring it will be dumped as a number
…		…
245	IEEE single format if possible without loss of precision, otherwise	614	IEEE single format if possible without loss of precision, otherwise
246	the IEEE double format will be used. Perls that use formats other	615	the IEEE double format will be used. Perls that use formats other
247	than IEEE double to represent numerical values are supported, but	616	than IEEE double to represent numerical values are supported, but
248	might suffer loss of precision.	617	might suffer loss of precision.
249		618
		619	TYPE CASTS
		620	EXPERIMENTAL: As an experimental extension, "CBOR::XS" allows you to
		621	force specific cbor types to be used when encoding. That allows you to
		622	encode types not normally accessible (e.g. half floats) as well as force
		623	string types even when "text_strings" is in effect.
		624
		625	Type forcing is done by calling a special "cast" function which keeps a
		626	copy of the value and returns a new value that can be handed over to any
		627	CBOR encoder function.
		628
		629	The following casts are currently available (all of which are unary
		630	operators):
		631
		632	CBOR::XS::as_int $value
		633	Forces the value to be encoded as some form of (basic, not bignum)
		634	integer type.
		635
		636	CBOR::XS::as_text $value
		637	Forces the value to be encoded as (UTF-8) text values.
		638
		639	CBOR::XS::as_bytes $value
		640	Forces the value to be encoded as a (binary) string value.
		641
		642	CBOR::XS::as_float16 $value
		643	Forces half-float (IEEE 754 binary16) encoding of the given value.
		644
		645	CBOR::XS::as_float32 $value
		646	Forces single-float (IEEE 754 binary32) encoding of the given value.
		647
		648	CBOR::XS::as_float64 $value
		649	Forces double-float (IEEE 754 binary64) encoding of the given value.
		650
		651	=item, CBOR::XS::as_cbor $cbor_text
		652
		653	Bot a type cast per-se, this type cast forces the argument to eb
		654	encoded as-is. This can be used to embed pre-encoded CBOR data.
		655
		656	Note that no checking on the validity of the $cbor_text is done -
		657	it's the callers responsibility to correctly encode values.
		658
		659	Example: encode a perl string as binary even though "text_strings" is in
		660	effect.
		661
		662	CBOR::XS->new->text_strings->encode ([4, "text", CBOR::XS::bytes "bytevalue"]);
		663
		664	OBJECT SERIALISATION
		665	This module implements both a CBOR-specific and the generic
		666	Types::Serialier object serialisation protocol. The following
		667	subsections explain both methods.
		668
		669	ENCODING
		670	This module knows two way to serialise a Perl object: The CBOR-specific
		671	way, and the generic way.
		672
		673	Whenever the encoder encounters a Perl object that it cannot serialise
		674	directly (most of them), it will first look up the "TO_CBOR" method on
		675	it.
		676
		677	If it has a "TO_CBOR" method, it will call it with the object as only
		678	argument, and expects exactly one return value, which it will then
		679	substitute and encode it in the place of the object.
		680
		681	Otherwise, it will look up the "FREEZE" method. If it exists, it will
		682	call it with the object as first argument, and the constant string
		683	"CBOR" as the second argument, to distinguish it from other serialisers.
		684
		685	The "FREEZE" method can return any number of values (i.e. zero or more).
		686	These will be encoded as CBOR perl object, together with the classname.
		687
		688	These methods MUST NOT change the data structure that is being
		689	serialised. Failure to comply to this can result in memory corruption -
		690	and worse.
		691
		692	If an object supports neither "TO_CBOR" nor "FREEZE", encoding will fail
		693	with an error.
		694
		695	DECODING
		696	Objects encoded via "TO_CBOR" cannot (normally) be automatically
		697	decoded, but objects encoded via "FREEZE" can be decoded using the
		698	following protocol:
		699
		700	When an encoded CBOR perl object is encountered by the decoder, it will
		701	look up the "THAW" method, by using the stored classname, and will fail
		702	if the method cannot be found.
		703
		704	After the lookup it will call the "THAW" method with the stored
		705	classname as first argument, the constant string "CBOR" as second
		706	argument, and all values returned by "FREEZE" as remaining arguments.
		707
		708	EXAMPLES
		709	Here is an example "TO_CBOR" method:
		710
		711	sub My::Object::TO_CBOR {
		712	my ($obj) = @_;
		713
		714	["this is a serialised My::Object object", $obj->{id}]
		715	}
		716
		717	When a "My::Object" is encoded to CBOR, it will instead encode a simple
		718	array with two members: a string, and the "object id". Decoding this
		719	CBOR string will yield a normal perl array reference in place of the
		720	object.
		721
		722	A more useful and practical example would be a serialisation method for
		723	the URI module. CBOR has a custom tag value for URIs, namely 32:
		724
		725	sub URI::TO_CBOR {
		726	my ($self) = @_;
		727	my $uri = "$self"; # stringify uri
		728	utf8::upgrade $uri; # make sure it will be encoded as UTF-8 string
		729	CBOR::XS::tag 32, "$_[0]"
		730	}
		731
		732	This will encode URIs as a UTF-8 string with tag 32, which indicates an
		733	URI.
		734
		735	Decoding such an URI will not (currently) give you an URI object, but
		736	instead a CBOR::XS::Tagged object with tag number 32 and the string -
		737	exactly what was returned by "TO_CBOR".
		738
		739	To serialise an object so it can automatically be deserialised, you need
		740	to use "FREEZE" and "THAW". To take the URI module as example, this
		741	would be a possible implementation:
		742
		743	sub URI::FREEZE {
		744	my ($self, $serialiser) = @_;
		745	"$self" # encode url string
		746	}
		747
		748	sub URI::THAW {
		749	my ($class, $serialiser, $uri) = @_;
		750	$class->new ($uri)
		751	}
		752
		753	Unlike "TO_CBOR", multiple values can be returned by "FREEZE". For
		754	example, a "FREEZE" method that returns "type", "id" and "variant"
		755	values would cause an invocation of "THAW" with 5 arguments:
		756
		757	sub My::Object::FREEZE {
		758	my ($self, $serialiser) = @_;
		759
		760	($self->{type}, $self->{id}, $self->{variant})
		761	}
		762
		763	sub My::Object::THAW {
		764	my ($class, $serialiser, $type, $id, $variant) = @_;
		765
		766	$class-<new (type => $type, id => $id, variant => $variant)
		767	}
		768
250	MAGIC HEADER	769	MAGIC HEADER
251	There is no way to distinguish CBOR from other formats programmatically.	770	There is no way to distinguish CBOR from other formats programmatically.
252	To make it easier to distinguish CBOR from other formats, the CBOR	771	To make it easier to distinguish CBOR from other formats, the CBOR
253	specification has a special "magic string" that can be prepended to any	772	specification has a special "magic string" that can be prepended to any
254	CBOR string without changing it's meaning.	773	CBOR string without changing its meaning.
255		774
256	This string is available as $CBOR::XS::MAGIC. This module does not	775	This string is available as $CBOR::XS::MAGIC. This module does not
257	prepend this string tot he CBOR data it generates, but it will ignroe it	776	prepend this string to the CBOR data it generates, but it will ignore it
258	if present, so users can prepend this string as a "file type" indicator	777	if present, so users can prepend this string as a "file type" indicator
259	as required.	778	as required.
260		779
		780	THE CBOR::XS::Tagged CLASS
		781	CBOR has the concept of tagged values - any CBOR value can be tagged
		782	with a numeric 64 bit number, which are centrally administered.
		783
		784	"CBOR::XS" handles a few tags internally when en- or decoding. You can
		785	also create tags yourself by encoding "CBOR::XS::Tagged" objects, and
		786	the decoder will create "CBOR::XS::Tagged" objects itself when it hits
		787	an unknown tag.
		788
		789	These objects are simply blessed array references - the first member of
		790	the array being the numerical tag, the second being the value.
		791
		792	You can interact with "CBOR::XS::Tagged" objects in the following ways:
		793
		794	$tagged = CBOR::XS::tag $tag, $value
		795	This function(!) creates a new "CBOR::XS::Tagged" object using the
		796	given $tag (0..2**64-1) to tag the given $value (which can be any
		797	Perl value that can be encoded in CBOR, including serialisable Perl
		798	objects and "CBOR::XS::Tagged" objects).
		799
		800	$tagged->[0]
		801	$tagged->[0] = $new_tag
		802	$tag = $tagged->tag
		803	$new_tag = $tagged->tag ($new_tag)
		804	Access/mutate the tag.
		805
		806	$tagged->[1]
		807	$tagged->[1] = $new_value
		808	$value = $tagged->value
		809	$new_value = $tagged->value ($new_value)
		810	Access/mutate the tagged value.
		811
		812	EXAMPLES
		813	Here are some examples of "CBOR::XS::Tagged" uses to tag objects.
		814
		815	You can look up CBOR tag value and emanings in the IANA registry at
		816	<http://www.iana.org/assignments/cbor-tags/cbor-tags.xhtml>.
		817
		818	Prepend a magic header ($CBOR::XS::MAGIC):
		819
		820	my $cbor = encode_cbor CBOR::XS::tag 55799, $value;
		821	# same as:
		822	my $cbor = $CBOR::XS::MAGIC . encode_cbor $value;
		823
		824	Serialise some URIs and a regex in an array:
		825
		826	my $cbor = encode_cbor [
		827	(CBOR::XS::tag 32, "http://www.nethype.de/"),
		828	(CBOR::XS::tag 32, "http://software.schmorp.de/"),
		829	(CBOR::XS::tag 35, "^[Pp][Ee][Rr][lL]\$"),
		830	];
		831
		832	Wrap CBOR data in CBOR:
		833
		834	my $cbor_cbor = encode_cbor
		835	CBOR::XS::tag 24,
		836	encode_cbor [1, 2, 3];
		837
		838	TAG HANDLING AND EXTENSIONS
		839	This section describes how this module handles specific tagged values
		840	and extensions. If a tag is not mentioned here and no additional filters
		841	are provided for it, then the default handling applies (creating a
		842	CBOR::XS::Tagged object on decoding, and only encoding the tag when
		843	explicitly requested).
		844
		845	Tags not handled specifically are currently converted into a
		846	CBOR::XS::Tagged object, which is simply a blessed array reference
		847	consisting of the numeric tag value followed by the (decoded) CBOR
		848	value.
		849
		850	Future versions of this module reserve the right to special case
		851	additional tags (such as base64url).
		852
		853	ENFORCED TAGS
		854	These tags are always handled when decoding, and their handling cannot
		855	be overridden by the user.
		856
		857	26 (perl-object, <http://cbor.schmorp.de/perl-object>)
		858	These tags are automatically created (and decoded) for serialisable
		859	objects using the "FREEZE/THAW" methods (the Types::Serialier object
		860	serialisation protocol). See "OBJECT SERIALISATION" for details.
		861
		862	28, 29 (shareable, sharedref, <http://cbor.schmorp.de/value-sharing>)
		863	These tags are automatically decoded when encountered (and they do
		864	not result in a cyclic data structure, see "allow_cycles"),
		865	resulting in shared values in the decoded object. They are only
		866	encoded, however, when "allow_sharing" is enabled.
		867
		868	Not all shared values can be successfully decoded: values that
		869	reference themselves will currently decode as "undef" (this is not
		870	the same as a reference pointing to itself, which will be
		871	represented as a value that contains an indirect reference to itself
		872	- these will be decoded properly).
		873
		874	Note that considerably more shared value data structures can be
		875	decoded than will be encoded - currently, only values pointed to by
		876	references will be shared, others will not. While non-reference
		877	shared values can be generated in Perl with some effort, they were
		878	considered too unimportant to be supported in the encoder. The
		879	decoder, however, will decode these values as shared values.
		880
		881	256, 25 (stringref-namespace, stringref,
		882	<http://cbor.schmorp.de/stringref>)
		883	These tags are automatically decoded when encountered. They are only
		884	encoded, however, when "pack_strings" is enabled.
		885
		886	22098 (indirection, <http://cbor.schmorp.de/indirection>)
		887	This tag is automatically generated when a reference are encountered
		888	(with the exception of hash and array references). It is converted
		889	to a reference when decoding.
		890
		891	55799 (self-describe CBOR, RFC 7049)
		892	This value is not generated on encoding (unless explicitly requested
		893	by the user), and is simply ignored when decoding.
		894
		895	NON-ENFORCED TAGS
		896	These tags have default filters provided when decoding. Their handling
		897	can be overridden by changing the %CBOR::XS::FILTER entry for the tag,
		898	or by providing a custom "filter" callback when decoding.
		899
		900	When they result in decoding into a specific Perl class, the module
		901	usually provides a corresponding "TO_CBOR" method as well.
		902
		903	When any of these need to load additional modules that are not part of
		904	the perl core distribution (e.g. URI), it is (currently) up to the user
		905	to provide these modules. The decoding usually fails with an exception
		906	if the required module cannot be loaded.
		907
		908	0, 1 (date/time string, seconds since the epoch)
		909	These tags are decoded into Time::Piece objects. The corresponding
		910	"Time::Piece::TO_CBOR" method always encodes into tag 1 values
		911	currently.
		912
		913	The Time::Piece API is generally surprisingly bad, and fractional
		914	seconds are only accidentally kept intact, so watch out. On the plus
		915	side, the module comes with perl since 5.10, which has to count for
		916	something.
		917
		918	2, 3 (positive/negative bignum)
		919	These tags are decoded into Math::BigInt objects. The corresponding
		920	"Math::BigInt::TO_CBOR" method encodes "small" bigints into normal
		921	CBOR integers, and others into positive/negative CBOR bignums.
		922
		923	4, 5, 264, 265 (decimal fraction/bigfloat)
		924	Both decimal fractions and bigfloats are decoded into Math::BigFloat
		925	objects. The corresponding "Math::BigFloat::TO_CBOR" method always
		926	encodes into a decimal fraction (either tag 4 or 264).
		927
		928	NaN and infinities are not encoded properly, as they cannot be
		929	represented in CBOR.
		930
		931	See "BIGNUM SECURITY CONSIDERATIONS" for more info.
		932
		933	30 (rational numbers)
		934	These tags are decoded into Math::BigRat objects. The corresponding
		935	"Math::BigRat::TO_CBOR" method encodes rational numbers with
		936	denominator 1 via their numerator only, i.e., they become normal
		937	integers or "bignums".
		938
		939	See "BIGNUM SECURITY CONSIDERATIONS" for more info.
		940
		941	21, 22, 23 (expected later JSON conversion)
		942	CBOR::XS is not a CBOR-to-JSON converter, and will simply ignore
		943	these tags.
		944
		945	32 (URI)
		946	These objects decode into URI objects. The corresponding
		947	"URI::TO_CBOR" method again results in a CBOR URI value.
		948
261	CBOR and JSON	949	CBOR and JSON
262	CBOR is supposed to implement a superset of the JSON data model, and is,	950	CBOR is supposed to implement a superset of the JSON data model, and is,
263	with some coercion, able to represent all JSON texts (something that	951	with some coercion, able to represent all JSON texts (something that
264	other "binary JSON" formats such as BSON generally do not support).	952	other "binary JSON" formats such as BSON generally do not support).
265		953
266	CBOR implements some extra hints and support for JSON interoperability,	954	CBOR implements some extra hints and support for JSON interoperability,
…		…
270	interoperability is improved in the future, then the goal will be to	958	interoperability is improved in the future, then the goal will be to
271	ensure that decoded JSON data will round-trip encoding and decoding to	959	ensure that decoded JSON data will round-trip encoding and decoding to
272	CBOR intact.	960	CBOR intact.
273		961
274	SECURITY CONSIDERATIONS	962	SECURITY CONSIDERATIONS
275	When you are using CBOR in a protocol, talking to untrusted potentially	963	Tl;dr... if you want to decode or encode CBOR from untrusted sources,
276	hostile creatures requires relatively few measures.	964	you should start with a coder object created via "new_safe" (which
		965	implements the mitigations explained below):
277		966
		967	my $coder = CBOR::XS->new_safe;
		968
		969	my $data = $coder->decode ($cbor_text);
		970	my $cbor = $coder->encode ($data);
		971
		972	Longer version: When you are using CBOR in a protocol, talking to
		973	untrusted potentially hostile creatures requires some thought:
		974
		975	Security of the CBOR decoder itself
278	First of all, your CBOR decoder should be secure, that is, should not	976	First and foremost, your CBOR decoder should be secure, that is,
279	have any buffer overflows. Obviously, this module should ensure that and	977	should not have any buffer overflows or similar bugs that could
		978	potentially be exploited. Obviously, this module should ensure that
280	I am trying hard on making that true, but you never know.	979	and I am trying hard on making that true, but you never know.
281		980
		981	CBOR::XS can invoke almost arbitrary callbacks during decoding
		982	CBOR::XS supports object serialisation - decoding CBOR can cause
		983	calls to any "THAW" method in any package that exists in your
		984	process (that is, CBOR::XS will not try to load modules, but any
		985	existing "THAW" method or function can be called, so they all have
		986	to be secure).
		987
		988	Less obviously, it will also invoke "TO_CBOR" and "FREEZE" methods -
		989	even if all your "THAW" methods are secure, encoding data structures
		990	from untrusted sources can invoke those and trigger bugs in those.
		991
		992	So, if you are not sure about the security of all the modules you
		993	have loaded (you shouldn't), you should disable this part using
		994	"forbid_objects" or using "new_safe".
		995
		996	CBOR can be extended with tags that call library code
		997	CBOR can be extended with tags, and "CBOR::XS" has a registry of
		998	conversion functions for many existing tags that can be extended via
		999	third-party modules (see the "filter" method).
		1000
		1001	If you don't trust these, you should configure the "safe" filter
		1002	function, "CBOR::XS::safe_filter" ("new_safe" does this), which by
		1003	default only includes conversion functions that are considered
		1004	"safe" by the author (but again, they can be extended by third party
		1005	modules).
		1006
		1007	Depending on your level of paranoia, you can use the "safe" filter:
		1008
		1009	$cbor->filter (\&CBOR::XS::safe_filter);
		1010
		1011	... your own filter...
		1012
		1013	$cbor->filter (sub { ... do your stuffs here ... });
		1014
		1015	... or even no filter at all, disabling all tag decoding:
		1016
		1017	$cbor->filter (sub { });
		1018
		1019	This is never a problem for encoding, as the tag mechanism only
		1020	exists in CBOR texts.
		1021
		1022	Resource-starving attacks: object memory usage
282	Second, you need to avoid resource-starving attacks. That means you	1023	You need to avoid resource-starving attacks. That means you should
283	should limit the size of CBOR data you accept, or make sure then when	1024	limit the size of CBOR data you accept, or make sure then when your
284	your resources run out, that's just fine (e.g. by using a separate	1025	resources run out, that's just fine (e.g. by using a separate
285	process that can crash safely). The size of a CBOR string in octets is	1026	process that can crash safely). The size of a CBOR string in octets
286	usually a good indication of the size of the resources required to	1027	is usually a good indication of the size of the resources required
287	decode it into a Perl structure. While CBOR::XS can check the size of	1028	to decode it into a Perl structure. While CBOR::XS can check the
		1029	size of the CBOR text (using "max_size" - done by "new_safe"), it
288	the CBOR text, it might be too late when you already have it in memory,	1030	might be too late when you already have it in memory, so you might
289	so you might want to check the size before you accept the string.	1031	want to check the size before you accept the string.
290		1032
		1033	As for encoding, it is possible to construct data structures that
		1034	are relatively small but result in large CBOR texts (for example by
		1035	having an array full of references to the same big data structure,
		1036	which will all be deep-cloned during encoding by default). This is
		1037	rarely an actual issue (and the worst case is still just running out
		1038	of memory), but you can reduce this risk by using "allow_sharing".
		1039
		1040	Resource-starving attacks: stack overflows
291	Third, CBOR::XS recurses using the C stack when decoding objects and	1041	CBOR::XS recurses using the C stack when decoding objects and
292	arrays. The C stack is a limited resource: for instance, on my amd64	1042	arrays. The C stack is a limited resource: for instance, on my amd64
293	machine with 8MB of stack size I can decode around 180k nested arrays	1043	machine with 8MB of stack size I can decode around 180k nested
294	but only 14k nested CBOR objects (due to perl itself recursing deeply on	1044	arrays but only 14k nested CBOR objects (due to perl itself
295	croak to free the temporary). If that is exceeded, the program crashes.	1045	recursing deeply on croak to free the temporary). If that is
296	To be conservative, the default nesting limit is set to 512. If your	1046	exceeded, the program crashes. To be conservative, the default
297	process has a smaller stack, you should adjust this setting accordingly	1047	nesting limit is set to 512. If your process has a smaller stack,
298	with the "max_depth" method.	1048	you should adjust this setting accordingly with the "max_depth"
		1049	method.
299		1050
		1051	Resource-starving attacks: CPU en-/decoding complexity
		1052	CBOR::XS will use the Math::BigInt, Math::BigFloat and Math::BigRat
		1053	libraries to represent encode/decode bignums. These can be very slow
		1054	(as in, centuries of CPU time) and can even crash your program (and
		1055	are generally not very trustworthy). See the next section on bignum
		1056	security for details.
		1057
		1058	Data breaches: leaking information in error messages
		1059	CBOR::XS might leak contents of your Perl data structures in its
		1060	error messages, so when you serialise sensitive information you
		1061	might want to make sure that exceptions thrown by CBOR::XS will not
		1062	end up in front of untrusted eyes.
		1063
		1064	Something else...
300	Something else could bomb you, too, that I forgot to think of. In that	1065	Something else could bomb you, too, that I forgot to think of. In
301	case, you get to keep the pieces. I am always open for hints, though...	1066	that case, you get to keep the pieces. I am always open for hints,
		1067	though...
302		1068
303	Also keep in mind that CBOR::XS might leak contents of your Perl data	1069	BIGNUM SECURITY CONSIDERATIONS
304	structures in its error messages, so when you serialise sensitive	1070	CBOR::XS provides a "TO_CBOR" method for both Math::BigInt and
305	information you might want to make sure that exceptions thrown by	1071	Math::BigFloat that tries to encode the number in the simplest possible
306	CBOR::XS will not end up in front of untrusted eyes.	1072	way, that is, either a CBOR integer, a CBOR bigint/decimal fraction (tag
		1073	4) or an arbitrary-exponent decimal fraction (tag 264). Rational numbers
		1074	(Math::BigRat, tag 30) can also contain bignums as members.
		1075
		1076	CBOR::XS will also understand base-2 bigfloat or arbitrary-exponent
		1077	bigfloats (tags 5 and 265), but it will never generate these on its own.
		1078
		1079	Using the built-in Math::BigInt::Calc support, encoding and decoding
		1080	decimal fractions is generally fast. Decoding bigints can be slow for
		1081	very big numbers (tens of thousands of digits, something that could
		1082	potentially be caught by limiting the size of CBOR texts), and decoding
		1083	bigfloats or arbitrary-exponent bigfloats can be extremely slow
		1084	(minutes, decades) for large exponents (roughly 40 bit and longer).
		1085
		1086	Additionally, Math::BigInt can take advantage of other bignum libraries,
		1087	such as Math::GMP, which cannot handle big floats with large exponents,
		1088	and might simply abort or crash your program, due to their code quality.
		1089
		1090	This can be a concern if you want to parse untrusted CBOR. If it is, you
		1091	might want to disable decoding of tag 2 (bigint) and 3 (negative bigint)
		1092	types. You should also disable types 5 and 265, as these can be slow
		1093	even without bigints.
		1094
		1095	Disabling bigints will also partially or fully disable types that rely
		1096	on them, e.g. rational numbers that use bignums.
307		1097
308	CBOR IMPLEMENTATION NOTES	1098	CBOR IMPLEMENTATION NOTES
309	This section contains some random implementation notes. They do not	1099	This section contains some random implementation notes. They do not
310	describe guaranteed behaviour, but merely behaviour as-is implemented	1100	describe guaranteed behaviour, but merely behaviour as-is implemented
311	right now.	1101	right now.
…		…
319	Only the double data type is supported for NV data types - when Perl	1109	Only the double data type is supported for NV data types - when Perl
320	uses long double to represent floating point values, they might not be	1110	uses long double to represent floating point values, they might not be
321	encoded properly. Half precision types are accepted, but not encoded.	1111	encoded properly. Half precision types are accepted, but not encoded.
322		1112
323	Strict mode and canonical mode are not implemented.	1113	Strict mode and canonical mode are not implemented.
		1114
		1115	LIMITATIONS ON PERLS WITHOUT 64-BIT INTEGER SUPPORT
		1116	On perls that were built without 64 bit integer support (these are rare
		1117	nowadays, even on 32 bit architectures, as all major Perl distributions
		1118	are built with 64 bit integer support), support for any kind of 64 bit
		1119	value in CBOR is very limited - most likely, these 64 bit values will be
		1120	truncated, corrupted, or otherwise not decoded correctly. This also
		1121	includes string, float, array and map sizes that are stored as 64 bit
		1122	integers.
324		1123
325	THREADS	1124	THREADS
326	This module is not guaranteed to be thread safe and there are no plans	1125	This module is not guaranteed to be thread safe and there are no plans
327	to change this until Perl gets thread support (as opposed to the	1126	to change this until Perl gets thread support (as opposed to the
328	horribly slow so-called "threads" which are simply slow and bloated	1127	horribly slow so-called "threads" which are simply slow and bloated
…		…
340		1139
341	SEE ALSO	1140	SEE ALSO
342	The JSON and JSON::XS modules that do similar, but human-readable,	1141	The JSON and JSON::XS modules that do similar, but human-readable,
343	serialisation.	1142	serialisation.
344		1143
		1144	The Types::Serialiser module provides the data model for true, false and
		1145	error values.
		1146
345	AUTHOR	1147	AUTHOR
346	Marc Lehmann <schmorp@schmorp.de>	1148	Marc Lehmann <schmorp@schmorp.de>
347	http://home.schmorp.de/	1149	http://home.schmorp.de/
348		1150

Diff Legend

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

Comparing CBOR-XS/README (file contents): Revision 1.4 by root, Sat Oct 26 23:02:55 2013 UTC vs. Revision 1.19 by root, Sun Nov 29 21:35:51 2020 UTC

Diff Legend

Comparing CBOR-XS/README (file contents):
Revision 1.4 by root, Sat Oct 26 23:02:55 2013 UTC vs.
Revision 1.19 by root, Sun Nov 29 21:35:51 2020 UTC