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, *, padded=True, wrapcol=0)¶
Base64 を使って bytes-like object の s をエンコードし、エンコードされた
bytesを返します。オプション引数 altchars は長さ 2 の bytes-like object で 、
+と/の代わりに使われる代替アルファベットを指定します。これにより、アプリケーションはたとえば URL やファイルシステムの影響を受けない Base64 文字列を生成できます。デフォルトはNoneで、標準の Base64 アルファベットが使われます。padded が真 (デフォルト) の場合、エンコードしたデータの長さが 4 の倍数になるように '=' でパディングします。 padded が偽の場合、パディング文字を追加しません。
wrapcol がゼロでない場合、最大 wrapcol 文字ごとに改行文字 (
b'\n') を挿入します。 wrapcol がゼロ (デフォルト) の場合、改行を挿入しません。バージョン 3.15 で変更: padded と wrapcol パラメーターが追加されました。
- base64.b64decode(s, altchars=None, validate=False, *, padded=True, canonical=False)¶
- base64.b64decode(s, altchars=None, validate=True, *, ignorechars, padded=True, canonical=False)
Base64 エンコードされた bytes-like object または ASCII 文字列 s をデコードし、デコードされた
bytesを返します。オプション引数の altchars は長さ 2 の bytes-like object または ASCII 文字列で、
+と/の代わりに使われる代替アルファベットを指定します。padded が真の場合、Base64 アルファベットの最後の 4 文字の組には '=' によるパディングが必要です。 padded が偽の場合、パディングは不要で、パディングとしての認識もしません。 '=' はパディングではなくアルファベット外の文字として扱われるため、validate が偽なら黙って破棄されます。 validate が真なら、ignorechars に
b'='が含まれていない限りErrorが発生します。s が正しくパディングされていない場合は
binascii.Error例外を発生させます。ignorechars を指定する場合は、validate が真のときに入力から無視する文字を含む bytes-like object を渡してください。 ignorechars にパディング文字
'='を含めると、エンコードされたデータの末尾より前に現れるパディング文字や、余分なパディング文字を無視します。 validate のデフォルト値は、ignorechars を指定した場合はTrue、それ以外はFalseです。If validate is false, characters that are neither in the normal base-64 alphabet nor (if ignorechars is not specified) the alternative alphabet are discarded prior to the padding check, but the
+and/characters keep their meaning if they are not in altchars (they will be discarded in future Python versions).validate が真の場合、入力にこれらのアルファベット外の文字があると
binascii.Errorが発生します。canonical が真の場合、ゼロでないパディングビットを拒否します。 詳しくは
binascii.a2b_base64()を参照してください。厳密な base64 チェックのについての詳細は
binascii.a2b_base64()を参照してくださいバージョン 3.15 で変更: canonical、ignorechars、padded パラメーターが追加されました。
バージョン 3.15 で非推奨: 代替アルファベットの使用時に
+と/を受け入れることは非推奨になりました。
- 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, *, padded=True)¶
bytes-like object s を、URL やファイルシステムで安全に使えるアルファベットでエンコードし、エンコードされた
bytesを返します。 このアルファベットは、標準の Base64 アルファベットの+を-に、/を_に置き換えたものです。 padded が真 (デフォルト) の場合、結果には=が含まれることがあります。バージョン 3.15 で変更: padded パラメーターが追加されました。
- base64.urlsafe_b64decode(s, *, padded=False)¶
bytes-like object または ASCII 文字列 s を URLとファイルシステムセーフなアルファベットを利用してデコードし、デコードされた
bytesを返します。標準 base64 アルファベットに比べて、+の替わりに-を、/の替わりに_を置換します。バージョン 3.15 で変更: padded パラメーターが追加されました。 デフォルトでは入力のパディングが不要になりました。
バージョン 3.15 で非推奨:
+と/を受け入れることは非推奨になりました。
- base64.b32encode(s, *, padded=True, wrapcol=0)¶
Base32 を使って bytes-like object の s をエンコードし、エンコードされた
bytesを返します。padded が真 (デフォルト) の場合、エンコードしたデータの長さが 8 の倍数になるように '=' でパディングします。 padded が偽の場合、パディング文字を追加しません。
wrapcol がゼロでない場合、最大 wrapcol 文字ごとに改行文字 (
b'\n') を挿入します。 wrapcol がゼロ (デフォルト) の場合、改行を追加しません。バージョン 3.15 で変更: padded と wrapcol パラメーターが追加されました。
- base64.b32decode(s, casefold=False, map01=None, *, padded=True, ignorechars=b'', canonical=False)¶
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 は入力として許可されていません。padded が真の場合、Base32 アルファベットの最後の 8 文字の組には '=' によるパディングが必要です。 padded が偽の場合、パディングは不要で、パディングとしての認識もしません。 '=' はパディングではなくアルファベット外の文字として扱われるため、ignorechars に
b'='が含まれていない限りErrorが発生します。ignorechars には、入力から無視する文字を含む bytes-like object を指定してください。
canonical が真の場合、ゼロでないパディングビットを拒否します。 詳しくは
binascii.a2b_base32()を参照してください。s が正しくパディングされていない場合や、入力にアルファベットでない文字が含まれていた場合に、
binascii.Error例外を発生させます。バージョン 3.15 で変更: canonical、ignorechars、padded パラメーターが追加されました。
- base64.b32hexencode(s, *, padded=True, wrapcol=0)¶
b32encode()に似ていますが、 RFC 4648 で定義されているようにExtended Hex Alphabetを使用します。Added in version 3.10.
バージョン 3.15 で変更: padded と wrapcol パラメーターが追加されました。
- base64.b32hexdecode(s, casefold=False, *, padded=True, ignorechars=b'', canonical=False)¶
b32decode()に似ていますが、 RFC 4648 で定義されているようにExtended Hex Alphabetを使用します。この方式では、数字の 0 (ゼロ) を文字の O (オー) に、数字の 1 (いち) を文字の I (アイ) または L (エル) に対応付けることはできません。 これらはすべて Extended Hex Alphabet に含まれる別々の文字で、置き換えられないためです。
Added in version 3.10.
バージョン 3.15 で変更: canonical、ignorechars、padded パラメーターが追加されました。
- base64.b16encode(s, *, wrapcol=0)¶
Base16 を使って bytes-like object の s をエンコードし、エンコードされた
bytesを返します。wrapcol がゼロでない場合、最大 wrapcol 文字ごとに改行文字 (
b'\n') を挿入します。 wrapcol がゼロ (デフォルト) の場合、改行を追加しません。バージョン 3.15 で変更: wrapcol パラメーターが追加されました。
- base64.b16decode(s, casefold=False, *, ignorechars=b'')¶
Base16 エンコードされた bytes-like object または ASCII 文字列 s をデコードし、デコードされた
bytesを返します。オプション引数 casefold は小文字のアルファベットを受けつけるかどうかを指定します。セキュリティ上の理由により、デフォルトではこれは
Falseになっています。ignorechars には、入力から無視する文字を含む bytes-like object を指定してください。
s が正しくパディングされていない場合や、入力にアルファベットでない文字が含まれていた場合に、
binascii.Error例外を発生させます。バージョン 3.15 で変更: ignorechars パラメーターが追加されました。
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 がゼロでない場合、最大 wrapcol 文字ごとに改行文字 (
b'\n') を挿入します。 wrapcol がゼロ (デフォルト) の場合、改行を挿入しません。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', canonical=False)¶
Ascii85 エンコードされた bytes-like object または ASCII 文字列 b をデコードし、デコードされた
bytesを返します。foldspaces は、短縮表現 'y' を連続する 4 つのスペース (ASCII 0x20) として受け入れるかどうかを指定するフラグです。 PDF や PostScript で使われる標準の Ascii85 エンコーディングは、この機能をサポートしていません。
adobe は、マーカー
<~と~>の有無を指定します。 先頭の<~は必須ではありませんが、入力は~>で終わる必要があり、そうでなければValueErrorを送出します。ignorechars should be a bytes-like object containing characters to ignore from the input. This should only contain whitespace characters, and by default contains all whitespace characters in ASCII.
canonical が真の場合、正規形でないエンコーディングを拒否します。 詳しくは
binascii.a2b_ascii85()を参照してください。Added in version 3.4.
バージョン 3.15 で変更: canonical パラメーターが追加されました。 最後のグループが 1 文字だけの場合は、エンコーディングの規則に違反するものとして常に拒否するようになりました。
- base64.b85encode(b, pad=False, *, wrapcol=0)¶
base85 (これは例えば git スタイルのバイナリ diff で用いられています) を使って bytes-like object の b をエンコードし、エンコードされた
bytesを返します。エンコードの前に、入力の長さが 4 バイトの倍数になるよう
b'\0'でパディングします。 pad が真の場合、結果の文字はすべて出力に残るため、出力の長さは常に 5 バイトの倍数になります。 そのため、デコード時にデータの長さが保たれない場合があります。wrapcol がゼロでない場合、最大 wrapcol 文字ごとに改行文字 (
b'\n') を挿入します。 wrapcol がゼロ (デフォルト) の場合、改行を追加しません。Added in version 3.4.
バージョン 3.15 で変更: wrapcol パラメーターが追加されました。
- base64.b85decode(b, *, ignorechars=b'', canonical=False)¶
Base85 でエンコードされた bytes-like object または ASCII 文字列 b をデコードし、デコードされた
bytesを返します。ignorechars には、入力から無視する文字を含む bytes-like object を指定してください。
canonical が真の場合、正規形でないエンコーディングを拒否します。 詳しくは
binascii.a2b_base85()を参照してください。Added in version 3.4.
バージョン 3.15 で変更: canonical と ignorechars パラメーターが追加されました。 最後のグループが 1 文字だけの場合は、エンコーディングの規則に違反するものとして常に拒否するようになりました。
- base64.z85encode(s, pad=False, *, wrapcol=0)¶
bytes-like object s を、ZeroMQ で使われる Z85 でエンコードし、エンコードされた
bytesを返します。エンコードの前に、入力の長さが 4 バイトの倍数になるよう
b'\0'でパディングします。 pad が真の場合、結果の文字はすべて出力に残るため、ZeroMQ の標準で要求されるとおり、出力の長さは常に 5 バイトの倍数になります。wrapcol がゼロでない場合、最大 wrapcol 文字ごとに改行文字 (
b'\n') を挿入します。 wrapcol がゼロ (デフォルト) の場合、改行を追加しません。Added in version 3.13.
バージョン 3.15 で変更: pad パラメーターが追加されました。
バージョン 3.15 で変更: wrapcol パラメーターが追加されました。
- base64.z85decode(s, *, ignorechars=b'', canonical=False)¶
Z85 でエンコードされた bytes-like object または ASCII 文字列 s をデコードし、デコードされた
bytesを返します。ignorechars には、入力から無視する文字を含む bytes-like object を指定してください。
canonical が真の場合、正規形でないエンコーディングを拒否します。 詳しくは
binascii.a2b_base85()を参照してください。Added in version 3.13.
バージョン 3.15 で変更: canonical と ignorechars パラメーターが追加されました。 最後のグループが 1 文字だけの場合は、エンコーディングの規則に違反するものとして常に拒否するようになりました。
レガシーインターフェース¶
- 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 で使われる文字集合を定義しています。