doc: describe why new Buffer() is problematic
Existing docs weren't clear on the actual problem. In addition, the text described 8.0.0 as being a future Node.js release, so adjust language to reflect that 8.0.0 is in the past (while not losing important information about what the pre-8.x behaviour was). PR-URL: https://github.com/nodejs/node/pull/28825 Reviewed-By: Michael Dawson <michael_dawson@ca.ibm.com> Reviewed-By: Rich Trott <rtrott@gmail.com> Reviewed-By: Сковорода Никита Андреевич <chalkerx@gmail.com> Reviewed-By: Luigi Pinca <luigipinca@gmail.com> Reviewed-By: Jeremiah Senkpiel <fishrock123@rocketmail.com> Reviewed-By: Trivikram Kamat <trivikr.dev@gmail.com>
This commit is contained in:
parent
16f673ebcc
commit
e9ea8eaf7a
@ -59,8 +59,8 @@ differently based on what arguments are provided:
|
|||||||
entire `Buffer`. While this behavior is *intentional* to improve performance,
|
entire `Buffer`. While this behavior is *intentional* to improve performance,
|
||||||
development experience has demonstrated that a more explicit distinction is
|
development experience has demonstrated that a more explicit distinction is
|
||||||
required between creating a fast-but-uninitialized `Buffer` versus creating a
|
required between creating a fast-but-uninitialized `Buffer` versus creating a
|
||||||
slower-but-safer `Buffer`. Starting in Node.js 8.0.0, `Buffer(num)` and
|
slower-but-safer `Buffer`. Since Node.js 8.0.0, `Buffer(num)` and `new
|
||||||
`new Buffer(num)` will return a `Buffer` with initialized memory.
|
Buffer(num)` return a `Buffer` with initialized memory.
|
||||||
* Passing a string, array, or `Buffer` as the first argument copies the
|
* Passing a string, array, or `Buffer` as the first argument copies the
|
||||||
passed object's data into the `Buffer`.
|
passed object's data into the `Buffer`.
|
||||||
* Passing an [`ArrayBuffer`][] or a [`SharedArrayBuffer`][] returns a `Buffer`
|
* Passing an [`ArrayBuffer`][] or a [`SharedArrayBuffer`][] returns a `Buffer`
|
||||||
@ -71,6 +71,19 @@ first argument, security and reliability issues can be inadvertently introduced
|
|||||||
into applications when argument validation or `Buffer` initialization is not
|
into applications when argument validation or `Buffer` initialization is not
|
||||||
performed.
|
performed.
|
||||||
|
|
||||||
|
For example, if an attacker can cause an application to receive a number where
|
||||||
|
a string is expected, the application may call `new Buffer(100)`
|
||||||
|
instead of `new Buffer("100")`, it will allocate a 100 byte buffer instead
|
||||||
|
of allocating a 3 byte buffer with content `"100"`. This is commonly possible
|
||||||
|
using JSON API calls. Since JSON distinguishes between numeric and string types,
|
||||||
|
it allows injection of numbers where a naive application might expect to always
|
||||||
|
receive a string. Before Node.js 8.0.0, the 100 byte buffer might contain
|
||||||
|
arbitrary pre-existing in-memory data, so may be used to expose in-memory
|
||||||
|
secrets to a remote attacker. Since Node.js 8.0.0, exposure of memory cannot
|
||||||
|
occur because the data is zero-filled. However, other attacks are still
|
||||||
|
possible, such as causing very large buffers to be allocated by the server,
|
||||||
|
leading to performance degradation or crashing on memory exhaustion.
|
||||||
|
|
||||||
To make the creation of `Buffer` instances more reliable and less error-prone,
|
To make the creation of `Buffer` instances more reliable and less error-prone,
|
||||||
the various forms of the `new Buffer()` constructor have been **deprecated**
|
the various forms of the `new Buffer()` constructor have been **deprecated**
|
||||||
and replaced by separate `Buffer.from()`, [`Buffer.alloc()`][], and
|
and replaced by separate `Buffer.from()`, [`Buffer.alloc()`][], and
|
||||||
@ -92,7 +105,7 @@ to one of these new APIs.*
|
|||||||
initialized `Buffer` of the specified size. This method is slower than
|
initialized `Buffer` of the specified size. This method is slower than
|
||||||
[`Buffer.allocUnsafe(size)`][`Buffer.allocUnsafe()`] but guarantees that newly
|
[`Buffer.allocUnsafe(size)`][`Buffer.allocUnsafe()`] but guarantees that newly
|
||||||
created `Buffer` instances never contain old data that is potentially
|
created `Buffer` instances never contain old data that is potentially
|
||||||
sensitive.
|
sensitive. A `TypeError` will be thrown if `size` is not a number.
|
||||||
* [`Buffer.allocUnsafe(size)`][`Buffer.allocUnsafe()`] and
|
* [`Buffer.allocUnsafe(size)`][`Buffer.allocUnsafe()`] and
|
||||||
[`Buffer.allocUnsafeSlow(size)`][`Buffer.allocUnsafeSlow()`] each return a
|
[`Buffer.allocUnsafeSlow(size)`][`Buffer.allocUnsafeSlow()`] each return a
|
||||||
new uninitialized `Buffer` of the specified `size`. Because the `Buffer` is
|
new uninitialized `Buffer` of the specified `size`. Because the `Buffer` is
|
||||||
@ -111,7 +124,9 @@ added: v5.10.0
|
|||||||
|
|
||||||
Node.js can be started using the `--zero-fill-buffers` command line option to
|
Node.js can be started using the `--zero-fill-buffers` command line option to
|
||||||
cause all newly allocated `Buffer` instances to be zero-filled upon creation by
|
cause all newly allocated `Buffer` instances to be zero-filled upon creation by
|
||||||
default, including buffers returned by `new Buffer(size)`,
|
default. Before Node.js 8.0.0, this included buffers allocated by `new
|
||||||
|
Buffer(size)`. Since Node.js 8.0.0, buffers allocated with `new` are always
|
||||||
|
zero-filled, whether this option is used or not.
|
||||||
[`Buffer.allocUnsafe()`][], [`Buffer.allocUnsafeSlow()`][], and `new
|
[`Buffer.allocUnsafe()`][], [`Buffer.allocUnsafeSlow()`][], and `new
|
||||||
SlowBuffer(size)`. Use of this flag can have a significant negative impact on
|
SlowBuffer(size)`. Use of this flag can have a significant negative impact on
|
||||||
performance. Use of the `--zero-fill-buffers` option is recommended only when
|
performance. Use of the `--zero-fill-buffers` option is recommended only when
|
||||||
|
Loading…
x
Reference in New Issue
Block a user