minimal examples: update for CSP best practices

1) update the logos to svg 2) add svg icon for strict security policy where used 3) define new vhost option flag to enforce sending CSP headers with the result code 4) add vhost option flag to minimal examples to enforce sending CSP where applicable 5) Go through all the affecting examples confirming they still work 6) add LWS_RECOMMENDED_MIN_HEADER_SPACE constant (currently 2048) to clarify when we need a buffer to hold headers... with CSP the headers have become potentially a lot larger.
mgiaco · Nov 21, 2018 · d9f982a · d9f982a
1 parent ac03254
commit d9f982a
Show file tree

Hide file tree

Showing 185 changed files with 5,953 additions and 868 deletions.
diff --git a/README.md b/README.md
@@ -8,7 +8,8 @@ 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.
 
-[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.
+[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.
 
 ![overview](./doc-assets/lws-overview.svg)
 
@@ -19,38 +20,38 @@ News
 
  - **lws threadpool** - lightweight pool of pthreads integrated to lws wsi, with all
    synchronization to event loop handled internally, queue for excess tasks
-   [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)
+   [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), 
    Cmake config: `-DLWS_WITH_THREADPOOL=1`
 
  - **libdbus support** integrated on lws event loop
-   [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)
+   [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), 
    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
-   [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)
+   [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), 
    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.
-   [lws_tokenize docs](https://libwebsockets.org/git/libwebsockets/tree/include/libwebsockets/lws-tokenize.h)
+   [lws_tokenize docs](https://libwebsockets.org/git/libwebsockets/tree/include/libwebsockets/lws-tokenize.h), 
    [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.
-   [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)
+   [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), 
    Cmake config: `-DLWS_WITH_FTS=1 -DLWS_WITH_LWSAC=1`
 
  - **gzip + brotli http server-side compression** - h1 and h2 detection of client support
@@ -62,19 +63,26 @@ News
  - **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.
-   [lws diskcache docs](https://libwebsockets.org/git/libwebsockets/tree/include/libwebsockets/lws-diskcache.h)
+   [lws diskcache docs](https://libwebsockets.org/git/libwebsockets/tree/include/libwebsockets/lws-diskcache.h), 
    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.
-   [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`
+   [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).
 
  - **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)
+   which explain how and why lws is developed, released and maintained.
 
 ## v3.0.1 released
 

diff --git a/READMEs/README.content-security-policy.md b/READMEs/README.content-security-policy.md
@@ -85,7 +85,8 @@ completely rejected by the browser.
 Inline `onclick()` etc are kinds of inline scripting and are banned.
 
 Modern browsers have offered a different system called ["EventListener" for
-a while](https://developer.mozilla.org/en-US/docs/Web/API/EventListener) which allows binding of events to DOM elements in JS.
+a while](https://developer.mozilla.org/en-US/docs/Web/API/EventListener)
+which allows binding of events to DOM elements in JS.
 
 A bunch of different named events are possible to listen on, commonly the
 `.js` file will ask for one or both of

diff --git a/READMEs/README.unix-domain-reverse-proxy.md b/READMEs/README.unix-domain-reverse-proxy.md
@@ -7,7 +7,9 @@ lws is able to use a mount to place reverse proxies into the URL space.
 These are particularly useful when using Unix Domain Sockets, basically
 files in the server filesystem, to communicate between lws and a separate
 server process and integrate the result into a coherent URL namespace on
-the lws side.
+the lws side.  It's also possible to proxy using tcp sockets.
+
+![overview](../doc-assets/http-proxy-overview.svg)
 
 This has the advantage that the actual web server that forwards the
 data from the unix socket owner is in a different process than the server

diff --git a/changelog b/changelog
@@ -12,6 +12,11 @@ v3.1.0
  - CHANGE: CMAKE:
      - LWS_WITH_HTTP2:         now defaults ON
 
+ - CHANGE: Minimal examples updated to use Content Security Policy best
+   practices, using
+   `LWS_SERVER_OPTION_HTTP_HEADERS_SECURITY_BEST_PRACTICES_ENFORCE` vhost
+   option flag and disabling of inline style and scripts.
+
  - NEW: CMAKE
      - LWS_FOR_GITOHASHI: sets various cmake options suitable for gitohashi
      - LWS_WITH_ASAN: for Linux, enable build with ASAN