Permalink
Browse files

doc: Reduce crypto stability to 2-Unstable

  • Loading branch information...
1 parent 6a128e0 commit 99b2368a6cd408e75850ac73585de8800e2a10a1 @isaacs isaacs committed Oct 11, 2012
Showing with 33 additions and 1 deletion.
  1. +33 −1 doc/api/crypto.markdown
@@ -1,6 +1,7 @@
# Crypto
- Stability: 3 - Stable
+ Stability: 2 - Unstable; API changes are being discussed for
+ future versions. Breaking changes will be minimized. See below.
Use `require('crypto')` to access this module.
@@ -366,6 +367,37 @@ Generates cryptographically strong pseudo-random data. Usage:
// handle error
}
+## Proposed API Changes in Future Versions of Node
+
+The Crypto module was added to Node before there was the concept of a
+unified Stream API, and before there were Buffer objects for handling
+binary data.
+
+As such, the streaming classes don't have the typical methods found on
+other Node classes, and many methods accept and return Binary-encoded
+strings by default rather than Buffers.
+
+A future version of node will make Buffers the default data type.
+This will be a breaking change for some use cases, but not all.
+
+For example, if you currently use the default arguments to the Sign
+class, and then pass the results to the Verify class, without ever
+inspecting the data, then it will continue to work as before. Where
+you now get a binary string and then present the binary string to the
+Verify object, you'll get a Buffer, and present the Buffer to the
+Verify object.
+
+However, if you are doing things with the string data that will not
+work properly on Buffers (such as, concatenating them, storing in
+databases, etc.), or you are passing binary strings to the crypto
+functions without an encoding arguemnt, then you will need to start
+providing encoding arguments to specify which encoding you'd like to
+use.
+
+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
[crypto.createDiffieHellman()]: #crypto_crypto_creatediffiehellman_prime_encoding

2 comments on commit 99b2368

@langpavel

BTW is pseudo 'buffer' encondig working at this point?

@isaacs
isaacs commented on 99b2368 Oct 13, 2012

It's working with the 'buffer' encoding on master now. I've just about finished making it use buffers by default, we can try it out in the next 0.9 release.

Please sign in to comment.