2018-10-10 13:54:43 +08:00
[](https://travis-ci.org/warmcat/libwebsockets) [](https://ci.appveyor.com/project/lws-team/libwebsockets) [](https://scan.coverity.com/projects/3576) [](https://bestpractices.coreinfrastructure.org/projects/2266) [](https://www.codacy.com/app/lws-team/libwebsockets?utm_source=github.com& utm_medium=referral& utm_content=warmcat/libwebsockets& utm_campaign=Badge_Grade)
2014-12-01 01:21:10 +01:00
2018-11-16 09:10:41 +08:00
# Libwebsockets
Libwebsockets is a simple-to-use, pure C library providing client and server
for **http/1** , **http/2** , **websockets** and other protocols in a security-minded,
lightweight, configurable, scalable and flexible way. It's easy to build and
cross-build via cmake and is suitable for tasks from embedded RTOS through mass
cloud serving.
2018-11-19 07:40:47 +08:00
[50 minimal examples ](https://libwebsockets.org/git/libwebsockets/tree/minimal-examples ) for
various scenarios, CC0-licensed (public domain) for cut-and-paste, allow you to get started quickly.
2018-11-16 09:10:41 +08:00
2018-12-13 20:05:12 +08:00
2014-12-01 01:21:10 +01:00
2017-03-16 10:46:31 +08:00
News
----
2019-08-14 09:22:50 +01:00
## V3.2 relase last planned LGPLv2.1+SLE release
As foretold the v3.2 release is the last planned release that will have the code
under LGPLv2.1+SLE. Master has those parts changed to MIT license; the pieces
that were CC0 or another liberal license remain the same.
2019-07-19 07:46:38 -07:00
## License change plan
Lws is planning to change the pieces that are currently LGPLv2.1+SLE to MIT
https://opensource.org/licenses/MIT . Stuff that is already CC0 or another
permissive license will stay as it is.
This license change is making an already permissive license (it was already LGPL,
and the SLE removed most restrictions already) even more permissive.
So I expect most contributors either don't much care or are happy about it.
Contributors who object should contact me via:
- the lws mailing list https://libwebsockets.org/mailman/listinfo/libwebsockets
- github issue https://github.com/warmcat/libwebsockets , or
- email to `andy@warmcat.com`
...before **Aug 11 2019** , and I'll rewrite the related code before the change.
There'll be a last release of the currently-licensed stuff (probably v3.2) and
then the same code will have the licese grant changed in the sources, become
master and also have an otherwise identical release, probably v4.0. The v3.2
stuff won't be maintained (by me anyway... it's FOSS though) but the v4.0
stuff which is the same except the license will get the usual v4.0-stable
treatment.
Even after the change I will continue to rely on users to help me with bug
reports and patches, work together on new features. The license will no
longer require it but the practical advantages from staying aligned with
upstream lws for users remain the same.
2018-11-29 08:29:48 +08:00
## New features on master
2019-01-13 06:58:21 +08:00
- `LWS_WITH_NETWORK` cmake option (default on) allows one-step removal of vhost,
wsi, roles, event loop and all network-related code from the build. This
enables use-cases where you actually need unrelated features like JOSE or FTS
compactly. lws_context still exists and if tls is enabled, the tls-related code
is still built so the crypto is available, just nothing related to network.
2018-12-31 20:35:54 +08:00
- New Crypto-agile APIs + JOSE / JWS / JWE / JWK support... apis work exactly
the same with OpenSSL or mbedTLS tls library backends, and allow key cycling
and crypto algorithm changes while allowing for grace periods
[README.crypto-apis ](https://libwebsockets.org/git/libwebsockets/tree/READMEs/README.crypto-apis.md )
2018-12-13 20:05:12 +08:00
- CMake config simplification for crypto: `-DLWS_WITH_GENCRYPTO=1` for all
generic cipher and hash apis built (which work the same on mbedtls and
OpenSSL transparently), and `-DLWS_WITH_JOSE=1` for all JOSE, JWK, JWS
and JWE support built (which use gencrypto and so also work the same
regardless of tls library backend).
2018-12-31 20:35:54 +08:00
- **`x.509` ** - new generic x509 api allows PEM-based certificate and key
trust relationship verification, and conversion between x.509 keys and
JWK. Works for EC and RSA keys, and on mbedtls and OpenSSl the same.
[x.509 api ](https://libwebsockets.org/git/libwebsockets/tree/include/libwebsockets/lws-x509.h ),
[x.509 minimal example ](https://libwebsockets.org/git/libwebsockets/tree/minimal-examples/crypto/minimal-crypto-x509 )
2018-12-24 07:42:03 +08:00
- **`JWE` ** - JWE (RFC7516) Algorithms with CI tests:
2018-12-13 20:05:12 +08:00
|Key Encryption|Payload authentication + crypt|Enc + Dec Support|
|---|---|---|
|`RSAES-PKCS1-v1.5` 2048b & 4096b|`AES_128_CBC_HMAC_SHA_256` |Enc + Dec|
|`RSAES-PKCS1-v1.5` 2048b|`AES_192_CBC_HMAC_SHA_384` |Enc + Dec|
|`RSAES-PKCS1-v1.5` 2048b|`AES_256_CBC_HMAC_SHA_512` |Enc + Dec|
|`RSAES-OAEP` |`AES_256_GCM` |Enc + Dec|
|`AES128KW` , `AES192KW` , `AES256KW` |`AES_128_CBC_HMAC_SHA_256` |Enc + Dec|
|`AES128KW` , `AES192KW` , `AES256KW` |`AES_192_CBC_HMAC_SHA_384` |Enc + Dec|
|`AES128KW` , `AES192KW` , `AES256KW` |`AES_256_CBC_HMAC_SHA_512` |Enc + Dec|
2018-12-24 07:42:03 +08:00
|`ECDH-ES` (P-256/384/521 key)|`AES_128/192/256_GCM` |Enc + Dec|
|`ECDH-ES+A128/192/256KW` (P-256/384/521 key)|`AES_128/192/256_GCM` |Enc + Dec|
2018-12-13 20:05:12 +08:00
All tests pass on both OpenSSL and mbedTLS backends, using keys generated on
both OpenSSL and mbedTLS in the tests.
A minimal example tool shows how to encrypt and decrypt compact JWE objects
from the commandline for all supported algorithms.
[jwe api ](https://libwebsockets.org/git/libwebsockets/tree/include/libwebsockets/lws-jwe.h ),
[jwe unit tests ](https://libwebsockets.org/git/libwebsockets/tree/minimal-examples/api-tests/api-test-jose/jwe.c ),
[jwe minimal example ](https://libwebsockets.org/git/libwebsockets/tree/minimal-examples/crypto/minimal-crypto-jwe )
2018-12-24 07:42:03 +08:00
- **`lws-genec` ECDSA** - JWS-compatible ECDSA is supported on both OpenSSL and mbedtls.
2018-12-13 20:05:12 +08:00
- **`JWS` ** - JWS (RFC7515) is now supported for none, HS256/384/512, RS256/384/512, and ES256/384/512, on both OpenSSL and mbedtls. There's a minimal example tool that signs and verifies compact
representation JWS from stdin.
[jws api ](https://libwebsockets.org/git/libwebsockets/tree/include/libwebsockets/lws-jws.h ),
[jws unit tests ](https://libwebsockets.org/git/libwebsockets/tree/minimal-examples/api-tests/api-test-jose/jws.c ),
[jws minimal example ](https://libwebsockets.org/git/libwebsockets/tree/minimal-examples/crypto/minimal-crypto-jwe )
- **`JWK` ** - JWK (RFC7517) now supports oct, RSA and EC keys including JSON key
arrays on both OpenSSL and mbedtls. A minimal example tool shows how to create
new JSON JWK keys to specified parameters from the commandline for all supported
ciphers.
[jwk minimal example ](https://libwebsockets.org/git/libwebsockets/tree/minimal-examples/crypto/minimal-crypto-jwk )
2018-12-05 13:11:03 +08:00
- **`lws-genrsa` OAEP + PSS support** - in addition to PKCS#1 1.5 padding, OAEP and PSS are
2018-12-08 07:10:09 +08:00
now supported on both mbedtls and openssl backends.
- **`lws-genaes` Generic AES crypto** - thin api layer works identically with both mbedtls and openssl
2018-12-04 08:03:58 +08:00
backends. Supports CBC, CFB128, CFB8, CTR, ECB, OFB, XTS and GCM variants. Unit tests in CI.
[genaes api ](https://libwebsockets.org/git/libwebsockets/tree/include/libwebsockets/lws-genaes.h ),
[api test ](https://libwebsockets.org/git/libwebsockets/tree/minimal-examples/api-tests/api-test-gencrypto ),
2018-12-13 20:05:12 +08:00
CMake config: `-DLWS_WITH_GENCRYPTO=1`
2018-12-04 08:03:58 +08:00
2018-11-29 08:29:48 +08:00
- **http fallback support** - you can specify a role and protocol to apply if non-http or non-tls
packets arrive at an http(s) listen port. For example, you can specify that the new `raw proxy`
role + protocol should be used, to proxy your sshd port over :443 or :80. Without affecting
normal http(s) serving on those ports but allowing, eg, `ssh -p 443 invalid@libwebsockets.org` .
[http fallback docs ](https://libwebsockets.org/git/libwebsockets/tree/READMEs/README.http-fallback.md )
- **raw tcp proxy role and protocol** - adding raw tcp proxying is now trivial using the built-in lws
implementation. You can control the onward connection using a pvo in the format "ipv4:server.com:port"
[raw proxy minimal example ](https://libwebsockets.org/git/libwebsockets/tree/minimal-examples/raw/minimal-raw-proxy ),
[raw proxy docs ](https://libwebsockets.org/git/libwebsockets/tree/plugins/raw-proxy ),
Cmake config: `-DLWS_ROLE_RAW_PROXY=1 -DLWS_WITH_PLUGINS=1`
- **deaddrop HTML file upload protocol** - protocol and minimal example for file upload and sharing using
drag and drop and a file picker. Integrated with basic auth, uploaded files marked with upload user,
and files owned by the authenticated user may be deleted via the UI. Supports multiple simultaneous
uploads both by drag-and-drop and from the file picker.
[deaddrop minimal example ](https://libwebsockets.org/git/libwebsockets/tree/minimal-examples/http-server/minimal-http-server-deaddrop )
- **basic auth for ws(s)** - You can apply basic auth credential requirement to ws connections same
as on mounts now. Just add a pvo "basic-auth" with the value being the credentials file path when
enabling the ws protocol for the vhost.
2018-11-23 11:30:56 +08:00
## v3.1 released: new features in v3.1
2018-11-16 09:10:41 +08:00
- **lws threadpool** - lightweight pool of pthreads integrated to lws wsi, with all
synchronization to event loop handled internally, queue for excess tasks
2018-11-19 07:40:47 +08:00
[threadpool docs ](https://libwebsockets.org/git/libwebsockets/tree/lib/misc/threadpool ),
[threadpool minimal example ](https://libwebsockets.org/git/libwebsockets/tree/minimal-examples/ws-server/minimal-ws-server-threadpool ),
2018-11-16 09:10:41 +08:00
Cmake config: `-DLWS_WITH_THREADPOOL=1`
- **libdbus support** integrated on lws event loop
2018-11-19 07:40:47 +08:00
[lws dbus docs ](https://libwebsockets.org/git/libwebsockets/tree/lib/roles/dbus ),
[lws dbus client minimal examples ](https://libwebsockets.org/git/libwebsockets/tree/minimal-examples/dbus-client ),
[lws dbus server minimal examples ](https://libwebsockets.org/git/libwebsockets/tree/minimal-examples/dbus-server ),
2018-11-16 09:10:41 +08:00
Cmake config: `-DLWS_ROLE_DBUS=1`
- **lws allocated chunks (lwsac)** - helpers for optimized mass allocation of small
objects inside a few larger malloc chunks... if you need to allocate a lot of
inter-related structs for a limited time, this removes per-struct allocation
library overhead completely and removes the need for any destruction handling
2018-11-19 07:40:47 +08:00
[lwsac docs ](https://libwebsockets.org/git/libwebsockets/tree/lib/misc/lwsac ),
[lwsac minimal example ](https://libwebsockets.org/git/libwebsockets/tree/minimal-examples/api-tests/api-test-lwsac ),
2018-11-16 09:10:41 +08:00
Cmake Config: `-DLWS_WITH_LWSAC=1`
- **lws tokenizer** - helper api for robustly tokenizing your own strings without
allocating or adding complexity. Configurable by flags for common delimiter
sets and comma-separated-lists in the tokenizer. Detects and reports syntax
errors.
2018-11-19 07:40:47 +08:00
[lws_tokenize docs ](https://libwebsockets.org/git/libwebsockets/tree/include/libwebsockets/lws-tokenize.h ),
2018-11-16 09:10:41 +08:00
[lws_tokenize minimal example / api test ](https://libwebsockets.org/git/libwebsockets/tree/minimal-examples/api-tests/api-test-lws_tokenize )
- **lws full-text search** - optimized trie generation, serialization,
autocomplete suggestion generation and instant global search support extensible
to huge corpuses of UTF-8 text while remaining super lightweight on resources.
2018-11-19 07:40:47 +08:00
[full-text search docs ](https://libwebsockets.org/git/libwebsockets/tree/lib/misc/fts ),
[full-text search minimal example / api test ](https://libwebsockets.org/git/libwebsockets/tree/minimal-examples/api-tests/api-test-fts ),
[demo ](https://libwebsockets.org/ftsdemo/ ),
[demo sources ](https://libwebsockets.org/git/libwebsockets/tree/plugins/protocol_fulltext_demo.c ),
2018-11-16 09:10:41 +08:00
Cmake config: `-DLWS_WITH_FTS=1 -DLWS_WITH_LWSAC=1`
- **gzip + brotli http server-side compression** - h1 and h2 detection of client support
for server compression, and auto-application to files with mimetypes "text/*",
"application/javascript" and "image/svg.xml".
Cmake config: `-DLWS_WITH_HTTP_STREAM_COMPRESSION=1` for gzip, optionally also give
`-DLWS_WITH_HTTP_BROTLI=1` for preferred `br` brotli compression
- **managed disk cache** - API for managing a directory containing cached files
with hashed names, and automatic deletion of LRU files once the cache is
above a given limit.
2018-11-19 07:40:47 +08:00
[lws diskcache docs ](https://libwebsockets.org/git/libwebsockets/tree/include/libwebsockets/lws-diskcache.h ),
2018-11-16 09:10:41 +08:00
Cmake config: `-DLWS_WITH_DISKCACHE=1`
- **http reverse proxy** - lws mounts support proxying h1 or h2 requests to
a local or remote IP, or unix domain socket over h1. This allows microservice
type architectures where parts of the common URL space are actually handled
by external processes which may be remote or on the same machine.
[lws gitohashi serving ](https://libwebsockets.org/git/ ) is handled this way.
2018-11-19 07:40:47 +08:00
[unix domain sockets reverse proxy docs ](https://libwebsockets.org/git/libwebsockets/tree/READMEs/README.unix-domain-reverse-proxy.md ),
CMake config: `-DLWS_WITH_HTTP_PROXY=1` and `-DLWS_UNIX_SOCK=1` for Unix Domain Sockets
- **update minimal examples for strict Content Security Policy** the minimal
examples now show the best practices around Content Security Policy and
disabling inline Javascript. Updated examples that are served with the
recommended security restrictions show a new "Strict Content Security Policy"
graphic. [Read how to upgrade your applications to use a strict CSP ](https://libwebsockets.org/git/libwebsockets/tree/READMEs/README.content-security-policy.md ).
2018-11-16 09:10:41 +08:00
- **release policy docs** - unsure what branch, version or tag to use, or how
to follow master cleanly? [Read the release policy docs ](https://libwebsockets.org/git/libwebsockets/tree/READMEs/README.release-policy.md )
2018-11-19 07:40:47 +08:00
which explain how and why lws is developed, released and maintained.
2018-11-16 09:10:41 +08:00
2018-09-02 14:35:37 +08:00
## v3.0.1 released
See the git log for the list of fixes.
2018-05-07 13:38:53 +08:00
## v3.0.0 released
2018-06-11 14:29:07 +08:00
See the changelog for info https://libwebsockets.org/git/libwebsockets/tree/changelog?h=v3.0-stable
2018-05-07 13:38:53 +08:00
2018-04-20 10:33:23 +08:00
## Major CI improvements for QA
2018-11-16 09:10:41 +08:00
The Travis build of lws done on every commit now runs:
2018-04-20 10:33:23 +08:00
Tests|Count|Explanation
---|---|---
2018-11-16 09:10:41 +08:00
Build / Linux / gcc|16|-Wall -Werror cmake config variants
Build / Mac / Clang|16|-Wall -Werror cmake config variants
2018-04-20 10:33:23 +08:00
Build / Windows / MSVC|7|default
2018-11-16 09:10:41 +08:00
Selftests|openssl:43, mbedtls:43|minimal examples built and run against each other and remote server
2018-04-20 10:33:23 +08:00
attack.sh|225|Correctness, robustness and security tests for http parser
Autobahn Server|480|Testing lws ws client, including permessage-deflate
Autobahn Client|480|Testing lws ws server, including permaessage-deflate
2018-05-01 12:41:42 +08:00
h2spec|openssl:146, mbedtls:146|Http/2 server compliance suite (in strict mode)
h2load|openssl:6, mbedtls:6|Http/2 server load tool (checks 10K / 100K in h1 and h2, at 1, 10, 100 concurrency)
2018-04-27 13:09:15 +08:00
h2load SMP|6|Http/2 and http/1.1 server load checks on SMP server build
2018-04-20 10:33:23 +08:00
2018-11-16 09:10:41 +08:00
The over 1,500 tests run on every commit take 1hr 15 of compute time to complete.
2018-04-20 10:33:23 +08:00
If any problems are found, it breaks the travis build, generating an email.
2018-11-16 09:10:41 +08:00
Codacy also checks every patch and the information used to keep lws at zero issues.
Current master is checked by Coverity at least daily and kept at zero issues.
2018-04-20 10:33:23 +08:00
Current master passes all the tests and these new CI arrangements will help
keep it that way.
2018-03-11 11:26:06 +08:00
## Lws has the first official ws-over-h2 server support
2018-08-14 19:09:23 +08:00
2018-03-22 07:44:02 +08:00
2018-11-16 09:10:41 +08:00
There's a new [RFC ](https://tools.ietf.org/html/rfc8441 ) that enables multiplexing ws connections
2018-03-11 11:26:06 +08:00
over an http/2 link. Compared to making individual tcp and tls connections for
each ws link back to the same server, this makes your site start up radically
2018-03-20 13:28:25 +08:00
faster, and since all the connections are in one tls tunnel, with considerable memory
2018-03-11 11:26:06 +08:00
reduction serverside.
To enable it on master you just need -DLWS_WITH_HTTP2=1 at cmake. No changes to
existing code are necessary for either http/2 (if you use the official header creation
apis if you return your own headers, as shown in the test apps for several versions)
or to take advantage of ws-over-h2. When built with http/2 support, it automatically
falls back to http/1 and traditional ws upgrade if that's all the client can handle.
2018-03-20 13:28:25 +08:00
Currently only Chrome Canary v67 supports this ws-over-h2 encapsulation (chrome
2018-11-16 09:10:41 +08:00
must be started with `--enable-websocket-over-http2` switch to enable it currently),
and patches exist for Firefox. Authors of both browser implementations tested
against the lws server implementation.
2018-03-11 11:26:06 +08:00
2018-03-08 12:04:13 +08:00
## New "minimal examples"
2018-06-11 14:29:07 +08:00
https://libwebsockets.org/git/libwebsockets/tree/minimal-examples
2018-03-08 12:04:13 +08:00
2018-07-30 15:22:33 +08:00
These are like the test apps, but focus on doing one thing, the best way, with the
minimum amount of code. For example the minimal-http-server serves the cwd on
http/1 or http/2 in 50 LOC. Same thing with tls is just three more lines.
2018-03-08 12:04:13 +08:00
2018-03-20 13:28:25 +08:00
They build standalone, so it's easier to copy them directly to start your own project; they
2018-03-08 12:04:13 +08:00
are CC0 licensed (public domain) to facilitate that.
## Windows binary builds
2018-07-30 15:22:33 +08:00
32- and 64-bit Windows binary builds are available via Appveyor. Visit
[lws on Appveyor ](https://ci.appveyor.com/project/lws-team/libwebsockets ),
2017-10-26 07:24:45 +08:00
click on a build, the ARTIFACTS, and unzip the zip file at `C:\Program Files (x86)/libwebsockets` .
2018-03-08 12:04:13 +08:00
## Support
2016-08-07 08:33:08 +08:00
2013-02-06 16:07:27 +09:00
This is the libwebsockets C library for lightweight websocket clients and
servers. For support, visit
2016-02-21 10:42:46 +08:00
https://libwebsockets.org
2013-02-06 16:07:27 +09:00
and consider joining the project mailing list at
2016-02-21 10:42:46 +08:00
https://libwebsockets.org/mailman/listinfo/libwebsockets
2013-02-06 16:07:27 +09:00
2016-02-21 10:42:46 +08:00
You can get the latest version of the library from git:
2013-02-06 16:07:27 +09:00
2016-02-21 10:42:46 +08:00
- https://libwebsockets.org/git
2013-02-06 16:07:27 +09:00
2016-06-20 17:05:31 +08:00
Doxygen API docs for master: https://libwebsockets.org/lws-api-doc-master/html/index.html
2013-02-06 16:07:27 +09:00
