Модуль Base64

Модуль Base64 предоставляет методы для:

• Encoding двоичной строки (содержащей символы, не из ASCII) в строку печатаемых символов ASCII.

• Декодирования такой закодированной строки.

Base64 часто используется в контекстах, где двоичные данные не разрешены или не поддерживаются:

• Изображения в файлах HTML или CSS, или в URL.

• Вложения электронной почты.

Строка, закодированная в Base64, примерно на одну треть больше исходной. См. статью Википедии для получения дополнительной информации.

Этот модуль предоставляет три пары методов кодирования/декодирования. Ваш выбор среди этих методов должен зависеть от:

• Какой набор символов будет использоваться для кодирования и декодирования.

• Используется ли «заполнение».

• Будут ли закодированные строки содержать новые строки.

Примечание: примеры на этой странице предполагают, что включающая программа выполнила:

require 'base64'

Encoding Наборы символов

Закодированная в Base64 строка состоит только из символов из набора из 64 символов:

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

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

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

• =, символ «заполнения».

• Либо:

  • %w[+ /]: совместимый с RFC-2045; не безопасен для URL.

  • %w[- _]: совместимый с RFC-4648; безопасен для URL.

Если вы работаете со строками, закодированными в Base64, которые будут получены из или помещены в URL, вы должны выбрать эту пару методов, совместимых с RFC-4648:

• Base64.urlsafe_encode64 и Base64.urlsafe_decode64.

В противном случае, вы можете выбрать любую пару в этом модуле, включая пару выше, или пары, совместимые с RFC-2045:

• Base64.encode64 и Base64.decode64.

• Base64.strict_encode64 и Base64.strict_decode64.

Заполнение

Кодирование Base64 изменяет тройку входных байтов на квартет выходных символов.

Заполнение в методах кодирования

Заполнение – расширение закодированной строки нулем, одним или двумя trailing = символами – выполняется методами Base64.encode64, Base64.strict_encode64 и, по умолчанию, Base64.urlsafe_encode64:

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

Когда выполняется заполнение, длина закодированной строки всегда равна 4n, где n – неотрицательное целое число:

• Входные байты длиной 3n генерируют незаполненные выходные символы длиной 4n:

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

• Входные байты длиной 3n+1 генерируют заполненные выходные символы длиной 4(n+1) с двумя символами заполнения в конце:

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

• Входные байты длиной 3n+2 генерируют заполненные выходные символы длиной 4(n+1) с одним символом заполнения в конце:

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

Когда заполнение подавлено, для положительного целого числа n:

• Входные байты длиной 3n генерируют незаполненные выходные символы длиной 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"
  

• Входные байты длиной 3n+1 генерируют незаполненные выходные символы длиной 4n+2 с двумя символами заполнения в конце:

  # 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"
  

• Входные байты длиной 3n+2 генерируют незаполненные выходные символы длиной 4n+3 с одним символом заполнения в конце:

  # 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"
  

Заполнение в методах декодирования

Все методы декодирования Base64 поддерживают (но не требуют) заполнение.

Метод Base64.decode64 не проверяет размер заполнения:

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

Метод Base64.strict_decode64 строго накладывает размер заполнения:

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

Метод Base64.urlsafe_decode64 допускает заполнение в str, которое, если присутствует, должно быть правильным: см. Заполнение, выше:

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

Новые строки

Закодированная строка, возвращаемая Base64.encode64 или Base64.urlsafe_encode64, содержит вставленный символ новой строки после каждой последовательности из 60 символов и, если она не пуста, в конце:

# 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]

Строка, подлежащая кодированию, сама может содержать новые строки, которые кодируются в Base64:

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