From 0e36fc7effc7b442ec1ce5436d29c1afd9cf77a6 Mon Sep 17 00:00:00 2001 From: Faye Amacker <33205765+fxamacker@users.noreply.github.com> Date: Sun, 5 Mar 2023 23:39:25 -0600 Subject: [PATCH] Update README for cbor v2.5.0-beta2 - Remove "What is CBOR" section for now. - Add heading "Who uses fxamacker/cbor". - Update "CBOR Security" with updated benchmarks. for decoding 10 bytes of malicious CBOR data. --- README.md | 44 ++++++++++++++++++++++++++------------------ 1 file changed, 26 insertions(+), 18 deletions(-) diff --git a/README.md b/README.md index 7ad7ad16..7bceb4d4 100644 --- a/README.md +++ b/README.md @@ -10,23 +10,26 @@ [![Go Report Card](https://goreportcard.com/badge/github.com/fxamacker/cbor)](https://goreportcard.com/report/github.com/fxamacker/cbor) [![](https://img.shields.io/badge/go-%3E%3D%201.12-blue)](#cbor-library-installation) -[__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. +[__fxamacker/cbor__](https://github.com/fxamacker/cbor) is a modern [CBOR](https://tools.ietf.org/html/rfc8949) codec in [Go](https://golang.org). CBOR is an [Internet Standard](https://en.wikipedia.org/wiki/Internet_Standard) data format designed to be relevant for decades. This is a compact, fast, and secure alternative to `encoding/json` and `encoding/gob`. -Features 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. +Features include `keyasint` and `toarray` struct tags for more compact CBOR encoding with less programming effort. -Using 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. +API is designed to be safe, fast, and easy for concurrent use. Immutable encoding and decoding modes can be reused concurrently after being created at startup from CBOR options. -There are [1276 repositories](https://github.com/fxamacker/cbor/network/dependents?package_id=UGFja2FnZS0yMjcwNDY1OTQ4) that depend on fxamacker/cbor/v2. Additional 155 repositories are using version 1.x of this CBOR codec (please upgrade to v2). +This CBOR codec supports 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. -fxamacker/cbor is used by Arm Ltd., Berlin Institute of Health at Charité, Chainlink, ConsenSys, Dapper Labs, Duo Labs (cisco), EdgeX Foundry, Mozilla, National Cybersecurity Agency of France (govt), Netherlands (govt), Oasis Labs, Tailscale, Taurus SA, Teleport, TIBCO, and others. +Install with `go get github.com/fxamacker/cbor/v2` and `import "github.com/fxamacker/cbor/v2"`. +See [Quick Start](#quick-start) to save time. -Microsoft Corporation had NCC Group conduct a security assessment (PDF) which includes portions of this library in its scope. +## Who uses fxamacker/cbor -fxamacker/cbor has 98% coverage and is fuzz tested. +`fxamacker/cbor` is used by Arm Ltd., Berlin Institute of Health at Charité, Chainlink, ConsenSys, Dapper Labs, Duo Labs (cisco), EdgeX Foundry, F5, Fraunhofer-AISEC, Mozilla, National Cybersecurity Agency of France (govt), Netherlands (govt), Oasis Labs, Smallstep, Tailscale, Taurus SA, Teleport, TIBCO, and others. -Install with `go get github.com/fxamacker/cbor/v2` and `import "github.com/fxamacker/cbor/v2"`. -See [Quick Start](#quick-start) to save time. +Github reports [1750+ repositories](https://github.com/fxamacker/cbor/network/dependents?package_id=UGFja2FnZS0yMjcwNDY1OTQ4) depend on fxamacker/cbor/v2. Additional 150+ repos are using version 1.x (please upgrade to v2). +A security assessment [viewable online](https://github.com/veraison/go-cose/blob/v1.0.0-rc.1/reports/NCC_Microsoft-go-cose-Report_2022-05-26_v1.0.pdf) (prepared by NCC Group for Microsoft) includes a subset of fxamacker/cbor in its scope. + + -## Why fxamacker/cbor? +## Why fxamacker/cbor fxamacker/cbor balances competing factors such as speed, size, safety, usability, maintainability, and etc. @@ -55,16 +59,20 @@ fxamacker/cbor balances competing factors such as speed, size, safety, usability __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. -Decoding 9 or 10 bytes of malformed CBOR data shouldn't exhaust memory. For example, -`[]byte{0x9B, 0x00, 0x00, 0x42, 0xFA, 0x42, 0xFA, 0x42, 0xFA, 0x42}` +Decoding 10 bytes of malicious data into `[]byte` shouldn't exhaust memory. E.g. +`[]byte{0x9B, 0x00, 0x00, 0x42, 0xFA, 0x42, 0xFA, 0x42, 0xFA, 0x42}`. -| | Decode bad 10 bytes to interface{} | Decode bad 10 bytes to []byte | -| :--- | :------------------ | :--------------- | -| fxamacker/cbor
1.0-2.3 | 49.44 ns/op, 24 B/op, 2 allocs/op* | 51.93 ns/op, 32 B/op, 2 allocs/op* | -| ugorji/go 1.2.6 | ⚠️ 45021 ns/op, 262852 B/op, 7 allocs/op | 💥 runtime: out of memory: cannot allocate | -| ugorji/go 1.1-1.1.7 | 💥 runtime: out of memory: cannot allocate | 💥 runtime: out of memory: cannot allocate| +| Codec | Speed (ns/op) | Memory | Allocs | +| :---- | ------------: | -----: | -----: | +| fxamacker/cbor 2.5.0-beta2 | 44.33 ± 2% | 32 B/op | 2 allocs/op | +| fxamacker/cbor 0.1.0 - 2.4.0 | ~44.68 ± 6% | 32 B/op | 2 allocs/op | +| ugorji/go 1.2.10 | 5524792.50 ± 3% | 67110491 B/op | 12 allocs/op | +| ugorji/go 1.1.0 - 1.2.6 | 💥 runtime: | out of memory: | cannot allocate | -*Speed and memory are for latest codec version listed in the row (compiled with Go 1.17.5). +``` +go1.19.6, linux/amd64, i5-13600K +GOMAXPROCS=6 go test -bench=. -benchmem -count=20 +``` fxamacker/cbor CBOR safety settings include: MaxNestedLevels, MaxArrayElements, MaxMapPairs, and IndefLength.