diff options
Diffstat (limited to 'doc/api')
| -rw-r--r-- | doc/api/child_process.markdown | 97 | ||||
| -rw-r--r-- | doc/api/crypto.markdown | 12 | ||||
| -rw-r--r-- | doc/api/dns.markdown | 11 | ||||
| -rw-r--r-- | doc/api/https.markdown | 4 | ||||
| -rw-r--r-- | doc/api/net.markdown | 8 | ||||
| -rw-r--r-- | doc/api/process.markdown | 6 | ||||
| -rw-r--r-- | doc/api/stream.markdown | 26 | ||||
| -rw-r--r-- | doc/api/tls.markdown | 43 | ||||
| -rw-r--r-- | doc/api/url.markdown | 6 |
9 files changed, 167 insertions, 46 deletions
diff --git a/doc/api/child_process.markdown b/doc/api/child_process.markdown index 7db488292..5b628f339 100644 --- a/doc/api/child_process.markdown +++ b/doc/api/child_process.markdown @@ -95,29 +95,71 @@ Messages send by `.send(message, [sendHandle])` are obtained using the * {Stream object} A `Writable Stream` that represents the child process's `stdin`. -Closing this stream via `end()` often causes the child process to terminate. +If the child is waiting to read all its input, it will not continue until this +stream has been closed via `end()`. -If the child stdio streams are shared with the parent, then this will +If the child was not spawned with `stdio[0]` set to `'pipe'`, then this will not be set. +`child.stdin` is shorthand for `child.stdio[0]`. Both properties will refer +to the same object, or null. + ### child.stdout * {Stream object} A `Readable Stream` that represents the child process's `stdout`. -If the child stdio streams are shared with the parent, then this will +If the child was not spawned with `stdio[1]` set to `'pipe'`, then this will not be set. +`child.stdout` is shorthand for `child.stdio[1]`. Both properties will refer +to the same object, or null. + ### child.stderr * {Stream object} A `Readable Stream` that represents the child process's `stderr`. -If the child stdio streams are shared with the parent, then this will +If the child was not spawned with `stdio[2]` set to `'pipe'`, then this will not be set. +`child.stderr` is shorthand for `child.stdio[2]`. Both properties will refer +to the same object, or null. + +### child.stdio + +* {Array} + +A sparse array of pipes to the child process, corresponding with positions in +the [stdio](#child_process_options_stdio) option to +[spawn](#child_process_child_process_spawn_command_args_options) that have been +set to `'pipe'`. +Note that streams 0-2 are also available as ChildProcess.stdin, +ChildProcess.stdout, and ChildProcess.stderr, respectively. + +In the following example, only the child's fd `1` is setup as a pipe, so only +the parent's `child.stdio[1]` is a stream, all other values in the array are +`null`. + + child = child_process.spawn("ls", { + stdio: [ + 0, // use parents stdin for child + 'pipe', // pipe child's stdout to parent + fs.openSync("err.out", "w") // direct child's stderr to a file + ] + }); + + assert.equal(child.stdio[0], null); + assert.equal(child.stdio[0], child.stdin); + + assert(child.stdout); + assert.equal(child.stdio[1], child.stdout); + + assert.equal(child.stdio[2], null); + assert.equal(child.stdio[2], child.stderr); + ### child.pid * {Integer} @@ -311,7 +353,12 @@ callback or returning an EventEmitter). * `cwd` {String} Current working directory of the child process * `stdio` {Array|String} Child's stdio configuration. (See below) * `env` {Object} Environment key-value pairs - * `detached` {Boolean} The child will be a process group leader. (See below) + * `stdio` {Array|String} Child's stdio configuration. (See + [below](#child_process_options_stdio)) + * `customFds` {Array} **Deprecated** File descriptors for the child to use + for stdio. (See [below](#child_process_options_customFds)) + * `detached` {Boolean} The child will be a process group leader. (See + [below](#child_process_options_detached)) * `uid` {Number} Sets the user identity of the process. (See setuid(2).) * `gid` {Number} Sets the group identity of the process. (See setgid(2).) * return: {ChildProcess object} @@ -325,8 +372,11 @@ The third argument is used to specify additional options, with these defaults: env: process.env } -`cwd` allows you to specify the working directory from which the process is spawned. -Use `env` to specify environment variables that will be visible to the new process. +Use `cwd` to specify the working directory from which the process is spawned. +If not given, the default is to inherit the current working directory. + +Use `env` to specify environment variables that will be visible to the new +process, the default is `process.env`. Example of running `ls -lh /usr`, capturing `stdout`, `stderr`, and the exit code: @@ -382,16 +432,16 @@ Example: A very elaborate way to run 'ps ax | grep ssh' }); -Example of checking for failed exec: +### options.stdio - var spawn = require('child_process').spawn, - child = spawn('bad_command'); +As a shorthand, the `stdio` argument may also be one of the following +strings: - child.on('error', function (err) { - console.log('Failed to start child process.'); - }); +* `'pipe'` - `['pipe', 'pipe', 'pipe']`, this is the default value +* `'ignore'` - `['ignore', 'ignore', 'ignore']` +* `'inherit'` - `[process.stdin, process.stdout, process.stderr]` or `[0,1,2]` -The 'stdio' option to `child_process.spawn()` is an array where each +Otherwise, the 'stdio' option to `child_process.spawn()` is an array where each index corresponds to a fd in the child. The value is one of the following: 1. `'pipe'` - Create a pipe between the child process and the parent process. @@ -422,13 +472,6 @@ index corresponds to a fd in the child. The value is one of the following: words, stdin, stdout, and stderr) a pipe is created. For fd 3 and up, the default is `'ignore'`. -As a shorthand, the `stdio` argument may also be one of the following -strings, rather than an array: - -* `ignore` - `['ignore', 'ignore', 'ignore']` -* `pipe` - `['pipe', 'pipe', 'pipe']` -* `inherit` - `[process.stdin, process.stdout, process.stderr]` or `[0,1,2]` - Example: var spawn = require('child_process').spawn; @@ -443,6 +486,8 @@ Example: // startd-style interface. spawn('prg', [], { stdio: ['pipe', null, null, null, 'pipe'] }); +### options.detached + If the `detached` option is set, the child process will be made the leader of a new process group. This makes it possible for the child to continue running after the parent exits. @@ -471,6 +516,15 @@ will not stay running in the background unless it is provided with a `stdio` configuration that is not connected to the parent. If the parent's `stdio` is inherited, the child will remain attached to the controlling terminal. +### options.customFds + +There is a deprecated option called `customFds` which allows one to specify +specific file descriptors for the stdio of the child process. This API was +not portable to all platforms and therefore removed. +With `customFds` it was possible to hook up the new process' `[stdin, stdout, +stderr]` to existing streams; `-1` meant that a new stream should be created. +Use at your own risk. + See also: `child_process.exec()` and `child_process.fork()` ### child_process.exec(command[, options], callback) @@ -562,7 +616,6 @@ leaner than `child_process.exec`. It has the same options. * `options` {Object} * `cwd` {String} Current working directory of the child process * `env` {Object} Environment key-value pairs - * `encoding` {String} (Default: 'utf8') * `execPath` {String} Executable used to create the child process * `execArgv` {Array} List of string arguments passed to the executable (Default: `process.execArgv`) diff --git a/doc/api/crypto.markdown b/doc/api/crypto.markdown index b6dcf4612..a9fad8cd8 100644 --- a/doc/api/crypto.markdown +++ b/doc/api/crypto.markdown @@ -191,6 +191,16 @@ written data is used to compute the hash. Once the writable side of the stream is ended, use the `read()` method to get the enciphered contents. The legacy `update` and `final` methods are also supported. +Note: `createCipher` derives keys with the OpenSSL function [EVP_BytesToKey][] +with the digest algorithm set to MD5, one iteration, and no salt. The lack of +salt allows dictionary attacks as the same password always creates the same key. +The low iteration count and non-cryptographically secure hash algorithm allow +passwords to be tested very rapidly. + +In line with OpenSSL's recommendation to use pbkdf2 instead of EVP_BytesToKey it +is recommended you derive a key and iv yourself with [crypto.pbkdf2][] and to +then use [createCipheriv()][] to create the cipher stream. + ## crypto.createCipheriv(algorithm, key, iv) Creates and returns a cipher object, with the given algorithm, key and @@ -756,3 +766,5 @@ temporary measure. [diffieHellman.setPublicKey()]: #crypto_diffiehellman_setpublickey_public_key_encoding [RFC 2412]: http://www.rfc-editor.org/rfc/rfc2412.txt [RFC 3526]: http://www.rfc-editor.org/rfc/rfc3526.txt +[crypto.pbkdf2]: #crypto_crypto_pbkdf2_password_salt_iterations_keylen_callback +[EVP_BytesToKey]: https://www.openssl.org/docs/crypto/EVP_BytesToKey.html
\ No newline at end of file diff --git a/doc/api/dns.markdown b/doc/api/dns.markdown index d080d6661..1c4434467 100644 --- a/doc/api/dns.markdown +++ b/doc/api/dns.markdown @@ -2,10 +2,13 @@ Stability: 3 - Stable -Use `require('dns')` to access this module. All methods in the dns module -use C-Ares except for `dns.lookup` which uses `getaddrinfo(3)` in a thread -pool. C-Ares is much faster than `getaddrinfo` but the system resolver is -more consistent with how other programs operate. When a user does +Use `require('dns')` to access this module. All methods in the dns module use +C-Ares except for `dns.lookup` which uses `getaddrinfo(3)` in a thread pool. +C-Ares is much faster than `getaddrinfo(3)` but, due to the way it is +configured by node, it doesn't use the same set of system configuration files. +For instance, _C- Ares will not use the configuration from `/etc/hosts`_. As a +result, __only `dns.lookup` should be expected to behave like other programs +running on the same system regarding name resolution.__ When a user does `net.connect(80, 'google.com')` or `http.get({ host: 'google.com' })` the `dns.lookup` method is used. Users who need to do a large number of lookups quickly should use the methods that go through C-Ares. diff --git a/doc/api/https.markdown b/doc/api/https.markdown index 464677e01..12c0e8a30 100644 --- a/doc/api/https.markdown +++ b/doc/api/https.markdown @@ -134,8 +134,8 @@ The following options from [tls.connect()][] can also be specified. However, a the list of supplied CAs. An `'error'` event is emitted if verification fails. Verification happens at the connection level, *before* the HTTP request is sent. Default `true`. -- `secureProtocol`: The SSL method to use, e.g. `SSLv3_method` to force - SSL version 3. The possible values depend on your installation of +- `secureProtocol`: The SSL method to use, e.g. `TLSv1_method` to force + TLS version 1. The possible values depend on your installation of OpenSSL and are defined in the constant [SSL_METHODS][]. In order to specify these options, use a custom `Agent`. diff --git a/doc/api/net.markdown b/doc/api/net.markdown index 380f3458e..f1fdf99d0 100644 --- a/doc/api/net.markdown +++ b/doc/api/net.markdown @@ -33,9 +33,9 @@ on port 8124: var net = require('net'); var server = net.createServer(function(c) { //'connection' listener - console.log('server connected'); + console.log('client connected'); c.on('end', function() { - console.log('server disconnected'); + console.log('client disconnected'); }); c.write('hello\r\n'); c.pipe(c); @@ -98,7 +98,7 @@ Here is an example of a client of echo server as described previously: var net = require('net'); var client = net.connect({port: 8124}, function() { //'connect' listener - console.log('client connected'); + console.log('connected to server!'); client.write('world!\r\n'); }); client.on('data', function(data) { @@ -106,7 +106,7 @@ Here is an example of a client of echo server as described previously: client.end(); }); client.on('end', function() { - console.log('client disconnected'); + console.log('disconnected from server'); }); To connect on the socket `/tmp/echo.sock` the second line would just be diff --git a/doc/api/process.markdown b/doc/api/process.markdown index ba0032509..de2439506 100644 --- a/doc/api/process.markdown +++ b/doc/api/process.markdown @@ -172,7 +172,7 @@ emulation with `process.kill()`, and `child_process.kill()`: ## process.stdout -A `Writable Stream` to `stdout`. +A `Writable Stream` to `stdout` (on fd `1`). Example: the definition of `console.log` @@ -207,7 +207,7 @@ See [the tty docs](tty.html#tty_tty) for more information. ## process.stderr -A writable stream to stderr. +A writable stream to stderr (on fd `2`). `process.stderr` and `process.stdout` are unlike other streams in Node in that they cannot be closed (`end()` will throw), they never emit the `finish` @@ -222,7 +222,7 @@ event and that writes are usually blocking. ## process.stdin -A `Readable Stream` for stdin. +A `Readable Stream` for stdin (on fd `0`). Example of opening standard input and listening for both events: diff --git a/doc/api/stream.markdown b/doc/api/stream.markdown index 5ffcef914..1029c43c9 100644 --- a/doc/api/stream.markdown +++ b/doc/api/stream.markdown @@ -585,11 +585,10 @@ Calling [`write()`][] after calling [`end()`][] will raise an error. ```javascript // write 'hello, ' and then end with 'world!' -http.createServer(function (req, res) { - res.write('hello, '); - res.end('world!'); - // writing more now is not allowed! -}); +var file = fs.createWriteStream('example.txt'); +file.write('hello, '); +file.end('world!'); +// writing more now is not allowed! ``` #### Event: 'finish' @@ -1156,7 +1155,7 @@ initialized. * `encoding` {String} If the chunk is a string, then this is the encoding type. (Ignore if `decodeStrings` chunk is a buffer.) * `callback` {Function} Call this function (optionally with an error - argument) when you are done processing the supplied chunk. + argument and data) when you are done processing the supplied chunk. Note: **This function MUST NOT be called directly.** It should be implemented by child classes, and called by the internal Transform @@ -1176,7 +1175,20 @@ as a result of this chunk. Call the callback function only when the current chunk is completely consumed. Note that there may or may not be output as a result of any -particular input chunk. +particular input chunk. If you supply as the second argument to the +it will be passed to push method, in other words the following are +equivalent: + +```javascript +transform.prototype._transform = function (data, encoding, callback) { + this.push(data); + callback(); +} + +transform.prototype._transform = function (data, encoding, callback) { + callback(null, data); +} +``` This method is prefixed with an underscore because it is internal to the class that defines it, and should not be called directly by user diff --git a/doc/api/tls.markdown b/doc/api/tls.markdown index c03845e87..9316dacdb 100644 --- a/doc/api/tls.markdown +++ b/doc/api/tls.markdown @@ -10,14 +10,14 @@ Secure Socket Layer: encrypted stream communication. TLS/SSL is a public/private key infrastructure. Each client and each server must have a private key. A private key is created like this: - openssl genrsa -out ryans-key.pem 1024 + openssl genrsa -out ryans-key.pem 2048 All servers and some clients need to have a certificate. Certificates are public keys signed by a Certificate Authority or self-signed. The first step to getting a certificate is to create a "Certificate Signing Request" (CSR) file. This is done with: - openssl req -new -key ryans-key.pem -out ryans-csr.pem + openssl req -new -sha256 -key ryans-key.pem -out ryans-csr.pem To create a self-signed certificate with the CSR, do this: @@ -38,6 +38,40 @@ To create .pfx or .p12, do this: - `certfile`: all CA certs concatenated in one file like `cat ca1-cert.pem ca2-cert.pem > ca-cert.pem` +## Protocol support + +Node.js is compiled with SSLv2 and SSLv3 protocol support by default, but these +protocols are **disabled**. They are considered insecure and could be easily +compromised as was shown by [CVE-2014-3566][]. However, in some situations, it +may cause problems with legacy clients/servers (such as Internet Explorer 6). +If you wish to enable SSLv2 or SSLv3, run node with the `--enable-ssl2` or +`--enable-ssl3` flag respectively. In future versions of Node.js SSLv2 and +SSLv3 will not be compiled in by default. + +There is a way to force node into using SSLv3 or SSLv2 only mode by explicitly +specifying `secureProtocol` to `'SSLv3_method'` or `'SSLv2_method'`. + +The default protocol method Node.js uses is `SSLv23_method` which would be more +accurately named `AutoNegotiate_method`. This method will try and negotiate +from the highest level down to whatever the client supports. To provide a +secure default, Node.js (since v0.10.33) explicitly disables the use of SSLv3 +and SSLv2 by setting the `secureOptions` to be +`SSL_OP_NO_SSLv3|SSL_OP_NO_SSLv2` (again, unless you have passed +`--enable-ssl3`, or `--enable-ssl2`, or `SSLv3_method` as `secureProtocol`). + +If you have set `secureOptions` to anything, we will not override your +options. + +The ramifications of this behavior change: + + * If your application is behaving as a secure server, clients who are `SSLv3` +only will now not be able to appropriately negotiate a connection and will be +refused. In this case your server will emit a `clientError` event. The error +message will include `'wrong version number'`. + * If your application is behaving as a secure client and communicating with a +server that doesn't support methods more secure than SSLv3 then your connection +won't be able to negotiate and will fail. In this case your client will emit a +an `error` event. The error message will include `'wrong version number'`. ## Client-initiated renegotiation attack mitigation @@ -229,6 +263,10 @@ automatically set as a listener for the [secureConnection][] event. The SSL version 3. The possible values depend on your installation of OpenSSL and are defined in the constant [SSL_METHODS][]. + - `secureOptions`: Set server options. For example, to disable the SSLv3 + protocol set the `SSL_OP_NO_SSLv3` flag. See [SSL_CTX_set_options] + for all available options. + Here is a simple example echo server: var tls = require('tls'); @@ -815,3 +853,4 @@ The numeric representation of the local port. [ECDHE]: https://en.wikipedia.org/wiki/Elliptic_curve_Diffie%E2%80%93Hellman [asn1.js]: http://npmjs.org/package/asn1.js [OCSP request]: http://en.wikipedia.org/wiki/OCSP_stapling +[CVE-2014-3566]: https://access.redhat.com/articles/1232123 diff --git a/doc/api/url.markdown b/doc/api/url.markdown index 3ace69957..e8749b46c 100644 --- a/doc/api/url.markdown +++ b/doc/api/url.markdown @@ -82,6 +82,8 @@ Pass `true` as the third argument to treat `//foo/bar` as Take a parsed URL object, and return a formatted URL string. +Here's how the formatting process works: + * `href` will be ignored. * `protocol` is treated the same with or without the trailing `:` (colon). * The protocols `http`, `https`, `ftp`, `gopher`, `file` will be @@ -97,9 +99,9 @@ Take a parsed URL object, and return a formatted URL string. * `host` will be used in place of `hostname` and `port` * `pathname` is treated the same with or without the leading `/` (slash). * `path` is treated the same with `pathname` but able to contain `query` as well. -* `search` will be used in place of `query`. * `query` (object; see `querystring`) will only be used if `search` is absent. -* `search` is treated the same with or without the leading `?` (question mark). +* `search` will be used in place of `query`. + * It is treated the same with or without the leading `?` (question mark) * `hash` is treated the same with or without the leading `#` (pound sign, anchor). ## url.resolve(from, to) |