doc/api/crypto.markdown

   1 # Crypto
   2
   3     Stability: 2 - Unstable; API changes are being discussed for
   4     future versions.  Breaking changes will be minimized.  See below.
   5
   6 Use `require('crypto')` to access this module.
   7
   8 The crypto module offers a way of encapsulating secure credentials to be
   9 used as part of a secure HTTPS net or http connection.
  10
  11 It also offers a set of wrappers for OpenSSL's hash, hmac, cipher,
  12 decipher, sign and verify methods.
  13
  14
  15 ## crypto.getCiphers()
  16
  17 Returns an array with the names of the supported ciphers.
  18
  19 Example:
  20
  21     var ciphers = crypto.getCiphers();
  22     console.log(ciphers); // ['AES128-SHA', 'AES256-SHA', ...]
  23
  24
  25 ## crypto.getHashes()
  26
  27 Returns an array with the names of the supported hash algorithms.
  28
  29 Example:
  30
  31     var hashes = crypto.getHashes();
  32     console.log(hashes); // ['sha', 'sha1', 'sha1WithRSAEncryption', ...]
  33
  34
  35 ## crypto.createCredentials(details)
  36
  37 Creates a credentials object, with the optional details being a
  38 dictionary with keys:
  39
  40 * `pfx` : A string or buffer holding the PFX or PKCS12 encoded private
  41   key, certificate and CA certificates
  42 * `key` : A string holding the PEM encoded private key
  43 * `passphrase` : A string of passphrase for the private key or pfx
  44 * `cert` : A string holding the PEM encoded certificate
  45 * `ca` : Either a string or list of strings of PEM encoded CA
  46   certificates to trust.
  47 * `crl` : Either a string or list of strings of PEM encoded CRLs
  48   (Certificate Revocation List)
  49 * `ciphers`: A string describing the ciphers to use or exclude.
  50   Consult
  51   <http://www.openssl.org/docs/apps/ciphers.html#CIPHER_LIST_FORMAT>
  52   for details on the format.
  53
  54 If no 'ca' details are given, then node.js will use the default
  55 publicly trusted list of CAs as given in
  56 <http://mxr.mozilla.org/mozilla/source/security/nss/lib/ckfw/builtins/certdata.txt>.
  57
  58
  59 ## crypto.createHash(algorithm)
  60
  61 Creates and returns a hash object, a cryptographic hash with the given
  62 algorithm which can be used to generate hash digests.
  63
  64 `algorithm` is dependent on the available algorithms supported by the
  65 version of OpenSSL on the platform. Examples are `'sha1'`, `'md5'`,
  66 `'sha256'`, `'sha512'`, etc.  On recent releases, `openssl
  67 list-message-digest-algorithms` will display the available digest
  68 algorithms.
  69
  70 Example: this program that takes the sha1 sum of a file
  71
  72     var filename = process.argv[2];
  73     var crypto = require('crypto');
  74     var fs = require('fs');
  75
  76     var shasum = crypto.createHash('sha1');
  77
  78     var s = fs.ReadStream(filename);
  79     s.on('data', function(d) {
  80       shasum.update(d);
  81     });
  82
  83     s.on('end', function() {
  84       var d = shasum.digest('hex');
  85       console.log(d + '  ' + filename);
  86     });
  87
  88 ## Class: Hash
  89
  90 The class for creating hash digests of data.
  91
  92 It is a [stream](stream.html) that is both readable and writable.  The
  93 written data is used to compute the hash.  Once the writable side of
  94 the stream is ended, use the `read()` method to get the computed hash
  95 digest.  The legacy `update` and `digest` methods are also supported.
  96
  97 Returned by `crypto.createHash`.
  98
  99 ### hash.update(data, [input_encoding])
 100
 101 Updates the hash content with the given `data`, the encoding of which
 102 is given in `input_encoding` and can be `'utf8'`, `'ascii'` or
 103 `'binary'`.  If no encoding is provided, then a buffer is expected.
 104
 105 This can be called many times with new data as it is streamed.
 106
 107 ### hash.digest([encoding])
 108
 109 Calculates the digest of all of the passed data to be hashed.  The
 110 `encoding` can be `'hex'`, `'binary'` or `'base64'`.  If no encoding
 111 is provided, then a buffer is returned.
 112
 113 Note: `hash` object can not be used after `digest()` method has been
 114 called.
 115
 116
 117 ## crypto.createHmac(algorithm, key)
 118
 119 Creates and returns a hmac object, a cryptographic hmac with the given
 120 algorithm and key.
 121
 122 It is a [stream](stream.html) that is both readable and writable.  The
 123 written data is used to compute the hmac.  Once the writable side of
 124 the stream is ended, use the `read()` method to get the computed
 125 digest.  The legacy `update` and `digest` methods are also supported.
 126
 127 `algorithm` is dependent on the available algorithms supported by
 128 OpenSSL - see createHash above.  `key` is the hmac key to be used.
 129
 130 ## Class: Hmac
 131
 132 Class for creating cryptographic hmac content.
 133
 134 Returned by `crypto.createHmac`.
 135
 136 ### hmac.update(data)
 137
 138 Update the hmac content with the given `data`.  This can be called
 139 many times with new data as it is streamed.
 140
 141 ### hmac.digest([encoding])
 142
 143 Calculates the digest of all of the passed data to the hmac.  The
 144 `encoding` can be `'hex'`, `'binary'` or `'base64'`.  If no encoding
 145 is provided, then a buffer is returned.
 146
 147 Note: `hmac` object can not be used after `digest()` method has been
 148 called.
 149
 150
 151 ## crypto.createCipher(algorithm, password)
 152
 153 Creates and returns a cipher object, with the given algorithm and
 154 password.
 155
 156 `algorithm` is dependent on OpenSSL, examples are `'aes192'`, etc.  On
 157 recent releases, `openssl list-cipher-algorithms` will display the
 158 available cipher algorithms.  `password` is used to derive key and IV,
 159 which must be a `'binary'` encoded string or a [buffer](buffer.html).
 160
 161 It is a [stream](stream.html) that is both readable and writable.  The
 162 written data is used to compute the hash.  Once the writable side of
 163 the stream is ended, use the `read()` method to get the computed hash
 164 digest.  The legacy `update` and `digest` methods are also supported.
 165
 166 ## crypto.createCipheriv(algorithm, key, iv)
 167
 168 Creates and returns a cipher object, with the given algorithm, key and
 169 iv.
 170
 171 `algorithm` is the same as the argument to `createCipher()`.  `key` is
 172 the raw key used by the algorithm.  `iv` is an [initialization
 173 vector](http://en.wikipedia.org/wiki/Initialization_vector).
 174
 175 `key` and `iv` must be `'binary'` encoded strings or
 176 [buffers](buffer.html).
 177
 178 ## Class: Cipher
 179
 180 Class for encrypting data.
 181
 182 Returned by `crypto.createCipher` and `crypto.createCipheriv`.
 183
 184 Cipher objects are [streams](stream.html) that are both readable and
 185 writable.  The written plain text data is used to produce the
 186 encrypted data on the readable side.  The legacy `update` and `final`
 187 methods are also supported.
 188
 189 ### cipher.update(data, [input_encoding], [output_encoding])
 190
 191 Updates the cipher with `data`, the encoding of which is given in
 192 `input_encoding` and can be `'utf8'`, `'ascii'` or `'binary'`.  If no
 193 encoding is provided, then a buffer is expected.
 194
 195 The `output_encoding` specifies the output format of the enciphered
 196 data, and can be `'binary'`, `'base64'` or `'hex'`.  If no encoding is
 197 provided, then a buffer is returned.
 198
 199 Returns the enciphered contents, and can be called many times with new
 200 data as it is streamed.
 201
 202 ### cipher.final([output_encoding])
 203
 204 Returns any remaining enciphered contents, with `output_encoding`
 205 being one of: `'binary'`, `'base64'` or `'hex'`.  If no encoding is
 206 provided, then a buffer is returned.
 207
 208 Note: `cipher` object can not be used after `final()` method has been
 209 called.
 210
 211 ### cipher.setAutoPadding(auto_padding=true)
 212
 213 You can disable automatic padding of the input data to block size. If
 214 `auto_padding` is false, the length of the entire input data must be a
 215 multiple of the cipher's block size or `final` will fail.  Useful for
 216 non-standard padding, e.g. using `0x0` instead of PKCS padding. You
 217 must call this before `cipher.final`.
 218
 219
 220 ## crypto.createDecipher(algorithm, password)
 221
 222 Creates and returns a decipher object, with the given algorithm and
 223 key.  This is the mirror of the [createCipher()][] above.
 224
 225 ## crypto.createDecipheriv(algorithm, key, iv)
 226
 227 Creates and returns a decipher object, with the given algorithm, key
 228 and iv.  This is the mirror of the [createCipheriv()][] above.
 229
 230 ## Class: Decipher
 231
 232 Class for decrypting data.
 233
 234 Returned by `crypto.createDecipher` and `crypto.createDecipheriv`.
 235
 236 Decipher objects are [streams](stream.html) that are both readable and
 237 writable.  The written enciphered data is used to produce the
 238 plain-text data on the the readable side.  The legacy `update` and
 239 `final` methods are also supported.
 240
 241 ### decipher.update(data, [input_encoding], [output_encoding])
 242
 243 Updates the decipher with `data`, which is encoded in `'binary'`,
 244 `'base64'` or `'hex'`.  If no encoding is provided, then a buffer is
 245 expected.
 246
 247 The `output_decoding` specifies in what format to return the
 248 deciphered plaintext: `'binary'`, `'ascii'` or `'utf8'`.  If no
 249 encoding is provided, then a buffer is returned.
 250
 251 ### decipher.final([output_encoding])
 252
 253 Returns any remaining plaintext which is deciphered, with
 254 `output_encoding` being one of: `'binary'`, `'ascii'` or `'utf8'`.  If
 255 no encoding is provided, then a buffer is returned.
 256
 257 Note: `decipher` object can not be used after `final()` method has been
 258 called.
 259
 260 ### decipher.setAutoPadding(auto_padding=true)
 261
 262 You can disable auto padding if the data has been encrypted without
 263 standard block padding to prevent `decipher.final` from checking and
 264 removing it. Can only work if the input data's length is a multiple of
 265 the ciphers block size. You must call this before streaming data to
 266 `decipher.update`.
 267
 268 ## crypto.createSign(algorithm)
 269
 270 Creates and returns a signing object, with the given algorithm.  On
 271 recent OpenSSL releases, `openssl list-public-key-algorithms` will
 272 display the available signing algorithms. Examples are `'RSA-SHA256'`.
 273
 274 ## Class: Sign
 275
 276 Class for generating signatures.
 277
 278 Returned by `crypto.createSign`.
 279
 280 Sign objects are writable [streams](stream.html).  The written data is
 281 used to generate the signature.  Once all of the data has been
 282 written, the `sign` method will return the signature.  The legacy
 283 `update` method is also supported.
 284
 285 ### sign.update(data)
 286
 287 Updates the sign object with data.  This can be called many times
 288 with new data as it is streamed.
 289
 290 ### sign.sign(private_key, [output_format])
 291
 292 Calculates the signature on all the updated data passed through the
 293 sign.  `private_key` is a string containing the PEM encoded private
 294 key for signing.
 295
 296 Returns the signature in `output_format` which can be `'binary'`,
 297 `'hex'` or `'base64'`. If no encoding is provided, then a buffer is
 298 returned.
 299
 300 Note: `sign` object can not be used after `sign()` method has been
 301 called.
 302
 303 ## crypto.createVerify(algorithm)
 304
 305 Creates and returns a verification object, with the given algorithm.
 306 This is the mirror of the signing object above.
 307
 308 ## Class: Verify
 309
 310 Class for verifying signatures.
 311
 312 Returned by `crypto.createVerify`.
 313
 314 Verify objects are writable [streams](stream.html).  The written data
 315 is used to validate against the supplied signature.  Once all of the
 316 data has been written, the `verify` method will return true if the
 317 supplied signature is valid.  The legacy `update` method is also
 318 supported.
 319
 320 ### verifier.update(data)
 321
 322 Updates the verifier object with data.  This can be called many times
 323 with new data as it is streamed.
 324
 325 ### verifier.verify(object, signature, [signature_format])
 326
 327 Verifies the signed data by using the `object` and `signature`.
 328 `object` is  a string containing a PEM encoded object, which can be
 329 one of RSA public key, DSA public key, or X.509 certificate.
 330 `signature` is the previously calculated signature for the data, in
 331 the `signature_format` which can be `'binary'`, `'hex'` or `'base64'`.
 332 If no encoding is specified, then a buffer is expected.
 333
 334 Returns true or false depending on the validity of the signature for
 335 the data and public key.
 336
 337 Note: `verifier` object can not be used after `verify()` method has been
 338 called.
 339
 340 ## crypto.createDiffieHellman(prime_length)
 341
 342 Creates a Diffie-Hellman key exchange object and generates a prime of
 343 the given bit length. The generator used is `2`.
 344
 345 ## crypto.createDiffieHellman(prime, [encoding])
 346
 347 Creates a Diffie-Hellman key exchange object using the supplied prime.
 348 The generator used is `2`. Encoding can be `'binary'`, `'hex'`, or
 349 `'base64'`.  If no encoding is specified, then a buffer is expected.
 350
 351 ## Class: DiffieHellman
 352
 353 The class for creating Diffie-Hellman key exchanges.
 354
 355 Returned by `crypto.createDiffieHellman`.
 356
 357 ### diffieHellman.generateKeys([encoding])
 358
 359 Generates private and public Diffie-Hellman key values, and returns
 360 the public key in the specified encoding. This key should be
 361 transferred to the other party. Encoding can be `'binary'`, `'hex'`,
 362 or `'base64'`.  If no encoding is provided, then a buffer is returned.
 363
 364 ### diffieHellman.computeSecret(other_public_key, [input_encoding], [output_encoding])
 365
 366 Computes the shared secret using `other_public_key` as the other
 367 party's public key and returns the computed shared secret. Supplied
 368 key is interpreted using specified `input_encoding`, and secret is
 369 encoded using specified `output_encoding`. Encodings can be
 370 `'binary'`, `'hex'`, or `'base64'`. If the input encoding is not
 371 provided, then a buffer is expected.
 372
 373 If no output encoding is given, then a buffer is returned.
 374
 375 ### diffieHellman.getPrime([encoding])
 376
 377 Returns the Diffie-Hellman prime in the specified encoding, which can
 378 be `'binary'`, `'hex'`, or `'base64'`. If no encoding is provided,
 379 then a buffer is returned.
 380
 381 ### diffieHellman.getGenerator([encoding])
 382
 383 Returns the Diffie-Hellman prime in the specified encoding, which can
 384 be `'binary'`, `'hex'`, or `'base64'`. If no encoding is provided,
 385 then a buffer is returned.
 386
 387 ### diffieHellman.getPublicKey([encoding])
 388
 389 Returns the Diffie-Hellman public key in the specified encoding, which
 390 can be `'binary'`, `'hex'`, or `'base64'`. If no encoding is provided,
 391 then a buffer is returned.
 392
 393 ### diffieHellman.getPrivateKey([encoding])
 394
 395 Returns the Diffie-Hellman private key in the specified encoding,
 396 which can be `'binary'`, `'hex'`, or `'base64'`. If no encoding is
 397 provided, then a buffer is returned.
 398
 399 ### diffieHellman.setPublicKey(public_key, [encoding])
 400
 401 Sets the Diffie-Hellman public key. Key encoding can be `'binary'`,
 402 `'hex'` or `'base64'`. If no encoding is provided, then a buffer is
 403 expected.
 404
 405 ### diffieHellman.setPrivateKey(private_key, [encoding])
 406
 407 Sets the Diffie-Hellman private key. Key encoding can be `'binary'`,
 408 `'hex'` or `'base64'`. If no encoding is provided, then a buffer is
 409 expected.
 410
 411 ## crypto.getDiffieHellman(group_name)
 412
 413 Creates a predefined Diffie-Hellman key exchange object.  The
 414 supported groups are: `'modp1'`, `'modp2'`, `'modp5'` (defined in [RFC
 415 2412][]) and `'modp14'`, `'modp15'`, `'modp16'`, `'modp17'`,
 416 `'modp18'` (defined in [RFC 3526][]).  The returned object mimics the
 417 interface of objects created by [crypto.createDiffieHellman()][]
 418 above, but will not allow to change the keys (with
 419 [diffieHellman.setPublicKey()][] for example).  The advantage of using
 420 this routine is that the parties don't have to generate nor exchange
 421 group modulus beforehand, saving both processor and communication
 422 time.
 423
 424 Example (obtaining a shared secret):
 425
 426     var crypto = require('crypto');
 427     var alice = crypto.getDiffieHellman('modp5');
 428     var bob = crypto.getDiffieHellman('modp5');
 429
 430     alice.generateKeys();
 431     bob.generateKeys();
 432
 433     var alice_secret = alice.computeSecret(bob.getPublicKey(), null, 'hex');
 434     var bob_secret = bob.computeSecret(alice.getPublicKey(), null, 'hex');
 435
 436     /* alice_secret and bob_secret should be the same */
 437     console.log(alice_secret == bob_secret);
 438
 439 ## crypto.pbkdf2(password, salt, iterations, keylen, callback)
 440
 441 Asynchronous PBKDF2 applies pseudorandom function HMAC-SHA1 to derive
 442 a key of given length from the given password, salt and iterations.
 443 The callback gets two arguments `(err, derivedKey)`.
 444
 445 ## crypto.pbkdf2Sync(password, salt, iterations, keylen)
 446
 447 Synchronous PBKDF2 function.  Returns derivedKey or throws error.
 448
 449 ## crypto.randomBytes(size, [callback])
 450
 451 Generates cryptographically strong pseudo-random data. Usage:
 452
 453     // async
 454     crypto.randomBytes(256, function(ex, buf) {
 455       if (ex) throw ex;
 456       console.log('Have %d bytes of random data: %s', buf.length, buf);
 457     });
 458
 459     // sync
 460     try {
 461       var buf = crypto.randomBytes(256);
 462       console.log('Have %d bytes of random data: %s', buf.length, buf);
 463     } catch (ex) {
 464       // handle error
 465     }
 466
 467 ## crypto.pseudoRandomBytes(size, [callback])
 468
 469 Generates *non*-cryptographically strong pseudo-random data. The data
 470 returned will be unique if it is sufficiently long, but is not
 471 necessarily unpredictable. For this reason, the output of this
 472 function should never be used where unpredictability is important,
 473 such as in the generation of encryption keys.
 474
 475 Usage is otherwise identical to `crypto.randomBytes`.
 476
 477 ## crypto.DEFAULT_ENCODING
 478
 479 The default encoding to use for functions that can take either strings
 480 or buffers.  The default value is `'buffer'`, which makes it default
 481 to using Buffer objects.  This is here to make the crypto module more
 482 easily compatible with legacy programs that expected `'binary'` to be
 483 the default encoding.
 484
 485 Note that new programs will probably expect buffers, so only use this
 486 as a temporary measure.
 487
 488 ## Recent API Changes
 489
 490 The Crypto module was added to Node before there was the concept of a
 491 unified Stream API, and before there were Buffer objects for handling
 492 binary data.
 493
 494 As such, the streaming classes don't have the typical methods found on
 495 other Node classes, and many methods accepted and returned
 496 Binary-encoded strings by default rather than Buffers.  This was
 497 changed to use Buffers by default instead.
 498
 499 This is a breaking change for some use cases, but not all.
 500
 501 For example, if you currently use the default arguments to the Sign
 502 class, and then pass the results to the Verify class, without ever
 503 inspecting the data, then it will continue to work as before.  Where
 504 you once got a binary string and then presented the binary string to
 505 the Verify object, you'll now get a Buffer, and present the Buffer to
 506 the Verify object.
 507
 508 However, if you were doing things with the string data that will not
 509 work properly on Buffers (such as, concatenating them, storing in
 510 databases, etc.), or you are passing binary strings to the crypto
 511 functions without an encoding argument, then you will need to start
 512 providing encoding arguments to specify which encoding you'd like to
 513 use.  To switch to the previous style of using binary strings by
 514 default, set the `crypto.DEFAULT_ENCODING` field to 'binary'.  Note
 515 that new programs will probably expect buffers, so only use this as a
 516 temporary measure.
 517
 518
 519 [createCipher()]: #crypto_crypto_createcipher_algorithm_password
 520 [createCipheriv()]: #crypto_crypto_createcipheriv_algorithm_key_iv
 521 [crypto.createDiffieHellman()]: #crypto_crypto_creatediffiehellman_prime_encoding
 522 [diffieHellman.setPublicKey()]: #crypto_diffiehellman_setpublickey_public_key_encoding
 523 [RFC 2412]: http://www.rfc-editor.org/rfc/rfc2412.txt
 524 [RFC 3526]: http://www.rfc-editor.org/rfc/rfc3526.txt