Add README, LICENSE, CONTRIBUTING etc (now that the VMOD is public).

CONTRIBUTING.rst

+CONTRIBUTING
+============
+
+To contribute code or documentation, submit a pull request at the
+`source repository website
+<https://code.uplex.de/uplex-varnish/libvmod-ece>`_.
+
+If you have a problem or discover a bug, you can post an `issue
+<https://code.uplex.de/uplex-varnish/libvmod-ece/issues>`_ at
+the website. You can also write to <varnish-support@uplex.de>.
+
+For developers
+--------------
+
+The VMOD source code is in C, and compilation has been tested with gcc
+and clang. The code MUST always compile successfully with both of
+them.
+
+The build specifies C99 conformance for C sources (``-std=c99``). All
+compiler warnings are turned on, and all warnings are considered
+errors (``-Werror -Wall -Wextra``).  The code MUST always build
+without warnings or errors under these constraints.
+
+By default, ``CFLAGS`` is set to ``-g -O2``, so that symbols are
+included in the shared library, and optimization is at level
+``O2``. To change or disable these options, set ``CFLAGS`` explicitly
+before calling ``configure`` (it may be set to the empty string).
+
+For development/debugging cycles, the ``configure`` option
+``--enable-debugging`` is recommended (off by default). This will turn
+off optimizations and function inlining, so that a debugger will step
+through the code as expected.
+
+Experience has shown that adding ``-ggdb3`` to ``CFLAGS`` is
+beneficial if you need to examine the VMOD with the gdb debugger. The
+shared object for a VMOD is loaded from a directory relative to the
+Varnish home directory (by default
+``/usr/local/var/varnish/$INSTANCE`` for development builds). A
+debugger needs to locate the shared object from that relative path to
+load its symbols, so the Varnish home directory should be the current
+working directory when the debugger is run. For example::
+
+  # To run gdb and examine a coredump
+  $ cd /usr/local/var/myinstance
+  $ gdb /usr/local/sbin/varnishd /path/to/coredump
+
+By default, the VMOD is built with the stack protector enabled
+(compile option ``-fstack-protector``), but it can be disabled with
+the ``configure`` option ``--disable-stack-protector``.
+
+Setting the salt for testing
+============================
+
+The salt bytes specified by RFC 8188 are usually generated for an
+encrypted message from the ``libcrypto`` pseudo-random number
+generator. The test scripts include tests against known answers given
+in RFC 8188, for which a fixed salt is specified. To test message
+encryption against the known answer, it is necessary to set the salt
+bytes.
+
+This is possible when the ``configure`` script is invoked with
+``--enable-set-salt``. When set-salt is enabled, a base64-encoded salt
+value may be set in the backend request header with the fixed name
+``XYZZY-ECE-Salt``::
+
+  sub vcl_backend_response {
+	# Set the salt bytes specified in the RFC 8188 examples.
+        set bereq.http.XYZZY-ECE-Salt = "I1BsxtFttlv3u/Oo94xnmw==";
+        set beresp.filters = "ece_encrypt";
+  }
+
+The base64 decoding function from ``libcrypto`` is used to decode the
+header contents. This function uses the alphabet ``[a-ZA-Z0-9/+]`` and
+``=`` padding, just like the ``BASE64`` encoding scheme used by VMOD
+blob in the standard Varnish distribution. Since the salt is specified
+by RFC 8188 to be 16 bytes long, the base64 encoding is always 24
+characters long, including two ``=`` padding characters.
+
+For encryption, when the set-salt feature is enabled, the VFP looks
+for the header, and if it is present, the salt is set from the
+header's base64-decoded contents. If the header is not present, then
+random salt is generated as in normal operation.
+
+The tests in ``src/tests`` that require specific salt are skipped
+unless the environment variable ``ENABLE_SET_SALT`` is set to
+``yes``. When ``configure`` is invoked with ``--enable-set-salt``,
+``automake`` ensures that ``ENABLE_SET_SALT=yes`` when ``make check``
+is invoked.
+
+The set-salt feature should *not* be enabled for production builds.
+It should be used *only* for testing purposes.
+
+Test coverage
+=============
+
+.. _lcov: http://ltp.sourceforge.net/coverage/lcov.php
+
+The autotools generate a make target ``coverage``, which can be used
+to generate test coverage reports, if you have the tools ``lcov`` and
+``genhtml`` installed (see `lcov`_). HTML coverage reports are
+generated in ``src/coverage``::
+
+  $ make coverage
+  # Now point your browser to src/coverage/index.html
+
+By default, ``configure`` checks if both of ``lcov`` and ``genhtml``
+can be found on the ``PATH``; if they cannot be found, then coverage
+reports cannot be generated (and ``make coverage`` results in an
+error). If necessary, you can invoke ``configure`` with
+``--with-lcov=/path/to/lcov`` and/or
+``--with-genhtml=/path/to/genhtml`` to specify their locations.
+
+Invoking ``make coverage`` has these effects:
+
+* ``make clean`` is invoked.
+
+* Code is compiled with ``CFLAGS`` set to generate ``gcov`` output.
+  This entails disabling debugging and optimization.
+
+* ``make check`` is invoked.
+
+* ``lcov`` and ``genhtml`` are used to generate the reports.
+
+After running ``make coverage``, it may be necessary to clean up with
+``make clean`` and rebuild the code before you continue development
+and debugging, since the symbols for ``gcov`` may interfere with
+linkage and testing.

