Fred Drake | 295da24 | 1998-08-10 19:42:37 +0000 | [diff] [blame] | 1 | \section{\module{base64} --- |
Barry Warsaw | ad9aaee | 2004-01-04 01:14:01 +0000 | [diff] [blame] | 2 | RFC 3548: Base16, Base32, Base64 Data Encodings} |
Fred Drake | b91e934 | 1998-07-23 17:59:49 +0000 | [diff] [blame] | 3 | |
Fred Drake | 180b68b | 1999-02-22 13:45:09 +0000 | [diff] [blame] | 4 | \declaremodule{standard}{base64} |
Barry Warsaw | ad9aaee | 2004-01-04 01:14:01 +0000 | [diff] [blame] | 5 | \modulesynopsis{RFC 3548: Base16, Base32, Base64 Data Encodings} |
Fred Drake | 180b68b | 1999-02-22 13:45:09 +0000 | [diff] [blame] | 6 | |
Fred Drake | b91e934 | 1998-07-23 17:59:49 +0000 | [diff] [blame] | 7 | |
Fred Drake | 674e0fd | 1998-04-02 16:24:29 +0000 | [diff] [blame] | 8 | \indexii{base64}{encoding} |
| 9 | \index{MIME!base64 encoding} |
Guido van Rossum | e76b7a8 | 1997-04-27 21:25:52 +0000 | [diff] [blame] | 10 | |
Barry Warsaw | ad9aaee | 2004-01-04 01:14:01 +0000 | [diff] [blame] | 11 | This module provides data encoding and decoding as specified in |
| 12 | \rfc{3548}. This standard defines the Base16, Base32, and Base64 |
| 13 | algorithms for encoding and decoding arbitrary binary strings into |
| 14 | text strings that can be safely sent by email, used as parts of URLs, |
Johannes Gijsbers | f4a70f3 | 2004-12-12 16:52:40 +0000 | [diff] [blame] | 15 | or included as part of an HTTP POST request. The encoding algorithm is |
Barry Warsaw | ad9aaee | 2004-01-04 01:14:01 +0000 | [diff] [blame] | 16 | not the same as the \program{uuencode} program. |
Guido van Rossum | e76b7a8 | 1997-04-27 21:25:52 +0000 | [diff] [blame] | 17 | |
Barry Warsaw | ad9aaee | 2004-01-04 01:14:01 +0000 | [diff] [blame] | 18 | There are two interfaces provided by this module. The modern |
| 19 | interface supports encoding and decoding string objects using all |
| 20 | three alphabets. The legacy interface provides for encoding and |
| 21 | decoding to and from file-like objects as well as strings, but only |
| 22 | using the Base64 standard alphabet. |
| 23 | |
| 24 | The modern interface provides: |
| 25 | |
| 26 | \begin{funcdesc}{b64encode}{s\optional{, altchars}} |
| 27 | Encode a string use Base64. |
| 28 | |
| 29 | \var{s} is the string to encode. Optional \var{altchars} must be a |
| 30 | string of at least length 2 (additional characters are ignored) which |
| 31 | specifies an alternative alphabet for the \code{+} and \code{/} |
| 32 | characters. This allows an application to e.g. generate URL or |
| 33 | filesystem safe Base64 strings. The default is \code{None}, for which |
| 34 | the standard Base64 alphabet is used. |
| 35 | |
| 36 | The encoded string is returned. |
| 37 | \end{funcdesc} |
| 38 | |
| 39 | \begin{funcdesc}{b64decode}{s\optional{, altchars}} |
| 40 | Decode a Base64 encoded string. |
| 41 | |
| 42 | \var{s} is the string to decode. Optional \var{altchars} must be a |
| 43 | string of at least length 2 (additional characters are ignored) which |
| 44 | specifies the alternative alphabet used instead of the \code{+} and |
| 45 | \code{/} characters. |
| 46 | |
| 47 | The decoded string is returned. A \exception{TypeError} is raised if |
| 48 | \var{s} were incorrectly padded or if there are non-alphabet |
| 49 | characters present in the string. |
| 50 | \end{funcdesc} |
| 51 | |
| 52 | \begin{funcdesc}{standard_b64encode}{s} |
| 53 | Encode string \var{s} using the standard Base64 alphabet. |
| 54 | \end{funcdesc} |
| 55 | |
| 56 | \begin{funcdesc}{standard_b64decode}{s} |
| 57 | Decode string \var{s} using the standard Base64 alphabet. |
| 58 | \end{funcdesc} |
| 59 | |
| 60 | \begin{funcdesc}{urlsafe_b64encode}{s} |
| 61 | Encode string \var{s} using a URL-safe alphabet, which substitutes |
| 62 | \code{-} instead of \code{+} and \code{_} instead of \code{/} in the |
| 63 | standard Base64 alphabet. |
| 64 | \end{funcdesc} |
| 65 | |
| 66 | \begin{funcdesc}{urlsafe_b64decode}{s} |
| 67 | Decode string \var{s} using a URL-safe alphabet, which substitutes |
| 68 | \code{-} instead of \code{+} and \code{_} instead of \code{/} in the |
| 69 | standard Base64 alphabet. |
| 70 | \end{funcdesc} |
| 71 | |
| 72 | \begin{funcdesc}{b32encode}{s} |
| 73 | Encode a string using Base32. \var{s} is the string to encode. The |
| 74 | encoded string is returned. |
| 75 | \end{funcdesc} |
| 76 | |
| 77 | \begin{funcdesc}{b32decode}{s\optional{, casefold\optional{, map01}}} |
| 78 | Decode a Base32 encoded string. |
| 79 | |
| 80 | \var{s} is the string to decode. Optional \var{casefold} is a flag |
| 81 | specifying whether a lowercase alphabet is acceptable as input. For |
| 82 | security purposes, the default is \code{False}. |
| 83 | |
| 84 | \rfc{3548} allows for optional mapping of the digit 0 (zero) to the |
| 85 | letter O (oh), and for optional mapping of the digit 1 (one) to either |
| 86 | the letter I (eye) or letter L (el). The optional argument |
| 87 | \var{map01} when not \code{None}, specifies which letter the digit 1 should |
| 88 | be mapped to (when map01 is not \var{None}, the digit 0 is always |
| 89 | mapped to the letter O). For security purposes the default is |
| 90 | \code{None}, so that 0 and 1 are not allowed in the input. |
| 91 | |
| 92 | The decoded string is returned. A \exception{TypeError} is raised if |
| 93 | \var{s} were incorrectly padded or if there are non-alphabet characters |
| 94 | present in the string. |
| 95 | \end{funcdesc} |
| 96 | |
| 97 | \begin{funcdesc}{b16encode}{s} |
| 98 | Encode a string using Base16. |
| 99 | |
| 100 | \var{s} is the string to encode. The encoded string is returned. |
| 101 | \end{funcdesc} |
| 102 | |
| 103 | \begin{funcdesc}{b16decode}{s\optional{, casefold}} |
| 104 | Decode a Base16 encoded string. |
| 105 | |
| 106 | \var{s} is the string to decode. Optional \var{casefold} is a flag |
| 107 | specifying whether a lowercase alphabet is acceptable as input. For |
| 108 | security purposes, the default is \code{False}. |
| 109 | |
| 110 | The decoded string is returned. A \exception{TypeError} is raised if |
| 111 | \var{s} were incorrectly padded or if there are non-alphabet |
| 112 | characters present in the string. |
| 113 | \end{funcdesc} |
| 114 | |
| 115 | The legacy interface: |
Fred Drake | 798654f | 1997-11-30 05:53:22 +0000 | [diff] [blame] | 116 | |
Fred Drake | 7994843 | 1998-01-07 03:47:10 +0000 | [diff] [blame] | 117 | \begin{funcdesc}{decode}{input, output} |
Guido van Rossum | e76b7a8 | 1997-04-27 21:25:52 +0000 | [diff] [blame] | 118 | Decode the contents of the \var{input} file and write the resulting |
| 119 | binary data to the \var{output} file. |
| 120 | \var{input} and \var{output} must either be file objects or objects that |
| 121 | mimic the file object interface. \var{input} will be read until |
| 122 | \code{\var{input}.read()} returns an empty string. |
| 123 | \end{funcdesc} |
| 124 | |
| 125 | \begin{funcdesc}{decodestring}{s} |
| 126 | Decode the string \var{s}, which must contain one or more lines of |
Fred Drake | 674e0fd | 1998-04-02 16:24:29 +0000 | [diff] [blame] | 127 | base64 encoded data, and return a string containing the resulting |
Guido van Rossum | e76b7a8 | 1997-04-27 21:25:52 +0000 | [diff] [blame] | 128 | binary data. |
| 129 | \end{funcdesc} |
| 130 | |
Fred Drake | 7994843 | 1998-01-07 03:47:10 +0000 | [diff] [blame] | 131 | \begin{funcdesc}{encode}{input, output} |
Guido van Rossum | e76b7a8 | 1997-04-27 21:25:52 +0000 | [diff] [blame] | 132 | Encode the contents of the \var{input} file and write the resulting |
Fred Drake | 674e0fd | 1998-04-02 16:24:29 +0000 | [diff] [blame] | 133 | base64 encoded data to the \var{output} file. |
Guido van Rossum | e76b7a8 | 1997-04-27 21:25:52 +0000 | [diff] [blame] | 134 | \var{input} and \var{output} must either be file objects or objects that |
| 135 | mimic the file object interface. \var{input} will be read until |
Raymond Hettinger | cadc9fb | 2002-05-16 04:28:44 +0000 | [diff] [blame] | 136 | \code{\var{input}.read()} returns an empty string. \function{encode()} |
| 137 | returns the encoded data plus a trailing newline character |
| 138 | (\code{'\e n'}). |
Guido van Rossum | e76b7a8 | 1997-04-27 21:25:52 +0000 | [diff] [blame] | 139 | \end{funcdesc} |
| 140 | |
| 141 | \begin{funcdesc}{encodestring}{s} |
| 142 | Encode the string \var{s}, which can contain arbitrary binary data, |
| 143 | and return a string containing one or more lines of |
Raymond Hettinger | cadc9fb | 2002-05-16 04:28:44 +0000 | [diff] [blame] | 144 | base64-encoded data. \function{encodestring()} returns a |
| 145 | string containing one or more lines of base64-encoded data |
| 146 | always including an extra trailing newline (\code{'\e n'}). |
Guido van Rossum | e76b7a8 | 1997-04-27 21:25:52 +0000 | [diff] [blame] | 147 | \end{funcdesc} |
Fred Drake | ae35aa8 | 1999-04-23 15:52:18 +0000 | [diff] [blame] | 148 | |
Fred Drake | ae35aa8 | 1999-04-23 15:52:18 +0000 | [diff] [blame] | 149 | \begin{seealso} |
Fred Drake | c37b65e | 2001-11-28 07:26:15 +0000 | [diff] [blame] | 150 | \seemodule{binascii}{Support module containing \ASCII-to-binary |
Fred Drake | ba0a989 | 2000-10-18 17:43:06 +0000 | [diff] [blame] | 151 | and binary-to-\ASCII{} conversions.} |
Fred Drake | e20bd19 | 2001-04-12 16:47:17 +0000 | [diff] [blame] | 152 | \seerfc{1521}{MIME (Multipurpose Internet Mail Extensions) Part One: |
| 153 | Mechanisms for Specifying and Describing the Format of |
| 154 | Internet Message Bodies}{Section 5.2, ``Base64 |
| 155 | Content-Transfer-Encoding,'' provides the definition of the |
| 156 | base64 encoding.} |
Fred Drake | ae35aa8 | 1999-04-23 15:52:18 +0000 | [diff] [blame] | 157 | \end{seealso} |