base64 --- Base16, Base32, Base64, Base85 データのエンコード¶
ソースコード: Lib/base64.py
このモジュールは、バイナリデータを表示可能な ASCII 文字にエンコードし、エンコードされたデータをバイナリデータに戻す関数を提供します。 RFC 4648 で 規定されているエンコーディング (Base64、Base32、Base16)、PDF 2.0 で規定されている Base85 エンコーディング、その他の場所で使われる Base85 の非標準の変種を含みます。
このモジュールは、2つのインターフェースを提供します。このモダンなインターフェースは、bytes-like object を ASCII bytes にエンコードし、bytes-like object か ASCII 文字列を、bytes にデコードすることができます。RFC 4648 に定義されている base-64 アルファベット (一般の、URL あるいはファイルシステムセーフなもの) の両方が使用できます。
従来のインターフェース は文字列からのデコードができませんが、file object との間のエンコードとデコードが可能な関数を提供します。これは標準の base64 アルファベットのみをサポートし、RFC 2045 の規定にあるように、76文字ごとに改行されます。RFC 2045 のサポートのためには、代わりに email パッケージを参照する必要があるかもしれません。
バージョン 3.3 で変更: モダンなインターフェイスのデコード関数が ASCII のみの Unicode 文字列を受け付けるようになりました。
バージョン 3.4 で変更: このモジュールのすべてのエンコード・デコード関数が任意の bytes-like オブジェクト を受け取るようになりました。Ascii85/Base85 のサポートが追加されました。
RFC 4648 エンコーディング¶
RFC 4648 エンコーディングは、email で安全に送信したり、 URL の一部として使ったり、あるいは HTTP POST リクエストの一部に含めるために用いるのに適しています。
- base64.b64encode(s, altchars=None)¶
Base64 を使って bytes-like object の s をエンコードし、エンコードされた
bytesを返します。オプション引数 altchars は長さ 2 の bytes-like object で 、
+と/の代わりに使われる代替アルファベットを指定します。これにより、アプリケーションはたとえば URL やファイルシステムの影響を受けない Base64 文字列を生成できます。デフォルトはNoneで、標準の Base64 アルファベットが使われます。May assert or raise a
ValueErrorif the length of altchars is not 2. Raises aTypeErrorif altchars is not a bytes-like object.
- base64.b64decode(s, altchars=None, validate=False)¶
Base64 エンコードされた bytes-like object または ASCII 文字列 s をデコードし、デコードされた
bytesを返します。オプション引数の altchars は長さ 2 の bytes-like object または ASCII 文字列で、
+と/の代わりに使われる代替アルファベットを指定します。s が正しくパディングされていない場合は
binascii.Error例外を発生させます。If validate is
False(the default), characters that are neither in the normal base-64 alphabet nor the alternative alphabet are discarded prior to the padding check. If validate isTrue, these non-alphabet characters in the input result in abinascii.Error.厳密な base64 チェックのについての詳細は
binascii.a2b_base64()を参照してくださいMay assert or raise a
ValueErrorif the length of altchars is not 2.
- base64.standard_b64encode(s)¶
標準の base64 アルファベットを使用して bytes-like object の s をエンコードし、エンコードされた
bytesを返します。
- base64.standard_b64decode(s)¶
標準の base64 アルファベットを使用した bytes-like object または ASCII 文字列 s をデコードし、デコードされた
bytesを返します。
- base64.urlsafe_b64encode(s)¶
Encode bytes-like object s using the URL- and filesystem-safe alphabet, which substitutes
-instead of+and_instead of/in the standard Base64 alphabet, and return the encodedbytes. The result can still contain=.
- base64.urlsafe_b64decode(s)¶
bytes-like object または ASCII 文字列 s を URLとファイルシステムセーフなアルファベットを利用してデコードし、デコードされた
bytesを返します。標準 base64 アルファベットに比べて、+の替わりに-を、/の替わりに_を置換します。
- base64.b32encode(s)¶
Base32 を使って bytes-like object の s をエンコードし、エンコードされた
bytesを返します。
- base64.b32decode(s, casefold=False, map01=None)¶
Base32 エンコードされた bytes-like object または ASCII 文字列 s をデコードし、デコードされた
bytesを返します。オプション引数 casefold は小文字のアルファベットを受けつけるかどうかを指定します。セキュリティ上の理由により、デフォルトではこれは
Falseになっています。RFC 4648 は付加的なマッピングとして、数字の 0 (零) をアルファベットの O (オー) に、数字の 1 (壱) をアルファベットの I (アイ) または L (エル) に対応させることを許しています。オプション引数は map01 は、
Noneでないときは、数字の 1 をどの文字に対応づけるかを指定します (map01 がNoneでないとき、数字の 0 はつねにアルファベットの O (オー) に対応づけられます)。セキュリティ上の理由により、これはデフォルトではNoneになっているため、 0 および 1 は入力として許可されていません。s が正しくパディングされていない場合や、入力にアルファベットでない文字が含まれていた場合に、
binascii.Error例外を発生させます。
- base64.b32hexencode(s)¶
b32encode()に似ていますが、 RFC 4648 で定義されているようにExtended Hex Alphabetを使用します。Added in version 3.10.
- base64.b32hexdecode(s, casefold=False)¶
b32decode()に似ていますが、 RFC 4648 で定義されているようにExtended Hex Alphabetを使用します。この方式では、数字の 0 (ゼロ) を文字の O (オー) に、数字の 1 (いち) を文字の I (アイ) または L (エル) に対応付けることはできません。 これらはすべて Extended Hex Alphabet に含まれる別々の文字で、置き換えられないためです。
Added in version 3.10.
- base64.b16encode(s)¶
Base16 を使って bytes-like object の s をエンコードし、エンコードされた
bytesを返します。
- base64.b16decode(s, casefold=False)¶
Base16 エンコードされた bytes-like object または ASCII 文字列 s をデコードし、デコードされた
bytesを返します。オプション引数 casefold は小文字のアルファベットを受けつけるかどうかを指定します。セキュリティ上の理由により、デフォルトではこれは
Falseになっています。s が正しくパディングされていない場合や、入力にアルファベットでない文字が含まれていた場合に、
binascii.Error例外を発生させます。
Base85 エンコーディング¶
Base85 エンコーディングは、4 バイトを 5 つの ASCII 文字で表すアルゴリズム群です。
もともとは Unix の btoa(1) ユーティリティに実装され、その後 Adobe がその一種を PostScript 言語に採用し、PDF 2.0 (ISO 32000-2) で標準化されました。
この方式の btoa 版と PDF 版は、どちらも a85encode() に実装されています。
出力に異なる文字集合を使う別の方式は、エイプリルフールのジョークとして RFC 1924 で定義されましたが、現在は Git などのソフトウェアで使われています。
この方式は b85encode() に実装されています。
さらに、プログラミング言語の文字列に安全に含められるよう設計された、別の出力文字集合を使う 3 番目の方式を ZeroMQ が定義しています。
この方式は z85encode() に実装されています。
このモジュールの各関数は、次の点の扱いが異なります。
囲みのマーカー
<~と~>を出力に含めるか、入力に期待するか。入力を複数の行に折り返すか。
エンコードに使う ASCII 文字の集合。
連続するスペースやヌルバイトの短縮表現。
入力に加えたゼロパディングのバイトをどうエンコードするか。
詳しくは、各関数のドキュメントを参照してください。
- base64.a85encode(b, *, foldspaces=False, wrapcol=0, pad=False, adobe=False)¶
Ascii85 を使って bytes-like object の b をエンコードし、エンコードされた
bytesを返します。foldspaces は省略可能なフラグです。 'btoa' と同様に、連続する 4 つのスペース (ASCII 0x20) の代わりに特別な短縮表現 'y' を使います。 PDF で使われる標準のエンコーディングは、この機能をサポートしていません。
wrapcol controls whether the output should have newline (
b'\n') characters added to it. If this is non-zero, each output line will be at most this many characters long, excluding the trailing newline.pad controls whether zero-padding applied to the end of the input is fully retained in the output encoding, as done by
btoa, producing an exact multiple of 5 bytes of output. This is not part of the standard encoding used in PDF, as it does not preserve the length of the data.adobe は、PostScript の Base85 文字列リテラルのように、エンコードしたバイト列を
<~と~>で囲むかどうかを制御します。 PDF 文書の ASCII85Decode ストリームは~>で終わる 必要があります が、先頭に<~を付けては いけません。Added in version 3.4.
- base64.a85decode(b, *, foldspaces=False, adobe=False, ignorechars=b' \t\n\r\x0b')¶
Ascii85 エンコードされた bytes-like object または ASCII 文字列 b をデコードし、デコードされた
bytesを返します。foldspaces は、短縮表現 'y' を連続する 4 つのスペース (ASCII 0x20) として受け入れるかどうかを指定するフラグです。 PDF や PostScript で使われる標準の Ascii85 エンコーディングは、この機能をサポートしていません。
adobe は、マーカー
<~と~>の有無を指定します。 先頭の<~は必須ではありませんが、入力は~>で終わる必要があり、そうでなければValueErrorを送出します。ignorechars should be a byte string containing characters to ignore from the input. This should only contain whitespace characters, and by default contains all whitespace characters in ASCII.
Added in version 3.4.
- base64.b85encode(b, pad=False)¶
base85 (これは例えば git スタイルのバイナリ diff で用いられています) を使って bytes-like object の b をエンコードし、エンコードされた
bytesを返します。エンコードの前に、入力の長さが 4 バイトの倍数になるよう
b'\0'でパディングします。 pad が真の場合、結果の文字はすべて出力に残るため、出力の長さは常に 5 バイトの倍数になります。 そのため、デコード時にデータの長さが保たれない場合があります。Added in version 3.4.
- base64.b85decode(b)¶
Base85 でエンコードされた bytes-like object または ASCII 文字列 b をデコードし、デコードされた
bytesを返します。Added in version 3.4.
- base64.z85encode(s)¶
bytes-like object s を、ZeroMQ で使われる Z85 でエンコードし、エンコードされた
bytesを返します。The ZeroMQ specification requires the length of Z85-encoded data to be a multiple of 5 bytes. To produce compliant data frames, you must pad the input data to this function to a multiple of 4 bytes.
Added in version 3.13.
- base64.z85decode(s)¶
Z85 でエンコードされた bytes-like object または ASCII 文字列 s をデコードし、デコードされた
bytesを返します。Added in version 3.13.
レガシーインターフェース¶
- base64.decode(input, output)¶
input ファイルの中身をデコードし、結果のバイナリデータを output ファイルに出力します。 input 、 output ともに file objects でなければなりません。 input は
input.readline()が空バイト列を返すまで読まれます。
- base64.decodebytes(s)¶
bytes-like object s をデコードし、デコードされた
bytesを返します。 s には一行以上の base64 形式でエンコードされたデータが含まれている必要があります。Added in version 3.1.
- base64.encode(input, output)¶
バイナリの input ファイルの中身を base64 形式でエンコードした結果を output ファイルに出力します。 input 、 output ともに file objects でなければなりません。 input は
input.read()が空バイト列を返すまで読まれます。encode()は76バイトの出力ごとに改行文字(b'\n')を挿入し、RFC 2045 (MIME) の規定にあるように常に出力が新しい行で終わることを保証します。
- base64.encodebytes(s)¶
bytes-like object s (任意のバイナリデータを含むことができます) を、RFC 2045 (MIME) に規定されるように末尾に新しい行のある、76バイトの出力ごとに新しい行 (
b'\n') が挿入された、base64 形式でエンコードしたデータを含むbytesを返します。Added in version 3.1.
モジュールの使用例:
>>> import base64
>>> encoded = base64.b64encode(b'data to be encoded')
>>> encoded
b'ZGF0YSB0byBiZSBlbmNvZGVk'
>>> data = base64.b64decode(encoded)
>>> data
b'data to be encoded'
セキュリティで考慮すべき点¶
RFC 4648 に、セキュリティ上の考慮事項をまとめた節 (第 12 節) が新たに追加されました。 本番環境で使うコードでは、このセキュリティの節を確認することを推奨します。
参考
- モジュール
binascii ASCII からバイナリへ、バイナリから ASCII への変換をサポートするモジュール。
- RFC 1521 - MIME (Multipurpose Internet Mail Extensions) Part One: Mechanisms for Specifying and Describing the Format of Internet Message Bodies
Section 5.2, "Base64 Content-Transfer-Encoding," provides the definition of the base64 encoding.
- ISO 32000-2 Portable document format - Part 2: PDF 2.0
第 7.4.3 節 "ASCII85Decode Filter" は、PDF と PostScript で使われる Ascii85 エンコーディングを定義しています。 出力の文字集合のほか、ゼロパディングと部分的な出力グループによってデータ長を保持する方法が詳しく説明されています。
- ZeroMQ RFC 32/Z85
"Formal Specification" の節は、Z85 で使われる文字集合を定義しています。