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

Available inall subroutines.

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

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

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

Try it out

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