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[![Build Status](https://travis-ci.org/creytiv/re.svg?branch=master)](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