穩(wěn)定性: 2 - 不穩(wěn)定; 正在討論未來版本的 API 改進,會盡量減少重大變化。詳見后文。
使用 require('crypto')
來訪問這個模塊。
加密模塊提供了 HTTP 或 HTTPS 連接過程中封裝安全憑證的方法。
它也提供了 OpenSSL 的哈希,hmac, 加密(cipher), 解密(decipher), 簽名(sign) 和 驗證(verify) 方法的封裝。
為某些/所有 OpenSSL 函數(shù)加載并設置引擎(根據(jù)參數(shù) flags 來設置)。
engine
可能是 id,或者是指向引擎共享庫的路徑。
flags
是可選參數(shù),默認值是ENGINE_METHOD_ALL
,它可以是以下一個或多個參數(shù)的組合(在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
返回支持的加密算法名數(shù)組。
例如:
var ciphers = crypto.getCiphers();
console.log(ciphers); // ['AES-128-CBC', 'AES-128-CBC-HMAC-SHA1', ...]
返回支持的哈希算法名數(shù)組。
例如:
var hashes = crypto.getHashes();
console.log(hashes); // ['sha', 'sha1', 'sha1WithRSAEncryption', ...]
穩(wěn)定性: 0 - 拋棄. 用 [tls.createSecureContext][] 替換.
根據(jù)參數(shù) details,創(chuàng)建一個加密憑證對象。參數(shù)為字典,key 包括:
pfx
: 字符串或者buffer對象,表示經PFX或PKCS12編碼產生的私鑰、證書以及CA證書key
: 進過 PEM 編碼的私鑰passphrase
: 私鑰或 pfx 的密碼cert
: PEM 編碼的證書ca
: 字符串或字符串數(shù)組,PEM 編碼的可信任的 CA 證書。crl
: 字符串或字符串數(shù)組,PEM 編碼的 CRLs(證書吊銷列表Certificate Revocation List)。ciphers
: 字符串,使用或者排除的加密算法。參見http://www.openssl.org/docs/apps/ciphers.html#CIPHER_LIST_FORMAT。如果沒有指定 'ca',Node.js將會使用下面列表中的CAhttp://mxr.mozilla.org/mozilla/source/security/nss/lib/ckfw/builtins/certdata.txt。
創(chuàng)建并返回一個哈希對象,使用指定的算法來生成哈希摘要。
參數(shù) algorithm
取決于平臺上 OpenSSL 版本所支持的算法。例如,'sha1'
, 'md5'
,
'sha256'
, 'sha512'
等等。在最近的版本中,openssllist-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);
});
用來生成數(shù)據(jù)的哈希值。
它是可讀寫的流 stream 。寫入的數(shù)據(jù)來用計算哈希值。當寫入流結束后,使用 read()
方法來獲取計算后的哈希值。也支持老的 update
和 digest
方法。
通過 crypto.createHash
返回。
根據(jù) data
來更新哈希內容,編碼方式根據(jù) input_encoding
來定,有 'utf8'
, 'ascii'
或
'binary'
。如果沒有傳入值,默認編碼方式是'binary'
。如果 data
是 Buffer
, input_encoding
將會被忽略。
因為它是流式數(shù)據(jù),所以可以使用不同的數(shù)據(jù)調用很多次。
計算傳入的數(shù)據(jù)的哈希摘要。encoding
可以是 'hex'
, 'binary'
或 'base64'
,如果沒有指定encoding
,將返回 buffer。
注意:調用 digest()
后不能再用 hash
對象。
創(chuàng)建并返回一個 hmac 對象,用指定的算法和秘鑰生成 hmac 圖譜。
它是可讀寫的流 stream 。寫入的數(shù)據(jù)來用計算 hmac。當寫入流結束后,使用 read()
方法來獲取計算后的值。也支持老的 update
和 digest
方法。
參數(shù) algorithm
取決于平臺上 OpenSSL 版本所支持的算法,參見前面的 createHash。key
是 hmac 算法中用的 key。
用來創(chuàng)建 hmac 加密圖譜。
通過 crypto.createHmac
返回。
根據(jù) data
更新 hmac 對象。因為它是流式數(shù)據(jù),所以可以使用新數(shù)據(jù)調用多次。
計算傳入數(shù)據(jù)的 hmac 值。encoding
可以是 'hex'
, 'binary'
或 'base64'
,如果沒有指定encoding
,將返回 buffer。
注意:調用 digest()
后不能再用 hmac
對象。
使用傳入的算法和秘鑰來生成并返回加密對象。
algorithm
取決于 OpenSSL,例如'aes192'
等。最近發(fā)布的版本中, openssl list-cipher-algorithms
將會展示可用的加密算法。password
用來派生 key 和 IV,它必須是一個'binary'
編碼的字符串或者一個buffer。
它是可讀寫的流 stream 。寫入的數(shù)據(jù)來用計算 hmac。當寫入流結束后,使用 read()
方法來獲取計算后的值。也支持老的update
和 digest
方法。
注意,OpenSSL 函數(shù)EVP_BytesToKey摘要算法如果是一次迭代(one iteration),無需鹽值(no salt)的 MD5 時, createCipher
為它派生秘鑰。缺少鹽值使得字典攻擊,相同的密碼總是生成相同的key,低迭代次數(shù)和非加密的哈希算法,使得密碼測試非常迅速。
OpenSSL推薦使用 pbkdf2 來替換 EVP_BytesToKey,推薦使用 crypto.pbkdf2 來派生 key 和 iv ,推薦使用 createCipheriv() 來創(chuàng)建加密流。
創(chuàng)建并返回一個加密對象,用指定的算法,key 和 iv。
algorithm
參數(shù)和 createCipher()
一致。key
在算法中用到.iv
是一個initialization vector.
key
和 iv
必須是 'binary'
的編碼字符串或buffers.
加密數(shù)據(jù)的類。.
通過 crypto.createCipher
和 crypto.createCipheriv
返回。
它是可讀寫的流 stream 。寫入的數(shù)據(jù)來用計算 hmac。當寫入流結束后,使用 read()
方法來獲取計算后的值。也支持老的update
和 digest
方法。
根據(jù) data
來更新哈希內容,編碼方式根據(jù) input_encoding
來定,有 'utf8'
, 'ascii'
or
'binary'
。如果沒有傳入值,默認編碼方式是'binary'
。如果data
是 Buffer
,input_encoding
將會被忽略。
output_encoding
指定了輸出的加密數(shù)據(jù)的編碼格式,它可用是 'binary'
, 'base64'
或 'hex'
。如果沒有提供編碼,將返回 buffer 。
返回加密后的內容,因為它是流式數(shù)據(jù),所以可以使用不同的數(shù)據(jù)調用很多次。
返回加密后的內容,編碼方式是由 output_encoding
指定,可以是 'binary'
, 'base64'
或 'hex'
。如果沒有傳入值,將返回 buffer。
注意:cipher
對象不能在 final()
方法之后調用。
你可以禁用輸入數(shù)據(jù)自動填充到塊大小的功能。如果 auto_padding
是false, 那么輸入數(shù)據(jù)的長度必須是加密器塊大小的整倍數(shù),否則 final
會失敗。這對非標準的填充很有用,例如使用0x0而不是PKCS的填充。這個函數(shù)必須在 cipher.final
之前調用。
加密認證模式(目前支持:GCM),這個方法返回經過計算的認證標志 Buffer
。必須使用final
方法完全加密后調用。
加密認證模式(目前支持:GCM),這個方法設置附加認證數(shù)據(jù)( AAD )。
根據(jù)傳入的算法和密鑰,創(chuàng)建并返回一個解密對象。這是 createCipher() 的鏡像。
根據(jù)傳入的算法,密鑰和 iv,創(chuàng)建并返回一個解密對象。這是 createCipheriv() 的鏡像。
解密數(shù)據(jù)類。
通過 crypto.createDecipher
和 crypto.createDecipheriv
返回。
解密對象是可讀寫的流 streams 。用寫入的加密數(shù)據(jù)生成可讀的純文本數(shù)據(jù)。也支持老的update
和 digest
方法。
使用參數(shù) data
更新需要解密的內容,其編碼方式是 'binary'
,'base64'
或 'hex'
。如果沒有指定編碼方式,則把 data
當成 buffer
對象。
如果 data
是 Buffer
,則忽略 input_encoding
參數(shù)。
參數(shù) output_decoding
指定返回文本的格式,是 'binary'
, 'ascii'
或 'utf8'
之一。如果沒有提供編碼格式,則返回 buffer。
返回剩余的解密過的內容,參數(shù) output_encoding
是 'binary'
, 'ascii'
或 'utf8'
,如果沒有指定編碼方式,返回 buffer。
注意,decipher
對象不能在 final()
方法之后使用。
如果加密的數(shù)據(jù)是非標準塊,可以禁止其自動填充,防止 decipher.final
檢查并移除。僅在輸入數(shù)據(jù)長度是加密塊長度的整數(shù)倍的時才有效。你必須在 decipher.update
前調用。
對于加密認證模式(目前支持:GCM),必須用這個方法來傳遞接收到的認證標志。如果沒有提供標志,或者密文被篡改,將會拋出 final
標志,認證失敗,密文會被拋棄,
對于加密認證模式(目前支持:GCM),用這個方法設置附加認證數(shù)據(jù)( AAD )。
根據(jù)傳入的算法創(chuàng)建并返回一個簽名數(shù)據(jù)。 OpenSSL 的最近版本里,openssl list-public-key-algorithms
會列出所有算法,比如'RSA-SHA256'
。
生成數(shù)字簽名的類。
通過 crypto.createSign
返回。
簽名對象是可讀寫的流 streams??蓪憯?shù)據(jù)用來生成簽名。當所有的數(shù)據(jù)寫完,sign
簽名方法會返回簽名。也支持老的 update
和 digest
方法。
用參數(shù) data
來更新簽名對象。因為是流式數(shù)據(jù),它可以被多次調用。
根據(jù)傳送給sign的數(shù)據(jù)來計算電子簽名。
private_key
可以是一個對象或者字符串。如果是字符串,將會被當做沒有密碼的key。
private_key
:
key
: 包含 PEM 編碼的私鑰passphrase
: 私鑰的密碼返回值output_format
包含數(shù)字簽名, 格式是 'binary'
,'hex'
或 'base64'
之一。如果沒有指定 encoding
,將返回 buffer。
注意:sign
對象不能在 sign()
方法之后調用。
根據(jù)傳入的算法,創(chuàng)建并返回驗證對象。是簽名對象(signing object)的鏡像。
用來驗證簽名的類。
通過 crypto.createVerify
返回。
是可寫流 streams??蓪憯?shù)據(jù)用來驗證簽名。一旦所有數(shù)據(jù)寫完后,如簽名正確 verify
方法會返回 true
。
也支持老的 update
方法。
用參數(shù) data
來更新驗證對象。因為是流式數(shù)據(jù),它可以被多次調用。
使用 object
和 signature
驗證簽名數(shù)據(jù)。參數(shù) object
是包含了 PEM 編碼對象的字符串,它可以是 RSA 公鑰, DSA 公鑰, 或 X.509 證書。signature
是之前計算出來的數(shù)字簽名。signature_format
可以是 'binary'
, 'hex'
或 'base64'
之一,如果沒有指定編碼方式 ,則默認是buffer 對象。
根據(jù)數(shù)據(jù)和公鑰驗證簽名有效性,來返回 true 或 false。
注意:verifier
對象不能在 verify()
方法之后調用。
創(chuàng)建一個 Diffie-Hellman 密鑰交換(Diffie-Hellman key exchange)對象,并根據(jù)給定的位長度生成一個質數(shù)。如果沒有指定參數(shù) generator
,默認為 2
。
使用傳入的 prime
和 generator
創(chuàng)建 Diffie-Hellman 秘鑰交互對象。
generator
可以是數(shù)字,字符串或Buffer。
如果沒有指定 generator
,使用 2
.
prime_encoding
和 generator_encoding
可以是 'binary'
, 'hex'
, 或 'base64'
。
如果沒有指定 prime_encoding
, 則 Buffer 為 prime
。
如果沒有指定 generator_encoding
,則 Buffer 為 generator
。
創(chuàng)建 Diffie-Hellman 秘鑰交換的類。
通過 crypto.createDiffieHellman
返回。
在初始化的時候,如果有警告或錯誤,將會反應到這。它是以下值(定義在 constants
模塊):
DH_CHECK_P_NOT_SAFE_PRIME
DH_CHECK_P_NOT_PRIME
DH_UNABLE_TO_CHECK_GENERATOR
DH_NOT_SUITABLE_GENERATOR
生成秘鑰和公鑰,并返回指定格式的公鑰。這個值必須傳給其他部分。編碼方式: 'binary'
, 'hex'
,
或 'base64'
。如果沒有指定編碼方式,將返回 buffer。
使用 other_public_key
作為第三方公鑰來計算并返回共享秘密(shared secret)。秘鑰用input_encoding
編碼。編碼方式為:'binary'
, 'hex'
, 或 'base64'
。如果沒有指定編碼方式 ,默認為 buffer。
如果沒有指定返回編碼方式,將返回 buffer。
用參數(shù) encoding 指明的編碼方式返回 Diffie-Hellman 質數(shù),編碼方式為: 'binary'
, 'hex'
, 或 'base64'
。 如果沒有指定編碼方式,將返回 buffer。
用參數(shù) encoding 指明的編碼方式返回 Diffie-Hellman 生成器,編碼方式為: 'binary'
, 'hex'
, 或 'base64'
. 如果沒有指定編碼方式 ,將返回 buffer。
用參數(shù) encoding 指明的編碼方式返回 Diffie-Hellman 公鑰,編碼方式為: 'binary'
, 'hex'
, 或 'base64'
. 如果沒有指定編碼方式 ,將返回 buffer。
用參數(shù) encoding 指明的編碼方式返回 Diffie-Hellman 私鑰,編碼方式為: 'binary'
, 'hex'
, 或 'base64'
. 如果沒有指定編碼方式 ,將返回 buffer。
設置 Diffie-Hellman 的公鑰,編碼方式為: 'binary'
, 'hex'
, 或 'base64'
,如果沒有指定編碼方式 ,默認為 buffer。
設置 Diffie-Hellman 的私鑰,編碼方式為: 'binary'
, 'hex'
, 或 'base64'
,如果沒有指定編碼方式 ,默認為 buffer。
創(chuàng)建一個預定義的 Diffie-Hellman 秘鑰交換對象。支持的組: 'modp1'
, 'modp2'
, 'modp5'
(定義于RFC 2412) and 'modp14'
, 'modp15'
, 'modp16'
, 'modp17'
,'modp18'
(定義于RFC 3526). 返回對象模仿了上述創(chuàng)建的crypto.createDiffieHellman()對象,但是不允許修改秘鑰交換(例如,diffieHellman.setPublicKey())。使用這套流程的好處是,雙方不需要生成或交換組組余數(shù),節(jié)省了計算和通訊時間。
例如 (獲取一個共享秘密):
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);
使用傳入的參數(shù) curve_name
,創(chuàng)建一個 Elliptic Curve (EC) Diffie-Hellman 秘鑰交換對象。
這個類用來創(chuàng)建 EC Diffie-Hellman 秘鑰交換。
通過 crypto.createECDH
返回。
生成 EC Diffie-Hellman 的秘鑰和公鑰,并返回指定格式和編碼的公鑰,它會傳遞給第三方。
參數(shù) format
是 'compressed'
, 'uncompressed'
, 或 'hybrid'
. 如果沒有指定,將返回'uncompressed'
格式.
參數(shù)encoding
是 'binary'
, 'hex'
, 或 'base64'
. 如果沒有指定編碼方式 ,將返回 buffer。
以other_public_key
作為第三方公鑰計算共享秘密,并返回。秘鑰會以input_encoding
來解讀。編碼是:'binary'
, 'hex'
, 或 'base64'
。如果沒有指定編碼方式 ,默認為 buffer。
如果沒有指定編碼方式 ,將返回 buffer。
用參數(shù) encoding 指明的編碼方式返回 EC Diffie-Hellman 公鑰,編碼方式為: 'compressed'
, 'uncompressed'
, 或
'hybrid'
. 如果沒有指定編碼方式 ,將返回'uncompressed'
。
編碼是:'binary'
, 'hex'
, 或 'base64'
。如果沒有指定編碼方式 ,默認為 buffer。
用參數(shù) encoding 指明的編碼方式返回 EC Diffie-Hellman 私鑰,編碼是:'binary'
, 'hex'
, 或 'base64'
。如果沒有指定編碼方式 ,默認為 buffer。
設置 EC Diffie-Hellman 的公鑰,編碼方式為: 'binary'
, 'hex'
, 或 'base64'
,如果沒有指定編碼方式 ,默認為 buffer。
設置 EC Diffie-Hellman 的私鑰,編碼方式為: 'binary'
, 'hex'
, 或 'base64'
,如果沒有指定編碼方式 ,默認為 buffer。
例如 (包含一個共享秘密):
var crypto = require('crypto');
var alice = crypto.createECDH('secp256k1');
var bob = crypto.createECDH('secp256k1');
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);
異步 PBKDF2 提供了一個偽隨機函數(shù) HMAC-SHA1,根據(jù)給定密碼的長度,salt 和 iterations 來得出一個密鑰。回調函數(shù)得到兩個參數(shù) (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() 里有支持的摘要函數(shù)列表。
異步 PBKDF2 函數(shù). 返回 derivedKey 或拋出錯誤。
生成一個密碼強度隨機的數(shù)據(jù):
// 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
}
注意:如果沒有足夠積累的熵來生成隨機強度的密碼,將會拋出錯誤,或調用回調函數(shù)返回錯誤。換句話說,沒有回調函數(shù)的 crypto.randomBytes
不會阻塞,即使耗盡所有的熵。
生成非密碼學強度的偽隨機數(shù)據(jù)。如果數(shù)據(jù)足夠長會返回一個唯一數(shù)據(jù),但是這個數(shù)可能是可以預期的。因此,當不可預期很重要的時候,不要用這個函數(shù)。例如,在生成加密的秘鑰時。
用法和 crypto.randomBytes
相同。
這個類和簽過名的公鑰打交道。最重要的場景是處理 <keygen>
元素,http://www.openssl.org/docs/apps/spkac.html。
通過 crypto.Certificate
返回.
根據(jù) SPKAC 返回 true 或 false。
根據(jù)提供的SPKAC,返回加密的公鑰。
輸出和 SPKAC 關聯(lián)的編碼 challenge。
使用 public_key
加密 buffer
。目前僅支持 RSA。
public_key
可以是對象或字符串。如果 public_key
是一個字符串,將會當做沒有密碼的key,并會用RSA_PKCS1_OAEP_PADDING
。
public_key
:
key
: 包含有 PEM 編碼的私鑰。padding
: 填充值,如下
constants.RSA_NO_PADDING
constants.RSA_PKCS1_PADDING
constants.RSA_PKCS1_OAEP_PADDING
注意: 所有的填充值 定義于constants
模塊.
使用 private_key
來解密 buffer
.
private_key
:
key
: 包含有 PEM 編碼的私鑰passphrase
: 私鑰的密碼padding
: 填充值,如下:
constants.RSA_NO_PADDING
constants.RSA_PKCS1_PADDING
constants.RSA_PKCS1_OAEP_PADDING
注意: 所有的填充值 定義于constants
模塊.
函數(shù)所用的編碼方式可以是字符串或 buffer ,默認值是 'buffer'。這是為了加密模塊兼容默認 'binary' 為編碼方式的遺留程序。
注意,新程序希望用 buffer 對象,所以這是暫時手段。
在統(tǒng)一的流 API 概念出現(xiàn)前,在引入 Buffer 對象來處理二進制數(shù)據(jù)之前,Crypto 模塊就已經添加到 Node。
因此,流相關的類里沒有其他的 Node 類里的典型方法,并且很多方法接收并返回二級制編碼的字符串,而不是 Buffers。在最近的版本中,這些函數(shù)改成默認使用 Buffers。
對于一些場景來說這是重大變化。
例如,如果你使用默認參數(shù)給簽名類,將結果返回給認證類,中間沒有驗證數(shù)據(jù),程序會正常工作。之前你會得到二進制編碼的字符串,并傳遞給驗證類,現(xiàn)在則是 Buffer。
如果你之前使用的字符串數(shù)據(jù)在 Buffers 對象不能正常工作(比如,連接數(shù)據(jù),并存儲在數(shù)據(jù)庫里 )。或者你傳遞了二進制字符串給加密函數(shù),但是沒有指定編碼方式,現(xiàn)在就需要提供編碼參數(shù)。如果想切換回原來的風格,將 crypto.DEFAULT_ENCODING
設置為 'binary'。注意,新的程序希望是 buffers,所以之前的方法只能作為臨時的辦法。