Node.js v0.8.26 マニュアル & ドキュメンテーション


Table of Contents

Crypto#

Stability: 2 - Unstable; 将来のバージョンで API を変更することがが
議論されています。互換性を損なう変更は最小限です。後述します。

このモジュールにアクセスするには require('crypto') を使用します。

暗号化モジュールは下層のプラットフォームで OpenSSL が有効であることを 必要とします。 それは安全な HTTPS ネットワークや http コネクションの一部として使われる、 安全な認証情報をカプセル化する方法を提供します。

同時に OpenSSL のハッシュ、HMAC、暗号、復号、署名、そして検証へのラッパーを一式提供します。

crypto.createCredentials(details)#

認証情報オブジェクトを作成します。オプションの details は以下のキーを持つ辞書です:

  • pfx : PFX または PKCS12 でエンコードされた秘密鍵、証明書、および CA の 証明書を含む文字列またはバッファ。
  • key : PEM でエンコードされた秘密鍵を保持する文字列。
  • passphrase: 秘密鍵または pfx のパスフレーズ。
  • cert : PEM でエンコードされた証明書を保持する文字列。
  • ca : 信頼できる認証局の証明書が PEM でエンコードされた文字列または 文字列の配列。
  • crl : PEM でエンコードされた CRL (Certificate Revocation List、 失効した証明書の一覧) の文字列または文字列の配列。
  • ciphers: 使用または除外する暗号を記述した文字列。 詳細は http://www.openssl.org/docs/apps/ciphers.html#CIPHER_LIST_FORMAT を参照してください。

'ca' の詳細が与えられなかった場合、node.js はデフォルトとして

http://mxr.mozilla.org/mozilla/source/security/nss/lib/ckfw/builtins/certdata.txt で与えられる、信頼できる認証局の公開されたリストを使用します。

crypto.createHash(algorithm)#

ハッシュオブジェクトを生成して返します。 与えられたアルゴリズムによる暗号ハッシュ関数はダイジェストの生成に使われます。

algorithm は、プラットフォーム上の OpenSSL のバージョンでサポートされている利用可能なアルゴリズムに依存します。 例えば 'sha1''md5''sha256''sha512'、などです。 最近のリリースでは、openssl list-message-digest-algorithms で利用可能なダイジェストアルゴリズムが表示されます。

例: このプログラムはファイルのsha1ハッシュ値を求めます。

var filename = process.argv[2];
var crypto = require('crypto');
var fs = require('fs');

var shasum = crypto.createHash('sha1');

var s = fs.ReadStream(filename);
s.on('data', function(d) {
  shasum.update(d);
});

s.on('end', function() {
  var d = shasum.digest('hex');
  console.log(d + '  ' + filename);
});

Class: Hash#

データのハッシュダイジェストを作成するためのクラスです。

crypto.createHash() から返されます。

hash.update(data, [input_encoding])#

与えられた data でハッシュの内容を更新します。 そのエンコーディングは input_encoding で与えられ、'utf8''ascii'、 または 'binary' を指定することができます。 デフォルトは 'binary' です。 これは新しいデータがストリームに流される際に何度も呼び出されます。

hash.digest([encoding])#

渡された全てのデータがハッシュ化されたダイジェストを計算します。 encoding'hex''binary'、または 'base64' のいずれかです。 デフォルトは 'binary' です。

注意: digest() メソッドを呼び出した後で hash オブジェクトを使うことはできません。

crypto.createHmac(algorithm, key)#

与えられたアルゴリズムとキーで HMAC を計算する、HMAC オブジェクトを作成して返します。

algorithm は OpenSSL でサポートされているアルゴリズムに依存します - 前述の createHash を参照してください。

Class: Hmac#

hmac を作成するためのクラスです。

crypto.createHamc から返されます。

hmac.update(data)#

与えられた data で HMAC の内容を更新します。 これは新しいデータがストリームに流される際に何度も呼び出されます。

hmac.digest([encoding])#

