diff --git a/doc/api/crypto.md b/doc/api/crypto.md index e1166230d719c6..e195c98e322746 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): - -* `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` +is a bit field taking one of or a mix of the following flags (defined in +`crypto.constants`): + +* `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 e752a1b33dde94..bd975732c67987 100644 --- a/doc/api/fs.md +++ b/doc/api/fs.md @@ -315,13 +315,13 @@ 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` - `path` is visible to the calling process. This is useful +- `fs.constants.F_OK` - `path` 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` - `path` can be read by the calling process. -- `fs.W_OK` - `path` can be written by the calling process. -- `fs.X_OK` - `path` can be executed by the calling process. This has -no effect on Windows (will behave like `fs.F_OK`). +- `fs.constants.R_OK` - `path` can be read by the calling process. +- `fs.constants.W_OK` - `path` can be written by the calling process. +- `fs.constants.X_OK` - `path` 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 @@ -329,7 +329,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'); }); ``` @@ -342,8 +342,8 @@ added: v0.11.15 * `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) - Stability: 0 - Deprecated: Use [`fs.statSync()`][] or [`fs.accessSync()`][] instead. + Stability: 0 - Deprecated: Use [`fs.statSync()`][] or [`fs.accessSync()`][] + instead. * `path` {String | Buffer} @@ -991,7 +999,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. @@ -1294,11 +1302,11 @@ added: v0.1.31 * `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: @@ -1543,9 +1551,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)