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

Index | View on single page | View as JSON

Crypto

Crypto#

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

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

暗号化モジュールは安全な HTTPS ネットワークや http コネクションの一部として使われる、安全な認証情報をカプセル化する方法を提供します。

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

crypto.setEngine(engine, [flags])#

一部または全ての OpenSSL 関数のために、エンジンをロードまたは設定します (フラグによって選択されます)。

engine は id か、エンジンの共有ライブラリへのパスかのいずれかです。

flags はオプションで、デフォルトは ENGINE_METHOD_ALL です。以下のフラグから一つまたは組み合わせを指定することが出来ます (constants モジュールに定義されています)。

ENGINE_METHOD_RSA
ENGINE_METHOD_DSA
ENGINE_METHOD_DH
ENGINE_METHOD_RAND
ENGINE_METHOD_ECDH
ENGINE_METHOD_ECDSA
ENGINE_METHOD_CIPHERS
ENGINE_METHOD_DIGESTS
ENGINE_METHOD_STORE
ENGINE_METHOD_PKEY_METH
ENGINE_METHOD_PKEY_ASN1_METH
ENGINE_METHOD_ALL
ENGINE_METHOD_NONE

crypto.getCiphers()#

サポートされている暗号の名前からなる配列を返します。

例:

var ciphers = crypto.getCiphers();
console.log(ciphers); // ['AES-128-CBC', 'AES-128-CBC-HMAC-SHA1', ...]

crypto.getHashes()#

サポートされているハッシュアルゴリズムの名前からなる配列を返します。

var hashes = crypto.getHashes();
console.log(hashes); // ['sha', 'sha1', 'sha1WithRSAEncryption', ...]

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#

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

これは読み込みと書き込みの両方が可能なストリームです。書き込まれたデータはハッシュを計算するために使われます。一度ストリームの書き込み側が閉じられると、計算されたハッシュダイジェストを読み出すために read() メソッドを使うことができます。レガシーな update() および digest() メソッドもサポートされます。

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

hash.update(data, [input_encoding])#

与えられた data でハッシュの内容を更新します。そのエンコーディングは input_encoding で与えられ、'utf8'、'ascii'、または 'binary' を指定することができます。入力が文字列でエンコーディングが与えられなかった場合、エンコーディングは 'binary' が強制されます。もし data が Buffer なら、input_encoding は無視されます。

これは新しいデータがストリームに流される際に何度も呼び出されます。

hash.digest([encoding])#

渡された全てのデータがハッシュ化されたダイジェストを計算します。 encoding は 'hex'、'binary'、または 'base64' のいずれかです。エンコーディングが与えられなかった場合はバッファが返されます。

注意: 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' のいずれかです。エンコーディングが与えられなかった場合はバッファが返されます。

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

crypto.createCipher(algorithm, password)#

与えられたアルゴリズムとパスワードを使用する暗号オブジェクトを作成して返します。

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

crypto.createCipheriv(algorithm, key, iv)#

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

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

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

Class: Cipher#

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

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

暗号化オブジェクトは読み込みと書き込みの両方が可能なストリームです。書き込まれたプレーンテキストデータは、読み込み側に暗号化されたデータを生成するために使われます。レガシーな update() および final() メソッドもサポートされます。

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

data で暗号を更新します。 input_encoding で与えられるエンコーディングは 'utf8'、'ascii'、'binary' のいずれかです。エンコーディングが与えられなかった場合はバッファが期待されます。もし data が Buffer なら、input_encoding は無視されます。

The output_encoding specifies the output format of the enciphered data, and can be 'binary', 'base64' or 'hex'. If no encoding is provided, then a buffer is returned. -->

output_encoding は暗号化されたデータの出力フォーマットを指定するもので、 'utf8'、'ascii' または 'binary' のいずれかです。エンコーディングが与えられなかった場合はバッファが返されます。

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

cipher.final([output_encoding])#

暗号化されたコンテンツの残りを返します。 output_encoding は次のいずれかです: 'binary'、'base64' または 'hex'。エンコーディングが与えられなかった場合はバッファが返されます。

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

cipher.setAutoPadding(auto_padding=true)#

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

cipher.getAuthTag()#

