buffer: introduce latin1 encoding term

When node began using the OneByte API (f150d56) it also switched to
officially supporting ISO-8859-1. Though at the time no new encoding
string was introduced.

Introduce the new encoding string 'latin1' to be more explicit. The
previous 'binary' and documented as an alias to 'latin1'.  While many
tests have switched to use 'latin1', there are still plenty that do both
'binary' and 'latin1' checks side-by-side to ensure there is no
regression.

PR-URL: https://github.com/nodejs/node/pull/7111
Reviewed-By: Ben Noordhuis <info@bnoordhuis.nl>
Reviewed-By: Anna Henningsen <anna@addaleax.net>
Reviewed-By: James M Snell <jasnell@gmail.com>

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.