Permalink
Browse files

doc: Crypto streaming interface

  • Loading branch information...
1 parent a48aa8c commit f907e249aec10d78b8798321f38d045468f34699 @isaacs isaacs committed Oct 30, 2012
Showing with 42 additions and 9 deletions.
  1. +42 −9 doc/api/crypto.markdown
View
@@ -89,6 +89,11 @@ Example: this program that takes the sha1 sum of a file
The class for creating hash digests of data.
+It is a [stream](stream.html) that is both readable and writable. The
+written data is used to compute the hash. Once the writable side of
+the stream is ended, use the `read()` method to get the computed hash
+digest. The legacy `update` and `digest` methods are also supported.
+
Returned by `crypto.createHash`.
### hash.update(data, [input_encoding])
@@ -114,6 +119,11 @@ called.
Creates and returns a hmac object, a cryptographic hmac with the given
algorithm and key.
+It is a [stream](stream.html) that is both readable and writable. The
+written data is used to compute the hmac. Once the writable side of
+the stream is ended, use the `read()` method to get the computed
+digest. The legacy `update` and `digest` methods are also supported.
+
`algorithm` is dependent on the available algorithms supported by
OpenSSL - see createHash above. `key` is the hmac key to be used.
@@ -148,6 +158,11 @@ recent releases, `openssl list-cipher-algorithms` will display the
available cipher algorithms. `password` is used to derive key and IV,
which must be a `'binary'` encoded string or a [buffer](buffer.html).
+It is a [stream](stream.html) that is both readable and writable. The
+written data is used to compute the hash. Once the writable side of
+the stream is ended, use the `read()` method to get the computed hash
+digest. The legacy `update` and `digest` methods are also supported.
+
## crypto.createCipheriv(algorithm, key, iv)
Creates and returns a cipher object, with the given algorithm, key and
@@ -166,6 +181,11 @@ Class for encrypting data.
Returned by `crypto.createCipher` and `crypto.createCipheriv`.
+Cipher objects are [streams](stream.html) that are both readable and
+writable. The written plain text data is used to produce the
+encrypted data on the the readable side. The legacy `update` and
+`final` methods are also supported.
+
### cipher.update(data, [input_encoding], [output_encoding])
Updates the cipher with `data`, the encoding of which is given in
@@ -213,6 +233,11 @@ Class for decrypting data.
Returned by `crypto.createDecipher` and `crypto.createDecipheriv`.
+Decipher objects are [streams](stream.html) that are both readable and
+writable. The written enciphered data is used to produce the
+plain-text data on the the readable side. The legacy `update` and
+`final` methods are also supported.
+
### decipher.update(data, [input_encoding], [output_encoding])
Updates the decipher with `data`, which is encoded in `'binary'`,
@@ -246,28 +271,33 @@ Creates and returns a signing object, with the given algorithm. On
recent OpenSSL releases, `openssl list-public-key-algorithms` will
display the available signing algorithms. Examples are `'RSA-SHA256'`.
-## Class: Signer
+## Class: Sign
Class for generating signatures.
Returned by `crypto.createSign`.
-### signer.update(data)
+Sign objects are writable [streams](stream.html). The written data is
+used to generate the signature. Once all of the data has been
+written, the `sign` method will return the signature. The legacy
+`update` method is also supported.
+
+### sign.update(data)
-Updates the signer object with data. This can be called many times
+Updates the sign object with data. This can be called many times
with new data as it is streamed.
-### signer.sign(private_key, [output_format])
+### sign.sign(private_key, [output_format])
Calculates the signature on all the updated data passed through the
-signer. `private_key` is a string containing the PEM encoded private
+sign. `private_key` is a string containing the PEM encoded private
key for signing.
Returns the signature in `output_format` which can be `'binary'`,
`'hex'` or `'base64'`. If no encoding is provided, then a buffer is
returned.
-Note: `signer` object can not be used after `sign()` method been
+Note: `sign` object can not be used after `sign()` method been
called.
## crypto.createVerify(algorithm)
@@ -281,6 +311,12 @@ Class for verifying signatures.
Returned by `crypto.createVerify`.
+Verify objects are writable [streams](stream.html). The written data
+is used to validate against the supplied signature. Once all of the
+data has been written, the `verify` method will return true if the
+supplied signature is valid. The legacy `update` method is also
+supported.
+
### verifier.update(data)
Updates the verifier object with data. This can be called many times
@@ -469,9 +505,6 @@ default, set the `crypto.DEFAULT_ENCODING` field to 'binary'. Note
that new programs will probably expect buffers, so only use this as a
temporary measure.
-Also, a Streaming API will be provided, but this will be done in such
-a way as to preserve the legacy API surface.
-
[createCipher()]: #crypto_crypto_createcipher_algorithm_password
[createCipheriv()]: #crypto_crypto_createcipheriv_algorithm_key_iv

0 comments on commit f907e24

Please sign in to comment.