README.rst 5.17 KB
Newer Older
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274
..
.. 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