cbor

README

CBOR library in Go

fxamacker/cbor is a CBOR encoder & decoder in Go. It has a standard API, CBOR tags, options for duplicate map keys, float64→32→16, toarray, keyasint, etc. Each release passes 375+ tests and 250+ million execs fuzzing.

What is CBOR? CBOR (RFC 7049) is a binary data format inspired by JSON and MessagePack. CBOR is used in IETF Internet Standards such as COSE (RFC 8152) and CWT (RFC 8392 CBOR Web Token). WebAuthn also uses CBOR.

fxamacker/cbor is safe and fast. It safely handles malformed CBOR data:

fxamacker/cbor is fast when using CBOR data with Go structs:

Benchmarks used data from RFC 8392 Appendix A.1 and default options for each CBOR library.

fxamacker/cbor produces smaller binaries. All builds of cisco/senml had MessagePack feature removed:

---

Standard API: functions with signatures identical to encoding/json include:
Marshal, Unmarshal, NewEncoder, NewDecoder, encoder.Encode, and decoder.Decode.

Standard interfaces allow custom encoding or decoding:
BinaryMarshaler, BinaryUnmarshaler, Marshaler, and Unmarshaler.

Struct tags like toarray & keyasint translate Go struct fields to CBOR array elements, etc.

---

fxamacker/cbor is a full-featured CBOR encoder and decoder. Support for CBOR includes:

---

⚓ Installation • System Requirements • Quick Start Guide

---

Why this CBOR library? It doesn't crash and it has well-balanced qualities: small, fast, safe and easy. It also has a standard API, CBOR tags (built-in and user-defined), float64→32→16, and duplicate map key options.

• Standard API. Codec functions with signatures identical to encoding/json include:
  Marshal, Unmarshal, NewEncoder, NewDecoder, encoder.Encode, and decoder.Decode.

• Customizable. Standard interfaces are provided to allow user-implemented encoding or decoding:
  BinaryMarshaler, BinaryUnmarshaler, Marshaler, and Unmarshaler.

• Small apps. Same programs are 4-9 MB smaller by switching to this library. No code gen and the only imported pkg is x448/float16 which is maintained by the same team as this library.

• Small data. The toarray, keyasint, and omitempty struct tags shrink size of Go structs encoded to CBOR. Integers encode to smallest form that fits. Floats can shrink from float64 -> float32 -> float16 if values fit.

• Fast. v1.3 became faster than a well-known library that uses unsafe optimizations and code gen. Faster libraries will always exist, but speed is only one factor. This library doesn't use unsafe optimizations or code gen.

• Safe and reliable. It prevents crashes on malicious CBOR data by using extensive tests, coverage-guided fuzzing, data validation, and avoiding Go's unsafe pkg. Decoder settings include: MaxNestedLevels, MaxArrayElements, MaxMapPairs, and IndefLength.

• Easy and saves time. Simple (no param) functions return preset EncOptions so you don't have to know the differences between Canonical CBOR and CTAP2 Canonical CBOR to use those standards.

💡 Struct tags are a Go language feature. CBOR tags relate to a CBOR data type (major type 6).

Struct tags for CBOR and JSON like `cbor:"name,omitempty"` and `json:"name,omitempty"` are supported so you can leverage your existing code. If both cbor: and json: tags exist then it will use cbor:.

New struct tags like keyasint and toarray make compact CBOR data such as COSE, CWT, and SenML easier to use.

⚓ Quick Start • Status • Design Goals • Features • Standards • API • Usage • Fuzzing • Security Policy • License

Installation

👉 If Go modules aren't used, delete or modify example_test.go
from "github.com/fxamacker/cbor/v2" to "github.com/fxamacker/cbor"

Using Go modules is recommended.

$ GO111MODULE=on go get github.com/fxamacker/cbor/v2

import (
	"github.com/fxamacker/cbor/v2" // imports as package "cbor"
)

Released versions benefit from longer fuzz tests.

System Requirements

Using Go modules is recommended but not required.

• Go 1.12 (or newer).
• amd64, arm64, ppc64le and s390x. Other architectures may also work but they are not tested as frequently.

If Go modules feature isn't used, please see Installation about deleting or modifying example_test.go.

Quick Start

🛡️ Use Go's io.LimitReader to limit size when decoding very large or indefinite size data.

Functions with identical signatures to encoding/json include:
Marshal, Unmarshal, NewEncoder, NewDecoder, encoder.Encode, decoder.Decode.

Default Mode

If default options are acceptable, package level functions can be used for encoding and decoding.

b, err := cbor.Marshal(v)        // encode v to []byte b

err := cbor.Unmarshal(b, &v)     // decode []byte b to v

encoder := cbor.NewEncoder(w)    // create encoder with io.Writer w

decoder := cbor.NewDecoder(r)    // create decoder with io.Reader r

Modes

If you need to use options or CBOR tags, then you'll want to create a mode.

"Mode" means defined way of encoding or decoding -- it links the standard API to your CBOR options and CBOR tags. This way, you don't pass around options and the API remains identical to encoding/json.

EncMode and DecMode are interfaces created from EncOptions or DecOptions structs.
For example, em, err := cbor.EncOptions{...}.EncMode() or em, err := cbor.CanonicalEncOptions().EncMode().

EncMode and DecMode use immutable options so their behavior won't accidentally change at runtime. Modes are reusable, safe for concurrent use, and allow fast parallelism.

Creating and Using Encoding Modes

💡 Avoid using init(). For best performance, reuse EncMode and DecMode after creating them.

Most apps will probably create one EncMode and DecMode before init(). However, there's no limit and each can use different options.

// Create EncOptions using either struct literal or a function.
opts := cbor.CanonicalEncOptions()

// If needed, modify opts. For example: opts.Time = cbor.TimeUnix

// Create reusable EncMode interface with immutable options, safe for concurrent use.
em, err := opts.EncMode()   

// Use EncMode like encoding/json, with same function signatures.
b, err := em.Marshal(v)      // encode v to []byte b

encoder := em.NewEncoder(w)  // create encoder with io.Writer w
err := encoder.Encode(v)     // encode v to io.Writer w

Creating Modes With CBOR Tags

A TagSet is used to specify CBOR tags.

em, err := opts.EncMode()                  // no tags
em, err := opts.EncModeWithTags(ts)        // immutable tags
em, err := opts.EncModeWithSharedTags(ts)  // mutable shared tags

TagSet and all modes using it are safe for concurrent use. Equivalent API is available for DecMode.

Predefined Encoding Options

func CanonicalEncOptions() EncOptions {}            // settings for RFC 7049 Canonical CBOR
func CTAP2EncOptions() EncOptions {}                // settings for FIDO2 CTAP2 Canonical CBOR
func CoreDetEncOptions() EncOptions {}              // settings from a draft RFC (subject to change)
func PreferredUnsortedEncOptions() EncOptions {}    // settings from a draft RFC (subject to change)

The empty curly braces prevent a syntax highlighting bug on GitHub, please ignore them.

Struct Tags (keyasint, toarray, omitempty)

The keyasint, toarray, and omitempty struct tags make it easy to use compact CBOR message formats. Internet standards often use CBOR arrays and CBOR maps with int keys to save space.

More Info About API, Options, and Usage

Options are listed in the Features section: Encoding Options and Decoding Options

For more details about each setting, see Options section.

For additional API and usage examples, see API and Usage sections.

---

⚓ Install • Status • Design Goals • Features • Standards • API • Usage • Fuzzing • Security Policy • License

Current Status

Latest version is v2.x, which has:

• Stable API – Six codec function signatures will never change. No breaking API changes for other funcs in same major version. And these two functions are subject to change until the draft RFC is approved by IETF (est. in 2020):
  • CoreDetEncOptions() is subject to change because it uses draft standard.
  • PreferredUnsortedEncOptions() is subject to change because it uses draft standard.
• Passed all tests – v2.x passed all 375+ tests on amd64, arm64, ppc64le and s390x with linux.
• Passed fuzzing – v2.2 passed 459+ million execs in coverage-guided fuzzing on Feb 24, 2020 (still fuzzing.)

Why v2.x?:

v1 required breaking API changes to support new features like CBOR tags, detection of duplicate map keys, and having more functions with identical signatures to encoding/json.

v2.1 is roughly 26% faster and uses 57% fewer allocs than v1.x when decoding COSE and CWT using default options.

Recent Activity:

• Release v2.1 (Feb. 17, 2020)

  • CBOR tags (major type 6) for encoding and decoding.
  • Decoding options for duplicate map key detection: DupMapKeyQuiet (default) and DupMapKeyEnforcedAPF
  • Decoding optimizations. Structs using keyasint tag (like COSE and CWT) is
    24-28% faster and 53-61% fewer allocs than both v1.5 and v2.0.1.

