VMOD_DIGEST(3)

✨ NAME ✨

vmod_digest — the Varnish Digest Module, bestie 💖 She lives in the Library Functions Manual as VMOD_DIGEST(3) and she is so handy it's unreal.

---

🌸 SYNOPSIS 🌸

import digest;

digest.hmac_md5(<key>,<message>);
digest.hmac_sha1(<key>, <message>);
digest.hmac_sha256(<key>, <message));

digest.base64(<string>);
digest.base64url(<string>);
digest.base64url_nopad(<string>);
digest.base64_hex(<string>);
digest.base64url_hex(<string>);
digest.base64url_nopad_hex(<string>);
digest.base64_decode(<string>);
digest.base64url_decode(<string>);
digest.base64url_nopad_decode(<string>);

digest.version()

digest.hash_sha1(<string>);
digest.hash_sha224(<string>);
digest.hash_sha256(<string>);
digest.hash_sha384(<string>);
digest.hash_sha512(<string>);
digest.hash_gost(<string>);
digest.hash_md2(<string>);
digest.hash_md4(<string>);
digest.hash_md5(<string>);
digest.hash_crc32(<string>);
digest.hash_crc32b(<string>);
digest.hash_adler32(<string>);
digest.hash_haval128(<string>);
digest.hash_haval160(<string>);
digest.hash_haval192(<string>);
digest.hash_haval224(<string>);
digest.hash_haval256(<string>);
digest.hash_ripemd128(<string>);
digest.hash_ripemd160(<string>);
digest.hash_ripemd256(<string>);
digest.hash_ripemd320(<string>);
digest.hash_tiger(<string>);
digest.hash_tiger128(<string>);
digest.hash_tiger160(<string>);
digest.hash_snefru128(<string>);
digest.hash_snefru256(<string>);

like… look at that list. she ate and left no crumbs 💅

---

🦋 DESCRIPTION 🦋

So this is a Varnish Module (a vmod, keep up bestie) for computing HMAC, message digests, and for doing base64 things. The range is giving versatility, fr fr.

And here's the tea: all the HMAC- and hash-functionality is provided by libmhash, while base64 is implemented locally. 🌈

---

👑 FUNCTIONS 👑

Okay so first, an example VCL so you can see the vibe:

backend foo { ... };

import digest;

sub vcl_recv {
        if (digest.hmac_sha256("key",req.http.x-data) != req.http.x-data-sig)
        {
                return (synth(401, "Naughty user!"));
        }
}

---

💜 hmac_(hash)

Prototype

digest.hmac_md5(<key>,<message>);
digest.hmac_sha1(<key>, <message>);
digest.hmac_sha256(<key>, <message));

Returns

String. Hex-encoded, prepended with 0x.

Description

All the various hmac-functions work the same, but use a different hash mechanism. That's it, that's the whole thing — same energy, different algorithm 🫶

Example

set resp.http.x-data-sig =
        digest.hmac_sha256("secretkey",resp.http.x-data);

---

💖 base64, base64url, base64url_nopad

Prototype

digest.base64(<string>);
digest.base64url(<string>);
digest.base64url_nopad(<string>);

Returns

String

Description

