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

Comparing CBOR-XS/README (file contents):
Revision 1.6 by root, Mon Oct 28 21:28:14 2013 UTC vs.
Revision 1.23 by root, Fri Sep 8 20:03:06 2023 UTC

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

Diff Legend

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

Comparing CBOR-XS/README (file contents): Revision 1.6 by root, Mon Oct 28 21:28:14 2013 UTC vs. Revision 1.23 by root, Fri Sep 8 20:03:06 2023 UTC

Diff Legend

Comparing CBOR-XS/README (file contents):
Revision 1.6 by root, Mon Oct 28 21:28:14 2013 UTC vs.
Revision 1.23 by root, Fri Sep 8 20:03:06 2023 UTC