[ViewVC] Diff of: cvs/CBOR-XS/XS.pm

Comparing CBOR-XS/XS.pm (file contents):
Revision 1.67 by root, Thu Nov 15 19:52:41 2018 UTC vs.
Revision 1.70 by root, Sat Nov 9 07:30:36 2019 UTC

 with the added ability of supporting serialisation of Perl objects. (JSON
 often compresses better than CBOR though, so if you plan to compress the
 data later and speed is less important you might want to compare both
 formats first).
+The primary goal of this module is to be I<correct> and the secondary goal
+is to be I<fast>. To reach the latter goal it was written in C.
 To give you a general idea about speed, with texts in the megabyte range,
 C<CBOR::XS> usually encodes roughly twice as fast as L<Storable> or
 L<JSON::XS> and decodes about 15%-30% faster than those. The shorter the
 data, the worse L<Storable> performs in comparison.
 In addition to the core CBOR data format, this module implements a
 number of extensions, to support cyclic and shared data structures
 (see C<allow_sharing> and C<allow_cycles>), string deduplication (see
 C<pack_strings>) and scalar references (always enabled).
-The primary goal of this module is to be I<correct> and the secondary goal
-is to be I<fast>. To reach the latter goal it was written in C.
 See MAPPING, below, on how CBOR::XS maps perl values to CBOR values and
 vice versa.
 =cut
 (L<http://cbor.schmorp.de/value-sharing>), as without decoder support, the
 resulting data structure might be unusable.
 Detecting shared values incurs a runtime overhead when values are encoded
 that have a reference counter large than one, and might unnecessarily
-increase the encoded size, as potentially shared values are encode as
+increase the encoded size, as potentially shared values are encoded as
 shareable whether or not they are actually shared.
 At the moment, only targets of references can be shared (e.g. scalars,
 arrays or hashes pointed to by a reference). Weirder constructs, such as
 an array with multiple "copies" of the I<same> string, which are hard but
 when there is trailing garbage after the CBOR string, it will silently
 stop parsing there and return the number of characters consumed so far.
 This is useful if your CBOR texts are not delimited by an outer protocol
 and you need to know where the first CBOR string ends amd the next one
-starts.
+starts - CBOR strings are self-delimited, so it is possible to concatenate
+CBOR strings without any delimiters or size fields and recover their data.
    CBOR::XS->new->decode_prefix ("......")
    => ("...", 3)
 =back
 =head1 SECURITY CONSIDERATIONS
 Tl;dr... if you want to decode or encode CBOR from untrusted sources, you
-should start with a coder object created via C<new_safe>:
+should start with a coder object created via C<new_safe> (which implements
+the mitigations explained below):
    my $coder = CBOR::XS->new_safe;
    my $data = $coder->decode ($cbor_text);
    my $cbor = $coder->encode ($data);
 even if all your C<THAW> methods are secure, encoding data structures from
 untrusted sources can invoke those and trigger bugs in those.
 So, if you are not sure about the security of all the modules you
 have loaded (you shouldn't), you should disable this part using
-C<forbid_objects>.
+C<forbid_objects> or using C<new_safe>.
 =item CBOR can be extended with tags that call library code
 CBOR can be extended with tags, and C<CBOR::XS> has a registry of
 conversion functions for many existing tags that can be extended via
 third-party modules (see the C<filter> method).
 If you don't trust these, you should configure the "safe" filter function,
-C<CBOR::XS::safe_filter>, which by default only includes conversion
+C<CBOR::XS::safe_filter> (C<new_safe> does this), which by default only
-functions that are considered "safe" by the author (but again, they can be
+includes conversion functions that are considered "safe" by the author
-extended by third party modules).
+(but again, they can be extended by third party modules).
 Depending on your level of paranoia, you can use the "safe" filter:
    $cbor->filter (\&CBOR::XS::safe_filter);
 the size of CBOR data you accept, or make sure then when your resources
 run out, that's just fine (e.g. by using a separate process that can
 crash safely). The size of a CBOR string in octets is usually a good
 indication of the size of the resources required to decode it into a Perl
 structure. While CBOR::XS can check the size of the CBOR text (using
-C<max_size>), it might be too late when you already have it in memory, so
+C<max_size> - done by C<new_safe>), it might be too late when you already
-you might want to check the size before you accept the string.
+have it in memory, so you might want to check the size before you accept
+the string.
 As for encoding, it is possible to construct data structures that are
 relatively small but result in large CBOR texts (for example by having an
 array full of references to the same big data structure, which will all be
 deep-cloned during encoding by default). This is rarely an actual issue
 method.
 =item Resource-starving attacks: CPU en-/decoding complexity
 CBOR::XS will use the L<Math::BigInt>, L<Math::BigFloat> and
-L<Math::BigRat> libraries to represent encode/decode bignums. These can
+L<Math::BigRat> libraries to represent encode/decode bignums. These can be
-be very slow (as in, centuries of CPU time) and can even crash your
+very slow (as in, centuries of CPU time) and can even crash your program
-program (and are generally not very trustworthy). See the next section for
+(and are generally not very trustworthy). See the next section on bignum
-details.
+security for details.
 =item Data breaches: leaking information in error messages
 CBOR::XS might leak contents of your Perl data structures in its error
 messages, so when you serialise sensitive information you might want to

Diff Legend

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

Comparing CBOR-XS/XS.pm (file contents): Revision 1.67 by root, Thu Nov 15 19:52:41 2018 UTC vs. Revision 1.70 by root, Sat Nov 9 07:30:36 2019 UTC

Diff Legend

Comparing CBOR-XS/XS.pm (file contents):
Revision 1.67 by root, Thu Nov 15 19:52:41 2018 UTC vs.
Revision 1.70 by root, Sat Nov 9 07:30:36 2019 UTC