README.md
1libre README
2============
3
4
5libre is a Generic library for real-time communications with async IO support.
6Copyright (C) 2010 - 2018 Creytiv.com
7
8
9[](https://travis-ci.org/creytiv/re)
10
11
12## Features
13
14* SIP Stack ([RFC 3261](https://tools.ietf.org/html/rfc3261))
15* SDP
16* RTP and RTCP
17* SRTP and SRTCP (Secure RTP)
18* DNS-Client
19* STUN/TURN/ICE stack
20* BFCP
21* HTTP-stack with client/server
22* Websockets
23* Jitter-buffer
24* Async I/O (poll, epoll, select, kqueue)
25* UDP/TCP/TLS/DTLS transport
26* JSON parser
27
28
29## Building
30
31libre is using GNU makefiles. Make and OpenSSL development headers must be
32installed before building.
33
34
35### Build with debug enabled
36
37```
38$ make
39$ sudo make install
40$ sudo ldconfig
41```
42
43### Build with release
44
45```
46$ make RELEASE=1
47$ sudo make RELEASE=1 install
48$ sudo ldconfig
49```
50
51### Build with clang compiler
52
53```
54$ make CC=clang
55$ sudo make CC=clang install
56$ sudo ldconfig
57```
58
59
60## Documentation
61
62The online documentation generated with doxygen is available in
63the main [website](http://creytiv.com/doxygen/re-dox/html/)
64
65
66
67### Examples
68
69Coding examples are available from the
70[redemo](http://creytiv.com/pub/redemo-0.5.0.tar.gz) project
71
72
73## License
74
75The libre project is using the BSD license.
76
77
78## Contributing
79
80Patches can sent via Github
81[Pull-Requests](https://github.com/creytiv/re/pulls) or to the RE devel
82[mailing-list](http://lists.creytiv.com/mailman/listinfo/re-devel).
83Currently we only accept small patches.
84Please send private feedback to libre [at] creytiv.com
85
86
87## Design goals
88
89* Portable POSIX source code (ANSI C89 and ISO C99 standard)
90* Robust, fast, low memory footprint
91* RFC compliance
92* IPv4 and IPv6 support
93
94
95## Modules
96
97| Name | Status | Description |
98|----------|----------|------------------------------------------------|
99| aes | unstable | AES (Advanced Encryption Standard) |
100| base64 | testing | Base-64 encoding/decoding functions |
101| bfcp | unstable | The Binary Floor Control Protocol (BFCP) |
102| conf | testing | Configuration file parser |
103| crc32 | testing | 32-bit CRC defined in ITU V.42 |
104| dbg | testing | Debug printing |
105| dns | stable | DNS resolving (NAPTR, SRV, A) |
106| fmt | testing | Formatted printing and regular expression |
107| hash | testing | Hashmap table |
108| hmac | testing | HMAC: Keyed-Hashing for Message Authentication |
109| http | unstable | HTTP parser (RFC 2616) |
110| httpauth | testing | HTTP-based Authentication (RFC 2617) |
111| ice | unstable | Interactive Connectivity Establishment (ICE) |
112| jbuf | testing | Jitter buffer |
113| json | unstable | JavaScript Object Notation (JSON) |
114| list | stable | Sortable doubly-linked list handling |
115| lock | testing | Resource locking functions |
116| main | testing | Main poll loop |
117| mbuf | stable | Linear memory buffers |
118| md5 | stable | The MD5 Message-Digest Algorithm (RFC 1321) |
119| mem | stable | Memory referencing |
120| mod | testing | Run-time module loading |
121| mqueue | testing | Thread-safe message queue |
122| msg | unstable | Generic message component library |
123| natbd | unstable | NAT Behavior Discovery using STUN |
124| net | testing | Networking routines |
125| odict | unstable | Ordered Dictionary |
126| rtp | testing | Real-time Transport Protocol |
127| sa | stable | Socket Address functions |
128| sdp | testing | Session Description Protocol |
129| sha | testing | Secure Hash Standard, NIST, FIPS PUB 180-1 |
130| sip | stable | Core SIP library |
131| sipevent | testing | SIP Event framework |
132| sipreg | stable | SIP register client |
133| sipsess | stable | SIP Sessions |
134| srtp | unstable | Secure Real-time Transport Protocol (SRTP) |
135| stun | stable | Session Traversal Utilities for NAT (STUN) |
136| sys | testing | System information |
137| tcp | testing | TCP transport |
138| telev | testing | Telephony Events (RFC 4733) |
139| tls | unstable | Transport Layer Security |
140| tmr | stable | Timer handling |
141| turn | stable | Obtaining Relay Addresses from STUN (TURN) |
142| udp | testing | UDP transport |
143| uri | testing | Generic URI library |
144| websock | unstable | WebSocket Client and Server |
145
146legend:
147* *stable* - code complete; stable code and stable API
148* *testing* - code complete, but API might change
149* *unstable* - code complete but not completely tested
150* *development* - code is under development
151
152
153## Features
154
155* [RFC 1321](https://tools.ietf.org/html/rfc1321) - The MD5 Message-Digest Algorithm
156* [RFC 1886](https://tools.ietf.org/html/rfc1886) - DNS Extensions to support IP version 6
157* [RFC 2032](https://tools.ietf.org/html/rfc2032) - RTP Payload Format for H.261 Video Streams
158* [RFC 2616](https://tools.ietf.org/html/rfc2616) - Hypertext Transfer Protocol -- HTTP/1.1
159* [RFC 2617](https://tools.ietf.org/html/rfc2617) - HTTP Authentication: Basic and Digest Access Authentication
160* [RFC 2782](https://tools.ietf.org/html/rfc2782) - A DNS RR for Specifying the Location of Services (DNS SRV)
161* [RFC 2915](https://tools.ietf.org/html/rfc2915) - The Naming Authority Pointer (NAPTR) DNS Resource Record
162* [RFC 3261](https://tools.ietf.org/html/rfc3261) - SIP: Session Initiation Protocol
163* [RFC 3263](https://tools.ietf.org/html/rfc3263) - Locating SIP Servers
164* [RFC 3264](https://tools.ietf.org/html/rfc3264) - An Offer/Answer Model with SDP
165* [RFC 3265](https://tools.ietf.org/html/rfc3265) - SIP-Specific Event Notification
166* [RFC 3327](https://tools.ietf.org/html/rfc3327) - SIP Extension Header Field for Registering Non-Adjacent Contacts
167* [RFC 3428](https://tools.ietf.org/html/rfc3428) - SIP Extension for Instant Messaging
168* [RFC 3489](https://tools.ietf.org/html/rfc3489) - STUN - Simple Traversal of UDP Through NATs
169* [RFC 3515](https://tools.ietf.org/html/rfc3515) - The SIP Refer Method
170* [RFC 3550](https://tools.ietf.org/html/rfc3550) - RTP: A Transport Protocol for Real-Time Applications
171* [RFC 3551](https://tools.ietf.org/html/rfc3551) - RTP Profile for Audio and Video Conferences with Minimal Control
172* [RFC 3555](https://tools.ietf.org/html/rfc3555) - MIME Type Registration of RTP Payload Formats
173* [RFC 3556](https://tools.ietf.org/html/rfc3556) - SDP Bandwidth Modifiers for RTCP Bandwidth
174* [RFC 3581](https://tools.ietf.org/html/rfc3581) - An Extension to SIP for Symmetric Response Routing
175* [RFC 3605](https://tools.ietf.org/html/rfc3605) - RTCP attribute in SDP
176* [RFC 3711](https://tools.ietf.org/html/rfc3711) - The Secure Real-time Transport Protocol (SRTP)
177* [RFC 3969](https://tools.ietf.org/html/rfc3969) - The IANA URI Parameter Registry for SIP
178* [RFC 3994](https://tools.ietf.org/html/rfc3994) - Indication of Message Composition for Instant Messaging
179* [RFC 4346](https://tools.ietf.org/html/rfc4346) - The TLS Protocol Version 1.1
180* [RFC 4566](https://tools.ietf.org/html/rfc4566) - SDP: Session Description Protocol
181* [RFC 4582](https://tools.ietf.org/html/rfc4582) - The Binary Floor Control Protocol (BFCP)
182* [RFC 4582bis](https://tools.ietf.org/html/draft-ietf-bfcpbis-rfc4582bis-08) - The Binary Floor Control Protocol (BFCP)
183* [RFC 4585](https://tools.ietf.org/html/rfc4585) - Extended RTP Profile for RTCP-Based Feedback
184* [RFC 4733](https://tools.ietf.org/html/rfc4733) - RTP Payload for DTMF Digits, Telephony Tones, and Teleph. Signals
185* [RFC 4961](https://tools.ietf.org/html/rfc4961) - Symmetric RTP / RTP Control Protocol (RTCP)
186* [RFC 5118](https://tools.ietf.org/html/rfc5118) - SIP Torture Test Messages for IPv6
187* [RFC 5245](https://tools.ietf.org/html/rfc5245) - Interactive Connectivity Establishment (ICE)
188* [RFC 5389](https://tools.ietf.org/html/rfc5389) - Session Traversal Utilities for NAT (STUN)
189* [RFC 5626](https://tools.ietf.org/html/rfc5626) - Managing Client-Initiated Connections in SIP
190* [RFC 5761](https://tools.ietf.org/html/rfc5761) - Multiplexing RTP Data and Control Packets on a Single Port
191* [RFC 5766](https://tools.ietf.org/html/rfc5766) - Traversal Using Relays around NAT (TURN)
192* [RFC 5768](https://tools.ietf.org/html/rfc5768) - Indicating Support for ICE in SIP
193* [RFC 5769](https://tools.ietf.org/html/rfc5769) - Test vectors for STUN
194* [RFC 5780](https://tools.ietf.org/html/rfc5780) - NAT Behaviour Discovery Using STUN
195* [RFC 6026](https://tools.ietf.org/html/rfc6026) - Correct Transaction Handling for 2xx Resp. to SIP INVITE Requests
196* [RFC 6156](https://tools.ietf.org/html/rfc6156) - TURN Extension for IPv6
197* [RFC 6188](https://tools.ietf.org/html/rfc6188) - The Use of AES-192 and AES-256 in Secure RTP
198* [RFC 6455](https://tools.ietf.org/html/rfc6455) - The WebSocket Protocol
199* [RFC 7159](https://tools.ietf.org/html/rfc7159) - JavaScript Object Notation (JSON)
200* [RFC 7350](https://tools.ietf.org/html/rfc7350) - DTLS as Transport for STUN
201* [RFC 7714](https://tools.ietf.org/html/rfc7714) - AES-GCM Authenticated Encryption in SRTP
202
203
204## Supported platforms
205
206* Linux
207* FreeBSD
208* OpenBSD
209* NetBSD
210* Solaris 11
211* Windows
212* Apple Mac OS X and iOS
213* Android
214
215### Supported versions of C Standard library
216
217* Android bionic
218* BSD libc
219* GNU C Library (glibc)
220* Windows C Run-Time Libraries (CRT)
221* uClibc
222
223
224### Supported compilers:
225
226* gcc 3.x
227* gcc 4.x
228* gcc 5.x
229* gcc 6.x
230* ms vc2003 compiler
231* clang
232
233### Supported versions of OpenSSL
234
235* OpenSSL version 1.0.1
236* OpenSSL version 1.0.2
237* OpenSSL version 1.1.0 (supported since version 0.5.0)
238* LibreSSL version 2.x
239
240
241## Coding guidelines
242
243* Use enum for constants where appropriate
244* Use const as much as possible (where appropriate)
245* Use C99 data types (intN_t, uintN_t, bool)
246* Hide data-types in .c files where possible (use struct foo)
247* Avoid malloc/free, use mem_alloc/mem_deref instead
248* CVS/svn/git tags are NOT allowed in the code!
249* Avoid bit-fields in structs which are not portable
250* Use dummy handlers for timing-critical callbacks
251* return err, return alloced objects as pointer-pointers
252* in allocating functions, first arg is always double pointer
253* Use POSIX error-codes; EINVAL for invalid args, EBADMSG for
254 parse errors and EPROTO for protocol errors
255
256
257## Transport protocols
258
259
260| | TCP | UDP | TLS | DTLS|
261|:--------|:---:|:---:|:---:|:---:|
262| BFCP | - | yes | - | - |
263| DNS | yes | yes | - | - |
264| HTTP | yes | n/a | yes | n/a |
265| ICE | - | yes | - | - |
266| RTP | - | yes | - | - |
267| RTCP | - | yes | - | - |
268| SIP | yes | yes | yes | - |
269| STUN | yes | yes | yes | yes |
270| TURN | yes | yes | yes | yes |
271| WEBSOCK | yes | n/a | yes | n/a |
272
273
274## Related projects
275
276* [librem](https://github.com/creytiv/rem)
277* [retest](https://github.com/creytiv/retest)
278* [baresip](https://github.com/alfredh/baresip)
279* [restund](http://creytiv.com/restund.html)
280
281
282
283## References
284
285http://creytiv.com/re.html
286
287https://github.com/creytiv/re
288
289http://lists.creytiv.com/mailman/listinfo/re-devel
290
291
){kind=link}