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

Comparing CBOR-XS/XS.pm (file contents):
Revision 1.51 by root, Sun Apr 24 19:16:15 2016 UTC vs.
Revision 1.63 by root, Fri Nov 25 12:16:12 2016 UTC

 package CBOR::XS;
 use common::sense;
-our $VERSION = 1.41;
+our $VERSION = 1.51;
 our @ISA = qw(Exporter);
 our @EXPORT = qw(encode_cbor decode_cbor);
 use Exporter;
 reference to the earlier value.
 This means that such values will only be encoded once, and will not result
 in a deep cloning of the value on decode, in decoders supporting the value
 sharing extension. This also makes it possible to encode cyclic data
-structures (which need C<allow_cycles> to ne enabled to be decoded by this
+structures (which need C<allow_cycles> to be enabled to be decoded by this
 module).
 It is recommended to leave it off unless you know your
 communication partner supports the value sharing extensions to CBOR
 (L<http://cbor.schmorp.de/value-sharing>), as without decoder support, the
 If C<$enable> is false (the default), then C<encode> will encode strings
 the standard CBOR way.
 This option does not affect C<decode> in any way - string references will
 always be decoded properly if present.
+=item $cbor = $cbor->text_keys ([$enable])
+=item $enabled = $cbor->get_text_keys
+If C<$enabled> is true (or missing), then C<encode> will encode all
+perl hash keys as CBOR text strings/UTF-8 string, upgrading them as needed.
+If C<$enable> is false (the default), then C<encode> will encode hash keys
+normally - upgraded perl strings (strings internally encoded as UTF-8) as
+CBOR text strings, and downgraded perl strings as CBOR byte strings.
+This option does not affect C<decode> in any way.
+This option is useful for interoperability with CBOR decoders that don't
+treat byte strings as a form of text. It is especially useful as Perl
+gives very little control over hash keys.
+Enabling this option can be slow, as all downgraded hash keys that are
+encoded need to be scanned and converted to UTF-8.
+=item $cbor = $cbor->text_strings ([$enable])
+=item $enabled = $cbor->get_text_strings
+This option works similar to C<text_keys>, above, but works on all strings
+(including hash keys), so C<text_keys> has no further effect after
+enabling C<text_strings>.
+If C<$enabled> is true (or missing), then C<encode> will encode all perl
+strings as CBOR text strings/UTF-8 strings, upgrading them as needed.
+If C<$enable> is false (the default), then C<encode> will encode strings
+normally (but see C<text_keys>) - upgraded perl strings (strings
+internally encoded as UTF-8) as CBOR text strings, and downgraded perl
+strings as CBOR byte strings.
+This option does not affect C<decode> in any way.
+This option has similar advantages and disadvantages as C<text_keys>. In
+addition, this option effectively removes the ability to encode byte
+strings, which might break some C<FREEZE> and C<TO_CBOR> methods that rely
+on this, such as bignum encoding, so this option is mainly useful for very
+simple data.
 =item $cbor = $cbor->validate_utf8 ([$enable])
 =item $enabled = $cbor->get_validate_utf8
 Resets the incremental decoder. This throws away any saved state, so that
 subsequent calls to C<incr_parse> or C<incr_parse_multiple> start to parse
 a new CBOR value from the beginning of the C<$buffer> again.
-This method can be caled at any time, but it I<must> be called if you want
+This method can be called at any time, but it I<must> be called if you want
 to change your C<$buffer> or there was a decoding error and you want to
 reuse the C<$cbor> object for future incremental parsings.
 =back
    my $x = 3.1; # some variable containing a number
    "$x";        # stringified
    $x .= "";    # another, more awkward way to stringify
    print $x;    # perl does it for you, too, quite often
-You can force whether a string ie encoded as byte or text string by using
+You can force whether a string is encoded as byte or text string by using
-C<utf8::upgrade> and C<utf8::downgrade>):
+C<utf8::upgrade> and C<utf8::downgrade> (if C<text_strings> is disabled):
   utf8::upgrade $x;   # encode $x as text string
   utf8::downgrade $x; # encode $x as byte string
 Perl doesn't define what operations up- and downgrade strings, so if the
 difference between byte and text is important, you should up- or downgrade
-your string as late as possible before encoding.
+your string as late as possible before encoding. You can also force the
+use of CBOR text strings by using C<text_keys> or C<text_strings>.
 You can force the type to be a CBOR number by numifying it:
    my $x = "3"; # some variable containing a string
    $x += 0;     # numify it, ensuring it will be dumped as a number
       "$self" # encode url string
    }
    sub URI::THAW {
       my ($class, $serialiser, $uri) = @_;
       $class->new ($uri)
    }
 Unlike C<TO_CBOR>, multiple values can be returned by C<FREEZE>. For
 example, a C<FREEZE> method that returns "type", "id" and "variant" values
 These tags are decoded into L<Math::BigInt> objects. The corresponding
 C<Math::BigInt::TO_CBOR> method encodes "small" bigints into normal CBOR
 integers, and others into positive/negative CBOR bignums.
