Skip to content

Commit

Permalink
Update README.md
Browse files Browse the repository at this point in the history
  • Loading branch information
fxamacker authored Nov 24, 2019
1 parent aa44241 commit 3677ff0
Showing 1 changed file with 14 additions and 5 deletions.
19 changes: 14 additions & 5 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -16,7 +16,7 @@ __What is CBOR__? [CBOR](CBOR.md) ([RFC 7049](https://tools.ietf.org/html/rfc70

__Why this CBOR library?__ It doesn't crash and it has well-balanced qualities: small, fast, reliable and easy.

* __Small__ and self-contained. It compiles to under 0.5 MB, has no external dependencies, and no code gen. In extreme cases, program sizes can be smaller by 8-9 MB by using this library. See [comparisons](#comparisons).
* __Small__ and self-contained. It has no external dependencies and no code gen. Programs in projects like cisco/senml are 4 MB smaller by switching to this library. In extreme cases programs can be smaller by 8+ MB. See [comparisons](#comparisons).

* __Fast__ (esp. since v1.3). It soley uses safe optimizations. Faster libraries will always exist, but speed is only one factor. Choose this library if you value your time, program size, and system reliability.

Expand Down Expand Up @@ -55,7 +55,7 @@ This CBOR library was created for my [WebAuthn (FIDO2) server library](https://g
This library is designed to be:

* __Easy__ – idiomatic API like `encoding/json` with identical API when possible.
* __Small and self-contained__compiles to under 0.5 MB and has no external dependencies.
* __Small and self-contained__no external dependencies and no code gen. Programs in cisco/senml are 4 MB smaller by switching to this library. In extreme cases programs can be smaller by 8+ MB. See [comparisons](#comparisons).
* __Safe and reliable__ – no `unsafe` pkg, coverage >95%, coverage-guided fuzzing, and data validation to avoid crashes on malformed or malicious data.

Competing factors are balanced:
Expand All @@ -71,10 +71,12 @@ All releases prioritize reliability to avoid crashes on decoding malformed CBOR

![alt text](https://user-images.githubusercontent.com/57072051/69281068-3e424680-0bad-11ea-97ab-730b3d3069af.png "CBOR library and program size comparison chart")

Additional comparisons may be added here from time to time (esp. speed comparisons!)
Programs like senmlCat in cisco/senml will be about 4 MB smaller by switching to this library.

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

Additional comparisons may be added here from time to time (esp. speed comparisons!)

## Features

* Idiomatic API like `encoding/json`.
Expand All @@ -100,7 +102,7 @@ Each release passes coverage-guided fuzzing using [fxamacker/cbor-fuzz](https://

* 2 files related to WebAuthn (FIDO U2F key).
* 17 files with [COSE examples (RFC 8152 Appendix B & C)](https://github.com/cose-wg/Examples/tree/master/RFC8152).
* 82 files with [CBOR examples (RFC 7049 Appendix A) ](https://tools.ietf.org/html/rfc7049#appendix-A).
* 81 files with [CBOR examples (RFC 7049 Appendix A) ](https://tools.ietf.org/html/rfc7049#appendix-A). It excludes 1 errata first reported in [issue #46](https://github.com/fxamacker/cbor/issues/46).
* 340 files generated by fuzzing for 50 hours with 2 workers on AMD EPYC 7601 virtual machine.

Unit tests include all RFC 7049 examples, bugs found by fuzzing, 2 maliciously crafted CBOR data, and etc.
Expand All @@ -112,7 +114,14 @@ Code coverage is 97.8% (`go test -cover`) for cbor v1.3 which is among the highe
## Standards
This library implements CBOR as specified in [RFC 7049](https://tools.ietf.org/html/rfc7049), with minor [limitations](#limitations).

It also supports [canonical CBOR encodings](https://tools.ietf.org/html/rfc7049#section-3.9) (both RFC 7049 and [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)). CTAP2 canonical CBOR encoding is used by [CTAP](https://fidoalliance.org/specs/fido-v2.0-id-20180227/fido-client-to-authenticator-protocol-v2.0-id-20180227.html) and [WebAuthn](https://www.w3.org/TR/webauthn/) in [FIDO2](https://fidoalliance.org/fido2/) framework.
Three encoding modes are available since v1.3.1:
* default: no sorting, so it's the fastest mode.
* Canonical: [(RFC 7049 Section 3.9)](https://tools.ietf.org/html/rfc7049#section-3.9) uses length-first map key ordering.
* CTAP2Canonical: [(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) uses bytewise lexicographic order for sorting keys.

CTAP2 Canonical CBOR encoding is used by [CTAP](https://fidoalliance.org/specs/fido-v2.0-id-20180227/fido-client-to-authenticator-protocol-v2.0-id-20180227.html) and [WebAuthn](https://www.w3.org/TR/webauthn/) in [FIDO2](https://fidoalliance.org/fido2/) framework.

All three encoding modes in this library use smallest form of CBOR integer that preserves data.

## Limitations
🎈 CBOR tags (type 6) is being considered for a future release. Please let me know if this feature is important to you.
Expand Down

0 comments on commit 3677ff0

Please sign in to comment.