#-
# 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

$Module ece 3 "Varnish Module for encrypted Content-Encoding per RFC 8188"

$ABI vrt

$Synopsis manual

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 ...

$Object encrypter(PRIV_VCL, STRING name, BYTES rs=4096,
                  STRING key_hdr="X-ECE-Key-ID")

Create an encryption filter named ``name`` with custom parameters.

XXX ...

$Method VOID .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 ...

$Object decrypter(PRIV_VCL, STRING name, BYTES chunksz=16384,
		  BYTES max_rs=1048576)

Create a decryption filter named ``name`` with custom parameters.

XXX ...

$Method VOID .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 ...

$Function 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 ...

$Function 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 ...

$Function 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 ...

$Function VOID delete_key(STRING id)

Remove the keying material identified by ``id``.

XXX ...

$Function BOOL key_exists(STRING id)

Returns true iff the keying material identified by ``id`` has been added.

XXX ...

$Function TIME key_added(STRING id)

Returns the time at which the keying material identified by ``id`` was
added.

XXX ...

$Function TIME key_updated(STRING id)

Returns the time at which the keying material identified by ``id`` was
last updated.

XXX ...

$Function 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 ...

$Function STRING libcrypto_version()

Return the libcrypto version string.

Example::

  std.log("Using libcrypto version: " + ece.libcrypto_version());

$Function 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`_

$Event event