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

Available inall subroutines.

Returns the HMAC-SHA512 of message using key, as a lowercase hexadecimal string with a 0x prefix.

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 a 130-character string: a 0x prefix followed by 128 lowercase hexadecimal characters representing the 512-bit (64-byte) HMAC.

Example output: 0x5b6a26f290fb28d52d9f87304f4c46df2263ec9d01987444956f960303b9a6b23ed425a47b637a99609ff9da1fae100fcab3cc279b98fad0ad7409e69e74253b

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

Examples

Basic usage

declare local var.hmac STRING;
set var.hmac = digest.hmac_sha512("secret-key", "hello world");
# Result: 0x5b6a26f290fb28d52d9f87304f4c46df2263ec9d01987444956f960303b9a6b23ed425a47b637a99609ff9da1fae100fcab3cc279b98fad0ad7409e69e74253b

To verify this output using OpenSSL:

$ echo -n "hello world" | openssl dgst -sha512 -hmac "secret-key"
SHA2-512(stdin)= 5b6a26f290fb28d52d9f87304f4c46df2263ec9d01987444956f960303b9a6b23ed425a47b637a99609ff9da1fae100fcab3cc279b98fad0ad7409e69e74253b

RFC 4231 test vector

declare local var.hmac STRING;
set var.hmac = digest.hmac_sha512("key", "The quick brown fox jumps over the lazy dog");
# Result: 0xb42af09057bac1e2d41708e48a902e09b5ff7f12ab428a4fe86653c73dd248fb82f948a549f7b791a5b41915ee4d1ec3935357e4e2317250d0372afa2ebeeb3a

High-security message authentication

HMAC-SHA512 provides a larger security margin than HMAC-SHA256 and is suitable for applications requiring long-term security:

sub vcl_recv {
    declare local var.signature STRING;
    declare local var.secret STRING;

    set var.secret = table.lookup(high_security_keys, "critical-api");
    if (var.secret == "") {
        error 500 "Security key not configured";
    }

    set var.signature = digest.hmac_sha512(var.secret, req.body);
    set req.http.X-Signature-512 = var.signature;
}

Deriving multiple keys from a master secret

The 512-bit output can be split to derive multiple keys:

sub vcl_recv {
    declare local var.derived STRING;
    declare local var.enc_key STRING;
    declare local var.mac_key STRING;

    # Generate 512 bits of keying material
    set var.derived = digest.hmac_sha512(table.lookup(secrets, "master"), "key-derivation|" + client.ip);

    # Split into two 256-bit keys (skip 0x prefix, each half is 64 hex chars)
    set var.enc_key = substr(var.derived, 2, 64);  # First 256 bits for encryption
    set var.mac_key = substr(var.derived, 66, 64); # Second 256 bits for MAC
}

When to use SHA-512 vs SHA-256

For most applications, HMAC-SHA256 provides sufficient security and has better performance than SHA-512 due to hardware acceleration.

Use HMAC-SHA512 when you need > 256 bit output.

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

Key requirements

For optimal security with HMAC-SHA512:

• Use keys of at least 64 bytes (512 bits) to match the hash output size.
• Store keys in edge dictionaries, not in VCL source code.
• Use cryptographically random keys generated with openssl rand -hex 64.

Related content

• digest.hmac_sha512_base64 - Returns Base64-encoded output instead of hex.
• digest.hmac_sha256 - HMAC with SHA-256 (256-bit output).
• digest.secure_is_equal - Constant-time string comparison.

Try it out

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