canonical libwebsockets.org websocket library
Find a file
Andy Green d678ea3cd2 renable deflate frame buffer expansion fixing DoS
This reverts the removal of the deflate_frame code that was crashing after porting
David Galeano's code: he pointed out there's a typo in the merged version causing
the crash which is fixed here.

However the fixed code has a problem, there's no limit (other than int size) to the
amount of memory it will try to malloc, which can allow a DoS of the server by the
client sending malicious compression states that inflate to a large amount.  I have
added checking for OOM already that will avert the segfault that would otherwise follow
but the server will be unusuable if malicious connections were made repeatedly each
forcing it to allocate large buffers and cause small allocations on other connections
to fail.

The patch changes the code to use realloc(), and introduces a configurable limit
on the amount of memory one connection may need for zlib before the server hangs
up the connection.  It defaults to 64KBytes but can be set from ./configure as
described now in the README.

Signed-off-by: Andy Green <andy.green@linaro.org>
2013-01-12 23:36:27 +08:00
lib renable deflate frame buffer expansion fixing DoS 2013-01-12 23:36:27 +08:00
scripts refactor-into-dirs.patch 2010-11-01 09:12:17 +00:00
test-server logging extend level set api to allow setting emission function 2013-01-12 09:17:42 +08:00
win32port zlib update 1.2.7 2013-01-10 10:03:42 +08:00
.gitignore Ignoring linux build files 2013-01-09 15:46:11 +08:00
autogen.sh use autogen.sh 2012-10-06 15:17:01 +08:00
configure.ac fix config enable name for getifaddrs 2013-01-12 23:31:39 +08:00
COPYING add-COPYING-lgpl-2.1.patch 2010-11-08 17:12:19 +00:00
INSTALL add-INSTALL.patch 2010-11-12 13:11:50 +00:00
libwebsockets-api-doc.html logging extend level set api to allow setting emission function 2013-01-12 09:17:42 +08:00
libwebsockets.pc.in add pkg-config file libwebsockets.pc 2012-10-19 18:26:22 +08:00
libwebsockets.spec uplevel-rpm-spec-to-include-new-extpoll-sample.patch 2011-02-13 09:08:11 +00:00
Makefile.am add pkg-config file libwebsockets.pc 2012-10-19 18:26:22 +08:00
README-test-server renable deflate frame buffer expansion fixing DoS 2013-01-12 23:36:27 +08:00
README.rst Added README file with some useful tips for using the library. 2013-01-10 12:45:54 +08:00

Useful tips for using `libwebsockets`
=====================================

Maximum number of clients
-------------------------
There is a hard limit on the maximum number of clients the library will accept and by default it is set to **100**.
This limit can be changed by modifying the **MAX_CLIENTS** preprocessor macro in the file
**lib/private-libwebsockets.h**. The higher the limit the more memory the library will allocate at startup.

SSL performance
---------------
It is recommended to tweak the ciphers allowed on secure connections for performance reasons,
otherwise a slow algorithm may be selected by the two endpoints and the server could expend most of its time just
encrypting and decrypting data, severely limiting the amount of messages it will be able to handle per second.
To limit the ciphers supported on secure connections you should modify the preprocessor macro **CIPHERS_LIST_STRING**
in the file **lib/private-libwebsockets.h**. For example::

    #define CIPHERS_LIST_STRING "RC4-MD5:RC4-SHA:AES128-SHA:AES256-SHA:HIGH:!DSS:!aNULL"

Other tweaks
------------
There are several preprocessor macros that could be tweaked to reduce memory usage,
to increase performance or to change the behaviour of the library to suit your needs,
they are all located in the file **lib/private-libwebsockets.h**.

Big frames
----------
The library process data from the sockets in chunks of **4KB** (defined by the macro **MAX_USER_RX_BUFFER**),
these chunks will be passed to the client callback as **LWS_CALLBACK_RECEIVE**.
If you want to know whether you have all the data for the current frame you need to use the function
**libwebsockets_remaining_packet_payload**.

Fragmented messages
-------------------
To support fragmented messages you need to check for the final frame of a message with
**libwebsocket_is_final_fragment**. This check can be combined with **libwebsockets_remaining_packet_payload**
to gather the whole contents of a message like in this example::

    case LWS_CALLBACK_RECEIVE:
    {
        Client * const client = (Client *)user;
        const size_t remaining = libwebsockets_remaining_packet_payload(wsi);
        if (0 == remaining &&
            libwebsocket_is_final_fragment(wsi))
        {
            if (client->HasFragments())
            {
                client->AppendMessageFragment(in, len, 0);
                in = (void *)client->GetMessage();
                len = client->GetMessageLength();
            }

            client->ProcessMessage((char *)in, len, wsi);

            client->ResetMessage();
        }
        else
        {
            client->AppendMessageFragment(in, len, remaining);
        }
    }
    break;

HTTP requests
-------------
If your server is going to support regular HTTP requests by handling **LWS_CALLBACK_HTTP** it is recommended to
**return 1** as the result of the callback after you write the response,
this will tell the library to automatically close the connection.
Closing the connection will liberate an slot for another HTTP request,
otherwise it would be up to the browser to close the connection,
which could be an issue because the library has a hard limit on the number of open connections, as explained before.