渡された全てのデータが HMAC 化されたダイジェストを計算します。 encoding'hex''binary'、または 'base64' のいずれかです。 デフォルトは 'binary' です。

注意: digest() メソッドを呼び出した後で hmac オブジェクトを使うことはできません。

crypto.createCipher(algorithm, password)#

与えられたアルゴリズムとパスワードを使用する暗号オブジェクトを作成して返します。 algorithm は、OpenSSL に依存します。例えば 'aes192' などです。 最近のリリースでは、openssl list-cipher-algorithms で利用可能な暗号アルゴリズムが表示されます。 password はキーと IV の生成に使用されます。 これは 'binary' でエンコードされた文字列または buffer でなければなりません

crypto.createCipheriv(algorithm, key, iv)#

与えられたアルゴリズムとキーおよび IV を使用する暗号オブジェクトを作成して 返します。

algorithmcreateCipher() の引数と同じです。 key はアルゴリズムで使用される生のキーです。 ivinitialization vector です。

keyiv'binary' でエンコードされた文字列または buffers でなければなりません

Class: Cipher#

データを暗号化するためのクラスです。

crypto.createCipher および crypto.createCipheriv から返されます。

cipher.update(data, [input_encoding], [output_encoding])#

data で暗号を更新します。 input_encoding で与えられるエンコーディングは 'utf8''ascii''binary' のいずれかです。 デフォルトは 'binary' です。

output_encoding は暗号化されたデータの出力フォーマットを指定するもので、 'utf8''ascii' または 'binary' のいずれかです。 デフォルトは 'binary' です。

暗号化されたコンテンツが返されます。これは新しいデータがストリームに流される際に何度も呼び出されます。

cipher.final([output_encoding])#

暗号化されたコンテンツの残りを返します。 output_encoding は次のいずれかです: 'binary''base64' または 'hex'。 デフォルトは 'binary' です。

注意: final() メソッドを呼び出した後で cipher オブジェクトを使うことはできません。

cipher.setAutoPadding(auto_padding=true)#

入力データが自動的にブロックサイズにパディングされることを 抑止することができます。 auto_paddingfalse の場合、入力データ全体の長さは 暗号ブロックサイズの倍数でなければなりません。 でなければ、final() は失敗します。 これは非標準のパディング、たとえば PKCS パディングの代わりに 0x0 を使う場合に便利です。 cipher.final() の前に呼び出す必要があります。

crypto.createDecipher(algorithm, password)#

与えられたアルゴリズムとパスワードを使用する復号オブジェクトを作成して返します。 これは前述の createCipher() の鏡写しです。

crypto.createDecipheriv(algorithm, key, iv)#

与えられたアルゴリズムとキー、IV を使用する復号オブジェクトを作成して返します。 これは前述の createCipheriv() の鏡写しです。

Class: Decipher#

復号化のためのクラスです。

crypto.createDecipher および crypto.createDecipheriv から返されます。

decipher.update(data, [input_encoding], [output_encoding])#

'binary''base64' または 'hex' のいずれかでエンコードされた復号を data で更新します。デフォルトは 'binary' です。

output_decoding は復号化されたプレーンテキストのフォーマットを指定するもので、 'binary''ascii' あるいは 'utf8' のいずれかです。 デフォルトは 'binary' です。

decipher.final([output_encoding])#

復号化されたプレーンテキストの残りを返します。 output_decoding'binary''ascii' あるいは 'utf8' のいずれかです。 デフォルトは 'binary' です。

注意: final() メソッドを呼び出した後で decipher オブジェクトを使うことはできません。

decipher.setAutoPadding(auto_padding=true)#

データブロックが非標準のパディングで暗号化されている場合、 decipher.final() によるチェックを無効にすることができます。 入力データの長さが暗号ブロックサイズの倍数の場合のみ動作します。 decipher.update() の前に呼び出す必要があります。

crypto.createSign(algorithm)#

与えられたアルゴリズムで署名オブジェクトを作成して返します。 最近のOpenSSLのリリースでは、openssl list-public-key-algorithms で利用可能な署名アルゴリズムの一覧が表示されます。例えば 'RSA-SHA256'。

