Commit e3a7f88c authored by Nils Goroll's avatar Nils Goroll

documentation update

parent 8af42be4
Pipeline #280 skipped
......@@ -44,13 +44,10 @@ This Varnish Module (VMOD) generates message digests, keyed-hash
message authentication codes (HMACs) and checksums using the VCL data
type BLOB, which may contain arbitrary data of any length.
Currently (in Varnish versions through 5.0), BLOBs may only be used in
VCL as arguments of VMOD functions, so this VMOD must be used in
combination with other VMODs. For example, the blob VMOD (see `SEE
ALSO`_) may be used to convert BLOBs using binary-to-text encodings,
to initialize data for this VMOD and to save its results. The
advantage of using BLOBs is that operations on the data are separated
from issues such as encoding.
This vmod is intended for use together with the blob vmod from the
Varnish-Cache distribution for binary-to-text encodings, to initialize
data and to save results. The advantage of using BLOBs is that
operations on the data are separated from issues such as encoding.
digest object and hash function
-------------------------------
......@@ -99,7 +96,6 @@ Here are some examples::
import blobdigest;
import blob;
import blob;
sub vcl_init {
# Create a BLOB consisting of the string "foo"
......@@ -125,11 +121,11 @@ Here are some examples::
sub vcl_recv {
# Use the fooprefix object to get the hash of "foobar"
if (!fooprefix.update(blob.decode(IDENTITY, "bar"))) {
if (!fooprefix.update(blob.decode(encoded="bar"))) {
call do_error;
}
set req.http.Foobar-Hash = blob.encode(BASE64,
fooprefix.final());
set req.http.Foobar-Hash = blob.encode(encoding=BASE64,
blob=fooprefix.final());
}
sub vcl_backend_response {
......@@ -137,16 +133,17 @@ Here are some examples::
# The uses of the object in client and backend contexts have
# no effect on each other, or on subsequent client or
# backend transactions.
if (!fooprefix.update(blob.decode(IDENTITY, "baz"))) {
if (!fooprefix.update(blob.decode(encoded="baz"))) {
call do_error;
}
set req.http.Foobaz-Hash = blob.encode(BASE64,
fooprefix.final());
set req.http.Foobaz-Hash = blob.encode(encoding=BASE64,
blob=fooprefix.final());
}
sub vcl_deliver {
# Retrieve the SHA256 hash of "foo" computed in the constructor
set req.http.Foo-Hash = blob.encode(BASE64, foohash.final());
set req.http.Foo-Hash = blob.encode(encoding=BASE64,
blob=foohash.final());
}
The ``hash()`` function computes the message digest for its argument
......@@ -164,16 +161,16 @@ and returns the result. It is functionally equivalent to using a
sub vcl_recv {
# Get the SHA256 hash of "foo"
set req.http.Foo-Hash-Functional
= blob.encode(BASE64,
blobdigest.hash(blob.decode(IDENTITY,
"foo")));
= blob.encode(encoding=BASE64,
blob=blobdigest.hash(blob.decode(encoded=
"foo")));
# Same result using the object interface
if (!sha256.update(blob.decode(IDENTITY, "foo"))) {
if (!sha256.update(blob.decode(encoded="foo"))) {
call do_error;
}
set req.http.Foo-Hash-Object
= blob.encode(BASE64, sha256.final());
= blob.encode(encoding=BASE64, blob=sha256.final());
}
The ``hash()`` function makes for a somewhat less verbose interface,
......@@ -329,7 +326,6 @@ Example::
import blobdigest;
import blob;
import blob;
sub vcl_init {
# Compute and save the SHA512 hash for "foo"
......@@ -347,23 +343,23 @@ Example::
sub vcl_recv {
# Retrieve the hash for "foo" computed in vcl_init
set req.http.Foo-Hash
= blob.encode(BASE64, foohash.final());
= blob.encode(encoding=BASE64, blob=foohash.final());
# Compute the base64-encoded SHA3_256 hash for "bar"
if (!sha3_256.update(blob.decode(IDENTITY, "bar"))) {
if (!sha3_256.update(blob.decode(encoded="bar"))) {
call do_client_error;
}
set req.http.Bar-Hash-Base64
= blocbcode.decode(BASE64, sha3_256.final());
= blocbcode.decode(encoding=BASE64, blob=sha3_256.final());
}
sub vcl_backend_fetch {
# Compute the base64-encoded SHA3_256 hash for "baz"
if (!sha3_256.update(blob.decode(IDENTITY, "baz"))) {
if (!sha3_256.update(blob.decode(encoded="baz"))) {
call do_client_error;
}
set bereq.http.Baz-Hash-Base64
= blocbcode.encode(BASE64, sha3_256.final());
= blocbcode.encode(encoding=BASE64, blob=sha3_256.final());
}
sub vcl_backend_response {
......@@ -413,7 +409,7 @@ Example::
set req.http.SHA256
= blob.encode(HEX, UPPER,
blobdigest.hash(SHA256,
blob.decode(BASE64, "Zm9v"));
blob.decode(decoding=BASE64, encoded="Zm9v"));
.. _obj_hmac:
......@@ -496,8 +492,8 @@ Example::
set req.http.HMAC
= blob.encode(HEX, UPPER,
blobdigest.hmacf(SHA512,
blob.decode(BASE64, "Zm9v"),
blob.decode(IDENTITY,
blob.decode(decoding=BASE64, encoded="Zm9v"),
blob.decode(encoded=
req.http.Msg)));
.. _func_version:
......@@ -518,13 +514,11 @@ Example::
REQUIREMENTS
============
This version of the VMOD requires Varnish since version 5.1. See the
This version of the VMOD requires Varnish since version 5.2. See the
source repository for versions that are compatible with other versions
of Varnish.
The gcc compiler and Perl 5 are required for the build. For the
self-tests invoked by ``make check``, the VMODs ``blob`` and
``blob`` must be installed (see `SEE ALSO`_).
The gcc compiler and Perl 5 are required for the build.
LIMITATIONS
===========
......@@ -567,8 +561,6 @@ SEE ALSO
* varnishd(1)
* vcl(7)
* source repository: https://code.uplex.de/uplex-varnish/libvmod-blobdigest
* VMOD blob: https://code.uplex.de/uplex-varnish/libvmod-blob
* VMOD blob: https://code.uplex.de/uplex-varnish/libvmod-blob
* RHash:
* https://github.com/rhash/RHash
......
......@@ -29,13 +29,10 @@ This Varnish Module (VMOD) generates message digests, keyed-hash
message authentication codes (HMACs) and checksums using the VCL data
type BLOB, which may contain arbitrary data of any length.
Currently (in Varnish versions through 5.0), BLOBs may only be used in
VCL as arguments of VMOD functions, so this VMOD must be used in
combination with other VMODs. For example, the blob VMOD (see `SEE
ALSO`_) may be used to convert BLOBs using binary-to-text encodings,
to initialize data for this VMOD and to save its results. The
advantage of using BLOBs is that operations on the data are separated
from issues such as encoding.
This vmod is intended for use together with the blob vmod from the
Varnish-Cache distribution for binary-to-text encodings, to initialize
data and to save results. The advantage of using BLOBs is that
operations on the data are separated from issues such as encoding.
digest object and hash function
-------------------------------
......@@ -84,7 +81,6 @@ Here are some examples::
import blobdigest;
import blob;
import blob;
sub vcl_init {
# Create a BLOB consisting of the string "foo"
......@@ -286,7 +282,6 @@ Example::
import blobdigest;
import blob;
import blob;
sub vcl_init {
# Compute and save the SHA512 hash for "foo"
......@@ -445,13 +440,11 @@ Example::
REQUIREMENTS
============
This version of the VMOD requires Varnish since version 5.1. See the
This version of the VMOD requires Varnish since version 5.2. See the
source repository for versions that are compatible with other versions
of Varnish.
The gcc compiler and Perl 5 are required for the build. For the
self-tests invoked by ``make check``, the VMODs ``blob`` and
``blob`` must be installed (see `SEE ALSO`_).
The gcc compiler and Perl 5 are required for the build.
LIMITATIONS
===========
......@@ -494,8 +487,6 @@ SEE ALSO
* varnishd(1)
* vcl(7)
* source repository: https://code.uplex.de/uplex-varnish/libvmod-blobdigest
* VMOD blob: https://code.uplex.de/uplex-varnish/libvmod-blob
* VMOD blob: https://code.uplex.de/uplex-varnish/libvmod-blob
* RHash:
* https://github.com/rhash/RHash
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment