view release on metacpan or  search on metacpan

README  view on Meta::CPAN

        Not all shared values can be successfully decoded: values that
        reference themselves will *currently* decode as "undef" (this is not
        the same as a reference pointing to itself, which will be
        represented as a value that contains an indirect reference to itself
        - these will be decoded properly).

        Note that considerably more shared value data structures can be
        decoded than will be encoded - currently, only values pointed to by
        references 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.

    256, 25 (stringref-namespace, stringref,
    <http://cbor.schmorp.de/stringref>)
        These tags are automatically decoded when encountered. They are only
        encoded, however, when "pack_strings" is enabled.

    22098 (indirection, <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.

    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.

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

    When they result in decoding into a specific Perl class, the module
    usually provides a corresponding "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. 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.

    0, 1 (date/time string, seconds since the epoch)
        These tags are decoded into Time::Piece objects. The corresponding
        "Time::Piece::TO_CBOR" method always encodes into tag 1 values
        currently.

        The 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.

    2, 3 (positive/negative bignum)
        These tags are decoded into Math::BigInt objects. The corresponding
        "Math::BigInt::TO_CBOR" method encodes "small" bigints into normal
        CBOR integers, and others into positive/negative CBOR bignums.

    4, 5, 264, 265 (decimal fraction/bigfloat)
        Both decimal fractions and bigfloats are decoded into Math::BigFloat
        objects. The corresponding "Math::BigFloat::TO_CBOR" method *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 "BIGNUM SECURITY CONSIDERATIONS" for more info.

    30 (rational numbers)
        These tags are decoded into Math::BigRat objects. The corresponding
        "Math::BigRat::TO_CBOR" method encodes rational numbers with
        denominator 1 via their numerator only, i.e., they become normal
        integers or "bignums".

        See "BIGNUM SECURITY CONSIDERATIONS" for more info.

    21, 22, 23 (expected later JSON conversion)
        CBOR::XS is not a CBOR-to-JSON converter, and will simply ignore
        these tags.

    32 (URI)
        These objects decode into URI objects. The corresponding
        "URI::TO_CBOR" method again results in a CBOR URI value.

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.

SECURITY CONSIDERATIONS
    Tl;dr... if you want to decode or encode CBOR from untrusted sources,
    you should start with a coder object created via "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:

    Security of the CBOR decoder itself
        First and foremost, your CBOR decoder should be secure, that is,
        should not have any buffer overflows or similar bugs that could
        potentially be exploited. Obviously, this module should ensure that
        and I am trying hard on making that true, but you never know.

    CBOR::XS can invoke almost arbitrary callbacks during decoding
        CBOR::XS supports object serialisation - decoding CBOR can cause
        calls to *any* "THAW" method in *any* package that exists in your
        process (that is, CBOR::XS will not try to load modules, but any
        existing "THAW" method or function can be called, so they all have
        to be secure).

        Less obviously, it will also invoke "TO_CBOR" and "FREEZE" methods -