Base64 のエンコードとデコード

Base64 とは、バイナリーからテキストへの符号化を行う手法のグループであり、64 を基数とする表現に変換することで、バイナリーデータを ASCII 文字列で表すことができます。Base64 という呼び方は、MIME の Content-Transfer-Encoding における特定の符号化方式の名前に由来します。

Base64 符号化方式がよく使われるのは、テキストデータを扱うよう設計されたメディア上で、バイナリーデータを格納または転送する必要がある場合です。Base64 符号化により、転送中に変換されることなく、バイナリーデータがそのままであることを保証できます。Base64 は、MIME による電子メールや XML における複合型データの格納など、多くのアプリケーションで幅広く使われています。

JavaScript には、Base64 文字列のエンコードとデコードのそれぞれに対応した、次の 2 つの関数があります。

• atob()
• btoa()

atob() 関数は、Base64 符号化方式によりエンコードされている文字列をデコードしてバイナリー文字列を作ります。逆に btoa() 関数は、バイナリー文字列から Base64 でエンコードされた ASCII 文字列を作ります。

atob() と btoa() のどちらも、文字列に対して動作します。もし ArrayBuffer に対して動作させたい場合は、この段落 を読んでください。

符号化によるサイズ増加

Base64 の 1 文字はデータのちょうど 6 ビット分を表します。そのため、入力される文字列やバイナリーファイルに含まれる 3 バイト (3×8 ビット = 24 ビット) は、4 桁の Base64 で表されます (4×6 = 24 ビット)。

このことにより、Base64 で表された文字列またはファイルは、元のサイズの 133% の大きさになると言えます (33% の増加)。エンコードされるデータが小さい場合は、さらに増加幅が大きくなります。例えば、length === 1 である文字列 "a" は、エンコードされて length === 4 の文字列 "YQ==" になり、これは 300% の増加です。

あの「Unicode の問題」

DOMString は 16 ビットで符号化された文字列であるので、Unicode 文字列を使って window.btoa を実行すると、8 ビットの範囲 (0x00~0xFF) を超えた文字がある場合に、ほとんどのブラウザーで Character Out Of Range 例外が発生します。以下は、この問題を解決するための 5 つの方法です。

• 最初の方法は、JavaScript のネイティブ UTF-16 文字列を直接 Base64 にエンコードします (高速で、移植性があり、クリーン)
• 2 番目の方法は、JavaScript のネイティブ UTF-16 文字列を UTF-8 に変換し、その後 Base64 にエンコードします (比較的高速で、移植性があり、クリーン)
• 3 番目の方法は、JavaScript のネイティブ UTF-16 文字列を、バイナリー文字列経由で、Base64 にエンコードします (非常に高速で、比較的移植性があり、非常にコンパクト)
• 4 番目の方法は、文字列全体をエスケープし (UTF-8 を使う。encodeURIComponent を参照)、そしてエンコードします (移植性はあるが、非標準的)
• 5 番目の方法は、2 番目の方法と似ていますが、サードパーティのライブラリを使います

方法 1 – JavaScript の UTF-16 => Base64

Unicode 問題を解決する、非常に高速で幅広く使われている方法は、JavaScript のネイティブ UTF-16 文字列を直接 Base64 にエンコードすることです。デモのために URL data:text/plain;charset=utf-16;base64,OCY5JjomOyY8Jj4mPyY= を開いてください (このデータ URL をコピーし、新しいタブを開き、データ URL をアドレスバーに貼り付け、エンターをを押す)。この方法は、文字列を配列に割り当てるところを除き、どのような種類の変換も必要としないため、特に効率的です。次のコードは、Base64 文字列から ArrayBuffer に変換したり、その逆変換をするのにも便利です (下記参照)。

"use strict";

/*\
|*|
|*|  Base64 / binary data / UTF-8 strings utilities (#1)
|*|
|*|  https://developer.mozilla.org/en-US/docs/Web/API/WindowBase64/Base64_encoding_and_decoding
|*|
|*|  Author: madmurphy
|*|
\*/

