diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/api/buffer.md | 16 | ||||
| -rw-r--r-- | doc/api/crypto.md | 68 |
2 files changed, 47 insertions, 37 deletions
diff --git a/doc/api/buffer.md b/doc/api/buffer.md index f20f80c747..354fed25d5 100644 --- a/doc/api/buffer.md +++ b/doc/api/buffer.md @@ -165,12 +165,22 @@ The character encodings currently supported by Node.js include: this encoding will also correctly accept "URL and Filename Safe Alphabet" as specified in [RFC 4648, Section 5]. -* `'binary'` - A way of encoding the buffer into a one-byte (`latin-1`) - encoded string. The string `'latin-1'` is not supported. Instead, pass - `'binary'` to use `'latin-1'` encoding. +* `'latin1'` - A way of encoding the buffer into a one-byte encoded string + (as defined by the IANA in [RFC1345](https://tools.ietf.org/html/rfc1345), + page 63, to be the Latin-1 supplement block and C0/C1 control codes). + +* `'binary'` - (deprecated) A way of encoding the buffer into a one-byte + (`latin1`) encoded string. * `'hex'` - Encode each byte as two hexadecimal characters. +_Note_: Today's browsers follow the [WHATWG +spec](https://encoding.spec.whatwg.org/) that aliases both `latin1` and +`iso-8859-1` to `win-1252`. Meaning, while doing something like `http.get()`, +if the returned charset is one of those listed in the WHATWG spec it's possible +that the server actually returned `win-1252` encoded data, and using `latin1` +encoding may incorrectly decode the graphical characters. + ## Buffers and TypedArray Buffers are also `Uint8Array` TypedArray instances. However, there are subtle diff --git a/doc/api/crypto.md b/doc/api/crypto.md index e195c98e32..759fe12441 100644 --- a/doc/api/crypto.md +++ b/doc/api/crypto.md @@ -160,7 +160,7 @@ console.log(encrypted); ### cipher.final([output_encoding]) Returns any remaining enciphered contents. If `output_encoding` -parameter is one of `'binary'`, `'base64'` or `'hex'`, a string is returned. +parameter is one of `'latin1'`, `'base64'` or `'hex'`, a string is returned. If an `output_encoding` is not provided, a [`Buffer`][] is returned. Once the `cipher.final()` method has been called, the `Cipher` object can no @@ -198,13 +198,13 @@ The `cipher.setAutoPadding()` method must be called before [`cipher.final()`][]. ### cipher.update(data[, input_encoding][, output_encoding]) Updates the cipher with `data`. If the `input_encoding` argument is given, -it's value must be one of `'utf8'`, `'ascii'`, or `'binary'` and the `data` +it's value must be one of `'utf8'`, `'ascii'`, or `'latin1'` and the `data` argument is a string using the specified encoding. If the `input_encoding` argument is not given, `data` must be a [`Buffer`][]. If `data` is a [`Buffer`][] then `input_encoding` is ignored. The `output_encoding` specifies the output format of the enciphered -data, and can be `'binary'`, `'base64'` or `'hex'`. If the `output_encoding` +data, and can be `'latin1'`, `'base64'` or `'hex'`. If the `output_encoding` is specified, a string using the specified encoding is returned. If no `output_encoding` is provided, a [`Buffer`][] is returned. @@ -277,7 +277,7 @@ console.log(decrypted); ### decipher.final([output_encoding]) Returns any remaining deciphered contents. If `output_encoding` -parameter is one of `'binary'`, `'base64'` or `'hex'`, a string is returned. +parameter is one of `'latin1'`, `'base64'` or `'hex'`, a string is returned. If an `output_encoding` is not provided, a [`Buffer`][] is returned. Once the `decipher.final()` method has been called, the `Decipher` object can @@ -313,13 +313,13 @@ The `decipher.setAutoPadding()` method must be called before ### decipher.update(data[, input_encoding][, output_encoding]) Updates the decipher with `data`. If the `input_encoding` argument is given, -it's value must be one of `'binary'`, `'base64'`, or `'hex'` and the `data` +it's value must be one of `'latin1'`, `'base64'`, or `'hex'` and the `data` argument is a string using the specified encoding. If the `input_encoding` argument is not given, `data` must be a [`Buffer`][]. If `data` is a [`Buffer`][] then `input_encoding` is ignored. The `output_encoding` specifies the output format of the enciphered -data, and can be `'binary'`, `'ascii'` or `'utf8'`. If the `output_encoding` +data, and can be `'latin1'`, `'ascii'` or `'utf8'`. If the `output_encoding` is specified, a string using the specified encoding is returned. If no `output_encoding` is provided, a [`Buffer`][] is returned. @@ -361,7 +361,7 @@ Computes the shared secret using `other_public_key` as the other party's public key and returns the computed shared secret. The supplied key is interpreted using the specified `input_encoding`, and secret is encoded using specified `output_encoding`. Encodings can be -`'binary'`, `'hex'`, or `'base64'`. If the `input_encoding` is not +`'latin1'`, `'hex'`, or `'base64'`. If the `input_encoding` is not provided, `other_public_key` is expected to be a [`Buffer`][]. If `output_encoding` is given a string is returned; otherwise, a @@ -371,45 +371,45 @@ If `output_encoding` is given a string is returned; otherwise, a Generates private and public Diffie-Hellman key values, and returns the public key in the specified `encoding`. This key should be -transferred to the other party. Encoding can be `'binary'`, `'hex'`, +transferred to the other party. Encoding can be `'latin1'`, `'hex'`, or `'base64'`. If `encoding` is provided a string is returned; otherwise a [`Buffer`][] is returned. ### diffieHellman.getGenerator([encoding]) Returns the Diffie-Hellman generator in the specified `encoding`, which can -be `'binary'`, `'hex'`, or `'base64'`. If `encoding` is provided a string is +be `'latin1'`, `'hex'`, or `'base64'`. If `encoding` is provided a string is returned; otherwise a [`Buffer`][] is returned. ### diffieHellman.getPrime([encoding]) Returns the Diffie-Hellman prime in the specified `encoding`, which can -be `'binary'`, `'hex'`, or `'base64'`. If `encoding` is provided a string is +be `'latin1'`, `'hex'`, or `'base64'`. If `encoding` is provided a string is returned; otherwise a [`Buffer`][] is returned. ### diffieHellman.getPrivateKey([encoding]) Returns the Diffie-Hellman private key in the specified `encoding`, -which can be `'binary'`, `'hex'`, or `'base64'`. If `encoding` is provided a +which can be `'latin1'`, `'hex'`, or `'base64'`. If `encoding` is provided a string is returned; otherwise a [`Buffer`][] is returned. ### diffieHellman.getPublicKey([encoding]) Returns the Diffie-Hellman public key in the specified `encoding`, which -can be `'binary'`, `'hex'`, or `'base64'`. If `encoding` is provided a +can be `'latin1'`, `'hex'`, or `'base64'`. If `encoding` is provided a string is returned; otherwise a [`Buffer`][] is returned. ### diffieHellman.setPrivateKey(private_key[, encoding]) Sets the Diffie-Hellman private key. If the `encoding` argument is provided -and is either `'binary'`, `'hex'`, or `'base64'`, `private_key` is expected +and is either `'latin1'`, `'hex'`, or `'base64'`, `private_key` is expected to be a string. If no `encoding` is provided, `private_key` is expected to be a [`Buffer`][]. ### diffieHellman.setPublicKey(public_key[, encoding]) Sets the Diffie-Hellman public key. If the `encoding` argument is provided -and is either `'binary'`, `'hex'` or `'base64'`, `public_key` is expected +and is either `'latin1'`, `'hex'` or `'base64'`, `public_key` is expected to be a string. If no `encoding` is provided, `public_key` is expected to be a [`Buffer`][]. @@ -460,7 +460,7 @@ Computes the shared secret using `other_public_key` as the other party's public key and returns the computed shared secret. The supplied key is interpreted using specified `input_encoding`, and the returned secret is encoded using the specified `output_encoding`. Encodings can be -`'binary'`, `'hex'`, or `'base64'`. If the `input_encoding` is not +`'latin1'`, `'hex'`, or `'base64'`. If the `input_encoding` is not provided, `other_public_key` is expected to be a [`Buffer`][]. If `output_encoding` is given a string will be returned; otherwise a @@ -476,14 +476,14 @@ The `format` arguments specifies point encoding and can be `'compressed'`, `'uncompressed'`, or `'hybrid'`. If `format` is not specified, the point will be returned in `'uncompressed'` format. -The `encoding` argument can be `'binary'`, `'hex'`, or `'base64'`. If +The `encoding` argument can be `'latin1'`, `'hex'`, or `'base64'`. If `encoding` is provided a string is returned; otherwise a [`Buffer`][] is returned. ### ecdh.getPrivateKey([encoding]) Returns the EC Diffie-Hellman private key in the specified `encoding`, -which can be `'binary'`, `'hex'`, or `'base64'`. If `encoding` is provided +which can be `'latin1'`, `'hex'`, or `'base64'`. If `encoding` is provided a string is returned; otherwise a [`Buffer`][] is returned. ### ecdh.getPublicKey([encoding[, format]]) @@ -495,13 +495,13 @@ The `format` argument specifies point encoding and can be `'compressed'`, `'uncompressed'`, or `'hybrid'`. If `format` is not specified the point will be returned in `'uncompressed'` format. -The `encoding` argument can be `'binary'`, `'hex'`, or `'base64'`. If +The `encoding` argument can be `'latin1'`, `'hex'`, or `'base64'`. If `encoding` is specified, a string is returned; otherwise a [`Buffer`][] is returned. ### ecdh.setPrivateKey(private_key[, encoding]) -Sets the EC Diffie-Hellman private key. The `encoding` can be `'binary'`, +Sets the EC Diffie-Hellman private key. The `encoding` can be `'latin1'`, `'hex'` or `'base64'`. If `encoding` is provided, `private_key` is expected to be a string; otherwise `private_key` is expected to be a [`Buffer`][]. If `private_key` is not valid for the curve specified when the `ECDH` object was @@ -512,7 +512,7 @@ public point (key) is also generated and set in the ECDH object. Stability: 0 - Deprecated -Sets the EC Diffie-Hellman public key. Key encoding can be `'binary'`, +Sets the EC Diffie-Hellman public key. Key encoding can be `'latin1'`, `'hex'` or `'base64'`. If `encoding` is provided `public_key` is expected to be a string; otherwise a [`Buffer`][] is expected. @@ -604,7 +604,7 @@ console.log(hash.digest('hex')); ### hash.digest([encoding]) Calculates the digest of all of the data passed to be hashed (using the -[`hash.update()`][] method). The `encoding` can be `'hex'`, `'binary'` or +[`hash.update()`][] method). The `encoding` can be `'hex'`, `'latin1'` or `'base64'`. If `encoding` is provided a string will be returned; otherwise a [`Buffer`][] is returned. @@ -615,7 +615,7 @@ called. Multiple calls will cause an error to be thrown. Updates the hash content with the given `data`, the encoding of which is given in `input_encoding` and can be `'utf8'`, `'ascii'` or -`'binary'`. If `encoding` is not provided, and the `data` is a string, an +`'latin1'`. If `encoding` is not provided, and the `data` is a string, an encoding of `'utf8'` is enforced. If `data` is a [`Buffer`][] then `input_encoding` is ignored. @@ -678,7 +678,7 @@ console.log(hmac.digest('hex')); ### hmac.digest([encoding]) Calculates the HMAC digest of all of the data passed using [`hmac.update()`][]. -The `encoding` can be `'hex'`, `'binary'` or `'base64'`. If `encoding` is +The `encoding` can be `'hex'`, `'latin1'` or `'base64'`. If `encoding` is provided a string is returned; otherwise a [`Buffer`][] is returned; The `Hmac` object can not be used again after `hmac.digest()` has been @@ -688,7 +688,7 @@ called. Multiple calls to `hmac.digest()` will result in an error being thrown. Updates the `Hmac` content with the given `data`, the encoding of which is given in `input_encoding` and can be `'utf8'`, `'ascii'` or -`'binary'`. If `encoding` is not provided, and the `data` is a string, an +`'latin1'`. If `encoding` is not provided, and the `data` is a string, an encoding of `'utf8'` is enforced. If `data` is a [`Buffer`][] then `input_encoding` is ignored. @@ -768,7 +768,7 @@ object, it is interpreted as a hash containing two properties: * `key` : {String} - PEM encoded private key * `passphrase` : {String} - passphrase for the private key -The `output_format` can specify one of `'binary'`, `'hex'` or `'base64'`. If +The `output_format` can specify one of `'latin1'`, `'hex'` or `'base64'`. If `output_format` is provided a string is returned; otherwise a [`Buffer`][] is returned. @@ -779,7 +779,7 @@ called. Multiple calls to `sign.sign()` will result in an error being thrown. Updates the `Sign` content with the given `data`, the encoding of which is given in `input_encoding` and can be `'utf8'`, `'ascii'` or -`'binary'`. If `encoding` is not provided, and the `data` is a string, an +`'latin1'`. If `encoding` is not provided, and the `data` is a string, an encoding of `'utf8'` is enforced. If `data` is a [`Buffer`][] then `input_encoding` is ignored. @@ -831,7 +831,7 @@ console.log(verify.verify(public_key, signature)); Updates the `Verify` content with the given `data`, the encoding of which is given in `input_encoding` and can be `'utf8'`, `'ascii'` or -`'binary'`. If `encoding` is not provided, and the `data` is a string, an +`'latin1'`. If `encoding` is not provided, and the `data` is a string, an encoding of `'utf8'` is enforced. If `data` is a [`Buffer`][] then `input_encoding` is ignored. @@ -843,7 +843,7 @@ Verifies the provided data using the given `object` and `signature`. The `object` argument is a string containing a PEM encoded object, which can be one an RSA public key, a DSA public key, or an X.509 certificate. The `signature` argument is the previously calculated signature for the data, in -the `signature_format` which can be `'binary'`, `'hex'` or `'base64'`. +the `signature_format` which can be `'latin1'`, `'hex'` or `'base64'`. If a `signature_format` is specified, the `signature` is expected to be a string; otherwise `signature` is expected to be a [`Buffer`][]. @@ -869,7 +869,7 @@ or [buffers][`Buffer`]. The default value is `'buffer'`, which makes methods default to [`Buffer`][] objects. The `crypto.DEFAULT_ENCODING` mechanism is provided for backwards compatibility -with legacy programs that expect `'binary'` to be the default encoding. +with legacy programs that expect `'latin1'` to be the default encoding. New applications should expect the default to be `'buffer'`. This property may become deprecated in a future Node.js release. @@ -889,7 +889,7 @@ recent OpenSSL releases, `openssl list-cipher-algorithms` will display the available cipher algorithms. The `password` is used to derive the cipher key and initialization vector (IV). -The value must be either a `'binary'` encoded string or a [`Buffer`][]. +The value must be either a `'latin1'` encoded string or a [`Buffer`][]. The implementation of `crypto.createCipher()` derives keys using the OpenSSL function [`EVP_BytesToKey`][] with the digest algorithm set to MD5, one @@ -913,7 +913,7 @@ recent OpenSSL releases, `openssl list-cipher-algorithms` will display the available cipher algorithms. The `key` is the raw key used by the `algorithm` and `iv` is an -[initialization vector][]. Both arguments must be `'binary'` encoded strings or +[initialization vector][]. Both arguments must be `'latin1'` encoded strings or [buffers][`Buffer`]. ### crypto.createCredentials(details) @@ -968,7 +968,7 @@ recent OpenSSL releases, `openssl list-cipher-algorithms` will display the available cipher algorithms. The `key` is the raw key used by the `algorithm` and `iv` is an -[initialization vector][]. Both arguments must be `'binary'` encoded strings or +[initialization vector][]. Both arguments must be `'latin1'` encoded strings or [buffers][`Buffer`]. ### crypto.createDiffieHellman(prime[, prime_encoding][, generator][, generator_encoding]) @@ -979,7 +979,7 @@ optional specific `generator`. The `generator` argument can be a number, string, or [`Buffer`][]. If `generator` is not specified, the value `2` is used. -The `prime_encoding` and `generator_encoding` arguments can be `'binary'`, +The `prime_encoding` and `generator_encoding` arguments can be `'latin1'`, `'hex'`, or `'base64'`. If `prime_encoding` is specified, `prime` is expected to be a string; otherwise @@ -1345,7 +1345,7 @@ unified Stream API, and before there were [`Buffer`][] objects for handling binary data. As such, the many of the `crypto` defined classes have methods not typically found on other Node.js classes that implement the [streams][stream] API (e.g. `update()`, `final()`, or `digest()`). Also, many methods accepted -and returned `'binary'` encoded strings by default rather than Buffers. This +and returned `'latin1'` encoded strings by default rather than Buffers. This default was changed after Node.js v0.8 to use [`Buffer`][] objects by default instead. |