From dc0323ca1f4820d2bd7a2e44d8a03cdf748ee814 Mon Sep 17 00:00:00 2001 From: Sam Roberts Date: Thu, 23 Apr 2015 19:33:38 +0900 Subject: [PATCH] doc: add tls.DEFAULT_ECDH_CURVE A user can change the default curve for ECDH key agreement by using tls.DEFAULT_ECDH_CURVE. PR-URL: https://github.com/nodejs/node/pull/10264 Reviewed-By: Roman Reiss Reviewed-By: Italo A. Casas Reviewed-By: Ben Noordhuis Reviewed-By: James M Snell Reviewed-By: Shigeki Ohtsu --- doc/api/tls.md | 62 +++++++++++++++++++++++++++++--------------------- 1 file changed, 36 insertions(+), 26 deletions(-) diff --git a/doc/api/tls.md b/doc/api/tls.md index fb90f776c94270..c33174f250479a 100644 --- a/doc/api/tls.md +++ b/doc/api/tls.md @@ -926,10 +926,10 @@ added: v0.11.13 *Note*: [`tls.createServer()`][] sets the default value to `true`, other APIs that create secure contexts leave it unset. * `ecdhCurve` {string} A string describing a named curve to use for ECDH key - agreement or `false` to disable ECDH. Defaults to `prime256v1` (NIST P-256). - Use [`crypto.getCurves()`][] to obtain a list of available curve names. On - recent releases, `openssl ecparam -list_curves` will also display the name - and description of each available elliptic curve. + agreement or `false` to disable ECDH. Defaults to + [`tls.DEFAULT_ECDH_CURVE`]. Use [`crypto.getCurves()`][] to obtain a list + of available curve names. On recent releases, `openssl ecparam -list_curves` + will also display the name and description of each available elliptic curve. * `dhparam` {string|Buffer} Diffie Hellman parameters, required for [Perfect Forward Secrecy][]. Use `openssl dhparam` to create the parameters. The key length must be greater than or equal to 1024 bits, otherwise an @@ -1077,6 +1077,13 @@ For example: console.log(tls.getCiphers()); // ['AES128-SHA', 'AES256-SHA', ...] ``` +## tls.DEFAULT_ECDH_CURVE + +The default curve name to use for ECDH key agreement in a tls server. The +default value is `'prime256v1'` (NIST P-256). Consult [RFC 4492] and +[FIPS.186-4] for more details. + + ## Deprecated APIs ### Class: CryptoStream @@ -1184,32 +1191,35 @@ secure_socket = tls.TLSSocket(socket, options); where `secure_socket` has the same API as `pair.cleartext`. -[OpenSSL cipher list format documentation]: https://www.openssl.org/docs/man1.0.2/apps/ciphers.html#CIPHER-LIST-FORMAT [Chrome's 'modern cryptography' setting]: https://www.chromium.org/Home/chromium-security/education/tls#TOC-Cipher-Suites -[OpenSSL Options]: crypto.html#crypto_openssl_options -[modifying the default cipher suite]: #tls_modifying_the_default_tls_cipher_suite -[specific attacks affecting larger AES key sizes]: https://www.schneier.com/blog/archives/2009/07/another_new_aes.html -[`crypto.getCurves()`]: crypto.html#crypto_crypto_getcurves -[`tls.createServer()`]: #tls_tls_createserver_options_secureconnectionlistener -[`tls.createSecurePair()`]: #tls_tls_createsecurepair_context_isserver_requestcert_rejectunauthorized_options -[`tls.TLSSocket`]: #tls_class_tls_tlssocket -[`net.Server`]: net.html#net_class_net_server -[`net.Socket`]: net.html#net_class_net_socket -[`net.Server.address()`]: net.html#net_server_address -[`'secureConnect'`]: #tls_event_secureconnect -[`'secureConnection'`]: #tls_event_secureconnection -[Perfect Forward Secrecy]: #tls_perfect_forward_secrecy -[Stream]: stream.html#stream_stream -[SSL_METHODS]: https://www.openssl.org/docs/man1.0.2/ssl/ssl.html#DEALING-WITH-PROTOCOL-METHODS -[tls.Server]: #tls_class_tls_server -[SSL_CTX_set_timeout]: https://www.openssl.org/docs/man1.0.2/ssl/SSL_CTX_set_timeout.html -[Forward secrecy]: https://en.wikipedia.org/wiki/Perfect_forward_secrecy [DHE]: https://en.wikipedia.org/wiki/Diffie%E2%80%93Hellman_key_exchange [ECDHE]: https://en.wikipedia.org/wiki/Elliptic_curve_Diffie%E2%80%93Hellman -[asn1.js]: https://npmjs.org/package/asn1.js +[FIPS.186-4]: http://nvlpubs.nist.gov/nistpubs/FIPS/NIST.FIPS.186-4.pdf +[Forward secrecy]: https://en.wikipedia.org/wiki/Perfect_forward_secrecy [OCSP request]: https://en.wikipedia.org/wiki/OCSP_stapling -[TLS recommendations]: https://wiki.mozilla.org/Security/Server_Side_TLS +[OpenSSL Options]: crypto.html#crypto_openssl_options +[OpenSSL cipher list format documentation]: https://www.openssl.org/docs/man1.0.2/apps/ciphers.html#CIPHER-LIST-FORMAT +[Perfect Forward Secrecy]: #tls_perfect_forward_secrecy +[RFC 4492]: https://www.rfc-editor.org/rfc/rfc4492.txt +[SSL_CTX_set_timeout]: https://www.openssl.org/docs/man1.0.2/ssl/SSL_CTX_set_timeout.html +[SSL_METHODS]: https://www.openssl.org/docs/man1.0.2/ssl/ssl.html#DEALING-WITH-PROTOCOL-METHODS +[Stream]: stream.html#stream_stream [TLS Session Tickets]: https://www.ietf.org/rfc/rfc5077.txt +[TLS recommendations]: https://wiki.mozilla.org/Security/Server_Side_TLS +[`'secureConnect'`]: #tls_event_secureconnect +[`'secureConnection'`]: #tls_event_secureconnection +[`crypto.getCurves()`]: crypto.html#crypto_crypto_getcurves +[`net.Server.address()`]: net.html#net_server_address +[`net.Server`]: net.html#net_class_net_server +[`net.Socket`]: net.html#net_class_net_socket +[`tls.DEFAULT_ECDH_CURVE`]: #tls_tls_default_ecdh_curve [`tls.TLSSocket.getPeerCertificate()`]: #tls_tlssocket_getpeercertificate_detailed -[`tls.createSecureContext()`]: #tls_tls_createsecurecontext_options +[`tls.TLSSocket`]: #tls_class_tls_tlssocket [`tls.connect()`]: #tls_tls_connect_options_callback +[`tls.createSecureContext()`]: #tls_tls_createsecurecontext_options +[`tls.createSecurePair()`]: #tls_tls_createsecurepair_context_isserver_requestcert_rejectunauthorized_options +[`tls.createServer()`]: #tls_tls_createserver_options_secureconnectionlistener +[asn1.js]: https://npmjs.org/package/asn1.js +[modifying the default cipher suite]: #tls_modifying_the_default_tls_cipher_suite +[specific attacks affecting larger AES key sizes]: https://www.schneier.com/blog/archives/2009/07/another_new_aes.html +[tls.Server]: #tls_class_tls_server