/* Array of bytes to base64 string decoding */

function b64ToUint6 (nChr) {

  return nChr > 64 && nChr < 91 ?
      nChr - 65
    : nChr > 96 && nChr < 123 ?
      nChr - 71
    : nChr > 47 && nChr < 58 ?
      nChr + 4
    : nChr === 43 ?
      62
    : nChr === 47 ?
      63
    :
      0;

}

function base64DecToArr (sBase64, nBlockSize) {

  var
    sB64Enc = sBase64.replace(/[^A-Za-z0-9\+\/]/g, ""), nInLen = sB64Enc.length,
    nOutLen = nBlockSize ? Math.ceil((nInLen * 3 + 1 >>> 2) / nBlockSize) * nBlockSize : nInLen * 3 + 1 >>> 2, aBytes = new Uint8Array(nOutLen);

  for (var nMod3, nMod4, nUint24 = 0, nOutIdx = 0, nInIdx = 0; nInIdx < nInLen; nInIdx++) {
    nMod4 = nInIdx & 3;
    nUint24 |= b64ToUint6(sB64Enc.charCodeAt(nInIdx)) << 18 - 6 * nMod4;
    if (nMod4 === 3 || nInLen - nInIdx === 1) {
      for (nMod3 = 0; nMod3 < 3 && nOutIdx < nOutLen; nMod3++, nOutIdx++) {
        aBytes[nOutIdx] = nUint24 >>> (16 >>> nMod3 & 24) & 255;
      }
      nUint24 = 0;
    }
  }

  return aBytes;
}

/* Base64 string to array encoding */

function uint6ToB64 (nUint6) {

  return nUint6 < 26 ?
      nUint6 + 65
    : nUint6 < 52 ?
      nUint6 + 71
    : nUint6 < 62 ?
      nUint6 - 4
    : nUint6 === 62 ?
      43
    : nUint6 === 63 ?
      47
    :
      65;

}

function base64EncArr (aBytes) {

  var eqLen = (3 - (aBytes.length % 3)) % 3, sB64Enc = "";

  for (var nMod3, nLen = aBytes.length, nUint24 = 0, nIdx = 0; nIdx < nLen; nIdx++) {
    nMod3 = nIdx % 3;
    /* Uncomment the following line in order to split the output in lines 76-character long: */
    /*
    if (nIdx > 0 && (nIdx * 4 / 3) % 76 === 0) { sB64Enc += "\r\n"; }
    */
    nUint24 |= aBytes[nIdx] << (16 >>> nMod3 & 24);
    if (nMod3 === 2 || aBytes.length - nIdx === 1) {
      sB64Enc += String.fromCharCode(uint6ToB64(nUint24 >>> 18 & 63), uint6ToB64(nUint24 >>> 12 & 63), uint6ToB64(nUint24 >>> 6 & 63), uint6ToB64(nUint24 & 63));
      nUint24 = 0;
    }
  }

  return  eqLen === 0 ?
      sB64Enc
    :
      sB64Enc.substring(0, sB64Enc.length - eqLen) + (eqLen === 1 ? "=" : "==");

}

テスト

var myString = "☸☹☺☻☼☾☿";

/* Part 1: `myString` をネイティブの UTF-16 を使って Base64 にエンコードする */

var aUTF16CodeUnits = new Uint16Array(myString.length);
Array.prototype.forEach.call(aUTF16CodeUnits, function (el, idx, arr) { arr[idx] = myString.charCodeAt(idx); });
var sUTF16Base64 = base64EncArr(new Uint8Array(aUTF16CodeUnits.buffer));

/* 出力を表示する */

alert(sUTF16Base64); // "OCY5JjomOyY8Jj4mPyY="

/* Part 2: `sUTF16Base64` を UTF-16 にデコードする */

var sDecodedString = String.fromCharCode.apply(null, new Uint16Array(base64DecToArr(sUTF16Base64, 2).buffer));

/* 出力を表示する */

alert(sDecodedString); // "☸☹☺☻☼☾☿"