COPYING

+See LICENSE for details.
+

INSTALL.rst

+INSTALLATION
+============
+
+Building from source
+~~~~~~~~~~~~~~~~~~~~
+
+The VMOD is built against a Varnish installation, and the autotools
+use ``pkg-config(1)`` to locate the necessary header files and other
+resources. This sequence will install the VMOD::
+
+  > ./autogen.sh	# for builds from the git repo
+  > ./configure
+  > make
+  > make check		# to run unit tests in src/tests/*.vtc
+  > make distcheck	# run check and prepare a distribution tarball
+  > sudo make install
+
+See `CONTRIBUTING.rst <CONTRIBUTING.rst>`_ for notes about building
+from source.
+
+The VMOD requires the ``libcrypto`` library for crytographic
+operations, which may be provided by OpenSSL or LibreSSL. The
+``libcrypto`` headers and library are also located via
+``pkg-config(1)``.
+
+If you have installed Varnish in non-standard directories, call
+``autogen.sh`` and ``configure`` with the ``PKG_CONFIG_PATH``
+environment variable set to include the paths where the ``.pc`` files
+can be located for ``varnishapi`` and ``libcrypto``. For example, when
+varnishd configure was called with ``--prefix=$PREFIX``, use::
+
+  > PKG_CONFIG_PATH=${PREFIX}/lib/pkgconfig
+  > export PKG_CONFIG_PATH
+
+By default, the vmod ``configure`` script installs the vmod in
+the same directory as Varnish, determined via ``pkg-config(1)``. The
+vmod installation directory can be overridden by passing the
+``VMOD_DIR`` variable to ``configure``.
+
+Other files such as the man-page are installed in the locations
+determined by ``configure``, which inherits its default ``--prefix``
+setting from Varnish.

LICENSE

+Copyright (c) 2019 UPLEX Nils Goroll Systemoptimierung
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions
+are met:
+1. Redistributions of source code must retain the above copyright
+   notice, this list of conditions and the following disclaimer.
+2. Redistributions in binary form must reproduce the above copyright
+   notice, this list of conditions and the following disclaimer in the
+   documentation and/or other materials provided with the distribution.
+
+THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
+ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+ARE DISCLAIMED.  IN NO EVENT SHALL AUTHOR OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
+OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
+HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
+LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
+OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
+SUCH DAMAGE.

Makefile.am

@@ -7,3 +7,21 @@ DISTCHECK_CONFIGURE_FLAGS = \
 
 coverage:
 	$(MAKE) $(AM_MAKEFLAGS) -C src coverage
