xref: /freebsd/contrib/libcbor/README.md (revision a259b98fa211ed87bfee58c575de4e2de94ee0fa) 
1# [libcbor](https://github.com/PJK/libcbor)
2
3[![CircleCI](https://circleci.com/gh/PJK/libcbor/tree/master.svg?style=svg)](https://circleci.com/gh/PJK/libcbor/tree/master)
4[![Documentation Status](https://readthedocs.org/projects/libcbor/badge/?version=latest)](https://readthedocs.org/projects/libcbor/?badge=latest)
5[![latest packaged version(s)](https://repology.org/badge/latest-versions/libcbor.svg)](https://repology.org/project/libcbor/versions)
6[![codecov](https://codecov.io/gh/PJK/libcbor/branch/master/graph/badge.svg)](https://codecov.io/gh/PJK/libcbor)
7
8**libcbor** is a C library for parsing and generating [CBOR](https://cbor.io/), the general-purpose schema-less binary data format.
9
10## Main features
11
12- Complete CBOR [IETF RFC 8949 (STD 94)](https://www.rfc-editor.org/info/std94) specification conformance (previously known as [RFC 7049](https://www.rfc-editor.org/info/rfc7049))
13- Supports CBOR Sequences ([RFC 8742](https://datatracker.ietf.org/doc/html/rfc8742))
14- Robust platform-independent C99 implementation, tested on
15  - Linux, OS X, Windows, BSD
16  - x86(_64), arm(64), mips(el), riscv64
17- Layered architecture offers both control and convenience
18- Flexible memory management
19- No shared global state - threading friendly
20- Proper handling of UTF-8
21- Full support for streams & incremental processing
22- Extensive documentation and test suite
23- No runtime dependencies, small footprint
24
25## References
26
27libcbor is most prominently used in:
28
29- Yubico's [libfido2](https://developers.yubico.com/libfido2/) 2FA security key implementation
30- Amazon's [AWS C SDK](https://github.com/awslabs/aws-c-common)
31- Gnome [fwdup](https://github.com/fwupd/fwupd/blob/main/meson.build#L339)
32- Alibaba's [Inclavare librats](https://github.com/inclavare-containers/librats)
33- [QEMU](https://wiki.qemu.org/ChangeLog/9.2)
34- [ITK](https://docs.itk.org/projects/wasm/en/latest/introduction/parts.html)
35
36It found its way into many open source an proprietary projects. If you run among others [OpenSSH](https://www.matbra.com/2020/02/17/using-fido2-with-ssh.html), [Microsoft PowerShell](https://github.com/PowerShell/libcbor), [SteamOS](https://github.com/randombk/steamos-teardown/blob/5a37d977fae55d9c41eaf1d07528fa965740bb26/docs/packages.md?plain=1#L461), or [MySQL](https://dev.mysql.com/doc/relnotes/mysql/8.0/en/news-8-0-34.html) -- you might be indirectly running libcbor too.
37
38Also, thank you for the shout out in <https://github.com/oz123/awesome-c?tab=readme-ov-file#others>!
39
40## Getting started
41
42### Compile from source
43
44```bash
45git clone https://github.com/PJK/libcbor
46cmake -DCMAKE_BUILD_TYPE=Release libcbor
47make
48make install
49```
50
51### Homebrew
52
53```bash
54brew install libcbor
55```
56
57### Ubuntu 18.04 and above
58
59```bash
60sudo add-apt-repository universe
61sudo apt-get install libcbor-dev
62```
63
64### Fedora & RPM friends
65
66```bash
67yum install libcbor-devel
68```
69
70### Include git repository using using CMake
71
72See e.g. <https://github.com/inclavare-containers/librats/blob/master/cmake/LibCBOR.cmake>.
73
74## Include git repository using Bazel
75
76See <https://github.com/PJK/libcbor/tree/master/examples/bazel>.
77
78### Others
79
80<details>
81  <summary>Packaged libcbor is available from 15+ major repositories. Click here for more detail</summary>
82
83  [![Packaging status](https://repology.org/badge/vertical-allrepos/libcbor.svg)](https://repology.org/project/libcbor/versions)
84</details>
85
86## Usage example
87
88```c
89#include <cbor.h>
90#include <stdio.h>
91
92int main(void) {
93  /* Preallocate the map structure */
94  cbor_item_t* root = cbor_new_definite_map(2);
95  /* Add the content */
96  bool success = cbor_map_add(
97      root, (struct cbor_pair){
98                .key = cbor_move(cbor_build_string("Is CBOR awesome?")),
99                .value = cbor_move(cbor_build_bool(true))});
100  success &= cbor_map_add(
101      root, (struct cbor_pair){
102                .key = cbor_move(cbor_build_uint8(42)),
103                .value = cbor_move(cbor_build_string("Is the answer"))});
104  if (!success) return 1;
105  /* Output: `length` bytes of data in the `buffer` */
106  unsigned char* buffer;
107  size_t buffer_size;
108  cbor_serialize_alloc(root, &buffer, &buffer_size);
109
110  fwrite(buffer, 1, buffer_size, stdout);
111  free(buffer);
112
113  fflush(stdout);
114  cbor_decref(&root);
115}
116```
117
118## Documentation
119
120Crash course: <https://libcbor.readthedocs.io/en/latest/tutorial.html#crash-course>
121
122Get the latest documentation at [libcbor.readthedocs.org](http://libcbor.readthedocs.org/)
123
124## Contributions
125
126Bug reports and contributions are welcome. Please see [CONTRIBUTING.md](https://github.com/PJK/libcbor/blob/master/CONTRIBUTING.md) for more info.
127
128Kudos to all the [contributors](https://github.com/PJK/libcbor/graphs/contributors)!
129
130## License
131
132The MIT License (MIT)
133
134Copyright (c) Pavel Kalvoda, 2014-2020
135
136Permission is hereby granted, free of charge, to any person obtaining a copy
137of this software and associated documentation files (the "Software"), to deal
138in the Software without restriction, including without limitation the rights
139to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
140copies of the Software, and to permit persons to whom the Software is
141furnished to do so, subject to the following conditions:
142
143The above copyright notice and this permission notice shall be included in all
144copies or substantial portions of the Software.
145
146THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
147IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
148FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
149AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
150LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
151OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
152SOFTWARE.
153