認証された暗号モード (現在サポートされているもの: GCM) では、このメソッドは与えられたデータから計算された 認証タグ を表現する Buffer を返します。 final() メソッドを使った暗号化が完了した後に呼び出されるべきです！

crypto.createDecipher(algorithm, password)#

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

crypto.createDecipheriv(algorithm, key, iv)#

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

Class: Decipher#

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

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

復号化オブジェクトは読み込みと書き込みの両方が可能なストリームです。書き込まれた暗号化データは、読み込み側にプレーンテキストデータを生成するために使われます。レガシーな update() および final() メソッドもサポートされます。

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

'binary'、'base64' または 'hex' のいずれかでエンコードされた復号を data で更新します。エンコーディングが与えられなかった場合はバッファが期待されます。もし data が Buffer なら、input_encoding は無視されます。

output_decoding は復号化されたプレーンテキストのフォーマットを指定するもので、 'binary'、'ascii' あるいは 'utf8' のいずれかです。エンコーディングが与えられなかった場合はバッファが返されます。

decipher.final([output_encoding])#

復号化されたプレーンテキストの残りを返します。 output_decoding は 'binary'、'ascii' あるいは 'utf8' のいずれかです。エンコーディングが与えられなかった場合はバッファが返されます。

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

decipher.setAutoPadding(auto_padding=true)#

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

decipher.setAuthTag(buffer)#

認証された暗号モード (現在サポートされているもの: GCM) に対して、このメソッドは受け取った認証タグを渡すために使われなければなりません。タグが提供されなかった場合や暗号文が改竄された場合は、 final がスローされ、その暗号文は認証が失敗したために破棄されなければならないことが示されます。

crypto.createSign(algorithm)#

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

Class: Sign#

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

crypto.createSign から返されます。

署名オブジェクトは書き込み可能なストリームです。書き込まれたデータは署名を生成するために使われます。全てのデータが書き込まれると、sign() メソッドはその署名を返します。レガシーな update() メソッドもサポートされます。

sign.update(data)#

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

sign.sign(private_key, [output_format])#

署名オブジェクトに渡された全ての更新データで署名を計算します。

private_key はオブジェクトまたは文字列です。 private_key が文字列なら、それはパスフレーズのない鍵とみなされます。

private_key:

key : PEM でエンコードされた秘密鍵を保持する文字列
passphrase : 秘密鍵のパスフレーズを表す文字列

'binary'、'hex'、あるいは 'base64' のいずれかを指定した output_format による署名を返します。エンコーディングが与えられなかった場合はバッファが返されます。

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

crypto.createVerify(algorithm)#

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

Class: Verify#

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

crypto.createVerify から返されます。

検証オブジェクトは書き込み可能なストリームです。書き込まれたデータは与えられた署名を検証するために使われます。全てのデータが書き込まれると、verify() メソッドは与えられた署名が正しければ true を返します。レガシーな update() メソッドもサポートされます。

verifier.update(data)#

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

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

署名されたデータを object と signature で検証します。 object は RSA 公開鍵、DSA 公開鍵、X.509証明書のいずれかを PEM でエンコードしたオブジェクトです。 signature は先に計算したデータの署名で、その signature_format は 'binary'、'hex'、または 'base64' のいずれかです。エンコーディングが与えられなかった場合はバッファが期待されます。

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

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

crypto.createDiffieHellman(prime_length)#

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

crypto.createDiffieHellman(prime, [encoding])#

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

Class: DiffieHellman#

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

crypto.creaateDiffieHellman から返されます。

diffieHellman.generateKeys([encoding])#

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

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

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

出力のエンコーディングが与えられなかった場合はバッファが返されます。

diffieHellman.getPrime([encoding])#

ディフィー・ヘルマン法の素数を指定のエンコーディングで返します。エンコーディングは 'binary'、'hex'、または 'base64' のいずれかです。エンコーディングが与えられなかった場合はバッファが返されます。

diffieHellman.getGenerator([encoding])#

ディフィー・ヘルマン法の生成元を指定のエンコーディングで返します。エンコーディングは 'binary'、'hex'、または 'base64' のいずれかです。エンコーディングが与えられなかった場合はバッファが返されます。

diffieHellman.getPublicKey([encoding])#

