1. Home
2. Reference documentation
3. VCL reference
4. Functions
5. Cryptographic

Available inall subroutines.

Returns the HMAC-SHA512 of message using key, encoded as a Base64 string.

Parameters

The key is used directly as the HMAC key. For keys longer than 128 bytes (the SHA-512 block size), the key is first hashed with SHA-512 before use, as specified in RFC 2104.

Return value

Returns an 88-character Base64-encoded string representing the 512-bit (64-byte) HMAC, using standard Base64 encoding (RFC 4648 Section 4) with padding.

Example output: W2om8pD7KNUtn4cwT0xG3yJj7J0BmHRElW+WAwO5prI+1CWke2N6mWCf+dofrhAPyrPMJ5uY+tCtdAnmnnQlOw==

If key is empty or not set, the function returns an empty string (not set).

Base64 encoding

This function uses standard Base64 encoding as defined in RFC 4648 Section 4:

Examples

Basic usage

declare local var.hmac STRING;
set var.hmac = digest.hmac_sha512_base64("secret-key", "hello world");
# Result: W2om8pD7KNUtn4cwT0xG3yJj7J0BmHRElW+WAwO5prI+1CWke2N6mWCf+dofrhAPyrPMJ5uY+tCtdAnmnnQlOw==

To verify this output using OpenSSL:

$ echo -n "hello world" | openssl dgst -sha512 -hmac "secret-key" -binary | openssl base64
W2om8pD7KNUtn4cwT0xG3yJj7J0BmHRElW+WAwO5prI+1CWke2N6mWCf+dofrhAPyrPMJ5uY+tCtdAnmnnQlOw==

RFC 4231 test vector

declare local var.hmac STRING;
set var.hmac = digest.hmac_sha512_base64("key", "The quick brown fox jumps over the lazy dog");
# Result: tCrwkFe6weLUFwjkipAuCbX/fxKrQopP6GZTxz3SSPuC+UilSfe3kaW0GRXuTR7Dk1NX5OIxclDQNyr6Lr7rOg==

API authentication with Base64 signature

sub vcl_recv {
    declare local var.string_to_sign STRING;
    declare local var.signature STRING;
    declare local var.api_secret STRING;

    set var.api_secret = table.lookup(api_keys, "secure-service");
    if (var.api_secret == "") {
        error 500 "API secret not configured";
    }

    set var.string_to_sign = req.http.Date + "\n"
        + req.method + "\n"
        + req.url.path;

    set var.signature = digest.hmac_sha512_base64(var.api_secret, var.string_to_sign);
    set req.http.X-Auth-Signature = var.signature;
}

Comparison with hex output

Base64 encoding is more compact than hex (88 characters vs 130).

Security considerations

Constant-time comparison

When comparing HMAC values for authentication, always use digest.secure_is_equal to prevent timing attacks. String comparison with == leaks information about which bytes matched, potentially allowing an attacker to forge valid authentication tags:

if (!digest.secure_is_equal(var.expected, var.actual)) {
    error 401 "Invalid signature";
}

Validate keys before use

Always verify that key lookups succeed before computing an HMAC:

declare local var.key STRING;
set var.key = table.lookup(secrets, "api-key");
if (var.key == "") {
    error 500 "API key not found";
}

Related content

• digest.hmac_sha512 - Returns hex-encoded output with 0x prefix.
• digest.hmac_sha256_base64 - HMAC-SHA256 with Base64 output.
• digest.secure_is_equal - Constant-time string comparison.

Try it out

digest.hmac_sha512_base64 is used in the following code examples. Examples apply VCL to real-world use cases and can be deployed as they are, or adapted for your own service. See the full list of code examples for more inspiration.

Click RUN on a sample below to provision a Fastly service, execute the code on Fastly, and see how the function behaves.