Digest

Description

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

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

For example

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

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)

Arguments: None

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)

Arguments: None

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)

Arguments: None

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