1# CBOR Codec in Go 2 3[![](https://github.com/fxamacker/images/raw/master/cbor/v2.4.0/fxamacker_cbor_banner.png)](#cbor-library-in-go) 4 5[![](https://github.com/fxamacker/cbor/workflows/ci/badge.svg)](https://github.com/fxamacker/cbor/actions?query=workflow%3Aci) 6[![](https://github.com/fxamacker/cbor/workflows/cover%20%E2%89%A598%25/badge.svg)](https://github.com/fxamacker/cbor/actions?query=workflow%3A%22cover+%E2%89%A598%25%22) 7[![](https://github.com/fxamacker/cbor/workflows/linters/badge.svg)](https://github.com/fxamacker/cbor/actions?query=workflow%3Alinters) 8[![CodeQL](https://github.com/fxamacker/cbor/actions/workflows/codeql-analysis.yml/badge.svg)](https://github.com/fxamacker/cbor/actions/workflows/codeql-analysis.yml) 9[![](https://img.shields.io/badge/fuzzing-3%2B%20billion%20execs-44c010)](#fuzzing-and-code-coverage) 10[![Go Report Card](https://goreportcard.com/badge/github.com/fxamacker/cbor)](https://goreportcard.com/report/github.com/fxamacker/cbor) 11[![](https://img.shields.io/badge/go-%3E%3D%201.12-blue)](#cbor-library-installation) 12 13[__fxamacker/cbor__](https://github.com/fxamacker/cbor) is a modern [CBOR](https://tools.ietf.org/html/rfc8949) codec in [Go](https://golang.org). It's like `encoding/json` for CBOR with time-saving features. It balances [security](https://github.com/fxamacker/cbor/#cbor-security), usability, [speed](https://github.com/fxamacker/cbor/#cbor-performance), data size, program size, and other competing factors. 14 15Features include CBOR tags, duplicate map key detection, float64→32→16, and Go struct tags (`toarray`, `keyasint`, `omitempty`). API is close to `encoding/json` plus predefined CBOR options like Core Deterministic Encoding, Preferred Serialization, CTAP2, etc. 16 17Using CBOR [Preferred Serialization](https://www.rfc-editor.org/rfc/rfc8949.html#name-preferred-serialization) with Go struct tags (`toarray`, `keyasint`, `omitempty`) reduces programming effort and creates smaller encoded data size. 18 19fxamacker/cbor has 98% coverage and is fuzz tested. It won't exhaust RAM decoding 9 bytes of bad CBOR data. It's used by Arm Ltd., Berlin Institute of Health at Charité, Chainlink, ConsenSys, Dapper Labs, Duo Labs (cisco), EdgeX Foundry, Mozilla, Netherlands (govt), Oasis Labs, Taurus SA, Teleport, and others. 20 21Install with `go get github.com/fxamacker/cbor/v2` and `import "github.com/fxamacker/cbor/v2"`. 22See [Quick Start](#quick-start) to save time. 23 24## What is CBOR? 25 26[CBOR](https://tools.ietf.org/html/rfc8949) is a concise binary data format inspired by [JSON](https://www.json.org) and [MessagePack](https://msgpack.org). CBOR is defined in [RFC 8949](https://tools.ietf.org/html/rfc8949) (December 2020) which obsoletes [RFC 7049](https://tools.ietf.org/html/rfc7049) (October 2013). 27 28CBOR is an [Internet Standard](https://en.wikipedia.org/wiki/Internet_Standard) by [IETF](https://www.ietf.org). It's used in other standards like [WebAuthn](https://en.wikipedia.org/wiki/WebAuthn) by [W3C](https://www.w3.org), [COSE (RFC 8152)](https://tools.ietf.org/html/rfc8152), [CWT (RFC 8392)](https://tools.ietf.org/html/rfc8392), [CDDL (RFC 8610)](https://datatracker.ietf.org/doc/html/rfc8610) and [more](CBOR_GOLANG.md). 29 30[Reasons for choosing CBOR](https://github.com/fxamacker/cbor/wiki/Why-CBOR) vary by project. Some projects replaced protobuf, encoding/json, encoding/gob, etc. with CBOR. For example, by replacing protobuf with CBOR in gRPC. 31 32## Why fxamacker/cbor? 33 34fxamacker/cbor balances competing factors such as speed, size, safety, usability, maintainability, and etc. 35 36- Killer features include Go struct tags like `toarray`, `keyasint`, etc. They reduce encoded data size, improve speed, and reduce programming effort. For example, `toarray` automatically translates a Go struct to/from a CBOR array. 37 38- Modern CBOR features include Core Deterministic Encoding and Preferred Encoding. Other features include CBOR tags, big.Int, float64→32→16, an API like `encoding/json`, and more. 39 40- Security features include the option to detect duplicate map keys and options to set various max limits. And it's designed to make concurrent use of CBOR options easy and free from side-effects. 41 42- To prevent crashes, it has been fuzz-tested since before release 1.0 and code coverage is kept above 98%. 43 44- For portability and safety, it avoids using `unsafe`, which makes it portable and protected by Go1's compatibility guidelines. 45 46- For performance, it uses safe optimizations. When used properly, fxamacker/cbor can be faster than CBOR codecs that rely on `unsafe`. However, speed is only one factor and should be considered together with other competing factors. 47 48## CBOR Security 49 50__fxamacker/cbor__ is secure. It rejects malformed CBOR data and has an option to detect duplicate map keys. It doesn't crash when decoding bad CBOR data. It has extensive tests, coverage-guided fuzzing, data validation, and avoids Go's `unsafe` package. 51 52Decoding 9 or 10 bytes of malformed CBOR data shouldn't exhaust memory. For example, 53`[]byte{0x9B, 0x00, 0x00, 0x42, 0xFA, 0x42, 0xFA, 0x42, 0xFA, 0x42}` 54 55| | Decode bad 10 bytes to interface{} | Decode bad 10 bytes to []byte | 56| :--- | :------------------ | :--------------- | 57| fxamacker/cbor<br/>1.0-2.3 | 49.44 ns/op, 24 B/op, 2 allocs/op* | 51.93 ns/op, 32 B/op, 2 allocs/op* | 58| ugorji/go 1.2.6 | ⚠️ 45021 ns/op, 262852 B/op, 7 allocs/op | runtime: out of memory: cannot allocate | 59| ugorji/go 1.1-1.1.7 | runtime: out of memory: cannot allocate | runtime: out of memory: cannot allocate| 60 61*Speed and memory are for latest codec version listed in the row (compiled with Go 1.17.5). 62 63fxamacker/cbor CBOR safety settings include: MaxNestedLevels, MaxArrayElements, MaxMapPairs, and IndefLength. 64 65For more info, see: 66 - [RFC 8949 Section 10 (Security Considerations)](https://tools.ietf.org/html/rfc8949#section-10) or [RFC 7049 Section 8](https://tools.ietf.org/html/rfc7049#section-8). 67 - [Go warning](https://golang.org/pkg/unsafe/), "Packages that import unsafe may be non-portable and are not protected by the Go 1 compatibility guidelines." 68 69## CBOR Performance 70 71__fxamacker/cbor__ is fast without sacrificing security. It can be faster than libraries relying on `unsafe` package. 72 73![alt text](https://github.com/fxamacker/images/raw/master/cbor/v2.3.0/cbor_speed_comparison.svg?sanitize=1 "CBOR speed comparison chart") 74 75__Click to expand:__ 76 77<details> 78 <summary> CBOR Program Size Comparison </summary><p> 79 80__fxamacker/cbor__ produces smaller programs without sacrificing features. 81 82![alt text](https://github.com/fxamacker/images/raw/master/cbor/v2.3.0/cbor_size_comparison.svg?sanitize=1 "CBOR program size comparison chart") 83 84</details> 85 86<details><summary> fxamacker/cbor 2.3.0 (safe) vs ugorji/go 1.2.6 (unsafe)</summary><p> 87 88fxamacker/cbor 2.3.0 (not using `unsafe`) is faster than ugorji/go 1.2.6 (using `unsafe`). 89 90``` 91benchstat results/bench-ugorji-go-count20.txt results/bench-fxamacker-cbor-count20.txt 92name old time/op new time/op delta 93DecodeCWTClaims-8 1.08µs ± 0% 0.67µs ± 0% -38.10% (p=0.000 n=16+20) 94DecodeCOSE/128-Bit_Symmetric_Key-8 715ns ± 0% 501ns ± 0% -29.97% (p=0.000 n=20+19) 95DecodeCOSE/256-Bit_Symmetric_Key-8 722ns ± 0% 507ns ± 0% -29.72% (p=0.000 n=19+18) 96DecodeCOSE/ECDSA_P256_256-Bit_Key-8 1.11µs ± 0% 0.83µs ± 0% -25.27% (p=0.000 n=19+20) 97DecodeWebAuthn-8 880ns ± 0% 727ns ± 0% -17.31% (p=0.000 n=18+20) 98EncodeCWTClaims-8 785ns ± 0% 388ns ± 0% -50.51% (p=0.000 n=20+20) 99EncodeCOSE/128-Bit_Symmetric_Key-8 973ns ± 0% 433ns ± 0% -55.45% (p=0.000 n=20+19) 100EncodeCOSE/256-Bit_Symmetric_Key-8 974ns ± 0% 435ns ± 0% -55.37% (p=0.000 n=20+19) 101EncodeCOSE/ECDSA_P256_256-Bit_Key-8 1.14µs ± 0% 0.55µs ± 0% -52.10% (p=0.000 n=19+19) 102EncodeWebAuthn-8 564ns ± 0% 450ns ± 1% -20.18% (p=0.000 n=18+20) 103 104name old alloc/op new alloc/op delta 105DecodeCWTClaims-8 744B ± 0% 160B ± 0% -78.49% (p=0.000 n=20+20) 106DecodeCOSE/128-Bit_Symmetric_Key-8 792B ± 0% 232B ± 0% -70.71% (p=0.000 n=20+20) 107DecodeCOSE/256-Bit_Symmetric_Key-8 816B ± 0% 256B ± 0% -68.63% (p=0.000 n=20+20) 108DecodeCOSE/ECDSA_P256_256-Bit_Key-8 905B ± 0% 344B ± 0% -61.99% (p=0.000 n=20+20) 109DecodeWebAuthn-8 1.56kB ± 0% 0.99kB ± 0% -36.41% (p=0.000 n=20+20) 110EncodeCWTClaims-8 1.35kB ± 0% 0.18kB ± 0% -86.98% (p=0.000 n=20+20) 111EncodeCOSE/128-Bit_Symmetric_Key-8 1.95kB ± 0% 0.22kB ± 0% -88.52% (p=0.000 n=20+20) 112EncodeCOSE/256-Bit_Symmetric_Key-8 1.95kB ± 0% 0.24kB ± 0% -87.70% (p=0.000 n=20+20) 113EncodeCOSE/ECDSA_P256_256-Bit_Key-8 1.95kB ± 0% 0.32kB ± 0% -83.61% (p=0.000 n=20+20) 114EncodeWebAuthn-8 1.30kB ± 0% 1.09kB ± 0% -16.56% (p=0.000 n=20+20) 115 116name old allocs/op new allocs/op delta 117DecodeCWTClaims-8 6.00 ± 0% 6.00 ± 0% ~ (all equal) 118DecodeCOSE/128-Bit_Symmetric_Key-8 4.00 ± 0% 4.00 ± 0% ~ (all equal) 119DecodeCOSE/256-Bit_Symmetric_Key-8 4.00 ± 0% 4.00 ± 0% ~ (all equal) 120DecodeCOSE/ECDSA_P256_256-Bit_Key-8 7.00 ± 0% 7.00 ± 0% ~ (all equal) 121DecodeWebAuthn-8 5.00 ± 0% 5.00 ± 0% ~ (all equal) 122EncodeCWTClaims-8 4.00 ± 0% 2.00 ± 0% -50.00% (p=0.000 n=20+20) 123EncodeCOSE/128-Bit_Symmetric_Key-8 6.00 ± 0% 2.00 ± 0% -66.67% (p=0.000 n=20+20) 124EncodeCOSE/256-Bit_Symmetric_Key-8 6.00 ± 0% 2.00 ± 0% -66.67% (p=0.000 n=20+20) 125EncodeCOSE/ECDSA_P256_256-Bit_Key-8 6.00 ± 0% 2.00 ± 0% -66.67% (p=0.000 n=20+20) 126EncodeWebAuthn-8 4.00 ± 0% 2.00 ± 0% -50.00% (p=0.000 n=20+20) 127``` 128 </details> 129 130Benchmarks used Go 1.17.5, linux_amd64, and data from [RFC 8392 Appendix A.1](https://tools.ietf.org/html/rfc8392#appendix-A.1). Default build options were used for all CBOR libraries. Library init code was put outside the benchmark loop for all libraries compared. 131 132## CBOR API 133 134__fxamacker/cbor__ is easy to use. It provides standard API and interfaces. 135 136__Standard API__. Function signatures identical to [`encoding/json`](https://golang.org/pkg/encoding/json/) include: 137`Marshal`, `Unmarshal`, `NewEncoder`, `NewDecoder`, `(*Encoder).Encode`, and `(*Decoder).Decode`. 138 139__Standard Interfaces__. Custom encoding and decoding is handled by implementing: 140`BinaryMarshaler`, `BinaryUnmarshaler`, `Marshaler`, and `Unmarshaler`. 141 142__Predefined Encoding Options__. Encoding options are easy to use and are customizable. 143 144```go 145func CoreDetEncOptions() EncOptions {} // RFC 8949 Core Deterministic Encoding 146func PreferredUnsortedEncOptions() EncOptions {} // RFC 8949 Preferred Serialization 147func CanonicalEncOptions() EncOptions {} // RFC 7049 Canonical CBOR 148func CTAP2EncOptions() EncOptions {} // FIDO2 CTAP2 Canonical CBOR 149``` 150 151fxamacker/cbor designed to simplify concurrency. CBOR options can be used without creating unintended runtime side-effects. 152 153## Go Struct Tags 154 155__fxamacker/cbor__ provides Go struct tags like __`toarray`__ and __`keyasint`__ to save time and reduce encoded size of data. 156 157<br> 158 159![alt text](https://github.com/fxamacker/images/raw/master/cbor/v2.3.0/cbor_struct_tags_api.svg?sanitize=1 "CBOR API and Go Struct Tags") 160 161## CBOR Features 162 163__fxamacker/cbor__ is a full-featured CBOR encoder and decoder. 164 165| | CBOR Feature | Description | 166| :--- | :--- | :--- | 167| ☑️ | CBOR tags | API supports built-in and user-defined tags. | 168| ☑️ | Preferred serialization | Integers encode to fewest bytes. Optional float64 → float32 → float16. | 169| ☑️ | Map key sorting | Unsorted, length-first (Canonical CBOR), and bytewise-lexicographic (CTAP2). | 170| ☑️ | Duplicate map keys | Always forbid for encoding and option to allow/forbid for decoding. | 171| ☑️ | Indefinite length data | Option to allow/forbid for encoding and decoding. | 172| ☑️ | Well-formedness | Always checked and enforced. | 173| ☑️ | Basic validity checks | Check UTF-8 validity and optionally check duplicate map keys. | 174| ☑️ | Security considerations | Prevent integer overflow and resource exhaustion (RFC 8949 Section 10). | 175 176## CBOR Library Installation 177 178fxamacker/cbor supports Go 1.12 and newer versions. Init the Go module, go get v2, and begin coding. 179 180``` 181go mod init github.com/my_name/my_repo 182go get github.com/fxamacker/cbor/v2 183``` 184 185```go 186import "github.com/fxamacker/cbor/v2" // imports as cbor 187``` 188 189## Quick Start 190️ Use Go's `io.LimitReader` to limit size when decoding very large or indefinite size data. 191 192Import using "/v2" like this: `import "github.com/fxamacker/cbor/v2"`, and 193it will import version 2.x as package "cbor" (when using Go modules). 194 195Functions with identical signatures to encoding/json include: 196`Marshal`, `Unmarshal`, `NewEncoder`, `NewDecoder`, `(*Encoder).Encode`, `(*Decoder).Decode`. 197 198__Default Mode__ 199 200If default options are acceptable, package level functions can be used for encoding and decoding. 201 202```go 203b, err := cbor.Marshal(v) // encode v to []byte b 204err := cbor.Unmarshal(b, &v) // decode []byte b to v 205encoder := cbor.NewEncoder(w) // create encoder with io.Writer w 206decoder := cbor.NewDecoder(r) // create decoder with io.Reader r 207``` 208 209__Modes__ 210 211If you need to use options or CBOR tags, then you'll want to create a mode. 212 213"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`. 214 215EncMode and DecMode are interfaces created from EncOptions or DecOptions structs. 216For example, `em, err := cbor.EncOptions{...}.EncMode()` or `em, err := cbor.CanonicalEncOptions().EncMode()`. 217 218EncMode 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. 219 220__Creating and Using Encoding Modes__ 221 222 Avoid using init(). For best performance, reuse EncMode and DecMode after creating them. 223 224Most apps will probably create one EncMode and DecMode before init(). There's no limit and each can use different options. 225 226```go 227// Create EncOptions using either struct literal or a function. 228opts := cbor.CanonicalEncOptions() 229 230// If needed, modify opts. For example: opts.Time = cbor.TimeUnix 231 232// Create reusable EncMode interface with immutable options, safe for concurrent use. 233em, err := opts.EncMode() 234 235// Use EncMode like encoding/json, with same function signatures. 236b, err := em.Marshal(v) // encode v to []byte b 237 238encoder := em.NewEncoder(w) // create encoder with io.Writer w 239err := encoder.Encode(v) // encode v to io.Writer w 240``` 241 242Both `em.Marshal(v)` and `encoder.Encode(v)` use encoding options specified during creation of encoding mode `em`. 243 244__Creating Modes With CBOR Tags__ 245 246A TagSet is used to specify CBOR tags. 247 248```go 249em, err := opts.EncMode() // no tags 250em, err := opts.EncModeWithTags(ts) // immutable tags 251em, err := opts.EncModeWithSharedTags(ts) // mutable shared tags 252``` 253 254TagSet and all modes using it are safe for concurrent use. Equivalent API is available for DecMode. 255 256__Predefined Encoding Options__ 257 258```go 259func CoreDetEncOptions() EncOptions {} // RFC 8949 Core Deterministic Encoding 260func PreferredUnsortedEncOptions() EncOptions {} // RFC 8949 Preferred Serialization 261func CanonicalEncOptions() EncOptions {} // RFC 7049 Canonical CBOR 262func CTAP2EncOptions() EncOptions {} // FIDO2 CTAP2 Canonical CBOR 263``` 264 265The empty curly braces prevent a syntax highlighting bug on GitHub, please ignore them. 266 267__Struct Tags (keyasint, toarray, omitempty)__ 268 269The `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. 270 271The following sections provide more info: 272 273* [Struct Tags](#struct-tags-1) 274* [Decoding Options](#decoding-options) 275* [Encoding Options](#encoding-options) 276* [API](#api) 277* [Usage](#usage) 278 279<hr> 280 281⚓ [Quick Start](#quick-start) • [Features](#features) • [Standards](#standards) • [API](#api) • [Options](#options) • [Usage](#usage) • [Fuzzing](#fuzzing-and-code-coverage) • [License](#license) 282 283## Features 284 285### Standard API 286 287Many function signatures are identical to encoding/json, including: 288`Marshal`, `Unmarshal`, `NewEncoder`, `NewDecoder`, `(*Encoder).Encode`, `(*Decoder).Decode`. 289 290`RawMessage` can be used to delay CBOR decoding or precompute CBOR encoding, like `encoding/json`. 291 292Standard interfaces allow user-defined types to have custom CBOR encoding and decoding. They include: 293`BinaryMarshaler`, `BinaryUnmarshaler`, `Marshaler`, and `Unmarshaler`. 294 295`Marshaler` and `Unmarshaler` interfaces are satisfied by `MarshalCBOR` and `UnmarshalCBOR` functions using same params and return types as Go's MarshalJSON and UnmarshalJSON. 296 297### Struct Tags 298 299Support "cbor" and "json" keys in Go's struct tags. If both are specified for the same field, then "cbor" is used. 300 301* a different field name can be specified, like encoding/json. 302* `omitempty` omits (ignores) field if value is empty, like encoding/json. 303* `-` always omits (ignores) field, like encoding/json. 304* `keyasint` treats fields as elements of CBOR maps with specified int key. 305* `toarray` treats fields as elements of CBOR arrays. 306 307See [Struct Tags](#struct-tags-1) for more info. 308 309### CBOR Tags (New in v2.1) 310 311There are three categories of CBOR tags: 312 313* __Default built-in CBOR tags__ currently include tag numbers 0 (Standard Date/Time), 1 (Epoch Date/Time), 2 (Unsigned Bignum), 3 (Negative Bignum), 55799 (Self-Described CBOR). 314 315* __Optional built-in CBOR tags__ may be provided in the future via build flags or optional package(s) to help reduce bloat. 316 317* __User-defined CBOR tags__ are easy by using TagSet to associate tag numbers to user-defined Go types. 318 319### Preferred Serialization 320 321Preferred serialization encodes integers and floating-point values using the fewest bytes possible. 322 323* Integers are always encoded using the fewest bytes possible. 324* Floating-point values can optionally encode from float64->float32->float16 when values fit. 325 326### Compact Data Size 327 328The combination of preferred serialization and struct tags (toarray, keyasint, omitempty) allows very compact data size. 329 330### Predefined Encoding Options 331 332Easy-to-use functions (no params) return preset EncOptions struct: 333`CanonicalEncOptions`, `CTAP2EncOptions`, `CoreDetEncOptions`, `PreferredUnsortedEncOptions` 334 335### Encoding Options 336 337Integers always encode to the shortest form that preserves value. By default, time values are encoded without tags. 338 339Encoding of other data types and map key sort order are determined by encoder options. 340 341| EncOptions | Available Settings (defaults listed first) 342| :--- | :--- | 343| Sort | **SortNone**, SortLengthFirst, SortBytewiseLexical <br/> Aliases: SortCanonical, SortCTAP2, SortCoreDeterministic | 344| Time | **TimeUnix**, TimeUnixMicro, TimeUnixDynamic, TimeRFC3339, TimeRFC3339Nano | 345| TimeTag | **EncTagNone**, EncTagRequired | 346| ShortestFloat | **ShortestFloatNone**, ShortestFloat16 | 347| BigIntConvert | **BigIntConvertShortest**, BigIntConvertNone | 348| InfConvert | **InfConvertFloat16**, InfConvertNone | 349| NaNConvert | **NaNConvert7e00**, NaNConvertNone, NaNConvertQuiet, NaNConvertPreserveSignal | 350| IndefLength | **IndefLengthAllowed**, IndefLengthForbidden | 351| TagsMd | **TagsAllowed**, TagsForbidden | 352 353See [Options](#options) section for details about each setting. 354 355### Decoding Options 356 357| DecOptions | Available Settings (defaults listed first) | 358| :--- | :--- | 359| TimeTag | **DecTagIgnored**, DecTagOptional, DecTagRequired | 360| DupMapKey | **DupMapKeyQuiet**, DupMapKeyEnforcedAPF | 361| IntDec | **IntDecConvertNone**, IntDecConvertSigned | 362| IndefLength | **IndefLengthAllowed**, IndefLengthForbidden | 363| TagsMd | **TagsAllowed**, TagsForbidden | 364| ExtraReturnErrors | **ExtraDecErrorNone**, ExtraDecErrorUnknownField | 365| MaxNestedLevels | **32**, can be set to [4, 256] | 366| MaxArrayElements | **131072**, can be set to [16, 2147483647] | 367| MaxMapPairs | **131072**, can be set to [16, 2147483647] | 368 369See [Options](#options) section for details about each setting. 370 371### Additional Features 372 373* Decoder always checks for invalid UTF-8 string errors. 374* Decoder always decodes in-place to slices, maps, and structs. 375* Decoder tries case-sensitive first and falls back to case-insensitive field name match when decoding to structs. 376* Decoder supports decoding registered CBOR tag data to interface types. 377* Both encoder and decoder support indefinite length CBOR data (["streaming"](https://tools.ietf.org/html/rfc7049#section-2.2)). 378* Both encoder and decoder correctly handles nil slice, map, pointer, and interface values. 379 380<hr> 381 382⚓ [Quick Start](#quick-start) • [Features](#features) • [Standards](#standards) • [API](#api) • [Options](#options) • [Usage](#usage) • [Fuzzing](#fuzzing-and-code-coverage) • [License](#license) 383 384## Standards 385This library is a full-featured generic CBOR [(RFC 8949)](https://tools.ietf.org/html/rfc8949) encoder and decoder. Notable CBOR features include: 386 387| | CBOR Feature | Description | 388| :--- | :--- | :--- | 389| ☑️ | CBOR tags | API supports built-in and user-defined tags. | 390| ☑️ | Preferred serialization | Integers encode to fewest bytes. Optional float64 → float32 → float16. | 391| ☑️ | Map key sorting | Unsorted, length-first (Canonical CBOR), and bytewise-lexicographic (CTAP2). | 392| ☑️ | Duplicate map keys | Always forbid for encoding and option to allow/forbid for decoding. | 393| ☑️ | Indefinite length data | Option to allow/forbid for encoding and decoding. | 394| ☑️ | Well-formedness | Always checked and enforced. | 395| ☑️ | Basic validity checks | Check UTF-8 validity and optionally check duplicate map keys. | 396| ☑️ | Security considerations | Prevent integer overflow and resource exhaustion (RFC 8949 Section 10). | 397 398See the Features section for list of [Encoding Options](#encoding-options) and [Decoding Options](#decoding-options). 399 400Known limitations are noted in the [Limitations section](#limitations). 401 402Go nil values for slices, maps, pointers, etc. are encoded as CBOR null. Empty slices, maps, etc. are encoded as empty CBOR arrays and maps. 403 404Decoder checks for all required well-formedness errors, including all "subkinds" of syntax errors and too little data. 405 406After well-formedness is verified, basic validity errors are handled as follows: 407 408* Invalid UTF-8 string: Decoder always checks and returns invalid UTF-8 string error. 409* Duplicate keys in a map: Decoder has options to ignore or enforce rejection of duplicate map keys. 410 411When 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. 412 413By default, decoder treats time values of floating-point NaN and Infinity as if they are CBOR Null or CBOR Undefined. 414 415See [Options](#options) section for detailed settings or [Features](#features) section for a summary of options. 416 417__Click to expand topic:__ 418 419<details> 420 <summary>Duplicate Map Keys</summary><p> 421 422This 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. 423 424`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. 425 426`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. 427 428APF 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. 429 430</details> 431 432<details> 433 <summary>Tag Validity</summary><p> 434 435This library checks tag validity for built-in tags (currently tag numbers 0, 1, 2, 3, and 55799): 436 437* Inadmissible type for tag content 438* Inadmissible value for tag content 439 440Unknown tag data items (not tag number 0, 1, 2, 3, or 55799) are handled in two ways: 441 442* When decoding into an empty interface, unknown tag data item will be decoded into `cbor.Tag` data type, which contains tag number and tag content. The tag content will be decoded into the default Go data type for the CBOR data type. 443* When decoding into other Go types, unknown tag data item is decoded into the specified Go type. If Go type is registered with a tag number, the tag number can optionally be verified. 444 445Decoder also has an option to forbid tag data items (treat any tag data item as error) which is specified by protocols such as CTAP2 Canonical CBOR. 446 447For more information, see [decoding options](#decoding-options-1) and [tag options](#tag-options). 448 449</details> 450 451## Limitations 452 453If any of these limitations prevent you from using this library, please open an issue along with a link to your project. 454 455* CBOR `Undefined` (0xf7) value decodes to Go's `nil` value. CBOR `Null` (0xf6) more closely matches Go's `nil`. 456* 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. 457* When using io.Reader interface to read very large or indefinite length CBOR data, Go's `io.LimitReader` should be used to limit size. 458* When decoding registered CBOR tag data to interface type, decoder creates a pointer to registered Go type matching CBOR tag number. Requiring a pointer for this is a Go limitation. 459 460<hr> 461 462⚓ [Quick Start](#quick-start) • [Features](#features) • [Standards](#standards) • [API](#api) • [Options](#options) • [Usage](#usage) • [Fuzzing](#fuzzing-and-code-coverage) • [License](#license) 463 464## API 465Many function signatures are identical to Go's encoding/json, such as: 466`Marshal`, `Unmarshal`, `NewEncoder`, `NewDecoder`, `(*Encoder).Encode`, and `(*Decoder).Decode`. 467 468Interfaces identical or comparable to Go's encoding, encoding/json, or encoding/gob include: 469`Marshaler`, `Unmarshaler`, `BinaryMarshaler`, and `BinaryUnmarshaler`. 470 471Like `encoding/json`, `RawMessage` can be used to delay CBOR decoding or precompute CBOR encoding. 472 473"Mode" in this API means defined way of encoding or decoding -- it links the standard API to CBOR options and CBOR tags. 474 475EncMode and DecMode are interfaces created from EncOptions or DecOptions structs. 476For example, `em, err := cbor.EncOptions{...}.EncMode()` or `em, err := cbor.CanonicalEncOptions().EncMode()`. 477 478EncMode 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. 479 480__API for Default Mode__ 481 482If default options are acceptable, then you don't need to create EncMode or DecMode. 483 484```go 485Marshal(v interface{}) ([]byte, error) 486NewEncoder(w io.Writer) *Encoder 487 488Unmarshal(data []byte, v interface{}) error 489NewDecoder(r io.Reader) *Decoder 490``` 491 492__API for Creating & Using Encoding Modes__ 493 494```go 495// EncMode interface uses immutable options and is safe for concurrent use. 496type EncMode interface { 497 Marshal(v interface{}) ([]byte, error) 498 NewEncoder(w io.Writer) *Encoder 499 EncOptions() EncOptions // returns copy of options 500} 501 502// EncOptions specifies encoding options. 503type EncOptions struct { 504... 505} 506 507// EncMode returns an EncMode interface created from EncOptions. 508func (opts EncOptions) EncMode() (EncMode, error) {} 509 510// EncModeWithTags returns EncMode with options and tags that are both immutable. 511func (opts EncOptions) EncModeWithTags(tags TagSet) (EncMode, error) {} 512 513// EncModeWithSharedTags returns EncMode with immutable options and mutable shared tags. 514func (opts EncOptions) EncModeWithSharedTags(tags TagSet) (EncMode, error) {} 515``` 516 517The empty curly braces prevent a syntax highlighting bug, please ignore them. 518 519__API for Predefined Encoding Options__ 520 521```go 522func CoreDetEncOptions() EncOptions {} // RFC 8949 Core Deterministic Encoding 523func PreferredUnsortedEncOptions() EncOptions {} // RFC 8949 Preferred Serialization 524func CanonicalEncOptions() EncOptions {} // RFC 7049 Canonical CBOR 525func CTAP2EncOptions() EncOptions {} // FIDO2 CTAP2 Canonical CBOR 526``` 527 528__API for Creating & Using Decoding Modes__ 529 530```go 531// DecMode interface uses immutable options and is safe for concurrent use. 532type DecMode interface { 533 Unmarshal(data []byte, v interface{}) error 534 NewDecoder(r io.Reader) *Decoder 535 DecOptions() DecOptions // returns copy of options 536} 537 538// DecOptions specifies decoding options. 539type DecOptions struct { 540... 541} 542 543// DecMode returns a DecMode interface created from DecOptions. 544func (opts DecOptions) DecMode() (DecMode, error) {} 545 546// DecModeWithTags returns DecMode with options and tags that are both immutable. 547func (opts DecOptions) DecModeWithTags(tags TagSet) (DecMode, error) {} 548 549// DecModeWithSharedTags returns DecMode with immutable options and mutable shared tags. 550func (opts DecOptions) DecModeWithSharedTags(tags TagSet) (DecMode, error) {} 551``` 552 553The empty curly braces prevent a syntax highlighting bug, please ignore them. 554 555__API for Using CBOR Tags__ 556 557`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. 558 559`Tag` and `RawTag` can be used to encode/decode a tag number with a Go value, but `TagSet` is generally recommended. 560 561```go 562type TagSet interface { 563 // Add adds given tag number(s), content type, and tag options to TagSet. 564 Add(opts TagOptions, contentType reflect.Type, num uint64, nestedNum ...uint64) error 565 566 // Remove removes given tag content type from TagSet. 567 Remove(contentType reflect.Type) 568} 569``` 570 571`Tag` and `RawTag` types can also be used to encode/decode tag number with Go value. 572 573```go 574type Tag struct { 575 Number uint64 576 Content interface{} 577} 578 579type RawTag struct { 580 Number uint64 581 Content RawMessage 582} 583``` 584 585See [API docs (godoc.org)](https://godoc.org/github.com/fxamacker/cbor) for more details and more functions. See [Usage section](#usage) for usage and code examples. 586 587<hr> 588 589⚓ [Quick Start](#quick-start) • [Features](#features) • [Standards](#standards) • [API](#api) • [Options](#options) • [Usage](#usage) • [Fuzzing](#fuzzing-and-code-coverage) • [License](#license) 590 591## Options 592 593Struct tags, decoding options, and encoding options. 594 595### Struct Tags 596 597This library supports both "cbor" and "json" key for some (not all) struct tags. If "cbor" and "json" keys are both present for the same field, then "cbor" key will be used. 598 599| Key | Format Str | Scope | Description | 600| --- | ---------- | ----- | ------------| 601| cbor or json | "myName" | field | Name of field to use such as "myName", etc. like encoding/json. | 602| cbor or json | ",omitempty" | field | Omit (ignore) this field if value is empty, like encoding/json. | 603| cbor or json | "-" | field | Omit (ignore) this field always, like encoding/json. | 604| cbor | ",keyasint" | field | Treat field as an element of CBOR map with specified int as key. | 605| cbor | ",toarray" | struct | Treat each field as an element of CBOR array. This automatically disables "omitempty" and "keyasint" for all fields in the struct. | 606 607The "keyasint" struct tag requires an integer key to be specified: 608 609``` 610type myStruct struct { 611 MyField int64 `cbor:"-1,keyasint,omitempty'` 612 OurField string `cbor:"0,keyasint,omitempty"` 613 FooField Foo `cbor:"5,keyasint,omitempty"` 614 BarField Bar `cbor:"hello,omitempty"` 615 ... 616} 617``` 618 619The "toarray" struct tag requires a special field "_" (underscore) to indicate "toarray" applies to the entire struct: 620 621``` 622type myStruct struct { 623 _ struct{} `cbor:",toarray"` 624 MyField int64 625 OurField string 626 ... 627} 628``` 629 630__Click to expand:__ 631 632<details> 633 <summary>Example Using CBOR Web Tokens</summary><p> 634 635![alt text](https://github.com/fxamacker/images/raw/master/cbor/v2.3.0/cbor_struct_tags_api.svg?sanitize=1 "CBOR API and Go Struct Tags") 636 637</details> 638 639### Decoding Options 640 641| DecOptions.TimeTag | Description | 642| ------------------ | ----------- | 643| DecTagIgnored (default) | Tag numbers are ignored (if present) for time values. | 644| DecTagOptional | Tag numbers are only checked for validity if present for time values. | 645| DecTagRequired | Tag numbers must be provided for time values except for CBOR Null and CBOR Undefined. | 646 647The following CBOR time values are decoded as Go's "zero time instant": 648 649* CBOR Null 650* CBOR Undefined 651* CBOR floating-point NaN 652* CBOR floating-point Infinity 653 654Go's `time` package provides `IsZero` function, which reports whether t represents "zero time instant" 655(January 1, year 1, 00:00:00 UTC). 656 657<br> 658 659| DecOptions.DupMapKey | Description | 660| -------------------- | ----------- | 661| 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. | 662| 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. | 663 664`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. 665 666<br> 667 668| DecOptions.IntDec | Description | 669| ------------------ | ----------- | 670| IntDecConvertNone (default) | When decoding to Go interface{}, CBOR positive int (major type 0) decode to uint64 value, and CBOR negative int (major type 1) decode to int64 value. | 671| IntDecConvertSigned | When decoding to Go interface{}, CBOR positive/negative int (major type 0 and 1) decode to int64 value. | 672 673If `IntDecConvertedSigned` is used and value overflows int64, UnmarshalTypeError is returned. 674 675<br> 676 677| DecOptions.IndefLength | Description | 678| ---------------------- | ----------- | 679|IndefLengthAllowed (default) | allow indefinite length data | 680|IndefLengthForbidden | forbid indefinite length data | 681 682<br> 683 684| DecOptions.TagsMd | Description | 685| ----------------- | ----------- | 686|TagsAllowed (default) | allow CBOR tags (major type 6) | 687|TagsForbidden | forbid CBOR tags (major type 6) | 688 689<br> 690 691| DecOptions.ExtraReturnErrors | Description | 692| ----------------- | ----------- | 693|ExtraDecErrorNone (default) | no extra decoding errors. E.g. ignore unknown fields if encountered. | 694|ExtraDecErrorUnknownField | return error if unknown field is encountered | 695 696<br> 697 698| DecOptions.MaxNestedLevels | Description | 699| -------------------------- | ----------- | 700| 32 (default) | allowed setting is [4, 256] | 701 702<br> 703 704| DecOptions.MaxArrayElements | Description | 705| --------------------------- | ----------- | 706| 131072 (default) | allowed setting is [16, 2147483647] | 707 708<br> 709 710| DecOptions.MaxMapPairs | Description | 711| ---------------------- | ----------- | 712| 131072 (default) | allowed setting is [16, 2147483647] | 713 714### Encoding Options 715 716__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. 717 718These functions are provided to create and return a modifiable EncOptions struct with predefined settings. 719 720| Predefined EncOptions | Description | 721| --------------------- | ----------- | 722| CanonicalEncOptions() |[Canonical CBOR (RFC 7049 Section 3.9)](https://tools.ietf.org/html/rfc7049#section-3.9). | 723| CTAP2EncOptions() |[CTAP2 Canonical CBOR (FIDO2 CTAP2)](https://fidoalliance.org/specs/fido-v2.0-id-20180227/fido-client-to-authenticator-protocol-v2.0-id-20180227.html#ctap2-canonical-cbor-encoding-form). | 724| PreferredUnsortedEncOptions() |Unsorted, encode float64->float32->float16 when values fit, NaN values encoded as float16 0x7e00. | 725| CoreDetEncOptions() |PreferredUnsortedEncOptions() + map keys are sorted bytewise lexicographic. | 726 727<br> 728 729| EncOptions.Sort | Description | 730| --------------- | ----------- | 731| SortNone (default) |No sorting for map keys. | 732| SortLengthFirst |Length-first map key ordering. | 733| SortBytewiseLexical |Bytewise lexicographic map key ordering [(RFC 8949 Section 4.2.1)](https://datatracker.ietf.org/doc/html/rfc8949#section-4.2.1).| 734| SortCanonical |(alias) Same as SortLengthFirst [(RFC 7049 Section 3.9)](https://tools.ietf.org/html/rfc7049#section-3.9) | 735| SortCTAP2 |(alias) Same as SortBytewiseLexical [(CTAP2 Canonical CBOR)](https://fidoalliance.org/specs/fido-v2.0-id-20180227/fido-client-to-authenticator-protocol-v2.0-id-20180227.html#ctap2-canonical-cbor-encoding-form). | 736| SortCoreDeterministic |(alias) Same as SortBytewiseLexical [(RFC 8949 Section 4.2.1)](https://datatracker.ietf.org/doc/html/rfc8949#section-4.2.1). | 737 738<br> 739 740| EncOptions.Time | Description | 741| --------------- | ----------- | 742| TimeUnix (default) | (seconds) Encode as integer. | 743| TimeUnixMicro | (microseconds) Encode as floating-point. ShortestFloat option determines size. | 744| TimeUnixDynamic | (seconds or microseconds) Encode as integer if time doesn't have fractional seconds, otherwise encode as floating-point rounded to microseconds. | 745| TimeRFC3339 | (seconds) Encode as RFC 3339 formatted string. | 746| TimeRFC3339Nano | (nanoseconds) Encode as RFC3339 formatted string. | 747 748<br> 749 750| EncOptions.TimeTag | Description | 751| ------------------ | ----------- | 752| EncTagNone (default) | Tag number will not be encoded for time values. | 753| EncTagRequired | Tag number (0 or 1) will be encoded unless time value is undefined/zero-instant. | 754 755By 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. 756 757Go's `time` package provides `IsZero` function, which reports whether t represents the zero time instant, January 1, year 1, 00:00:00 UTC. 758 759<br> 760 761| EncOptions.BigIntConvert | Description | 762| ------------------------ | ----------- | 763| BigIntConvertShortest (default) | Encode big.Int as CBOR integer if value fits. | 764| BigIntConvertNone | Encode big.Int as CBOR bignum (tag 2 or 3). | 765 766<br> 767 768__Floating-Point Options__ 769 770Encoder has 3 types of options for floating-point data: ShortestFloatMode, InfConvertMode, and NaNConvertMode. 771 772| EncOptions.ShortestFloat | Description | 773| ------------------------ | ----------- | 774| ShortestFloatNone (default) | No size conversion. Encode float32 and float64 to CBOR floating-point of same bit-size. | 775| ShortestFloat16 | Encode float64 -> float32 -> float16 ([IEEE 754 binary16](https://en.wikipedia.org/wiki/Half-precision_floating-point_format)) when values fit. | 776 777Conversions for infinity and NaN use InfConvert and NaNConvert settings. 778 779| EncOptions.InfConvert | Description | 780| --------------------- | ----------- | 781| InfConvertFloat16 (default) | Convert +- infinity to float16 since they always preserve value (recommended) | 782| InfConvertNone |Don't convert +- infinity to other representations -- used by CTAP2 Canonical CBOR | 783 784<br> 785 786| EncOptions.NaNConvert | Description | 787| --------------------- | ----------- | 788| NaNConvert7e00 (default) | Encode to 0xf97e00 (CBOR float16 = 0x7e00) -- used by RFC 8949 Preferred Encoding, etc. | 789| NaNConvertNone | Don't convert NaN to other representations -- used by CTAP2 Canonical CBOR. | 790| NaNConvertQuiet | Force quiet bit = 1 and use shortest form that preserves NaN payload. | 791| NaNConvertPreserveSignal | Convert to smallest form that preserves value (quit bit unmodified and NaN payload preserved). | 792 793<br> 794 795| EncOptions.IndefLength | Description | 796| ---------------------- | ----------- | 797|IndefLengthAllowed (default) | allow indefinite length data | 798|IndefLengthForbidden | forbid indefinite length data | 799 800<br> 801 802| EncOptions.TagsMd | Description | 803| ----------------- | ----------- | 804|TagsAllowed (default) | allow CBOR tags (major type 6) | 805|TagsForbidden | forbid CBOR tags (major type 6) | 806 807 808### Tag Options 809 810TagOptions specifies how encoder and decoder handle tag number registered with TagSet. 811 812| TagOptions.DecTag | Description | 813| ------------------ | ----------- | 814| DecTagIgnored (default) | Tag numbers are ignored (if present). | 815| DecTagOptional | Tag numbers are only checked for validity if present. | 816| DecTagRequired | Tag numbers must be provided except for CBOR Null and CBOR Undefined. | 817 818<br> 819 820| TagOptions.EncTag | Description | 821| ------------------ | ----------- | 822| EncTagNone (default) | Tag number will not be encoded. | 823| EncTagRequired | Tag number will be encoded. | 824 825<hr> 826 827⚓ [Quick Start](#quick-start) • [Features](#features) • [Standards](#standards) • [API](#api) • [Options](#options) • [Usage](#usage) • [Fuzzing](#fuzzing-and-code-coverage) • [License](#license) 828 829## Usage 830️ Use Go's `io.LimitReader` to limit size when decoding very large or indefinite size data. 831 832Functions with identical signatures to encoding/json include: 833`Marshal`, `Unmarshal`, `NewEncoder`, `NewDecoder`, `(*Encoder).Encode`, `(*Decoder).Decode`. 834 835__Default Mode__ 836 837If default options are acceptable, package level functions can be used for encoding and decoding. 838 839```go 840b, err := cbor.Marshal(v) // encode v to []byte b 841 842err := cbor.Unmarshal(b, &v) // decode []byte b to v 843 844encoder := cbor.NewEncoder(w) // create encoder with io.Writer w 845 846decoder := cbor.NewDecoder(r) // create decoder with io.Reader r 847``` 848 849__Modes__ 850 851If you need to use options or CBOR tags, then you'll want to create a mode. 852 853"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`. 854 855EncMode and DecMode are interfaces created from EncOptions or DecOptions structs. 856For example, `em, err := cbor.EncOptions{...}.EncMode()` or `em, err := cbor.CanonicalEncOptions().EncMode()`. 857 858EncMode 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. 859 860__Creating and Using Encoding Modes__ 861 862EncMode is an interface ([API](#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. 863 864```go 865// Create EncOptions using either struct literal or a function. 866opts := cbor.CanonicalEncOptions() 867 868// If needed, modify opts. For example: opts.Time = cbor.TimeUnix 869 870// Create reusable EncMode interface with immutable options, safe for concurrent use. 871em, err := opts.EncMode() 872 873// Use EncMode like encoding/json, with same function signatures. 874b, err := em.Marshal(v) // encode v to []byte b 875 876encoder := em.NewEncoder(w) // create encoder with io.Writer w 877err := encoder.Encode(v) // encode v to io.Writer w 878``` 879 880__Struct Tags (keyasint, toarray, omitempty)__ 881 882The `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. 883 884<hr> 885 886![alt text](https://github.com/fxamacker/images/raw/master/cbor/v2.3.0/cbor_struct_tags_api.svg?sanitize=1 "CBOR API and Struct Tags") 887 888<hr> 889 890__Decoding CWT (CBOR Web Token)__ using `keyasint` and `toarray` struct tags: 891 892```go 893// Signed CWT is defined in RFC 8392 894type signedCWT struct { 895 _ struct{} `cbor:",toarray"` 896 Protected []byte 897 Unprotected coseHeader 898 Payload []byte 899 Signature []byte 900} 901 902// Part of COSE header definition 903type coseHeader struct { 904 Alg int `cbor:"1,keyasint,omitempty"` 905 Kid []byte `cbor:"4,keyasint,omitempty"` 906 IV []byte `cbor:"5,keyasint,omitempty"` 907} 908 909// data is []byte containing signed CWT 910 911var v signedCWT 912if err := cbor.Unmarshal(data, &v); err != nil { 913 return err 914} 915``` 916 917__Encoding CWT (CBOR Web Token)__ using `keyasint` and `toarray` struct tags: 918 919```go 920// Use signedCWT struct defined in "Decoding CWT" example. 921 922var v signedCWT 923... 924if data, err := cbor.Marshal(v); err != nil { 925 return err 926} 927``` 928 929__Encoding and Decoding CWT (CBOR Web Token) with CBOR Tags__ 930 931```go 932// Use signedCWT struct defined in "Decoding CWT" example. 933 934// Create TagSet (safe for concurrency). 935tags := cbor.NewTagSet() 936// Register tag COSE_Sign1 18 with signedCWT type. 937tags.Add( 938 cbor.TagOptions{EncTag: cbor.EncTagRequired, DecTag: cbor.DecTagRequired}, 939 reflect.TypeOf(signedCWT{}), 940 18) 941 942// Create DecMode with immutable tags. 943dm, _ := cbor.DecOptions{}.DecModeWithTags(tags) 944 945// Unmarshal to signedCWT with tag support. 946var v signedCWT 947if err := dm.Unmarshal(data, &v); err != nil { 948 return err 949} 950 951// Create EncMode with immutable tags. 952em, _ := cbor.EncOptions{}.EncModeWithTags(tags) 953 954// Marshal signedCWT with tag number. 955if data, err := cbor.Marshal(v); err != nil { 956 return err 957} 958``` 959 960For more examples, see [examples_test.go](example_test.go). 961 962<hr> 963 964⚓ [Quick Start](#quick-start) • [Features](#features) • [Standards](#standards) • [API](#api) • [Options](#options) • [Usage](#usage) • [Fuzzing](#fuzzing-and-code-coverage) • [License](#license) 965 966## Comparisons 967 968Comparisons 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. 969 970__This library is safer__. Small malicious CBOR messages are rejected quickly before they exhaust system resources. 971 972Decoding 9 or 10 bytes of malformed CBOR data shouldn't exhaust memory. For example, 973`[]byte{0x9B, 0x00, 0x00, 0x42, 0xFA, 0x42, 0xFA, 0x42, 0xFA, 0x42}` 974 975| | Decode bad 10 bytes to interface{} | Decode bad 10 bytes to []byte | 976| :--- | :------------------ | :--------------- | 977| fxamacker/cbor<br/>1.0-2.3 | 49.44 ns/op, 24 B/op, 2 allocs/op* | 51.93 ns/op, 32 B/op, 2 allocs/op* | 978| ugorji/go 1.2.6 | ⚠️ 45021 ns/op, 262852 B/op, 7 allocs/op | runtime: out of memory: cannot allocate | 979| ugorji/go 1.1.0-1.1.7 | runtime: out of memory: cannot allocate | runtime: out of memory: cannot allocate| 980 981*Speed and memory are for latest codec version listed in the row (compiled with Go 1.17.5). 982 983fxamacker/cbor CBOR safety settings include: MaxNestedLevels, MaxArrayElements, MaxMapPairs, and IndefLength. 984 985__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. 986 987![alt text](https://github.com/fxamacker/images/raw/master/cbor/v2.3.0/cbor_size_comparison.svg?sanitize=1 "CBOR speed comparison chart") 988 989 990__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. 991 992![alt text](https://github.com/fxamacker/images/raw/master/cbor/v2.3.0/cbor_speed_comparison.svg?sanitize=1 "CBOR speed comparison chart") 993 994__This library uses less memory__ for encoding and decoding CBOR Web Token (CWT) using test data from RFC 8392 A.1. 995 996| | fxamacker/cbor 2.3 | ugorji/go 1.2.6 | 997| :--- | :--- | :--- | 998| Encode CWT | 0.18 kB/op 2 allocs/op | 1.35 kB/op 4 allocs/op | 999| Decode CWT | 160 bytes/op 6 allocs/op | 744 bytes/op 6 allocs/op | 1000 1001Running your own benchmarks is highly recommended. Use your most common data structures and data sizes. 1002 1003<hr> 1004 1005⚓ [Quick Start](#quick-start) • [Features](#features) • [Standards](#standards) • [API](#api) • [Options](#options) • [Usage](#usage) • [Fuzzing](#fuzzing-and-code-coverage) • [License](#license) 1006 1007## Benchmarks 1008 1009Go structs are faster than maps with string keys: 1010 1011* decoding into struct is >28% faster than decoding into map. 1012* encoding struct is >35% faster than encoding map. 1013 1014Go structs with `keyasint` struct tag are faster than maps with integer keys: 1015 1016* decoding into struct is >28% faster than decoding into map. 1017* encoding struct is >34% faster than encoding map. 1018 1019Go structs with `toarray` struct tag are faster than slice: 1020 1021* decoding into struct is >15% faster than decoding into slice. 1022* encoding struct is >12% faster than encoding slice. 1023 1024Doing your own benchmarks is highly recommended. Use your most common message sizes and data types. 1025 1026See [Benchmarks for fxamacker/cbor](CBOR_BENCHMARKS.md). 1027 1028## Fuzzing and Code Coverage 1029 1030__Over 375 tests__ must pass on 4 architectures before tagging a release. They include all RFC 7049 and RFC 8949 examples, bugs found by fuzzing, maliciously crafted CBOR data, and over 87 tests with malformed data. There's some overlap in the tests but it isn't a high priority to trim tests. 1031 1032__Code coverage__ must not fall below 95% when tagging a release. Code coverage is above 98% (`go test -cover`) for cbor v2.3 which is among the highest for libraries (in Go) of this type. 1033 1034__Coverage-guided fuzzing__ must pass 1+ billion execs using a large corpus before tagging a release. Fuzzing is usually continued after the release is tagged and is manually stopped after reaching 1-3 billion execs. Fuzzing uses a customized version of [dvyukov/go-fuzz](https://github.com/dvyukov/go-fuzz). 1035 1036To prevent delays to release schedules, fuzzing is not restarted for a release if changes are limited to ci, docs, and comments. 1037 1038<hr> 1039 1040⚓ [Quick Start](#quick-start) • [Features](#features) • [Standards](#standards) • [API](#api) • [Options](#options) • [Usage](#usage) • [Fuzzing](#fuzzing-and-code-coverage) • [License](#license) 1041 1042## Versions and API Changes 1043This project uses [Semantic Versioning](https://semver.org), so the API is always backwards compatible unless the major version number changes. 1044 1045These functions have signatures identical to encoding/json and they will likely never change even after major new releases: 1046`Marshal`, `Unmarshal`, `NewEncoder`, `NewDecoder`, `(*Encoder).Encode`, and `(*Decoder).Decode`. 1047 1048Newly added API documented as "subject to change" are excluded from SemVer. 1049 1050Newly added API in the master branch that has never been release tagged are excluded from SemVer. 1051 1052## Code of Conduct 1053This project has adopted the [Contributor Covenant Code of Conduct](CODE_OF_CONDUCT.md). Contact [faye.github@gmail.com](mailto:faye.github@gmail.com) with any questions or comments. 1054 1055## Contributing 1056Please refer to [How to Contribute](CONTRIBUTING.md). 1057 1058## Security Policy 1059Security fixes are provided for the latest released version of fxamacker/cbor. 1060 1061For the full text of the Security Policy, see [SECURITY.md](SECURITY.md). 1062 1063## Disclaimers 1064Phrases like "no crashes", "doesn't crash", and "is secure" mean there are no known crash bugs in the latest version based on results of unit tests and coverage-guided fuzzing. They don't imply the software is 100% bug-free or 100% invulnerable to all known and unknown attacks. 1065 1066Please read the license for additional disclaimers and terms. 1067 1068## Special Thanks 1069 1070__Making this library better__ 1071 1072* Stefan Tatschner for using this library in [sep](https://rumpelsepp.org/projects/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](https://github.com/cbor/cbor.github.io/pull/56) on Aug 12, 2019. 1073* Yawning Angel for using this library to [oasis-core](https://github.com/oasislabs/oasis-core), and requesting BinaryMarshaler in issue #5. 1074* Jernej Kos for requesting RawMessage in issue #11 and offering feedback on v2.1 API for CBOR tags. 1075* ZenGround0 for using this library in [go-filecoin](https://github.com/filecoin-project/go-filecoin), filing "toarray" bug in issue #129, and requesting 1076CBOR BSTR <--> Go array in #133. 1077* Keith Randall for [fixing Go bugs and providing workarounds](https://github.com/golang/go/issues/36400) so we don't have to wait for new versions of Go. 1078 1079__Help clarifying CBOR RFC 7049 or 7049bis (7049bis is the draft of RFC 8949)__ 1080 1081* Carsten Bormann for RFC 7049 (CBOR), adding this library to cbor.io, his fast confirmation to my RFC 7049 errata, approving my pull request to 7049bis, and his patience when I misread a line in 7049bis. 1082* 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. 1083* Jeffrey Yasskin for his help on the IETF mailing list for 7049bis. 1084 1085__Words of encouragement and support__ 1086 1087* 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. 1088 1089 1090## License 1091Copyright © 2019-2022 [Faye Amacker](https://github.com/fxamacker). 1092 1093fxamacker/cbor is licensed under the MIT License. See [LICENSE](LICENSE) for the full license text. 1094 1095<hr> 1096 1097⚓ [Quick Start](#quick-start) • [Features](#features) • [Standards](#standards) • [API](#api) • [Options](#options) • [Usage](#usage) • [Fuzzing](#fuzzing-and-code-coverage) • [License](#license) 1098