ディフィー・ヘルマン法による公開鍵を指定のエンコーディングで返します。エンコーディングは 'binary'、'hex'、または 'base64' のいずれかです。エンコーディングが与えられなかった場合はバッファが返されます。

diffieHellman.getPrivateKey([encoding])#

ディフィー・ヘルマン法による秘密鍵を指定のエンコーディングで返します。エンコーディングは 'binary'、'hex'、または 'base64' のいずれかです。エンコーディングが与えられなかった場合はバッファが返されます。

diffieHellman.setPublicKey(public_key, [encoding])#

ディフィー・ヘルマン法による公開鍵を設定します。鍵のエンコーディングは 'binary'、'hex'、または 'base64' のいずれかです。エンコーディングが与えられなかった場合はバッファが期待されます。

diffieHellman.setPrivateKey(private_key, [encoding])#

ディフィー・ヘルマン法による秘密鍵を設定します。鍵のエンコーディングは 'binary'、'hex'、または 'base64' のいずれかです。エンコーディングが与えられなかった場合はバッファが期待されます。

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(), null, 'hex');
var bob_secret = bob.computeSecret(alice.getPublicKey(), null, 'hex');

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

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

非同期の PBKDF2 関数です。選択された HMAC ダイジェスト関数 (デフォルト: SHA1) を適用して、要求されたパスワード、salt、および繰り返しの数から、指定された長さの鍵を生成します。コールバック関数は二つの引数を受け取ります: (err, derivedKey)

例:

crypto.pbkdf2('secret', 'salt', 4096, 512, 'sha256', function(err, key) {
  if (err)
    throw err;
  console.log(key.toString('hex'));  // 'c5e478d...1469e50'
});

crypto.getHashes() からサポートされるダイジェスト関数の一覧を得ることが出来ます。

crypto.pbkdf2Sync(password, salt, iterations, keylen, [digest])#

同期版の PBKDF2 関数。生成された鍵を返すか、例外をスローします。

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
  // most likely, entropy sources are drained
}

注意: もし暗号理論的に強いデータを生成するために十分な累積エントロピーがなければ、エラーがスローされるか、エラーと共にコールバックが呼ばれます。言い換えると、コールバックを渡さずに crypto.randomBytes() を呼び出しても、全てのエントロピー源が枯渇するまでブロックするわけではありません。

crypto.pseudoRandomBytes(size, [callback])#

暗号理論的ではない、強い疑似乱数データを生成します。返されるデータは十分に長ければユニークですが、必ずしも予測不可能ではありません。この理由のため、この関数の出力を暗号化キーの生成など、予測不可能であることが重要なところでは決して使用しないでください。

他の使い方は crypto.randomBytes と同じです。

Class: Certificate#

このクラスは「signed public key & challenges (SPKAC)」のために使われます。この一連の関数の主な用途は、<keygen> 要素の取り扱いです。 http://www.openssl.org/docs/apps/spkac.html

crypto.Certificate を返します。

Certificate.verifySpkac(spkac)#

妥当なSPKAC かどうかを true または false で返します。

Certificate.exportChallenge(spkac)#

与えられた SPKAC からエンコードされた公開鍵を取り出します。

Certificate.exportPublicKey(spkac)#

与えられた SPKAC からエンコードされたチャレンジを取り出します。

crypto.DEFAULT_ENCODING#

関数が使用するエンコーディングのデフォルトは、文字列かバッファのいずれかにすることができます。

新しいプログラムはおそらくバッファを期待することに注意してください。これは一時的な手段としてのみ使用してください。

Recent API Changes#

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

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

これはあるユースケースにおいては互換性を損ないますが、全てのケースではありません。

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

しかしながら、Buffer が文字列と正確に同じようには動かない何かをしている場合 (例えば、それらを連結したり、データベースに保存したりするなど)、あるいはバイナリ文字列を Crypto の関数にエンコーディング引数無しで渡している場合、エンコーディング引数を与えてどのエンコーディングを使用しているかを指定する必要があります。以前のようにデフォルトでバイナリ文字列を使うように切り替えるには、 crypto.DEFAULT_ENCODING フィールドに binary を設定します。新しいプログラムはおそらくバッファを期待することに注意してください。これは一時的な手段としてのみ使用してください。

Table of Contents