---
title: digest.base64_decode
summary: null
url: >-
  https://www.fastly.com/documentation/reference/vcl/functions/cryptographic/digest-base64-decode
---

```
STRING digest.base64_decode(STRING s)
```

**Available in:** all subroutines

Returns the original representation of the Base64-encoded string `s`
as produced by `digest.base64()`.

> **IMPORTANT:** 
> Although the input string may contain encoded binary data, the resulting output
> is treated as a string.
> As such, any _NUL_ characters in the string will appear as a truncated result.

Base64 encoding works by viewing a string as a sequence of bits, and grouping
those into six bits for each encoded character. The following example illustrates
the Base64-encoded string `YWJjZA==` in relation to its corresponding decoded bytes
`abcd`:

```
                                                              (optional padding)
Base64:    Y        W        J        j        Z        A        =        =
        ╭──┴───╮ ╭──┴───╮ ╭──┴───╮ ╭──┴───╮ ╭──┴───╮ ╭──┴───╮ ╭──┴───╮ ╭──┴───╮
        01 10 00 01 01 10 00 10 01 10 00 11 01 10 01 00 00 00 -- -- -- -- -- --
        ╰────┬────╯ ╰────┬────╯ ╰────┬────╯ ╰────┬────╯ ╰─┬─╯
Text:        a           b           c           d   (not used)
Bit:    0                                23 24                               47
```

## Padding

The binary in the above example is illustrated in groups of two bits to help
make it clearer to see where the six-bit and eight-bit boundaries are.
Their corresponding bit numbers (indicated by the "Bit:" line) show alignment
to 24-bit boundaries.

Padding is used to bring the Base64-encoded string up to the next 24-bit
boundary if necessary. In this case, two padding bytes are present,
bringing the length up to 28 bits. This alignment is not always necessary,
and so padding is optional.

The presence of padding causes decoding to terminate. Any subsequent data is
ignored. For example, the Base64-encoded string `YWJjZA=YWJ` decodes to
just `abcd` and stops at the `=` character.
This case should have two `=` characters to pad correctly, but since padding is
optional, the single padding character here does not cause an error.
The subsequent `YWJ` is ignored.

## Unused bits

In the above example illustrating `YWJjZA==`, the least significant four bits
of `A` are not used, and these are ignored when producing the decoded string.
These ignored bits could have different values. For this reason, multiple
Base64-encoded strings may decode to the same bytes out.

For example, `YWJjZB==` also decodes to the same bytes `abcd`, because the
most significant two bits of `B` are the same as the first two bits of `A`.
There is not a one-to-one correlation between a Base64-encoded string and its
decoded bytes unless the number of decoded bytes aligns to a 24-bit boundary.
This only happens when there are no unused bits in the encoded string.

For this reason we recommend against comparing Base64-encoded strings for
equality, and to compare decoded strings instead.

## Handling for invalid characters

The character `~` is not valid in any Base64 alphabet, and is used here
to represent any similarly invalid character. Invalid characters are
skipped entirely when decoding, and do not contribute to the bits for
the current byte being output. Decoding continues for subsequent data
as if the invalid character were not present.

```
Base64:    Y        W        J        ~        Y        W        J
        ╭──┴───╮ ╭──┴───╮ ╭──┴───╮ ╭──┴───╮ ╭──┴───╮ ╭──┴───╮ ╭──┴───╮
        01 10 00 01 01 10 00 10 01 -- -- -- 01 10 00 01 01 10 00 10 01 ...
        ╰────┬────╯ ╰────┬────╯ ╰─────────┬────────╯ ╰────┬────╯
Text:        a           b                X               X      (etc)
```

## Example

```vcl
declare local var.base64_decoded STRING;
set var.base64_decoded = digest.base64_decode("zprOsc67z47PgiDOv8+Bzq/Pg86xz4TOtQ==");
# var.base64_decoded is now "Καλώς ορίσατε"
```