Merge branch 'v0.4'

[platform/upstream/nodejs.git] / doc / api / crypto.markdown

diff --git a/doc/api/crypto.markdown b/doc/api/crypto.markdown
index 19b88c2..b1833b2 100644 (file)
--- a/doc/api/crypto.markdown
+++ b/doc/api/crypto.markdown
@@ -57,6 +57,8 @@ This can be called many times with new data as it is streamed.
 Calculates the digest of all of the passed data to be hashed.
 The `encoding` can be `'hex'`, `'binary'` or `'base64'`.
 
+Note: `hash` object can not be used after `digest()` method been called.
+
 
 ### crypto.createHmac(algorithm, key)
 
@@ -75,13 +77,26 @@ This can be called many times with new data as it is streamed.
 Calculates the digest of all of the passed data to the hmac.
 The `encoding` can be `'hex'`, `'binary'` or `'base64'`.
 
+Note: `hmac` object can not be used after `digest()` method been called.
+
 
-### crypto.createCipher(algorithm, key)
+### crypto.createCipher(algorithm, password)
 
-Creates and returns a cipher object, with the given algorithm and key.
+Creates and returns a cipher object, with the given algorithm and password.
 
 `algorithm` is dependent on OpenSSL, examples are `'aes192'`, etc.
-On recent releases, `openssl list-cipher-algorithms` will display the available cipher algorithms.
+On recent releases, `openssl list-cipher-algorithms` will display the
+available cipher algorithms.
+`password` is used to derive key and IV, which must be `'binary'` encoded
+string (See the [Buffers](buffers.html) for more information).
+
+### crypto.createCipheriv(algorithm, key, iv)
+
+Creates and returns a cipher object, with the given algorithm, key and iv.
+
+`algorithm` is the same as the `createCipher()`. `key` is a raw key used in
+algorithm. `iv` is an Initialization vector. `key` and `iv` must be `'binary'`
+encoded string (See the [Buffers](buffers.html) for more information).
 
 ### cipher.update(data, input_encoding='binary', output_encoding='binary')
 
@@ -95,10 +110,18 @@ Returns the enciphered contents, and can be called many times with new data as i
 
 Returns any remaining enciphered contents, with `output_encoding` being one of: `'binary'`, `'base64'` or `'hex'`.
 
-### crypto.createDecipher(algorithm, key)
+Note: `cipher` object can not be used after `final()` method been called.
+
+
+### crypto.createDecipher(algorithm, password)
 
 Creates and returns a decipher object, with the given algorithm and key.
-This is the mirror of the cipher object above.
+This is the mirror of the [createCipher()](#crypto.createCipher) above.
+
+### crypto.createDecipheriv(algorithm, key, iv)
+
+Creates and returns a decipher object, with the given algorithm, key and iv.
+This is the mirror of the [createCipheriv()](#crypto.createCipheriv) above.
 
 ### decipher.update(data, input_encoding='binary', output_encoding='binary')
 
@@ -110,6 +133,8 @@ The `output_decoding` specifies in what format to return the deciphered plaintex
 Returns any remaining plaintext which is deciphered,
 with `output_encoding` being one of: `'binary'`, `'ascii'` or `'utf8'`.
 
+Note: `decipher` object can not be used after `final()` method been called.
+
 
 ### crypto.createSign(algorithm)
 
@@ -129,6 +154,9 @@ Calculates the signature on all the updated data passed through the signer.
 
 Returns the signature in `output_format` which can be `'binary'`, `'hex'` or `'base64'`.
 
+Note: `signer` object can not be used after `sign()` method been called.
+
+
 ### crypto.createVerify(algorithm)
 
 Creates and returns a verification object, with the given algorithm.
@@ -149,6 +177,8 @@ signature for the data, in the `signature_format` which can be `'binary'`,
 
 Returns true or false depending on the validity of the signature for the data and public key.
 
+Note: `verifier` object can not be used after `verify()` method been called.
+
 ### crypto.createDiffieHellman(prime_length)
 
 Creates a Diffie-Hellman key exchange object and generates a prime of the