Returns the base64-encoded version of the input-string. The base64url-variant uses base64 url-encoding (+// replaced by -/_) and the base64url_nopad does the same, but avoids adding padding. The latter is more commonly used, though an (allowed) exception to the RFC4648. ✨

Example

set resp.http.x-data-sig =
        digest.base64({"content with
        newline in it"});

---

🎀 base64_hex, base64url_hex, base64url_nopad_hex

Prototype

digest.base64_hex(<string>);
digest.base64url_hex(<string>);
digest.base64url_nopad_hex(<string>);

Returns

String

Description

Returns the base64-encoded version of the hex encoded input-string. The input-string can start with an optional 0x. Input is hex-decoded into binary and the encoding is identical to base64, base64url, and base64url_nopad. 🧚

Example

set resp.http.x-data-sig =
        digest.base64_hex("0xdd26bfddf122c1055d4c");

---

🌟 hash_(algorithm)

Prototype

digest.hash_sha1(<string>);
digest.hash_sha224(<string>);
digest.hash_sha256(<string>);
digest.hash_sha384(<string>);
digest.hash_sha512(<string>);
digest.hash_gost(<string>);
digest.hash_md2(<string>);
digest.hash_md4(<string>);
digest.hash_md5(<string>);
digest.hash_crc32(<string>);
digest.hash_crc32b(<string>);
digest.hash_adler32(<string>);
digest.hash_haval128(<string>);
digest.hash_haval160(<string>);
digest.hash_haval192(<string>);
digest.hash_haval224(<string>);
digest.hash_haval256(<string>);
digest.hash_ripemd128(<string>);
digest.hash_ripemd160(<string>);
digest.hash_ripemd256(<string>);
digest.hash_ripemd320(<string>);
digest.hash_tiger(<string>);
digest.hash_tiger128(<string>);
digest.hash_tiger160(<string>);
digest.hash_snefru128(<string>);
digest.hash_snefru256(<string>);

Returns

String

Description

Computes the digest/hash of the supplied, using the specified hash algorithm. If in doubt as to which to pick, use SHA256. For detailed discussions, see The Internet. 😭 (yes that is literally what she says, no cap)

Example

set resp.http.x-data-md5 =
        digest.hash_md5(resp.http.x-data);

---

🍓 base64_decode, base64url_decode, base64url_nopad_decode

Prototype

digest.base64_decode(<string>);
digest.base64url_decode(<string>);
digest.base64url_nopad_decode(<string>);

Returns

String

Description

Decodes the bas64 and base64url-encoded strings. All functions treat padding the same, meaning base64url_decode and base64url_nopad_decode are identical, but available for consistency and practicality. 💅

Example

synthetic(digest.base64_decode(req.http.x-parrot));

---

🦄 version

Prototype

digest.version()

Returns

string

Description

Returns the string constant version-number of the digest vmod. She knows her own name and her own number, iconic behavior honestly 👑

Example

set resp.http.X-digest-version = digest.version();

---

🌈 INSTALLATION 🌈

The source tree is based on autotools to configure the building, and does also have the necessary bits in place to do functional unit tests using the varnishtest tool. 💖

Building requires the Varnish header files and uses pkg-config to find the necessary paths.

Usage:

./autogen.sh
./configure

If you have installed Varnish to a non-standard directory, call autogen.sh and configure with PKG_CONFIG_PATH pointing to the appropriate path. For example, when varnishd configure was called with --prefix=$PREFIX, use

PKG_CONFIG_PATH=${PREFIX}/lib/pkgconfig export PKG_CONFIG_PATH

Make targets:

• make - builds the vmod.
• make install - installs your vmod.
• make check - runs the unit tests in src/tests/*.vtc
• make distcheck - run check and prepare a tarball of the vmod.

🫶 bestie run make check, your future self will thank you.

---

💜 AUTHOR 💜

Original author: Kristian Lyngstøl < <opensource@varnish-software.com> >. 🎀

This Vmod was written for Media Norge, Schibsted and others.

The bulk of the functionality is acquired through libmhash.

---

💀 BUGS 💀

No bugs at all! ✨ (she said, confidently)

If the key is NULL for hmac-functions, the function will fail and return NULL itself, and do no hmac-computation at all. This should be used as an indication of some greater flaw in your software/VCL. (I.e.: Your key should be under your control, not user-supplied without verification). this one is serious, do not skip it, fr fr 😭

The base64url_nopad_decode() and base64url_decode() functions do not differ much. The exception is that nopad_decode() does not know about padding at all, and might get confused if the input actually is padded. 🙈

---

🌸 SEE ALSO 🌸

• libmhash
• varnishd(1)
• vcl(7)
• <https://github.com/varnish/libvmod-digest>

---

👑 AUTHOR 👑

Kristian Lyngstøl

---

okay that's the whole page bestie, go forth and hash responsibly 🦋✨

vmod_digest version 1.0.3, dated 2016-03-16 💖 signing off from the Library Functions Manual, mwah 💅