#- # Copyright (c) 2019 UPLEX Nils Goroll Systemoptimierung # All rights reserved # # Author: Geoffrey Simmons # # 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 `_ in the source repository. LIMITATIONS =========== XXX ... SEE ALSO ======== * varnishd(1) * vcl(7) * `RFC 8188`_ $Event event