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'`.
 
 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)
 
 
 ### 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'`.
 
 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.
 
 `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')
 
 
 ### 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'`.
 
 
 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.
 
 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')
 
 
 ### 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'`.
 
 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)
 
 
 ### 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'`.
 
 
 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.
 ### 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.
 
 
 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
 ### crypto.createDiffieHellman(prime_length)
 
 Creates a Diffie-Hellman key exchange object and generates a prime of the