• Release v2.2 (Feb. 24, 2020)

  • CBOR BSTR <--> Go byte array (byte slices were already supported)
  • Add more encoding and decoding options (MaxNestedLevels, MaxArrayElements, MaxMapKeyPairs, TagsMd, etc.)
  • Fix potential error when decoding shorter CBOR indef length array to Go array (slice wasn't affected). This bug affects all prior versions of 1.x and 2.x.

---

⚓ Install • Status • Design Goals • Features • Standards • API • Usage • Fuzzing • Security Policy • License

Design Goals

This library is designed to be a generic CBOR encoder and decoder. It was initially created for a WebAuthn (FIDO2) server library, because existing CBOR libraries (in Go) didn't meet certain criteria in 2019.

This library is designed to be:

• Easy – API is like encoding/json plus keyasint and toarray struct tags.
• Small – Programs in cisco/senml are 4 MB smaller by switching to this library. In extreme cases programs can be smaller by 9+ MB. No code gen and the only imported pkg is x448/float16 which is maintained by the same team.
• Safe and reliable – No unsafe pkg, coverage >95%, coverage-guided fuzzing, and data validation to avoid crashes on malformed or malicious data. Decoder settings include: MaxNestedLevels, MaxArrayElements, MaxMapPairs, and IndefLength.

Avoiding unsafe package has benefits. The unsafe package warns:

Packages that import unsafe may be non-portable and are not protected by the Go 1 compatibility guidelines.

All releases prioritize reliability to avoid crashes on decoding malformed CBOR data. See Fuzzing and Coverage.

Competing factors are balanced:

• Speed vs safety vs size – to keep size small, avoid code generation. For safety, validate data and avoid Go's unsafe pkg. For speed, use safe optimizations such as caching struct metadata. This library is faster than a well-known library that uses unsafe and code gen.
• Standards compliance vs size – Supports CBOR RFC 7049 with minor limitations. To limit bloat, CBOR tags are supported but not all tags are built-in. The API allows users to add tags that aren't built-in. The API also allows custom encoding and decoding of user-defined Go types.

Click to expand topic:

Supported CBOR Features (Highlights)

v2.0 API Design

v2.0 decoupled options from CBOR encoding & decoding functions:

• More encoding/decoding function signatures are identical to encoding/json.
• More function signatures can remain stable forever.
• More flexibility for evolving internal data types, optimizations, and concurrency.
• Features like CBOR tags can be added without more breaking API changes.
• Options to handle duplicate map keys can be added without more breaking API changes.

Features not in Go's standard library are usually not added. However, the toarray struct tag in ugorji/go was too useful to ignore. It was added in v1.3 when a project mentioned they were using it with CBOR to save disk space.

---

⚓ Install • Status • Design Goals • Features • Standards • API • Usage • Fuzzing • Security Policy • License

Features

Standard API

Many function signatures are identical to encoding/json, including:
Marshal, Unmarshal, NewEncoder, NewDecoder, encoder.Encode, decoder.Decode.

RawMessage can be used to delay CBOR decoding or precompute CBOR encoding, like encoding/json.

Standard interfaces allow user-defined types to have custom CBOR encoding and decoding. They include:
BinaryMarshaler, BinaryUnmarshaler, Marshaler, and Unmarshaler.

Marshaler and Unmarshaler interfaces are satisfied by MarshalCBOR and UnmarshalCBOR functions using same params and return types as Go's MarshalJSON and UnmarshalJSON.

Struct Tags

Support "cbor" and "json" keys in Go's struct tags. If both are specified, then "cbor" is used.

• toarray struct tag allows named struct fields for elements of CBOR arrays.
• keyasint struct tag allows named struct fields for elements of CBOR maps with int keys.
• omitempty struct tag excludes empty field values from being encoded.

See Usage.

CBOR Tags (New in v2.1)

There are three broad categories of CBOR tags:

• Default built-in CBOR tags currently include tag numbers 0 and 1 (Time). Additional default built-in tags in future releases may include tag numbers 2 and 3 (Bignum).

• Optional built-in CBOR tags may be provided in the future via build flags or optional package(s) to help reduce bloat.

• User-defined CBOR tags are easy by using TagSet to associate tag numbers to user-defined Go types.

Preferred Serialization

Preferred serialization encodes integers and floating-point values using the fewest bytes possible.

• Integers are always encoded using the fewest bytes possible.
• Floating-point values can optionally encode from float64->float32->float16 when values fit.

Compact Data Size

The combination of preferred serialization and struct tags (toarray, keyasint, omitempty) allows very compact data size.

Predefined Encoding Options

Easy-to-use functions (no params) return preset EncOptions struct:
CanonicalEncOptions, CTAP2EncOptions, CoreDetEncOptions, PreferredUnsortedEncOptions

Encoding Options

Integers always encode to the shortest form that preserves value. By default, time values are encoded without tags.

Encoding of other data types and map key sort order are determined by encoder options.

Encoding Option	Available Settings (defaults in bold, aliases in italics)
EncOptions.Sort	SortNone, SortLengthFirst, SortBytewiseLexical, SortCanonical, SortCTAP2, SortCoreDeterministic
EncOptions.Time	TimeUnix, TimeUnixMicro, TimeUnixDynamic, TimeRFC3339, TimeRFC3339Nano
EncOptions.TimeTag	EncTagNone, EncTagRequired
EncOptions.ShortestFloat	ShortestFloatNone, ShortestFloat16
EncOptions.InfConvert	InfConvertFloat16, InfConvertNone
EncOptions.NaNConvert	NaNConvert7e00, NaNConvertNone, NaNConvertQuiet, NaNConvertPreserveSignal
EncOptions.IndefLength	IndefLengthAllowed, IndefLengthForbidden
EncOptions.TagsMd	TagsAllowed, TagsForbidden

See Options section for details about each setting.

Decoding Options

Decoding Option	Available Settings (defaults in bold, aliases in italics)
DecOptions.TimeTag	DecTagIgnored, DecTagOptional, DecTagRequired
DecOptions.DupMapKey	DupMapKeyQuiet, DupMapKeyEnforcedAPF
DecOptions.IndefLength	IndefLengthAllowed, IndefLengthForbidden
DecOptions.TagsMd	TagsAllowed, TagsForbidden
DecOptions.MaxNestedLevels	32, can be set to [4, 256]
DecOptions.MaxArrayElements	131072, can be set to [16, 134217728]
DecOptions.MaxMapPairs	131072, can be set to [16, 134217728]

See Options section for details about each setting.

Additional Features

• Decoder always checks for invalid UTF-8 string errors.
• Decoder always decodes in-place to slices, maps, and structs.
• Decoder tries case-sensitive first and falls back to case-insensitive field name match when decoding to structs.
• Both encoder and decoder support indefinite length CBOR data ("streaming").
• Both encoder and decoder correctly handles nil slice, map, pointer, and interface values.

---

⚓ Install • Status • Design Goals • Features • Standards • API • Usage • Fuzzing • Security Policy • License

Standards

This library is a full-featured generic CBOR (RFC 7049) encoder and decoder. Notable CBOR features include:

See the Features section for list of Encoding Options and Decoding Options.

Known limitations are noted in the Limitations section.

Go nil values for slices, maps, pointers, etc. are encoded as CBOR null. Empty slices, maps, etc. are encoded as empty CBOR arrays and maps.

Decoder checks for all required well-formedness errors, including all "subkinds" of syntax errors and too little data.

After well-formedness is verified, basic validity errors are handled as follows:

• Invalid UTF-8 string: Decoder always checks and returns invalid UTF-8 string error.
• Duplicate keys in a map: Decoder has options to ignore or enforce rejection of duplicate map keys.

When decoding well-formed CBOR arrays and maps, decoder saves the first error it encounters and continues with the next item. Options to handle this differently may be added in the future.

See Options section for detailed settings or Features section for a summary of options.

Click to expand topic:

Duplicate Map Keys

This library provides options for fast detection and rejection of duplicate map keys based on applying a Go-specific data model to CBOR's extended generic data model in order to determine duplicate vs distinct map keys. Detection relies on whether the CBOR map key would be a duplicate "key" when decoded and applied to the user-provided Go map or struct.

DupMapKeyQuiet turns off detection of duplicate map keys. It tries to use a "keep fastest" method by choosing either "keep first" or "keep last" depending on the Go data type.

DupMapKeyEnforcedAPF enforces detection and rejection of duplidate map keys. Decoding stops immediately and returns DupMapKeyError when the first duplicate key is detected. The error includes the duplicate map key and the index number.

APF suffix means "Allow Partial Fill" so the destination map or struct can contain some decoded values at the time of error. It is the caller's responsibility to respond to the DupMapKeyError by discarding the partially filled result if that's required by their protocol.

Limitations

If any of these limitations prevent you from using this library, please open an issue along with a link to your project.

• CBOR negative int (type 1) that cannot fit into Go's int64 are not supported, such as RFC 7049 example -18446744073709551616. Decoding these values returns cbor.UnmarshalTypeError like Go's encoding/json. However, this may be resolved in a future release by adding support for big.Int. Until then, users can use the API for custom encoding and decoding.
• CBOR Undefined (0xf7) value decodes to Go's nil value. CBOR Null (0xf6) more closely matches Go's nil.
• CBOR map keys with data types not supported by Go for map keys are ignored and an error is returned after continuing to decode remaining items.
• When using io.Reader interface to read very large or indefinite length CBOR data, Go's io.LimitReader should be used to limit size.

---

⚓ Install • Status • Design Goals • Features • Standards • API • Usage • Fuzzing • Security Policy • License

API

Many function signatures are identical to Go's encoding/json, such as:
Marshal, Unmarshal, NewEncoder, NewDecoder, encoder.Encode, and decoder.Decode.

Interfaces identical or comparable to Go's encoding, encoding/json, or encoding/gob include:
Marshaler, Unmarshaler, BinaryMarshaler, and BinaryUnmarshaler.

Like encoding/json, RawMessage can be used to delay CBOR decoding or precompute CBOR encoding.

"Mode" in this API means defined way of encoding or decoding -- it links the standard API to CBOR options and CBOR tags.

EncMode and DecMode are interfaces created from EncOptions or DecOptions structs.
For example, em, err := cbor.EncOptions{...}.EncMode() or em, err := cbor.CanonicalEncOptions().EncMode().

EncMode and DecMode use immutable options so their behavior won't accidentally change at runtime. Modes are intended to be reused and are safe for concurrent use.

API for Default Mode

If default options are acceptable, then you don't need to create EncMode or DecMode.

Marshal(v interface{}) ([]byte, error)
NewEncoder(w io.Writer) *Encoder

Unmarshal(data []byte, v interface{}) error
NewDecoder(r io.Reader) *Decoder

API for Creating & Using Encoding Modes

// EncMode interface uses immutable options and is safe for concurrent use.
type EncMode interface {
	Marshal(v interface{}) ([]byte, error)
	NewEncoder(w io.Writer) *Encoder
	EncOptions() EncOptions  // returns copy of options
}

// EncOptions specifies encoding options.
type EncOptions struct {
...
}

// EncMode returns an EncMode interface created from EncOptions.
func (opts EncOptions) EncMode() (EncMode, error) {}

// EncModeWithTags returns EncMode with options and tags that are both immutable. 
func (opts EncOptions) EncModeWithTags(tags TagSet) (EncMode, error) {}

// EncModeWithSharedTags returns EncMode with immutable options and mutable shared tags. 
func (opts EncOptions) EncModeWithSharedTags(tags TagSet) (EncMode, error) {}

The empty curly braces prevent a syntax highlighting bug, please ignore them.

API for Predefined Encoding Options

func CanonicalEncOptions() EncOptions {}            // settings for RFC 7049 Canonical CBOR
func CTAP2EncOptions() EncOptions {}                // settings for FIDO2 CTAP2 Canonical CBOR
func CoreDetEncOptions() EncOptions {}              // settings from a draft RFC (subject to change)
func PreferredUnsortedEncOptions() EncOptions {}    // settings from a draft RFC (subject to change)

API for Creating & Using Decoding Modes

// DecMode interface uses immutable options and is safe for concurrent use.
type DecMode interface {
	Unmarshal(data []byte, v interface{}) error
	NewDecoder(r io.Reader) *Decoder
	DecOptions() DecOptions  // returns copy of options
}

// DecOptions specifies decoding options.
type DecOptions struct {
...
}

// DecMode returns a DecMode interface created from DecOptions.
func (opts DecOptions) DecMode() (DecMode, error) {}

// DecModeWithTags returns DecMode with options and tags that are both immutable. 
func (opts DecOptions) DecModeWithTags(tags TagSet) (DecMode, error) {}

// DecModeWithSharedTags returns DecMode with immutable options and mutable shared tags. 
func (opts DecOptions) DecModeWithSharedTags(tags TagSet) (DecMode, error) {}

The empty curly braces prevent a syntax highlighting bug, please ignore them.

API for Using CBOR Tags

TagSet can be used to associate user-defined Go type(s) to tag number(s). It's also used to create EncMode or DecMode. For example, em := EncOptions{...}.EncModeWithTags(ts) or em := EncOptions{...}.EncModeWithSharedTags(ts). This allows every standard API exported by em (like Marshal and NewEncoder) to use the specified tags automatically.

Tag and RawTag can be used to encode/decode a tag number with a Go value, but TagSet is generally recommended.

type TagSet interface {
    // Add adds given tag number(s), content type, and tag options to TagSet.
    Add(opts TagOptions, contentType reflect.Type, num uint64, nestedNum ...uint64) error

    // Remove removes given tag content type from TagSet.
    Remove(contentType reflect.Type)    
}

Tag and RawTag types can also be used to encode/decode tag number with Go value.

type Tag struct {
    Number  uint64
    Content interface{}
}

type RawTag struct {
    Number  uint64
    Content RawMessage
}

See API docs (godoc.org) for more details and more functions. See Usage section for usage and code examples.

---

⚓ Install • Status • Design Goals • Features • Standards • API • Usage • Fuzzing • Security Policy • License

Options

Options for the decoding and encoding are listed here.

Decoding Options

DecOptions.TimeTag	Description
DecTagIgnored (default)	Tag numbers are ignored (if present) for time values.
DecTagOptional	Tag numbers are only checked for validity if present for time values.
DecTagRequired	Tag numbers must be provided for time values except for CBOR Null and CBOR Undefined.

CBOR Null and CBOR Undefined are silently treated as Go's zero time instant. Go's time package provides IsZero function, which reports whether t represents the zero time instant, January 1, year 1, 00:00:00 UTC.

DecOptions.DupMapKey	Description
DupMapKeyQuiet (default)	turns off detection of duplicate map keys. It uses a "keep fastest" method by choosing either "keep first" or "keep last" depending on the Go data type.
DupMapKeyEnforcedAPF	enforces detection and rejection of duplidate map keys. Decoding stops immediately and returns DupMapKeyError when the first duplicate key is detected. The error includes the duplicate map key and the index number.

DupMapKeyEnforcedAPF uses "Allow Partial Fill" so the destination map or struct can contain some decoded values at the time of error. Users can respond to the DupMapKeyError by discarding the partially filled result if that's required by their protocol.

DecOptions.IndefLength	Description
IndefLengthAllowed (default)	allow indefinite length data
IndefLengthForbidden	forbid indefinite length data

DecOptions.TagsMd	Description
TagsAllowed (default)	allow CBOR tags (major type 6)
TagsForbidden	forbid CBOR tags (major type 6)

DecOptions.MaxNestedLevels	Description
32 (default)	allowed setting is [4, 256]

DecOptions.MaxArrayElements	Description
131072 (default)	allowed setting is [16, 134217728]

DecOptions.MaxMapPairs	Description
131072 (default)	allowed setting is [16, 134217728]

Encoding Options

Integers always encode to the shortest form that preserves value. Encoding of other data types and map key sort order are determined by encoding options.

These functions are provided to create and return a modifiable EncOptions struct with predefined settings.

Predefined EncOptions	Description
CanonicalEncOptions()	Canonical CBOR (RFC 7049 Section 3.9).
CTAP2EncOptions()	CTAP2 Canonical CBOR (FIDO2 CTAP2).
PreferredUnsortedEncOptions()	Unsorted, encode float64->float32->float16 when values fit, NaN values encoded as float16 0x7e00.
CoreDetEncOptions()	PreferredUnsortedEncOptions() + map keys are sorted bytewise lexicographic.

🌱 CoreDetEncOptions() and PreferredUnsortedEncOptions() are subject to change until the draft RFC they used is approved by IETF.

EncOptions.Sort	Description
SortNone (default)	No sorting for map keys.
SortLengthFirst	Length-first map key ordering.
SortBytewiseLexical	Bytewise lexicographic map key ordering
SortCanonical	(alias) Same as SortLengthFirst (RFC 7049 Section 3.9)
SortCTAP2	(alias) Same as SortBytewiseLexical (CTAP2 Canonical CBOR).
SortCoreDeterministic	(alias) Same as SortBytewiseLexical.

EncOptions.Time	Description
TimeUnix (default)	(seconds) Encode as integer.
TimeUnixMicro	(microseconds) Encode as floating-point. ShortestFloat option determines size.
TimeUnixDynamic	(seconds or microseconds) Encode as integer if time doesn't have fractional seconds, otherwise encode as floating-point rounded to microseconds.
TimeRFC3339	(seconds) Encode as RFC 3339 formatted string.
TimeRFC3339Nano	(nanoseconds) Encode as RFC3339 formatted string.

EncOptions.TimeTag	Description
EncTagNone (default)	Tag number will not be encoded for time values.
EncTagRequired	Tag number (0 or 1) will be encoded unless time value is undefined/zero-instant.

Undefined Time Values

By default, undefined (zero instant) time values will encode as CBOR Null without tag number for both EncTagNone and EncTagRequired. Although CBOR Undefined might be technically more correct for EncTagRequired, CBOR Undefined might not be supported by other generic decoders and it isn't supported by JSON.

Go's time package provides IsZero function, which reports whether t represents the zero time instant, January 1, year 1, 00:00:00 UTC.

Floating-Point Options

Encoder has 3 types of options for floating-point data: ShortestFloatMode, InfConvertMode, and NaNConvertMode.

EncOptions.ShortestFloat	Description
ShortestFloatNone (default)	No size conversion. Encode float32 and float64 to CBOR floating-point of same bit-size.
ShortestFloat16	Encode float64 -> float32 -> float16 (IEEE 754 binary16) when values fit.

Conversions for infinity and NaN use InfConvert and NaNConvert settings.

EncOptions.InfConvert	Description
InfConvertFloat16 (default)	Convert +- infinity to float16 since they always preserve value (recommended)
InfConvertNone	Don't convert +- infinity to other representations -- used by CTAP2 Canonical CBOR

EncOptions.NaNConvert	Description
NaNConvert7e00 (default)	Encode to 0xf97e00 (CBOR float16 = 0x7e00) -- used by RFC 7049 Canonical CBOR.
NaNConvertNone	Don't convert NaN to other representations -- used by CTAP2 Canonical CBOR.
NaNConvertQuiet	Force quiet bit = 1 and use shortest form that preserves NaN payload.
NaNConvertPreserveSignal	Convert to smallest form that preserves value (quit bit unmodified and NaN payload preserved).

EncOptions.IndefLength	Description
IndefLengthAllowed (default)	allow indefinite length data
IndefLengthForbidden	forbid indefinite length data

EncOptions.TagsMd	Description
TagsAllowed (default)	allow CBOR tags (major type 6)
TagsForbidden	forbid CBOR tags (major type 6)

---

⚓ Install • Status • Design Goals • Features • Standards • API • Usage • Fuzzing • Security Policy • License

Usage

🛡️ Use Go's io.LimitReader to limit size when decoding very large or indefinite size data.

Functions with identical signatures to encoding/json include:
Marshal, Unmarshal, NewEncoder, NewDecoder, encoder.Encode, decoder.Decode.

Default Mode

If default options are acceptable, package level functions can be used for encoding and decoding.

b, err := cbor.Marshal(v)        // encode v to []byte b

err := cbor.Unmarshal(b, &v)     // decode []byte b to v

encoder := cbor.NewEncoder(w)    // create encoder with io.Writer w

decoder := cbor.NewDecoder(r)    // create decoder with io.Reader r

Modes

If you need to use options or CBOR tags, then you'll want to create a mode.

"Mode" means defined way of encoding or decoding -- it links the standard API to your CBOR options and CBOR tags. This way, you don't pass around options and the API remains identical to encoding/json.

EncMode and DecMode are interfaces created from EncOptions or DecOptions structs.
For example, em, err := cbor.EncOptions{...}.EncMode() or em, err := cbor.CanonicalEncOptions().EncMode().

EncMode and DecMode use immutable options so their behavior won't accidentally change at runtime. Modes are reusable, safe for concurrent use, and allow fast parallelism.

Creating and Using Encoding Modes

EncMode is an interface (API) created from EncOptions struct. EncMode uses immutable options after being created and is safe for concurrent use. For best performance, EncMode should be reused.

// Create EncOptions using either struct literal or a function.
opts := cbor.CanonicalEncOptions()

// If needed, modify opts. For example: opts.Time = cbor.TimeUnix

// Create reusable EncMode interface with immutable options, safe for concurrent use.
em, err := opts.EncMode()   

// Use EncMode like encoding/json, with same function signatures.
b, err := em.Marshal(v)      // encode v to []byte b

encoder := em.NewEncoder(w)  // create encoder with io.Writer w
err := encoder.Encode(v)     // encode v to io.Writer w

Struct Tags (keyasint, toarray, omitempty)

The keyasint, toarray, and omitempty struct tags make it easy to use compact CBOR message formats. Internet standards often use CBOR arrays and CBOR maps with int keys to save space.

---

---

Decoding CWT (CBOR Web Token) using keyasint and toarray struct tags:

// Signed CWT is defined in RFC 8392
type signedCWT struct {
	_           struct{} `cbor:",toarray"`
	Protected   []byte
	Unprotected coseHeader
	Payload     []byte
	Signature   []byte
}

// Part of COSE header definition
type coseHeader struct {
	Alg int    `cbor:"1,keyasint,omitempty"`
	Kid []byte `cbor:"4,keyasint,omitempty"`
	IV  []byte `cbor:"5,keyasint,omitempty"`
}

// data is []byte containing signed CWT

var v signedCWT
if err := cbor.Unmarshal(data, &v); err != nil {
	return err
}

Encoding CWT (CBOR Web Token) using keyasint and toarray struct tags:

// Use signedCWT struct defined in "Decoding CWT" example.

var v signedCWT
...
if data, err := cbor.Marshal(v); err != nil {
	return err
}

Encoding and Decoding CWT (CBOR Web Token) with CBOR Tags

// Use signedCWT struct defined in "Decoding CWT" example.

// Create TagSet (safe for concurrency).
tags := cbor.NewTagSet()
// Register tag COSE_Sign1 18 with signedCWT type.
tags.Add(	
	cbor.TagOptions{EncTag: cbor.EncTagRequired, DecTag: cbor.DecTagRequired}, 
	reflect.TypeOf(signedCWT{}), 
	18)

// Create DecMode with immutable tags.
dm, _ := cbor.DecOptions{}.DecModeWithTags(tags)

// Unmarshal to signedCWT with tag support.
var v signedCWT
if err := dm.Unmarshal(data, &v); err != nil {
	return err
}

// Create EncMode with immutable tags.
em, _ := cbor.EncOptions{}.EncModeWithTags(tags)

// Marshal signedCWT with tag number.
if data, err := cbor.Marshal(v); err != nil {
	return err
}

For more examples, see examples_test.go.

---

⚓ Install • Status • Design Goals • Features • Standards • API • Usage • Fuzzing • Security Policy • License

Comparisons

Comparisons are between this newer library and a well-known library that had 1,000+ stars before this library was created. Default build settings for each library were used for all comparisons.

This library is safer. Small malicious CBOR messages are rejected quickly before they exhaust system resources.

This library is smaller. Programs like senmlCat can be 4 MB smaller by switching to this library. Programs using more complex CBOR data types can be 9.2 MB smaller.

This library is faster for encoding and decoding CBOR Web Token (CWT). However, speed is only one factor and it can vary depending on data types and sizes. Unlike the other library, this one doesn't use Go's unsafe package or code gen.

The resource intensive codec.CborHandle initialization (in the other library) was placed outside the benchmark loop to make sure their library wasn't penalized.

This library uses less memory for encoding and decoding CBOR Web Token (CWT) using test data from RFC 8392 A.1.

Doing your own comparisons is highly recommended. Use your most common message sizes and data types.

---

⚓ Install • Status • Design Goals • Features • Standards • API • Usage • Fuzzing • Security Policy • License

Benchmarks

Go structs are faster than maps with string keys:

• decoding into struct is >28% faster than decoding into map.
• encoding struct is >35% faster than encoding map.

Go structs with keyasint struct tag are faster than maps with integer keys:

• decoding into struct is >28% faster than decoding into map.
• encoding struct is >34% faster than encoding map.

Go structs with toarray struct tag are faster than slice:

• decoding into struct is >15% faster than decoding into slice.
• encoding struct is >12% faster than encoding slice.

Doing your own benchmarks is highly recommended. Use your most common message sizes and data types.

See Benchmarks for fxamacker/cbor.

Fuzzing and Code Coverage

Over 375 tests must pass on 4 architectures before tagging a release. They include all RFC 7049 examples, bugs found by fuzzing, maliciously crafted CBOR data, and over 87 tests with malformed data.

Code coverage must not fall below 95% when tagging a release. Code coverage is 98.6% (go test -cover) for cbor v2.2 which is among the highest for libraries (in Go) of this type.

Coverage-guided fuzzing must pass 250+ million execs before tagging a release. Fuzzing uses fxamacker/cbor-fuzz. Default corpus has:

• 2 files related to WebAuthn (FIDO U2F key).
• 3 files with custom struct.
• 9 files with CWT examples (RFC 8392 Appendix A).
• 17 files with COSE examples (RFC 8152 Appendix B & C).
• 81 files with CBOR examples (RFC 7049 Appendix A) . It excludes 1 errata first reported in issue #46.

Over 1,100 files (corpus) are used for fuzzing because it includes fuzz-generated corpus.

To prevent excessive delays, fuzzing is not restarted for a release if changes are limited to docs and comments.

---

⚓ Install • Status • Design Goals • Features • Standards • API • Usage • Fuzzing • Security Policy • License

Versions and API Changes

This project uses Semantic Versioning, so the API is always backwards compatible unless the major version number changes.

These functions have signatures identical to encoding/json and they will likely never change even after major new releases: Marshal, Unmarshal, NewEncoder, NewDecoder, encoder.Encode, and decoder.Decode.

Newly added API documented as "subject to change" are excluded from SemVer.

Newly added API in the master branch that has never been release tagged are excluded from SemVer.

Code of Conduct

This project has adopted the Contributor Covenant Code of Conduct. Contact faye.github@gmail.com with any questions or comments.

Contributing

Please refer to How to Contribute.

Security Policy

Security fixes are provided for the latest released version.

To report security vulnerabilities, please email faye.github@gmail.com and allow time for the problem to be resolved before reporting it to the public.

Disclaimers

Phrases like "no crashes" or "doesn't crash" mean there are no known crash bugs in the latest version based on results of unit tests and coverage-guided fuzzing. It doesn't imply the software is 100% bug-free or 100% invulnerable to all known and unknown attacks.

Please read the license for additional disclaimers and terms.

Special Thanks

Making this library better

• Montgomery Edwards⁴⁴⁸ for x448/float16, updating the docs, creating charts & slideshow, filing issues, nudging me to ask for feedback from users, helping with design of v2.0-v2.1 API, and general idea for DupMapKeyEnforcedAPF.
• Stefan Tatschner for using this library in sep, being the 1st to discover my CBOR library, requesting time.Time in issue #1, and submitting this library in a PR to cbor.io on Aug 12, 2019.
• Yawning Angel for using this library to oasis-core, and requesting BinaryMarshaler in issue #5.
• Jernej Kos for requesting RawMessage in issue #11 and offering feedback on v2.1 API for CBOR tags.
• ZenGround0 for using this library in go-filecoin, filing "toarray" bug in issue #129, and requesting
  CBOR BSTR <--> Go array in #133.
• Keith Randall for fixing Go bugs and providing workarounds so we don't have to wait for new versions of Go.

Help clarifying CBOR RFC 7049 or 7049bis

• Carsten Bormann for RFC 7049 (CBOR), his fast confirmation to my RFC 7049 errata, approving my pull request to 7049bis, and his patience when I misread a line in 7049bis.
• Laurence Lundblade for his help on the IETF mailing list for 7049bis and for pointing out on a CBORbis issue that CBOR Undefined might be problematic translating to JSON.
• Jeffrey Yasskin for his help on the IETF mailing list for 7049bis.

Words of encouragement and support

• Jakob Borg for his words of encouragement about this library at Go Forum. This is especially appreciated in the early stages when there's a lot of rough edges.

License

Copyright © 2019-present Faye Amacker.

fxamacker/cbor is licensed under the MIT License. See LICENSE for the full license text.

---

⚓ Install • Status • Design Goals • Features • Standards • API • Usage • Fuzzing • Security Policy • License

Documentation

Overview

Package cbor is a fast & safe CBOR encoder & decoder (RFC 7049) with a standard API + toarray & keyasint struct tags, CBOR tags, float64->32->16, CTAP2 & Canonical CBOR, duplicate map key options, and is customizable via simple API.

CBOR encoding options allow "preferred serialization" by encoding integers and floats to their smallest forms (like float16) when values fit.

Struct tags like "keyasint", "toarray" and "omitempty" makes CBOR data smaller.

For example, "toarray" makes struct fields encode to array elements. And "keyasint" makes struct fields encode to elements of CBOR map with int keys.

Basics

Function signatures identical to encoding/json include:

Marshal, Unmarshal, NewEncoder, NewDecoder, encoder.Encode, decoder.Decode.

Codec functions are available at package-level (using defaults) or by creating modes from options at runtime.

"Mode" in this API means definite way of encoding or decoding. Specifically, EncMode or DecMode.

EncMode and DecMode interfaces are created from EncOptions or DecOptions structs. For example,

em := cbor.EncOptions{...}.EncMode()
em := cbor.CanonicalEncOptions().EncMode()
em := cbor.CTAP2EncOptions().EncMode()

Modes use immutable options to avoid side-effects and simplify concurrency. Behavior of modes won't accidentally change at runtime after they're created.

Modes are intended to be reused and are safe for concurrent use.

EncMode and DecMode Interfaces

    // EncMode interface uses immutable options and is safe for concurrent use.
    type EncMode interface {
	Marshal(v interface{}) ([]byte, error)
	NewEncoder(w io.Writer) *Encoder
	EncOptions() EncOptions  // returns copy of options
    }

    // DecMode interface uses immutable options and is safe for concurrent use.
    type DecMode interface {
	Unmarshal(data []byte, v interface{}) error
	NewDecoder(r io.Reader) *Decoder
	DecOptions() DecOptions  // returns copy of options
    }

Using Default Encoding Mode

b, err := cbor.Marshal(v)

encoder := cbor.NewEncoder(w)
err = encoder.Encode(v)

Using Default Decoding Mode

err := cbor.Unmarshal(b, &v)

decoder := cbor.NewDecoder(r)
err = decoder.Decode(&v)

Creating and Using Encoding Modes

// Create EncOptions using either struct literal or a function.
opts := cbor.CanonicalEncOptions()

// If needed, modify encoding options
opts.Time = cbor.TimeUnix

// Create reusable EncMode interface with immutable options, safe for concurrent use.
em, err := opts.EncMode()

// Use EncMode like encoding/json, with same function signatures.
b, err := em.Marshal(v)
// or
encoder := em.NewEncoder(w)
err := encoder.Encode(v)

Default Options

Default encoding options are listed at https://github.com/fxamacker/cbor#api

Struct Tags

Struct tags like `cbor:"name,omitempty"` and `json:"name,omitempty"` work as expected. If both struct tags are specified then `cbor` is used.

Struct tags like "keyasint", "toarray", and "omitempty" make it easy to use very compact formats like COSE and CWT (CBOR Web Tokens) with structs.

For example, "toarray" makes struct fields encode to array elements. And "keyasint" makes struct fields encode to elements of CBOR map with int keys.

https://raw.githubusercontent.com/fxamacker/images/master/cbor/v2.0.0/cbor_easy_api.png

Tests and Fuzzing

Over 375 tests are included in this package. Cover-guided fuzzing is handled by a separate package: fxamacker/cbor-fuzz.

Example (COSE)

// Use "keyasint" struct tag to encode/decode struct to/from CBOR map.
// Use cbor.RawMessage to delay unmarshaling (CrvOrNOrK's data type depends on Kty's value).
type coseKey struct {
	Kty       int             `cbor:"1,keyasint,omitempty"`
	Kid       []byte          `cbor:"2,keyasint,omitempty"`
	Alg       int             `cbor:"3,keyasint,omitempty"`
	KeyOpts   int             `cbor:"4,keyasint,omitempty"`
	IV        []byte          `cbor:"5,keyasint,omitempty"`
	CrvOrNOrK cbor.RawMessage `cbor:"-1,keyasint,omitempty"` // K for symmetric keys, Crv for elliptic curve keys, N for RSA modulus
	XOrE      cbor.RawMessage `cbor:"-2,keyasint,omitempty"` // X for curve x-coordinate, E for RSA public exponent
	Y         cbor.RawMessage `cbor:"-3,keyasint,omitempty"` // Y for curve y-cooridate
	D         []byte          `cbor:"-4,keyasint,omitempty"`
}
// Data from https://tools.ietf.org/html/rfc8392#appendix-A section A.2
// 128-Bit Symmetric Key
cborData, _ := hex.DecodeString("a42050231f4c4d4d3051fdc2ec0a3851d5b3830104024c53796d6d6574726963313238030a")
var v coseKey
if err := cbor.Unmarshal(cborData, &v); err != nil {
	fmt.Println("error:", err)
}
if _, err := cbor.Marshal(v); err != nil {
	fmt.Println("error:", err)
}
fmt.Printf("%+v", v)

Output:

{Kty:4 Kid:[83 121 109 109 101 116 114 105 99 49 50 56] Alg:10 KeyOpts:0 IV:[] CrvOrNOrK:[80 35 31 76 77 77 48 81 253 194 236 10 56 81 213 179 131] XOrE:[] Y:[] D:[]}

Example (CWT)

// Use "keyasint" struct tag to encode/decode struct to/from CBOR map.
type claims struct {
	Iss string `cbor:"1,keyasint"`
	Sub string `cbor:"2,keyasint"`
	Aud string `cbor:"3,keyasint"`
	Exp int    `cbor:"4,keyasint"`
	Nbf int    `cbor:"5,keyasint"`
	Iat int    `cbor:"6,keyasint"`
	Cti []byte `cbor:"7,keyasint"`
}
// Data from https://tools.ietf.org/html/rfc8392#appendix-A section A.1
cborData, _ := hex.DecodeString("a70175636f61703a2f2f61732e6578616d706c652e636f6d02656572696b77037818636f61703a2f2f6c696768742e6578616d706c652e636f6d041a5612aeb0051a5610d9f0061a5610d9f007420b71")
var v claims
if err := cbor.Unmarshal(cborData, &v); err != nil {
	fmt.Println("error:", err)
}
if _, err := cbor.Marshal(v); err != nil {
	fmt.Println("error:", err)
}
fmt.Printf("%+v", v)

Output:

{Iss:coap://as.example.com Sub:erikw Aud:coap://light.example.com Exp:1444064944 Nbf:1443944944 Iat:1443944944 Cti:[11 113]}

Example (CWTWithDupMapKeyOption)

type claims struct {
	Iss string `cbor:"1,keyasint"`
	Sub string `cbor:"2,keyasint"`
	Aud string `cbor:"3,keyasint"`
	Exp int    `cbor:"4,keyasint"`
	Nbf int    `cbor:"5,keyasint"`
	Iat int    `cbor:"6,keyasint"`
	Cti []byte `cbor:"7,keyasint"`
}

// Data from https://tools.ietf.org/html/rfc8392#appendix-A section A.1
cborData, _ := hex.DecodeString("a70175636f61703a2f2f61732e6578616d706c652e636f6d02656572696b77037818636f61703a2f2f6c696768742e6578616d706c652e636f6d041a5612aeb0051a5610d9f0061a5610d9f007420b71")

dm, _ := cbor.DecOptions{DupMapKey: cbor.DupMapKeyEnforcedAPF}.DecMode()

var v claims
if err := dm.Unmarshal(cborData, &v); err != nil {
	fmt.Println("error:", err)
}
fmt.Printf("%+v", v)

Output:

{Iss:coap://as.example.com Sub:erikw Aud:coap://light.example.com Exp:1444064944 Nbf:1443944944 Iat:1443944944 Cti:[11 113]}

Example (SenML)

// Use "keyasint" struct tag to encode/decode struct to/from CBOR map.
type SenMLRecord struct {
	BaseName    string  `cbor:"-2,keyasint,omitempty"`
	BaseTime    float64 `cbor:"-3,keyasint,omitempty"`
	BaseUnit    string  `cbor:"-4,keyasint,omitempty"`
	BaseValue   float64 `cbor:"-5,keyasint,omitempty"`
	BaseSum     float64 `cbor:"-6,keyasint,omitempty"`
	BaseVersion int     `cbor:"-1,keyasint,omitempty"`
	Name        string  `cbor:"0,keyasint,omitempty"`
	Unit        string  `cbor:"1,keyasint,omitempty"`
	Time        float64 `cbor:"6,keyasint,omitempty"`
	UpdateTime  float64 `cbor:"7,keyasint,omitempty"`
	Value       float64 `cbor:"2,keyasint,omitempty"`
	ValueS      string  `cbor:"3,keyasint,omitempty"`
	ValueB      bool    `cbor:"4,keyasint,omitempty"`
	ValueD      string  `cbor:"8,keyasint,omitempty"`
	Sum         float64 `cbor:"5,keyasint,omitempty"`
}
// Data from https://tools.ietf.org/html/rfc8428#section-6
cborData, _ := hex.DecodeString("87a721781b75726e3a6465763a6f773a3130653230373361303130383030363a22fb41d303a15b00106223614120050067766f6c7461676501615602fb405e066666666666a3006763757272656e74062402fb3ff3333333333333a3006763757272656e74062302fb3ff4cccccccccccda3006763757272656e74062202fb3ff6666666666666a3006763757272656e74062102f93e00a3006763757272656e74062002fb3ff999999999999aa3006763757272656e74060002fb3ffb333333333333")
var v []*SenMLRecord
if err := cbor.Unmarshal(cborData, &v); err != nil {
	fmt.Println("error:", err)
}
// Encoder uses ShortestFloat16 option to use float16 as the shortest form that preserves floating-point value.
em, err := cbor.EncOptions{ShortestFloat: cbor.ShortestFloat16}.EncMode()
if err != nil {
	fmt.Println("error:", err)
}
if _, err := em.Marshal(v); err != nil {
	fmt.Println("error:", err)
}
for _, rec := range v {
	fmt.Printf("%+v\n", *rec)
}

Output:

{BaseName:urn:dev:ow:10e2073a0108006: BaseTime:1.276020076001e+09 BaseUnit:A BaseValue:0 BaseSum:0 BaseVersion:5 Name:voltage Unit:V Time:0 UpdateTime:0 Value:120.1 ValueS: ValueB:false ValueD: Sum:0}
{BaseName: BaseTime:0 BaseUnit: BaseValue:0 BaseSum:0 BaseVersion:0 Name:current Unit: Time:-5 UpdateTime:0 Value:1.2 ValueS: ValueB:false ValueD: Sum:0}
{BaseName: BaseTime:0 BaseUnit: BaseValue:0 BaseSum:0 BaseVersion:0 Name:current Unit: Time:-4 UpdateTime:0 Value:1.3 ValueS: ValueB:false ValueD: Sum:0}
{BaseName: BaseTime:0 BaseUnit: BaseValue:0 BaseSum:0 BaseVersion:0 Name:current Unit: Time:-3 UpdateTime:0 Value:1.4 ValueS: ValueB:false ValueD: Sum:0}
{BaseName: BaseTime:0 BaseUnit: BaseValue:0 BaseSum:0 BaseVersion:0 Name:current Unit: Time:-2 UpdateTime:0 Value:1.5 ValueS: ValueB:false ValueD: Sum:0}
{BaseName: BaseTime:0 BaseUnit: BaseValue:0 BaseSum:0 BaseVersion:0 Name:current Unit: Time:-1 UpdateTime:0 Value:1.6 ValueS: ValueB:false ValueD: Sum:0}
{BaseName: BaseTime:0 BaseUnit: BaseValue:0 BaseSum:0 BaseVersion:0 Name:current Unit: Time:0 UpdateTime:0 Value:1.7 ValueS: ValueB:false ValueD: Sum:0}

Example (SignedCWT)

// Use "keyasint" struct tag to encode/decode struct to/from CBOR map.
// Partial COSE header definition
type coseHeader struct {
	Alg int    `cbor:"1,keyasint,omitempty"`
	Kid []byte `cbor:"4,keyasint,omitempty"`
	IV  []byte `cbor:"5,keyasint,omitempty"`
}
// Use "toarray" struct tag to encode/decode struct to/from CBOR array.
type signedCWT struct {
	_           struct{} `cbor:",toarray"`
	Protected   []byte
	Unprotected coseHeader
	Payload     []byte
	Signature   []byte
}
// Data from https://tools.ietf.org/html/rfc8392#appendix-A section A.3
cborData, _ := hex.DecodeString("d28443a10126a104524173796d6d657472696345434453413235365850a70175636f61703a2f2f61732e6578616d706c652e636f6d02656572696b77037818636f61703a2f2f6c696768742e6578616d706c652e636f6d041a5612aeb0051a5610d9f0061a5610d9f007420b7158405427c1ff28d23fbad1f29c4c7c6a555e601d6fa29f9179bc3d7438bacaca5acd08c8d4d4f96131680c429a01f85951ecee743a52b9b63632c57209120e1c9e30")
var v signedCWT
if err := cbor.Unmarshal(cborData, &v); err != nil {
	fmt.Println("error:", err)
}
if _, err := cbor.Marshal(v); err != nil {
	fmt.Println("error:", err)
}
fmt.Printf("%+v", v)

Output:

{_:{} Protected:[161 1 38] Unprotected:{Alg:0 Kid:[65 115 121 109 109 101 116 114 105 99 69 67 68 83 65 50 53 54] IV:[]} Payload:[167 1 117 99 111 97 112 58 47 47 97 115 46 101 120 97 109 112 108 101 46 99 111 109 2 101 101 114 105 107 119 3 120 24 99 111 97 112 58 47 47 108 105 103 104 116 46 101 120 97 109 112 108 101 46 99 111 109 4 26 86 18 174 176 5 26 86 16 217 240 6 26 86 16 217 240 7 66 11 113] Signature:[84 39 193 255 40 210 63 186 209 242 156 76 124 106 85 94 96 29 111 162 159 145 121 188 61 116 56 186 202 202 90 205 8 200 212 212 249 97 49 104 12 66 154 1 248 89 81 236 238 116 58 82 185 182 54 50 197 114 9 18 14 28 158 48]}

Example (SignedCWTWithTag)

// Use "keyasint" struct tag to encode/decode struct to/from CBOR map.
// Partial COSE header definition
type coseHeader struct {
	Alg int    `cbor:"1,keyasint,omitempty"`
	Kid []byte `cbor:"4,keyasint,omitempty"`
	IV  []byte `cbor:"5,keyasint,omitempty"`
}
// Use "toarray" struct tag to encode/decode struct to/from CBOR array.
type signedCWT struct {
	_           struct{} `cbor:",toarray"`
	Protected   []byte
	Unprotected coseHeader
	Payload     []byte
	Signature   []byte
}

// Data from https://tools.ietf.org/html/rfc8392#appendix-A section A.3
cborData, _ := hex.DecodeString("d28443a10126a104524173796d6d657472696345434453413235365850a70175636f61703a2f2f61732e6578616d706c652e636f6d02656572696b77037818636f61703a2f2f6c696768742e6578616d706c652e636f6d041a5612aeb0051a5610d9f0061a5610d9f007420b7158405427c1ff28d23fbad1f29c4c7c6a555e601d6fa29f9179bc3d7438bacaca5acd08c8d4d4f96131680c429a01f85951ecee743a52b9b63632c57209120e1c9e30")

// Register tag COSE_Sign1 18 with signedCWT type.
tags := cbor.NewTagSet()
if err := tags.Add(
	cbor.TagOptions{EncTag: cbor.EncTagRequired, DecTag: cbor.DecTagRequired},
	reflect.TypeOf(signedCWT{}),
	18); err != nil {
	fmt.Println("error:", err)
}

dm, _ := cbor.DecOptions{}.DecModeWithTags(tags)
em, _ := cbor.EncOptions{}.EncModeWithTags(tags)

var v signedCWT
if err := dm.Unmarshal(cborData, &v); err != nil {
	fmt.Println("error:", err)
}

if _, err := em.Marshal(v); err != nil {
	fmt.Println("error:", err)
}
fmt.Printf("%+v", v)

Output:

{_:{} Protected:[161 1 38] Unprotected:{Alg:0 Kid:[65 115 121 109 109 101 116 114 105 99 69 67 68 83 65 50 53 54] IV:[]} Payload:[167 1 117 99 111 97 112 58 47 47 97 115 46 101 120 97 109 112 108 101 46 99 111 109 2 101 101 114 105 107 119 3 120 24 99 111 97 112 58 47 47 108 105 103 104 116 46 101 120 97 109 112 108 101 46 99 111 109 4 26 86 18 174 176 5 26 86 16 217 240 6 26 86 16 217 240 7 66 11 113] Signature:[84 39 193 255 40 210 63 186 209 242 156 76 124 106 85 94 96 29 111 162 159 145 121 188 61 116 56 186 202 202 90 205 8 200 212 212 249 97 49 104 12 66 154 1 248 89 81 236 238 116 58 82 185 182 54 50 197 114 9 18 14 28 158 48]}

Example (WebAuthn)

// Use cbor.RawMessage to delay unmarshaling (AttStmt's data type depends on Fmt's value).
type attestationObject struct {
	AuthnData []byte          `cbor:"authData"`
	Fmt       string          `cbor:"fmt"`
	AttStmt   cbor.RawMessage `cbor:"attStmt"`
}
cborData, _ := hex.DecodeString("a363666d74686669646f2d7532666761747453746d74a26373696758483046022100e7ab373cfbd99fcd55fd59b0f6f17fef5b77a20ddec3db7f7e4d55174e366236022100828336b4822125fb56541fb14a8a273876acd339395ec2dad95cf41c1dd2a9ae637835638159024e3082024a30820132a0030201020204124a72fe300d06092a864886f70d01010b0500302e312c302a0603550403132359756269636f2055324620526f6f742043412053657269616c203435373230303633313020170d3134303830313030303030305a180f32303530303930343030303030305a302c312a302806035504030c2159756269636f205532462045452053657269616c203234393431343937323135383059301306072a8648ce3d020106082a8648ce3d030107034200043d8b1bbd2fcbf6086e107471601468484153c1c6d3b4b68a5e855e6e40757ee22bcd8988bf3befd7cdf21cb0bf5d7a150d844afe98103c6c6607d9faae287c02a33b3039302206092b0601040182c40a020415312e332e362e312e342e312e34313438322e312e313013060b2b0601040182e51c020101040403020520300d06092a864886f70d01010b05000382010100a14f1eea0076f6b8476a10a2be72e60d0271bb465b2dfbfc7c1bd12d351989917032631d795d097fa30a26a325634e85721bc2d01a86303f6bc075e5997319e122148b0496eec8d1f4f94cf4110de626c289443d1f0f5bbb239ca13e81d1d5aa9df5af8e36126475bfc23af06283157252762ff68879bcf0ef578d55d67f951b4f32b63c8aea5b0f99c67d7d814a7ff5a6f52df83e894a3a5d9c8b82e7f8bc8daf4c80175ff8972fda79333ec465d806eacc948f1bab22045a95558a48c20226dac003d41fbc9e05ea28a6bb5e10a49de060a0a4f6a2676a34d68c4abe8c61874355b9027e828ca9e064b002d62e8d8cf0744921753d35e3c87c5d5779453e7768617574684461746158c449960de5880e8c687434170f6476605b8fe4aeb9a28632c7995cf3ba831d976341000000000000000000000000000000000000000000408903fd7dfd2c9770e98cae0123b13a2c27828a106349bc6277140e7290b7e9eb7976aa3c04ed347027caf7da3a2fa76304751c02208acfc4e7fc6c7ebbc375c8a5010203262001215820ad7f7992c335b90d882b2802061b97a4fabca7e2ee3e7a51e728b8055e4eb9c7225820e0966ba7005987fece6f0e0e13447aa98cec248e4000a594b01b74c1cb1d40b3")
var v attestationObject
if err := cbor.Unmarshal(cborData, &v); err != nil {
	fmt.Println("error:", err)
}
if _, err := cbor.Marshal(v); err != nil {
	fmt.Println("error:", err)
}
fmt.Printf("%+v", v)

Index

• func Marshal(v interface{}) ([]byte, error)
• func Unmarshal(data []byte, v interface{}) error
• type DecMode
• type DecOptions
  • func (opts DecOptions) DecMode() (DecMode, error)
  • func (opts DecOptions) DecModeWithSharedTags(tags TagSet) (DecMode, error)
  • func (opts DecOptions) DecModeWithTags(tags TagSet) (DecMode, error)
• type DecTagMode
• type Decoder
  • func NewDecoder(r io.Reader) *Decoder
  • func (dec *Decoder) Decode(v interface{}) error
  • func (dec *Decoder) NumBytesRead() int
• type DupMapKeyError
  • func (e *DupMapKeyError) Error() string
• type DupMapKeyMode
• type EncMode
• type EncOptions
  • func CTAP2EncOptions() EncOptions
  • func CanonicalEncOptions() EncOptions
  • func CoreDetEncOptions() EncOptions
  • func PreferredUnsortedEncOptions() EncOptions
  • func (opts EncOptions) EncMode() (EncMode, error)
  • func (opts EncOptions) EncModeWithSharedTags(tags TagSet) (EncMode, error)
  • func (opts EncOptions) EncModeWithTags(tags TagSet) (EncMode, error)
• type EncTagMode
• type Encoder
  • func NewEncoder(w io.Writer) *Encoder
  • func (enc *Encoder) Encode(v interface{}) error
  • func (enc *Encoder) EndIndefinite() error
  • func (enc *Encoder) StartIndefiniteArray() error
  • func (enc *Encoder) StartIndefiniteByteString() error
  • func (enc *Encoder) StartIndefiniteMap() error
  • func (enc *Encoder) StartIndefiniteTextString() error
• type IndefLengthMode
• type IndefiniteLengthError
  • func (e *IndefiniteLengthError) Error() string
• type InfConvertMode
• type InvalidUnmarshalError
  • func (e *InvalidUnmarshalError) Error() string
• type Marshaler
• type MaxArrayElementsError
  • func (e *MaxArrayElementsError) Error() string
• type MaxMapPairsError
  • func (e *MaxMapPairsError) Error() string
• type MaxNestedLevelError
  • func (e *MaxNestedLevelError) Error() string
• type NaNConvertMode
• type RawMessage
  • func (m RawMessage) MarshalCBOR() ([]byte, error)
  • func (m *RawMessage) UnmarshalCBOR(data []byte) error
• type RawTag
  • func (t RawTag) MarshalCBOR() ([]byte, error)
  • func (t *RawTag) UnmarshalCBOR(data []byte) error
• type SemanticError
  • func (e *SemanticError) Error() string
• type ShortestFloatMode
• type SortMode
• type SyntaxError
  • func (e *SyntaxError) Error() string
• type Tag
• type TagOptions
• type TagSet
  • func NewTagSet() TagSet
• type TagsMdError
  • func (e *TagsMdError) Error() string
• type TagsMode
• type TimeMode
• type UnmarshalTypeError
  • func (e *UnmarshalTypeError) Error() string
• type Unmarshaler
• type UnsupportedTypeError
  • func (e *UnsupportedTypeError) Error() string
• type WrongTagError
  • func (e *WrongTagError) Error() string

Examples

• Package (COSE)
• Package (CWT)
• Package (CWTWithDupMapKeyOption)
• Package (SenML)
• Package (SignedCWT)
• Package (SignedCWTWithTag)
• Package (WebAuthn)
• Decoder
• Encoder
• Encoder (IndefiniteLengthArray)
• Encoder (IndefiniteLengthByteString)
• Encoder (IndefiniteLengthMap)
• Encoder (IndefiniteLengthTextString)
• Marshal
• Marshal (Canonical)
• Marshal (Keyasint)
• Marshal (Time)
• Marshal (Toarray)
• Unmarshal
• Unmarshal (Time)

Functions

func Marshal

func Marshal(v interface{}) ([]byte, error)

Marshal returns the CBOR encoding of v using the default encoding options.

Marshal uses the following type-dependent default encodings:

Boolean values encode as CBOR booleans (type 7).

Positive integer values encode as CBOR positive integers (type 0).

Negative integer values encode as CBOR negative integers (type 1).

Floating point values encode as CBOR floating points (type 7).

String values encode as CBOR text strings (type 3).

[]byte values encode as CBOR byte strings (type 2).

Array and slice values encode as CBOR arrays (type 4).

Map values encode as CBOR maps (type 5).

Struct values encode as CBOR maps (type 5). Each exported struct field becomes a pair with field name encoded as CBOR text string (type 3) and field value encoded based on its type.

Pointer values encode as the value pointed to.

Nil slice/map/pointer/interface values encode as CBOR nulls (type 7).

time.Time values encode as text strings specified in RFC3339 when EncOptions.TimeRFC3339 is true; otherwise, time.Time values encode as numerical representation of seconds since January 1, 1970 UTC.

If value implements the Marshaler interface, Marshal calls its MarshalCBOR method. If value implements encoding.BinaryMarshaler instead, Marhsal calls its MarshalBinary method and encode it as CBOR byte string.

Marshal supports format string stored under the "cbor" key in the struct field's tag. CBOR format string can specify the name of the field, "omitempty" and "keyasint" options, and special case "-" for field omission. If "cbor" key is absent, Marshal uses "json" key.

Struct field name is treated as integer if it has "keyasint" option in its format string. The format string must specify an integer as its field name.

Special struct field "_" is used to specify struct level options, such as "toarray". "toarray" option enables Go struct to be encoded as CBOR array. "omitempty" is disabled by "toarray" to ensure that the same number of elements are encoded every time.

Anonymous struct fields are usually marshaled as if their exported fields were fields in the outer struct. Marshal follows the same struct fields visibility rules used by JSON encoding package. An anonymous struct field with a name given in its CBOR tag is treated as having that name, rather than being anonymous. An anonymous struct field of interface type is treated the same as having that type as its name, rather than being anonymous.

Interface values encode as the value contained in the interface. A nil interface value encodes as the null CBOR value.

Channel, complex, and functon values cannot be encoded in CBOR. Attempting to encode such a value causes Marshal to return an UnsupportedTypeError.

Example

type Animal struct {
	Age    int
	Name   string
	Owners []string
	Male   bool
}
animal := Animal{Age: 4, Name: "Candy", Owners: []string{"Mary", "Joe"}}
b, err := cbor.Marshal(animal)
if err != nil {
	fmt.Println("error:", err)
}
fmt.Printf("%x\n", b)

Output:

a46341676504644e616d656543616e6479664f776e65727382644d617279634a6f65644d616c65f4

Example (Canonical)

This example uses Marshal to encode struct and map in canonical form.

type Animal struct {
	Age      int
	Name     string
	Contacts map[string]string
	Male     bool
}
animal := Animal{Age: 4, Name: "Candy", Contacts: map[string]string{"Mary": "111-111-1111", "Joe": "222-222-2222"}}
em, err := cbor.CanonicalEncOptions().EncMode()
if err != nil {
	fmt.Println("error:", err)
}
b, err := em.Marshal(animal)
if err != nil {
	fmt.Println("error:", err)
}
fmt.Printf("%x\n", b)

Output:

a46341676504644d616c65f4644e616d656543616e647968436f6e7461637473a2634a6f656c3232322d3232322d32323232644d6172796c3131312d3131312d31313131

Example (Keyasint)

This example uses "keyasint" struct tag to encode struct's fiele names as integer. This feautre is very useful in handling COSE, CWT, SenML data.

type Record struct {
	Name        string `cbor:"1,keyasint"`
	Unit        string `cbor:"2,keyasint"`
	Measurement int    `cbor:"3,keyasint"`
}
rec := Record{Name: "current", Unit: "V", Measurement: 1}
b, err := cbor.Marshal(rec)
if err != nil {
	fmt.Println("error:", err)
}
fmt.Printf("%x\n", b)

Output:

a3016763757272656e740261560301

Example (Time)

tm, _ := time.Parse(time.RFC3339, "2013-03-21T20:04:00Z")

// Encode time as string in RFC3339 format with second precision.
em, err := cbor.EncOptions{Time: cbor.TimeRFC3339}.EncMode()
if err != nil {
	fmt.Println("error:", err)
}
b, err := em.Marshal(tm)
if err != nil {
	fmt.Println("error:", err)
}
fmt.Printf("%x\n", b)

// Encode time as numerical representation of seconds since January 1, 1970 UTC.
em, err = cbor.EncOptions{Time: cbor.TimeUnix}.EncMode()
if err != nil {
	fmt.Println("error:", err)
}
b, err = em.Marshal(tm)
if err != nil {
	fmt.Println("error:", err)
}
fmt.Printf("%x\n", b)

Output:

74323031332d30332d32315432303a30343a30305a
1a514b67b0

Example (Toarray)

This example uses "toarray" struct tag to encode struct as CBOR array.

type Record struct {
	_           struct{} `cbor:",toarray"`
	Name        string
	Unit        string
	Measurement int
}
rec := Record{Name: "current", Unit: "V", Measurement: 1}
b, err := cbor.Marshal(rec)
if err != nil {
	fmt.Println("error:", err)
}
fmt.Printf("%x\n", b)

Output:

836763757272656e74615601

func Unmarshal

func Unmarshal(data []byte, v interface{}) error

Unmarshal parses the CBOR-encoded data and stores the result in the value pointed to by v using the default decoding options. If v is nil or not a pointer, Unmarshal returns an error.

Unmarshal uses the inverse of the encodings that Marshal uses, allocating maps, slices, and pointers as necessary, with the following additional rules:

To unmarshal CBOR into a pointer, Unmarshal first handles the case of the CBOR being the CBOR literal null. In that case, Unmarshal sets the pointer to nil. Otherwise, Unmarshal unmarshals the CBOR into the value pointed at by the pointer. If the pointer is nil, Unmarshal allocates a new value for it to point to.

To unmarshal CBOR into an interface value, Unmarshal stores one of these in the interface value:

bool, for CBOR booleans
uint64, for CBOR positive integers
int64, for CBOR negative integers
float64, for CBOR floating points
[]byte, for CBOR byte strings
string, for CBOR text strings
[]interface{}, for CBOR arrays
map[interface{}]interface{}, for CBOR maps
nil, for CBOR null

To unmarshal a CBOR array into a slice, Unmarshal allocates a new slice only if the CBOR array is empty or slice capacity is less than CBOR array length. Otherwise Unmarshal reuses the existing slice, overwriting existing elements. Unmarshal sets the slice length to CBOR array length.

To ummarshal a CBOR array into a Go array, Unmarshal decodes CBOR array elements into corresponding Go array elements. If the Go array is smaller than the CBOR array, the additional CBOR array elements are discarded. If the CBOR array is smaller than the Go array, the additional Go array elements are set to zero values.

To unmarshal a CBOR map into a map, Unmarshal allocates a new map only if the map is nil. Otherwise Unmarshal reuses the existing map, keeping existing entries. Unmarshal stores key-value pairs from the CBOR map into Go map.

To unmarshal a CBOR map into a struct, Unmarshal matches CBOR map keys to the keys in the following priority:

1. "cbor" key in struct field tag,
2. "json" key in struct field tag,
3. struct field name.

Unmarshal prefers an exact match but also accepts a case-insensitive match. Map keys which don't have a corresponding struct field are ignored.

To unmarshal a CBOR text string into a time.Time value, Unmarshal parses text string formatted in RFC3339. To unmarshal a CBOR integer/float into a time.Time value, Unmarshal creates an unix time with integer/float as seconds and fractional seconds since January 1, 1970 UTC.

To unmarshal CBOR into a value implementing the Unmarshaler interface, Unmarshal calls that value's UnmarshalCBOR method.

Unmarshal decodes a CBOR byte string into a value implementing encoding.BinaryUnmarshaler.

If a CBOR value is not appropriate for a given Go type, or if a CBOR number overflows the Go type, Unmarshal skips that field and completes the unmarshalling as best as it can. If no more serious errors are encountered, unmarshal returns an UnmarshalTypeError describing the earliest such error. In any case, it's not guaranteed that all the remaining fields following the problematic one will be unmarshaled into the target object.

The CBOR null value unmarshals into a slice/map/pointer/interface by setting that Go value to nil. Because null is often used to mean "not present", unmarshalling a CBOR null into any other Go type has no effect on the value produces no error.

Unmarshal ignores CBOR tag data and parses tagged data following CBOR tag.

Example

type Animal struct {
	Age    int
	Name   string
	Owners []string
	Male   bool
}
cborData, _ := hex.DecodeString("a46341676504644e616d656543616e6479664f776e65727382644d617279634a6f65644d616c65f4")
var animal Animal
err := cbor.Unmarshal(cborData, &animal)
if err != nil {
	fmt.Println("error:", err)
}
fmt.Printf("%+v", animal)

Output:

{Age:4 Name:Candy Owners:[Mary Joe] Male:false}

Example (Time)

cborRFC3339Time, _ := hex.DecodeString("74323031332d30332d32315432303a30343a30305a")
tm := time.Time{}
if err := cbor.Unmarshal(cborRFC3339Time, &tm); err != nil {
	fmt.Println("error:", err)
}
fmt.Printf("%+v\n", tm.UTC().Format(time.RFC3339Nano))
cborUnixTime, _ := hex.DecodeString("1a514b67b0")
tm = time.Time{}
if err := cbor.Unmarshal(cborUnixTime, &tm); err != nil {
	fmt.Println("error:", err)
}
fmt.Printf("%+v\n", tm.UTC().Format(time.RFC3339Nano))

Output:

2013-03-21T20:04:00Z
2013-03-21T20:04:00Z

Types

type DecMode

type DecMode interface {
	Unmarshal(data []byte, v interface{}) error
	NewDecoder(r io.Reader) *Decoder
	DecOptions() DecOptions
}

DecMode is the main interface for CBOR decoding.

type DecOptions

type DecOptions struct {
	// DupMapKey specifies whether to enforce duplicate map key.
	DupMapKey DupMapKeyMode

	// TimeTag specifies whether to check validity of time.Time (e.g. valid tag number and tag content type).
	// For now, valid tag number means 0 or 1 as specified in RFC 7049 if the Go type is time.Time.
	TimeTag DecTagMode

	// MaxNestedLevels specifies the max nested levels allowed for any combination of CBOR array, maps, and tags.
	// Default is 32 levels and it can be set to [4, 256].
	MaxNestedLevels int

	// MaxArrayElements specifies the max number of elements for CBOR arrays.
	// Default is 128*1024=131072 and it can be set to [16, 134217728]
	MaxArrayElements int

	// MaxMapPairs specifies the max number of key-value pairs for CBOR maps.
	// Default is 128*1024=131072 and it can be set to [16, 134217728]
	MaxMapPairs int

	// IndefLength specifies whether to allow indefinite length CBOR items.
	IndefLength IndefLengthMode

	// TagsMd specifies whether to allow CBOR tags (major type 6).
	TagsMd TagsMode
}

DecOptions specifies decoding options.

func (DecOptions) DecMode

func (opts DecOptions) DecMode() (DecMode, error)

DecMode returns DecMode with immutable options and no tags (safe for concurrency).

func (DecOptions) DecModeWithSharedTags

func (opts DecOptions) DecModeWithSharedTags(tags TagSet) (DecMode, error)

DecModeWithSharedTags returns DecMode with immutable options and mutable shared tags (safe for concurrency).

func (DecOptions) DecModeWithTags

func (opts DecOptions) DecModeWithTags(tags TagSet) (DecMode, error)

DecModeWithTags returns DecMode with options and tags that are both immutable (safe for concurrency).

type DecTagMode

type DecTagMode int

DecTagMode specifies how decoder handles tag number.

const (
	// DecTagIgnored makes decoder ignore tag number (skips if present).
	DecTagIgnored DecTagMode = iota

	// DecTagOptional makes decoder verify tag number if it's present.
	DecTagOptional

	// DecTagRequired makes decoder verify tag number and tag number must be present.
	DecTagRequired
)

type Decoder

type Decoder struct {
	// contains filtered or unexported fields
}

Decoder reads and decodes CBOR values from an input stream.

Example

type Animal struct {
	Age    int
	Name   string
	Owners []string
	Male   bool
}
cborData, _ := hex.DecodeString("a46341676504644d616c65f4644e616d656543616e6479664f776e65727382644d617279634a6f65a46341676506644d616c65f5644e616d656452756479664f776e657273816543696e6479a46341676502644d616c65f5644e616d656444756b65664f776e65727381664e6f72746f6e")
dec := cbor.NewDecoder(bytes.NewReader(cborData))
for {
	var animal Animal
	if err := dec.Decode(&animal); err != nil {
		if err != io.EOF {
			fmt.Println("error:", err)
		}
		break
	}
	fmt.Printf("%+v\n", animal)
}

Output:

{Age:4 Name:Candy Owners:[Mary Joe] Male:false}
{Age:6 Name:Rudy Owners:[Cindy] Male:true}
{Age:2 Name:Duke Owners:[Norton] Male:true}

func NewDecoder

func NewDecoder(r io.Reader) *Decoder

NewDecoder returns a new decoder that reads from r using the default decoding options.

func (*Decoder) Decode

func (dec *Decoder) Decode(v interface{}) error

Decode reads the next CBOR-encoded value from its input and stores it in the value pointed to by v.

func (*Decoder) NumBytesRead

func (dec *Decoder) NumBytesRead() int

NumBytesRead returns the number of bytes read.

type DupMapKeyError

type DupMapKeyError struct {
	Key   interface{}
	Index int
}

DupMapKeyError describes detected duplicate map key in CBOR map.

func (*DupMapKeyError) Error

func (e *DupMapKeyError) Error() string

type DupMapKeyMode

type DupMapKeyMode int

DupMapKeyMode specifies how to enforce duplicate map key.

const (
	// DupMapKeyQuiet doesn't enforce duplicate map key. Decoder quietly (no error)
	// uses faster of "keep first" or "keep last" depending on Go data type and other factors.
	DupMapKeyQuiet DupMapKeyMode = iota

	// DupMapKeyEnforcedAPF enforces detection and rejection of duplicate map keys.
	// APF means "Allow Partial Fill" and the destination map or struct can be partially filled.
	// If a duplicate map key is detected, DupMapKeyError is returned without further decoding
	// of the map. It's the caller's responsibility to respond to DupMapKeyError by
	// discarding the partially filled result if their protocol requires it.
	// WARNING: using DupMapKeyEnforcedAPF will decrease performance and increase memory use.
	DupMapKeyEnforcedAPF
)

type EncMode

type EncMode interface {
	Marshal(v interface{}) ([]byte, error)
	NewEncoder(w io.Writer) *Encoder
	EncOptions() EncOptions
}

EncMode is the main interface for CBOR encoding.

type EncOptions

type EncOptions struct {
	// Sort specifies sorting order.
	Sort SortMode

	// ShortestFloat specifies the shortest floating-point encoding that preserves
	// the value being encoded.
	ShortestFloat ShortestFloatMode

	// NaNConvert specifies how to encode NaN and it overrides ShortestFloatMode.
	NaNConvert NaNConvertMode

	// InfConvert specifies how to encode Inf and it overrides ShortestFloatMode.
	InfConvert InfConvertMode

	// Time specifies how to encode time.Time.
	Time TimeMode

	// TimeTag allows time.Time to be encoded with a tag number.
	// RFC3339 format gets tag number 0, and numeric epoch time tag number 1.
	TimeTag EncTagMode

	// IndefLength specifies whether to allow indefinite length CBOR items.
	IndefLength IndefLengthMode

	// TagsMd specifies whether to allow CBOR tags (major type 6).
	TagsMd TagsMode
}

EncOptions specifies encoding options.

func CTAP2EncOptions

func CTAP2EncOptions() EncOptions

CTAP2EncOptions returns EncOptions for "CTAP2 Canonical CBOR" encoding, defined in CTAP specification, with the following rules:

1. "Integers must be encoded as small as possible."
2. "The representations of any floating-point values are not changed."
3. "The expression of lengths in major types 2 through 5 must be as short as possible."
4. "Indefinite-length items must be made into definite-length items.""
5. The keys in every map must be sorted in bytewise lexicographic order. See SortBytewiseLexical for details.
6. "Tags as defined in Section 2.4 in [RFC7049] MUST NOT be present."

func CanonicalEncOptions

func CanonicalEncOptions() EncOptions

CanonicalEncOptions returns EncOptions for "Canonical CBOR" encoding, defined in RFC 7049 Section 3.9 with the following rules:

1. "Integers must be as small as possible."
2. "The expression of lengths in major types 2 through 5 must be as short as possible."
3. The keys in every map must be sorted in length-first sorting order. See SortLengthFirst for details.
4. "Indefinite-length items must be made into definite-length items."
5. "If a protocol allows for IEEE floats, then additional canonicalization rules might need to be added. One example rule might be to have all floats start as a 64-bit float, then do a test conversion to a 32-bit float; if the result is the same numeric value, use the shorter value and repeat the process with a test conversion to a 16-bit float. (This rule selects 16-bit float for positive and negative Infinity as well.) Also, there are many representations for NaN. If NaN is an allowed value, it must always be represented as 0xf97e00."

func CoreDetEncOptions

func CoreDetEncOptions() EncOptions

CoreDetEncOptions returns EncOptions for "Core Deterministic" encoding, defined in RFC 7049bis with the following rules:

1. "Preferred serialization MUST be used. In particular, this means that arguments (see Section 3) for integers, lengths in major types 2 through 5, and tags MUST be as short as possible" "Floating point values also MUST use the shortest form that preserves the value"
2. "Indefinite-length items MUST NOT appear."
3. "The keys in every map MUST be sorted in the bytewise lexicographic order of their deterministic encodings."

func PreferredUnsortedEncOptions

func PreferredUnsortedEncOptions() EncOptions

PreferredUnsortedEncOptions returns EncOptions for "Preferred Serialization" encoding, defined in RFC 7049bis with the following rules:

1. "The preferred serialization always uses the shortest form of representing the argument (Section 3);"
2. "it also uses the shortest floating-point encoding that preserves the value being encoded (see Section 5.5)." "The preferred encoding for a floating-point value is the shortest floating-point encoding that preserves its value, e.g., 0xf94580 for the number 5.5, and 0xfa45ad9c00 for the number 5555.5, unless the CBOR-based protocol specifically excludes the use of the shorter floating-point encodings. For NaN values, a shorter encoding is preferred if zero-padding the shorter significand towards the right reconstitutes the original NaN value (for many applications, the single NaN encoding 0xf97e00 will suffice)."
3. "Definite length encoding is preferred whenever the length is known at the time the serialization of the item starts."

func (EncOptions) EncMode

func (opts EncOptions) EncMode() (EncMode, error)

EncMode returns EncMode with immutable options and no tags (safe for concurrency).

func (EncOptions) EncModeWithSharedTags

func (opts EncOptions) EncModeWithSharedTags(tags TagSet) (EncMode, error)

EncModeWithSharedTags returns EncMode with immutable options and mutable shared tags (safe for concurrency).

func (EncOptions) EncModeWithTags

func (opts EncOptions) EncModeWithTags(tags TagSet) (EncMode, error)

EncModeWithTags returns EncMode with options and tags that are both immutable (safe for concurrency).

type EncTagMode

type EncTagMode int

EncTagMode specifies how encoder handles tag number.

const (
	// EncTagNone makes encoder not encode tag number.
	EncTagNone EncTagMode = iota

	// EncTagRequired makes encoder encode tag number.
	EncTagRequired
)

type Encoder

type Encoder struct {
	// contains filtered or unexported fields
}

Encoder writes CBOR values to an output stream.

Example

type Animal struct {
	Age    int
	Name   string
	Owners []string
	Male   bool
}
animals := []Animal{
	{Age: 4, Name: "Candy", Owners: []string{"Mary", "Joe"}, Male: false},
	{Age: 6, Name: "Rudy", Owners: []string{"Cindy"}, Male: true},
	{Age: 2, Name: "Duke", Owners: []string{"Norton"}, Male: true},
}
var buf bytes.Buffer
em, err := cbor.CanonicalEncOptions().EncMode()
if err != nil {
	fmt.Println("error:", err)
}
enc := em.NewEncoder(&buf)
for _, animal := range animals {
	err := enc.Encode(animal)
	if err != nil {
		fmt.Println("error:", err)
	}
}
fmt.Printf("%x\n", buf.Bytes())

Output:

a46341676504644d616c65f4644e616d656543616e6479664f776e65727382644d617279634a6f65a46341676506644d616c65f5644e616d656452756479664f776e657273816543696e6479a46341676502644d616c65f5644e616d656444756b65664f776e65727381664e6f72746f6e

Example (IndefiniteLengthArray)

ExampleEncoder_indefiniteLengthArray encodes a stream of elements as an indefinite length array. Encoder supports nested indefinite length values.

var buf bytes.Buffer
enc := cbor.NewEncoder(&buf)
// Start indefinite length array encoding.
if err := enc.StartIndefiniteArray(); err != nil {
	fmt.Println("error:", err)
}
// Encode array element.
if err := enc.Encode(1); err != nil {
	fmt.Println("error:", err)
}
// Encode array element.
if err := enc.Encode([]int{2, 3}); err != nil {
	fmt.Println("error:", err)
}
// Start a nested indefinite length array as array element.
if err := enc.StartIndefiniteArray(); err != nil {
	fmt.Println("error:", err)
}
// Encode nested array element.
if err := enc.Encode(4); err != nil {
	fmt.Println("error:", err)
}
// Encode nested array element.
if err := enc.Encode(5); err != nil {
	fmt.Println("error:", err)
}
// Close nested indefinite length array.
if err := enc.EndIndefinite(); err != nil {
	fmt.Println("error:", err)
}
// Close outer indefinite length array.
if err := enc.EndIndefinite(); err != nil {
	fmt.Println("error:", err)
}
fmt.Printf("%x\n", buf.Bytes())

Output:

9f018202039f0405ffff

Example (IndefiniteLengthByteString)

ExampleEncoder_indefiniteLengthByteString encodes a stream of definite length byte string ("chunks") as an indefinite length byte string.

var buf bytes.Buffer
encoder := cbor.NewEncoder(&buf)
// Start indefinite length byte string encoding.
if err := encoder.StartIndefiniteByteString(); err != nil {
	fmt.Println("error:", err)
}
// Encode definite length byte string.
if err := encoder.Encode([]byte{1, 2}); err != nil {
	fmt.Println("error:", err)
}
// Encode definite length byte string.
if err := encoder.Encode([3]byte{3, 4, 5}); err != nil {
	fmt.Println("error:", err)
}
// Close indefinite length byte string.
if err := encoder.EndIndefinite(); err != nil {
	fmt.Println("error:", err)
}
fmt.Printf("%x\n", buf.Bytes())

Output:

5f42010243030405ff

Example (IndefiniteLengthMap)

ExampleEncoder_indefiniteLengthMap encodes a stream of elements as an indefinite length map. Encoder supports nested indefinite length values.

var buf bytes.Buffer
em, err := cbor.EncOptions{Sort: cbor.SortCanonical}.EncMode()
if err != nil {
	fmt.Println("error:", err)
}
enc := em.NewEncoder(&buf)
// Start indefinite length map encoding.
if err := enc.StartIndefiniteMap(); err != nil {
	fmt.Println("error:", err)
}
// Encode map key.
if err := enc.Encode("a"); err != nil {
	fmt.Println("error:", err)
}
// Encode map value.
if err := enc.Encode(1); err != nil {
	fmt.Println("error:", err)
}
// Encode map key.
if err := enc.Encode("b"); err != nil {
	fmt.Println("error:", err)
}
// Start an indefinite length array as map value.
if err := enc.StartIndefiniteArray(); err != nil {
	fmt.Println("error:", err)
}
// Encoded array element.
if err := enc.Encode(2); err != nil {
	fmt.Println("error:", err)
}
// Encoded array element.
if err := enc.Encode(3); err != nil {
	fmt.Println("error:", err)
}
// Close indefinite length array.
if err := enc.EndIndefinite(); err != nil {
	fmt.Println("error:", err)
}
// Close indefinite length map.
if err := enc.EndIndefinite(); err != nil {
	fmt.Println("error:", err)
}
fmt.Printf("%x\n", buf.Bytes())

Output:

bf61610161629f0203ffff

Example (IndefiniteLengthTextString)

ExampleEncoder_indefiniteLengthTextString encodes a stream of definite length text string ("chunks") as an indefinite length text string.

var buf bytes.Buffer
encoder := cbor.NewEncoder(&buf)
// Start indefinite length text string encoding.
if err := encoder.StartIndefiniteTextString(); err != nil {
	fmt.Println("error:", err)
}
// Encode definite length text string.
if err := encoder.Encode("strea"); err != nil {
	fmt.Println("error:", err)
}
// Encode definite length text string.
if err := encoder.Encode("ming"); err != nil {
	fmt.Println("error:", err)
}
// Close indefinite length text string.
if err := encoder.EndIndefinite(); err != nil {
	fmt.Println("error:", err)
}
fmt.Printf("%x\n", buf.Bytes())

Output:

7f657374726561646d696e67ff

func NewEncoder

func NewEncoder(w io.Writer) *Encoder

NewEncoder returns a new encoder that writes to w using the default encoding options.

func (*Encoder) Encode

func (enc *Encoder) Encode(v interface{}) error

Encode writes the CBOR encoding of v to the stream.

func (*Encoder) EndIndefinite

func (enc *Encoder) EndIndefinite() error

EndIndefinite closes last opened indefinite length value.

func (*Encoder) StartIndefiniteArray

func (enc *Encoder) StartIndefiniteArray() error

StartIndefiniteArray starts array encoding of indefinite length. Subsequent calls of (*Encoder).Encode() encodes elements of the array until EndIndefinite is called.

func (*Encoder) StartIndefiniteByteString

func (enc *Encoder) StartIndefiniteByteString() error

StartIndefiniteByteString starts byte string encoding of indefinite length. Subsequent calls of (*Encoder).Encode() encodes definite length byte strings ("chunks") as one continguous string until EndIndefinite is called.

func (*Encoder) StartIndefiniteMap

func (enc *Encoder) StartIndefiniteMap() error

StartIndefiniteMap starts array encoding of indefinite length. Subsequent calls of (*Encoder).Encode() encodes elements of the map until EndIndefinite is called.

func (*Encoder) StartIndefiniteTextString

func (enc *Encoder) StartIndefiniteTextString() error

StartIndefiniteTextString starts text string encoding of indefinite length. Subsequent calls of (*Encoder).Encode() encodes definite length text strings ("chunks") as one continguous string until EndIndefinite is called.

type IndefLengthMode

type IndefLengthMode int

IndefLengthMode specifies whether to allow indefinite length items.

const (
	// IndefLengthAllowed allows indefinite length items.
	IndefLengthAllowed IndefLengthMode = iota

	// IndefLengthForbidden disallows indefinite length items.
	IndefLengthForbidden
)

type IndefiniteLengthError

type IndefiniteLengthError struct {
	// contains filtered or unexported fields
}

IndefiniteLengthError indicates found disallowed indefinite length items.

func (*IndefiniteLengthError) Error

func (e *IndefiniteLengthError) Error() string

type InfConvertMode

type InfConvertMode int

InfConvertMode specifies how to encode Infinity and overrides ShortestFloatMode. ShortestFloatMode is not used for encoding Infinity and NaN values.

const (
	// InfConvertFloat16 always converts Inf to lossless IEEE binary16 (float16).
	InfConvertFloat16 InfConvertMode = iota

	// InfConvertNone never converts (used by CTAP2 Canonical CBOR).
	InfConvertNone
)

type InvalidUnmarshalError

type InvalidUnmarshalError struct {
	Type reflect.Type
}

InvalidUnmarshalError describes an invalid argument passed to Unmarshal.

func (*InvalidUnmarshalError) Error

func (e *InvalidUnmarshalError) Error() string

type Marshaler

type Marshaler interface {
	MarshalCBOR() ([]byte, error)
}

Marshaler is the interface implemented by types that can marshal themselves into valid CBOR.

type MaxArrayElementsError

type MaxArrayElementsError struct {
	// contains filtered or unexported fields
}

MaxArrayElementsError indicates exceeded max number of elements for CBOR arrays.

func (*MaxArrayElementsError) Error

func (e *MaxArrayElementsError) Error() string

type MaxMapPairsError

type MaxMapPairsError struct {
	// contains filtered or unexported fields
}

MaxMapPairsError indicates exceeded max number of key-value pairs for CBOR maps.

func (*MaxMapPairsError) Error

func (e *MaxMapPairsError) Error() string

type MaxNestedLevelError

type MaxNestedLevelError struct {
	// contains filtered or unexported fields
}

MaxNestedLevelError indicates exceeded max nested level of any combination of CBOR arrays/maps/tags.

func (*MaxNestedLevelError) Error

func (e *MaxNestedLevelError) Error() string

type NaNConvertMode

type NaNConvertMode int

NaNConvertMode specifies how to encode NaN and overrides ShortestFloatMode. ShortestFloatMode is not used for encoding Infinity and NaN values.

const (
	// NaNConvert7e00 always encodes NaN to 0xf97e00 (CBOR float16 = 0x7e00).
	NaNConvert7e00 NaNConvertMode = iota

	// NaNConvertNone never modifies or converts NaN to other representations
	// (float64 NaN stays float64, etc. even if it can use float16 without losing
	// any bits).
	NaNConvertNone

	// NaNConvertPreserveSignal converts NaN to the smallest form that preserves
	// value (quiet bit + payload) as described in RFC 7049bis Draft 12.
	NaNConvertPreserveSignal

	// NaNConvertQuiet always forces quiet bit = 1 and shortest form that preserves
	// NaN payload.
	NaNConvertQuiet
)

type RawMessage

type RawMessage []byte

RawMessage is a raw encoded CBOR value. It implements Marshaler and Unmarshaler interfaces and can be used to delay CBOR decoding or precompute a CBOR encoding.

func (RawMessage) MarshalCBOR

func (m RawMessage) MarshalCBOR() ([]byte, error)

MarshalCBOR returns m as the CBOR encoding of m.

func (*RawMessage) UnmarshalCBOR

func (m *RawMessage) UnmarshalCBOR(data []byte) error

UnmarshalCBOR sets *m to a copy of data.

type RawTag

type RawTag struct {
	Number  uint64
	Content RawMessage
}

RawTag represents CBOR tag data, including tag number and raw tag content. RawTag implements Unmarshaler and Marshaler interfaces.

func (RawTag) MarshalCBOR

func (t RawTag) MarshalCBOR() ([]byte, error)

MarshalCBOR returns CBOR encoding of t.

func (*RawTag) UnmarshalCBOR

func (t *RawTag) UnmarshalCBOR(data []byte) error

UnmarshalCBOR sets *t with tag number and raw tag content copied from data.

type SemanticError

type SemanticError struct {
	// contains filtered or unexported fields
}

SemanticError is a description of a CBOR semantic error.

func (*SemanticError) Error

func (e *SemanticError) Error() string

type ShortestFloatMode

type ShortestFloatMode int

ShortestFloatMode specifies which floating-point format should be used as the shortest possible format for CBOR encoding. It is not used for encoding Infinity and NaN values.

const (
	// ShortestFloatNone makes float values encode without any conversion.
	// This is the default for ShortestFloatMode in v1.
	// E.g. a float32 in Go will encode to CBOR float32.  And
	// a float64 in Go will encode to CBOR float64.
	ShortestFloatNone ShortestFloatMode = iota

	// ShortestFloat16 specifies float16 as the shortest form that preserves value.
	// E.g. if float64 can convert to float32 while preserving value, then
	// encoding will also try to convert float32 to float16.  So a float64 might
	// encode as CBOR float64, float32 or float16 depending on the value.
	ShortestFloat16
)

type SortMode

type SortMode int

SortMode identifies supported sorting order.

const (
	// SortNone means no sorting.
	SortNone SortMode = 0

	// SortLengthFirst causes map keys or struct fields to be sorted such that:
	//     - If two keys have different lengths, the shorter one sorts earlier;
	//     - If two keys have the same length, the one with the lower value in
	//       (byte-wise) lexical order sorts earlier.
	// It is used in "Canonical CBOR" encoding in RFC 7049 3.9.
	SortLengthFirst SortMode = 1

	// SortBytewiseLexical causes map keys or struct fields to be sorted in the
	// bytewise lexicographic order of their deterministic CBOR encodings.
	// It is used in "CTAP2 Canonical CBOR" and "Core Deterministic Encoding"
	// in RFC 7049bis.
	SortBytewiseLexical SortMode = 2

	// SortCanonical is used in "Canonical CBOR" encoding in RFC 7049 3.9.
	SortCanonical SortMode = SortLengthFirst

	// SortCTAP2 is used in "CTAP2 Canonical CBOR".
	SortCTAP2 SortMode = SortBytewiseLexical

	// SortCoreDeterministic is used in "Core Deterministic Encoding" in RFC 7049bis.
	SortCoreDeterministic SortMode = SortBytewiseLexical
)

type SyntaxError

type SyntaxError struct {
	// contains filtered or unexported fields
}

SyntaxError is a description of a CBOR syntax error.

func (*SyntaxError) Error

func (e *SyntaxError) Error() string

type Tag

type Tag struct {
	Number  uint64
	Content interface{}
}

Tag represents CBOR tag data, including tag number and unmarshaled tag content.

type TagOptions

type TagOptions struct {
	DecTag DecTagMode
	EncTag EncTagMode
}

TagOptions specifies how encoder and decoder handle tag number.

type TagSet

type TagSet interface {
	// Add adds given tag number(s), content type, and tag options to TagSet.
	Add(opts TagOptions, contentType reflect.Type, num uint64, nestedNum ...uint64) error

	// Remove removes given tag content type from TagSet.
	Remove(contentType reflect.Type)
	// contains filtered or unexported methods
}

TagSet is an interface to add and remove tag info. It is used by EncMode and DecMode to provide CBOR tag support.

func NewTagSet

func NewTagSet() TagSet

NewTagSet returns TagSet (safe for concurrency).

type TagsMdError

type TagsMdError struct {
}

TagsMdError indicates found disallowed CBOR tags.

func (*TagsMdError) Error

func (e *TagsMdError) Error() string

type TagsMode

type TagsMode int

TagsMode specifies whether to allow CBOR tags.

const (
	// TagsAllowed allows CBOR tags.
	TagsAllowed TagsMode = iota

	// TagsForbidden disallows CBOR tags.
	TagsForbidden
)

type TimeMode

type TimeMode int

TimeMode specifies how to encode time.Time values.

const (
	// TimeUnix causes time.Time to be encoded as epoch time in integer with second precision.
	TimeUnix TimeMode = iota

	// TimeUnixMicro causes time.Time to be encoded as epoch time in float-point rounded to microsecond precision.
	TimeUnixMicro

	// TimeUnixDynamic causes time.Time to be encoded as integer if time.Time doesn't have fractional seconds,
	// otherwise float-point rounded to microsecond precision.
	TimeUnixDynamic

	// TimeRFC3339 causes time.Time to be encoded as RFC3339 formatted string with second precision.
	TimeRFC3339

	// TimeRFC3339Nano causes time.Time to be encoded as RFC3339 formatted string with nanosecond precision.
	TimeRFC3339Nano
)

type UnmarshalTypeError

type UnmarshalTypeError struct {
	Value  string       // description of CBOR value
	Type   reflect.Type // type of Go value it could not be assigned to
	Struct string       // struct type containing the field
	Field  string       // name of the field holding the Go value
	// contains filtered or unexported fields
}

UnmarshalTypeError describes a CBOR value that was not appropriate for a Go type.

func (*UnmarshalTypeError) Error

func (e *UnmarshalTypeError) Error() string

type Unmarshaler

type Unmarshaler interface {
	UnmarshalCBOR([]byte) error
}

Unmarshaler is the interface implemented by types that can unmarshal a CBOR representation of themselves. The input can be assumed to be a valid encoding of a CBOR value. UnmarshalCBOR must copy the CBOR data if it wishes to retain the data after returning.

type UnsupportedTypeError

type UnsupportedTypeError struct {
	Type reflect.Type
}

UnsupportedTypeError is returned by Marshal when attempting to encode an unsupported value type.

func (*UnsupportedTypeError) Error

func (e *UnsupportedTypeError) Error() string

type WrongTagError

type WrongTagError struct {
	RegisteredType   reflect.Type
	RegisteredTagNum []uint64
	TagNum           []uint64
}

WrongTagError describes mismatch between CBOR tag and registered tag.

func (*WrongTagError) Error

func (e *WrongTagError) Error() string