view release on metacpan or  search on metacpan

XS.pm  view on Meta::CPAN

will be shared, others will not. While non-reference shared values can be
generated in Perl with some effort, they were considered too unimportant
to be supported in the encoder. The decoder, however, will decode these
values as shared values.

=item 256, 25 (stringref-namespace, stringref, L<http://cbor.schmorp.de/stringref>)

These tags are automatically decoded when encountered. They are only
encoded, however, when C<pack_strings> is enabled.

=item 22098 (indirection, L<http://cbor.schmorp.de/indirection>)

This tag is automatically generated when a reference are encountered (with
the exception of hash and array references). It is converted to a reference
when decoding.

=item 55799 (self-describe CBOR, RFC 7049)

This value is not generated on encoding (unless explicitly requested by
the user), and is simply ignored when decoding.

=back

=head2 NON-ENFORCED TAGS

These tags have default filters provided when decoding. Their handling can
be overridden by changing the C<%CBOR::XS::FILTER> entry for the tag, or by
providing a custom C<filter> callback when decoding.

When they result in decoding into a specific Perl class, the module
usually provides a corresponding C<TO_CBOR> method as well.

When any of these need to load additional modules that are not part of the
perl core distribution (e.g. L<URI>), it is (currently) up to the user to
provide these modules. The decoding usually fails with an exception if the
required module cannot be loaded.

=over 4

=item 0, 1 (date/time string, seconds since the epoch)

These tags are decoded into L<Time::Piece> objects. The corresponding
C<Time::Piece::TO_CBOR> method always encodes into tag 1 values currently.

The L<Time::Piece> API is generally surprisingly bad, and fractional
seconds are only accidentally kept intact, so watch out. On the plus side,
the module comes with perl since 5.10, which has to count for something.

=item 2, 3 (positive/negative bignum)

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, 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 (either tag 4 or 264).

NaN and infinities are not encoded properly, as they cannot be represented
in CBOR.

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.

=item 32 (URI)

These objects decode into L<URI> objects. The corresponding
C<URI::TO_CBOR> method again results in a CBOR URI value.

=back

=cut

=head1 CBOR and JSON

CBOR is supposed to implement a superset of the JSON data model, and is,
with some coercion, able to represent all JSON texts (something that other
"binary JSON" formats such as BSON generally do not support).

CBOR implements some extra hints and support for JSON interoperability,
and the spec offers further guidance for conversion between CBOR and
JSON. None of this is currently implemented in CBOR, and the guidelines
in the spec do not result in correct round-tripping of data. If JSON
interoperability is improved in the future, then the goal will be to
ensure that decoded JSON data will round-trip encoding and decoding to
CBOR intact.


=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> (which implements
the mitigations explained below):

   my $coder = CBOR::XS->new_safe;

   my $data = $coder->decode ($cbor_text);
   my $cbor = $coder->encode ($data);

Longer version: When you are using CBOR in a protocol, talking to
untrusted potentially hostile creatures requires some thought:

=over 4

=item Security of the CBOR decoder itself