12.42 rfc.base64 - Base64 encoding/decoding

Module: rfc.base64 ¶

This module defines a few functions to encode/decode Base64 format, defined in RFC 4648 (https://www.ietf.org/rfc/rfc4648.txt). It also supports Base32 and Base16 formats defined in it as well.

The common naming convention is as follows.

encoding-encode, encoding-decode

Port-based encoder/decoder. It reads input from the current input port, and emits encoded/decoded output to the current output port.

encoding-encode-message

Takes the input as either a string or a u8vector, and returns the encoded result as a string. Note that BaseN encoding always results readable strings.

encoding-decode-string-to

Takes the encoded string, and returns the result in either a u8vector or a string, as specified by the target argument. Note that the decoded result is a byte sequence in general, so a string may be incomplete.

Base64

Function: base64-encode :key line-width digits url-safe omit-padding ¶

{rfc.base64} Reads byte stream from the current input port, encodes it in Base64 format and writes the result character stream to the current output port. The conversion ends when it reads EOF from the current input port.

Newline characters can be inserted to keep the maximum line width to the value given to the line-width keyword argument. The default value of line-width is 76, as specified in RFC2045. You can give #f or zero to line-width to suppress line splitting.

Base64 can have different mappings in the digit of 62 and 63; the “standard” encoding uses + and /, and the “url-safe” encoding uses - and _. You can specify which to use by either url-safe or digits.

If a true value is given to url-safe, the input bytes will be encoded with “url-safe” encoding. Otherwise, you can give a two-letter string to digits argument, in which case the first character is used for digit 62 and the second character is used for digit 63. The digits argument is added to support SRFI-207 (see srfi.207 - String-notated bytevectors).

If a true value is given to omit-padding, the trailing padding characters (#\=) are omitted. (See RFC4648 Section 3.2 (https://www.rfc-editor.org/rfc/rfc4648#section-3.2)). The default is not omitting padding characters.

Function: base64-encode-message message :key line-width digits url-safe omit-padding ¶

{rfc.base64} Encodes message, which must be either a string or a u8vector, with Base64 encoding and returns the result as a string. The meaning of keyword arguments are the same as base64-encode above.

(base64-encode-message "Hau'oli makahiki hou")
 ⇒ "SGF1J29saSBtYWthaGlraSBob3U="

For the portable code, you may want to use bytestring->base64 in srfi.207 (see srfi.207 - String-notated bytevectors).

Function: base64-decode :key digits url-safe strict ¶

{rfc.base64} Reads character stream from the current input port, decodes it from Base64 format and writes the result byte stream to the current output port. The conversion ends when it reads EOF or the termination character (=).

The characters which does not in legal Base64 encoded character set are silently ignored by default. If a true value is given to the strict keyword argument, however, non-whitespace out-of-set characters in the input raises an error.

The input can lack the trailing padding character by default. However, if strict argument is true, an error is thrown unless the input has a proper number of padding characters.

The digits and url-safe keyword arguments can be used to choose different mappings of digit 62 and 63. See base64-encode above for the details.

Function: base64-decode-string-to target string :key line-width digits url-safe omit-padding ¶

{rfc.base64} The target argument must be a class object <string> or <u8vector>. This procedure takes Base64-encoded input string, and returns the decoded result as an instance of target.

The meaning of keyword arguments are the same as base64-decode above.

(base64-decode-string-to <string> "SGF1J29saSBtYWthaGlraSBob3U=")
 ⇒ "Hau'oli makahiki hou"
(base64-decode-string-to <u8vector> "SGF1J29saSBtYWthaGlraSBob3U=")
 ⇒ #u8(72 97 117 39 111 108 105 32 109 97 107 97 104 105
    107 105 32 104 111 117)

Note that if you ask a string to be returned, the result may be an incomplete string.

(base64-decode-string-to <string> "8PHy8w==")
 ⇒ #**"\xf0;\xf1;\xf2;\xf3;"

For the portable code, you may want to use base64->bytestring in srfi.207 (see srfi.207 - String-notated bytevectors).

Base32

RFC4648 defines two completely different encodings as base-32; The standard Base32 uses A-Z for 0 to 25, and 2-7 for 26 to 31. The “base32hex” variant uses 0-9 for 0 to 9, and A-V for 10 to 31. Since RFC states the latter should not be referred to as base32, we provide separate procedures for those encodings.

Function: base32-encode :key omit-padding line-width ¶

Function: base32hex-encode :key omit-padding line-width ¶

{rfc.base64} The procedures are port-based; they read input from the current standard port, and emits the base32 or base32hex encoded result to the current output port.

The keyword arguments omit-padding and line-width are the same as base64-encode.

Function: base32-encode-message message :key omit-padding line-width ¶

Function: base32hex-encode-message message :key omit-padding line-width ¶

{rfc.base64} Base32 or Base32hex encode message, which should be a string or a u8vector, and returns the result in a string.

The keyword arguments omit-padding and line-width are the same as base64-encode.

(base32-encode-message "Hau'oli makahiki hou!")
 ⇒ "JBQXKJ3PNRUSA3LBNNQWQ2LLNEQGQ33VEE======"
(base32hex-encode-message "Hau'oli makahiki hou!")
 ⇒ "91GNA9RFDHKI0RB1DDGMGQBBD4G6GRRL44======"

Function: base32-decode :key strict ¶

Function: base32hex-decode :key strict ¶

{rfc.base64} Read Base32/Base32hex encoded string from the current input port, and emits the decoded result to the current output port.

If a true value is given to the strict argument, an error is thrown if non-whitespace illegal characters exist in the input, or the proper padding characters are missing. The default of strict is #f and illegal characters are just ignored.

Function: base32-decode-string-to target string :key strict ¶

Function: base32hex-decode-string-to target string :key strict ¶

{rfc.base64} Decode a Base32/Base32hex encoded string string, and returns the result as an instance of class target, which must be either <u8vector> or <string>.

The meaning of strict argument is the same as in base32-decode.

(base32-decode-string-to <string>
   "JBQXKJ3PNRUSA3LBNNQWQ2LLNEQGQ33VEE======")
 ⇒ "Hau'oli makahiki hou!"

Base16

Base16 is simply the hexadecimal encoding of input octets. RFC4648 defines to use uppercase letters A-F for digits 10 to 15. In practice, lowercase letters are also used for hexadecimal encoding, so we provide that option, too.

Function: base16-encode :key lowercase ¶

{rfc.base64} Read data from the current input port, and emits Base16 encoded result to the current output port.

By default, A-F are used for digit 10 to 15, as specified in RFC4648. If lowercase argument is given and true, a-f are used instead.

Note that no padding character is ever generated in Base16 encoding.

Function: base16-encode-message message :key lowercase ¶

{rfc.base64} Base16 encode message, which should be a string or a u8vector, and returns the result in a string. The lowercase argument is the same as base16-encode.

(base16-encode-message "Aloha")
 ⇒ "416C6F6861"
(base16-encode-message "Aloha" :lowercase #t)
 ⇒ "416c6f6861"

Function: base16-decode :key strict ¶

{rfc.base64} Read Base16 encoded string from the current input port, and emits the decoded result to the current output port.

By default, characters other than Base16 digits are ignored, and both upperase and lowercase alphabets are recognized. If strict argument is given and true, however, characters other than #[0-9A-F] throws an error.

Function: base16-decode-string-to target string :key strict ¶

{rfc.base64} Decode Base16-encoded string string, and returns the result as an instance of class target, which must be either <u8vector> or <string>.

The strict argument is the same as base16-decode.

(base16-decode-string-to <u8vector> "416c6f6861")
 ⇒ #u8(65 108 111 104 97)
(base16-decode-string-to <string> "416c6f6861")
 ⇒ "Aloha"

Deprecated API

The following API is deprecated. Avoid using them in new code.

Function: base64-encode-string string :key line-width digits url-safe ¶

Function: base64-encode-bytevector u8vector :key line-width digits url-safe ¶

{rfc.base64} Deprecated. Converts contents of string/u8vector to Base64 encoded format. For base64-encode-string, input string can be either complete or incomplete string; it is always interpreted as a byte sequence. The digits and url-safe arguments are the same as base64-encode.

Function: base64-decode-string string :key url-safe strict ¶

Function: base64-decode-bytevector u8vector :key url-safe strict ¶

{rfc.base64} Deprecated. Decodes a Base64 encoded string string and returns the result as a string or a u8vector, respectively. The conversion terminates at the end of string or the termination character (=).

The characters which are not in legal Base64 encoded character set are silently ignored by default. If a true value is given to the strict keyword argument, however, non-whitespace out-of-set characters in the input raises an error.

The digits and url-safe arguments are the same as base64-encode.