Debian Codegraph @

Doc/library/base64.rst

raw
1 :mod:`!base64` --- Base16, Base32, Base64, Base85 Data Encodings
2 ================================================================
3
4 .. module:: base64
5 :synopsis: RFC 4648: Base16, Base32, Base64 Data Encodings;
6 Base85 and Ascii85
7
8 **Source code:** :source:`Lib/base64.py`
9
10 .. index::
11 pair: base64; encoding
12 single: MIME; base64 encoding
13
14 --------------
15
16 This module provides functions for encoding binary data to printable
17 ASCII characters and decoding such encodings back to binary data.
18 This includes the :ref:`encodings specified in <base64-rfc-4648>`
19 :rfc:`4648` (Base64, Base32 and Base16), the :ref:`Base85 encoding
20 <base64-base-85>` specified in `PDF 2.0
21 <https://pdfa.org/resource/iso-32000-2/>`_, and non-standard variants
22 of Base85 used elsewhere.
23
24 There are two interfaces provided by this module. The modern interface
25 supports encoding :term:`bytes-like objects <bytes-like object>` to ASCII
26 :class:`bytes`, and decoding :term:`bytes-like objects <bytes-like object>` or
27 strings containing ASCII to :class:`bytes`. Both base-64 alphabets
28 defined in :rfc:`4648` (normal, and URL- and filesystem-safe) are supported.
29
30 The :ref:`legacy interface <base64-legacy>` does not support decoding from strings, but it does
31 provide functions for encoding and decoding to and from :term:`file objects
32 <file object>`. It only supports the Base64 standard alphabet, and it adds
33 newlines every 76 characters as per :rfc:`2045`. Note that if you are looking
34 for :rfc:`2045` support you probably want to be looking at the :mod:`email`
35 package instead.
36
37
38 .. versionchanged:: 3.3
39 ASCII-only Unicode strings are now accepted by the decoding functions of
40 the modern interface.
41
42 .. versionchanged:: 3.4
43 Any :term:`bytes-like objects <bytes-like object>` are now accepted by all
44 encoding and decoding functions in this module. Ascii85/Base85 support added.
45
46
47 .. _base64-rfc-4648:
48
49 RFC 4648 Encodings
50 ------------------
51
52 The :rfc:`4648` encodings are suitable for encoding binary data so that it can be
53 safely sent by email, used as parts of URLs, or included as part of an HTTP
54 POST request.
55
56 .. function:: b64encode(s, altchars=None)
57
58 Encode the :term:`bytes-like object` *s* using Base64 and return the encoded
59 :class:`bytes`.
60
61 Optional *altchars* must be a :term:`bytes-like object` of length 2 which
62 specifies an alternative alphabet for the ``+`` and ``/`` characters.
63 This allows an application to e.g. generate URL or filesystem safe Base64
64 strings. The default is ``None``, for which the standard Base64 alphabet is used.
65
66 May assert or raise a :exc:`ValueError` if the length of *altchars* is not 2. Raises a
67 :exc:`TypeError` if *altchars* is not a :term:`bytes-like object`.
68
69
70 .. function:: b64decode(s, altchars=None, validate=False)
71
72 Decode the Base64 encoded :term:`bytes-like object` or ASCII string
73 *s* and return the decoded :class:`bytes`.
74
75 Optional *altchars* must be a :term:`bytes-like object` or ASCII string
76 of length 2 which specifies the alternative alphabet used instead of the
77 ``+`` and ``/`` characters.
78
79 A :exc:`binascii.Error` exception is raised
80 if *s* is incorrectly padded.
81
82 If *validate* is ``False`` (the default), characters that are neither
83 in the normal base-64 alphabet nor the alternative alphabet are
84 discarded prior to the padding check. If *validate* is ``True``,
85 these non-alphabet characters in the input result in a
86 :exc:`binascii.Error`.
87
88 For more information about the strict base64 check, see :func:`binascii.a2b_base64`
89
90 May assert or raise a :exc:`ValueError` if the length of *altchars* is not 2.
91
92 .. function:: standard_b64encode(s)
93
94 Encode :term:`bytes-like object` *s* using the standard Base64 alphabet
95 and return the encoded :class:`bytes`.
96
97
98 .. function:: standard_b64decode(s)
99
100 Decode :term:`bytes-like object` or ASCII string *s* using the standard
101 Base64 alphabet and return the decoded :class:`bytes`.
102
103
104 .. function:: urlsafe_b64encode(s)
105
106 Encode :term:`bytes-like object` *s* using the
107 URL- and filesystem-safe alphabet, which
108 substitutes ``-`` instead of ``+`` and ``_`` instead of ``/`` in the
109 standard Base64 alphabet, and return the encoded :class:`bytes`. The result
110 can still contain ``=``.
111
112
113 .. function:: urlsafe_b64decode(s)
114
115 Decode :term:`bytes-like object` or ASCII string *s*
116 using the URL- and filesystem-safe
117 alphabet, which substitutes ``-`` instead of ``+`` and ``_`` instead of
118 ``/`` in the standard Base64 alphabet, and return the decoded
119 :class:`bytes`.
120
121
122 .. function:: b32encode(s)
123
124 Encode the :term:`bytes-like object` *s* using Base32 and return the
125 encoded :class:`bytes`.
126
127
128 .. function:: b32decode(s, casefold=False, map01=None)
129
130 Decode the Base32 encoded :term:`bytes-like object` or ASCII string *s* and
131 return the decoded :class:`bytes`.
132
133 Optional *casefold* is a flag specifying
134 whether a lowercase alphabet is acceptable as input. For security purposes,
135 the default is ``False``.
136
137 :rfc:`4648` allows for optional mapping of the digit 0 (zero) to the letter O
138 (oh), and for optional mapping of the digit 1 (one) to either the letter I (eye)
139 or letter L (el). The optional argument *map01* when not ``None``, specifies
140 which letter the digit 1 should be mapped to (when *map01* is not ``None``, the
141 digit 0 is always mapped to the letter O). For security purposes the default is
142 ``None``, so that 0 and 1 are not allowed in the input.
143
144 A :exc:`binascii.Error` is raised if *s* is
145 incorrectly padded or if there are non-alphabet characters present in the
146 input.
147
148
149 .. function:: b32hexencode(s)
150
151 Similar to :func:`b32encode` but uses the Extended Hex Alphabet, as defined in
152 :rfc:`4648`.
153
154 .. versionadded:: 3.10
155
156
157 .. function:: b32hexdecode(s, casefold=False)
158
159 Similar to :func:`b32decode` but uses the Extended Hex Alphabet, as defined in
160 :rfc:`4648`.
161
162 This version does not allow the digit 0 (zero) to the letter O (oh) and digit
163 1 (one) to either the letter I (eye) or letter L (el) mappings, all these
164 characters are included in the Extended Hex Alphabet and are not
165 interchangeable.
166
167 .. versionadded:: 3.10
168
169
170 .. function:: b16encode(s)
171
172 Encode the :term:`bytes-like object` *s* using Base16 and return the
173 encoded :class:`bytes`.
174
175
176 .. function:: b16decode(s, casefold=False)
177
178 Decode the Base16 encoded :term:`bytes-like object` or ASCII string *s* and
179 return the decoded :class:`bytes`.
180
181 Optional *casefold* is a flag specifying whether a
182 lowercase alphabet is acceptable as input. For security purposes, the default
183 is ``False``.
184
185 A :exc:`binascii.Error` is raised if *s* is
186 incorrectly padded or if there are non-alphabet characters present in the
187 input.
188
189 .. _base64-base-85:
190
191 Base85 Encodings
192 -----------------
193
194 Base85 encoding is a family of algorithms which represent four bytes
195 using five ASCII characters. Originally implemented in the Unix
196 ``btoa(1)`` utility, a version of it was later adopted by Adobe in the
197 PostScript language and is standardized in PDF 2.0 (ISO 32000-2).
198 This version, in both its ``btoa`` and PDF variants, is implemented by
199 :func:`a85encode`.
200
201 A separate version, using a different output character set, was
202 defined as an April Fool's joke in :rfc:`1924` but is now used by Git
203 and other software. This version is implemented by :func:`b85encode`.
204
205 Finally, a third version, using yet another output character set
206 designed for safe inclusion in programming language strings, is
207 defined by ZeroMQ and implemented here by :func:`z85encode`.
208
209 The functions present in this module differ in how they handle the following:
210
211 * Whether to include and expect enclosing ``<~`` and ``~>`` markers.
212 * Whether to fold the input into multiple lines.
213 * The set of ASCII characters used for encoding.
214 * Compact encodings of sequences of spaces and null bytes.
215 * The encoding of zero-padding bytes applied to the input.
216
217 Refer to the documentation of the individual functions for more information.
218
219 .. function:: a85encode(b, *, foldspaces=False, wrapcol=0, pad=False, adobe=False)
220
221 Encode the :term:`bytes-like object` *b* using Ascii85 and return the
222 encoded :class:`bytes`.
223
224 *foldspaces* is an optional flag that uses the special short sequence 'y'
225 instead of 4 consecutive spaces (ASCII 0x20) as supported by 'btoa'. This
226 feature is not supported by the standard encoding used in PDF.
227
228 *wrapcol* controls whether the output should have newline (``b'\n'``)
229 characters added to it. If this is non-zero, each output line will be
230 at most this many characters long, excluding the trailing newline.
231
232 *pad* controls whether zero-padding applied to the end of the input
233 is fully retained in the output encoding, as done by ``btoa``,
234 producing an exact multiple of 5 bytes of output. This is not part
235 of the standard encoding used in PDF, as it does not preserve the
236 length of the data.
237
238 *adobe* controls whether the encoded byte sequence is framed with
239 ``<~`` and ``~>``, as in a PostScript base-85 string literal. Note
240 that while ASCII85Decode streams in PDF documents *must* be
241 terminated with ``~>``, they *must not* use a leading ``<~``.
242
243 .. versionadded:: 3.4
244
245
246 .. function:: a85decode(b, *, foldspaces=False, adobe=False, ignorechars=b' \t\n\r\v')
247
248 Decode the Ascii85 encoded :term:`bytes-like object` or ASCII string *b* and
249 return the decoded :class:`bytes`.
250
251 *foldspaces* is a flag that specifies whether the 'y' short sequence
252 should be accepted as shorthand for 4 consecutive spaces (ASCII 0x20).
253 This feature is not supported by the standard Ascii85 encoding used in
254 PDF and PostScript.
255
256 *adobe* controls whether the ``<~`` and ``~>`` markers are
257 present. While the leading ``<~`` is not required, the input must
258 end with ``~>``, or a :exc:`ValueError` is raised.
259
260 *ignorechars* should be a byte string containing characters to ignore
261 from the input. This should only contain whitespace characters, and by
262 default contains all whitespace characters in ASCII.
263
264 .. versionadded:: 3.4
265
266
267 .. function:: b85encode(b, pad=False)
268
269 Encode the :term:`bytes-like object` *b* using base85 (as used in e.g.
270 git-style binary diffs) and return the encoded :class:`bytes`.
271
272 The input is padded with ``b'\0'`` so its length is a multiple of 4
273 bytes before encoding. If *pad* is true, all the resulting
274 characters are retained in the output, which will always be a
275 multiple of 5 bytes, and thus the length of the data may not be
276 preserved on decoding.
277
278 .. versionadded:: 3.4
279
280
281 .. function:: b85decode(b)
282
283 Decode the base85-encoded :term:`bytes-like object` or ASCII string *b* and
284 return the decoded :class:`bytes`.
285
286 .. versionadded:: 3.4
287
288
289 .. function:: z85encode(s)
290
291 Encode the :term:`bytes-like object` *s* using Z85 (as used in ZeroMQ)
292 and return the encoded :class:`bytes`.
293
294 The `ZeroMQ specification <https://rfc.zeromq.org/spec/32/>`_
295 requires the length of Z85-encoded data to be a multiple of 5
296 bytes. To produce compliant data frames, you must pad the input
297 data to this function to a multiple of 4 bytes.
298
299 .. versionadded:: 3.13
300
301
302 .. function:: z85decode(s)
303
304 Decode the Z85-encoded :term:`bytes-like object` or ASCII string *s* and
305 return the decoded :class:`bytes`.
306
307 .. versionadded:: 3.13
308
309
310 .. _base64-legacy:
311
312 Legacy Interface
313 ----------------
314
315 .. function:: decode(input, output)
316
317 Decode the contents of the binary *input* file and write the resulting binary
318 data to the *output* file. *input* and *output* must be :term:`file objects
319 <file object>`. *input* will be read until ``input.readline()`` returns an
320 empty bytes object.
321
322
323 .. function:: decodebytes(s)
324
325 Decode the :term:`bytes-like object` *s*, which must contain one or more
326 lines of base64 encoded data, and return the decoded :class:`bytes`.
327
328 .. versionadded:: 3.1
329
330
331 .. function:: encode(input, output)
332
333 Encode the contents of the binary *input* file and write the resulting base64
334 encoded data to the *output* file. *input* and *output* must be :term:`file
335 objects <file object>`. *input* will be read until ``input.read()`` returns
336 an empty bytes object. :func:`encode` inserts a newline character (``b'\n'``)
337 after every 76 bytes of the output, as well as ensuring that the output
338 always ends with a newline, as per :rfc:`2045` (MIME).
339
340
341 .. function:: encodebytes(s)
342
343 Encode the :term:`bytes-like object` *s*, which can contain arbitrary binary
344 data, and return :class:`bytes` containing the base64-encoded data, with newlines
345 (``b'\n'``) inserted after every 76 bytes of output, and ensuring that
346 there is a trailing newline, as per :rfc:`2045` (MIME).
347
348 .. versionadded:: 3.1
349
350
351 An example usage of the module:
352
353 >>> import base64
354 >>> encoded = base64.b64encode(b'data to be encoded')
355 >>> encoded
356 b'ZGF0YSB0byBiZSBlbmNvZGVk'
357 >>> data = base64.b64decode(encoded)
358 >>> data
359 b'data to be encoded'
360
361 .. _base64-security:
362
363 Security Considerations
364 -----------------------
365
366 A new security considerations section was added to :rfc:`4648` (section 12); it's
367 recommended to review the security section for any code deployed to production.
368
369 .. seealso::
370
371 Module :mod:`binascii`
372 Support module containing ASCII-to-binary and binary-to-ASCII conversions.
373
374 :rfc:`1521` - MIME (Multipurpose Internet Mail Extensions) Part One: Mechanisms for Specifying and Describing the Format of Internet Message Bodies
375 Section 5.2, "Base64 Content-Transfer-Encoding," provides the definition of the
376 base64 encoding.
377
378 `ISO 32000-2 Portable document format - Part 2: PDF 2.0 <https://pdfa.org/resource/iso-32000-2/>`_
379 Section 7.4.3, "ASCII85Decode Filter," provides the definition
380 of the Ascii85 encoding used in PDF and PostScript, including
381 the output character set and the details of data length preservation
382 using zero-padding and partial output groups.
383
384 `ZeroMQ RFC 32/Z85 <https://rfc.zeromq.org/spec/32/>`_
385 The "Formal Specification" section provides the character set used in Z85.