穩(wěn)定性: 2 - 不穩(wěn)定; 正在討論未來版本的 API 改進,會盡量減少重大變化。詳見后文。
顧名思義,Node.js加密模塊允許你使用加密的功能,Node.js加密模塊通過使用require('crypto')
來訪問。
Node.js加密模塊提供了HTTP或HTTPS連接過程中封裝安全憑證的方法。
Node.js加密模塊還提供了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對象,表示經(jīng)PFX或PKCS12編碼產(chǎn)生的私鑰、證書以及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);
});
Hase用來生成數(shù)據(jù)的哈希值。
它是可讀寫的流stream。寫入的數(shù)據(jù)來用計算哈希值。當寫入流結(jié)束后,使用read()
方法來獲取計算后的哈希值。也支持舊的update
和digest
方法。
通過crypto.createHash
返回。
根據(jù)data
來更新哈希內(nèi)容,編碼方式根據(jù)input_encoding
來定,有'utf8'
、'ascii'
或'binary'
。如果沒有傳入值,默認編碼方式是'binary'
。如果 data
是Buffer
,則input_encoding
將會被忽略。
因為它是流式數(shù)據(jù),所以可以使用不同的數(shù)據(jù)調(diào)用很多次。
計算傳入的數(shù)據(jù)的哈希摘要。
encoding
可以是'hex'
、'binary'
或'base64'
,如果沒有指定encoding
,將返回buffer。
注意:調(diào)用digest()
后不能再用hash
對象。
創(chuàng)建并返回一個hmac對象,用指定的算法和秘鑰生成hmac圖譜。
它是可讀寫的流stream。寫入的數(shù)據(jù)來用計算hmac。當寫入流結(jié)束后,使用read()
方法來獲取計算后的值。也支持舊的update
和digest
方法。
參數(shù)algorithm
取決于平臺上OpenSSL版本所支持的算法,參見前面的createHash。key
是hmac算法中用的key。
用來創(chuàng)建hmac加密圖譜。
通過crypto.createHmac
返回。
根據(jù)data
更新hmac對象。因為它是流式數(shù)據(jù),所以可以使用新數(shù)據(jù)調(diào)用多次。
計算傳入數(shù)據(jù)的hmac值。encoding
可以是'hex'
、'binary'
或'base64'
,如果沒有指定encoding
,將返回buffer。
注意:調(diào)用digest()
后不能再用hmac
對象。
使用傳入的算法和秘鑰來生成并返回加密對象。
algorithm
取決于OpenSSL,例如'aes192'
等。最近發(fā)布的版本中,openssl list-cipher-algorithms
將會展示可用的加密算法。password
用來派生key 和IV,它必須是一個'binary'
編碼的字符串或者一個buffer。
它是可讀寫的stream流。寫入的數(shù)據(jù)來用計算hmac。當寫入流結(jié)束后,使用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。當寫入流結(jié)束后,使用read()
方法來獲取計算后的值。也支持舊的update
和digest
方法。
根據(jù)data
來更新哈希內(nèi)容,編碼方式根據(jù)input_encoding
來定,有'utf8'
、'ascii'
或者'binary'
。如果沒有傳入值,默認編碼方式是'binary'
。如果data
是Buffer
,input_encoding
將會被忽略。
output_encoding
指定了輸出的加密數(shù)據(jù)的編碼格式,它可用是'binary'
、'base64'
或'hex'
。如果沒有提供編碼,將返回buffer。
返回加密后的內(nèi)容,因為它是流式數(shù)據(jù),所以可以使用不同的數(shù)據(jù)調(diào)用很多次。
返回加密后的內(nèi)容,編碼方式是由output_encoding
指定,可以是'binary'
、'base64'
或'hex'
。如果沒有傳入值,將返回buffer。
注意:cipher
對象不能在final()
方法之后調(diào)用。
你可以禁用輸入數(shù)據(jù)自動填充到塊大小的功能。如果auto_padding
是false, 那么輸入數(shù)據(jù)的長度必須是加密器塊大小的整倍數(shù),否則final
會失敗。這對非標準的填充很有用,例如使用0x0而不是PKCS的填充。這個函數(shù)必須在cipher.final
之前調(diào)用。
加密認證模式(目前支持:GCM),這個方法返回經(jīng)過計算的認證標志Buffer
。必須使用final
方法完全加密后調(diào)用。
加密認證模式(目前支持: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
更新需要解密的內(nèi)容,其編碼方式是'binary'
、'base64'
或'hex'
。如果沒有指定編碼方式,則把data
當成buffer
對象。
如果data
是Buffer
,則忽略input_encoding
參數(shù)。
參數(shù)output_decoding
指定返回文本的格式,是'binary'
、'ascii'
或'utf8'
之一。如果沒有提供編碼格式,則返回buffer。
返回剩余的解密過的內(nèi)容,參數(shù)output_encoding
是'binary'
、'ascii'
或'utf8'
,如果沒有指定編碼方式,返回buffer。
注意:decipher
對象不能在final()
方法之后使用。
如果加密的數(shù)據(jù)是非標準塊,可以禁止其自動填充,防止decipher.final
檢查并移除。僅在輸入數(shù)據(jù)長度是加密塊長度的整數(shù)倍的時才有效。你必須在 decipher.update
前調(diào)用。
對于加密認證模式(目前支持: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ù),它可以被多次調(diào)用。
根據(jù)傳送給sign的數(shù)據(jù)來計算電子簽名。
private_key
可以是一個對象或者字符串。如果是字符串,將會被當做沒有密碼的key。
private_key
:
key
: 包含 PEM 編碼的私鑰passphrase
: 私鑰的密碼返回值output_format
包含數(shù)字簽名, 格式是'binary'
、'hex'
或'base64'
之一。如果沒有指定encoding
,將返回buffer。
注意:sign
對象不能在sign()
方法之后調(diào)用。
根據(jù)傳入的算法,創(chuàng)建并返回驗證對象。是簽名對象(signing object)的鏡像。
用來驗證簽名的類。
通過crypto.createVerify
返回。
是可寫streams流??蓪憯?shù)據(jù)用來驗證簽名。一旦所有數(shù)據(jù)寫完后,如簽名正確verify
方法會返回true
。
也支持老的update
方法。
用參數(shù)data
來更新驗證對象。因為是流式數(shù)據(jù),它可以被多次調(diào)用。
使用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()
方法之后調(diào)用。
創(chuàng)建一個Diffie-Hellman密鑰交換(Diffie-Hellman key exchange)對象,并根據(jù)給定的位長度生成一個質(zhì)數(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質(zhì)數(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),并且'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來得出一個密鑰?;卣{(diào)函數(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
}
注意:如果沒有足夠積累的熵來生成隨機強度的密碼,將會拋出錯誤,或調(diào)用回調(diào)函數(shù)返回錯誤。換句話說,沒有回調(diào)函數(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模塊就已經(jīng)添加到Node。
因此,流相關的類里沒有其他的Node類里的典型方法,并且很多方法接收并返回二級制編碼的字符串,而不是Buffers。在最近的版本中,這些函數(shù)改成默認使用 Buffers。
對于一些場景來說這是重大變化。
例如,如果你使用默認參數(shù)給簽名類,將結(jié)果返回給認證類,中間沒有驗證數(shù)據(jù),程序會正常工作。之前你會得到二進制編碼的字符串,并傳遞給驗證類,現(xiàn)在則是 Buffer。
如果你之前使用的字符串數(shù)據(jù)在Buffers對象不能正常工作(比如,連接數(shù)據(jù),并存儲在數(shù)據(jù)庫里 )?;蛘吣銈鬟f了二進制字符串給加密函數(shù),但是沒有指定編碼方式,現(xiàn)在就需要提供編碼參數(shù)。如果想切換回原來的風格,將crypto.DEFAULT_ENCODING
設置為'binary'。注意,新的程序希望是buffers,所以之前的方法只能作為臨時的辦法。
更多建議: