diff --git a/doc/api/crypto.md b/doc/api/crypto.md index e84c10dfa4..aac0c6eed6 100644 --- a/doc/api/crypto.md +++ b/doc/api/crypto.md @@ -856,6 +856,12 @@ thrown. ## `crypto` module methods and properties +## crypto.constants + +Returns an object containing commonly used constants for crypto and security +related operations. The specific constants currently defined are described in +[Crypto Constants][]. + ### crypto.DEFAULT_ENCODING The default encoding to use for functions that can take either strings @@ -1205,11 +1211,11 @@ keys: * `key` : {String} - PEM encoded private key * `passphrase` : {String} - Optional passphrase for the private key * `padding` : An optional padding value, one of the following: - * `constants.RSA_NO_PADDING` - * `constants.RSA_PKCS1_PADDING` - * `constants.RSA_PKCS1_OAEP_PADDING` + * `crypto.constants.RSA_NO_PADDING` + * `crypto.constants.RSA_PKCS1_PADDING` + * `crypto.constants.RSA_PKCS1_OAEP_PADDING` -All paddings are defined in the `constants` module. +All paddings are defined in `crypto.constants`. ### crypto.privateEncrypt(private_key, buffer) @@ -1223,11 +1229,11 @@ keys: * `key` : {String} - PEM encoded private key * `passphrase` : {String} - Optional passphrase for the private key * `padding` : An optional padding value, one of the following: - * `constants.RSA_NO_PADDING` - * `constants.RSA_PKCS1_PADDING` - * `constants.RSA_PKCS1_OAEP_PADDING` + * `crypto.constants.RSA_NO_PADDING` + * `crypto.constants.RSA_PKCS1_PADDING` + * `crypto.constants.RSA_PKCS1_OAEP_PADDING` -All paddings are defined in the `constants` module. +All paddings are defined in `crypto.constants`. ### crypto.publicDecrypt(public_key, buffer) @@ -1241,14 +1247,14 @@ keys: * `key` : {String} - PEM encoded public key * `passphrase` : {String} - Optional passphrase for the private key * `padding` : An optional padding value, one of the following: - * `constants.RSA_NO_PADDING` - * `constants.RSA_PKCS1_PADDING` - * `constants.RSA_PKCS1_OAEP_PADDING` + * `crypto.constants.RSA_NO_PADDING` + * `crypto.constants.RSA_PKCS1_PADDING` + * `crypto.constants.RSA_PKCS1_OAEP_PADDING` Because RSA public keys can be derived from private keys, a private key may be passed instead of a public key. -All paddings are defined in the `constants` module. +All paddings are defined in `crypto.constants`. ### crypto.publicEncrypt(public_key, buffer) @@ -1262,14 +1268,14 @@ keys: * `key` : {String} - PEM encoded public key * `passphrase` : {String} - Optional passphrase for the private key * `padding` : An optional padding value, one of the following: - * `constants.RSA_NO_PADDING` - * `constants.RSA_PKCS1_PADDING` - * `constants.RSA_PKCS1_OAEP_PADDING` + * `crypto.constants.RSA_NO_PADDING` + * `crypto.constants.RSA_PKCS1_PADDING` + * `crypto.constants.RSA_PKCS1_OAEP_PADDING` Because RSA public keys can be derived from private keys, a private key may be passed instead of a public key. -All paddings are defined in the `constants` module. +All paddings are defined in `crypto.constants`. ### crypto.randomBytes(size[, callback]) @@ -1313,22 +1319,22 @@ Load and set the `engine` for some or all OpenSSL functions (selected by flags). `engine` could be either an id or a path to the engine's shared library. The optional `flags` argument uses `ENGINE_METHOD_ALL` by default. The `flags` -is a bit field taking one of or a mix of the following flags (defined in the -`constants` module): +is a bit field taking one of or a mix of the following flags (defined in +`crypto.constants`): -* `ENGINE_METHOD_RSA` -* `ENGINE_METHOD_DSA` -* `ENGINE_METHOD_DH` -* `ENGINE_METHOD_RAND` -* `ENGINE_METHOD_ECDH` -* `ENGINE_METHOD_ECDSA` -* `ENGINE_METHOD_CIPHERS` -* `ENGINE_METHOD_DIGESTS` -* `ENGINE_METHOD_STORE` -* `ENGINE_METHOD_PKEY_METHS` -* `ENGINE_METHOD_PKEY_ASN1_METHS` -* `ENGINE_METHOD_ALL` -* `ENGINE_METHOD_NONE` +* `crypto.constants.ENGINE_METHOD_RSA` +* `crypto.constants.ENGINE_METHOD_DSA` +* `crypto.constants.ENGINE_METHOD_DH` +* `crypto.constants.ENGINE_METHOD_RAND` +* `crypto.constants.ENGINE_METHOD_ECDH` +* `crypto.constants.ENGINE_METHOD_ECDSA` +* `crypto.constants.ENGINE_METHOD_CIPHERS` +* `crypto.constants.ENGINE_METHOD_DIGESTS` +* `crypto.constants.ENGINE_METHOD_STORE` +* `crypto.constants.ENGINE_METHOD_PKEY_METHS` +* `crypto.constants.ENGINE_METHOD_PKEY_ASN1_METHS` +* `crypto.constants.ENGINE_METHOD_ALL` +* `crypto.constants.ENGINE_METHOD_NONE` ## Notes @@ -1380,6 +1386,316 @@ Based on the recommendations of [NIST SP 800-131A][]: See the reference for other recommendations and details. +## Crypto Constants + +The following constants exported by `crypto.constants` apply to various uses of +the `crypto`, `tls`, and `https` modules and are generally specific to OpenSSL. + +### OpenSSL Options + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ConstantDescription
SSL_OP_ALLApplies multiple bug workarounds within OpenSSL. See + https://www.openssl.org/docs/manmaster/ssl/SSL_CTX_set_options.html for + detail.
SSL_OP_ALLOW_UNSAFE_LEGACY_RENEGOTIATIONAllows legacy insecure renegotiation between OpenSSL and unpatched + clients or servers. See + https://www.openssl.org/docs/manmaster/ssl/SSL_CTX_set_options.html.
SSL_OP_CIPHER_SERVER_PREFERENCEUses the server's preferences instead of the clients when selecting a + cipher. See + https://www.openssl.org/docs/manmaster/ssl/SSL_CTX_set_options.html.
SSL_OP_CISCO_ANYCONNECTInstructs OpenSSL to use Cisco's "speshul" version of DTLS_BAD_VER.
SSL_OP_COOKIE_EXCHANGEInstructs OpenSSL to turn on cookie exchange.
SSL_OP_CRYPTOPRO_TLSEXT_BUGInstructs OpenSSL to add server-hello extension from an early version + of the cryptopro draft.
SSL_OP_DONT_INSERT_EMPTY_FRAGMENTSInstructs OpenSSL to disable a SSL 3.0/TLS 1.0 vulnerability + workaround added in OpenSSL 0.9.6d.
SSL_OP_EPHEMERAL_RSAInstructs OpenSSL to always use the tmp_rsa key when performing RSA + operations.
SSL_OP_LEGACY_SERVER_CONNECTAllow initial connection to servers that do not support RI.
SSL_OP_MICROSOFT_BIG_SSLV3_BUFFER
SSL_OP_MICROSOFT_SESS_ID_BUG
SSL_OP_MSIE_SSLV2_RSA_PADDINGInstructs OpenSSL to disable the workaround for a man-in-the-middle + protocol-version vulnerability in the SSL 2.0 server implementation.
SSL_OP_NETSCAPE_CA_DN_BUG
SSL_OP_NETSCAPE_CHALLENGE_BUG
SSL_OP_NETSCAPE_DEMO_CIPHER_CHANGE_BUG
SSL_OP_NETSCAPE_REUSE_CIPHER_CHANGE_BUG
SSL_OP_NO_COMPRESSIONInstructs OpenSSL to disable support for SSL/TLS compression.
SSL_OP_NO_QUERY_MTU
SSL_OP_NO_SESSION_RESUMPTION_ON_RENEGOTIATIONInstructs OpenSSL to always start a new session when performing + renegotiation.
SSL_OP_NO_SSLv2Instructs OpenSSL to turn off SSL v2
SSL_OP_NO_SSLv3Instructs OpenSSL to turn off SSL v3
SSL_OP_NO_TICKETInstructs OpenSSL to disable use of RFC4507bis tickets.
SSL_OP_NO_TLSv1Instructs OpenSSL to turn off TLS v1
SSL_OP_NO_TLSv1_1Instructs OpenSSL to turn off TLS v1.1
SSL_OP_NO_TLSv1_2Instructs OpenSSL to turn off TLS v1.2
SSL_OP_PKCS1_CHECK_1
SSL_OP_PKCS1_CHECK_2
SSL_OP_SINGLE_DH_USEInstructs OpenSSL to always create a new key when using + temporary/ephemeral DH parameters.
SSL_OP_SINGLE_ECDH_USEInstructs OpenSSL to always create a new key when using + temporary/ephemeral ECDH parameters.
SSL_OP_SSLEAY_080_CLIENT_DH_BUG
SSL_OP_SSLREF2_REUSE_CERT_TYPE_BUG
SSL_OP_TLS_BLOCK_PADDING_BUG
SSL_OP_TLS_D5_BUG
SSL_OP_TLS_ROLLBACK_BUGInstructs OpenSSL to disable version rollback attack detection.
+ +### OpenSSL Engine Constants + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ConstantDescription
ENGINE_METHOD_RSALimit engine usage to RSA
ENGINE_METHOD_DSALimit engine usage to DSA
ENGINE_METHOD_DHLimit engine usage to DH
ENGINE_METHOD_RANDLimit engine usage to RAND
ENGINE_METHOD_ECDHLimit engine usage to ECDH
ENGINE_METHOD_ECDSALimit engine usage to ECDSA
ENGINE_METHOD_CIPHERSLimit engine usage to CIPHERS
ENGINE_METHOD_DIGESTSLimit engine usage to DIGESTS
ENGINE_METHOD_STORELimit engine usage to STORE
ENGINE_METHOD_PKEY_METHSLimit engine usage to PKEY_METHDS
ENGINE_METHOD_PKEY_ASN1_METHSLimit engine usage to PKEY_ASN1_METHS
ENGINE_METHOD_ALL
ENGINE_METHOD_NONE
+ +### Other OpenSSL Constants + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ConstantDescription
DH_CHECK_P_NOT_SAFE_PRIME
DH_CHECK_P_NOT_PRIME
DH_UNABLE_TO_CHECK_GENERATOR
DH_NOT_SUITABLE_GENERATOR
NPN_ENABLED
ALPN_ENABLED
RSA_PKCS1_PADDING
RSA_SSLV23_PADDING
RSA_NO_PADDING
RSA_PKCS1_OAEP_PADDING
RSA_X931_PADDING
RSA_PKCS1_PSS_PADDING
POINT_CONVERSION_COMPRESSED
POINT_CONVERSION_UNCOMPRESSED
POINT_CONVERSION_HYBRID
+ +### Node.js Crypto Constants + + + + + + + + + + + + + + +
ConstantDescription
defaultCoreCipherListSpecifies the built-in default cipher list used by Node.js.
defaultCipherListSpecifies the active default cipher list used by the current Node.js + process.
+ + [`Buffer`]: buffer.html [`cipher.final()`]: #crypto_cipher_final_output_encoding [`cipher.update()`]: #crypto_cipher_update_data_input_encoding_output_encoding @@ -1423,3 +1739,4 @@ See the reference for other recommendations and details. [RFC 3526]: https://www.rfc-editor.org/rfc/rfc3526.txt [stream]: stream.html [stream-writable-write]: stream.html#stream_writable_write_chunk_encoding_callback +[Crypto Constants]: #crypto_crypto_constants diff --git a/doc/api/fs.md b/doc/api/fs.md index f3c74d3885..9ecd61b1b6 100644 --- a/doc/api/fs.md +++ b/doc/api/fs.md @@ -266,13 +266,13 @@ optional integer that specifies the accessibility checks to be performed. The following constants define the possible values of `mode`. It is possible to create a mask consisting of the bitwise OR of two or more values. -- `fs.F_OK` - File is visible to the calling process. This is useful for -determining if a file exists, but says nothing about `rwx` permissions. +- `fs.constants.F_OK` - File is visible to the calling process. This is useful +for determining if a file exists, but says nothing about `rwx` permissions. Default if no `mode` is specified. -- `fs.R_OK` - File can be read by the calling process. -- `fs.W_OK` - File can be written by the calling process. -- `fs.X_OK` - File can be executed by the calling process. This has no effect -on Windows (will behave like `fs.F_OK`). +- `fs.constants.R_OK` - File can be read by the calling process. +- `fs.constants.W_OK` - File can be written by the calling process. +- `fs.constants.X_OK` - File can be executed by the calling process. This has no +effect on Windows (will behave like `fs.constants.F_OK`). The final argument, `callback`, is a callback function that is invoked with a possible error argument. If any of the accessibility checks fail, the error @@ -280,7 +280,7 @@ argument will be populated. The following example checks if the file `/etc/passwd` can be read and written by the current process. ```js -fs.access('/etc/passwd', fs.R_OK | fs.W_OK, (err) => { +fs.access('/etc/passwd', fs.constants.R_OK | fs.constants.W_OK, (err) => { console.log(err ? 'no access!' : 'can read/write'); }); ``` @@ -290,8 +290,8 @@ fs.access('/etc/passwd', fs.R_OK | fs.W_OK, (err) => { * `path` {String | Buffer} * `mode` {Integer} -Synchronous version of [`fs.access()`][]. This throws if any accessibility checks -fail, and does nothing otherwise. +Synchronous version of [`fs.access()`][]. This throws if any accessibility +checks fail, and does nothing otherwise. ## fs.appendFile(file, data[, options], callback) @@ -384,6 +384,12 @@ to the completion callback. Synchronous close(2). Returns `undefined`. +## fs.constants + +Returns an object containing commonly used constants for file system +operations. The specific constants currently defined are described in +[FS Constants][]. + ## fs.createReadStream(path[, options]) * `path` {String | Buffer} @@ -419,9 +425,9 @@ the file instead of the entire file. Both `start` and `end` are inclusive and start at 0. The `encoding` can be any one of those accepted by [`Buffer`][]. If `fd` is specified, `ReadStream` will ignore the `path` argument and will use -the specified file descriptor. This means that no `'open'` event will be emitted. -Note that `fd` should be blocking; non-blocking `fd`s should be passed to -[`net.Socket`][]. +the specified file descriptor. This means that no `'open'` event will be +emitted. Note that `fd` should be blocking; non-blocking `fd`s should be passed +to [`net.Socket`][]. If `autoClose` is false, then the file descriptor won't be closed, even if there's an error. It is your responsibility to close it and make sure @@ -468,7 +474,8 @@ Returns a new [`WriteStream`][] object. (See [Writable Stream][]). `options` may also include a `start` option to allow writing data at some position past the beginning of the file. Modifying a file rather than replacing it may require a `flags` mode of `r+` rather than the -default mode `w`. The `defaultEncoding` can be any one of those accepted by [`Buffer`][]. +default mode `w`. The `defaultEncoding` can be any one of those accepted by +[`Buffer`][]. If `autoClose` is set to true (default behavior) on `error` or `end` the file descriptor will be closed automatically. If `autoClose` is false, @@ -507,7 +514,8 @@ non-existent. ## fs.existsSync(path) - Stability: 0 - Deprecated: Use [`fs.statSync()`][] or [`fs.accessSync()`][] instead. + Stability: 0 - Deprecated: Use [`fs.statSync()`][] or [`fs.accessSync()`][] + instead. * `path` {String | Buffer} @@ -789,7 +797,7 @@ to a non-existent file. The exclusive flag may or may not work with network file systems. `flags` can also be a number as documented by open(2); commonly used constants -are available from `require('constants')`. On Windows, flags are translated to +are available from `fs.constants`. On Windows, flags are translated to their equivalent ones where applicable, e.g. `O_WRONLY` to `FILE_GENERIC_WRITE`, or `O_EXCL|O_CREAT` to `CREATE_NEW`, as accepted by CreateFileW. @@ -1038,11 +1046,11 @@ Synchronous stat(2). Returns an instance of [`fs.Stats`][]. * `callback` {Function} Asynchronous symlink(2). No arguments other than a possible exception are given -to the completion callback. -The `type` argument can be set to `'dir'`, `'file'`, or `'junction'` (default -is `'file'`) and is only available on Windows (ignored on other platforms). -Note that Windows junction points require the destination path to be absolute. When using -`'junction'`, the `target` argument will automatically be normalized to absolute path. +to the completion callback. The `type` argument can be set to `'dir'`, +`'file'`, or `'junction'` (default is `'file'`) and is only available on +Windows (ignored on other platforms). Note that Windows junction points require +the destination path to be absolute. When using `'junction'`, the `target` +argument will automatically be normalized to absolute path. Here is an example below: @@ -1255,9 +1263,9 @@ _Note: when an `fs.watchFile` operation results in an `ENOENT` error, it will of zero. If the file is created later on, the listener will be called again, with the latest stat objects. This is a change in functionality since v0.10._ -_Note: [`fs.watch()`][] is more efficient than `fs.watchFile` and `fs.unwatchFile`. -`fs.watch` should be used instead of `fs.watchFile` and `fs.unwatchFile` -when possible._ +_Note: [`fs.watch()`][] is more efficient than `fs.watchFile` and +`fs.unwatchFile`. `fs.watch` should be used instead of `fs.watchFile` and +`fs.unwatchFile` when possible._ ## fs.write(fd, buffer, offset, length[, position], callback) @@ -1387,6 +1395,226 @@ The synchronous version of [`fs.writeFile()`][]. Returns `undefined`. Synchronous versions of [`fs.write()`][]. Returns the number of bytes written. +## FS Constants + +The following constants are exported by `fs.constants`. **Note:** Not every +constant will be available on every operating system. + +### File Access Constants + +The following constants are meant for use with [`fs.access()`][]. + + + + + + + + + + + + + + + + + + + + + + +
ConstantDescription
F_OKFlag indicating that the file is visible to the calling process.
R_OKFlag indicating that the file can be read by the calling process.
W_OKFlag indicating that the file can be written by the calling + process.
X_OKFlag indicating that the file can be executed by the calling + process.
+ +### File Open Constants + +The following constants are meant for use with `fs.open()`. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ConstantDescription
O_RDONLYFlag indicating to open a file for read-only access.
O_WRONLYFlag indicating to open a file for write-only access.
O_RDWRFlag indicating to open a file for read-write access.
O_CREATFlag indicating to create the file if it does not already exist.
O_EXCLFlag indicating that opening a file should fail if the + O_CREAT flag is set and the file already exists.
O_NOCTTYFlag indicating that if path identifies a terminal device, opening the + path shall not cause that terminal to become the controlling terminal for + the process (if the process does not already have one).
O_TRUNCFlag indicating that if the file exists and is a regular file, and the + file is opened successfully for write access, its length shall be truncated + to zero.
O_APPENDFlag indicating that data will be appended to the end of the file.
O_DIRECTORYFlag indicating that the open should fail if the path is not a + directory.
O_NOATIMEFlag indicating reading accesses to the file system will no longer + result in an update to the `atime` information associated with the file. + This flag is available on Linux operating systems only.
O_NOFOLLOWFlag indicating that the open should fail if the path is a symbolic + link.
O_SYNCFlag indicating that the file is opened for synchronous I/O.
O_SYMLINKFlag indicating to open the symbolic link itself rather than the + resource it is pointing to.
O_DIRECTWhen set, an attempt will be made to minimize caching effects of file + I/O.
O_NONBLOCKFlag indicating to open the file in nonblocking mode when possible.
+ +### File Type Constants + +The following constants are meant for use with the [`fs.Stats`][] object's +`mode` property for determining a file's type. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ConstantDescription
S_IFMTBit mask used to extract the file type code.
S_IFREGFile type constant for a regular file.
S_IFDIRFile type constant for a directory.
S_IFCHRFile type constant for a character-oriented device file.
S_IFBLKFile type constant for a block-oriented device file.
S_IFIFOFile type constant for a FIFO/pipe.
S_IFLNKFile type constant for a symbolic link.
S_IFSOCKFile type constant for a socket.
+ +### File Mode Constants + +The following constants are meant for use with the [`fs.Stats`][] object's +`mode` property for determining the access permissions for a file. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ConstantDescription
S_IRWXUFile mode indicating readable, writable and executable by owner.
S_IRUSRFile mode indicating readable by owner.
S_IWUSRFile mode indicating writable by owner.
S_IXUSRFile mode indicating executable by owner.
S_IRWXGFile mode indicating readable, writable and executable by group.
S_IRGRPFile mode indicating readable by group.
S_IWGRPFile mode indicating writable by group.
S_IXGRPFile mode indicating executable by group.
S_IRWXOFile mode indicating readable, writable and executable by others.
S_IROTHFile mode indicating readable by others.
S_IWOTHFile mode indicating writable by others.
S_IXOTHFile mode indicating executable by others.
+ [`Buffer.byteLength`]: buffer.html#buffer_class_method_buffer_bytelength_string_encoding [`Buffer`]: buffer.html#buffer_buffer [Caveats]: #fs_caveats @@ -1418,3 +1646,4 @@ Synchronous versions of [`fs.write()`][]. Returns the number of bytes written. [Readable Stream]: stream.html#stream_class_stream_readable [Writable Stream]: stream.html#stream_class_stream_writable [inode]: http://www.linux.org/threads/intro-to-inodes.4130 +[FS Constants]: #fs_fs_constants diff --git a/doc/api/os.md b/doc/api/os.md index 7e92f2bf43..59ed110666 100644 --- a/doc/api/os.md +++ b/doc/api/os.md @@ -22,6 +22,12 @@ added: v0.5.0 Returns the operating system CPU architecture. Possible values are `'x64'`, `'arm'` and `'ia32'`. Returns the value of [`process.arch`][]. +## os.constants + +Returns an object containing commonly used operating system specific constants +for error codes, process signals, and so on. The specific constants currently +defined are described in [OS Constants][]. + ## os.cpus()