-=item 4, 5 (decimal fraction/bigfloat)
+=item 4, 5, 264, 265 (decimal fraction/bigfloat)
 Both decimal fractions and bigfloats are decoded into L<Math::BigFloat>
 objects. The corresponding C<Math::BigFloat::TO_CBOR> method I<always>
-encodes into a decimal fraction.
+encodes into a decimal fraction (either tag 4 or 264).
-CBOR cannot represent bigfloats with I<very> large exponents - conversion
+NaN and infinities are not encoded properly, as they cannot be represented
-of such big float objects is undefined.
+in CBOR.
-Also, NaN and infinities are not encoded properly.
+See L<BIGNUM SECURITY CONSIDERATIONS> for more info.
+=item 30 (rational numbers)
+These tags are decoded into L<Math::BigRat> objects. The corresponding
+C<Math::BigRat::TO_CBOR> method encodes rational numbers with denominator
+C<1> via their numerator only, i.e., they become normal integers or
+C<bignums>.
+See L<BIGNUM SECURITY CONSIDERATIONS> for more info.
 =item 21, 22, 23 (expected later JSON conversion)
 CBOR::XS is not a CBOR-to-JSON converter, and will simply ignore these
 tags.
 First of all, your CBOR decoder should be secure, that is, should not have
 any buffer overflows. Obviously, this module should ensure that and I am
 trying hard on making that true, but you never know.
+Second, CBOR::XS supports object serialisation - decoding CBOR can cause
+calls to I<any> C<THAW> method in I<any> package that exists in your
+process (that is, CBOR::XS will not try to load modules, but any existing
+C<THAW> method or function can be called, so they all have to be secure).
-Second, you need to avoid resource-starving attacks. That means you should
+Third, you need to avoid resource-starving attacks. That means you should
 limit 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, it might be
 too late when you already have it in memory, so you might want to check
 the size before you accept the string.
-Third, CBOR::XS recurses using the C stack when decoding objects and
+Fourth, CBOR::XS recurses using the C stack when decoding objects and
 arrays. The C stack is a limited resource: for instance, on my amd64
 machine with 8MB of stack size I can decode around 180k nested arrays but
 only 14k nested CBOR objects (due to perl itself recursing deeply on croak
 to free the temporary). If that is exceeded, the program crashes. To be
 conservative, the default nesting limit is set to 512. If your process
 Also keep in mind that CBOR::XS might leak contents of your Perl data
 structures in its error messages, so when you serialise sensitive
 information you might want to make sure that exceptions thrown by CBOR::XS
 will not end up in front of untrusted eyes.
