---
title: digest.hmac_sha512
summary: null
url: >-
  https://www.fastly.com/documentation/reference/vcl/functions/cryptographic/digest-hmac-sha512
---

```
STRING digest.hmac_sha512(STRING key, STRING input)
```

**Available in:** all subroutines

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

## Parameters

| Parameter | Type   | Description                         |
| --------- | ------ | ----------------------------------- |
| `key`     | STRING | The secret key for HMAC computation |
| `message` | STRING | The message to authenticate         |

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

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

To verify this output using OpenSSL:

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

### RFC 4231 test vector

```vcl
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:

```vcl
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:

```vcl
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:

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