+
+EXTRA_DIST = README.rst LICENSE COPYING CONTRIBUTING.rst INSTALL.rst
+
+doc_DATA = README.rst LICENSE COPYING CONTRIBUTING.rst INSTALL.rst
+
+README.rst: src/vmod_ece.vcc
+	$(MAKE) $(AM_MAKEFLAGS) -C src vmod_ece.man.rst
+	cp src/vmod_ece.man.rst README.rst
+
+%.1 %.2 %.3 %.4 %.5 %.6 %.7 %.8 %.9:
+if HAVE_RST2MAN
+	${RST2MAN} $< $@
+else
+	@echo "========================================"
+	@echo "You need rst2man installed to make dist"
+	@echo "========================================"
+	@false
+endif

README.rst

+..
+.. NB:  This file is machine generated, DO NOT EDIT!
+..
+.. Edit vmod.vcc and run make instead
+..
+
+.. role:: ref(emphasis)
+
+========
+vmod_ece
+========
+
+----------------------------------------------------------
+Varnish Module for encrypted Content-Encoding per RFC 8188
+----------------------------------------------------------
+
+:Manual section: 3
+
+
+SYNOPSIS
+========
+
+::
+
+  import ece;
+
+  # The built-in "ece_decrypt" filter decrypts backend responses.
+  sub vcl_backend_response {
+	if (beresp.http.Content-Encoding == "aes128gcm") {
+		set beresp.filters = "ece_decrypt";
+	}
+  }
+
+  # VMOD version
+  STRING ece.version()
+
+DESCRIPTION
+===========
+
+VMOD ece is a Varnish module that supports the use of encrypted
+content encoding. It enables configurations that implement and
+interpret Content-Encoding ``aes128gcm``, by providing these
+resources:
+
+* a Varnish Fetch Processor (VFP) to decrypt backend responses
+
+* XXX
+
+Encrypted Content-Encoding for HTTP is specified in `RFC
+8188`_. Details of the encoding are beyond the scope of this manual;
+users of this library are advised to consult the RFC as well, to fully
+understand how to use it properly and securely.
+
+XXX ...
+
+Encryption and HTTP
+--------------------
+
+XXX ...
+
+.. _ece.encrypter():
+
+new xencrypter = ece.encrypter(STRING name, BYTES rs, STRING key_hdr)
+---------------------------------------------------------------------
+
+::
+
+   new xencrypter = ece.encrypter(
+      STRING name,
+      BYTES rs=4096,
+      STRING key_hdr="X-ECE-Key-ID"
+   )
+
+Create an encryption filter named ``name`` with custom parameters.
+
+XXX ...
+
+.. _xencrypter.create_stats():
+
+VOID xencrypter.create_stats()
+------------------------------
+
+Create statistics, observable with a tool like ``varnishstat(1)``, for
+the custom encryption filter. These are the same as the counters
+created for the standard ``"ece_encrypt"`` filter. See `STATISTICS`_
+below for details.
+
+XXX ...
+
+.. _ece.decrypter():
+
+new xdecrypter = ece.decrypter(STRING name, BYTES chunksz, BYTES max_rs)
+------------------------------------------------------------------------
+
+::
+
+   new xdecrypter = ece.decrypter(
+      STRING name,
+      BYTES chunksz=16384,
+      BYTES max_rs=1048576
+   )
+
+Create a decryption filter named ``name`` with custom parameters.
+
+XXX ...
+
+.. _xdecrypter.create_stats():
+
+VOID xdecrypter.create_stats()
+------------------------------
+
+Create statistics for the custom decryption filter, the same as the
+counters created for the standard ``"ece_decrypt"`` filter. See
+`STATISTICS`_ for details.
+
+XXX ...
+
+.. _ece.add_key():
+
+VOID add_key(STRING id, BLOB key)
+---------------------------------
+
+Add the keying material identified by ``id`` with the contents of the
+blob ``key``, provided that ``id`` does not already exist.
+
+XXX ...
+
+.. _ece.update_key():
+
+VOID update_key(STRING id, BLOB key)
+------------------------------------
+
+Change the keying material identified by ``id`` to the contents of the
+blob ``key``, provided that ``id`` already exists.
+
+XXX ...
+
+.. _ece.set_key():
+
+VOID set_key(STRING id, BLOB key)
+---------------------------------
+
+Set the keying material identified by ``id`` to the contents of the
+blob ``key``. This is the "add-or-update" operation; key ``id`` is
+added if it does not already exist, and modified if it already exists.
+
+XXX ...
+
+.. _ece.delete_key():
+
+VOID delete_key(STRING id)
+--------------------------
+
+Remove the keying material identified by ``id``.
+
+XXX ...
+
+.. _ece.key_exists():
+
+BOOL key_exists(STRING id)
+--------------------------
+
+Returns true iff the keying material identified by ``id`` has been added.
+
+XXX ...
+
+.. _ece.key_added():
+
+TIME key_added(STRING id)
+-------------------------
+
+Returns the time at which the keying material identified by ``id`` was
+added.
+
+XXX ...
+
+.. _ece.key_updated():
+
+TIME key_updated(STRING id)
+---------------------------
+
+Returns the time at which the keying material identified by ``id`` was
+last updated.
+
+XXX ...
+
+.. _ece.dump_keys():
+
+VOID dump_keys(ENUM {LOCAL, UTC} tz=LOCAL)
+------------------------------------------
+
+Generate a synthetic client response body with information in CSV
+format (comma-separated values) about all of the keys that are
+currently stored.
+
+XXX ...
+
+.. _ece.libcrypto_version():
+
+STRING libcrypto_version()
+--------------------------
+
+Return the libcrypto version string.
+
+Example::
+
+  std.log("Using libcrypto version: " + ece.libcrypto_version());
+
+.. _ece.version():
+
+STRING version()
+----------------
+
+Return the version string for this VMOD.
+
+Example::
+
+  std.log("Using VMOD ece version: " + ece.version());
+
+STATISTICS
+==========
+
+XXX ...
+
+SECURITY
+========
+
+XXX ...
+
+ERRORS
+======
+
+XXX ...
+
+REQUIREMENTS
+============
+
+The VMOD currently requires the Varnish master branch. It also
+requires the ``libcrypto`` library for cryptographic operations, and
+has been tested with OpenSSL versions 1.1.1c and 1.1.1d.
+
+XXX ...
+
+INSTALLATION
+============
+
+See `INSTALL.rst <INSTALL.rst>`_ in the source repository.
+
+LIMITATIONS
+===========
+
+XXX ...
+
+SEE ALSO
+========
+
+* varnishd(1)
+* vcl(7)
+* `RFC 8188`_
+
+COPYRIGHT
+=========
+
+::
+
+  Copyright (c) 2019 UPLEX Nils Goroll Systemoptimierung
+  All rights reserved
+ 
+  Author: Geoffrey Simmons <geoffrey.simmons@uplex.de>
+ 
+  See LICENSE
+ 
+
+.. _RFC 8188: https://tools.ietf.org/html/rfc8188

src/vmod_ece.vcc

@@ -24,7 +24,7 @@ SYNOPSIS
 
   # The built-in "ece_decrypt" filter decrypts backend responses.
   sub vcl_backend_response {
-	if (beresp.http.Content-Encoding == "aes128gc") {
+	if (beresp.http.Content-Encoding == "aes128gcm") {
 		set beresp.filters = "ece_decrypt";
 	}
   }
@@ -178,8 +178,8 @@ REQUIREMENTS
 ============
 
 The VMOD currently requires the Varnish master branch. It also
-requires the ``libcrypto`` library, and has been tested with
-OpenSSL version 1.1.1c.
+requires the ``libcrypto`` library for cryptographic operations, and
+has been tested with OpenSSL versions 1.1.1c and 1.1.1d.
 
 XXX ...