Class: Signer#

署名を作成するためのクラスです。

crypto.createSign から返されます。

signer.update(data)#

署名オブジェクトをデータで更新します。 これは新しいデータがストリームに流される際に何度も呼び出されます。

signer.sign(private_key, [output_format])#

署名オブジェクトに渡された全ての更新データで署名を計算します。 private_key は PEM でエンコードされた秘密鍵を内容とする文字列です。

'binary''hex'、あるいは 'base64' のいずれかを指定した output_format による署名を返します。デフォルトは 'binary' です。

注意: sign() メソッドを呼び出した後で signer オブジェクトを使うことはできません。

crypto.createVerify(algorithm)#

与えられたアルゴリズムで検証オブジェクトを作成して返します。これは前述の署名オブジェクトと鏡写しです。

Class: Verify#

署名を検証するためのクラスです。

crypto.createVerify から返されます。

verifier.update(data)#

検証オブジェクトをデータで更新します。 これは新しいデータがストリームに流される際に何度も呼び出されます。

verifier.verify(object, signature, [signature_format])#

署名されたデータを objectsignature で検証します。 object は RSA 公開鍵、DSA 公開鍵、X.509証明書のいずれかを PEM でエンコードしたオブジェクトです。 signature は先に計算したデータの署名で、 その signature_format'binary''hex'、または 'base64' のいずれかです。デフォルトは 'binary' です。

署名されたデータと公開鍵による検証の結果によって true または false を返します。

注意: verify() メソッドを呼び出した後で verifier オブジェクトを使うことはできません。

crypto.createDiffieHellman(prime_length)#

ディフィー・ヘルマン鍵共有オブジェクトを作成し、 与えられた長さの素数を生成します。生成元は 2 です。

crypto.createDiffieHellman(prime, [encoding])#

与えられた素数からディフィー・ヘルマン鍵共有オブジェクトを作成します。 生成元は 2 です。 エンコーディングは 'binary''hex'、または 'base64' のいずれかです。 デフォルトは 'binary' です。

Class: DiffieHellman#

ディフィー・ヘルマン鍵共有のためのクラスです。

crypto.creaateDiffieHellman から返されます。

diffieHellman.generateKeys([encoding])#

ディフィー・ヘルマン法で秘密および公開鍵を作成し、 指定の方法でエンコーディングされた公開鍵を返します。 この鍵は相手側に渡されるものです。 エンコーディングは 'binary''hex'、または 'base64' のいずれかです。 デフォルトは 'binary' です。

diffieHellman.computeSecret(other_public_key, [input_encoding], [output_encoding])#

other_public_key を相手側の公開鍵として共有の秘密鍵を計算して返します。 与えられた公開鍵は指定の input_encoding を使って解釈され、 秘密鍵は output_encoding で指定された方法でエンコードされます。 エンコーディングは 'binary''hex'、または 'base64' のいずれかです。 入力エンコーディングのデフォルトは 'binary' です。 出力のエンコーディングが与えられなかった場合は、入力のエンコーディングが 出力エンコーディングとして使われます。

diffieHellman.getPrime([encoding])#

ディフィー・ヘルマン法の素数を指定のエンコーディングで返します。 エンコーディングは 'binary''hex'、または 'base64' のいずれかです。 デフォルトは 'binary' です。

diffieHellman.getGenerator([encoding])#

ディフィー・ヘルマン法の生成元を指定のエンコーディングで返します。 エンコーディングは 'binary''hex'、または 'base64' のいずれかです。 デフォルトは 'binary' です。

diffieHellman.getPublicKey([encoding])#

ディフィー・ヘルマン法による公開鍵を指定のエンコーディングで返します。 エンコーディングは 'binary''hex'、または 'base64' のいずれかです。 デフォルトは 'binary' です。

diffieHellman.getPrivateKey([encoding])#