生成された Base64 文字列はどこでも使えますが、UTF-16 で表現されています。もし UTF-8 を望む場合は次の方法を参照してください。

方法 1 に対する補足: Base64 文字列を Uint8Array や ArrayBuffer にデコードする

上記の関数を使って、Base64 でエンコードされた文字列から Uint8Array や ArrayBuffer を作ることもできます。

var myArray = base64DecToArr("QmFzZSA2NCDigJQgTW96aWxsYSBEZXZlbG9wZXIgTmV0d29yaw=="); // "Base 64 \u2014 Mozilla Developer Network" (as UTF-8)

var myBuffer = base64DecToArr("QmFzZSA2NCDigJQgTW96aWxsYSBEZXZlbG9wZXIgTmV0d29yaw==").buffer; // "Base 64 \u2014 Mozilla Developer Network" (as UTF-8)

alert(myBuffer.byteLength);

完全なライブラリーは StringView – 型付き配列に基づく C 言語に似た文字列表現 を参照してください (ソースコードは GitHub で利用できます)。

方法 2 – JavaScript の UTF-16 => UTF-8 => Base64

この方法は、JavaScript ネイティブの UTF-16 文字列を UTF-8 文字列に変換し、それを Base64 でエンコードします。これにより、純粋な ASCII 文字列から Base64 への変換は、ネイティブの btoa() のように、常に同じ結果を出力します。

"use strict";

/*\
|*|
|*|  Base64 / binary data / UTF-8 strings utilities (#2)
|*|
|*|  https://developer.mozilla.org/en-US/docs/Web/API/WindowBase64/Base64_encoding_and_decoding
|*|
|*|  Author: madmurphy
|*|
\*/

/* Array of bytes to base64 string decoding */

function b64ToUint6 (nChr) {

  return nChr > 64 && nChr < 91 ?
      nChr - 65
    : nChr > 96 && nChr < 123 ?
      nChr - 71
    : nChr > 47 && nChr < 58 ?
      nChr + 4
    : nChr === 43 ?
      62
    : nChr === 47 ?
      63
    :
      0;

}

function base64DecToArr (sBase64, nBlockSize) {

  var
    sB64Enc = sBase64.replace(/[^A-Za-z0-9\+\/]/g, ""), nInLen = sB64Enc.length,
    nOutLen = nBlockSize ? Math.ceil((nInLen * 3 + 1 >>> 2) / nBlockSize) * nBlockSize : nInLen * 3 + 1 >>> 2, aBytes = new Uint8Array(nOutLen);

  for (var nMod3, nMod4, nUint24 = 0, nOutIdx = 0, nInIdx = 0; nInIdx < nInLen; nInIdx++) {
    nMod4 = nInIdx & 3;
    nUint24 |= b64ToUint6(sB64Enc.charCodeAt(nInIdx)) << 18 - 6 * nMod4;
    if (nMod4 === 3 || nInLen - nInIdx === 1) {
      for (nMod3 = 0; nMod3 < 3 && nOutIdx < nOutLen; nMod3++, nOutIdx++) {
        aBytes[nOutIdx] = nUint24 >>> (16 >>> nMod3 & 24) & 255;
      }
      nUint24 = 0;
    }
  }

  return aBytes;
}

/* Base64 string to array encoding */

function uint6ToB64 (nUint6) {

  return nUint6 < 26 ?
      nUint6 + 65
    : nUint6 < 52 ?
      nUint6 + 71
    : nUint6 < 62 ?
      nUint6 - 4
    : nUint6 === 62 ?
      43
    : nUint6 === 63 ?
      47
    :
      65;

}

