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