ディフィー・ヘルマン法による秘密鍵を指定のエンコーディングで返します。 エンコーディングは 'binary''hex'、または 'base64' のいずれかです。 デフォルトは 'binary' です。

diffieHellman.setPublicKey(public_key, [encoding])#

ディフィー・ヘルマン法による公開鍵を設定します。 鍵のエンコーディングは 'binary''hex'、または 'base64' のいずれかです。 デフォルトは 'binary' です。

diffieHellman.setPrivateKey(public_key, [encoding])#

ディフィー・ヘルマン法による秘密鍵を設定します。 鍵のエンコーディングは 'binary''hex'、または 'base64' のいずれかです。 デフォルトは 'binary' です。

crypto.getDiffieHellman(group_name)#

事前に定義された Diffie-Hellman 鍵交換オブジェクトを作成します。 サポートされるグループは、'modp1', 'modp2', 'modp5' (RFC 2412 で定義される)、 および 'modp14', 'modp15', 'modp16', 'modp17', 'modp18' (RFC 3526 で定義される) です。 返されるオブジェクトは、前述の crypto.createDiffieHellman() によって作成されたオブジェクトのインタフェースを模倣します。 しかし、 (たとえば diffieHellman.setPublicKey() で) 鍵を交換することはできません。 このルーチンを使うことによるアドバンテージは、 事前にグループ係数を生成することも交換する必要もないため、 処理と通信の時間を共に節約できることです。

例 (共有鍵を取得):

var crypto = require('crypto');
var alice = crypto.getDiffieHellman('modp5');
var bob = crypto.getDiffieHellman('modp5');

alice.generateKeys();
bob.generateKeys();

var alice_secret = alice.computeSecret(bob.getPublicKey(), 'binary', 'hex');
var bob_secret = bob.computeSecret(alice.getPublicKey(), 'binary', 'hex');

/* alice_secret and bob_secret should be the same */
console.log(alice_secret == bob_secret);

crypto.pbkdf2(password, salt, iterations, keylen, callback)#

疑似乱数を HMAC-SHA1 関数に適用して、与えられたパスワードと salt (ランダムなバイト値)、および繰り返しから、指定された長さの鍵を生成する、 非同期の PBKDF2 です。 コールバック関数は二つの引数を受け取る (err, derivedKey) です。

crypto.randomBytes(size, [callback])#

暗号学的に強い疑似乱数データを生成します。使用法:

// async
crypto.randomBytes(256, function(ex, buf) {
  if (ex) throw ex;
  console.log('Have %d bytes of random data: %s', buf.length, buf);
});

// sync
try {
  var buf = crypto.randomBytes(256);
  console.log('Have %d bytes of random data: %s', buf.length, buf);
} catch (ex) {
  // handle error
}

Proposed API Changes in Future Versions of Node#

Crypto モジュールは、統合されたストリーム API やバイトデータを扱う Buffer オブジェクトよりも先に Node に追加されました。

そのため、このストリーミングなクラスは他の Node のクラスに見られる 典型的なメソッドを持たず、多くのメソッドは引数や戻り値に Buffer ではなくバイナリエンコードされた文字列を使います。

将来のバージョンの Node では、Buffer がデフォルトのデータ型になります。 これはあるユースケースにおいては互換性を損ないますが、 全てのケースではありません。

たとえば、Sign クラスをデフォルト引数で使っていて、 その結果を全く調べずに Verify クラスに渡している場合、 それは以前と同じように動くでしょう。 それは、現時点ではバイナリ文字列を受け取ってそのバイナリ文字列を Veriy オブジェクトに渡しますが、将来は Buffer を受け取ってその Buffer を Verify オブジェクトに渡すようになります。

しかしながら、Buffer が文字列と正確に同じようには動かない何かをしている場合 (連結やデータの並べ替えなど)、あるいはバイナリ文字列を Crypto の関数に エンコーディング引数無しで渡している場合、エンコーディング引数を与えて どのエンコーディングを使用しているかを指定する必要があります。

同時に、ストリーミング API も提供されますが、それはレガシーな API を維持する方法でなされます。