function base64EncArr (aBytes) {

  var eqLen = (3 - (aBytes.length % 3)) % 3, sB64Enc = "";

  for (var nMod3, nLen = aBytes.length, nUint24 = 0, nIdx = 0; nIdx < nLen; nIdx++) {
    nMod3 = nIdx % 3;
    /* Uncomment the following line in order to split the output in lines 76-character long: */
    /*
    if (nIdx > 0 && (nIdx * 4 / 3) % 76 === 0) { sB64Enc += "\r\n"; }
    */
    nUint24 |= aBytes[nIdx] << (16 >>> nMod3 & 24);
    if (nMod3 === 2 || aBytes.length - nIdx === 1) {
      sB64Enc += String.fromCharCode(uint6ToB64(nUint24 >>> 18 & 63), uint6ToB64(nUint24 >>> 12 & 63), uint6ToB64(nUint24 >>> 6 & 63), uint6ToB64(nUint24 & 63));
      nUint24 = 0;
    }
  }

  return  eqLen === 0 ?
      sB64Enc
    :
      sB64Enc.substring(0, sB64Enc.length - eqLen) + (eqLen === 1 ? "=" : "==");

}

/* UTF-8 array to DOMString and vice versa */

function UTF8ArrToStr (aBytes) {

  var sView = "";

  for (var nPart, nLen = aBytes.length, nIdx = 0; nIdx < nLen; nIdx++) {
    nPart = aBytes[nIdx];
    sView += String.fromCharCode(
      nPart > 251 && nPart < 254 && nIdx + 5 < nLen ? /* six bytes */
        /* (nPart - 252 << 30) may be not so safe in ECMAScript! So...: */
        (nPart - 252) * 1073741824 + (aBytes[++nIdx] - 128 << 24) + (aBytes[++nIdx] - 128 << 18) + (aBytes[++nIdx] - 128 << 12) + (aBytes[++nIdx] - 128 << 6) + aBytes[++nIdx] - 128
      : nPart > 247 && nPart < 252 && nIdx + 4 < nLen ? /* five bytes */
        (nPart - 248 << 24) + (aBytes[++nIdx] - 128 << 18) + (aBytes[++nIdx] - 128 << 12) + (aBytes[++nIdx] - 128 << 6) + aBytes[++nIdx] - 128
      : nPart > 239 && nPart < 248 && nIdx + 3 < nLen ? /* four bytes */
        (nPart - 240 << 18) + (aBytes[++nIdx] - 128 << 12) + (aBytes[++nIdx] - 128 << 6) + aBytes[++nIdx] - 128
      : nPart > 223 && nPart < 240 && nIdx + 2 < nLen ? /* three bytes */
        (nPart - 224 << 12) + (aBytes[++nIdx] - 128 << 6) + aBytes[++nIdx] - 128
      : nPart > 191 && nPart < 224 && nIdx + 1 < nLen ? /* two bytes */
        (nPart - 192 << 6) + aBytes[++nIdx] - 128
      : /* nPart < 127 ? */ /* one byte */
        nPart
    );
  }

  return sView;

}

