導入
nsICryptoHash はデータの暗号化ハッシュ関数を計算するために使用することができます。例えば、ファイルの MD5 ハッシュを計算することができます。サポートされているハッシュアルゴリズムは MD2 と MD5, SHA-1, SHA-256, SHA-384 そして SHA-512 です。このインターフェースは Firefox 1.5 以上でのみ利用できます。
定数
ハッシュアルゴリズム
これらの定数はこのインターフェースでサポートされているハッシュアルゴリズムを表しています。利用可能な値は以下の通りです:
MD2MD5SHA1SHA512SHA256SHA384
メソッド
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() が呼ばれた後ではいつでも呼ばれるかもしれません。この呼び出しはオブジェクトを初期化する前の状態にリセットします。サンプルコード
ファイルのハッシュを計算する
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 進数文字列に変換しています。