Join MDN and developers like you at Mozilla's View Source conference, 12-14 September in Berlin, Germany. Learn more at https://viewsourceconf.org

nsICryptoHash

 

導入

nsICryptoHash はデータの暗号化ハッシュ関数を計算するために使用することができます。例えば、ファイルの MD5 ハッシュを計算することができます。サポートされているハッシュアルゴリズムは MD2 と MD5, SHA-1, SHA-256, SHA-384 そして SHA-512 です。このインターフェースは Firefox 1.5 以上でのみ利用できます。

Please add a summary to this article.
  最終更新: Gecko 1.8 (Firefox 1.5 / Thunderbird 1.5 / SeaMonkey 1.0)

定数

ハッシュアルゴリズム

これらの定数はこのインターフェースでサポートされているハッシュアルゴリズムを表しています。利用可能な値は以下の通りです:

  • MD2
  • MD5
  • SHA1
  • SHA512
  • SHA256
  • SHA384

メソッド

init

void init(in unsigned long aAlgorithm);

インタフェースで定義された定数の1つを指定してどのハッシュアルゴリズムを使用するか指示して、init() はオブジェクトを初期化します。どんなデータであれオブジェクトを更新する前にこのメソッドか initWithString() を呼ばなければなりません。

パラメタ

aAlgorithm

使用するハッシュアルゴリズム。インタフェースで定義されている定数の 1 つでなくてはなりません。
例外

NS_ERROR_INVALID_ARG

サポートされていないアルゴリズムの種類が渡されたことを示します。

initWithString

void initWithString(in ACString aAlgorithm);

initWithString()"MD5" のような文字列としてアルゴリズムの名前を指定することで、どのハッシュアルゴリズムを使用するか指定し、オブジェクトを初期化します。 どんなデータであれオブジェクトを更新する前にこのメソッドか init() を呼ばなければなりません。

パラメタ

aAlgorithm

使用するハッシュアルゴリズム
例外

NS_ERROR_INVALID_ARG

サポートされていないアルゴリズムの種類が渡されたことを示します。

update

void update([const, array, size_is(aLen)] in octet aData, in unsigned long aLen);

update() はハッシュを計算されるデータの配列をオブジェクトに追加します。このメソッドのを使った例は文字列のハッシュを計算するを参照してください。

パラメタ

aData

ハッシュを計算されるバッファ

aLen

aData バッファの長さ
例外

NS_ERROR_NOT_INITIALIZED

init()initWithString() が呼び出されていないことを表します。

updateFromStream

void updateFromStream(in nsIInputStream aStream, in unsigned long aLen);

updateFromStream()nsIInputStream からハッシュを計算されるデータを追加します。このメソッドのを使った例はファイルのハッシュを計算するを参照してください。

パラメタ

aStream

読み込まれる入力ストリーム

aLen

与えられた aStream をどれだけ読み込むか。PR_UINT32_MAX が渡されることは利用できる全てのデータがハッシュを更新するために使われることを示しています。
例外

NS_ERROR_NOT_INITIALIZED

init()initWithString() が呼び出されていないことを表します。NS_ERROR_NOT_AVAILABLE
ハッシュを計算するための要求された量のデータのが利用できないことを示しています。

finish

ACString finish(in PRBool aASCII);

finish() はハッシュオブジェクトを完成させ、実際のハッシュデータを生成します。

パラメタ

aASCII

もし true なら戻り値は base-64 エンコードされた文字列です。もし false なら戻り値にはバイナリデータです。
戻り値

このメソッドはオブジェクトから読み込まれたハッシュデータを返します。これはバイナリか base-64 エンコードされた文字列のどちらかが可能です。

例外

NS_ERROR_NOT_INITIALIZED

init()initWithString() が呼び出されていないことを表します。
注意: このメソッドは init() が呼ばれた後ではいつでも呼ばれるかもしれません。この呼び出しはオブジェクトを初期化する前の状態にリセットします。

サンプルコード

注意: 下のサンプルは Firefox 2 で実装された JavaScript 1.7 の機能を使っています。この例を Firefox 1.5 で使うには、配列内包をループに置き換えて下さい。

ファイルのハッシュを計算する

nsICryptoHash を使うと簡単にファイルのハッシュを計算することができます。nsICryptoHash のインスタンスを作り、ファイルから入力ストリームを開き、ファイルのハッシュを更新する必要があります。以下の例はファイルの MD5 ハッシュを計算する方法を示しています:

// 便宜上ここではハードコードしています。
var path = "c:\\windows\\notepad.exe";
var f = Components.classes["@mozilla.org/file/local;1"]
                  .createInstance(Components.interfaces.nsILocalFile);
f.initWithPath(path);
var istream = Components.classes["@mozilla.org/network/file-input-stream;1"]           
                        .createInstance(Components.interfaces.nsIFileInputStream);
// 読み出すためにストリームを開きます。
istream.init(f, 0x01, 0444, 0);
var ch = Components.classes["@mozilla.org/security/hash;1"]
                   .createInstance(Components.interfaces.nsICryptoHash);
// MD5 アルゴリズムを使います。
ch.init(ch.MD5);
// これはファイル全体を読む込むことを updateFromStream に指示します。
const PR_UINT32_MAX = 0xffffffff;
ch.updateFromStream(istream, PR_UINT32_MAX);
// ここで false を渡すとバイナリデータが戻ってきます
// true は base-64 文字列が戻ってきます
var hash = ch.finish(false);

// 1 バイトに対して 2 つの 16 進数コードを返す。
function toHexString(charCode)
{
  return ("0" + charCode.toString(16)).slice(-2);
}

// バイナリのハッシュデータを 16 進数文字列に変換する。
var s = Array.from(hash, (c, i) => toHexString(hash.charCodeAt(i))).join("");
// s は今 16 進数でハッシュを保持しています。

私の Windows XP SP2 システムでは、これはハッシュの値として 5eb63bbbe01eeed093cb22bb8f5acdc3 を返しましたが、 あなたのマイレージは違うかもしれません。単純ですがこの例はインターフェースの大部分の機能を示しました。

最初に注意すべきことは init() メソッドを呼んだときに、使うハッシュアルゴリズムを指定しなければならいないことです。利用可能なアルゴリズムの全てはインタフェースの定数として指定されています。

さらに注意すべきことは updateFromStream() メソッドを呼び出したとき、2 番目のパラメタは呼び出すバイト数であることがです。ここで PR_UINT32_MAX を渡すことでファイル全体を読み出したいことを要求します。

最後に finish() メソッドの呼び出しがハッシュ値を生成することに注意してください。このメソッドの 1 つのパラメタはこの例ではバイナリデータを返すために false です。true を渡すことで base 64 エンコードされた文字列としてハッシュを返します。この例ではバイナリデータを使い、ハッシュプログラムが通常出力するように結果を 16 進数文字列を生成しました。

文字列のハッシュを計算する

もう一つの一般的な操作は文字列のハッシュを計算することです。ハッシュ関数はバイトで計算するため、最初に文字列を nsIScriptableUnicodeConverter とあ指定した Unicode エンコーディングを使いバイトの並びに変換する必要があります。

注意: 異なるエンコーディングは異なるハッシュ値を生成します!もしあなたが結果を比較するなら、常に同じエンコーディングを使うべきです。

下の例では 文字列を UTF-8 エンコーディングでバイトに変換し、その MD5 ハッシュを計算する方法を示しています。前の例と同じように結果は 16 進数文字列として計算しました。

var str = "hello world";
var converter = Components.classes["@mozilla.org/intl/scriptableunicodeconverter"]
                          .createInstance(Components.interfaces.nsIScriptableUnicodeConverter);
// ここでは UTF-8 を使います。他のエンコーディングも選ぶこともできます。
converter.charset = "UTF-8";
// result は出力用パラメータです。
// result.value は配列の長さを保持します。
var result = {};
// data はバイトの配列です。
var data = converter.convertToByteArray(str, result);
var ch = Components.classes["@mozilla.org/security/hash;1"]
                   .createInstance(Components.interfaces.nsICryptoHash);
ch.init(ch.MD5);
ch.update(data, data.length);
var hash = ch.finish(false);

// 1 バイトに対して 2 つの 16 進数コードを返す。
function toHexString(charCode)
{
  return ("0" + charCode.toString(16)).slice(-2);
}

// バイナリのハッシュデータを 16 進数文字列に変換する。
var s = Array.from(hash, (c, i) => toHexString(hash.charCodeAt(i))).join("");
// 今 s はハッシュを 16 進数で保持しており、以下のようになるはずです。
// 5eb63bbbe01eeed093cb22bb8f5acdc3

この例では、ハッシュを計算されるバイトの配列を渡すために update() メソッドを使いました。先ほどの例と同じように、バイナリの結果を 16 進数文字列に変換しています。

ドキュメントのタグと貢献者

 このページの貢献者: arai, teoli, kazuyoshi, Taken
 最終更新者: arai,