---
name: "vmod_digest"
section: "3"
platform: "linux"
package: "varnish-vmod-digest"
version: "6.4+20230816-3"
release: "Debian 13 (Trixie)"
platforms: ["linux"]
url: "https://new.carta.tech/vmod_digest"
---

# vmod\_digest(3)

Varnish Digest Module

## NAME

vmod\_digest - Varnish Digest Module

## 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>);
```

## DESCRIPTION

Varnish Module (vmod) for computing HMAC, message digests and working with base64.

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

## FUNCTIONS

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

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

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

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

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

## 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!

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.

## SEE ALSO

- •

  libmhash

- •

  [varnishd(1)](/varnishd/1.md)

- •

  [vcl(7)](/vcl/7.md)

- •

   \<https://github.com/varnish/libvmod-digest\>

## AUTHOR

Kristian Lyngstøl