Module: Base64

Module Base64 provides methods for:

• Encoding a binary string (containing non-ASCII characters) as a string of printable ASCII characters.

• Decoding such an encoded string.

Base64 is commonly used in contexts where binary data is not allowed or supported:

• Images in HTML or CSS files, or in URLs.

• Email attachments.

A Base64-encoded string is about one-third larger that its source. See the Wikipedia article for more information.

This module provides three pairs of encode/decode methods. Your choices among these methods should depend on:

• Which character set is to be used for encoding and decoding.

• Whether “padding” is to be used.

• Whether encoded strings are to contain newlines.

Note: Examples on this page assume that the including program has executed:

require 'base64'

Encoding Character Sets

A Base64-encoded string consists only of characters from a 64-character set:

• ('A'..'Z').

• ('a'..'z').

• ('0'..'9').

• =, the ‘padding’ character.

• Either:

  • %w[+ /]: RFC-2045-compliant; not safe for URLs.

  • %w[- _]: RFC-4648-compliant; safe for URLs.

If you are working with Base64-encoded strings that will come from or be put into URLs, you should choose this encoder-decoder pair of RFC-4648-compliant methods:

• .urlsafe_encode64 and .urlsafe_decode64.

Otherwise, you may choose any of the pairs in this module, including the pair above, or the RFC-2045-compliant pairs:

• .encode64 and .decode64.

• .strict_encode64 and .strict_decode64.

Padding

Base64-encoding changes a triplet of input bytes into a quartet of output characters.

Padding in Encode Methods

Padding – extending an encoded string with zero, one, or two trailing = characters – is performed by methods .encode64, .strict_encode64, and, by default, .urlsafe_encode64:

Base64.encode64('s')                         # => "cw==\n"
Base64.strict_encode64('s')                  # => "cw=="
Base64.urlsafe_encode64('s')                 # => "cw=="
Base64.urlsafe_encode64('s', padding: false) # => "cw"

When padding is performed, the encoded string is always of length 4n, where n is a non-negative integer:

• Input bytes of length 3n generate unpadded output characters of length 4n:

  # n = 1:  3 bytes => 4 characters.
  Base64.strict_encode64('123')      # => "MDEy"
  # n = 2:  6 bytes => 8 characters.
  Base64.strict_encode64('123456')   # => "MDEyMzQ1"

• Input bytes of length 3n+1 generate padded output characters of length 4(n+1), with two padding characters at the end:

  # n = 1:  4 bytes => 8 characters.
  Base64.strict_encode64('1234')     # => "MDEyMw=="
  # n = 2:  7 bytes => 12 characters.
  Base64.strict_encode64('1234567')  # => "MDEyMzQ1Ng=="

• Input bytes of length 3n+2 generate padded output characters of length 4(n+1), with one padding character at the end:

  # n = 1:  5 bytes => 8 characters.
  Base64.strict_encode64('12345')    # => "MDEyMzQ="
  # n = 2:  8 bytes => 12 characters.
  Base64.strict_encode64('12345678') # => "MDEyMzQ1Njc="

When padding is suppressed, for a positive integer n:

• Input bytes of length 3n generate unpadded output characters of length 4n:

  # n = 1:  3 bytes => 4 characters.
  Base64.urlsafe_encode64('123', padding: false)      # => "MDEy"
  # n = 2:  6 bytes => 8 characters.
  Base64.urlsafe_encode64('123456', padding: false)   # => "MDEyMzQ1"

• Input bytes of length 3n+1 generate unpadded output characters of length 4n+2, with two padding characters at the end:

  # n = 1:  4 bytes => 6 characters.
  Base64.urlsafe_encode64('1234', padding: false)     # => "MDEyMw"
  # n = 2:  7 bytes => 10 characters.
  Base64.urlsafe_encode64('1234567', padding: false)  # => "MDEyMzQ1Ng"

• Input bytes of length 3n+2 generate unpadded output characters of length 4n+3, with one padding character at the end:

  # n = 1:  5 bytes => 7 characters.
  Base64.urlsafe_encode64('12345', padding: false)    # => "MDEyMzQ"
  # m = 2:  8 bytes => 11 characters.
  Base64.urlsafe_encode64('12345678', padding: false) # => "MDEyMzQ1Njc"

Padding in Decode Methods

All of the Base64 decode methods support (but do not require) padding.

Method .decode64 does not check the size of the padding:

Base64.decode64("MDEyMzQ1Njc") # => "01234567"
Base64.decode64("MDEyMzQ1Njc=") # => "01234567"
Base64.decode64("MDEyMzQ1Njc==") # => "01234567"

Method .strict_decode64 strictly enforces padding size:

Base64.strict_decode64("MDEyMzQ1Njc")   # Raises ArgumentError
Base64.strict_decode64("MDEyMzQ1Njc=")  # => "01234567"
Base64.strict_decode64("MDEyMzQ1Njc==") # Raises ArgumentError

Method .urlsafe_decode64 allows padding in str, which if present, must be correct: see [Padding](Base64.html#module-Base64-label-Padding), above:

Base64.urlsafe_decode64("MDEyMzQ1Njc") # => "01234567"
Base64.urlsafe_decode64("MDEyMzQ1Njc=") # => "01234567"
Base64.urlsafe_decode64("MDEyMzQ1Njc==") # Raises ArgumentError.

Newlines

An encoded string returned by .encode64 or .urlsafe_encode64 has an embedded newline character after each 60-character sequence, and, if non-empty, at the end:

# No newline if empty.
encoded = Base64.encode64("\x00" *  0)
encoded.index("\n") # => nil

# Newline at end of short output.
encoded = Base64.encode64("\x00" *  1)
encoded.size        # => 4
encoded.index("\n") # => 4

# Newline at end of longer output.
encoded = Base64.encode64("\x00" * 45)
encoded.size        # => 60
encoded.index("\n") # => 60

# Newlines embedded and at end of still longer output.
encoded = Base64.encode64("\x00" * 46)
encoded.size                          # => 65
encoded.rindex("\n")                  # => 65
encoded.split("\n").map {|s| s.size } # => [60, 4]

The string to be encoded may itself contain newlines, which are encoded as Base64:

  #   Base64.encode64("\n\n\n") # => "CgoK\n"
s = "This is line 1\nThis is line 2\n"
Base64.encode64(s) # => "VGhpcyBpcyBsaW5lIDEKVGhpcyBpcyBsaW5lIDIK\n"