function strToUTF8Arr (sDOMStr) {

  var aBytes, nChr, nStrLen = sDOMStr.length, nArrLen = 0;

  /* mapping... */

  for (var nMapIdx = 0; nMapIdx < nStrLen; nMapIdx++) {
    nChr = sDOMStr.charCodeAt(nMapIdx);
    nArrLen += nChr < 0x80 ? 1 : nChr < 0x800 ? 2 : nChr < 0x10000 ? 3 : nChr < 0x200000 ? 4 : nChr < 0x4000000 ? 5 : 6;
  }

  aBytes = new Uint8Array(nArrLen);

  /* transcription... */

  for (var nIdx = 0, nChrIdx = 0; nIdx < nArrLen; nChrIdx++) {
    nChr = sDOMStr.charCodeAt(nChrIdx);
    if (nChr < 128) {
      /* one byte */
      aBytes[nIdx++] = nChr;
    } else if (nChr < 0x800) {
      /* two bytes */
      aBytes[nIdx++] = 192 + (nChr >>> 6);
      aBytes[nIdx++] = 128 + (nChr & 63);
    } else if (nChr < 0x10000) {
      /* three bytes */
      aBytes[nIdx++] = 224 + (nChr >>> 12);
      aBytes[nIdx++] = 128 + (nChr >>> 6 & 63);
      aBytes[nIdx++] = 128 + (nChr & 63);
    } else if (nChr < 0x200000) {
      /* four bytes */
      aBytes[nIdx++] = 240 + (nChr >>> 18);
      aBytes[nIdx++] = 128 + (nChr >>> 12 & 63);
      aBytes[nIdx++] = 128 + (nChr >>> 6 & 63);
      aBytes[nIdx++] = 128 + (nChr & 63);
    } else if (nChr < 0x4000000) {
      /* five bytes */
      aBytes[nIdx++] = 248 + (nChr >>> 24);
      aBytes[nIdx++] = 128 + (nChr >>> 18 & 63);
      aBytes[nIdx++] = 128 + (nChr >>> 12 & 63);
      aBytes[nIdx++] = 128 + (nChr >>> 6 & 63);
      aBytes[nIdx++] = 128 + (nChr & 63);
    } else /* if (nChr <= 0x7fffffff) */ {
      /* six bytes */
      aBytes[nIdx++] = 252 + (nChr >>> 30);
      aBytes[nIdx++] = 128 + (nChr >>> 24 & 63);
      aBytes[nIdx++] = 128 + (nChr >>> 18 & 63);
      aBytes[nIdx++] = 128 + (nChr >>> 12 & 63);
      aBytes[nIdx++] = 128 + (nChr >>> 6 & 63);
      aBytes[nIdx++] = 128 + (nChr & 63);
    }
  }

  return aBytes;

}

テスト

/* テスト */

var sMyInput = "Base 64 \u2014 Mozilla Developer Network";

var aMyUTF8Input = strToUTF8Arr(sMyInput);

var sMyBase64 = base64EncArr(aMyUTF8Input);

alert(sMyBase64); // "QmFzZSA2NCDigJQgTW96aWxsYSBEZXZlbG9wZXIgTmV0d29yaw=="

var aMyUTF8Output = base64DecToArr(sMyBase64);

var sMyOutput = UTF8ArrToStr(aMyUTF8Output);

alert(sMyOutput); // "Base 64 — Mozilla Developer Network"

方法 3 – JavaScript の UTF-16 => バイナリー文字列 => Base64

これは、最も速く最もコンパクトな方法です。出力は方法 1 (UTF-16 ででエンコードされた文字列) のものと全く同じですが、atob() と btoa() を書き直すのではなく、ネイティブのものを使います。この方法はエンコードまたはデコードの入力として、型付き配列の代わりに、中間フォーマットであるバイナリー文字列を使います。方法 1 (バイナリー文字列 は灰色の領域です) に比べると、これは「汚い」回避策ではありますが、問題なく動作し、必要なコードはわずか数行です。

"use strict";

/*\
|*|
|*|  Base64 / binary data / UTF-8 strings utilities (#3)
|*|
|*|  https://developer.mozilla.org/en-US/docs/Web/API/WindowBase64/Base64_encoding_and_decoding
|*|
|*|  Author: madmurphy
|*|
\*/

function btoaUTF16 (sString) {

	var aUTF16CodeUnits = new Uint16Array(sString.length);
	Array.prototype.forEach.call(aUTF16CodeUnits, function (el, idx, arr) { arr[idx] = sString.charCodeAt(idx); });
	return btoa(String.fromCharCode.apply(null, new Uint8Array(aUTF16CodeUnits.buffer)));

}

function atobUTF16 (sBase64) {

	var sBinaryString = atob(sBase64), aBinaryView = new Uint8Array(sBinaryString.length);
	Array.prototype.forEach.call(aBinaryView, function (el, idx, arr) { arr[idx] = sBinaryString.charCodeAt(idx); });
	return String.fromCharCode.apply(null, new Uint16Array(aBinaryView.buffer));

}

テスト

var myString = "☸☹☺☻☼☾☿";

/* Part 1: `myString` をネイティブの UTF-16 を使って Base64 にエンコードする */

var sUTF16Base64 = btoaUTF16(myString);

/* 出力を表示する */

alert(sUTF16Base64); // "OCY5JjomOyY8Jj4mPyY="

