digest

Description

This vmod is distributed as part of the varnish-plus-vmods-extra package.

The digest vmod allows for computing HMAC, message digests and working with base64.

All HMAC- and hash-functionality is provided by libmhash, while base64 is implemented locally.

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).

The base64url_nopad_decode() and base64url_decode() functions differ in padding: base64url_decode() accepts input with or without padding, while base64url_nopad_decode() rejects padded input.

hmac_(hash)

All the various hmac-functions work the same, but use a different hash mechanism. Hex-encoded prepended with 0x.

For example

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

base64, base64url, base64url_nopad

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.

For example

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

base64_hex, base64url_hex, base64url_nopad_hex

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.

For example

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

hash_(algorithm)

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.

For example

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

base64_decode, base64url_decode, base64url_nopad_decode

Decodes the base64 and base64url-encoded strings. base64_decode() and base64url_decode() accept the input with or without padding, while base64url_nopad_decode() rejects padding: it does not decode the padded output of base64url(), only that of base64url_nopad().

By default, LF and CRLF line breaks in the input are ignored, wherever they occur, so that line-wrapped input or input carrying a trailing newline decodes. Every other character outside the alphabet makes the decode fail and return an empty string, spaces, tabs and a stray CR included. Setting the strict argument to true rejects line breaks as well, which is the RFC 4648 section 3.3 behavior of accepting nothing outside the alphabet.

For example

synthetic(digest.base64_decode(req.http.x-parrot));
synthetic(digest.base64_decode(req.http.x-parrot, strict = true));

Example

Example VCL

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!"));
  }
}

API

hmac_sha256

STRING hmac_sha256(STRING, STRING)

Arguments: None

Type: Function

Returns: String

hmac_sha1

STRING hmac_sha1(STRING, STRING)

Arguments: None

Type: Function

Returns: String

hmac_md5

STRING hmac_md5(STRING, STRING)

Arguments: None

Type: Function

Returns: String

base64

STRING base64(STRING)

Arguments: None

Type: Function

Returns: String

base64_hex

STRING base64_hex(STRING)

Arguments: None

Type: Function

Returns: String

base64_decode

STRING base64_decode(STRING, BOOL strict = false)

Arguments:

strict accepts type BOOL with a default value of false; when true, line breaks in the input are rejected instead of ignored optional

Type: Function

Returns: String

base64url

STRING base64url(STRING)

Arguments: None

Type: Function

Returns: String

base64url_hex

STRING base64url_hex(STRING)

Arguments: None

Type: Function

Returns: String

base64url_decode

STRING base64url_decode(STRING, BOOL strict = false)

Arguments:

strict accepts type BOOL with a default value of false; when true, line breaks in the input are rejected instead of ignored optional

Type: Function

Returns: String

base64url_nopad

STRING base64url_nopad(STRING)

Arguments: None

Type: Function

Returns: String

base64url_nopad_hex

STRING base64url_nopad_hex(STRING)

Arguments: None

Type: Function

Returns: String

base64url_nopad_decode

STRING base64url_nopad_decode(STRING, BOOL strict = false)

Arguments:

strict accepts type BOOL with a default value of false; when true, line breaks in the input are rejected instead of ignored optional

Type: Function

Returns: String

hash_sha1

STRING hash_sha1(STRING)

Arguments: None

Type: Function

Returns: String

hash_sha224

STRING hash_sha224(STRING)

Arguments: None

Type: Function

Returns: String

hash_sha256

STRING hash_sha256(STRING)

Arguments: None

Type: Function

Returns: String

hash_sha384

STRING hash_sha384(STRING)

Arguments: None

Type: Function

Returns: String

hash_sha512

STRING hash_sha512(STRING)

Arguments: None

Type: Function

Returns: String

hash_md5

STRING hash_md5(STRING)

Arguments: None

Type: Function

Returns: String

hash_ripemd160

STRING hash_ripemd160(STRING)

Only available on platforms with openssl newer than 3.0.7 or libmash

Arguments: None

Type: Function

Returns: String