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

Comparing CBOR-XS/README (file contents):
Revision 1.11 by root, Sat Nov 30 18:42:27 2013 UTC vs.
Revision 1.20 by root, Tue Dec 1 01:50:01 2020 UTC

…		…
33	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	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	35	compress the data later and speed is less important you might want to
36	compare both formats first).	36	compare both formats first).
37		37
		38	The primary goal of this module is to be correct and the secondary
		39	goal is to be fast. To reach the latter goal it was written in C.
		40
38	To give you a general idea about speed, with texts in the megabyte	41	To give you a general idea about speed, with texts in the megabyte
39	range, "CBOR::XS" usually encodes roughly twice as fast as Storable or	42	range, "CBOR::XS" usually encodes roughly twice as fast as Storable or
40	JSON::XS and decodes about 15%-30% faster than those. The shorter the	43	JSON::XS and decodes about 15%-30% faster than those. The shorter the
41	data, the worse Storable performs in comparison.	44	data, the worse Storable performs in comparison.
42		45
…		…
47	In addition to the core CBOR data format, this module implements a	50	In addition to the core CBOR data format, this module implements a
48	number of extensions, to support cyclic and shared data structures (see	51	number of extensions, to support cyclic and shared data structures (see
49	"allow_sharing" and "allow_cycles"), string deduplication (see	52	"allow_sharing" and "allow_cycles"), string deduplication (see
50	"pack_strings") and scalar references (always enabled).	53	"pack_strings") and scalar references (always enabled).
51		54
52	The primary goal of this module is to be correct and the secondary
53	goal is to be fast. To reach the latter goal it was written in C.
54
55	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
56	vice versa.	56	vice versa.
57		57
58	FUNCTIONAL INTERFACE	58	FUNCTIONAL INTERFACE
59	The following convenience methods are provided by this module. They are	59	The following convenience methods are provided by this module. They are
…		…
78		78
79	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
80	calls can be chained:	80	calls can be chained:
81		81
82	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).
83		97
84	$cbor = $cbor->max_depth ([$maximum_nesting_depth])	98	$cbor = $cbor->max_depth ([$maximum_nesting_depth])
85	$max_depth = $cbor->get_max_depth	99	$max_depth = $cbor->get_max_depth
86	Sets the maximum nesting level (default 512) accepted while encoding	100	Sets the maximum nesting level (default 512) accepted while encoding
87	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
…		…
101		115
102	Note that nesting is implemented by recursion in C. The default	116	Note that nesting is implemented by recursion in C. The default
103	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
104	allow without crashing.	118	allow without crashing.
105		119
106	See SECURITY CONSIDERATIONS, below, for more info on why this is	120	See "SECURITY CONSIDERATIONS", below, for more info on why this is
107	useful.	121	useful.
108		122
109	$cbor = $cbor->max_size ([$maximum_string_size])	123	$cbor = $cbor->max_size ([$maximum_string_size])
110	$max_size = $cbor->get_max_size	124	$max_size = $cbor->get_max_size
111	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
…		…
115	exception. This setting has no effect on "encode" (yet).	129	exception. This setting has no effect on "encode" (yet).
116		130
117	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
118	as when 0 is specified).	132	as when 0 is specified).
119		133
120	See SECURITY CONSIDERATIONS, below, for more info on why this is	134	See "SECURITY CONSIDERATIONS", below, for more info on why this is
121	useful.	135	useful.
122		136
123	$cbor = $cbor->allow_unknown ([$enable])	137	$cbor = $cbor->allow_unknown ([$enable])
124	$enabled = $cbor->get_allow_unknown	138	$enabled = $cbor->get_allow_unknown
125	If $enable is true (or missing), then "encode" will not throw an	139	If $enable is true (or missing), then "encode" will not throw an
…		…
141	instead will emit a reference to the earlier value.	155	instead will emit a reference to the earlier value.
142		156
143	This means that such values will only be encoded once, and will not	157	This means that such values will only be encoded once, and will not
144	result in a deep cloning of the value on decode, in decoders	158	result in a deep cloning of the value on decode, in decoders
145	supporting the value sharing extension. This also makes it possible	159	supporting the value sharing extension. This also makes it possible
146	to encode cyclic data structures (which need "allow_cycles" to ne	160	to encode cyclic data structures (which need "allow_cycles" to be
147	enabled to be decoded by this module).	161	enabled to be decoded by this module).
148		162
149	It is recommended to leave it off unless you know your communication	163	It is recommended to leave it off unless you know your communication
150	partner supports the value sharing extensions to CBOR	164	partner supports the value sharing extensions to CBOR
151	(<http://cbor.schmorp.de/value-sharing>), as without decoder	165	(<http://cbor.schmorp.de/value-sharing>), as without decoder
152	support, the resulting data structure might be unusable.	166	support, the resulting data structure might be unusable.
153		167
154	Detecting shared values incurs a runtime overhead when values are	168	Detecting shared values incurs a runtime overhead when values are
155	encoded that have a reference counter large than one, and might	169	encoded that have a reference counter large than one, and might
156	unnecessarily increase the encoded size, as potentially shared	170	unnecessarily increase the encoded size, as potentially shared
157	values are encode as shareable whether or not they are actually	171	values are encoded as shareable whether or not they are actually
158	shared.	172	shared.
159		173
160	At the moment, only targets of references can be shared (e.g.	174	At the moment, only targets of references can be shared (e.g.
161	scalars, arrays or hashes pointed to by a reference). Weirder	175	scalars, arrays or hashes pointed to by a reference). Weirder
162	constructs, such as an array with multiple "copies" of the same	176	constructs, such as an array with multiple "copies" of the same
…		…
178	code that isn't prepared for this will not leak memory.	192	code that isn't prepared for this will not leak memory.
179		193
180	If $enable is false (the default), then "decode" will throw an error	194	If $enable is false (the default), then "decode" will throw an error
181	when it encounters a self-referential/cyclic data structure.	195	when it encounters a self-referential/cyclic data structure.
182		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
183	This option does not affect "encode" in any way - shared values and	202	This option does not affect "encode" in any way - shared values and
184	references will always be decoded properly if present.	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.
185		223
186	$cbor = $cbor->pack_strings ([$enable])	224	$cbor = $cbor->pack_strings ([$enable])
187	$enabled = $cbor->get_pack_strings	225	$enabled = $cbor->get_pack_strings
188	If $enable is true (or missing), then "encode" will try not to	226	If $enable is true (or missing), then "encode" will try not to
189	encode the same string twice, but will instead encode a reference to	227	encode the same string twice, but will instead encode a reference to
…		…
200	the standard CBOR way.	238	the standard CBOR way.
201		239
202	This option does not affect "decode" in any way - string references	240	This option does not affect "decode" in any way - string references
203	will always be decoded properly if present.	241	will always be decoded properly if present.
204		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
205	$cbor = $cbor->filter ([$cb->($tag, $value)])	311	$cbor = $cbor->filter ([$cb->($tag, $value)])
206	$cb_or_undef = $cbor->get_filter	312	$cb_or_undef = $cbor->get_filter
207	Sets or replaces the tagged value decoding filter (when $cb is	313	Sets or replaces the tagged value decoding filter (when $cb is
208	specified) or clears the filter (if no argument or "undef" is	314	specified) or clears the filter (if no argument or "undef" is
209	provided).	315	provided).
…		…
226	When the filter is cleared (the default state), the default filter	332	When the filter is cleared (the default state), the default filter
227	function, "CBOR::XS::default_filter", is used. This function simply	333	function, "CBOR::XS::default_filter", is used. This function simply
228	looks up the tag in the %CBOR::XS::FILTER hash. If an entry exists	334	looks up the tag in the %CBOR::XS::FILTER hash. If an entry exists
229	it must be a code reference that is called with tag and value, and	335	it must be a code reference that is called with tag and value, and
230	is responsible for decoding the value. If no entry exists, it	336	is responsible for decoding the value. If no entry exists, it
231	returns no values.	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.
232		351
233	Example: decode all tags not handled internally into	352	Example: decode all tags not handled internally into
234	"CBOR::XS::Tagged" objects, with no other special handling (useful	353	"CBOR::XS::Tagged" objects, with no other special handling (useful
235	when working with potentially "unsafe" CBOR data).	354	when working with potentially "unsafe" CBOR data).
236		355
…		…
242	$CBOR::XS::FILTER{1347375694} = sub {	361	$CBOR::XS::FILTER{1347375694} = sub {
243	my ($tag, $value);	362	my ($tag, $value);
244		363
245	"tag 1347375694 value $value"	364	"tag 1347375694 value $value"
246	};	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);
247		386
248	$cbor_data = $cbor->encode ($perl_scalar)	387	$cbor_data = $cbor->encode ($perl_scalar)
249	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
250	representation.	389	representation.
251		390
…		…
259	will silently stop parsing there and return the number of characters	398	will silently stop parsing there and return the number of characters
260	consumed so far.	399	consumed so far.
261		400
262	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
263	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
264	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.
265		406
266	CBOR::XS->new->decode_prefix ("......")	407	CBOR::XS->new->decode_prefix ("......")
267	=> ("...", 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.
268		467
269	MAPPING	468	MAPPING
270	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
271	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
272	circumstances automatically, preserving round-tripping characteristics	471	circumstances automatically, preserving round-tripping characteristics
…		…
323		522
324	hash references	523	hash references
325	Perl hash references become CBOR maps. As there is no inherent	524	Perl hash references become CBOR maps. As there is no inherent
326	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
327	in a pseudo-random order. This order can be different each time a	526	in a pseudo-random order. This order can be different each time a
328	hahs is encoded.	527	hash is encoded.
329		528
330	Currently, tied hashes will use the indefinite-length format, while	529	Currently, tied hashes will use the indefinite-length format, while
331	normal hashes will use the fixed-length format.	530	normal hashes will use the fixed-length format.
332		531
333	array references	532	array references
…		…
382	my $x = 3.1; # some variable containing a number	581	my $x = 3.1; # some variable containing a number
383	"$x"; # stringified	582	"$x"; # stringified
384	$x .= ""; # another, more awkward way to stringify	583	$x .= ""; # another, more awkward way to stringify
385	print $x; # perl does it for you, too, quite often	584	print $x; # perl does it for you, too, quite often
386		585
387	You can force whether a string ie encoded as byte or text string by	586	You can force whether a string is encoded as byte or text string by
388	using "utf8::upgrade" and "utf8::downgrade"):	587	using "utf8::upgrade" and "utf8::downgrade" (if "text_strings" is
		588	disabled).
389		589
390	utf8::upgrade $x; # encode $x as text string	590	utf8::upgrade $x; # encode $x as text string
391	utf8::downgrade $x; # encode $x as byte string	591	utf8::downgrade $x; # encode $x as byte string
392		592
		593	More options are available, see "TYPE CASTS", below, and the
		594	"text_keys" and "text_strings" options.
		595
393	Perl doesn't define what operations up- and downgrade strings, so if	596	Perl doesn't define what operations up- and downgrade strings, so if
394	the difference between byte and text is important, you should up- or	597	the difference between byte and text is important, you should up- or
395	downgrade your string as late as possible before encoding.	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".
396		601
397	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:
398		603
399	my $x = "3"; # some variable containing a string	604	my $x = "3"; # some variable containing a string
400	$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
…		…
409	IEEE single format if possible without loss of precision, otherwise	614	IEEE single format if possible without loss of precision, otherwise
410	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
411	than IEEE double to represent numerical values are supported, but	616	than IEEE double to represent numerical values are supported, but
412	might suffer loss of precision.	617	might suffer loss of precision.
413		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_bool $value
		643	Converts a Perl boolean (which can be any kind of scalar) into a
		644	CBOR boolean. Strictly the same, but shorter to write, than:
		645
		646	$value ? Types::Serialiser::true : Types::Serialiser::false
		647
		648	CBOR::XS::as_float16 $value
		649	Forces half-float (IEEE 754 binary16) encoding of the given value.
		650
		651	CBOR::XS::as_float32 $value
		652	Forces single-float (IEEE 754 binary32) encoding of the given value.
		653
		654	CBOR::XS::as_float64 $value
		655	Forces double-float (IEEE 754 binary64) encoding of the given value.
		656
		657	=item, CBOR::XS::as_cbor $cbor_text
		658
		659	Bot a type cast per-se, this type cast forces the argument to eb
		660	encoded as-is. This can be used to embed pre-encoded CBOR data.
		661
		662	Note that no checking on the validity of the $cbor_text is done -
		663	it's the callers responsibility to correctly encode values.
		664
		665	Example: encode a perl string as binary even though "text_strings" is in
		666	effect.
		667
		668	CBOR::XS->new->text_strings->encode ([4, "text", CBOR::XS::bytes "bytevalue"]);
		669
414	OBJECT SERIALISATION	670	OBJECT SERIALISATION
415	This module implements both a CBOR-specific and the generic	671	This module implements both a CBOR-specific and the generic
416	Types::Serialier object serialisation protocol. The following	672	Types::Serialier object serialisation protocol. The following
417	subsections explain both methods.	673	subsections explain both methods.
418		674
…		…
495	"$self" # encode url string	751	"$self" # encode url string
496	}	752	}
497		753
498	sub URI::THAW {	754	sub URI::THAW {
499	my ($class, $serialiser, $uri) = @_;	755	my ($class, $serialiser, $uri) = @_;
500
501	$class->new ($uri)	756	$class->new ($uri)
502	}	757	}
503		758
504	Unlike "TO_CBOR", multiple values can be returned by "FREEZE". For	759	Unlike "TO_CBOR", multiple values can be returned by "FREEZE". For
505	example, a "FREEZE" method that returns "type", "id" and "variant"	760	example, a "FREEZE" method that returns "type", "id" and "variant"
…		…
601	Future versions of this module reserve the right to special case	856	Future versions of this module reserve the right to special case
602	additional tags (such as base64url).	857	additional tags (such as base64url).
603		858
604	ENFORCED TAGS	859	ENFORCED TAGS
605	These tags are always handled when decoding, and their handling cannot	860	These tags are always handled when decoding, and their handling cannot
606	be overriden by the user.	861	be overridden by the user.
607		862
608	26 (perl-object, <http://cbor.schmorp.de/perl-object>)	863	26 (perl-object, <http://cbor.schmorp.de/perl-object>)
609	These tags are automatically created (and decoded) for serialisable	864	These tags are automatically created (and decoded) for serialisable
610	objects using the "FREEZE/THAW" methods (the Types::Serialier object	865	objects using the "FREEZE/THAW" methods (the Types::Serialier object
611	serialisation protocol). See "OBJECT SERIALISATION" for details.	866	serialisation protocol). See "OBJECT SERIALISATION" for details.
612		867
613	28, 29 (shareable, sharedref, L <http://cbor.schmorp.de/value-sharing>)	868	28, 29 (shareable, sharedref, <http://cbor.schmorp.de/value-sharing>)
614	These tags are automatically decoded when encountered (and they do	869	These tags are automatically decoded when encountered (and they do
615	not result in a cyclic data structure, see "allow_cycles"),	870	not result in a cyclic data structure, see "allow_cycles"),
616	resulting in shared values in the decoded object. They are only	871	resulting in shared values in the decoded object. They are only
617	encoded, however, when "allow_sharing" is enabled.	872	encoded, however, when "allow_sharing" is enabled.
618		873
…		…
627	references will be shared, others will not. While non-reference	882	references will be shared, others will not. While non-reference
628	shared values can be generated in Perl with some effort, they were	883	shared values can be generated in Perl with some effort, they were
629	considered too unimportant to be supported in the encoder. The	884	considered too unimportant to be supported in the encoder. The
630	decoder, however, will decode these values as shared values.	885	decoder, however, will decode these values as shared values.
631		886
632	256, 25 (stringref-namespace, stringref, L	887	256, 25 (stringref-namespace, stringref,
633	<http://cbor.schmorp.de/stringref>)	888	<http://cbor.schmorp.de/stringref>)
634	These tags are automatically decoded when encountered. They are only	889	These tags are automatically decoded when encountered. They are only
635	encoded, however, when "pack_strings" is enabled.	890	encoded, however, when "pack_strings" is enabled.
636		891
637	22098 (indirection, <http://cbor.schmorp.de/indirection>)	892	22098 (indirection, <http://cbor.schmorp.de/indirection>)
638	This tag is automatically generated when a reference are encountered	893	This tag is automatically generated when a reference are encountered
639	(with the exception of hash and array refernces). It is converted to	894	(with the exception of hash and array references). It is converted
640	a reference when decoding.	895	to a reference when decoding.
641		896
642	55799 (self-describe CBOR, RFC 7049)	897	55799 (self-describe CBOR, RFC 7049)
643	This value is not generated on encoding (unless explicitly requested	898	This value is not generated on encoding (unless explicitly requested
644	by the user), and is simply ignored when decoding.	899	by the user), and is simply ignored when decoding.
645		900
646	NON-ENFORCED TAGS	901	NON-ENFORCED TAGS
647	These tags have default filters provided when decoding. Their handling	902	These tags have default filters provided when decoding. Their handling
648	can be overriden by changing the %CBOR::XS::FILTER entry for the tag, or	903	can be overridden by changing the %CBOR::XS::FILTER entry for the tag,
649	by providing a custom "filter" callback when decoding.	904	or by providing a custom "filter" callback when decoding.
650		905
651	When they result in decoding into a specific Perl class, the module	906	When they result in decoding into a specific Perl class, the module
652	usually provides a corresponding "TO_CBOR" method as well.	907	usually provides a corresponding "TO_CBOR" method as well.
653		908
654	When any of these need to load additional modules that are not part of	909	When any of these need to load additional modules that are not part of
655	the perl core distribution (e.g. URI), it is (currently) up to the user	910	the perl core distribution (e.g. URI), it is (currently) up to the user
656	to provide these modules. The decoding usually fails with an exception	911	to provide these modules. The decoding usually fails with an exception
657	if the required module cannot be loaded.	912	if the required module cannot be loaded.
658		913
		914	0, 1 (date/time string, seconds since the epoch)
		915	These tags are decoded into Time::Piece objects. The corresponding
		916	"Time::Piece::TO_CBOR" method always encodes into tag 1 values
		917	currently.
		918
		919	The Time::Piece API is generally surprisingly bad, and fractional
		920	seconds are only accidentally kept intact, so watch out. On the plus
		921	side, the module comes with perl since 5.10, which has to count for
		922	something.
		923
659	2, 3 (positive/negative bignum)	924	2, 3 (positive/negative bignum)
660	These tags are decoded into Math::BigInt objects. The corresponding	925	These tags are decoded into Math::BigInt objects. The corresponding
661	"Math::BigInt::TO_CBOR" method encodes "small" bigints into normal	926	"Math::BigInt::TO_CBOR" method encodes "small" bigints into normal
662	CBOR integers, and others into positive/negative CBOR bignums.	927	CBOR integers, and others into positive/negative CBOR bignums.
663		928
664	4, 5 (decimal fraction/bigfloat)	929	4, 5, 264, 265 (decimal fraction/bigfloat)
665	Both decimal fractions and bigfloats are decoded into Math::BigFloat	930	Both decimal fractions and bigfloats are decoded into Math::BigFloat
666	objects. The corresponding "Math::BigFloat::TO_CBOR" method always	931	objects. The corresponding "Math::BigFloat::TO_CBOR" method always
667	encodes into a decimal fraction.	932	encodes into a decimal fraction (either tag 4 or 264).
668		933
669	CBOR cannot represent bigfloats with very large exponents -
670	conversion of such big float objects is undefined.
671
672	Also, NaN and infinities are not encoded properly.	934	NaN and infinities are not encoded properly, as they cannot be
		935	represented in CBOR.
		936
		937	See "BIGNUM SECURITY CONSIDERATIONS" for more info.
		938
		939	30 (rational numbers)
		940	These tags are decoded into Math::BigRat objects. The corresponding
		941	"Math::BigRat::TO_CBOR" method encodes rational numbers with
		942	denominator 1 via their numerator only, i.e., they become normal
		943	integers or "bignums".
		944
		945	See "BIGNUM SECURITY CONSIDERATIONS" for more info.
673		946
674	21, 22, 23 (expected later JSON conversion)	947	21, 22, 23 (expected later JSON conversion)
675	CBOR::XS is not a CBOR-to-JSON converter, and will simply ignore	948	CBOR::XS is not a CBOR-to-JSON converter, and will simply ignore
676	these tags.	949	these tags.
677		950
…		…
691	interoperability is improved in the future, then the goal will be to	964	interoperability is improved in the future, then the goal will be to
692	ensure that decoded JSON data will round-trip encoding and decoding to	965	ensure that decoded JSON data will round-trip encoding and decoding to
693	CBOR intact.	966	CBOR intact.
694		967
695	SECURITY CONSIDERATIONS	968	SECURITY CONSIDERATIONS
696	When you are using CBOR in a protocol, talking to untrusted potentially	969	Tl;dr... if you want to decode or encode CBOR from untrusted sources,
697	hostile creatures requires relatively few measures.	970	you should start with a coder object created via "new_safe" (which
		971	implements the mitigations explained below):
698		972
		973	my $coder = CBOR::XS->new_safe;
		974
		975	my $data = $coder->decode ($cbor_text);
		976	my $cbor = $coder->encode ($data);
		977
		978	Longer version: When you are using CBOR in a protocol, talking to
		979	untrusted potentially hostile creatures requires some thought:
		980
		981	Security of the CBOR decoder itself
699	First of all, your CBOR decoder should be secure, that is, should not	982	First and foremost, your CBOR decoder should be secure, that is,
700	have any buffer overflows. Obviously, this module should ensure that and	983	should not have any buffer overflows or similar bugs that could
		984	potentially be exploited. Obviously, this module should ensure that
701	I am trying hard on making that true, but you never know.	985	and I am trying hard on making that true, but you never know.
702		986
		987	CBOR::XS can invoke almost arbitrary callbacks during decoding
		988	CBOR::XS supports object serialisation - decoding CBOR can cause
		989	calls to any "THAW" method in any package that exists in your
		990	process (that is, CBOR::XS will not try to load modules, but any
		991	existing "THAW" method or function can be called, so they all have
		992	to be secure).
		993
		994	Less obviously, it will also invoke "TO_CBOR" and "FREEZE" methods -
		995	even if all your "THAW" methods are secure, encoding data structures
		996	from untrusted sources can invoke those and trigger bugs in those.
		997
		998	So, if you are not sure about the security of all the modules you
		999	have loaded (you shouldn't), you should disable this part using
		1000	"forbid_objects" or using "new_safe".
		1001
		1002	CBOR can be extended with tags that call library code
		1003	CBOR can be extended with tags, and "CBOR::XS" has a registry of
		1004	conversion functions for many existing tags that can be extended via
		1005	third-party modules (see the "filter" method).
		1006
		1007	If you don't trust these, you should configure the "safe" filter
		1008	function, "CBOR::XS::safe_filter" ("new_safe" does this), which by
		1009	default only includes conversion functions that are considered
		1010	"safe" by the author (but again, they can be extended by third party
		1011	modules).
		1012
		1013	Depending on your level of paranoia, you can use the "safe" filter:
		1014
		1015	$cbor->filter (\&CBOR::XS::safe_filter);
		1016
		1017	... your own filter...
		1018
		1019	$cbor->filter (sub { ... do your stuffs here ... });
		1020
		1021	... or even no filter at all, disabling all tag decoding:
		1022
		1023	$cbor->filter (sub { });
		1024
		1025	This is never a problem for encoding, as the tag mechanism only
		1026	exists in CBOR texts.
		1027
		1028	Resource-starving attacks: object memory usage
703	Second, you need to avoid resource-starving attacks. That means you	1029	You need to avoid resource-starving attacks. That means you should
704	should limit the size of CBOR data you accept, or make sure then when	1030	limit the size of CBOR data you accept, or make sure then when your
705	your resources run out, that's just fine (e.g. by using a separate	1031	resources run out, that's just fine (e.g. by using a separate
706	process that can crash safely). The size of a CBOR string in octets is	1032	process that can crash safely). The size of a CBOR string in octets
707	usually a good indication of the size of the resources required to	1033	is usually a good indication of the size of the resources required
708	decode it into a Perl structure. While CBOR::XS can check the size of	1034	to decode it into a Perl structure. While CBOR::XS can check the
		1035	size of the CBOR text (using "max_size" - done by "new_safe"), it
709	the CBOR text, it might be too late when you already have it in memory,	1036	might be too late when you already have it in memory, so you might
710	so you might want to check the size before you accept the string.	1037	want to check the size before you accept the string.
711		1038
		1039	As for encoding, it is possible to construct data structures that
		1040	are relatively small but result in large CBOR texts (for example by
		1041	having an array full of references to the same big data structure,
		1042	which will all be deep-cloned during encoding by default). This is
		1043	rarely an actual issue (and the worst case is still just running out
		1044	of memory), but you can reduce this risk by using "allow_sharing".
		1045
		1046	Resource-starving attacks: stack overflows
712	Third, CBOR::XS recurses using the C stack when decoding objects and	1047	CBOR::XS recurses using the C stack when decoding objects and
713	arrays. The C stack is a limited resource: for instance, on my amd64	1048	arrays. The C stack is a limited resource: for instance, on my amd64
714	machine with 8MB of stack size I can decode around 180k nested arrays	1049	machine with 8MB of stack size I can decode around 180k nested
715	but only 14k nested CBOR objects (due to perl itself recursing deeply on	1050	arrays but only 14k nested CBOR objects (due to perl itself
716	croak to free the temporary). If that is exceeded, the program crashes.	1051	recursing deeply on croak to free the temporary). If that is
717	To be conservative, the default nesting limit is set to 512. If your	1052	exceeded, the program crashes. To be conservative, the default
718	process has a smaller stack, you should adjust this setting accordingly	1053	nesting limit is set to 512. If your process has a smaller stack,
719	with the "max_depth" method.	1054	you should adjust this setting accordingly with the "max_depth"
		1055	method.
720		1056
		1057	Resource-starving attacks: CPU en-/decoding complexity
		1058	CBOR::XS will use the Math::BigInt, Math::BigFloat and Math::BigRat
		1059	libraries to represent encode/decode bignums. These can be very slow
		1060	(as in, centuries of CPU time) and can even crash your program (and
		1061	are generally not very trustworthy). See the next section on bignum
		1062	security for details.
		1063
		1064	Data breaches: leaking information in error messages
		1065	CBOR::XS might leak contents of your Perl data structures in its
		1066	error messages, so when you serialise sensitive information you
		1067	might want to make sure that exceptions thrown by CBOR::XS will not
		1068	end up in front of untrusted eyes.
		1069
		1070	Something else...
721	Something else could bomb you, too, that I forgot to think of. In that	1071	Something else could bomb you, too, that I forgot to think of. In
722	case, you get to keep the pieces. I am always open for hints, though...	1072	that case, you get to keep the pieces. I am always open for hints,
		1073	though...
723		1074
724	Also keep in mind that CBOR::XS might leak contents of your Perl data	1075	BIGNUM SECURITY CONSIDERATIONS
725	structures in its error messages, so when you serialise sensitive	1076	CBOR::XS provides a "TO_CBOR" method for both Math::BigInt and
726	information you might want to make sure that exceptions thrown by	1077	Math::BigFloat that tries to encode the number in the simplest possible
727	CBOR::XS will not end up in front of untrusted eyes.	1078	way, that is, either a CBOR integer, a CBOR bigint/decimal fraction (tag
		1079	4) or an arbitrary-exponent decimal fraction (tag 264). Rational numbers
		1080	(Math::BigRat, tag 30) can also contain bignums as members.
		1081
		1082	CBOR::XS will also understand base-2 bigfloat or arbitrary-exponent
		1083	bigfloats (tags 5 and 265), but it will never generate these on its own.
		1084
		1085	Using the built-in Math::BigInt::Calc support, encoding and decoding
		1086	decimal fractions is generally fast. Decoding bigints can be slow for
		1087	very big numbers (tens of thousands of digits, something that could
		1088	potentially be caught by limiting the size of CBOR texts), and decoding
		1089	bigfloats or arbitrary-exponent bigfloats can be extremely slow
		1090	(minutes, decades) for large exponents (roughly 40 bit and longer).
		1091
		1092	Additionally, Math::BigInt can take advantage of other bignum libraries,
		1093	such as Math::GMP, which cannot handle big floats with large exponents,
		1094	and might simply abort or crash your program, due to their code quality.
		1095
		1096	This can be a concern if you want to parse untrusted CBOR. If it is, you
		1097	might want to disable decoding of tag 2 (bigint) and 3 (negative bigint)
		1098	types. You should also disable types 5 and 265, as these can be slow
		1099	even without bigints.
		1100
		1101	Disabling bigints will also partially or fully disable types that rely
		1102	on them, e.g. rational numbers that use bignums.
728		1103
729	CBOR IMPLEMENTATION NOTES	1104	CBOR IMPLEMENTATION NOTES
730	This section contains some random implementation notes. They do not	1105	This section contains some random implementation notes. They do not
731	describe guaranteed behaviour, but merely behaviour as-is implemented	1106	describe guaranteed behaviour, but merely behaviour as-is implemented
732	right now.	1107	right now.
…		…
743		1118
744	Strict mode and canonical mode are not implemented.	1119	Strict mode and canonical mode are not implemented.
745		1120
746	LIMITATIONS ON PERLS WITHOUT 64-BIT INTEGER SUPPORT	1121	LIMITATIONS ON PERLS WITHOUT 64-BIT INTEGER SUPPORT
747	On perls that were built without 64 bit integer support (these are rare	1122	On perls that were built without 64 bit integer support (these are rare
748	nowadays, even on 32 bit architectures), support for any kind of 64 bit	1123	nowadays, even on 32 bit architectures, as all major Perl distributions
		1124	are built with 64 bit integer support), support for any kind of 64 bit
749	integer in CBOR is very limited - most likely, these 64 bit values will	1125	value in CBOR is very limited - most likely, these 64 bit values will be
750	be truncated, corrupted, or otherwise not decoded correctly. This also	1126	truncated, corrupted, or otherwise not decoded correctly. This also
751	includes string, array and map sizes that are stored as 64 bit integers.	1127	includes string, float, array and map sizes that are stored as 64 bit
		1128	integers.
752		1129
753	THREADS	1130	THREADS
754	This module is not guaranteed to be thread safe and there are no plans	1131	This module is not guaranteed to be thread safe and there are no plans
755	to change this until Perl gets thread support (as opposed to the	1132	to change this until Perl gets thread support (as opposed to the
756	horribly slow so-called "threads" which are simply slow and bloated	1133	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.11 by root, Sat Nov 30 18:42:27 2013 UTC vs. Revision 1.20 by root, Tue Dec 1 01:50:01 2020 UTC

Diff Legend

Comparing CBOR-XS/README (file contents):
Revision 1.11 by root, Sat Nov 30 18:42:27 2013 UTC vs.
Revision 1.20 by root, Tue Dec 1 01:50:01 2020 UTC