/* Part 2: `sUTF16Base64` を UTF-16 にデコードする */

var sDecodedString = atobUTF16(sUTF16Base64);

/* 出力を表示する */

alert(sDecodedString); // "☸☹☺☻☼☾☿"

バイナリー文字列の代わりに型付き配列を使う、よりクリーンな方法については、方法 1 と方法 2 を参照してください。

方法 4 – エンコード前に文字列をエスケープ処理する

function b64EncodeUnicode(str) {
    // 最初に encodeURIComponent を使って "%" でエンコードされた UTF-8 文字列を取得し、
    // 次に "%" でエンコードされた文字列をバイナリー文字列に変換し、
    // それを btoa に与えます。
    return btoa(encodeURIComponent(str).replace(/%([0-9A-F]{2})/g,
        function toSolidBytes(match, p1) {
            return String.fromCharCode('0x' + p1);
    }));
}

b64EncodeUnicode('✓ à la mode'); // "4pyTIMOgIGxhIG1vZGU="
b64EncodeUnicode('\n'); // "Cg=="

Base64 でエンコードされた値を元の文字列に戻すには、次のようにします。

function b64DecodeUnicode(str) {
    // 逆変換: バイナリー文字列から "%" エンコードへ、そしてオリジナルの文字列へ。
    return decodeURIComponent(atob(str).split('').map(function(c) {
        return '%' + ('00' + c.charCodeAt(0).toString(16)).slice(-2);
    }).join(''));
}

b64DecodeUnicode('4pyTIMOgIGxhIG1vZGU='); // "✓ à la mode"
b64DecodeUnicode('Cg=='); // "\n"

Unibabel は、この方法を使った共通の変換を実装しています。

方法 5 – DOM の atob() や btoa() を JavaScript の TypedArray と UTF-8 を使って書き換える

TextEncoder のポリフィル、例えば TextEncoding (レガシーの Windows、Mac、ISO のエンコーディングも含む) や TextEncoderLite を、モダンブラウザーと Node.js の両方で使える Buffer または base64-js や TypeScript 版の base64-js のような Base64 実装とを、組み合わせて使います。

ネイティブの TextEncoder 実装がない場合、最も軽量な方法は 方法 3 でしょう。なぜなら、とても高速であることに加え、方法 3 は標準状態の IE9 でも動作するからです。 もう一つの方法は、TextEncoderLite と base64-js を使うことです。可能な場合はブラウザーの実装を使ってください。

次の関数は、この考えを実装したものです。これは、base64-js が <script type="text/javascript" src="base64js.min.js"/> のようにインポートされていることを前提にしています。TextEncoderLite は UTF-8 でのみ機能することに注意してください。

function Base64Encode(str, encoding = 'utf-8') {
    var bytes = new (typeof TextEncoder === "undefined" ? TextEncoderLite : TextEncoder)(encoding).encode(str);        
    return base64js.fromByteArray(bytes);
}

function Base64Decode(str, encoding = 'utf-8') {
    var bytes = base64js.toByteArray(str);
    return new (typeof TextDecoder === "undefined" ? TextDecoderLite : TextDecoder)(encoding).decode(bytes);
}

Note: TextEncoderLite は、4 バイトの UTF-8 文字、つまり '\uD842\uDFB7' や '\u{20BB7}' のような文字を誤って解釈します。この Issue を参照してください。
あるいは、代わりに text-encoding を使ってください。

いくつかの場合には、UTF-8 に変換した後 Base64 にする上記の方法は、記憶領域に対してとても非効率的です。U+0800 から U+FFFF の範囲にある文字は、UTF-8 では 3 バイトにエンコードされますが UTF-16 では 2 バイトであり、これらがテキストの大部分を占める場合、UTF-8 の出力長は UTF-16 よりも長くなります。均等に分散した UTF-16 コードポイントを含む JavaScript 文字列の場合、Base64 の変換の前のエンコードを UTF-8 ではなく UTF-16 にすることで、サイズを 40% 減少できます。