+=head1 BIGNUM SECURITY CONSIDERATIONS
+CBOR::XS provides a C<TO_CBOR> method for both L<Math::BigInt> and
+L<Math::BigFloat> that tries to encode the number in the simplest possible
+way, that is, either a CBOR integer, a CBOR bigint/decimal fraction (tag
+4) or an arbitrary-exponent decimal fraction (tag 264). Rational numbers
+(L<Math::BigRat>, tag 30) can also contain bignums as members.
+CBOR::XS will also understand base-2 bigfloat or arbitrary-exponent
+bigfloats (tags 5 and 265), but it will never generate these on its own.
+Using the built-in L<Math::BigInt::Calc> support, encoding and decoding
+decimal fractions is generally fast. Decoding bigints can be slow for very
+big numbers (tens of thousands of digits, something that could potentially
+be caught by limiting the size of CBOR texts), and decoding bigfloats or
+arbitrary-exponent bigfloats can be I<extremely> slow (minutes, decades)
+for large exponents (roughly 40 bit and longer).
+Additionally, L<Math::BigInt> can take advantage of other bignum
+libraries, such as L<Math::GMP>, which cannot handle big floats with large
+exponents, and might simply abort or crash your program, due to their code
+quality.
+This can be a concern if you want to parse untrusted CBOR. If it is, you
+might want to disable decoding of tag 2 (bigint) and 3 (negative bigint)
+types. You should also disable types 5 and 265, as these can be slow even
+without bigints.
+Disabling bigints will also partially or fully disable types that rely on
+them, e.g. rational numbers that use bignums.
 =head1 CBOR IMPLEMENTATION NOTES
 This section contains some random implementation notes. They do not
 describe guaranteed behaviour, but merely behaviour as-is implemented
    4 => sub { # decimal fraction, array
       require Math::BigFloat;
       Math::BigFloat->new ($_[1][1] . "E" . $_[1][0])
    },
+   264 => sub { # decimal fraction with arbitrary exponent
+      require Math::BigFloat;
+      Math::BigFloat->new ($_[1][1] . "E" . $_[1][0])
+   },
    5 => sub { # bigfloat, array
       require Math::BigFloat;
       scalar Math::BigFloat->new ($_[1][1]) * Math::BigFloat->new (2)->bpow ($_[1][0])
+   },
+   265 => sub { # bigfloat with arbitrary exponent
+      require Math::BigFloat;
+      scalar Math::BigFloat->new ($_[1][1]) * Math::BigFloat->new (2)->bpow ($_[1][0])
+   },
+   30 => sub { # rational number
+      require Math::BigRat;
+      Math::BigRat->new ("$_[1][0]/$_[1][1]") # separate parameters only work in recent versons
    },
    21 => sub { pop }, # expected conversion to base64url encoding
    22 => sub { pop }, # expected conversion to base64 encoding
    23 => sub { pop }, # expected conversion to base16 encoding
    utf8::upgrade $uri;
    tag 32, $uri
 }
 sub Math::BigInt::TO_CBOR {
-   if ($_[0] >= -2147483648 && $_[0] <= 2147483647) {
+   if (-2147483648 <= $_[0] && $_[0] <= 2147483647) {
       $_[0]->numify
    } else {
       my $hex = substr $_[0]->as_hex, 2;
       $hex = "0$hex" if 1 & length $hex; # sigh
       tag $_[0] >= 0 ? 2 : 3, pack "H*", $hex
    }
 }
 sub Math::BigFloat::TO_CBOR {
    my ($m, $e) = $_[0]->parts;
+   -9223372036854775808 <= $e && $e <= 18446744073709551615
-   tag 4, [$e->numify, $m]
+      ? tag 4, [$e->numify, $m]
+      : tag 264, [$e, $m]
+}
+sub Math::BigRat::TO_CBOR {
+   my ($n, $d) = $_[0]->parts;
+   # older versions of BigRat need *1, as they not always return numbers
+   $d*1 == 1
+      ? $n*1
+      : tag 30, [$n*1, $d*1]
 }
 sub Time::Piece::TO_CBOR {
    tag 1, 0 + $_[0]->epoch
 }

Diff Legend

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

Comparing CBOR-XS/XS.pm (file contents): Revision 1.51 by root, Sun Apr 24 19:16:15 2016 UTC vs. Revision 1.63 by root, Fri Nov 25 12:16:12 2016 UTC

Diff Legend

Comparing CBOR-XS/XS.pm (file contents):
Revision 1.51 by root, Sun Apr 24 19:16:15 2016 UTC vs.
Revision 1.63 by root, Fri Nov 25 12:16:12 2016 UTC