doc/api/crypto.markdown

   1 # Crypto
   2
   3     Stability: 3 - Stable
   4
   5 Use `require('crypto')` to access this module.
   6
   7 The crypto module requires OpenSSL to be available on the underlying platform.
   8 It offers a way of encapsulating secure credentials to be used as part
   9 of a secure HTTPS net or http connection.
  10
  11 It also offers a set of wrappers for OpenSSL's hash, hmac, cipher, decipher, sign and verify methods.
  12
  13 ## crypto.createCredentials(details)
  14
  15 Creates a credentials object, with the optional details being a dictionary with keys:
  16
  17 * `pfx` : A string or buffer holding the PFX or PKCS12 encoded private key, certificate and CA certificates
  18 * `key` : a string holding the PEM encoded private key
  19 * `cert` : a string holding the PEM encoded certificate
  20 * `passphrase` : A string of passphrase for the private key or pfx
  21 * `ca` : either a string or list of strings of PEM encoded CA certificates to trust.
  22 * `ciphers`: a string describing the ciphers to use or exclude. Consult
  23   <http://www.openssl.org/docs/apps/ciphers.html#CIPHER_LIST_FORMAT> for details
  24   on the format.
  25
  26 If no 'ca' details are given, then node.js will use the default publicly trusted list of CAs as given in
  27 <http://mxr.mozilla.org/mozilla/source/security/nss/lib/ckfw/builtins/certdata.txt>.
  28
  29
  30 ## crypto.createHash(algorithm)
  31
  32 Creates and returns a hash object, a cryptographic hash with the given algorithm
  33 which can be used to generate hash digests.
  34
  35 `algorithm` is dependent on the available algorithms supported by the version
  36 of OpenSSL on the platform. Examples are `'sha1'`, `'md5'`, `'sha256'`, `'sha512'`, etc.
  37 On recent releases, `openssl list-message-digest-algorithms` will display the available digest algorithms.
  38
  39 Example: this program that takes the sha1 sum of a file
  40
  41     var filename = process.argv[2];
  42     var crypto = require('crypto');
  43     var fs = require('fs');
  44
  45     var shasum = crypto.createHash('sha1');
  46
  47     var s = fs.ReadStream(filename);
  48     s.on('data', function(d) {
  49       shasum.update(d);
  50     });
  51
  52     s.on('end', function() {
  53       var d = shasum.digest('hex');
  54       console.log(d + '  ' + filename);
  55     });
  56
  57 ## Class: Hash
  58
  59 The class for creating hash digests of data.
  60
  61 Returned by `crypto.createHash`.
  62
  63 ### hash.update(data, [input_encoding])
  64
  65 Updates the hash content with the given `data`, the encoding of which is given
  66 in `input_encoding` and can be `'utf8'`, `'ascii'` or `'binary'`.
  67 Defaults to `'binary'`.
  68 This can be called many times with new data as it is streamed.
  69
  70 ### hash.digest([encoding])
  71
  72 Calculates the digest of all of the passed data to be hashed.
  73 The `encoding` can be `'hex'`, `'binary'` or `'base64'`.
  74 Defaults to `'binary'`.
  75
  76 Note: `hash` object can not be used after `digest()` method been called.
  77
  78
  79 ## crypto.createHmac(algorithm, key)
  80
  81 Creates and returns a hmac object, a cryptographic hmac with the given algorithm and key.
  82
  83 `algorithm` is dependent on the available algorithms supported by OpenSSL - see createHash above.
  84 `key` is the hmac key to be used.
  85
  86 ## Class: Hmac
  87
  88 Class for creating cryptographic hmac content.
  89
  90 Returned by `crypto.createHmac`.
  91
  92 ### hmac.update(data)
  93
  94 Update the hmac content with the given `data`.
  95 This can be called many times with new data as it is streamed.
  96
  97 ### hmac.digest([encoding])
  98
  99 Calculates the digest of all of the passed data to the hmac.
 100 The `encoding` can be `'hex'`, `'binary'` or `'base64'`.
 101 Defaults to `'binary'`.
 102
 103 Note: `hmac` object can not be used after `digest()` method been called.
 104
 105
 106 ## crypto.createCipher(algorithm, password)
 107
 108 Creates and returns a cipher object, with the given algorithm and password.
 109
 110 `algorithm` is dependent on OpenSSL, examples are `'aes192'`, etc.
 111 On recent releases, `openssl list-cipher-algorithms` will display the
 112 available cipher algorithms.
 113 `password` is used to derive key and IV, which must be `'binary'` encoded
 114 string (See the [Buffer section](buffer.html) for more information).
 115
 116 ## crypto.createCipheriv(algorithm, key, iv)
 117
 118 Creates and returns a cipher object, with the given algorithm, key and iv.
 119
 120 `algorithm` is the same as the `createCipher()`. `key` is a raw key used in
 121 algorithm. `iv` is an Initialization vector. `key` and `iv` must be `'binary'`
 122 encoded string (See the [Buffer section](buffer.html) for more information).
 123
 124 ## Class: Cipher
 125
 126 Class for encrypting data.
 127
 128 Returned by `crypto.createCipher` and `crypto.createCipheriv`.
 129
 130 ### cipher.update(data, [input_encoding], [output_encoding])
 131
 132 Updates the cipher with `data`, the encoding of which is given in
 133 `input_encoding` and can be `'utf8'`, `'ascii'` or `'binary'`.
 134 Defaults to `'binary'`.
 135
 136 The `output_encoding` specifies the output format of the enciphered data,
 137 and can be `'binary'`, `'base64'` or `'hex'`. Defaults to `'binary'`.
 138
 139 Returns the enciphered contents, and can be called many times with new data as it is streamed.
 140
 141 ### cipher.final([output_encoding])
 142
 143 Returns any remaining enciphered contents, with `output_encoding` being one of:
 144 `'binary'`, `'base64'` or `'hex'`. Defaults to `'binary'`.
 145
 146 Note: `cipher` object can not be used after `final()` method been called.
 147
 148
 149 ## crypto.createDecipher(algorithm, password)
 150
 151 Creates and returns a decipher object, with the given algorithm and key.
 152 This is the mirror of the [createCipher()](#crypto.createCipher) above.
 153
 154 ## crypto.createDecipheriv(algorithm, key, iv)
 155
 156 Creates and returns a decipher object, with the given algorithm, key and iv.
 157 This is the mirror of the [createCipheriv()](#crypto.createCipheriv) above.
 158
 159 ## Class: Decipher
 160
 161 Class for decrypting data.
 162
 163 Returned by `crypto.createDecipher` and `crypto.createDecipheriv`.
 164
 165 ### decipher.update(data, [input_encoding], [output_encoding])
 166
 167 Updates the decipher with `data`, which is encoded in `'binary'`, `'base64'`
 168 or `'hex'`. Defaults to `'binary'`.
 169
 170 The `output_decoding` specifies in what format to return the deciphered
 171 plaintext: `'binary'`, `'ascii'` or `'utf8'`. Defaults to `'binary'`.
 172
 173 ### decipher.final([output_encoding])
 174
 175 Returns any remaining plaintext which is deciphered,
 176 with `output_encoding` being one of: `'binary'`, `'ascii'` or `'utf8'`.
 177 Defaults to `'binary'`.
 178
 179 Note: `decipher` object can not be used after `final()` method been called.
 180
 181
 182 ## crypto.createSign(algorithm)
 183
 184 Creates and returns a signing object, with the given algorithm.
 185 On recent OpenSSL releases, `openssl list-public-key-algorithms` will display
 186 the available signing algorithms. Examples are `'RSA-SHA256'`.
 187
 188 ## Class: Signer
 189
 190 Class for generating signatures.
 191
 192 Returned by `crypto.createSign`.
 193
 194 ### signer.update(data)
 195
 196 Updates the signer object with data.
 197 This can be called many times with new data as it is streamed.
 198
 199 ### signer.sign(private_key, [output_format])
 200
 201 Calculates the signature on all the updated data passed through the signer.
 202 `private_key` is a string containing the PEM encoded private key for signing.
 203
 204 Returns the signature in `output_format` which can be `'binary'`, `'hex'` or
 205 `'base64'`. Defaults to `'binary'`.
 206
 207 Note: `signer` object can not be used after `sign()` method been called.
 208
 209 ## crypto.createVerify(algorithm)
 210
 211 Creates and returns a verification object, with the given algorithm.
 212 This is the mirror of the signing object above.
 213
 214 ## Class: Verify
 215
 216 Class for verifying signatures.
 217
 218 Returned by `crypto.createVerify`.
 219
 220 ### verifier.update(data)
 221
 222 Updates the verifier object with data.
 223 This can be called many times with new data as it is streamed.
 224
 225 ### verifier.verify(object, signature, [signature_format])
 226
 227 Verifies the signed data by using the `object` and `signature`. `object` is  a
 228 string containing a PEM encoded object, which can be one of RSA public key,
 229 DSA public key, or X.509 certificate. `signature` is the previously calculated
 230 signature for the data, in the `signature_format` which can be `'binary'`,
 231 `'hex'` or `'base64'`. Defaults to `'binary'`.
 232
 233 Returns true or false depending on the validity of the signature for the data and public key.
 234
 235 Note: `verifier` object can not be used after `verify()` method been called.
 236
 237 ## crypto.createDiffieHellman(prime_length)
 238
 239 Creates a Diffie-Hellman key exchange object and generates a prime of the
 240 given bit length. The generator used is `2`.
 241
 242 ## crypto.createDiffieHellman(prime, [encoding])
 243
 244 Creates a Diffie-Hellman key exchange object using the supplied prime. The
 245 generator used is `2`. Encoding can be `'binary'`, `'hex'`, or `'base64'`.
 246 Defaults to `'binary'`.
 247
 248 ## Class: DiffieHellman
 249
 250 The class for creating Diffie-Hellman key exchanges.
 251
 252 Returned by `crypto.createDiffieHellman`.
 253
 254 ### diffieHellman.generateKeys([encoding])
 255
 256 Generates private and public Diffie-Hellman key values, and returns the
 257 public key in the specified encoding. This key should be transferred to the
 258 other party. Encoding can be `'binary'`, `'hex'`, or `'base64'`.
 259 Defaults to `'binary'`.
 260
 261 ### diffieHellman.computeSecret(other_public_key, [input_encoding], [output_encoding])
 262
 263 Computes the shared secret using `other_public_key` as the other party's
 264 public key and returns the computed shared secret. Supplied key is
 265 interpreted using specified `input_encoding`, and secret is encoded using
 266 specified `output_encoding`. Encodings can be `'binary'`, `'hex'`, or
 267 `'base64'`. The input encoding defaults to `'binary'`.
 268 If no output encoding is given, the input encoding is used as output encoding.
 269
 270 ### diffieHellman.getPrime([encoding])
 271
 272 Returns the Diffie-Hellman prime in the specified encoding, which can be
 273 `'binary'`, `'hex'`, or `'base64'`. Defaults to `'binary'`.
 274
 275 ### diffieHellman.getGenerator([encoding])
 276
 277 Returns the Diffie-Hellman prime in the specified encoding, which can be
 278 `'binary'`, `'hex'`, or `'base64'`. Defaults to `'binary'`.
 279
 280 ### diffieHellman.getPublicKey([encoding])
 281
 282 Returns the Diffie-Hellman public key in the specified encoding, which can
 283 be `'binary'`, `'hex'`, or `'base64'`. Defaults to `'binary'`.
 284
 285 ### diffieHellman.getPrivateKey([encoding])
 286
 287 Returns the Diffie-Hellman private key in the specified encoding, which can
 288 be `'binary'`, `'hex'`, or `'base64'`. Defaults to `'binary'`.
 289
 290 ### diffieHellman.setPublicKey(public_key, [encoding])
 291
 292 Sets the Diffie-Hellman public key. Key encoding can be `'binary'`, `'hex'`,
 293 or `'base64'`. Defaults to `'binary'`.
 294
 295 ### diffieHellman.setPrivateKey(public_key, [encoding])
 296
 297 Sets the Diffie-Hellman private key. Key encoding can be `'binary'`, `'hex'`,
 298 or `'base64'`. Defaults to `'binary'`.
 299
 300 ## crypto.pbkdf2(password, salt, iterations, keylen, callback)
 301
 302 Asynchronous PBKDF2 applies pseudorandom function HMAC-SHA1 to derive
 303 a key of given length from the given password, salt and iterations.
 304 The callback gets two arguments `(err, derivedKey)`.
 305
 306 ## crypto.randomBytes(size, [callback])
 307
 308 Generates cryptographically strong pseudo-random data. Usage:
 309
 310     // async
 311     crypto.randomBytes(256, function(ex, buf) {
 312       if (ex) throw ex;
 313       console.log('Have %d bytes of random data: %s', buf.length, buf);
 314     });
 315
 316     // sync
 317     try {
 318       var buf = crypto.randomBytes(256);
 319       console.log('Have %d bytes of random data: %s', buf.length, buf);
 320     } catch (ex) {
 321       // handle error
 322     }