fxamacker/cbor

fxamacker/cbor

fxamacker/cbor is a high-performance Go library for encoding and decoding CBOR (IETF STD 94 / RFC 8949) and CBOR Sequences (RFC 8742). It also supports Extended Diagnostic Notation (Appendix G of RFC 8610).

Key Features:

• Full Conformance: Complies with IETF STD 94.
• Security: Includes configurable limits to defend against malicious/adversarial CBOR data, preventing resource exhaustion attacks (unlike encoding/gob).
• Performance: Fast encoding/decoding without using Go's unsafe package. Rejects malformed data very efficiently.
• Data Size Optimization: Supports struct tags to reduce encoded size and can optionally shrink float64 to float32 or float16 if values fit.
• Usability: The API is designed to be similar to encoding/json, making it easy to adopt. Encoding and decoding modes can be created at startup and reused across goroutines.

fxamacker/cbor is a CBOR codec that provides full conformance with IETF STD 94 (RFC 8949). It also supports CBOR Sequences (RFC 8742) and Extended Diagnostic Notation (Appendix G of RFC 8610).

Key Features:

• CBOR tags: Supports both built-in and user-defined tags.
• Preferred serialization: Integers are encoded using the fewest possible bytes. Supports optional float64 → float32 → float16 downcasting.
• Map key sorting: Supports Unsorted, length-first (Canonical CBOR), and bytewise-lexicographic (CTAP2) modes.
• Duplicate map keys: Encoding always forbids duplicate keys. Decoding can be configured to allow or forbid them.
• Indefinite length data: Configurable options for both encoding and decoding.
• Security: Implements protections against integer overflow and resource exhaustion as per RFC 8949 Section 10.
• Well-formedness: All data is checked for well-formedness and syntax errors.

For specific requirements (like WebAuthn/CTAP2), you should create custom encoding and decoding modes. Modes are created from settings (EncOptions or DecOptions), are immutable once created, and are safe for concurrent use. It is recommended to create modes at startup and reuse them.

Available Presets:

• CoreDetEncOptions(): RFC 8949 Core Deterministic Encoding
• PreferredUnsortedEncOptions(): RFC 8949 Preferred Serialization
• CanonicalEncOptions(): RFC 7049 Canonical CBOR
• CTAP2EncOptions(): FIDO2 CTAP2 Canonical CBOR

// Create encoding mode.
opts := cbor.CoreDetEncOptions()   // use preset options as a starting point
opts.Time = cbor.TimeUnix          // change any settings if needed
em, err := opts.EncMode()          // create an immutable encoding mode

// Reuse the encoding mode. It is safe for concurrent use.

// API matches encoding/json.
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

You can use Go struct tags to automatically reduce the size of encoded data and improve performance.

Supported Struct Tags:

• toarray: Encodes the struct without field names (as an array). Note: When using toarray, the encoder ignores omitempty and omitzero to maintain fixed element positions for correct decoding.
• keyasint: Encodes field names as integers instead of strings.
• omitempty: Omits the field when it contains its zero value.
• omitzero: Omits the field when it contains its zero value.
• -: Omits the field entirely from encoding.

Using these tags can significantly reduce the footprint of your data (e.g., reducing a nested struct to just 1 byte of CBOR compared to 18 bytes of JSON).

type GrandChild struct {
	Quux int `cbor:"omitempty"` // Note: use cbor tag prefix for this library
}

type Child struct {
	Baz int        `cbor:"omitempty"` 
	Qux GrandChild `cbor:"omitempty"` 
}

type Parent struct {
	Foo Child `cbor:"omitempty"` 
	Bar int   `cbor:"omitempty"` 
}

The Encoder supports indefinite-length encoding, which allows you to write a sequence of items until a "break" code is sent. This is useful for streaming data of unknown size.

Supported types:

• StartIndefiniteArray(): For indefinite-length arrays.
• StartIndefiniteMap(): For indefinite-length maps. Note that maps must contain an even number of items (key-value pairs) before closing.
• StartIndefiniteByteString(): For indefinite-length byte strings.
• StartIndefiniteTextString(): For indefinite-length text strings.

Closing indefinite-length items: Call EndIndefinite() to write the CBOR "break" code and close the current indefinite-length container. If you call EndIndefinite() on a map with an odd number of items, it returns an IndefiniteLengthMapOddItemCountError and does not write the break code, allowing you to add the missing item and retry.

enc := cbor.NewEncoder(w)

// Encoding an indefinite array
enc.StartIndefiniteArray()
enc.Encode(1)
enc.Encode("hello")
enc.EndIndefinite()