11cb0ef41Sopenharmony_ci<!DOCTYPE html> 21cb0ef41Sopenharmony_ci<html lang="en"> 31cb0ef41Sopenharmony_ci<head> 41cb0ef41Sopenharmony_ci <meta charset="utf-8"> 51cb0ef41Sopenharmony_ci <meta name="viewport" content="width=device-width"> 61cb0ef41Sopenharmony_ci <meta name="nodejs.org:node-version" content="v18.20.1"> 71cb0ef41Sopenharmony_ci <title>TLS (SSL) | Node.js v18.20.1 Documentation</title> 81cb0ef41Sopenharmony_ci <link rel="stylesheet" href="https://fonts.googleapis.com/css?family=Lato:400,700,400italic&display=fallback"> 91cb0ef41Sopenharmony_ci <link rel="stylesheet" href="assets/style.css"> 101cb0ef41Sopenharmony_ci <link rel="stylesheet" href="assets/hljs.css"> 111cb0ef41Sopenharmony_ci <link rel="canonical" href="https://nodejs.org/api/tls.html"> 121cb0ef41Sopenharmony_ci <script async defer src="assets/api.js" type="text/javascript"></script> 131cb0ef41Sopenharmony_ci 141cb0ef41Sopenharmony_ci</head> 151cb0ef41Sopenharmony_ci<body class="alt apidoc" id="api-section-tls"> 161cb0ef41Sopenharmony_ci <div id="content" class="clearfix"> 171cb0ef41Sopenharmony_ci <div id="column2" class="interior"> 181cb0ef41Sopenharmony_ci <div id="intro" class="interior"> 191cb0ef41Sopenharmony_ci <a href="/" title="Go back to the home page"> 201cb0ef41Sopenharmony_ci Node.js 211cb0ef41Sopenharmony_ci </a> 221cb0ef41Sopenharmony_ci </div> 231cb0ef41Sopenharmony_ci <ul> 241cb0ef41Sopenharmony_ci<li><a href="documentation.html" class="nav-documentation">About this documentation</a></li> 251cb0ef41Sopenharmony_ci<li><a href="synopsis.html" class="nav-synopsis">Usage and example</a></li> 261cb0ef41Sopenharmony_ci</ul> 271cb0ef41Sopenharmony_ci<hr class="line"> 281cb0ef41Sopenharmony_ci<ul> 291cb0ef41Sopenharmony_ci<li><a href="assert.html" class="nav-assert">Assertion testing</a></li> 301cb0ef41Sopenharmony_ci<li><a href="async_context.html" class="nav-async_context">Asynchronous context tracking</a></li> 311cb0ef41Sopenharmony_ci<li><a href="async_hooks.html" class="nav-async_hooks">Async hooks</a></li> 321cb0ef41Sopenharmony_ci<li><a href="buffer.html" class="nav-buffer">Buffer</a></li> 331cb0ef41Sopenharmony_ci<li><a href="addons.html" class="nav-addons">C++ addons</a></li> 341cb0ef41Sopenharmony_ci<li><a href="n-api.html" class="nav-n-api">C/C++ addons with Node-API</a></li> 351cb0ef41Sopenharmony_ci<li><a href="embedding.html" class="nav-embedding">C++ embedder API</a></li> 361cb0ef41Sopenharmony_ci<li><a href="child_process.html" class="nav-child_process">Child processes</a></li> 371cb0ef41Sopenharmony_ci<li><a href="cluster.html" class="nav-cluster">Cluster</a></li> 381cb0ef41Sopenharmony_ci<li><a href="cli.html" class="nav-cli">Command-line options</a></li> 391cb0ef41Sopenharmony_ci<li><a href="console.html" class="nav-console">Console</a></li> 401cb0ef41Sopenharmony_ci<li><a href="corepack.html" class="nav-corepack">Corepack</a></li> 411cb0ef41Sopenharmony_ci<li><a href="crypto.html" class="nav-crypto">Crypto</a></li> 421cb0ef41Sopenharmony_ci<li><a href="debugger.html" class="nav-debugger">Debugger</a></li> 431cb0ef41Sopenharmony_ci<li><a href="deprecations.html" class="nav-deprecations">Deprecated APIs</a></li> 441cb0ef41Sopenharmony_ci<li><a href="diagnostics_channel.html" class="nav-diagnostics_channel">Diagnostics Channel</a></li> 451cb0ef41Sopenharmony_ci<li><a href="dns.html" class="nav-dns">DNS</a></li> 461cb0ef41Sopenharmony_ci<li><a href="domain.html" class="nav-domain">Domain</a></li> 471cb0ef41Sopenharmony_ci<li><a href="errors.html" class="nav-errors">Errors</a></li> 481cb0ef41Sopenharmony_ci<li><a href="events.html" class="nav-events">Events</a></li> 491cb0ef41Sopenharmony_ci<li><a href="fs.html" class="nav-fs">File system</a></li> 501cb0ef41Sopenharmony_ci<li><a href="globals.html" class="nav-globals">Globals</a></li> 511cb0ef41Sopenharmony_ci<li><a href="http.html" class="nav-http">HTTP</a></li> 521cb0ef41Sopenharmony_ci<li><a href="http2.html" class="nav-http2">HTTP/2</a></li> 531cb0ef41Sopenharmony_ci<li><a href="https.html" class="nav-https">HTTPS</a></li> 541cb0ef41Sopenharmony_ci<li><a href="inspector.html" class="nav-inspector">Inspector</a></li> 551cb0ef41Sopenharmony_ci<li><a href="intl.html" class="nav-intl">Internationalization</a></li> 561cb0ef41Sopenharmony_ci<li><a href="modules.html" class="nav-modules">Modules: CommonJS modules</a></li> 571cb0ef41Sopenharmony_ci<li><a href="esm.html" class="nav-esm">Modules: ECMAScript modules</a></li> 581cb0ef41Sopenharmony_ci<li><a href="module.html" class="nav-module">Modules: <code>node:module</code> API</a></li> 591cb0ef41Sopenharmony_ci<li><a href="packages.html" class="nav-packages">Modules: Packages</a></li> 601cb0ef41Sopenharmony_ci<li><a href="net.html" class="nav-net">Net</a></li> 611cb0ef41Sopenharmony_ci<li><a href="os.html" class="nav-os">OS</a></li> 621cb0ef41Sopenharmony_ci<li><a href="path.html" class="nav-path">Path</a></li> 631cb0ef41Sopenharmony_ci<li><a href="perf_hooks.html" class="nav-perf_hooks">Performance hooks</a></li> 641cb0ef41Sopenharmony_ci<li><a href="permissions.html" class="nav-permissions">Permissions</a></li> 651cb0ef41Sopenharmony_ci<li><a href="process.html" class="nav-process">Process</a></li> 661cb0ef41Sopenharmony_ci<li><a href="punycode.html" class="nav-punycode">Punycode</a></li> 671cb0ef41Sopenharmony_ci<li><a href="querystring.html" class="nav-querystring">Query strings</a></li> 681cb0ef41Sopenharmony_ci<li><a href="readline.html" class="nav-readline">Readline</a></li> 691cb0ef41Sopenharmony_ci<li><a href="repl.html" class="nav-repl">REPL</a></li> 701cb0ef41Sopenharmony_ci<li><a href="report.html" class="nav-report">Report</a></li> 711cb0ef41Sopenharmony_ci<li><a href="single-executable-applications.html" class="nav-single-executable-applications">Single executable applications</a></li> 721cb0ef41Sopenharmony_ci<li><a href="stream.html" class="nav-stream">Stream</a></li> 731cb0ef41Sopenharmony_ci<li><a href="string_decoder.html" class="nav-string_decoder">String decoder</a></li> 741cb0ef41Sopenharmony_ci<li><a href="test.html" class="nav-test">Test runner</a></li> 751cb0ef41Sopenharmony_ci<li><a href="timers.html" class="nav-timers">Timers</a></li> 761cb0ef41Sopenharmony_ci<li><a href="tls.html" class="nav-tls active">TLS/SSL</a></li> 771cb0ef41Sopenharmony_ci<li><a href="tracing.html" class="nav-tracing">Trace events</a></li> 781cb0ef41Sopenharmony_ci<li><a href="tty.html" class="nav-tty">TTY</a></li> 791cb0ef41Sopenharmony_ci<li><a href="dgram.html" class="nav-dgram">UDP/datagram</a></li> 801cb0ef41Sopenharmony_ci<li><a href="url.html" class="nav-url">URL</a></li> 811cb0ef41Sopenharmony_ci<li><a href="util.html" class="nav-util">Utilities</a></li> 821cb0ef41Sopenharmony_ci<li><a href="v8.html" class="nav-v8">V8</a></li> 831cb0ef41Sopenharmony_ci<li><a href="vm.html" class="nav-vm">VM</a></li> 841cb0ef41Sopenharmony_ci<li><a href="wasi.html" class="nav-wasi">WASI</a></li> 851cb0ef41Sopenharmony_ci<li><a href="webcrypto.html" class="nav-webcrypto">Web Crypto API</a></li> 861cb0ef41Sopenharmony_ci<li><a href="webstreams.html" class="nav-webstreams">Web Streams API</a></li> 871cb0ef41Sopenharmony_ci<li><a href="worker_threads.html" class="nav-worker_threads">Worker threads</a></li> 881cb0ef41Sopenharmony_ci<li><a href="zlib.html" class="nav-zlib">Zlib</a></li> 891cb0ef41Sopenharmony_ci</ul> 901cb0ef41Sopenharmony_ci<hr class="line"> 911cb0ef41Sopenharmony_ci<ul> 921cb0ef41Sopenharmony_ci<li><a href="https://github.com/nodejs/node" class="nav-https-github-com-nodejs-node">Code repository and issue tracker</a></li> 931cb0ef41Sopenharmony_ci</ul> 941cb0ef41Sopenharmony_ci </div> 951cb0ef41Sopenharmony_ci 961cb0ef41Sopenharmony_ci <div id="column1" data-id="tls" class="interior"> 971cb0ef41Sopenharmony_ci <header class="header"> 981cb0ef41Sopenharmony_ci <div class="header-container"> 991cb0ef41Sopenharmony_ci <h1>Node.js v18.20.1 documentation</h1> 1001cb0ef41Sopenharmony_ci <button class="theme-toggle-btn" id="theme-toggle-btn" title="Toggle dark mode/light mode" aria-label="Toggle dark mode/light mode" hidden> 1011cb0ef41Sopenharmony_ci <svg xmlns="http://www.w3.org/2000/svg" class="icon dark-icon" height="24" width="24"> 1021cb0ef41Sopenharmony_ci <path fill="none" d="M0 0h24v24H0z" /> 1031cb0ef41Sopenharmony_ci <path d="M11.1 12.08c-2.33-4.51-.5-8.48.53-10.07C6.27 2.2 1.98 6.59 1.98 12c0 .14.02.28.02.42.62-.27 1.29-.42 2-.42 1.66 0 3.18.83 4.1 2.15A4.01 4.01 0 0111 18c0 1.52-.87 2.83-2.12 3.51.98.32 2.03.5 3.11.5 3.5 0 6.58-1.8 8.37-4.52-2.36.23-6.98-.97-9.26-5.41z"/> 1041cb0ef41Sopenharmony_ci <path d="M7 16h-.18C6.4 14.84 5.3 14 4 14c-1.66 0-3 1.34-3 3s1.34 3 3 3h3c1.1 0 2-.9 2-2s-.9-2-2-2z"/> 1051cb0ef41Sopenharmony_ci </svg> 1061cb0ef41Sopenharmony_ci <svg xmlns="http://www.w3.org/2000/svg" class="icon light-icon" height="24" width="24"> 1071cb0ef41Sopenharmony_ci <path d="M0 0h24v24H0z" fill="none" /> 1081cb0ef41Sopenharmony_ci <path d="M6.76 4.84l-1.8-1.79-1.41 1.41 1.79 1.79 1.42-1.41zM4 10.5H1v2h3v-2zm9-9.95h-2V3.5h2V.55zm7.45 3.91l-1.41-1.41-1.79 1.79 1.41 1.41 1.79-1.79zm-3.21 13.7l1.79 1.8 1.41-1.41-1.8-1.79-1.4 1.4zM20 10.5v2h3v-2h-3zm-8-5c-3.31 0-6 2.69-6 6s2.69 6 6 6 6-2.69 6-6-2.69-6-6-6zm-1 16.95h2V19.5h-2v2.95zm-7.45-3.91l1.41 1.41 1.79-1.8-1.41-1.41-1.79 1.8z"/> 1091cb0ef41Sopenharmony_ci </svg> 1101cb0ef41Sopenharmony_ci </button> 1111cb0ef41Sopenharmony_ci </div> 1121cb0ef41Sopenharmony_ci <div id="gtoc"> 1131cb0ef41Sopenharmony_ci <ul> 1141cb0ef41Sopenharmony_ci <li class="pinned-header">Node.js v18.20.1</li> 1151cb0ef41Sopenharmony_ci 1161cb0ef41Sopenharmony_ci <li class="picker-header"> 1171cb0ef41Sopenharmony_ci <a href="#"> 1181cb0ef41Sopenharmony_ci <span class="collapsed-arrow">►</span><span class="expanded-arrow">▼</span> 1191cb0ef41Sopenharmony_ci Table of contents 1201cb0ef41Sopenharmony_ci </a> 1211cb0ef41Sopenharmony_ci 1221cb0ef41Sopenharmony_ci <div class="picker"><div class="toc"><ul> 1231cb0ef41Sopenharmony_ci<li><span class="stability_2"><a href="#tls-ssl">TLS (SSL)</a></span> 1241cb0ef41Sopenharmony_ci<ul> 1251cb0ef41Sopenharmony_ci<li><a href="#determining-if-crypto-support-is-unavailable">Determining if crypto support is unavailable</a></li> 1261cb0ef41Sopenharmony_ci<li><a href="#tlsssl-concepts">TLS/SSL concepts</a> 1271cb0ef41Sopenharmony_ci<ul> 1281cb0ef41Sopenharmony_ci<li><a href="#perfect-forward-secrecy">Perfect forward secrecy</a></li> 1291cb0ef41Sopenharmony_ci<li><a href="#alpn-and-sni">ALPN and SNI</a></li> 1301cb0ef41Sopenharmony_ci<li><a href="#pre-shared-keys">Pre-shared keys</a></li> 1311cb0ef41Sopenharmony_ci<li><a href="#client-initiated-renegotiation-attack-mitigation">Client-initiated renegotiation attack mitigation</a></li> 1321cb0ef41Sopenharmony_ci<li><a href="#session-resumption">Session resumption</a> 1331cb0ef41Sopenharmony_ci<ul> 1341cb0ef41Sopenharmony_ci<li><a href="#session-identifiers">Session identifiers</a></li> 1351cb0ef41Sopenharmony_ci<li><a href="#session-tickets">Session tickets</a></li> 1361cb0ef41Sopenharmony_ci</ul> 1371cb0ef41Sopenharmony_ci</li> 1381cb0ef41Sopenharmony_ci</ul> 1391cb0ef41Sopenharmony_ci</li> 1401cb0ef41Sopenharmony_ci<li><a href="#modifying-the-default-tls-cipher-suite">Modifying the default TLS cipher suite</a></li> 1411cb0ef41Sopenharmony_ci<li><a href="#x509-certificate-error-codes">X509 certificate error codes</a></li> 1421cb0ef41Sopenharmony_ci<li><span class="stability_0"><a href="#class-tlscryptostream">Class: <code>tls.CryptoStream</code></a></span> 1431cb0ef41Sopenharmony_ci<ul> 1441cb0ef41Sopenharmony_ci<li><a href="#cryptostreambyteswritten"><code>cryptoStream.bytesWritten</code></a></li> 1451cb0ef41Sopenharmony_ci</ul> 1461cb0ef41Sopenharmony_ci</li> 1471cb0ef41Sopenharmony_ci<li><span class="stability_0"><a href="#class-tlssecurepair">Class: <code>tls.SecurePair</code></a></span> 1481cb0ef41Sopenharmony_ci<ul> 1491cb0ef41Sopenharmony_ci<li><a href="#event-secure">Event: <code>'secure'</code></a></li> 1501cb0ef41Sopenharmony_ci</ul> 1511cb0ef41Sopenharmony_ci</li> 1521cb0ef41Sopenharmony_ci<li><a href="#class-tlsserver">Class: <code>tls.Server</code></a> 1531cb0ef41Sopenharmony_ci<ul> 1541cb0ef41Sopenharmony_ci<li><a href="#event-connection">Event: <code>'connection'</code></a></li> 1551cb0ef41Sopenharmony_ci<li><a href="#event-keylog">Event: <code>'keylog'</code></a></li> 1561cb0ef41Sopenharmony_ci<li><a href="#event-newsession">Event: <code>'newSession'</code></a></li> 1571cb0ef41Sopenharmony_ci<li><a href="#event-ocsprequest">Event: <code>'OCSPRequest'</code></a></li> 1581cb0ef41Sopenharmony_ci<li><a href="#event-resumesession">Event: <code>'resumeSession'</code></a></li> 1591cb0ef41Sopenharmony_ci<li><a href="#event-secureconnection">Event: <code>'secureConnection'</code></a></li> 1601cb0ef41Sopenharmony_ci<li><a href="#event-tlsclienterror">Event: <code>'tlsClientError'</code></a></li> 1611cb0ef41Sopenharmony_ci<li><a href="#serveraddcontexthostname-context"><code>server.addContext(hostname, context)</code></a></li> 1621cb0ef41Sopenharmony_ci<li><a href="#serveraddress"><code>server.address()</code></a></li> 1631cb0ef41Sopenharmony_ci<li><a href="#serverclosecallback"><code>server.close([callback])</code></a></li> 1641cb0ef41Sopenharmony_ci<li><a href="#servergetticketkeys"><code>server.getTicketKeys()</code></a></li> 1651cb0ef41Sopenharmony_ci<li><a href="#serverlisten"><code>server.listen()</code></a></li> 1661cb0ef41Sopenharmony_ci<li><a href="#serversetsecurecontextoptions"><code>server.setSecureContext(options)</code></a></li> 1671cb0ef41Sopenharmony_ci<li><a href="#serversetticketkeyskeys"><code>server.setTicketKeys(keys)</code></a></li> 1681cb0ef41Sopenharmony_ci</ul> 1691cb0ef41Sopenharmony_ci</li> 1701cb0ef41Sopenharmony_ci<li><a href="#class-tlstlssocket">Class: <code>tls.TLSSocket</code></a> 1711cb0ef41Sopenharmony_ci<ul> 1721cb0ef41Sopenharmony_ci<li><a href="#new-tlstlssocketsocket-options"><code>new tls.TLSSocket(socket[, options])</code></a></li> 1731cb0ef41Sopenharmony_ci<li><a href="#event-keylog_1">Event: <code>'keylog'</code></a></li> 1741cb0ef41Sopenharmony_ci<li><a href="#event-ocspresponse">Event: <code>'OCSPResponse'</code></a></li> 1751cb0ef41Sopenharmony_ci<li><a href="#event-secureconnect">Event: <code>'secureConnect'</code></a></li> 1761cb0ef41Sopenharmony_ci<li><a href="#event-session">Event: <code>'session'</code></a></li> 1771cb0ef41Sopenharmony_ci<li><a href="#tlssocketaddress"><code>tlsSocket.address()</code></a></li> 1781cb0ef41Sopenharmony_ci<li><a href="#tlssocketauthorizationerror"><code>tlsSocket.authorizationError</code></a></li> 1791cb0ef41Sopenharmony_ci<li><a href="#tlssocketauthorized"><code>tlsSocket.authorized</code></a></li> 1801cb0ef41Sopenharmony_ci<li><a href="#tlssocketdisablerenegotiation"><code>tlsSocket.disableRenegotiation()</code></a></li> 1811cb0ef41Sopenharmony_ci<li><a href="#tlssocketenabletrace"><code>tlsSocket.enableTrace()</code></a></li> 1821cb0ef41Sopenharmony_ci<li><a href="#tlssocketencrypted"><code>tlsSocket.encrypted</code></a></li> 1831cb0ef41Sopenharmony_ci<li><a href="#tlssocketexportkeyingmateriallength-label-context"><code>tlsSocket.exportKeyingMaterial(length, label[, context])</code></a></li> 1841cb0ef41Sopenharmony_ci<li><a href="#tlssocketgetcertificate"><code>tlsSocket.getCertificate()</code></a></li> 1851cb0ef41Sopenharmony_ci<li><a href="#tlssocketgetcipher"><code>tlsSocket.getCipher()</code></a></li> 1861cb0ef41Sopenharmony_ci<li><a href="#tlssocketgetephemeralkeyinfo"><code>tlsSocket.getEphemeralKeyInfo()</code></a></li> 1871cb0ef41Sopenharmony_ci<li><a href="#tlssocketgetfinished"><code>tlsSocket.getFinished()</code></a></li> 1881cb0ef41Sopenharmony_ci<li><a href="#tlssocketgetpeercertificatedetailed"><code>tlsSocket.getPeerCertificate([detailed])</code></a> 1891cb0ef41Sopenharmony_ci<ul> 1901cb0ef41Sopenharmony_ci<li><a href="#certificate-object">Certificate object</a></li> 1911cb0ef41Sopenharmony_ci</ul> 1921cb0ef41Sopenharmony_ci</li> 1931cb0ef41Sopenharmony_ci<li><a href="#tlssocketgetpeerfinished"><code>tlsSocket.getPeerFinished()</code></a></li> 1941cb0ef41Sopenharmony_ci<li><a href="#tlssocketgetpeerx509certificate"><code>tlsSocket.getPeerX509Certificate()</code></a></li> 1951cb0ef41Sopenharmony_ci<li><a href="#tlssocketgetprotocol"><code>tlsSocket.getProtocol()</code></a></li> 1961cb0ef41Sopenharmony_ci<li><a href="#tlssocketgetsession"><code>tlsSocket.getSession()</code></a></li> 1971cb0ef41Sopenharmony_ci<li><a href="#tlssocketgetsharedsigalgs"><code>tlsSocket.getSharedSigalgs()</code></a></li> 1981cb0ef41Sopenharmony_ci<li><a href="#tlssocketgettlsticket"><code>tlsSocket.getTLSTicket()</code></a></li> 1991cb0ef41Sopenharmony_ci<li><a href="#tlssocketgetx509certificate"><code>tlsSocket.getX509Certificate()</code></a></li> 2001cb0ef41Sopenharmony_ci<li><a href="#tlssocketissessionreused"><code>tlsSocket.isSessionReused()</code></a></li> 2011cb0ef41Sopenharmony_ci<li><a href="#tlssocketlocaladdress"><code>tlsSocket.localAddress</code></a></li> 2021cb0ef41Sopenharmony_ci<li><a href="#tlssocketlocalport"><code>tlsSocket.localPort</code></a></li> 2031cb0ef41Sopenharmony_ci<li><a href="#tlssocketremoteaddress"><code>tlsSocket.remoteAddress</code></a></li> 2041cb0ef41Sopenharmony_ci<li><a href="#tlssocketremotefamily"><code>tlsSocket.remoteFamily</code></a></li> 2051cb0ef41Sopenharmony_ci<li><a href="#tlssocketremoteport"><code>tlsSocket.remotePort</code></a></li> 2061cb0ef41Sopenharmony_ci<li><a href="#tlssocketrenegotiateoptions-callback"><code>tlsSocket.renegotiate(options, callback)</code></a></li> 2071cb0ef41Sopenharmony_ci<li><a href="#tlssocketsetmaxsendfragmentsize"><code>tlsSocket.setMaxSendFragment(size)</code></a></li> 2081cb0ef41Sopenharmony_ci</ul> 2091cb0ef41Sopenharmony_ci</li> 2101cb0ef41Sopenharmony_ci<li><a href="#tlscheckserveridentityhostname-cert"><code>tls.checkServerIdentity(hostname, cert)</code></a></li> 2111cb0ef41Sopenharmony_ci<li><a href="#tlsconnectoptions-callback"><code>tls.connect(options[, callback])</code></a></li> 2121cb0ef41Sopenharmony_ci<li><a href="#tlsconnectpath-options-callback"><code>tls.connect(path[, options][, callback])</code></a></li> 2131cb0ef41Sopenharmony_ci<li><a href="#tlsconnectport-host-options-callback"><code>tls.connect(port[, host][, options][, callback])</code></a></li> 2141cb0ef41Sopenharmony_ci<li><a href="#tlscreatesecurecontextoptions"><code>tls.createSecureContext([options])</code></a></li> 2151cb0ef41Sopenharmony_ci<li><span class="stability_0"><a href="#tlscreatesecurepaircontext-isserver-requestcert-rejectunauthorized-options"><code>tls.createSecurePair([context][, isServer][, requestCert][, rejectUnauthorized][, options])</code></a></span></li> 2161cb0ef41Sopenharmony_ci<li><a href="#tlscreateserveroptions-secureconnectionlistener"><code>tls.createServer([options][, secureConnectionListener])</code></a></li> 2171cb0ef41Sopenharmony_ci<li><a href="#tlsgetciphers"><code>tls.getCiphers()</code></a></li> 2181cb0ef41Sopenharmony_ci<li><a href="#tlsrootcertificates"><code>tls.rootCertificates</code></a></li> 2191cb0ef41Sopenharmony_ci<li><a href="#tlsdefault_ecdh_curve"><code>tls.DEFAULT_ECDH_CURVE</code></a></li> 2201cb0ef41Sopenharmony_ci<li><a href="#tlsdefault_max_version"><code>tls.DEFAULT_MAX_VERSION</code></a></li> 2211cb0ef41Sopenharmony_ci<li><a href="#tlsdefault_min_version"><code>tls.DEFAULT_MIN_VERSION</code></a></li> 2221cb0ef41Sopenharmony_ci<li><a href="#tlsdefault_ciphers"><code>tls.DEFAULT_CIPHERS</code></a></li> 2231cb0ef41Sopenharmony_ci</ul> 2241cb0ef41Sopenharmony_ci</li> 2251cb0ef41Sopenharmony_ci</ul></div></div> 2261cb0ef41Sopenharmony_ci </li> 2271cb0ef41Sopenharmony_ci 2281cb0ef41Sopenharmony_ci 2291cb0ef41Sopenharmony_ci <li class="picker-header"> 2301cb0ef41Sopenharmony_ci <a href="#"> 2311cb0ef41Sopenharmony_ci <span class="collapsed-arrow">►</span><span class="expanded-arrow">▼</span> 2321cb0ef41Sopenharmony_ci Index 2331cb0ef41Sopenharmony_ci </a> 2341cb0ef41Sopenharmony_ci 2351cb0ef41Sopenharmony_ci <div class="picker"><ul> 2361cb0ef41Sopenharmony_ci<li><a href="documentation.html" class="nav-documentation">About this documentation</a></li> 2371cb0ef41Sopenharmony_ci<li><a href="synopsis.html" class="nav-synopsis">Usage and example</a></li> 2381cb0ef41Sopenharmony_ci 2391cb0ef41Sopenharmony_ci <li> 2401cb0ef41Sopenharmony_ci <a href="index.html">Index</a> 2411cb0ef41Sopenharmony_ci </li> 2421cb0ef41Sopenharmony_ci </ul> 2431cb0ef41Sopenharmony_ci 2441cb0ef41Sopenharmony_ci<hr class="line"> 2451cb0ef41Sopenharmony_ci<ul> 2461cb0ef41Sopenharmony_ci<li><a href="assert.html" class="nav-assert">Assertion testing</a></li> 2471cb0ef41Sopenharmony_ci<li><a href="async_context.html" class="nav-async_context">Asynchronous context tracking</a></li> 2481cb0ef41Sopenharmony_ci<li><a href="async_hooks.html" class="nav-async_hooks">Async hooks</a></li> 2491cb0ef41Sopenharmony_ci<li><a href="buffer.html" class="nav-buffer">Buffer</a></li> 2501cb0ef41Sopenharmony_ci<li><a href="addons.html" class="nav-addons">C++ addons</a></li> 2511cb0ef41Sopenharmony_ci<li><a href="n-api.html" class="nav-n-api">C/C++ addons with Node-API</a></li> 2521cb0ef41Sopenharmony_ci<li><a href="embedding.html" class="nav-embedding">C++ embedder API</a></li> 2531cb0ef41Sopenharmony_ci<li><a href="child_process.html" class="nav-child_process">Child processes</a></li> 2541cb0ef41Sopenharmony_ci<li><a href="cluster.html" class="nav-cluster">Cluster</a></li> 2551cb0ef41Sopenharmony_ci<li><a href="cli.html" class="nav-cli">Command-line options</a></li> 2561cb0ef41Sopenharmony_ci<li><a href="console.html" class="nav-console">Console</a></li> 2571cb0ef41Sopenharmony_ci<li><a href="corepack.html" class="nav-corepack">Corepack</a></li> 2581cb0ef41Sopenharmony_ci<li><a href="crypto.html" class="nav-crypto">Crypto</a></li> 2591cb0ef41Sopenharmony_ci<li><a href="debugger.html" class="nav-debugger">Debugger</a></li> 2601cb0ef41Sopenharmony_ci<li><a href="deprecations.html" class="nav-deprecations">Deprecated APIs</a></li> 2611cb0ef41Sopenharmony_ci<li><a href="diagnostics_channel.html" class="nav-diagnostics_channel">Diagnostics Channel</a></li> 2621cb0ef41Sopenharmony_ci<li><a href="dns.html" class="nav-dns">DNS</a></li> 2631cb0ef41Sopenharmony_ci<li><a href="domain.html" class="nav-domain">Domain</a></li> 2641cb0ef41Sopenharmony_ci<li><a href="errors.html" class="nav-errors">Errors</a></li> 2651cb0ef41Sopenharmony_ci<li><a href="events.html" class="nav-events">Events</a></li> 2661cb0ef41Sopenharmony_ci<li><a href="fs.html" class="nav-fs">File system</a></li> 2671cb0ef41Sopenharmony_ci<li><a href="globals.html" class="nav-globals">Globals</a></li> 2681cb0ef41Sopenharmony_ci<li><a href="http.html" class="nav-http">HTTP</a></li> 2691cb0ef41Sopenharmony_ci<li><a href="http2.html" class="nav-http2">HTTP/2</a></li> 2701cb0ef41Sopenharmony_ci<li><a href="https.html" class="nav-https">HTTPS</a></li> 2711cb0ef41Sopenharmony_ci<li><a href="inspector.html" class="nav-inspector">Inspector</a></li> 2721cb0ef41Sopenharmony_ci<li><a href="intl.html" class="nav-intl">Internationalization</a></li> 2731cb0ef41Sopenharmony_ci<li><a href="modules.html" class="nav-modules">Modules: CommonJS modules</a></li> 2741cb0ef41Sopenharmony_ci<li><a href="esm.html" class="nav-esm">Modules: ECMAScript modules</a></li> 2751cb0ef41Sopenharmony_ci<li><a href="module.html" class="nav-module">Modules: <code>node:module</code> API</a></li> 2761cb0ef41Sopenharmony_ci<li><a href="packages.html" class="nav-packages">Modules: Packages</a></li> 2771cb0ef41Sopenharmony_ci<li><a href="net.html" class="nav-net">Net</a></li> 2781cb0ef41Sopenharmony_ci<li><a href="os.html" class="nav-os">OS</a></li> 2791cb0ef41Sopenharmony_ci<li><a href="path.html" class="nav-path">Path</a></li> 2801cb0ef41Sopenharmony_ci<li><a href="perf_hooks.html" class="nav-perf_hooks">Performance hooks</a></li> 2811cb0ef41Sopenharmony_ci<li><a href="permissions.html" class="nav-permissions">Permissions</a></li> 2821cb0ef41Sopenharmony_ci<li><a href="process.html" class="nav-process">Process</a></li> 2831cb0ef41Sopenharmony_ci<li><a href="punycode.html" class="nav-punycode">Punycode</a></li> 2841cb0ef41Sopenharmony_ci<li><a href="querystring.html" class="nav-querystring">Query strings</a></li> 2851cb0ef41Sopenharmony_ci<li><a href="readline.html" class="nav-readline">Readline</a></li> 2861cb0ef41Sopenharmony_ci<li><a href="repl.html" class="nav-repl">REPL</a></li> 2871cb0ef41Sopenharmony_ci<li><a href="report.html" class="nav-report">Report</a></li> 2881cb0ef41Sopenharmony_ci<li><a href="single-executable-applications.html" class="nav-single-executable-applications">Single executable applications</a></li> 2891cb0ef41Sopenharmony_ci<li><a href="stream.html" class="nav-stream">Stream</a></li> 2901cb0ef41Sopenharmony_ci<li><a href="string_decoder.html" class="nav-string_decoder">String decoder</a></li> 2911cb0ef41Sopenharmony_ci<li><a href="test.html" class="nav-test">Test runner</a></li> 2921cb0ef41Sopenharmony_ci<li><a href="timers.html" class="nav-timers">Timers</a></li> 2931cb0ef41Sopenharmony_ci<li><a href="tls.html" class="nav-tls active">TLS/SSL</a></li> 2941cb0ef41Sopenharmony_ci<li><a href="tracing.html" class="nav-tracing">Trace events</a></li> 2951cb0ef41Sopenharmony_ci<li><a href="tty.html" class="nav-tty">TTY</a></li> 2961cb0ef41Sopenharmony_ci<li><a href="dgram.html" class="nav-dgram">UDP/datagram</a></li> 2971cb0ef41Sopenharmony_ci<li><a href="url.html" class="nav-url">URL</a></li> 2981cb0ef41Sopenharmony_ci<li><a href="util.html" class="nav-util">Utilities</a></li> 2991cb0ef41Sopenharmony_ci<li><a href="v8.html" class="nav-v8">V8</a></li> 3001cb0ef41Sopenharmony_ci<li><a href="vm.html" class="nav-vm">VM</a></li> 3011cb0ef41Sopenharmony_ci<li><a href="wasi.html" class="nav-wasi">WASI</a></li> 3021cb0ef41Sopenharmony_ci<li><a href="webcrypto.html" class="nav-webcrypto">Web Crypto API</a></li> 3031cb0ef41Sopenharmony_ci<li><a href="webstreams.html" class="nav-webstreams">Web Streams API</a></li> 3041cb0ef41Sopenharmony_ci<li><a href="worker_threads.html" class="nav-worker_threads">Worker threads</a></li> 3051cb0ef41Sopenharmony_ci<li><a href="zlib.html" class="nav-zlib">Zlib</a></li> 3061cb0ef41Sopenharmony_ci</ul> 3071cb0ef41Sopenharmony_ci<hr class="line"> 3081cb0ef41Sopenharmony_ci<ul> 3091cb0ef41Sopenharmony_ci<li><a href="https://github.com/nodejs/node" class="nav-https-github-com-nodejs-node">Code repository and issue tracker</a></li> 3101cb0ef41Sopenharmony_ci</ul></div> 3111cb0ef41Sopenharmony_ci </li> 3121cb0ef41Sopenharmony_ci 3131cb0ef41Sopenharmony_ci 3141cb0ef41Sopenharmony_ci <li class="picker-header"> 3151cb0ef41Sopenharmony_ci <a href="#"> 3161cb0ef41Sopenharmony_ci <span class="collapsed-arrow">►</span><span class="expanded-arrow">▼</span> 3171cb0ef41Sopenharmony_ci Other versions 3181cb0ef41Sopenharmony_ci </a> 3191cb0ef41Sopenharmony_ci <div class="picker"><ol id="alt-docs"><li><a href="https://nodejs.org/docs/latest-v21.x/api/tls.html">21.x</a></li> 3201cb0ef41Sopenharmony_ci<li><a href="https://nodejs.org/docs/latest-v20.x/api/tls.html">20.x <b>LTS</b></a></li> 3211cb0ef41Sopenharmony_ci<li><a href="https://nodejs.org/docs/latest-v19.x/api/tls.html">19.x</a></li> 3221cb0ef41Sopenharmony_ci<li><a href="https://nodejs.org/docs/latest-v18.x/api/tls.html">18.x <b>LTS</b></a></li> 3231cb0ef41Sopenharmony_ci<li><a href="https://nodejs.org/docs/latest-v17.x/api/tls.html">17.x</a></li> 3241cb0ef41Sopenharmony_ci<li><a href="https://nodejs.org/docs/latest-v16.x/api/tls.html">16.x</a></li> 3251cb0ef41Sopenharmony_ci<li><a href="https://nodejs.org/docs/latest-v15.x/api/tls.html">15.x</a></li> 3261cb0ef41Sopenharmony_ci<li><a href="https://nodejs.org/docs/latest-v14.x/api/tls.html">14.x</a></li> 3271cb0ef41Sopenharmony_ci<li><a href="https://nodejs.org/docs/latest-v13.x/api/tls.html">13.x</a></li> 3281cb0ef41Sopenharmony_ci<li><a href="https://nodejs.org/docs/latest-v12.x/api/tls.html">12.x</a></li> 3291cb0ef41Sopenharmony_ci<li><a href="https://nodejs.org/docs/latest-v11.x/api/tls.html">11.x</a></li> 3301cb0ef41Sopenharmony_ci<li><a href="https://nodejs.org/docs/latest-v10.x/api/tls.html">10.x</a></li> 3311cb0ef41Sopenharmony_ci<li><a href="https://nodejs.org/docs/latest-v9.x/api/tls.html">9.x</a></li> 3321cb0ef41Sopenharmony_ci<li><a href="https://nodejs.org/docs/latest-v8.x/api/tls.html">8.x</a></li> 3331cb0ef41Sopenharmony_ci<li><a href="https://nodejs.org/docs/latest-v7.x/api/tls.html">7.x</a></li> 3341cb0ef41Sopenharmony_ci<li><a href="https://nodejs.org/docs/latest-v6.x/api/tls.html">6.x</a></li> 3351cb0ef41Sopenharmony_ci<li><a href="https://nodejs.org/docs/latest-v5.x/api/tls.html">5.x</a></li> 3361cb0ef41Sopenharmony_ci<li><a href="https://nodejs.org/docs/latest-v4.x/api/tls.html">4.x</a></li> 3371cb0ef41Sopenharmony_ci<li><a href="https://nodejs.org/docs/latest-v0.12.x/api/tls.html">0.12.x</a></li> 3381cb0ef41Sopenharmony_ci<li><a href="https://nodejs.org/docs/latest-v0.10.x/api/tls.html">0.10.x</a></li></ol></div> 3391cb0ef41Sopenharmony_ci </li> 3401cb0ef41Sopenharmony_ci 3411cb0ef41Sopenharmony_ci <li class="picker-header"> 3421cb0ef41Sopenharmony_ci <a href="#"> 3431cb0ef41Sopenharmony_ci <span class="collapsed-arrow">►</span><span class="expanded-arrow">▼</span> 3441cb0ef41Sopenharmony_ci Options 3451cb0ef41Sopenharmony_ci </a> 3461cb0ef41Sopenharmony_ci 3471cb0ef41Sopenharmony_ci <div class="picker"> 3481cb0ef41Sopenharmony_ci <ul> 3491cb0ef41Sopenharmony_ci <li> 3501cb0ef41Sopenharmony_ci <a href="all.html">View on single page</a> 3511cb0ef41Sopenharmony_ci </li> 3521cb0ef41Sopenharmony_ci <li> 3531cb0ef41Sopenharmony_ci <a href="tls.json">View as JSON</a> 3541cb0ef41Sopenharmony_ci </li> 3551cb0ef41Sopenharmony_ci <li class="edit_on_github"><a href="https://github.com/nodejs/node/edit/main/doc/api/tls.md">Edit on GitHub</a></li> 3561cb0ef41Sopenharmony_ci </ul> 3571cb0ef41Sopenharmony_ci </div> 3581cb0ef41Sopenharmony_ci </li> 3591cb0ef41Sopenharmony_ci </ul> 3601cb0ef41Sopenharmony_ci </div> 3611cb0ef41Sopenharmony_ci <hr> 3621cb0ef41Sopenharmony_ci </header> 3631cb0ef41Sopenharmony_ci 3641cb0ef41Sopenharmony_ci <details id="toc" open><summary>Table of contents</summary><ul> 3651cb0ef41Sopenharmony_ci<li><span class="stability_2"><a href="#tls-ssl">TLS (SSL)</a></span> 3661cb0ef41Sopenharmony_ci<ul> 3671cb0ef41Sopenharmony_ci<li><a href="#determining-if-crypto-support-is-unavailable">Determining if crypto support is unavailable</a></li> 3681cb0ef41Sopenharmony_ci<li><a href="#tlsssl-concepts">TLS/SSL concepts</a> 3691cb0ef41Sopenharmony_ci<ul> 3701cb0ef41Sopenharmony_ci<li><a href="#perfect-forward-secrecy">Perfect forward secrecy</a></li> 3711cb0ef41Sopenharmony_ci<li><a href="#alpn-and-sni">ALPN and SNI</a></li> 3721cb0ef41Sopenharmony_ci<li><a href="#pre-shared-keys">Pre-shared keys</a></li> 3731cb0ef41Sopenharmony_ci<li><a href="#client-initiated-renegotiation-attack-mitigation">Client-initiated renegotiation attack mitigation</a></li> 3741cb0ef41Sopenharmony_ci<li><a href="#session-resumption">Session resumption</a> 3751cb0ef41Sopenharmony_ci<ul> 3761cb0ef41Sopenharmony_ci<li><a href="#session-identifiers">Session identifiers</a></li> 3771cb0ef41Sopenharmony_ci<li><a href="#session-tickets">Session tickets</a></li> 3781cb0ef41Sopenharmony_ci</ul> 3791cb0ef41Sopenharmony_ci</li> 3801cb0ef41Sopenharmony_ci</ul> 3811cb0ef41Sopenharmony_ci</li> 3821cb0ef41Sopenharmony_ci<li><a href="#modifying-the-default-tls-cipher-suite">Modifying the default TLS cipher suite</a></li> 3831cb0ef41Sopenharmony_ci<li><a href="#x509-certificate-error-codes">X509 certificate error codes</a></li> 3841cb0ef41Sopenharmony_ci<li><span class="stability_0"><a href="#class-tlscryptostream">Class: <code>tls.CryptoStream</code></a></span> 3851cb0ef41Sopenharmony_ci<ul> 3861cb0ef41Sopenharmony_ci<li><a href="#cryptostreambyteswritten"><code>cryptoStream.bytesWritten</code></a></li> 3871cb0ef41Sopenharmony_ci</ul> 3881cb0ef41Sopenharmony_ci</li> 3891cb0ef41Sopenharmony_ci<li><span class="stability_0"><a href="#class-tlssecurepair">Class: <code>tls.SecurePair</code></a></span> 3901cb0ef41Sopenharmony_ci<ul> 3911cb0ef41Sopenharmony_ci<li><a href="#event-secure">Event: <code>'secure'</code></a></li> 3921cb0ef41Sopenharmony_ci</ul> 3931cb0ef41Sopenharmony_ci</li> 3941cb0ef41Sopenharmony_ci<li><a href="#class-tlsserver">Class: <code>tls.Server</code></a> 3951cb0ef41Sopenharmony_ci<ul> 3961cb0ef41Sopenharmony_ci<li><a href="#event-connection">Event: <code>'connection'</code></a></li> 3971cb0ef41Sopenharmony_ci<li><a href="#event-keylog">Event: <code>'keylog'</code></a></li> 3981cb0ef41Sopenharmony_ci<li><a href="#event-newsession">Event: <code>'newSession'</code></a></li> 3991cb0ef41Sopenharmony_ci<li><a href="#event-ocsprequest">Event: <code>'OCSPRequest'</code></a></li> 4001cb0ef41Sopenharmony_ci<li><a href="#event-resumesession">Event: <code>'resumeSession'</code></a></li> 4011cb0ef41Sopenharmony_ci<li><a href="#event-secureconnection">Event: <code>'secureConnection'</code></a></li> 4021cb0ef41Sopenharmony_ci<li><a href="#event-tlsclienterror">Event: <code>'tlsClientError'</code></a></li> 4031cb0ef41Sopenharmony_ci<li><a href="#serveraddcontexthostname-context"><code>server.addContext(hostname, context)</code></a></li> 4041cb0ef41Sopenharmony_ci<li><a href="#serveraddress"><code>server.address()</code></a></li> 4051cb0ef41Sopenharmony_ci<li><a href="#serverclosecallback"><code>server.close([callback])</code></a></li> 4061cb0ef41Sopenharmony_ci<li><a href="#servergetticketkeys"><code>server.getTicketKeys()</code></a></li> 4071cb0ef41Sopenharmony_ci<li><a href="#serverlisten"><code>server.listen()</code></a></li> 4081cb0ef41Sopenharmony_ci<li><a href="#serversetsecurecontextoptions"><code>server.setSecureContext(options)</code></a></li> 4091cb0ef41Sopenharmony_ci<li><a href="#serversetticketkeyskeys"><code>server.setTicketKeys(keys)</code></a></li> 4101cb0ef41Sopenharmony_ci</ul> 4111cb0ef41Sopenharmony_ci</li> 4121cb0ef41Sopenharmony_ci<li><a href="#class-tlstlssocket">Class: <code>tls.TLSSocket</code></a> 4131cb0ef41Sopenharmony_ci<ul> 4141cb0ef41Sopenharmony_ci<li><a href="#new-tlstlssocketsocket-options"><code>new tls.TLSSocket(socket[, options])</code></a></li> 4151cb0ef41Sopenharmony_ci<li><a href="#event-keylog_1">Event: <code>'keylog'</code></a></li> 4161cb0ef41Sopenharmony_ci<li><a href="#event-ocspresponse">Event: <code>'OCSPResponse'</code></a></li> 4171cb0ef41Sopenharmony_ci<li><a href="#event-secureconnect">Event: <code>'secureConnect'</code></a></li> 4181cb0ef41Sopenharmony_ci<li><a href="#event-session">Event: <code>'session'</code></a></li> 4191cb0ef41Sopenharmony_ci<li><a href="#tlssocketaddress"><code>tlsSocket.address()</code></a></li> 4201cb0ef41Sopenharmony_ci<li><a href="#tlssocketauthorizationerror"><code>tlsSocket.authorizationError</code></a></li> 4211cb0ef41Sopenharmony_ci<li><a href="#tlssocketauthorized"><code>tlsSocket.authorized</code></a></li> 4221cb0ef41Sopenharmony_ci<li><a href="#tlssocketdisablerenegotiation"><code>tlsSocket.disableRenegotiation()</code></a></li> 4231cb0ef41Sopenharmony_ci<li><a href="#tlssocketenabletrace"><code>tlsSocket.enableTrace()</code></a></li> 4241cb0ef41Sopenharmony_ci<li><a href="#tlssocketencrypted"><code>tlsSocket.encrypted</code></a></li> 4251cb0ef41Sopenharmony_ci<li><a href="#tlssocketexportkeyingmateriallength-label-context"><code>tlsSocket.exportKeyingMaterial(length, label[, context])</code></a></li> 4261cb0ef41Sopenharmony_ci<li><a href="#tlssocketgetcertificate"><code>tlsSocket.getCertificate()</code></a></li> 4271cb0ef41Sopenharmony_ci<li><a href="#tlssocketgetcipher"><code>tlsSocket.getCipher()</code></a></li> 4281cb0ef41Sopenharmony_ci<li><a href="#tlssocketgetephemeralkeyinfo"><code>tlsSocket.getEphemeralKeyInfo()</code></a></li> 4291cb0ef41Sopenharmony_ci<li><a href="#tlssocketgetfinished"><code>tlsSocket.getFinished()</code></a></li> 4301cb0ef41Sopenharmony_ci<li><a href="#tlssocketgetpeercertificatedetailed"><code>tlsSocket.getPeerCertificate([detailed])</code></a> 4311cb0ef41Sopenharmony_ci<ul> 4321cb0ef41Sopenharmony_ci<li><a href="#certificate-object">Certificate object</a></li> 4331cb0ef41Sopenharmony_ci</ul> 4341cb0ef41Sopenharmony_ci</li> 4351cb0ef41Sopenharmony_ci<li><a href="#tlssocketgetpeerfinished"><code>tlsSocket.getPeerFinished()</code></a></li> 4361cb0ef41Sopenharmony_ci<li><a href="#tlssocketgetpeerx509certificate"><code>tlsSocket.getPeerX509Certificate()</code></a></li> 4371cb0ef41Sopenharmony_ci<li><a href="#tlssocketgetprotocol"><code>tlsSocket.getProtocol()</code></a></li> 4381cb0ef41Sopenharmony_ci<li><a href="#tlssocketgetsession"><code>tlsSocket.getSession()</code></a></li> 4391cb0ef41Sopenharmony_ci<li><a href="#tlssocketgetsharedsigalgs"><code>tlsSocket.getSharedSigalgs()</code></a></li> 4401cb0ef41Sopenharmony_ci<li><a href="#tlssocketgettlsticket"><code>tlsSocket.getTLSTicket()</code></a></li> 4411cb0ef41Sopenharmony_ci<li><a href="#tlssocketgetx509certificate"><code>tlsSocket.getX509Certificate()</code></a></li> 4421cb0ef41Sopenharmony_ci<li><a href="#tlssocketissessionreused"><code>tlsSocket.isSessionReused()</code></a></li> 4431cb0ef41Sopenharmony_ci<li><a href="#tlssocketlocaladdress"><code>tlsSocket.localAddress</code></a></li> 4441cb0ef41Sopenharmony_ci<li><a href="#tlssocketlocalport"><code>tlsSocket.localPort</code></a></li> 4451cb0ef41Sopenharmony_ci<li><a href="#tlssocketremoteaddress"><code>tlsSocket.remoteAddress</code></a></li> 4461cb0ef41Sopenharmony_ci<li><a href="#tlssocketremotefamily"><code>tlsSocket.remoteFamily</code></a></li> 4471cb0ef41Sopenharmony_ci<li><a href="#tlssocketremoteport"><code>tlsSocket.remotePort</code></a></li> 4481cb0ef41Sopenharmony_ci<li><a href="#tlssocketrenegotiateoptions-callback"><code>tlsSocket.renegotiate(options, callback)</code></a></li> 4491cb0ef41Sopenharmony_ci<li><a href="#tlssocketsetmaxsendfragmentsize"><code>tlsSocket.setMaxSendFragment(size)</code></a></li> 4501cb0ef41Sopenharmony_ci</ul> 4511cb0ef41Sopenharmony_ci</li> 4521cb0ef41Sopenharmony_ci<li><a href="#tlscheckserveridentityhostname-cert"><code>tls.checkServerIdentity(hostname, cert)</code></a></li> 4531cb0ef41Sopenharmony_ci<li><a href="#tlsconnectoptions-callback"><code>tls.connect(options[, callback])</code></a></li> 4541cb0ef41Sopenharmony_ci<li><a href="#tlsconnectpath-options-callback"><code>tls.connect(path[, options][, callback])</code></a></li> 4551cb0ef41Sopenharmony_ci<li><a href="#tlsconnectport-host-options-callback"><code>tls.connect(port[, host][, options][, callback])</code></a></li> 4561cb0ef41Sopenharmony_ci<li><a href="#tlscreatesecurecontextoptions"><code>tls.createSecureContext([options])</code></a></li> 4571cb0ef41Sopenharmony_ci<li><span class="stability_0"><a href="#tlscreatesecurepaircontext-isserver-requestcert-rejectunauthorized-options"><code>tls.createSecurePair([context][, isServer][, requestCert][, rejectUnauthorized][, options])</code></a></span></li> 4581cb0ef41Sopenharmony_ci<li><a href="#tlscreateserveroptions-secureconnectionlistener"><code>tls.createServer([options][, secureConnectionListener])</code></a></li> 4591cb0ef41Sopenharmony_ci<li><a href="#tlsgetciphers"><code>tls.getCiphers()</code></a></li> 4601cb0ef41Sopenharmony_ci<li><a href="#tlsrootcertificates"><code>tls.rootCertificates</code></a></li> 4611cb0ef41Sopenharmony_ci<li><a href="#tlsdefault_ecdh_curve"><code>tls.DEFAULT_ECDH_CURVE</code></a></li> 4621cb0ef41Sopenharmony_ci<li><a href="#tlsdefault_max_version"><code>tls.DEFAULT_MAX_VERSION</code></a></li> 4631cb0ef41Sopenharmony_ci<li><a href="#tlsdefault_min_version"><code>tls.DEFAULT_MIN_VERSION</code></a></li> 4641cb0ef41Sopenharmony_ci<li><a href="#tlsdefault_ciphers"><code>tls.DEFAULT_CIPHERS</code></a></li> 4651cb0ef41Sopenharmony_ci</ul> 4661cb0ef41Sopenharmony_ci</li> 4671cb0ef41Sopenharmony_ci</ul></details> 4681cb0ef41Sopenharmony_ci 4691cb0ef41Sopenharmony_ci <div id="apicontent"> 4701cb0ef41Sopenharmony_ci <h2>TLS (SSL)<span><a class="mark" href="#tls-ssl" id="tls-ssl">#</a></span><a aria-hidden="true" class="legacy" id="tls_tls_ssl"></a></h2> 4711cb0ef41Sopenharmony_ci 4721cb0ef41Sopenharmony_ci<p></p><div class="api_stability api_stability_2"><a href="documentation.html#stability-index">Stability: 2</a> - Stable</div><p></p> 4731cb0ef41Sopenharmony_ci<p><strong>Source Code:</strong> <a href="https://github.com/nodejs/node/blob/v18.20.1/lib/tls.js">lib/tls.js</a></p> 4741cb0ef41Sopenharmony_ci<p>The <code>node:tls</code> module provides an implementation of the Transport Layer Security 4751cb0ef41Sopenharmony_ci(TLS) and Secure Socket Layer (SSL) protocols that is built on top of OpenSSL. 4761cb0ef41Sopenharmony_ciThe module can be accessed using:</p> 4771cb0ef41Sopenharmony_ci<pre><code class="language-js"><span class="hljs-keyword">const</span> tls = <span class="hljs-built_in">require</span>(<span class="hljs-string">'node:tls'</span>);</code> <button class="copy-button">copy</button></pre> 4781cb0ef41Sopenharmony_ci<section><h3>Determining if crypto support is unavailable<span><a class="mark" href="#determining-if-crypto-support-is-unavailable" id="determining-if-crypto-support-is-unavailable">#</a></span><a aria-hidden="true" class="legacy" id="tls_determining_if_crypto_support_is_unavailable"></a></h3> 4791cb0ef41Sopenharmony_ci<p>It is possible for Node.js to be built without including support for the 4801cb0ef41Sopenharmony_ci<code>node:crypto</code> module. In such cases, attempting to <code>import</code> from <code>tls</code> or 4811cb0ef41Sopenharmony_cicalling <code>require('node:tls')</code> will result in an error being thrown.</p> 4821cb0ef41Sopenharmony_ci<p>When using CommonJS, the error thrown can be caught using try/catch:</p> 4831cb0ef41Sopenharmony_ci<!-- eslint-skip --> 4841cb0ef41Sopenharmony_ci<pre><code class="language-js cjs"><span class="hljs-keyword">let</span> tls; 4851cb0ef41Sopenharmony_ci<span class="hljs-keyword">try</span> { 4861cb0ef41Sopenharmony_ci tls = <span class="hljs-built_in">require</span>(<span class="hljs-string">'node:tls'</span>); 4871cb0ef41Sopenharmony_ci} <span class="hljs-keyword">catch</span> (err) { 4881cb0ef41Sopenharmony_ci <span class="hljs-variable language_">console</span>.<span class="hljs-title function_">error</span>(<span class="hljs-string">'tls support is disabled!'</span>); 4891cb0ef41Sopenharmony_ci}</code> <button class="copy-button">copy</button></pre> 4901cb0ef41Sopenharmony_ci<p>When using the lexical ESM <code>import</code> keyword, the error can only be 4911cb0ef41Sopenharmony_cicaught if a handler for <code>process.on('uncaughtException')</code> is registered 4921cb0ef41Sopenharmony_ci<em>before</em> any attempt to load the module is made (using, for instance, 4931cb0ef41Sopenharmony_cia preload module).</p> 4941cb0ef41Sopenharmony_ci<p>When using ESM, if there is a chance that the code may be run on a build 4951cb0ef41Sopenharmony_ciof Node.js where crypto support is not enabled, consider using the 4961cb0ef41Sopenharmony_ci<a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/import"><code>import()</code></a> function instead of the lexical <code>import</code> keyword:</p> 4971cb0ef41Sopenharmony_ci<pre><code class="language-js mjs"><span class="hljs-keyword">let</span> tls; 4981cb0ef41Sopenharmony_ci<span class="hljs-keyword">try</span> { 4991cb0ef41Sopenharmony_ci tls = <span class="hljs-keyword">await</span> <span class="hljs-keyword">import</span>(<span class="hljs-string">'node:tls'</span>); 5001cb0ef41Sopenharmony_ci} <span class="hljs-keyword">catch</span> (err) { 5011cb0ef41Sopenharmony_ci <span class="hljs-variable language_">console</span>.<span class="hljs-title function_">error</span>(<span class="hljs-string">'tls support is disabled!'</span>); 5021cb0ef41Sopenharmony_ci}</code> <button class="copy-button">copy</button></pre> 5031cb0ef41Sopenharmony_ci</section><section><h3>TLS/SSL concepts<span><a class="mark" href="#tlsssl-concepts" id="tlsssl-concepts">#</a></span><a aria-hidden="true" class="legacy" id="tls_tls_ssl_concepts"></a></h3> 5041cb0ef41Sopenharmony_ci<p>TLS/SSL is a set of protocols that rely on a public key infrastructure (PKI) to 5051cb0ef41Sopenharmony_cienable secure communication between a client and a server. For most common 5061cb0ef41Sopenharmony_cicases, each server must have a private key.</p> 5071cb0ef41Sopenharmony_ci<p>Private keys can be generated in multiple ways. The example below illustrates 5081cb0ef41Sopenharmony_ciuse of the OpenSSL command-line interface to generate a 2048-bit RSA private 5091cb0ef41Sopenharmony_cikey:</p> 5101cb0ef41Sopenharmony_ci<pre><code class="language-bash">openssl genrsa -out ryans-key.pem 2048</code> <button class="copy-button">copy</button></pre> 5111cb0ef41Sopenharmony_ci<p>With TLS/SSL, all servers (and some clients) must have a <em>certificate</em>. 5121cb0ef41Sopenharmony_ciCertificates are <em>public keys</em> that correspond to a private key, and that are 5131cb0ef41Sopenharmony_cidigitally signed either by a Certificate Authority or by the owner of the 5141cb0ef41Sopenharmony_ciprivate key (such certificates are referred to as "self-signed"). The first 5151cb0ef41Sopenharmony_cistep to obtaining a certificate is to create a <em>Certificate Signing Request</em> 5161cb0ef41Sopenharmony_ci(CSR) file.</p> 5171cb0ef41Sopenharmony_ci<p>The OpenSSL command-line interface can be used to generate a CSR for a private 5181cb0ef41Sopenharmony_cikey:</p> 5191cb0ef41Sopenharmony_ci<pre><code class="language-bash">openssl req -new -sha256 -key ryans-key.pem -out ryans-csr.pem</code> <button class="copy-button">copy</button></pre> 5201cb0ef41Sopenharmony_ci<p>Once the CSR file is generated, it can either be sent to a Certificate 5211cb0ef41Sopenharmony_ciAuthority for signing or used to generate a self-signed certificate.</p> 5221cb0ef41Sopenharmony_ci<p>Creating a self-signed certificate using the OpenSSL command-line interface 5231cb0ef41Sopenharmony_ciis illustrated in the example below:</p> 5241cb0ef41Sopenharmony_ci<pre><code class="language-bash">openssl x509 -req -<span class="hljs-keyword">in</span> ryans-csr.pem -signkey ryans-key.pem -out ryans-cert.pem</code> <button class="copy-button">copy</button></pre> 5251cb0ef41Sopenharmony_ci<p>Once the certificate is generated, it can be used to generate a <code>.pfx</code> or 5261cb0ef41Sopenharmony_ci<code>.p12</code> file:</p> 5271cb0ef41Sopenharmony_ci<pre><code class="language-bash">openssl pkcs12 -<span class="hljs-built_in">export</span> -<span class="hljs-keyword">in</span> ryans-cert.pem -inkey ryans-key.pem \ 5281cb0ef41Sopenharmony_ci -certfile ca-cert.pem -out ryans.pfx</code> <button class="copy-button">copy</button></pre> 5291cb0ef41Sopenharmony_ci<p>Where:</p> 5301cb0ef41Sopenharmony_ci<ul> 5311cb0ef41Sopenharmony_ci<li><code>in</code>: is the signed certificate</li> 5321cb0ef41Sopenharmony_ci<li><code>inkey</code>: is the associated private key</li> 5331cb0ef41Sopenharmony_ci<li><code>certfile</code>: is a concatenation of all Certificate Authority (CA) certs into 5341cb0ef41Sopenharmony_cia single file, e.g. <code>cat ca1-cert.pem ca2-cert.pem > ca-cert.pem</code></li> 5351cb0ef41Sopenharmony_ci</ul> 5361cb0ef41Sopenharmony_ci<h4>Perfect forward secrecy<span><a class="mark" href="#perfect-forward-secrecy" id="perfect-forward-secrecy">#</a></span><a aria-hidden="true" class="legacy" id="tls_perfect_forward_secrecy"></a></h4> 5371cb0ef41Sopenharmony_ci 5381cb0ef41Sopenharmony_ci<p>The term <em><a href="https://en.wikipedia.org/wiki/Perfect_forward_secrecy">forward secrecy</a></em> or <em>perfect forward secrecy</em> describes a feature 5391cb0ef41Sopenharmony_ciof key-agreement (i.e., key-exchange) methods. That is, the server and client 5401cb0ef41Sopenharmony_cikeys are used to negotiate new temporary keys that are used specifically and 5411cb0ef41Sopenharmony_cionly for the current communication session. Practically, this means that even 5421cb0ef41Sopenharmony_ciif the server's private key is compromised, communication can only be decrypted 5431cb0ef41Sopenharmony_ciby eavesdroppers if the attacker manages to obtain the key-pair specifically 5441cb0ef41Sopenharmony_cigenerated for the session.</p> 5451cb0ef41Sopenharmony_ci<p>Perfect forward secrecy is achieved by randomly generating a key pair for 5461cb0ef41Sopenharmony_cikey-agreement on every TLS/SSL handshake (in contrast to using the same key for 5471cb0ef41Sopenharmony_ciall sessions). Methods implementing this technique are called "ephemeral".</p> 5481cb0ef41Sopenharmony_ci<p>Currently two methods are commonly used to achieve perfect forward secrecy (note 5491cb0ef41Sopenharmony_cithe character "E" appended to the traditional abbreviations):</p> 5501cb0ef41Sopenharmony_ci<ul> 5511cb0ef41Sopenharmony_ci<li><a href="https://en.wikipedia.org/wiki/Elliptic_curve_Diffie%E2%80%93Hellman">ECDHE</a>: An ephemeral version of the Elliptic Curve Diffie-Hellman 5521cb0ef41Sopenharmony_cikey-agreement protocol.</li> 5531cb0ef41Sopenharmony_ci<li><a href="https://en.wikipedia.org/wiki/Diffie%E2%80%93Hellman_key_exchange">DHE</a>: An ephemeral version of the Diffie-Hellman key-agreement protocol.</li> 5541cb0ef41Sopenharmony_ci</ul> 5551cb0ef41Sopenharmony_ci<p>Perfect forward secrecy using ECDHE is enabled by default. The <code>ecdhCurve</code> 5561cb0ef41Sopenharmony_cioption can be used when creating a TLS server to customize the list of supported 5571cb0ef41Sopenharmony_ciECDH curves to use. See <a href="#tlscreateserveroptions-secureconnectionlistener"><code>tls.createServer()</code></a> for more info.</p> 5581cb0ef41Sopenharmony_ci<p>DHE is disabled by default but can be enabled alongside ECDHE by setting the 5591cb0ef41Sopenharmony_ci<code>dhparam</code> option to <code>'auto'</code>. Custom DHE parameters are also supported but 5601cb0ef41Sopenharmony_cidiscouraged in favor of automatically selected, well-known parameters.</p> 5611cb0ef41Sopenharmony_ci<p>Perfect forward secrecy was optional up to TLSv1.2. As of TLSv1.3, (EC)DHE is 5621cb0ef41Sopenharmony_cialways used (with the exception of PSK-only connections).</p> 5631cb0ef41Sopenharmony_ci<h4>ALPN and SNI<span><a class="mark" href="#alpn-and-sni" id="alpn-and-sni">#</a></span><a aria-hidden="true" class="legacy" id="tls_alpn_and_sni"></a></h4> 5641cb0ef41Sopenharmony_ci 5651cb0ef41Sopenharmony_ci<p>ALPN (Application-Layer Protocol Negotiation Extension) and 5661cb0ef41Sopenharmony_ciSNI (Server Name Indication) are TLS handshake extensions:</p> 5671cb0ef41Sopenharmony_ci<ul> 5681cb0ef41Sopenharmony_ci<li>ALPN: Allows the use of one TLS server for multiple protocols (HTTP, HTTP/2)</li> 5691cb0ef41Sopenharmony_ci<li>SNI: Allows the use of one TLS server for multiple hostnames with different 5701cb0ef41Sopenharmony_cicertificates.</li> 5711cb0ef41Sopenharmony_ci</ul> 5721cb0ef41Sopenharmony_ci<h4>Pre-shared keys<span><a class="mark" href="#pre-shared-keys" id="pre-shared-keys">#</a></span><a aria-hidden="true" class="legacy" id="tls_pre_shared_keys"></a></h4> 5731cb0ef41Sopenharmony_ci 5741cb0ef41Sopenharmony_ci<p>TLS-PSK support is available as an alternative to normal certificate-based 5751cb0ef41Sopenharmony_ciauthentication. It uses a pre-shared key instead of certificates to 5761cb0ef41Sopenharmony_ciauthenticate a TLS connection, providing mutual authentication. 5771cb0ef41Sopenharmony_ciTLS-PSK and public key infrastructure are not mutually exclusive. Clients and 5781cb0ef41Sopenharmony_ciservers can accommodate both, choosing either of them during the normal cipher 5791cb0ef41Sopenharmony_cinegotiation step.</p> 5801cb0ef41Sopenharmony_ci<p>TLS-PSK is only a good choice where means exist to securely share a 5811cb0ef41Sopenharmony_cikey with every connecting machine, so it does not replace the public key 5821cb0ef41Sopenharmony_ciinfrastructure (PKI) for the majority of TLS uses. 5831cb0ef41Sopenharmony_ciThe TLS-PSK implementation in OpenSSL has seen many security flaws in 5841cb0ef41Sopenharmony_cirecent years, mostly because it is used only by a minority of applications. 5851cb0ef41Sopenharmony_ciPlease consider all alternative solutions before switching to PSK ciphers. 5861cb0ef41Sopenharmony_ciUpon generating PSK it is of critical importance to use sufficient entropy as 5871cb0ef41Sopenharmony_cidiscussed in <a href="https://tools.ietf.org/html/rfc4086">RFC 4086</a>. Deriving a shared secret from a password or other 5881cb0ef41Sopenharmony_cilow-entropy sources is not secure.</p> 5891cb0ef41Sopenharmony_ci<p>PSK ciphers are disabled by default, and using TLS-PSK thus requires explicitly 5901cb0ef41Sopenharmony_cispecifying a cipher suite with the <code>ciphers</code> option. The list of available 5911cb0ef41Sopenharmony_ciciphers can be retrieved via <code>openssl ciphers -v 'PSK'</code>. All TLS 1.3 5921cb0ef41Sopenharmony_ciciphers are eligible for PSK and can be retrieved via 5931cb0ef41Sopenharmony_ci<code>openssl ciphers -v -s -tls1_3 -psk</code>.</p> 5941cb0ef41Sopenharmony_ci<p>According to the <a href="https://tools.ietf.org/html/rfc4279">RFC 4279</a>, PSK identities up to 128 bytes in length and 5951cb0ef41Sopenharmony_ciPSKs up to 64 bytes in length must be supported. As of OpenSSL 1.1.0 5961cb0ef41Sopenharmony_cimaximum identity size is 128 bytes, and maximum PSK length is 256 bytes.</p> 5971cb0ef41Sopenharmony_ci<p>The current implementation doesn't support asynchronous PSK callbacks due to the 5981cb0ef41Sopenharmony_cilimitations of the underlying OpenSSL API.</p> 5991cb0ef41Sopenharmony_ci<h4>Client-initiated renegotiation attack mitigation<span><a class="mark" href="#client-initiated-renegotiation-attack-mitigation" id="client-initiated-renegotiation-attack-mitigation">#</a></span><a aria-hidden="true" class="legacy" id="tls_client_initiated_renegotiation_attack_mitigation"></a></h4> 6001cb0ef41Sopenharmony_ci 6011cb0ef41Sopenharmony_ci<p>The TLS protocol allows clients to renegotiate certain aspects of the TLS 6021cb0ef41Sopenharmony_cisession. Unfortunately, session renegotiation requires a disproportionate amount 6031cb0ef41Sopenharmony_ciof server-side resources, making it a potential vector for denial-of-service 6041cb0ef41Sopenharmony_ciattacks.</p> 6051cb0ef41Sopenharmony_ci<p>To mitigate the risk, renegotiation is limited to three times every ten minutes. 6061cb0ef41Sopenharmony_ciAn <code>'error'</code> event is emitted on the <a href="#class-tlstlssocket"><code>tls.TLSSocket</code></a> instance when this 6071cb0ef41Sopenharmony_cithreshold is exceeded. The limits are configurable:</p> 6081cb0ef41Sopenharmony_ci<ul> 6091cb0ef41Sopenharmony_ci<li><code>tls.CLIENT_RENEG_LIMIT</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><number></a> Specifies the number of renegotiation 6101cb0ef41Sopenharmony_cirequests. <strong>Default:</strong> <code>3</code>.</li> 6111cb0ef41Sopenharmony_ci<li><code>tls.CLIENT_RENEG_WINDOW</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><number></a> Specifies the time renegotiation window 6121cb0ef41Sopenharmony_ciin seconds. <strong>Default:</strong> <code>600</code> (10 minutes).</li> 6131cb0ef41Sopenharmony_ci</ul> 6141cb0ef41Sopenharmony_ci<p>The default renegotiation limits should not be modified without a full 6151cb0ef41Sopenharmony_ciunderstanding of the implications and risks.</p> 6161cb0ef41Sopenharmony_ci<p>TLSv1.3 does not support renegotiation.</p> 6171cb0ef41Sopenharmony_ci<h4>Session resumption<span><a class="mark" href="#session-resumption" id="session-resumption">#</a></span><a aria-hidden="true" class="legacy" id="tls_session_resumption"></a></h4> 6181cb0ef41Sopenharmony_ci<p>Establishing a TLS session can be relatively slow. The process can be sped 6191cb0ef41Sopenharmony_ciup by saving and later reusing the session state. There are several mechanisms 6201cb0ef41Sopenharmony_cito do so, discussed here from oldest to newest (and preferred).</p> 6211cb0ef41Sopenharmony_ci<h5>Session identifiers<span><a class="mark" href="#session-identifiers" id="session-identifiers">#</a></span><a aria-hidden="true" class="legacy" id="tls_session_identifiers"></a></h5> 6221cb0ef41Sopenharmony_ci<p>Servers generate a unique ID for new connections and 6231cb0ef41Sopenharmony_cisend it to the client. Clients and servers save the session state. When 6241cb0ef41Sopenharmony_cireconnecting, clients send the ID of their saved session state and if the server 6251cb0ef41Sopenharmony_cialso has the state for that ID, it can agree to use it. Otherwise, the server 6261cb0ef41Sopenharmony_ciwill create a new session. See <a href="https://www.ietf.org/rfc/rfc2246.txt">RFC 2246</a> for more information, page 23 and 6271cb0ef41Sopenharmony_ci30.</p> 6281cb0ef41Sopenharmony_ci<p>Resumption using session identifiers is supported by most web browsers when 6291cb0ef41Sopenharmony_cimaking HTTPS requests.</p> 6301cb0ef41Sopenharmony_ci<p>For Node.js, clients wait for the <a href="#event-session"><code>'session'</code></a> event to get the session data, 6311cb0ef41Sopenharmony_ciand provide the data to the <code>session</code> option of a subsequent <a href="#tlsconnectoptions-callback"><code>tls.connect()</code></a> 6321cb0ef41Sopenharmony_cito reuse the session. Servers must 6331cb0ef41Sopenharmony_ciimplement handlers for the <a href="#event-newsession"><code>'newSession'</code></a> and <a href="#event-resumesession"><code>'resumeSession'</code></a> events 6341cb0ef41Sopenharmony_cito save and restore the session data using the session ID as the lookup key to 6351cb0ef41Sopenharmony_cireuse sessions. To reuse sessions across load balancers or cluster workers, 6361cb0ef41Sopenharmony_ciservers must use a shared session cache (such as Redis) in their session 6371cb0ef41Sopenharmony_cihandlers.</p> 6381cb0ef41Sopenharmony_ci<h5>Session tickets<span><a class="mark" href="#session-tickets" id="session-tickets">#</a></span><a aria-hidden="true" class="legacy" id="tls_session_tickets"></a></h5> 6391cb0ef41Sopenharmony_ci<p>The servers encrypt the entire session state and send it 6401cb0ef41Sopenharmony_cito the client as a "ticket". When reconnecting, the state is sent to the server 6411cb0ef41Sopenharmony_ciin the initial connection. This mechanism avoids the need for a server-side 6421cb0ef41Sopenharmony_cisession cache. If the server doesn't use the ticket, for any reason (failure 6431cb0ef41Sopenharmony_cito decrypt it, it's too old, etc.), it will create a new session and send a new 6441cb0ef41Sopenharmony_citicket. See <a href="https://tools.ietf.org/html/rfc5077">RFC 5077</a> for more information.</p> 6451cb0ef41Sopenharmony_ci<p>Resumption using session tickets is becoming commonly supported by many web 6461cb0ef41Sopenharmony_cibrowsers when making HTTPS requests.</p> 6471cb0ef41Sopenharmony_ci<p>For Node.js, clients use the same APIs for resumption with session identifiers 6481cb0ef41Sopenharmony_cias for resumption with session tickets. For debugging, if 6491cb0ef41Sopenharmony_ci<a href="#tlssocketgettlsticket"><code>tls.TLSSocket.getTLSTicket()</code></a> returns a value, the session data contains a 6501cb0ef41Sopenharmony_citicket, otherwise it contains client-side session state.</p> 6511cb0ef41Sopenharmony_ci<p>With TLSv1.3, be aware that multiple tickets may be sent by the server, 6521cb0ef41Sopenharmony_ciresulting in multiple <code>'session'</code> events, see <a href="#event-session"><code>'session'</code></a> for more 6531cb0ef41Sopenharmony_ciinformation.</p> 6541cb0ef41Sopenharmony_ci<p>Single process servers need no specific implementation to use session tickets. 6551cb0ef41Sopenharmony_ciTo use session tickets across server restarts or load balancers, servers must 6561cb0ef41Sopenharmony_ciall have the same ticket keys. There are three 16-byte keys internally, but the 6571cb0ef41Sopenharmony_citls API exposes them as a single 48-byte buffer for convenience.</p> 6581cb0ef41Sopenharmony_ci<p>It's possible to get the ticket keys by calling <a href="#servergetticketkeys"><code>server.getTicketKeys()</code></a> on 6591cb0ef41Sopenharmony_cione server instance and then distribute them, but it is more reasonable to 6601cb0ef41Sopenharmony_cisecurely generate 48 bytes of secure random data and set them with the 6611cb0ef41Sopenharmony_ci<code>ticketKeys</code> option of <a href="#tlscreateserveroptions-secureconnectionlistener"><code>tls.createServer()</code></a>. The keys should be regularly 6621cb0ef41Sopenharmony_ciregenerated and server's keys can be reset with 6631cb0ef41Sopenharmony_ci<a href="#serversetticketkeyskeys"><code>server.setTicketKeys()</code></a>.</p> 6641cb0ef41Sopenharmony_ci<p>Session ticket keys are cryptographic keys, and they <em><strong>must be stored 6651cb0ef41Sopenharmony_cisecurely</strong></em>. With TLS 1.2 and below, if they are compromised all sessions that 6661cb0ef41Sopenharmony_ciused tickets encrypted with them can be decrypted. They should not be stored 6671cb0ef41Sopenharmony_cion disk, and they should be regenerated regularly.</p> 6681cb0ef41Sopenharmony_ci<p>If clients advertise support for tickets, the server will send them. The 6691cb0ef41Sopenharmony_ciserver can disable tickets by supplying 6701cb0ef41Sopenharmony_ci<code>require('node:constants').SSL_OP_NO_TICKET</code> in <code>secureOptions</code>.</p> 6711cb0ef41Sopenharmony_ci<p>Both session identifiers and session tickets timeout, causing the server to 6721cb0ef41Sopenharmony_cicreate new sessions. The timeout can be configured with the <code>sessionTimeout</code> 6731cb0ef41Sopenharmony_cioption of <a href="#tlscreateserveroptions-secureconnectionlistener"><code>tls.createServer()</code></a>.</p> 6741cb0ef41Sopenharmony_ci<p>For all the mechanisms, when resumption fails, servers will create new sessions. 6751cb0ef41Sopenharmony_ciSince failing to resume the session does not cause TLS/HTTPS connection 6761cb0ef41Sopenharmony_cifailures, it is easy to not notice unnecessarily poor TLS performance. The 6771cb0ef41Sopenharmony_ciOpenSSL CLI can be used to verify that servers are resuming sessions. Use the 6781cb0ef41Sopenharmony_ci<code>-reconnect</code> option to <code>openssl s_client</code>, for example:</p> 6791cb0ef41Sopenharmony_ci<pre><code class="language-console"><span class="hljs-meta prompt_">$ </span><span class="language-bash">openssl s_client -connect localhost:443 -reconnect</span></code> <button class="copy-button">copy</button></pre> 6801cb0ef41Sopenharmony_ci<p>Read through the debug output. The first connection should say "New", for 6811cb0ef41Sopenharmony_ciexample:</p> 6821cb0ef41Sopenharmony_ci<pre><code class="language-text">New, TLSv1.2, Cipher is ECDHE-RSA-AES128-GCM-SHA256</code> <button class="copy-button">copy</button></pre> 6831cb0ef41Sopenharmony_ci<p>Subsequent connections should say "Reused", for example:</p> 6841cb0ef41Sopenharmony_ci<pre><code class="language-text">Reused, TLSv1.2, Cipher is ECDHE-RSA-AES128-GCM-SHA256</code> <button class="copy-button">copy</button></pre> 6851cb0ef41Sopenharmony_ci</section><section><h3>Modifying the default TLS cipher suite<span><a class="mark" href="#modifying-the-default-tls-cipher-suite" id="modifying-the-default-tls-cipher-suite">#</a></span><a aria-hidden="true" class="legacy" id="tls_modifying_the_default_tls_cipher_suite"></a></h3> 6861cb0ef41Sopenharmony_ci<p>Node.js is built with a default suite of enabled and disabled TLS ciphers. This 6871cb0ef41Sopenharmony_cidefault cipher list can be configured when building Node.js to allow 6881cb0ef41Sopenharmony_cidistributions to provide their own default list.</p> 6891cb0ef41Sopenharmony_ci<p>The following command can be used to show the default cipher suite:</p> 6901cb0ef41Sopenharmony_ci<pre><code class="language-console">node -p crypto.constants.defaultCoreCipherList | tr ':' '\n' 6911cb0ef41Sopenharmony_ciTLS_AES_256_GCM_SHA384 6921cb0ef41Sopenharmony_ciTLS_CHACHA20_POLY1305_SHA256 6931cb0ef41Sopenharmony_ciTLS_AES_128_GCM_SHA256 6941cb0ef41Sopenharmony_ciECDHE-RSA-AES128-GCM-SHA256 6951cb0ef41Sopenharmony_ciECDHE-ECDSA-AES128-GCM-SHA256 6961cb0ef41Sopenharmony_ciECDHE-RSA-AES256-GCM-SHA384 6971cb0ef41Sopenharmony_ciECDHE-ECDSA-AES256-GCM-SHA384 6981cb0ef41Sopenharmony_ciDHE-RSA-AES128-GCM-SHA256 6991cb0ef41Sopenharmony_ciECDHE-RSA-AES128-SHA256 7001cb0ef41Sopenharmony_ciDHE-RSA-AES128-SHA256 7011cb0ef41Sopenharmony_ciECDHE-RSA-AES256-SHA384 7021cb0ef41Sopenharmony_ciDHE-RSA-AES256-SHA384 7031cb0ef41Sopenharmony_ciECDHE-RSA-AES256-SHA256 7041cb0ef41Sopenharmony_ciDHE-RSA-AES256-SHA256 7051cb0ef41Sopenharmony_ciHIGH 7061cb0ef41Sopenharmony_ci!aNULL 7071cb0ef41Sopenharmony_ci!eNULL 7081cb0ef41Sopenharmony_ci!EXPORT 7091cb0ef41Sopenharmony_ci!DES 7101cb0ef41Sopenharmony_ci!RC4 7111cb0ef41Sopenharmony_ci!MD5 7121cb0ef41Sopenharmony_ci!PSK 7131cb0ef41Sopenharmony_ci!SRP 7141cb0ef41Sopenharmony_ci!CAMELLIA</code> <button class="copy-button">copy</button></pre> 7151cb0ef41Sopenharmony_ci<p>This default can be replaced entirely using the <a href="cli.html#--tls-cipher-listlist"><code>--tls-cipher-list</code></a> 7161cb0ef41Sopenharmony_cicommand-line switch (directly, or via the <a href="cli.html#node_optionsoptions"><code>NODE_OPTIONS</code></a> environment 7171cb0ef41Sopenharmony_civariable). For instance, the following makes <code>ECDHE-RSA-AES128-GCM-SHA256:!RC4</code> 7181cb0ef41Sopenharmony_cithe default TLS cipher suite:</p> 7191cb0ef41Sopenharmony_ci<pre><code class="language-bash">node --tls-cipher-list=<span class="hljs-string">'ECDHE-RSA-AES128-GCM-SHA256:!RC4'</span> server.js 7201cb0ef41Sopenharmony_ci 7211cb0ef41Sopenharmony_ci<span class="hljs-built_in">export</span> NODE_OPTIONS=--tls-cipher-list=<span class="hljs-string">'ECDHE-RSA-AES128-GCM-SHA256:!RC4'</span> 7221cb0ef41Sopenharmony_cinode server.js</code> <button class="copy-button">copy</button></pre> 7231cb0ef41Sopenharmony_ci<p>To verify, use the following command to show the set cipher list, note the 7241cb0ef41Sopenharmony_cidifference between <code>defaultCoreCipherList</code> and <code>defaultCipherList</code>:</p> 7251cb0ef41Sopenharmony_ci<pre><code class="language-bash">node --tls-cipher-list=<span class="hljs-string">'ECDHE-RSA-AES128-GCM-SHA256:!RC4'</span> -p crypto.constants.defaultCipherList | <span class="hljs-built_in">tr</span> <span class="hljs-string">':'</span> <span class="hljs-string">'\n'</span> 7261cb0ef41Sopenharmony_ciECDHE-RSA-AES128-GCM-SHA256 7271cb0ef41Sopenharmony_ci!RC4</code> <button class="copy-button">copy</button></pre> 7281cb0ef41Sopenharmony_ci<p>i.e. the <code>defaultCoreCipherList</code> list is set at compilation time and the 7291cb0ef41Sopenharmony_ci<code>defaultCipherList</code> is set at runtime.</p> 7301cb0ef41Sopenharmony_ci<p>To modify the default cipher suites from within the runtime, modify the 7311cb0ef41Sopenharmony_ci<code>tls.DEFAULT_CIPHERS</code> variable, this must be performed before listening on any 7321cb0ef41Sopenharmony_cisockets, it will not affect sockets already opened. For example:</p> 7331cb0ef41Sopenharmony_ci<pre><code class="language-js"><span class="hljs-comment">// Remove Obsolete CBC Ciphers and RSA Key Exchange based Ciphers as they don't provide Forward Secrecy</span> 7341cb0ef41Sopenharmony_citls.<span class="hljs-property">DEFAULT_CIPHERS</span> += 7351cb0ef41Sopenharmony_ci <span class="hljs-string">':!ECDHE-RSA-AES128-SHA:!ECDHE-RSA-AES128-SHA256:!ECDHE-RSA-AES256-SHA:!ECDHE-RSA-AES256-SHA384'</span> + 7361cb0ef41Sopenharmony_ci <span class="hljs-string">':!ECDHE-ECDSA-AES128-SHA:!ECDHE-ECDSA-AES128-SHA256:!ECDHE-ECDSA-AES256-SHA:!ECDHE-ECDSA-AES256-SHA384'</span> + 7371cb0ef41Sopenharmony_ci <span class="hljs-string">':!kRSA'</span>;</code> <button class="copy-button">copy</button></pre> 7381cb0ef41Sopenharmony_ci<p>The default can also be replaced on a per client or server basis using the 7391cb0ef41Sopenharmony_ci<code>ciphers</code> option from <a href="#tlscreatesecurecontextoptions"><code>tls.createSecureContext()</code></a>, which is also available 7401cb0ef41Sopenharmony_ciin <a href="#tlscreateserveroptions-secureconnectionlistener"><code>tls.createServer()</code></a>, <a href="#tlsconnectoptions-callback"><code>tls.connect()</code></a>, and when creating new 7411cb0ef41Sopenharmony_ci<a href="#class-tlstlssocket"><code>tls.TLSSocket</code></a>s.</p> 7421cb0ef41Sopenharmony_ci<p>The ciphers list can contain a mixture of TLSv1.3 cipher suite names, the ones 7431cb0ef41Sopenharmony_cithat start with <code>'TLS_'</code>, and specifications for TLSv1.2 and below cipher 7441cb0ef41Sopenharmony_cisuites. The TLSv1.2 ciphers support a legacy specification format, consult 7451cb0ef41Sopenharmony_cithe OpenSSL <a href="https://www.openssl.org/docs/man1.1.1/man1/ciphers.html#CIPHER-LIST-FORMAT">cipher list format</a> documentation for details, but those 7461cb0ef41Sopenharmony_cispecifications do <em>not</em> apply to TLSv1.3 ciphers. The TLSv1.3 suites can only 7471cb0ef41Sopenharmony_cibe enabled by including their full name in the cipher list. They cannot, for 7481cb0ef41Sopenharmony_ciexample, be enabled or disabled by using the legacy TLSv1.2 <code>'EECDH'</code> or 7491cb0ef41Sopenharmony_ci<code>'!EECDH'</code> specification.</p> 7501cb0ef41Sopenharmony_ci<p>Despite the relative order of TLSv1.3 and TLSv1.2 cipher suites, the TLSv1.3 7511cb0ef41Sopenharmony_ciprotocol is significantly more secure than TLSv1.2, and will always be chosen 7521cb0ef41Sopenharmony_ciover TLSv1.2 if the handshake indicates it is supported, and if any TLSv1.3 7531cb0ef41Sopenharmony_cicipher suites are enabled.</p> 7541cb0ef41Sopenharmony_ci<p>The default cipher suite included within Node.js has been carefully 7551cb0ef41Sopenharmony_ciselected to reflect current security best practices and risk mitigation. 7561cb0ef41Sopenharmony_ciChanging the default cipher suite can have a significant impact on the security 7571cb0ef41Sopenharmony_ciof an application. The <code>--tls-cipher-list</code> switch and <code>ciphers</code> option should by 7581cb0ef41Sopenharmony_ciused only if absolutely necessary.</p> 7591cb0ef41Sopenharmony_ci<p>The default cipher suite prefers GCM ciphers for <a href="https://www.chromium.org/Home/chromium-security/education/tls#TOC-Cipher-Suites">Chrome's 'modern 7601cb0ef41Sopenharmony_cicryptography' setting</a> and also prefers ECDHE and DHE ciphers for perfect 7611cb0ef41Sopenharmony_ciforward secrecy, while offering <em>some</em> backward compatibility.</p> 7621cb0ef41Sopenharmony_ci<p>Old clients that rely on insecure and deprecated RC4 or DES-based ciphers 7631cb0ef41Sopenharmony_ci(like Internet Explorer 6) cannot complete the handshaking process with 7641cb0ef41Sopenharmony_cithe default configuration. If these clients <em>must</em> be supported, the 7651cb0ef41Sopenharmony_ci<a href="https://wiki.mozilla.org/Security/Server_Side_TLS">TLS recommendations</a> may offer a compatible cipher suite. For more details 7661cb0ef41Sopenharmony_cion the format, see the OpenSSL <a href="https://www.openssl.org/docs/man1.1.1/man1/ciphers.html#CIPHER-LIST-FORMAT">cipher list format</a> documentation.</p> 7671cb0ef41Sopenharmony_ci<p>There are only five TLSv1.3 cipher suites:</p> 7681cb0ef41Sopenharmony_ci<ul> 7691cb0ef41Sopenharmony_ci<li><code>'TLS_AES_256_GCM_SHA384'</code></li> 7701cb0ef41Sopenharmony_ci<li><code>'TLS_CHACHA20_POLY1305_SHA256'</code></li> 7711cb0ef41Sopenharmony_ci<li><code>'TLS_AES_128_GCM_SHA256'</code></li> 7721cb0ef41Sopenharmony_ci<li><code>'TLS_AES_128_CCM_SHA256'</code></li> 7731cb0ef41Sopenharmony_ci<li><code>'TLS_AES_128_CCM_8_SHA256'</code></li> 7741cb0ef41Sopenharmony_ci</ul> 7751cb0ef41Sopenharmony_ci<p>The first three are enabled by default. The two <code>CCM</code>-based suites are supported 7761cb0ef41Sopenharmony_ciby TLSv1.3 because they may be more performant on constrained systems, but they 7771cb0ef41Sopenharmony_ciare not enabled by default since they offer less security.</p> 7781cb0ef41Sopenharmony_ci</section><section><h3>X509 certificate error codes<span><a class="mark" href="#x509-certificate-error-codes" id="x509-certificate-error-codes">#</a></span><a aria-hidden="true" class="legacy" id="tls_x509_certificate_error_codes"></a></h3> 7791cb0ef41Sopenharmony_ci<p>Multiple functions can fail due to certificate errors that are reported by 7801cb0ef41Sopenharmony_ciOpenSSL. In such a case, the function provides an <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error" class="type"><Error></a> via its callback that 7811cb0ef41Sopenharmony_cihas the property <code>code</code> which can take one of the following values:</p> 7821cb0ef41Sopenharmony_ci<!-- 7831cb0ef41Sopenharmony_civalues are taken from src/crypto/crypto_common.cc 7841cb0ef41Sopenharmony_cidescription are taken from deps/openssl/openssl/crypto/x509/x509_txt.c 7851cb0ef41Sopenharmony_ci--> 7861cb0ef41Sopenharmony_ci<ul> 7871cb0ef41Sopenharmony_ci<li><code>'UNABLE_TO_GET_ISSUER_CERT'</code>: Unable to get issuer certificate.</li> 7881cb0ef41Sopenharmony_ci<li><code>'UNABLE_TO_GET_CRL'</code>: Unable to get certificate CRL.</li> 7891cb0ef41Sopenharmony_ci<li><code>'UNABLE_TO_DECRYPT_CERT_SIGNATURE'</code>: Unable to decrypt certificate's 7901cb0ef41Sopenharmony_cisignature.</li> 7911cb0ef41Sopenharmony_ci<li><code>'UNABLE_TO_DECRYPT_CRL_SIGNATURE'</code>: Unable to decrypt CRL's signature.</li> 7921cb0ef41Sopenharmony_ci<li><code>'UNABLE_TO_DECODE_ISSUER_PUBLIC_KEY'</code>: Unable to decode issuer public key.</li> 7931cb0ef41Sopenharmony_ci<li><code>'CERT_SIGNATURE_FAILURE'</code>: Certificate signature failure.</li> 7941cb0ef41Sopenharmony_ci<li><code>'CRL_SIGNATURE_FAILURE'</code>: CRL signature failure.</li> 7951cb0ef41Sopenharmony_ci<li><code>'CERT_NOT_YET_VALID'</code>: Certificate is not yet valid.</li> 7961cb0ef41Sopenharmony_ci<li><code>'CERT_HAS_EXPIRED'</code>: Certificate has expired.</li> 7971cb0ef41Sopenharmony_ci<li><code>'CRL_NOT_YET_VALID'</code>: CRL is not yet valid.</li> 7981cb0ef41Sopenharmony_ci<li><code>'CRL_HAS_EXPIRED'</code>: CRL has expired.</li> 7991cb0ef41Sopenharmony_ci<li><code>'ERROR_IN_CERT_NOT_BEFORE_FIELD'</code>: Format error in certificate's notBefore 8001cb0ef41Sopenharmony_cifield.</li> 8011cb0ef41Sopenharmony_ci<li><code>'ERROR_IN_CERT_NOT_AFTER_FIELD'</code>: Format error in certificate's notAfter 8021cb0ef41Sopenharmony_cifield.</li> 8031cb0ef41Sopenharmony_ci<li><code>'ERROR_IN_CRL_LAST_UPDATE_FIELD'</code>: Format error in CRL's lastUpdate field.</li> 8041cb0ef41Sopenharmony_ci<li><code>'ERROR_IN_CRL_NEXT_UPDATE_FIELD'</code>: Format error in CRL's nextUpdate field.</li> 8051cb0ef41Sopenharmony_ci<li><code>'OUT_OF_MEM'</code>: Out of memory.</li> 8061cb0ef41Sopenharmony_ci<li><code>'DEPTH_ZERO_SELF_SIGNED_CERT'</code>: Self signed certificate.</li> 8071cb0ef41Sopenharmony_ci<li><code>'SELF_SIGNED_CERT_IN_CHAIN'</code>: Self signed certificate in certificate chain.</li> 8081cb0ef41Sopenharmony_ci<li><code>'UNABLE_TO_GET_ISSUER_CERT_LOCALLY'</code>: Unable to get local issuer certificate.</li> 8091cb0ef41Sopenharmony_ci<li><code>'UNABLE_TO_VERIFY_LEAF_SIGNATURE'</code>: Unable to verify the first certificate.</li> 8101cb0ef41Sopenharmony_ci<li><code>'CERT_CHAIN_TOO_LONG'</code>: Certificate chain too long.</li> 8111cb0ef41Sopenharmony_ci<li><code>'CERT_REVOKED'</code>: Certificate revoked.</li> 8121cb0ef41Sopenharmony_ci<li><code>'INVALID_CA'</code>: Invalid CA certificate.</li> 8131cb0ef41Sopenharmony_ci<li><code>'PATH_LENGTH_EXCEEDED'</code>: Path length constraint exceeded.</li> 8141cb0ef41Sopenharmony_ci<li><code>'INVALID_PURPOSE'</code>: Unsupported certificate purpose.</li> 8151cb0ef41Sopenharmony_ci<li><code>'CERT_UNTRUSTED'</code>: Certificate not trusted.</li> 8161cb0ef41Sopenharmony_ci<li><code>'CERT_REJECTED'</code>: Certificate rejected.</li> 8171cb0ef41Sopenharmony_ci<li><code>'HOSTNAME_MISMATCH'</code>: Hostname mismatch.</li> 8181cb0ef41Sopenharmony_ci</ul> 8191cb0ef41Sopenharmony_ci</section><section><h3>Class: <code>tls.CryptoStream</code><span><a class="mark" href="#class-tlscryptostream" id="class-tlscryptostream">#</a></span><a aria-hidden="true" class="legacy" id="tls_class_tls_cryptostream"></a></h3> 8201cb0ef41Sopenharmony_ci<div class="api_metadata"> 8211cb0ef41Sopenharmony_ci<span>Added in: v0.3.4</span><span>Deprecated since: v0.11.3</span> 8221cb0ef41Sopenharmony_ci</div> 8231cb0ef41Sopenharmony_ci<p></p><div class="api_stability api_stability_0"><a href="documentation.html#stability-index">Stability: 0</a> - Deprecated: Use <a href="#class-tlstlssocket"><code>tls.TLSSocket</code></a> instead.</div><p></p> 8241cb0ef41Sopenharmony_ci<p>The <code>tls.CryptoStream</code> class represents a stream of encrypted data. This class 8251cb0ef41Sopenharmony_ciis deprecated and should no longer be used.</p> 8261cb0ef41Sopenharmony_ci<h4><code>cryptoStream.bytesWritten</code><span><a class="mark" href="#cryptostreambyteswritten" id="cryptostreambyteswritten">#</a></span><a aria-hidden="true" class="legacy" id="tls_cryptostream_byteswritten"></a></h4> 8271cb0ef41Sopenharmony_ci<div class="api_metadata"> 8281cb0ef41Sopenharmony_ci<span>Added in: v0.3.4</span><span>Deprecated since: v0.11.3</span> 8291cb0ef41Sopenharmony_ci</div> 8301cb0ef41Sopenharmony_ci<p>The <code>cryptoStream.bytesWritten</code> property returns the total number of bytes 8311cb0ef41Sopenharmony_ciwritten to the underlying socket <em>including</em> the bytes required for the 8321cb0ef41Sopenharmony_ciimplementation of the TLS protocol.</p> 8331cb0ef41Sopenharmony_ci</section><section><h3>Class: <code>tls.SecurePair</code><span><a class="mark" href="#class-tlssecurepair" id="class-tlssecurepair">#</a></span><a aria-hidden="true" class="legacy" id="tls_class_tls_securepair"></a></h3> 8341cb0ef41Sopenharmony_ci<div class="api_metadata"> 8351cb0ef41Sopenharmony_ci<span>Added in: v0.3.2</span><span>Deprecated since: v0.11.3</span> 8361cb0ef41Sopenharmony_ci</div> 8371cb0ef41Sopenharmony_ci<p></p><div class="api_stability api_stability_0"><a href="documentation.html#stability-index">Stability: 0</a> - Deprecated: Use <a href="#class-tlstlssocket"><code>tls.TLSSocket</code></a> instead.</div><p></p> 8381cb0ef41Sopenharmony_ci<p>Returned by <a href="#tlscreatesecurepaircontext-isserver-requestcert-rejectunauthorized-options"><code>tls.createSecurePair()</code></a>.</p> 8391cb0ef41Sopenharmony_ci<h4>Event: <code>'secure'</code><span><a class="mark" href="#event-secure" id="event-secure">#</a></span><a aria-hidden="true" class="legacy" id="tls_event_secure"></a></h4> 8401cb0ef41Sopenharmony_ci<div class="api_metadata"> 8411cb0ef41Sopenharmony_ci<span>Added in: v0.3.2</span><span>Deprecated since: v0.11.3</span> 8421cb0ef41Sopenharmony_ci</div> 8431cb0ef41Sopenharmony_ci<p>The <code>'secure'</code> event is emitted by the <code>SecurePair</code> object once a secure 8441cb0ef41Sopenharmony_ciconnection has been established.</p> 8451cb0ef41Sopenharmony_ci<p>As with checking for the server 8461cb0ef41Sopenharmony_ci<a href="#event-secureconnection"><code>'secureConnection'</code></a> 8471cb0ef41Sopenharmony_cievent, <code>pair.cleartext.authorized</code> should be inspected to confirm whether the 8481cb0ef41Sopenharmony_cicertificate used is properly authorized.</p> 8491cb0ef41Sopenharmony_ci</section><section><h3>Class: <code>tls.Server</code><span><a class="mark" href="#class-tlsserver" id="class-tlsserver">#</a></span><a aria-hidden="true" class="legacy" id="tls_class_tls_server"></a></h3> 8501cb0ef41Sopenharmony_ci<div class="api_metadata"> 8511cb0ef41Sopenharmony_ci<span>Added in: v0.3.2</span> 8521cb0ef41Sopenharmony_ci</div> 8531cb0ef41Sopenharmony_ci<ul> 8541cb0ef41Sopenharmony_ci<li>Extends: <a href="net.html#class-netserver" class="type"><net.Server></a></li> 8551cb0ef41Sopenharmony_ci</ul> 8561cb0ef41Sopenharmony_ci<p>Accepts encrypted connections using TLS or SSL.</p> 8571cb0ef41Sopenharmony_ci<h4>Event: <code>'connection'</code><span><a class="mark" href="#event-connection" id="event-connection">#</a></span><a aria-hidden="true" class="legacy" id="tls_event_connection"></a></h4> 8581cb0ef41Sopenharmony_ci<div class="api_metadata"> 8591cb0ef41Sopenharmony_ci<span>Added in: v0.3.2</span> 8601cb0ef41Sopenharmony_ci</div> 8611cb0ef41Sopenharmony_ci<ul> 8621cb0ef41Sopenharmony_ci<li><code>socket</code> <a href="stream.html#class-streamduplex" class="type"><stream.Duplex></a></li> 8631cb0ef41Sopenharmony_ci</ul> 8641cb0ef41Sopenharmony_ci<p>This event is emitted when a new TCP stream is established, before the TLS 8651cb0ef41Sopenharmony_cihandshake begins. <code>socket</code> is typically an object of type <a href="net.html#class-netsocket"><code>net.Socket</code></a> but 8661cb0ef41Sopenharmony_ciwill not receive events unlike the socket created from the <a href="net.html#class-netserver"><code>net.Server</code></a> 8671cb0ef41Sopenharmony_ci<code>'connection'</code> event. Usually users will not want to access this event.</p> 8681cb0ef41Sopenharmony_ci<p>This event can also be explicitly emitted by users to inject connections 8691cb0ef41Sopenharmony_ciinto the TLS server. In that case, any <a href="stream.html#class-streamduplex"><code>Duplex</code></a> stream can be passed.</p> 8701cb0ef41Sopenharmony_ci<h4>Event: <code>'keylog'</code><span><a class="mark" href="#event-keylog" id="event-keylog">#</a></span><a aria-hidden="true" class="legacy" id="tls_event_keylog"></a></h4> 8711cb0ef41Sopenharmony_ci<div class="api_metadata"> 8721cb0ef41Sopenharmony_ci<span>Added in: v12.3.0, v10.20.0</span> 8731cb0ef41Sopenharmony_ci</div> 8741cb0ef41Sopenharmony_ci<ul> 8751cb0ef41Sopenharmony_ci<li><code>line</code> <a href="buffer.html#class-buffer" class="type"><Buffer></a> Line of ASCII text, in NSS <code>SSLKEYLOGFILE</code> format.</li> 8761cb0ef41Sopenharmony_ci<li><code>tlsSocket</code> <a href="tls.html#class-tlstlssocket" class="type"><tls.TLSSocket></a> The <code>tls.TLSSocket</code> instance on which it was 8771cb0ef41Sopenharmony_cigenerated.</li> 8781cb0ef41Sopenharmony_ci</ul> 8791cb0ef41Sopenharmony_ci<p>The <code>keylog</code> event is emitted when key material is generated or received by 8801cb0ef41Sopenharmony_cia connection to this server (typically before handshake has completed, but not 8811cb0ef41Sopenharmony_cinecessarily). This keying material can be stored for debugging, as it allows 8821cb0ef41Sopenharmony_cicaptured TLS traffic to be decrypted. It may be emitted multiple times for 8831cb0ef41Sopenharmony_cieach socket.</p> 8841cb0ef41Sopenharmony_ci<p>A typical use case is to append received lines to a common text file, which 8851cb0ef41Sopenharmony_ciis later used by software (such as Wireshark) to decrypt the traffic:</p> 8861cb0ef41Sopenharmony_ci<pre><code class="language-js"><span class="hljs-keyword">const</span> logFile = fs.<span class="hljs-title function_">createWriteStream</span>(<span class="hljs-string">'/tmp/ssl-keys.log'</span>, { <span class="hljs-attr">flags</span>: <span class="hljs-string">'a'</span> }); 8871cb0ef41Sopenharmony_ci<span class="hljs-comment">// ...</span> 8881cb0ef41Sopenharmony_ciserver.<span class="hljs-title function_">on</span>(<span class="hljs-string">'keylog'</span>, <span class="hljs-function">(<span class="hljs-params">line, tlsSocket</span>) =></span> { 8891cb0ef41Sopenharmony_ci <span class="hljs-keyword">if</span> (tlsSocket.<span class="hljs-property">remoteAddress</span> !== <span class="hljs-string">'...'</span>) 8901cb0ef41Sopenharmony_ci <span class="hljs-keyword">return</span>; <span class="hljs-comment">// Only log keys for a particular IP</span> 8911cb0ef41Sopenharmony_ci logFile.<span class="hljs-title function_">write</span>(line); 8921cb0ef41Sopenharmony_ci});</code> <button class="copy-button">copy</button></pre> 8931cb0ef41Sopenharmony_ci<h4>Event: <code>'newSession'</code><span><a class="mark" href="#event-newsession" id="event-newsession">#</a></span><a aria-hidden="true" class="legacy" id="tls_event_newsession"></a></h4> 8941cb0ef41Sopenharmony_ci<div class="api_metadata"> 8951cb0ef41Sopenharmony_ci<details class="changelog"><summary>History</summary> 8961cb0ef41Sopenharmony_ci<table> 8971cb0ef41Sopenharmony_ci<tbody><tr><th>Version</th><th>Changes</th></tr> 8981cb0ef41Sopenharmony_ci<tr><td>v0.11.12</td> 8991cb0ef41Sopenharmony_ci<td><p>The <code>callback</code> argument is now supported.</p></td></tr> 9001cb0ef41Sopenharmony_ci<tr><td>v0.9.2</td> 9011cb0ef41Sopenharmony_ci<td><p><span>Added in: v0.9.2</span></p></td></tr> 9021cb0ef41Sopenharmony_ci</tbody></table> 9031cb0ef41Sopenharmony_ci</details> 9041cb0ef41Sopenharmony_ci</div> 9051cb0ef41Sopenharmony_ci<p>The <code>'newSession'</code> event is emitted upon creation of a new TLS session. This may 9061cb0ef41Sopenharmony_cibe used to store sessions in external storage. The data should be provided to 9071cb0ef41Sopenharmony_cithe <a href="#event-resumesession"><code>'resumeSession'</code></a> callback.</p> 9081cb0ef41Sopenharmony_ci<p>The listener callback is passed three arguments when called:</p> 9091cb0ef41Sopenharmony_ci<ul> 9101cb0ef41Sopenharmony_ci<li><code>sessionId</code> <a href="buffer.html#class-buffer" class="type"><Buffer></a> The TLS session identifier</li> 9111cb0ef41Sopenharmony_ci<li><code>sessionData</code> <a href="buffer.html#class-buffer" class="type"><Buffer></a> The TLS session data</li> 9121cb0ef41Sopenharmony_ci<li><code>callback</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function" class="type"><Function></a> A callback function taking no arguments that must be 9131cb0ef41Sopenharmony_ciinvoked in order for data to be sent or received over the secure connection.</li> 9141cb0ef41Sopenharmony_ci</ul> 9151cb0ef41Sopenharmony_ci<p>Listening for this event will have an effect only on connections established 9161cb0ef41Sopenharmony_ciafter the addition of the event listener.</p> 9171cb0ef41Sopenharmony_ci<h4>Event: <code>'OCSPRequest'</code><span><a class="mark" href="#event-ocsprequest" id="event-ocsprequest">#</a></span><a aria-hidden="true" class="legacy" id="tls_event_ocsprequest"></a></h4> 9181cb0ef41Sopenharmony_ci<div class="api_metadata"> 9191cb0ef41Sopenharmony_ci<span>Added in: v0.11.13</span> 9201cb0ef41Sopenharmony_ci</div> 9211cb0ef41Sopenharmony_ci<p>The <code>'OCSPRequest'</code> event is emitted when the client sends a certificate status 9221cb0ef41Sopenharmony_cirequest. The listener callback is passed three arguments when called:</p> 9231cb0ef41Sopenharmony_ci<ul> 9241cb0ef41Sopenharmony_ci<li><code>certificate</code> <a href="buffer.html#class-buffer" class="type"><Buffer></a> The server certificate</li> 9251cb0ef41Sopenharmony_ci<li><code>issuer</code> <a href="buffer.html#class-buffer" class="type"><Buffer></a> The issuer's certificate</li> 9261cb0ef41Sopenharmony_ci<li><code>callback</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function" class="type"><Function></a> A callback function that must be invoked to provide 9271cb0ef41Sopenharmony_cithe results of the OCSP request.</li> 9281cb0ef41Sopenharmony_ci</ul> 9291cb0ef41Sopenharmony_ci<p>The server's current certificate can be parsed to obtain the OCSP URL 9301cb0ef41Sopenharmony_ciand certificate ID; after obtaining an OCSP response, <code>callback(null, resp)</code> is 9311cb0ef41Sopenharmony_cithen invoked, where <code>resp</code> is a <code>Buffer</code> instance containing the OCSP response. 9321cb0ef41Sopenharmony_ciBoth <code>certificate</code> and <code>issuer</code> are <code>Buffer</code> DER-representations of the 9331cb0ef41Sopenharmony_ciprimary and issuer's certificates. These can be used to obtain the OCSP 9341cb0ef41Sopenharmony_cicertificate ID and OCSP endpoint URL.</p> 9351cb0ef41Sopenharmony_ci<p>Alternatively, <code>callback(null, null)</code> may be called, indicating that there was 9361cb0ef41Sopenharmony_cino OCSP response.</p> 9371cb0ef41Sopenharmony_ci<p>Calling <code>callback(err)</code> will result in a <code>socket.destroy(err)</code> call.</p> 9381cb0ef41Sopenharmony_ci<p>The typical flow of an OCSP request is as follows:</p> 9391cb0ef41Sopenharmony_ci<ol> 9401cb0ef41Sopenharmony_ci<li>Client connects to the server and sends an <code>'OCSPRequest'</code> (via the status 9411cb0ef41Sopenharmony_ciinfo extension in ClientHello).</li> 9421cb0ef41Sopenharmony_ci<li>Server receives the request and emits the <code>'OCSPRequest'</code> event, calling the 9431cb0ef41Sopenharmony_cilistener if registered.</li> 9441cb0ef41Sopenharmony_ci<li>Server extracts the OCSP URL from either the <code>certificate</code> or <code>issuer</code> and 9451cb0ef41Sopenharmony_ciperforms an <a href="https://en.wikipedia.org/wiki/OCSP_stapling">OCSP request</a> to the CA.</li> 9461cb0ef41Sopenharmony_ci<li>Server receives <code>'OCSPResponse'</code> from the CA and sends it back to the client 9471cb0ef41Sopenharmony_civia the <code>callback</code> argument</li> 9481cb0ef41Sopenharmony_ci<li>Client validates the response and either destroys the socket or performs a 9491cb0ef41Sopenharmony_cihandshake.</li> 9501cb0ef41Sopenharmony_ci</ol> 9511cb0ef41Sopenharmony_ci<p>The <code>issuer</code> can be <code>null</code> if the certificate is either self-signed or the 9521cb0ef41Sopenharmony_ciissuer is not in the root certificates list. (An issuer may be provided 9531cb0ef41Sopenharmony_civia the <code>ca</code> option when establishing the TLS connection.)</p> 9541cb0ef41Sopenharmony_ci<p>Listening for this event will have an effect only on connections established 9551cb0ef41Sopenharmony_ciafter the addition of the event listener.</p> 9561cb0ef41Sopenharmony_ci<p>An npm module like <a href="https://www.npmjs.com/package/asn1.js">asn1.js</a> may be used to parse the certificates.</p> 9571cb0ef41Sopenharmony_ci<h4>Event: <code>'resumeSession'</code><span><a class="mark" href="#event-resumesession" id="event-resumesession">#</a></span><a aria-hidden="true" class="legacy" id="tls_event_resumesession"></a></h4> 9581cb0ef41Sopenharmony_ci<div class="api_metadata"> 9591cb0ef41Sopenharmony_ci<span>Added in: v0.9.2</span> 9601cb0ef41Sopenharmony_ci</div> 9611cb0ef41Sopenharmony_ci<p>The <code>'resumeSession'</code> event is emitted when the client requests to resume a 9621cb0ef41Sopenharmony_ciprevious TLS session. The listener callback is passed two arguments when 9631cb0ef41Sopenharmony_cicalled:</p> 9641cb0ef41Sopenharmony_ci<ul> 9651cb0ef41Sopenharmony_ci<li><code>sessionId</code> <a href="buffer.html#class-buffer" class="type"><Buffer></a> The TLS session identifier</li> 9661cb0ef41Sopenharmony_ci<li><code>callback</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function" class="type"><Function></a> A callback function to be called when the prior session 9671cb0ef41Sopenharmony_cihas been recovered: <code>callback([err[, sessionData]])</code> 9681cb0ef41Sopenharmony_ci<ul> 9691cb0ef41Sopenharmony_ci<li><code>err</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error" class="type"><Error></a></li> 9701cb0ef41Sopenharmony_ci<li><code>sessionData</code> <a href="buffer.html#class-buffer" class="type"><Buffer></a></li> 9711cb0ef41Sopenharmony_ci</ul> 9721cb0ef41Sopenharmony_ci</li> 9731cb0ef41Sopenharmony_ci</ul> 9741cb0ef41Sopenharmony_ci<p>The event listener should perform a lookup in external storage for the 9751cb0ef41Sopenharmony_ci<code>sessionData</code> saved by the <a href="#event-newsession"><code>'newSession'</code></a> event handler using the given 9761cb0ef41Sopenharmony_ci<code>sessionId</code>. If found, call <code>callback(null, sessionData)</code> to resume the session. 9771cb0ef41Sopenharmony_ciIf not found, the session cannot be resumed. <code>callback()</code> must be called 9781cb0ef41Sopenharmony_ciwithout <code>sessionData</code> so that the handshake can continue and a new session can 9791cb0ef41Sopenharmony_cibe created. It is possible to call <code>callback(err)</code> to terminate the incoming 9801cb0ef41Sopenharmony_ciconnection and destroy the socket.</p> 9811cb0ef41Sopenharmony_ci<p>Listening for this event will have an effect only on connections established 9821cb0ef41Sopenharmony_ciafter the addition of the event listener.</p> 9831cb0ef41Sopenharmony_ci<p>The following illustrates resuming a TLS session:</p> 9841cb0ef41Sopenharmony_ci<pre><code class="language-js"><span class="hljs-keyword">const</span> tlsSessionStore = {}; 9851cb0ef41Sopenharmony_ciserver.<span class="hljs-title function_">on</span>(<span class="hljs-string">'newSession'</span>, <span class="hljs-function">(<span class="hljs-params">id, data, cb</span>) =></span> { 9861cb0ef41Sopenharmony_ci tlsSessionStore[id.<span class="hljs-title function_">toString</span>(<span class="hljs-string">'hex'</span>)] = data; 9871cb0ef41Sopenharmony_ci <span class="hljs-title function_">cb</span>(); 9881cb0ef41Sopenharmony_ci}); 9891cb0ef41Sopenharmony_ciserver.<span class="hljs-title function_">on</span>(<span class="hljs-string">'resumeSession'</span>, <span class="hljs-function">(<span class="hljs-params">id, cb</span>) =></span> { 9901cb0ef41Sopenharmony_ci <span class="hljs-title function_">cb</span>(<span class="hljs-literal">null</span>, tlsSessionStore[id.<span class="hljs-title function_">toString</span>(<span class="hljs-string">'hex'</span>)] || <span class="hljs-literal">null</span>); 9911cb0ef41Sopenharmony_ci});</code> <button class="copy-button">copy</button></pre> 9921cb0ef41Sopenharmony_ci<h4>Event: <code>'secureConnection'</code><span><a class="mark" href="#event-secureconnection" id="event-secureconnection">#</a></span><a aria-hidden="true" class="legacy" id="tls_event_secureconnection"></a></h4> 9931cb0ef41Sopenharmony_ci<div class="api_metadata"> 9941cb0ef41Sopenharmony_ci<span>Added in: v0.3.2</span> 9951cb0ef41Sopenharmony_ci</div> 9961cb0ef41Sopenharmony_ci<p>The <code>'secureConnection'</code> event is emitted after the handshaking process for a 9971cb0ef41Sopenharmony_cinew connection has successfully completed. The listener callback is passed a 9981cb0ef41Sopenharmony_cisingle argument when called:</p> 9991cb0ef41Sopenharmony_ci<ul> 10001cb0ef41Sopenharmony_ci<li><code>tlsSocket</code> <a href="tls.html#class-tlstlssocket" class="type"><tls.TLSSocket></a> The established TLS socket.</li> 10011cb0ef41Sopenharmony_ci</ul> 10021cb0ef41Sopenharmony_ci<p>The <code>tlsSocket.authorized</code> property is a <code>boolean</code> indicating whether the 10031cb0ef41Sopenharmony_ciclient has been verified by one of the supplied Certificate Authorities for the 10041cb0ef41Sopenharmony_ciserver. If <code>tlsSocket.authorized</code> is <code>false</code>, then <code>socket.authorizationError</code> 10051cb0ef41Sopenharmony_ciis set to describe how authorization failed. Depending on the settings 10061cb0ef41Sopenharmony_ciof the TLS server, unauthorized connections may still be accepted.</p> 10071cb0ef41Sopenharmony_ci<p>The <code>tlsSocket.alpnProtocol</code> property is a string that contains the selected 10081cb0ef41Sopenharmony_ciALPN protocol. When ALPN has no selected protocol, <code>tlsSocket.alpnProtocol</code> 10091cb0ef41Sopenharmony_ciequals <code>false</code>.</p> 10101cb0ef41Sopenharmony_ci<p>The <code>tlsSocket.servername</code> property is a string containing the server name 10111cb0ef41Sopenharmony_cirequested via SNI.</p> 10121cb0ef41Sopenharmony_ci<h4>Event: <code>'tlsClientError'</code><span><a class="mark" href="#event-tlsclienterror" id="event-tlsclienterror">#</a></span><a aria-hidden="true" class="legacy" id="tls_event_tlsclienterror"></a></h4> 10131cb0ef41Sopenharmony_ci<div class="api_metadata"> 10141cb0ef41Sopenharmony_ci<span>Added in: v6.0.0</span> 10151cb0ef41Sopenharmony_ci</div> 10161cb0ef41Sopenharmony_ci<p>The <code>'tlsClientError'</code> event is emitted when an error occurs before a secure 10171cb0ef41Sopenharmony_ciconnection is established. The listener callback is passed two arguments when 10181cb0ef41Sopenharmony_cicalled:</p> 10191cb0ef41Sopenharmony_ci<ul> 10201cb0ef41Sopenharmony_ci<li><code>exception</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error" class="type"><Error></a> The <code>Error</code> object describing the error</li> 10211cb0ef41Sopenharmony_ci<li><code>tlsSocket</code> <a href="tls.html#class-tlstlssocket" class="type"><tls.TLSSocket></a> The <code>tls.TLSSocket</code> instance from which the 10221cb0ef41Sopenharmony_cierror originated.</li> 10231cb0ef41Sopenharmony_ci</ul> 10241cb0ef41Sopenharmony_ci<h4><code>server.addContext(hostname, context)</code><span><a class="mark" href="#serveraddcontexthostname-context" id="serveraddcontexthostname-context">#</a></span><a aria-hidden="true" class="legacy" id="tls_server_addcontext_hostname_context"></a></h4> 10251cb0ef41Sopenharmony_ci<div class="api_metadata"> 10261cb0ef41Sopenharmony_ci<span>Added in: v0.5.3</span> 10271cb0ef41Sopenharmony_ci</div> 10281cb0ef41Sopenharmony_ci<ul> 10291cb0ef41Sopenharmony_ci<li><code>hostname</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> A SNI host name or wildcard (e.g. <code>'*'</code>)</li> 10301cb0ef41Sopenharmony_ci<li><code>context</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object" class="type"><Object></a> | <a href="tls.html#tlscreatesecurecontextoptions" class="type"><tls.SecureContext></a> An object containing any of the possible 10311cb0ef41Sopenharmony_ciproperties from the <a href="#tlscreatesecurecontextoptions"><code>tls.createSecureContext()</code></a> <code>options</code> arguments 10321cb0ef41Sopenharmony_ci(e.g. <code>key</code>, <code>cert</code>, <code>ca</code>, etc), or a TLS context object created with 10331cb0ef41Sopenharmony_ci<a href="#tlscreatesecurecontextoptions"><code>tls.createSecureContext()</code></a> itself.</li> 10341cb0ef41Sopenharmony_ci</ul> 10351cb0ef41Sopenharmony_ci<p>The <code>server.addContext()</code> method adds a secure context that will be used if 10361cb0ef41Sopenharmony_cithe client request's SNI name matches the supplied <code>hostname</code> (or wildcard).</p> 10371cb0ef41Sopenharmony_ci<p>When there are multiple matching contexts, the most recently added one is 10381cb0ef41Sopenharmony_ciused.</p> 10391cb0ef41Sopenharmony_ci<h4><code>server.address()</code><span><a class="mark" href="#serveraddress" id="serveraddress">#</a></span><a aria-hidden="true" class="legacy" id="tls_server_address"></a></h4> 10401cb0ef41Sopenharmony_ci<div class="api_metadata"> 10411cb0ef41Sopenharmony_ci<span>Added in: v0.6.0</span> 10421cb0ef41Sopenharmony_ci</div> 10431cb0ef41Sopenharmony_ci<ul> 10441cb0ef41Sopenharmony_ci<li>Returns: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object" class="type"><Object></a></li> 10451cb0ef41Sopenharmony_ci</ul> 10461cb0ef41Sopenharmony_ci<p>Returns the bound address, the address family name, and port of the 10471cb0ef41Sopenharmony_ciserver as reported by the operating system. See <a href="net.html#serveraddress"><code>net.Server.address()</code></a> for 10481cb0ef41Sopenharmony_cimore information.</p> 10491cb0ef41Sopenharmony_ci<h4><code>server.close([callback])</code><span><a class="mark" href="#serverclosecallback" id="serverclosecallback">#</a></span><a aria-hidden="true" class="legacy" id="tls_server_close_callback"></a></h4> 10501cb0ef41Sopenharmony_ci<div class="api_metadata"> 10511cb0ef41Sopenharmony_ci<span>Added in: v0.3.2</span> 10521cb0ef41Sopenharmony_ci</div> 10531cb0ef41Sopenharmony_ci<ul> 10541cb0ef41Sopenharmony_ci<li><code>callback</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function" class="type"><Function></a> A listener callback that will be registered to listen 10551cb0ef41Sopenharmony_cifor the server instance's <code>'close'</code> event.</li> 10561cb0ef41Sopenharmony_ci<li>Returns: <a href="tls.html#class-tlsserver" class="type"><tls.Server></a></li> 10571cb0ef41Sopenharmony_ci</ul> 10581cb0ef41Sopenharmony_ci<p>The <code>server.close()</code> method stops the server from accepting new connections.</p> 10591cb0ef41Sopenharmony_ci<p>This function operates asynchronously. The <code>'close'</code> event will be emitted 10601cb0ef41Sopenharmony_ciwhen the server has no more open connections.</p> 10611cb0ef41Sopenharmony_ci<h4><code>server.getTicketKeys()</code><span><a class="mark" href="#servergetticketkeys" id="servergetticketkeys">#</a></span><a aria-hidden="true" class="legacy" id="tls_server_getticketkeys"></a></h4> 10621cb0ef41Sopenharmony_ci<div class="api_metadata"> 10631cb0ef41Sopenharmony_ci<span>Added in: v3.0.0</span> 10641cb0ef41Sopenharmony_ci</div> 10651cb0ef41Sopenharmony_ci<ul> 10661cb0ef41Sopenharmony_ci<li>Returns: <a href="buffer.html#class-buffer" class="type"><Buffer></a> A 48-byte buffer containing the session ticket keys.</li> 10671cb0ef41Sopenharmony_ci</ul> 10681cb0ef41Sopenharmony_ci<p>Returns the session ticket keys.</p> 10691cb0ef41Sopenharmony_ci<p>See <a href="#session-resumption">Session Resumption</a> for more information.</p> 10701cb0ef41Sopenharmony_ci<h4><code>server.listen()</code><span><a class="mark" href="#serverlisten" id="serverlisten">#</a></span><a aria-hidden="true" class="legacy" id="tls_server_listen"></a></h4> 10711cb0ef41Sopenharmony_ci<p>Starts the server listening for encrypted connections. 10721cb0ef41Sopenharmony_ciThis method is identical to <a href="net.html#serverlisten"><code>server.listen()</code></a> from <a href="net.html#class-netserver"><code>net.Server</code></a>.</p> 10731cb0ef41Sopenharmony_ci<h4><code>server.setSecureContext(options)</code><span><a class="mark" href="#serversetsecurecontextoptions" id="serversetsecurecontextoptions">#</a></span><a aria-hidden="true" class="legacy" id="tls_server_setsecurecontext_options"></a></h4> 10741cb0ef41Sopenharmony_ci<div class="api_metadata"> 10751cb0ef41Sopenharmony_ci<span>Added in: v11.0.0</span> 10761cb0ef41Sopenharmony_ci</div> 10771cb0ef41Sopenharmony_ci<ul> 10781cb0ef41Sopenharmony_ci<li><code>options</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object" class="type"><Object></a> An object containing any of the possible properties from 10791cb0ef41Sopenharmony_cithe <a href="#tlscreatesecurecontextoptions"><code>tls.createSecureContext()</code></a> <code>options</code> arguments (e.g. <code>key</code>, <code>cert</code>, 10801cb0ef41Sopenharmony_ci<code>ca</code>, etc).</li> 10811cb0ef41Sopenharmony_ci</ul> 10821cb0ef41Sopenharmony_ci<p>The <code>server.setSecureContext()</code> method replaces the secure context of an 10831cb0ef41Sopenharmony_ciexisting server. Existing connections to the server are not interrupted.</p> 10841cb0ef41Sopenharmony_ci<h4><code>server.setTicketKeys(keys)</code><span><a class="mark" href="#serversetticketkeyskeys" id="serversetticketkeyskeys">#</a></span><a aria-hidden="true" class="legacy" id="tls_server_setticketkeys_keys"></a></h4> 10851cb0ef41Sopenharmony_ci<div class="api_metadata"> 10861cb0ef41Sopenharmony_ci<span>Added in: v3.0.0</span> 10871cb0ef41Sopenharmony_ci</div> 10881cb0ef41Sopenharmony_ci<ul> 10891cb0ef41Sopenharmony_ci<li><code>keys</code> <a href="buffer.html#class-buffer" class="type"><Buffer></a> | <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/TypedArray" class="type"><TypedArray></a> | <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/DataView" class="type"><DataView></a> A 48-byte buffer containing the session 10901cb0ef41Sopenharmony_citicket keys.</li> 10911cb0ef41Sopenharmony_ci</ul> 10921cb0ef41Sopenharmony_ci<p>Sets the session ticket keys.</p> 10931cb0ef41Sopenharmony_ci<p>Changes to the ticket keys are effective only for future server connections. 10941cb0ef41Sopenharmony_ciExisting or currently pending server connections will use the previous keys.</p> 10951cb0ef41Sopenharmony_ci<p>See <a href="#session-resumption">Session Resumption</a> for more information.</p> 10961cb0ef41Sopenharmony_ci</section><section><h3>Class: <code>tls.TLSSocket</code><span><a class="mark" href="#class-tlstlssocket" id="class-tlstlssocket">#</a></span><a aria-hidden="true" class="legacy" id="tls_class_tls_tlssocket"></a></h3> 10971cb0ef41Sopenharmony_ci<div class="api_metadata"> 10981cb0ef41Sopenharmony_ci<span>Added in: v0.11.4</span> 10991cb0ef41Sopenharmony_ci</div> 11001cb0ef41Sopenharmony_ci<ul> 11011cb0ef41Sopenharmony_ci<li>Extends: <a href="net.html#class-netsocket" class="type"><net.Socket></a></li> 11021cb0ef41Sopenharmony_ci</ul> 11031cb0ef41Sopenharmony_ci<p>Performs transparent encryption of written data and all required TLS 11041cb0ef41Sopenharmony_cinegotiation.</p> 11051cb0ef41Sopenharmony_ci<p>Instances of <code>tls.TLSSocket</code> implement the duplex <a href="stream.html#stream">Stream</a> interface.</p> 11061cb0ef41Sopenharmony_ci<p>Methods that return TLS connection metadata (e.g. 11071cb0ef41Sopenharmony_ci<a href="#tlssocketgetpeercertificatedetailed"><code>tls.TLSSocket.getPeerCertificate()</code></a>) will only return data while the 11081cb0ef41Sopenharmony_ciconnection is open.</p> 11091cb0ef41Sopenharmony_ci<h4><code>new tls.TLSSocket(socket[, options])</code><span><a class="mark" href="#new-tlstlssocketsocket-options" id="new-tlstlssocketsocket-options">#</a></span><a aria-hidden="true" class="legacy" id="tls_new_tls_tlssocket_socket_options"></a></h4> 11101cb0ef41Sopenharmony_ci<div class="api_metadata"> 11111cb0ef41Sopenharmony_ci<details class="changelog"><summary>History</summary> 11121cb0ef41Sopenharmony_ci<table> 11131cb0ef41Sopenharmony_ci<tbody><tr><th>Version</th><th>Changes</th></tr> 11141cb0ef41Sopenharmony_ci<tr><td>v12.2.0</td> 11151cb0ef41Sopenharmony_ci<td><p>The <code>enableTrace</code> option is now supported.</p></td></tr> 11161cb0ef41Sopenharmony_ci<tr><td>v5.0.0</td> 11171cb0ef41Sopenharmony_ci<td><p>ALPN options are supported now.</p></td></tr> 11181cb0ef41Sopenharmony_ci<tr><td>v0.11.4</td> 11191cb0ef41Sopenharmony_ci<td><p><span>Added in: v0.11.4</span></p></td></tr> 11201cb0ef41Sopenharmony_ci</tbody></table> 11211cb0ef41Sopenharmony_ci</details> 11221cb0ef41Sopenharmony_ci</div> 11231cb0ef41Sopenharmony_ci<ul> 11241cb0ef41Sopenharmony_ci<li><code>socket</code> <a href="net.html#class-netsocket" class="type"><net.Socket></a> | <a href="stream.html#class-streamduplex" class="type"><stream.Duplex></a> 11251cb0ef41Sopenharmony_ciOn the server side, any <code>Duplex</code> stream. On the client side, any 11261cb0ef41Sopenharmony_ciinstance of <a href="net.html#class-netsocket"><code>net.Socket</code></a> (for generic <code>Duplex</code> stream support 11271cb0ef41Sopenharmony_cion the client side, <a href="#tlsconnectoptions-callback"><code>tls.connect()</code></a> must be used).</li> 11281cb0ef41Sopenharmony_ci<li><code>options</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object" class="type"><Object></a> 11291cb0ef41Sopenharmony_ci<ul> 11301cb0ef41Sopenharmony_ci<li><code>enableTrace</code>: See <a href="#tlscreateserveroptions-secureconnectionlistener"><code>tls.createServer()</code></a></li> 11311cb0ef41Sopenharmony_ci<li><code>isServer</code>: The SSL/TLS protocol is asymmetrical, TLSSockets must know if 11321cb0ef41Sopenharmony_cithey are to behave as a server or a client. If <code>true</code> the TLS socket will be 11331cb0ef41Sopenharmony_ciinstantiated as a server. <strong>Default:</strong> <code>false</code>.</li> 11341cb0ef41Sopenharmony_ci<li><code>server</code> <a href="net.html#class-netserver" class="type"><net.Server></a> A <a href="net.html#class-netserver"><code>net.Server</code></a> instance.</li> 11351cb0ef41Sopenharmony_ci<li><code>requestCert</code>: Whether to authenticate the remote peer by requesting a 11361cb0ef41Sopenharmony_cicertificate. Clients always request a server certificate. Servers 11371cb0ef41Sopenharmony_ci(<code>isServer</code> is true) may set <code>requestCert</code> to true to request a client 11381cb0ef41Sopenharmony_cicertificate.</li> 11391cb0ef41Sopenharmony_ci<li><code>rejectUnauthorized</code>: See <a href="#tlscreateserveroptions-secureconnectionlistener"><code>tls.createServer()</code></a></li> 11401cb0ef41Sopenharmony_ci<li><code>ALPNProtocols</code>: See <a href="#tlscreateserveroptions-secureconnectionlistener"><code>tls.createServer()</code></a></li> 11411cb0ef41Sopenharmony_ci<li><code>SNICallback</code>: See <a href="#tlscreateserveroptions-secureconnectionlistener"><code>tls.createServer()</code></a></li> 11421cb0ef41Sopenharmony_ci<li><code>session</code> <a href="buffer.html#class-buffer" class="type"><Buffer></a> A <code>Buffer</code> instance containing a TLS session.</li> 11431cb0ef41Sopenharmony_ci<li><code>requestOCSP</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type" class="type"><boolean></a> If <code>true</code>, specifies that the OCSP status request 11441cb0ef41Sopenharmony_ciextension will be added to the client hello and an <code>'OCSPResponse'</code> event 11451cb0ef41Sopenharmony_ciwill be emitted on the socket before establishing a secure communication</li> 11461cb0ef41Sopenharmony_ci<li><code>secureContext</code>: TLS context object created with 11471cb0ef41Sopenharmony_ci<a href="#tlscreatesecurecontextoptions"><code>tls.createSecureContext()</code></a>. If a <code>secureContext</code> is <em>not</em> provided, one 11481cb0ef41Sopenharmony_ciwill be created by passing the entire <code>options</code> object to 11491cb0ef41Sopenharmony_ci<code>tls.createSecureContext()</code>.</li> 11501cb0ef41Sopenharmony_ci<li>...: <a href="#tlscreatesecurecontextoptions"><code>tls.createSecureContext()</code></a> options that are used if the 11511cb0ef41Sopenharmony_ci<code>secureContext</code> option is missing. Otherwise, they are ignored.</li> 11521cb0ef41Sopenharmony_ci</ul> 11531cb0ef41Sopenharmony_ci</li> 11541cb0ef41Sopenharmony_ci</ul> 11551cb0ef41Sopenharmony_ci<p>Construct a new <code>tls.TLSSocket</code> object from an existing TCP socket.</p> 11561cb0ef41Sopenharmony_ci<h4>Event: <code>'keylog'</code><span><a class="mark" href="#event-keylog_1" id="event-keylog_1">#</a></span><a aria-hidden="true" class="legacy" id="tls_event_keylog_1"></a></h4> 11571cb0ef41Sopenharmony_ci<div class="api_metadata"> 11581cb0ef41Sopenharmony_ci<span>Added in: v12.3.0, v10.20.0</span> 11591cb0ef41Sopenharmony_ci</div> 11601cb0ef41Sopenharmony_ci<ul> 11611cb0ef41Sopenharmony_ci<li><code>line</code> <a href="buffer.html#class-buffer" class="type"><Buffer></a> Line of ASCII text, in NSS <code>SSLKEYLOGFILE</code> format.</li> 11621cb0ef41Sopenharmony_ci</ul> 11631cb0ef41Sopenharmony_ci<p>The <code>keylog</code> event is emitted on a <code>tls.TLSSocket</code> when key material 11641cb0ef41Sopenharmony_ciis generated or received by the socket. This keying material can be stored 11651cb0ef41Sopenharmony_cifor debugging, as it allows captured TLS traffic to be decrypted. It may 11661cb0ef41Sopenharmony_cibe emitted multiple times, before or after the handshake completes.</p> 11671cb0ef41Sopenharmony_ci<p>A typical use case is to append received lines to a common text file, which 11681cb0ef41Sopenharmony_ciis later used by software (such as Wireshark) to decrypt the traffic:</p> 11691cb0ef41Sopenharmony_ci<pre><code class="language-js"><span class="hljs-keyword">const</span> logFile = fs.<span class="hljs-title function_">createWriteStream</span>(<span class="hljs-string">'/tmp/ssl-keys.log'</span>, { <span class="hljs-attr">flags</span>: <span class="hljs-string">'a'</span> }); 11701cb0ef41Sopenharmony_ci<span class="hljs-comment">// ...</span> 11711cb0ef41Sopenharmony_citlsSocket.<span class="hljs-title function_">on</span>(<span class="hljs-string">'keylog'</span>, <span class="hljs-function">(<span class="hljs-params">line</span>) =></span> logFile.<span class="hljs-title function_">write</span>(line));</code> <button class="copy-button">copy</button></pre> 11721cb0ef41Sopenharmony_ci<h4>Event: <code>'OCSPResponse'</code><span><a class="mark" href="#event-ocspresponse" id="event-ocspresponse">#</a></span><a aria-hidden="true" class="legacy" id="tls_event_ocspresponse"></a></h4> 11731cb0ef41Sopenharmony_ci<div class="api_metadata"> 11741cb0ef41Sopenharmony_ci<span>Added in: v0.11.13</span> 11751cb0ef41Sopenharmony_ci</div> 11761cb0ef41Sopenharmony_ci<p>The <code>'OCSPResponse'</code> event is emitted if the <code>requestOCSP</code> option was set 11771cb0ef41Sopenharmony_ciwhen the <code>tls.TLSSocket</code> was created and an OCSP response has been received. 11781cb0ef41Sopenharmony_ciThe listener callback is passed a single argument when called:</p> 11791cb0ef41Sopenharmony_ci<ul> 11801cb0ef41Sopenharmony_ci<li><code>response</code> <a href="buffer.html#class-buffer" class="type"><Buffer></a> The server's OCSP response</li> 11811cb0ef41Sopenharmony_ci</ul> 11821cb0ef41Sopenharmony_ci<p>Typically, the <code>response</code> is a digitally signed object from the server's CA that 11831cb0ef41Sopenharmony_cicontains information about server's certificate revocation status.</p> 11841cb0ef41Sopenharmony_ci<h4>Event: <code>'secureConnect'</code><span><a class="mark" href="#event-secureconnect" id="event-secureconnect">#</a></span><a aria-hidden="true" class="legacy" id="tls_event_secureconnect"></a></h4> 11851cb0ef41Sopenharmony_ci<div class="api_metadata"> 11861cb0ef41Sopenharmony_ci<span>Added in: v0.11.4</span> 11871cb0ef41Sopenharmony_ci</div> 11881cb0ef41Sopenharmony_ci<p>The <code>'secureConnect'</code> event is emitted after the handshaking process for a new 11891cb0ef41Sopenharmony_ciconnection has successfully completed. The listener callback will be called 11901cb0ef41Sopenharmony_ciregardless of whether or not the server's certificate has been authorized. It 11911cb0ef41Sopenharmony_ciis the client's responsibility to check the <code>tlsSocket.authorized</code> property to 11921cb0ef41Sopenharmony_cidetermine if the server certificate was signed by one of the specified CAs. If 11931cb0ef41Sopenharmony_ci<code>tlsSocket.authorized === false</code>, then the error can be found by examining the 11941cb0ef41Sopenharmony_ci<code>tlsSocket.authorizationError</code> property. If ALPN was used, the 11951cb0ef41Sopenharmony_ci<code>tlsSocket.alpnProtocol</code> property can be checked to determine the negotiated 11961cb0ef41Sopenharmony_ciprotocol.</p> 11971cb0ef41Sopenharmony_ci<p>The <code>'secureConnect'</code> event is not emitted when a <a href="tls.html#class-tlstlssocket" class="type"><tls.TLSSocket></a> is created 11981cb0ef41Sopenharmony_ciusing the <code>new tls.TLSSocket()</code> constructor.</p> 11991cb0ef41Sopenharmony_ci<h4>Event: <code>'session'</code><span><a class="mark" href="#event-session" id="event-session">#</a></span><a aria-hidden="true" class="legacy" id="tls_event_session"></a></h4> 12001cb0ef41Sopenharmony_ci<div class="api_metadata"> 12011cb0ef41Sopenharmony_ci<span>Added in: v11.10.0</span> 12021cb0ef41Sopenharmony_ci</div> 12031cb0ef41Sopenharmony_ci<ul> 12041cb0ef41Sopenharmony_ci<li><code>session</code> <a href="buffer.html#class-buffer" class="type"><Buffer></a></li> 12051cb0ef41Sopenharmony_ci</ul> 12061cb0ef41Sopenharmony_ci<p>The <code>'session'</code> event is emitted on a client <code>tls.TLSSocket</code> when a new session 12071cb0ef41Sopenharmony_cior TLS ticket is available. This may or may not be before the handshake is 12081cb0ef41Sopenharmony_cicomplete, depending on the TLS protocol version that was negotiated. The event 12091cb0ef41Sopenharmony_ciis not emitted on the server, or if a new session was not created, for example, 12101cb0ef41Sopenharmony_ciwhen the connection was resumed. For some TLS protocol versions the event may be 12111cb0ef41Sopenharmony_ciemitted multiple times, in which case all the sessions can be used for 12121cb0ef41Sopenharmony_ciresumption.</p> 12131cb0ef41Sopenharmony_ci<p>On the client, the <code>session</code> can be provided to the <code>session</code> option of 12141cb0ef41Sopenharmony_ci<a href="#tlsconnectoptions-callback"><code>tls.connect()</code></a> to resume the connection.</p> 12151cb0ef41Sopenharmony_ci<p>See <a href="#session-resumption">Session Resumption</a> for more information.</p> 12161cb0ef41Sopenharmony_ci<p>For TLSv1.2 and below, <a href="#tlssocketgetsession"><code>tls.TLSSocket.getSession()</code></a> can be called once 12171cb0ef41Sopenharmony_cithe handshake is complete. For TLSv1.3, only ticket-based resumption is allowed 12181cb0ef41Sopenharmony_ciby the protocol, multiple tickets are sent, and the tickets aren't sent until 12191cb0ef41Sopenharmony_ciafter the handshake completes. So it is necessary to wait for the 12201cb0ef41Sopenharmony_ci<code>'session'</code> event to get a resumable session. Applications 12211cb0ef41Sopenharmony_cishould use the <code>'session'</code> event instead of <code>getSession()</code> to ensure 12221cb0ef41Sopenharmony_cithey will work for all TLS versions. Applications that only expect to 12231cb0ef41Sopenharmony_ciget or use one session should listen for this event only once:</p> 12241cb0ef41Sopenharmony_ci<pre><code class="language-js">tlsSocket.<span class="hljs-title function_">once</span>(<span class="hljs-string">'session'</span>, <span class="hljs-function">(<span class="hljs-params">session</span>) =></span> { 12251cb0ef41Sopenharmony_ci <span class="hljs-comment">// The session can be used immediately or later.</span> 12261cb0ef41Sopenharmony_ci tls.<span class="hljs-title function_">connect</span>({ 12271cb0ef41Sopenharmony_ci <span class="hljs-attr">session</span>: session, 12281cb0ef41Sopenharmony_ci <span class="hljs-comment">// Other connect options...</span> 12291cb0ef41Sopenharmony_ci }); 12301cb0ef41Sopenharmony_ci});</code> <button class="copy-button">copy</button></pre> 12311cb0ef41Sopenharmony_ci<h4><code>tlsSocket.address()</code><span><a class="mark" href="#tlssocketaddress" id="tlssocketaddress">#</a></span><a aria-hidden="true" class="legacy" id="tls_tlssocket_address"></a></h4> 12321cb0ef41Sopenharmony_ci<div class="api_metadata"> 12331cb0ef41Sopenharmony_ci<details class="changelog"><summary>History</summary> 12341cb0ef41Sopenharmony_ci<table> 12351cb0ef41Sopenharmony_ci<tbody><tr><th>Version</th><th>Changes</th></tr> 12361cb0ef41Sopenharmony_ci<tr><td>v18.4.0</td> 12371cb0ef41Sopenharmony_ci<td><p>The <code>family</code> property now returns a string instead of a number.</p></td></tr> 12381cb0ef41Sopenharmony_ci<tr><td>v18.0.0</td> 12391cb0ef41Sopenharmony_ci<td><p>The <code>family</code> property now returns a number instead of a string.</p></td></tr> 12401cb0ef41Sopenharmony_ci<tr><td>v0.11.4</td> 12411cb0ef41Sopenharmony_ci<td><p><span>Added in: v0.11.4</span></p></td></tr> 12421cb0ef41Sopenharmony_ci</tbody></table> 12431cb0ef41Sopenharmony_ci</details> 12441cb0ef41Sopenharmony_ci</div> 12451cb0ef41Sopenharmony_ci<ul> 12461cb0ef41Sopenharmony_ci<li>Returns: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object" class="type"><Object></a></li> 12471cb0ef41Sopenharmony_ci</ul> 12481cb0ef41Sopenharmony_ci<p>Returns the bound <code>address</code>, the address <code>family</code> name, and <code>port</code> of the 12491cb0ef41Sopenharmony_ciunderlying socket as reported by the operating system: 12501cb0ef41Sopenharmony_ci<code>{ port: 12346, family: 'IPv4', address: '127.0.0.1' }</code>.</p> 12511cb0ef41Sopenharmony_ci<h4><code>tlsSocket.authorizationError</code><span><a class="mark" href="#tlssocketauthorizationerror" id="tlssocketauthorizationerror">#</a></span><a aria-hidden="true" class="legacy" id="tls_tlssocket_authorizationerror"></a></h4> 12521cb0ef41Sopenharmony_ci<div class="api_metadata"> 12531cb0ef41Sopenharmony_ci<span>Added in: v0.11.4</span> 12541cb0ef41Sopenharmony_ci</div> 12551cb0ef41Sopenharmony_ci<p>Returns the reason why the peer's certificate was not been verified. This 12561cb0ef41Sopenharmony_ciproperty is set only when <code>tlsSocket.authorized === false</code>.</p> 12571cb0ef41Sopenharmony_ci<h4><code>tlsSocket.authorized</code><span><a class="mark" href="#tlssocketauthorized" id="tlssocketauthorized">#</a></span><a aria-hidden="true" class="legacy" id="tls_tlssocket_authorized"></a></h4> 12581cb0ef41Sopenharmony_ci<div class="api_metadata"> 12591cb0ef41Sopenharmony_ci<span>Added in: v0.11.4</span> 12601cb0ef41Sopenharmony_ci</div> 12611cb0ef41Sopenharmony_ci<ul> 12621cb0ef41Sopenharmony_ci<li><a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type" class="type"><boolean></a></li> 12631cb0ef41Sopenharmony_ci</ul> 12641cb0ef41Sopenharmony_ci<p>This property is <code>true</code> if the peer certificate was signed by one of the CAs 12651cb0ef41Sopenharmony_cispecified when creating the <code>tls.TLSSocket</code> instance, otherwise <code>false</code>.</p> 12661cb0ef41Sopenharmony_ci<h4><code>tlsSocket.disableRenegotiation()</code><span><a class="mark" href="#tlssocketdisablerenegotiation" id="tlssocketdisablerenegotiation">#</a></span><a aria-hidden="true" class="legacy" id="tls_tlssocket_disablerenegotiation"></a></h4> 12671cb0ef41Sopenharmony_ci<div class="api_metadata"> 12681cb0ef41Sopenharmony_ci<span>Added in: v8.4.0</span> 12691cb0ef41Sopenharmony_ci</div> 12701cb0ef41Sopenharmony_ci<p>Disables TLS renegotiation for this <code>TLSSocket</code> instance. Once called, attempts 12711cb0ef41Sopenharmony_cito renegotiate will trigger an <code>'error'</code> event on the <code>TLSSocket</code>.</p> 12721cb0ef41Sopenharmony_ci<h4><code>tlsSocket.enableTrace()</code><span><a class="mark" href="#tlssocketenabletrace" id="tlssocketenabletrace">#</a></span><a aria-hidden="true" class="legacy" id="tls_tlssocket_enabletrace"></a></h4> 12731cb0ef41Sopenharmony_ci<div class="api_metadata"> 12741cb0ef41Sopenharmony_ci<span>Added in: v12.2.0</span> 12751cb0ef41Sopenharmony_ci</div> 12761cb0ef41Sopenharmony_ci<p>When enabled, TLS packet trace information is written to <code>stderr</code>. This can be 12771cb0ef41Sopenharmony_ciused to debug TLS connection problems.</p> 12781cb0ef41Sopenharmony_ci<p>The format of the output is identical to the output of 12791cb0ef41Sopenharmony_ci<code>openssl s_client -trace</code> or <code>openssl s_server -trace</code>. While it is produced by 12801cb0ef41Sopenharmony_ciOpenSSL's <code>SSL_trace()</code> function, the format is undocumented, can change 12811cb0ef41Sopenharmony_ciwithout notice, and should not be relied on.</p> 12821cb0ef41Sopenharmony_ci<h4><code>tlsSocket.encrypted</code><span><a class="mark" href="#tlssocketencrypted" id="tlssocketencrypted">#</a></span><a aria-hidden="true" class="legacy" id="tls_tlssocket_encrypted"></a></h4> 12831cb0ef41Sopenharmony_ci<div class="api_metadata"> 12841cb0ef41Sopenharmony_ci<span>Added in: v0.11.4</span> 12851cb0ef41Sopenharmony_ci</div> 12861cb0ef41Sopenharmony_ci<p>Always returns <code>true</code>. This may be used to distinguish TLS sockets from regular 12871cb0ef41Sopenharmony_ci<code>net.Socket</code> instances.</p> 12881cb0ef41Sopenharmony_ci<h4><code>tlsSocket.exportKeyingMaterial(length, label[, context])</code><span><a class="mark" href="#tlssocketexportkeyingmateriallength-label-context" id="tlssocketexportkeyingmateriallength-label-context">#</a></span><a aria-hidden="true" class="legacy" id="tls_tlssocket_exportkeyingmaterial_length_label_context"></a></h4> 12891cb0ef41Sopenharmony_ci<div class="api_metadata"> 12901cb0ef41Sopenharmony_ci<span>Added in: v13.10.0, v12.17.0</span> 12911cb0ef41Sopenharmony_ci</div> 12921cb0ef41Sopenharmony_ci<ul> 12931cb0ef41Sopenharmony_ci<li> 12941cb0ef41Sopenharmony_ci<p><code>length</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><number></a> number of bytes to retrieve from keying material</p> 12951cb0ef41Sopenharmony_ci</li> 12961cb0ef41Sopenharmony_ci<li> 12971cb0ef41Sopenharmony_ci<p><code>label</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> an application specific label, typically this will be a 12981cb0ef41Sopenharmony_civalue from the 12991cb0ef41Sopenharmony_ci<a href="https://www.iana.org/assignments/tls-parameters/tls-parameters.xhtml#exporter-labels">IANA Exporter Label Registry</a>.</p> 13001cb0ef41Sopenharmony_ci</li> 13011cb0ef41Sopenharmony_ci<li> 13021cb0ef41Sopenharmony_ci<p><code>context</code> <a href="buffer.html#class-buffer" class="type"><Buffer></a> Optionally provide a context.</p> 13031cb0ef41Sopenharmony_ci</li> 13041cb0ef41Sopenharmony_ci<li> 13051cb0ef41Sopenharmony_ci<p>Returns: <a href="buffer.html#class-buffer" class="type"><Buffer></a> requested bytes of the keying material</p> 13061cb0ef41Sopenharmony_ci</li> 13071cb0ef41Sopenharmony_ci</ul> 13081cb0ef41Sopenharmony_ci<p>Keying material is used for validations to prevent different kind of attacks in 13091cb0ef41Sopenharmony_cinetwork protocols, for example in the specifications of IEEE 802.1X.</p> 13101cb0ef41Sopenharmony_ci<p>Example</p> 13111cb0ef41Sopenharmony_ci<pre><code class="language-js"><span class="hljs-keyword">const</span> keyingMaterial = tlsSocket.<span class="hljs-title function_">exportKeyingMaterial</span>( 13121cb0ef41Sopenharmony_ci <span class="hljs-number">128</span>, 13131cb0ef41Sopenharmony_ci <span class="hljs-string">'client finished'</span>); 13141cb0ef41Sopenharmony_ci 13151cb0ef41Sopenharmony_ci<span class="hljs-comment">/* 13161cb0ef41Sopenharmony_ci Example return value of keyingMaterial: 13171cb0ef41Sopenharmony_ci <Buffer 76 26 af 99 c5 56 8e 42 09 91 ef 9f 93 cb ad 6c 7b 65 f8 53 f1 d8 d9 13181cb0ef41Sopenharmony_ci 12 5a 33 b8 b5 25 df 7b 37 9f e0 e2 4f b8 67 83 a3 2f cd 5d 41 42 4c 91 13191cb0ef41Sopenharmony_ci 74 ef 2c ... 78 more bytes> 13201cb0ef41Sopenharmony_ci*/</span></code> <button class="copy-button">copy</button></pre> 13211cb0ef41Sopenharmony_ci<p>See the OpenSSL <a href="https://www.openssl.org/docs/man1.1.1/man3/SSL_export_keying_material.html"><code>SSL_export_keying_material</code></a> documentation for more 13221cb0ef41Sopenharmony_ciinformation.</p> 13231cb0ef41Sopenharmony_ci<h4><code>tlsSocket.getCertificate()</code><span><a class="mark" href="#tlssocketgetcertificate" id="tlssocketgetcertificate">#</a></span><a aria-hidden="true" class="legacy" id="tls_tlssocket_getcertificate"></a></h4> 13241cb0ef41Sopenharmony_ci<div class="api_metadata"> 13251cb0ef41Sopenharmony_ci<span>Added in: v11.2.0</span> 13261cb0ef41Sopenharmony_ci</div> 13271cb0ef41Sopenharmony_ci<ul> 13281cb0ef41Sopenharmony_ci<li>Returns: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object" class="type"><Object></a></li> 13291cb0ef41Sopenharmony_ci</ul> 13301cb0ef41Sopenharmony_ci<p>Returns an object representing the local certificate. The returned object has 13311cb0ef41Sopenharmony_cisome properties corresponding to the fields of the certificate.</p> 13321cb0ef41Sopenharmony_ci<p>See <a href="#tlssocketgetpeercertificatedetailed"><code>tls.TLSSocket.getPeerCertificate()</code></a> for an example of the certificate 13331cb0ef41Sopenharmony_cistructure.</p> 13341cb0ef41Sopenharmony_ci<p>If there is no local certificate, an empty object will be returned. If the 13351cb0ef41Sopenharmony_cisocket has been destroyed, <code>null</code> will be returned.</p> 13361cb0ef41Sopenharmony_ci<h4><code>tlsSocket.getCipher()</code><span><a class="mark" href="#tlssocketgetcipher" id="tlssocketgetcipher">#</a></span><a aria-hidden="true" class="legacy" id="tls_tlssocket_getcipher"></a></h4> 13371cb0ef41Sopenharmony_ci<div class="api_metadata"> 13381cb0ef41Sopenharmony_ci<details class="changelog"><summary>History</summary> 13391cb0ef41Sopenharmony_ci<table> 13401cb0ef41Sopenharmony_ci<tbody><tr><th>Version</th><th>Changes</th></tr> 13411cb0ef41Sopenharmony_ci<tr><td>v13.4.0, v12.16.0</td> 13421cb0ef41Sopenharmony_ci<td><p>Return the IETF cipher name as <code>standardName</code>.</p></td></tr> 13431cb0ef41Sopenharmony_ci<tr><td>v12.0.0</td> 13441cb0ef41Sopenharmony_ci<td><p>Return the minimum cipher version, instead of a fixed string (<code>'TLSv1/SSLv3'</code>).</p></td></tr> 13451cb0ef41Sopenharmony_ci<tr><td>v0.11.4</td> 13461cb0ef41Sopenharmony_ci<td><p><span>Added in: v0.11.4</span></p></td></tr> 13471cb0ef41Sopenharmony_ci</tbody></table> 13481cb0ef41Sopenharmony_ci</details> 13491cb0ef41Sopenharmony_ci</div> 13501cb0ef41Sopenharmony_ci<ul> 13511cb0ef41Sopenharmony_ci<li>Returns: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object" class="type"><Object></a> 13521cb0ef41Sopenharmony_ci<ul> 13531cb0ef41Sopenharmony_ci<li><code>name</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> OpenSSL name for the cipher suite.</li> 13541cb0ef41Sopenharmony_ci<li><code>standardName</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> IETF name for the cipher suite.</li> 13551cb0ef41Sopenharmony_ci<li><code>version</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> The minimum TLS protocol version supported by this cipher 13561cb0ef41Sopenharmony_cisuite. For the actual negotiated protocol, see <a href="#tlssocketgetprotocol"><code>tls.TLSSocket.getProtocol()</code></a>.</li> 13571cb0ef41Sopenharmony_ci</ul> 13581cb0ef41Sopenharmony_ci</li> 13591cb0ef41Sopenharmony_ci</ul> 13601cb0ef41Sopenharmony_ci<p>Returns an object containing information on the negotiated cipher suite.</p> 13611cb0ef41Sopenharmony_ci<p>For example, a TLSv1.2 protocol with AES256-SHA cipher:</p> 13621cb0ef41Sopenharmony_ci<pre><code class="language-json"><span class="hljs-punctuation">{</span> 13631cb0ef41Sopenharmony_ci <span class="hljs-attr">"name"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"AES256-SHA"</span><span class="hljs-punctuation">,</span> 13641cb0ef41Sopenharmony_ci <span class="hljs-attr">"standardName"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"TLS_RSA_WITH_AES_256_CBC_SHA"</span><span class="hljs-punctuation">,</span> 13651cb0ef41Sopenharmony_ci <span class="hljs-attr">"version"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"SSLv3"</span> 13661cb0ef41Sopenharmony_ci<span class="hljs-punctuation">}</span></code> <button class="copy-button">copy</button></pre> 13671cb0ef41Sopenharmony_ci<p>See 13681cb0ef41Sopenharmony_ci<a href="https://www.openssl.org/docs/man1.1.1/man3/SSL_CIPHER_get_name.html">SSL_CIPHER_get_name</a> 13691cb0ef41Sopenharmony_cifor more information.</p> 13701cb0ef41Sopenharmony_ci<h4><code>tlsSocket.getEphemeralKeyInfo()</code><span><a class="mark" href="#tlssocketgetephemeralkeyinfo" id="tlssocketgetephemeralkeyinfo">#</a></span><a aria-hidden="true" class="legacy" id="tls_tlssocket_getephemeralkeyinfo"></a></h4> 13711cb0ef41Sopenharmony_ci<div class="api_metadata"> 13721cb0ef41Sopenharmony_ci<span>Added in: v5.0.0</span> 13731cb0ef41Sopenharmony_ci</div> 13741cb0ef41Sopenharmony_ci<ul> 13751cb0ef41Sopenharmony_ci<li>Returns: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object" class="type"><Object></a></li> 13761cb0ef41Sopenharmony_ci</ul> 13771cb0ef41Sopenharmony_ci<p>Returns an object representing the type, name, and size of parameter of 13781cb0ef41Sopenharmony_cian ephemeral key exchange in <a href="#perfect-forward-secrecy">perfect forward secrecy</a> on a client 13791cb0ef41Sopenharmony_ciconnection. It returns an empty object when the key exchange is not 13801cb0ef41Sopenharmony_ciephemeral. As this is only supported on a client socket; <code>null</code> is returned 13811cb0ef41Sopenharmony_ciif called on a server socket. The supported types are <code>'DH'</code> and <code>'ECDH'</code>. The 13821cb0ef41Sopenharmony_ci<code>name</code> property is available only when type is <code>'ECDH'</code>.</p> 13831cb0ef41Sopenharmony_ci<p>For example: <code>{ type: 'ECDH', name: 'prime256v1', size: 256 }</code>.</p> 13841cb0ef41Sopenharmony_ci<h4><code>tlsSocket.getFinished()</code><span><a class="mark" href="#tlssocketgetfinished" id="tlssocketgetfinished">#</a></span><a aria-hidden="true" class="legacy" id="tls_tlssocket_getfinished"></a></h4> 13851cb0ef41Sopenharmony_ci<div class="api_metadata"> 13861cb0ef41Sopenharmony_ci<span>Added in: v9.9.0</span> 13871cb0ef41Sopenharmony_ci</div> 13881cb0ef41Sopenharmony_ci<ul> 13891cb0ef41Sopenharmony_ci<li>Returns: <a href="buffer.html#class-buffer" class="type"><Buffer></a> | <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Undefined_type" class="type"><undefined></a> The latest <code>Finished</code> message that has been 13901cb0ef41Sopenharmony_cisent to the socket as part of a SSL/TLS handshake, or <code>undefined</code> if 13911cb0ef41Sopenharmony_cino <code>Finished</code> message has been sent yet.</li> 13921cb0ef41Sopenharmony_ci</ul> 13931cb0ef41Sopenharmony_ci<p>As the <code>Finished</code> messages are message digests of the complete handshake 13941cb0ef41Sopenharmony_ci(with a total of 192 bits for TLS 1.0 and more for SSL 3.0), they can 13951cb0ef41Sopenharmony_cibe used for external authentication procedures when the authentication 13961cb0ef41Sopenharmony_ciprovided by SSL/TLS is not desired or is not enough.</p> 13971cb0ef41Sopenharmony_ci<p>Corresponds to the <code>SSL_get_finished</code> routine in OpenSSL and may be used 13981cb0ef41Sopenharmony_cito implement the <code>tls-unique</code> channel binding from <a href="https://tools.ietf.org/html/rfc5929">RFC 5929</a>.</p> 13991cb0ef41Sopenharmony_ci<h4><code>tlsSocket.getPeerCertificate([detailed])</code><span><a class="mark" href="#tlssocketgetpeercertificatedetailed" id="tlssocketgetpeercertificatedetailed">#</a></span><a aria-hidden="true" class="legacy" id="tls_tlssocket_getpeercertificate_detailed"></a></h4> 14001cb0ef41Sopenharmony_ci<div class="api_metadata"> 14011cb0ef41Sopenharmony_ci<span>Added in: v0.11.4</span> 14021cb0ef41Sopenharmony_ci</div> 14031cb0ef41Sopenharmony_ci<ul> 14041cb0ef41Sopenharmony_ci<li><code>detailed</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type" class="type"><boolean></a> Include the full certificate chain if <code>true</code>, otherwise 14051cb0ef41Sopenharmony_ciinclude just the peer's certificate.</li> 14061cb0ef41Sopenharmony_ci<li>Returns: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object" class="type"><Object></a> A certificate object.</li> 14071cb0ef41Sopenharmony_ci</ul> 14081cb0ef41Sopenharmony_ci<p>Returns an object representing the peer's certificate. If the peer does not 14091cb0ef41Sopenharmony_ciprovide a certificate, an empty object will be returned. If the socket has been 14101cb0ef41Sopenharmony_cidestroyed, <code>null</code> will be returned.</p> 14111cb0ef41Sopenharmony_ci<p>If the full certificate chain was requested, each certificate will include an 14121cb0ef41Sopenharmony_ci<code>issuerCertificate</code> property containing an object representing its issuer's 14131cb0ef41Sopenharmony_cicertificate.</p> 14141cb0ef41Sopenharmony_ci<h5>Certificate object<span><a class="mark" href="#certificate-object" id="certificate-object">#</a></span><a aria-hidden="true" class="legacy" id="tls_certificate_object"></a></h5> 14151cb0ef41Sopenharmony_ci<div class="api_metadata"> 14161cb0ef41Sopenharmony_ci<details class="changelog"><summary>History</summary> 14171cb0ef41Sopenharmony_ci<table> 14181cb0ef41Sopenharmony_ci<tbody><tr><th>Version</th><th>Changes</th></tr> 14191cb0ef41Sopenharmony_ci<tr><td>v18.13.0</td> 14201cb0ef41Sopenharmony_ci<td><p>Add "ca" property.</p></td></tr> 14211cb0ef41Sopenharmony_ci<tr><td>v17.2.0, v16.14.0</td> 14221cb0ef41Sopenharmony_ci<td><p>Add fingerprint512.</p></td></tr> 14231cb0ef41Sopenharmony_ci<tr><td>v11.4.0</td> 14241cb0ef41Sopenharmony_ci<td><p>Support Elliptic Curve public key info.</p></td></tr> 14251cb0ef41Sopenharmony_ci</tbody></table> 14261cb0ef41Sopenharmony_ci</details> 14271cb0ef41Sopenharmony_ci</div> 14281cb0ef41Sopenharmony_ci<p>A certificate object has properties corresponding to the fields of the 14291cb0ef41Sopenharmony_cicertificate.</p> 14301cb0ef41Sopenharmony_ci<ul> 14311cb0ef41Sopenharmony_ci<li><code>ca</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type" class="type"><boolean></a> <code>true</code> if a Certificate Authority (CA), <code>false</code> otherwise.</li> 14321cb0ef41Sopenharmony_ci<li><code>raw</code> <a href="buffer.html#class-buffer" class="type"><Buffer></a> The DER encoded X.509 certificate data.</li> 14331cb0ef41Sopenharmony_ci<li><code>subject</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object" class="type"><Object></a> The certificate subject, described in terms of 14341cb0ef41Sopenharmony_ciCountry (<code>C</code>), StateOrProvince (<code>ST</code>), Locality (<code>L</code>), Organization (<code>O</code>), 14351cb0ef41Sopenharmony_ciOrganizationalUnit (<code>OU</code>), and CommonName (<code>CN</code>). The CommonName is typically 14361cb0ef41Sopenharmony_cia DNS name with TLS certificates. Example: 14371cb0ef41Sopenharmony_ci<code>{C: 'UK', ST: 'BC', L: 'Metro', O: 'Node Fans', OU: 'Docs', CN: 'example.com'}</code>.</li> 14381cb0ef41Sopenharmony_ci<li><code>issuer</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object" class="type"><Object></a> The certificate issuer, described in the same terms as the 14391cb0ef41Sopenharmony_ci<code>subject</code>.</li> 14401cb0ef41Sopenharmony_ci<li><code>valid_from</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> The date-time the certificate is valid from.</li> 14411cb0ef41Sopenharmony_ci<li><code>valid_to</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> The date-time the certificate is valid to.</li> 14421cb0ef41Sopenharmony_ci<li><code>serialNumber</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> The certificate serial number, as a hex string. 14431cb0ef41Sopenharmony_ciExample: <code>'B9B0D332A1AA5635'</code>.</li> 14441cb0ef41Sopenharmony_ci<li><code>fingerprint</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> The SHA-1 digest of the DER encoded certificate. It is 14451cb0ef41Sopenharmony_cireturned as a <code>:</code> separated hexadecimal string. Example: <code>'2A:7A:C2:DD:...'</code>.</li> 14461cb0ef41Sopenharmony_ci<li><code>fingerprint256</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> The SHA-256 digest of the DER encoded certificate. 14471cb0ef41Sopenharmony_ciIt is returned as a <code>:</code> separated hexadecimal string. Example: 14481cb0ef41Sopenharmony_ci<code>'2A:7A:C2:DD:...'</code>.</li> 14491cb0ef41Sopenharmony_ci<li><code>fingerprint512</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> The SHA-512 digest of the DER encoded certificate. 14501cb0ef41Sopenharmony_ciIt is returned as a <code>:</code> separated hexadecimal string. Example: 14511cb0ef41Sopenharmony_ci<code>'2A:7A:C2:DD:...'</code>.</li> 14521cb0ef41Sopenharmony_ci<li><code>ext_key_usage</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array" class="type"><Array></a> (Optional) The extended key usage, a set of OIDs.</li> 14531cb0ef41Sopenharmony_ci<li><code>subjectaltname</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> (Optional) A string containing concatenated names 14541cb0ef41Sopenharmony_cifor the subject, an alternative to the <code>subject</code> names.</li> 14551cb0ef41Sopenharmony_ci<li><code>infoAccess</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array" class="type"><Array></a> (Optional) An array describing the AuthorityInfoAccess, 14561cb0ef41Sopenharmony_ciused with OCSP.</li> 14571cb0ef41Sopenharmony_ci<li><code>issuerCertificate</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object" class="type"><Object></a> (Optional) The issuer certificate object. For 14581cb0ef41Sopenharmony_ciself-signed certificates, this may be a circular reference.</li> 14591cb0ef41Sopenharmony_ci</ul> 14601cb0ef41Sopenharmony_ci<p>The certificate may contain information about the public key, depending on 14611cb0ef41Sopenharmony_cithe key type.</p> 14621cb0ef41Sopenharmony_ci<p>For RSA keys, the following properties may be defined:</p> 14631cb0ef41Sopenharmony_ci<ul> 14641cb0ef41Sopenharmony_ci<li><code>bits</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><number></a> The RSA bit size. Example: <code>1024</code>.</li> 14651cb0ef41Sopenharmony_ci<li><code>exponent</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> The RSA exponent, as a string in hexadecimal number 14661cb0ef41Sopenharmony_cinotation. Example: <code>'0x010001'</code>.</li> 14671cb0ef41Sopenharmony_ci<li><code>modulus</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> The RSA modulus, as a hexadecimal string. Example: 14681cb0ef41Sopenharmony_ci<code>'B56CE45CB7...'</code>.</li> 14691cb0ef41Sopenharmony_ci<li><code>pubkey</code> <a href="buffer.html#class-buffer" class="type"><Buffer></a> The public key.</li> 14701cb0ef41Sopenharmony_ci</ul> 14711cb0ef41Sopenharmony_ci<p>For EC keys, the following properties may be defined:</p> 14721cb0ef41Sopenharmony_ci<ul> 14731cb0ef41Sopenharmony_ci<li><code>pubkey</code> <a href="buffer.html#class-buffer" class="type"><Buffer></a> The public key.</li> 14741cb0ef41Sopenharmony_ci<li><code>bits</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><number></a> The key size in bits. Example: <code>256</code>.</li> 14751cb0ef41Sopenharmony_ci<li><code>asn1Curve</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> (Optional) The ASN.1 name of the OID of the elliptic 14761cb0ef41Sopenharmony_cicurve. Well-known curves are identified by an OID. While it is unusual, it is 14771cb0ef41Sopenharmony_cipossible that the curve is identified by its mathematical properties, in which 14781cb0ef41Sopenharmony_cicase it will not have an OID. Example: <code>'prime256v1'</code>.</li> 14791cb0ef41Sopenharmony_ci<li><code>nistCurve</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> (Optional) The NIST name for the elliptic curve, if it 14801cb0ef41Sopenharmony_cihas one (not all well-known curves have been assigned names by NIST). Example: 14811cb0ef41Sopenharmony_ci<code>'P-256'</code>.</li> 14821cb0ef41Sopenharmony_ci</ul> 14831cb0ef41Sopenharmony_ci<p>Example certificate:</p> 14841cb0ef41Sopenharmony_ci<!-- eslint-skip --> 14851cb0ef41Sopenharmony_ci<pre><code class="language-js">{ <span class="hljs-attr">subject</span>: 14861cb0ef41Sopenharmony_ci { <span class="hljs-attr">OU</span>: [ <span class="hljs-string">'Domain Control Validated'</span>, <span class="hljs-string">'PositiveSSL Wildcard'</span> ], 14871cb0ef41Sopenharmony_ci <span class="hljs-attr">CN</span>: <span class="hljs-string">'*.nodejs.org'</span> }, 14881cb0ef41Sopenharmony_ci <span class="hljs-attr">issuer</span>: 14891cb0ef41Sopenharmony_ci { <span class="hljs-attr">C</span>: <span class="hljs-string">'GB'</span>, 14901cb0ef41Sopenharmony_ci <span class="hljs-attr">ST</span>: <span class="hljs-string">'Greater Manchester'</span>, 14911cb0ef41Sopenharmony_ci <span class="hljs-attr">L</span>: <span class="hljs-string">'Salford'</span>, 14921cb0ef41Sopenharmony_ci <span class="hljs-attr">O</span>: <span class="hljs-string">'COMODO CA Limited'</span>, 14931cb0ef41Sopenharmony_ci <span class="hljs-attr">CN</span>: <span class="hljs-string">'COMODO RSA Domain Validation Secure Server CA'</span> }, 14941cb0ef41Sopenharmony_ci <span class="hljs-attr">subjectaltname</span>: <span class="hljs-string">'DNS:*.nodejs.org, DNS:nodejs.org'</span>, 14951cb0ef41Sopenharmony_ci <span class="hljs-attr">infoAccess</span>: 14961cb0ef41Sopenharmony_ci { <span class="hljs-string">'CA Issuers - URI'</span>: 14971cb0ef41Sopenharmony_ci [ <span class="hljs-string">'http://crt.comodoca.com/COMODORSADomainValidationSecureServerCA.crt'</span> ], 14981cb0ef41Sopenharmony_ci <span class="hljs-string">'OCSP - URI'</span>: [ <span class="hljs-string">'http://ocsp.comodoca.com'</span> ] }, 14991cb0ef41Sopenharmony_ci <span class="hljs-attr">modulus</span>: <span class="hljs-string">'B56CE45CB740B09A13F64AC543B712FF9EE8E4C284B542A1708A27E82A8D151CA178153E12E6DDA15BF70FFD96CB8A88618641BDFCCA03527E665B70D779C8A349A6F88FD4EF6557180BD4C98192872BCFE3AF56E863C09DDD8BC1EC58DF9D94F914F0369102B2870BECFA1348A0838C9C49BD1C20124B442477572347047506B1FCD658A80D0C44BCC16BC5C5496CFE6E4A8428EF654CD3D8972BF6E5BFAD59C93006830B5EB1056BBB38B53D1464FA6E02BFDF2FF66CD949486F0775EC43034EC2602AEFBF1703AD221DAA2A88353C3B6A688EFE8387811F645CEED7B3FE46E1F8B9F59FAD028F349B9BC14211D5830994D055EEA3D547911E07A0ADDEB8A82B9188E58720D95CD478EEC9AF1F17BE8141BE80906F1A339445A7EB5B285F68039B0F294598A7D1C0005FC22B5271B0752F58CCDEF8C8FD856FB7AE21C80B8A2CE983AE94046E53EDE4CB89F42502D31B5360771C01C80155918637490550E3F555E2EE75CC8C636DDE3633CFEDD62E91BF0F7688273694EEEBA20C2FC9F14A2A435517BC1D7373922463409AB603295CEB0BB53787A334C9CA3CA8B30005C5A62FC0715083462E00719A8FA3ED0A9828C3871360A73F8B04A4FC1E71302844E9BB9940B77E745C9D91F226D71AFCAD4B113AAF68D92B24DDB4A2136B55A1CD1ADF39605B63CB639038ED0F4C987689866743A68769CC55847E4A06D6E2E3F1'</span>, 15001cb0ef41Sopenharmony_ci <span class="hljs-attr">exponent</span>: <span class="hljs-string">'0x10001'</span>, 15011cb0ef41Sopenharmony_ci <span class="hljs-attr">pubkey</span>: <Buffer ... >, 15021cb0ef41Sopenharmony_ci valid_from: 'Aug 14 00:00:00 2017 GMT', 15031cb0ef41Sopenharmony_ci valid_to: 'Nov 20 23:59:59 2019 GMT', 15041cb0ef41Sopenharmony_ci fingerprint: '01:02:59:D9:C3:D2:0D:08:F7:82:4E:44:A4:B4:53:C5:E2:3A:87:4D', 15051cb0ef41Sopenharmony_ci fingerprint256: '69:AE:1A:6A:D4:3D:C6:C1:1B:EA:C6:23:DE:BA:2A:14:62:62:93:5C:7A:EA:06:41:9B:0B:BC:87:CE:48:4E:02', 15061cb0ef41Sopenharmony_ci fingerprint512: '19:2B:3E:C3:B3:5B:32:E8:AE:BB:78:97:27:E4:BA:6C:39:C9:92:79:4F:31:46:39:E2:70:E5:5F:89:42:17:C9:E8:64:CA:FF:BB:72:56:73:6E:28:8A:92:7E:A3:2A:15:8B:C2:E0:45:CA:C3:BC:EA:40:52:EC:CA:A2:68:CB:32', 15071cb0ef41Sopenharmony_ci ext_key_usage: [ '1.3.6.1.5.5.7.3.1', '1.3.6.1.5.5.7.3.2' ], 15081cb0ef41Sopenharmony_ci serialNumber: '66593D57F20CBC573E433381B5FEC280', 15091cb0ef41Sopenharmony_ci raw: <Buffer ... > }</code> <button class="copy-button">copy</button></pre> 15101cb0ef41Sopenharmony_ci<h4><code>tlsSocket.getPeerFinished()</code><span><a class="mark" href="#tlssocketgetpeerfinished" id="tlssocketgetpeerfinished">#</a></span><a aria-hidden="true" class="legacy" id="tls_tlssocket_getpeerfinished"></a></h4> 15111cb0ef41Sopenharmony_ci<div class="api_metadata"> 15121cb0ef41Sopenharmony_ci<span>Added in: v9.9.0</span> 15131cb0ef41Sopenharmony_ci</div> 15141cb0ef41Sopenharmony_ci<ul> 15151cb0ef41Sopenharmony_ci<li>Returns: <a href="buffer.html#class-buffer" class="type"><Buffer></a> | <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Undefined_type" class="type"><undefined></a> The latest <code>Finished</code> message that is expected 15161cb0ef41Sopenharmony_cior has actually been received from the socket as part of a SSL/TLS handshake, 15171cb0ef41Sopenharmony_cior <code>undefined</code> if there is no <code>Finished</code> message so far.</li> 15181cb0ef41Sopenharmony_ci</ul> 15191cb0ef41Sopenharmony_ci<p>As the <code>Finished</code> messages are message digests of the complete handshake 15201cb0ef41Sopenharmony_ci(with a total of 192 bits for TLS 1.0 and more for SSL 3.0), they can 15211cb0ef41Sopenharmony_cibe used for external authentication procedures when the authentication 15221cb0ef41Sopenharmony_ciprovided by SSL/TLS is not desired or is not enough.</p> 15231cb0ef41Sopenharmony_ci<p>Corresponds to the <code>SSL_get_peer_finished</code> routine in OpenSSL and may be used 15241cb0ef41Sopenharmony_cito implement the <code>tls-unique</code> channel binding from <a href="https://tools.ietf.org/html/rfc5929">RFC 5929</a>.</p> 15251cb0ef41Sopenharmony_ci<h4><code>tlsSocket.getPeerX509Certificate()</code><span><a class="mark" href="#tlssocketgetpeerx509certificate" id="tlssocketgetpeerx509certificate">#</a></span><a aria-hidden="true" class="legacy" id="tls_tlssocket_getpeerx509certificate"></a></h4> 15261cb0ef41Sopenharmony_ci<div class="api_metadata"> 15271cb0ef41Sopenharmony_ci<span>Added in: v15.9.0</span> 15281cb0ef41Sopenharmony_ci</div> 15291cb0ef41Sopenharmony_ci<ul> 15301cb0ef41Sopenharmony_ci<li>Returns: <a href="crypto.html#class-x509certificate" class="type"><X509Certificate></a></li> 15311cb0ef41Sopenharmony_ci</ul> 15321cb0ef41Sopenharmony_ci<p>Returns the peer certificate as an <a href="crypto.html#class-x509certificate" class="type"><X509Certificate></a> object.</p> 15331cb0ef41Sopenharmony_ci<p>If there is no peer certificate, or the socket has been destroyed, 15341cb0ef41Sopenharmony_ci<code>undefined</code> will be returned.</p> 15351cb0ef41Sopenharmony_ci<h4><code>tlsSocket.getProtocol()</code><span><a class="mark" href="#tlssocketgetprotocol" id="tlssocketgetprotocol">#</a></span><a aria-hidden="true" class="legacy" id="tls_tlssocket_getprotocol"></a></h4> 15361cb0ef41Sopenharmony_ci<div class="api_metadata"> 15371cb0ef41Sopenharmony_ci<span>Added in: v5.7.0</span> 15381cb0ef41Sopenharmony_ci</div> 15391cb0ef41Sopenharmony_ci<ul> 15401cb0ef41Sopenharmony_ci<li>Returns: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> | <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Null_type" class="type"><null></a></li> 15411cb0ef41Sopenharmony_ci</ul> 15421cb0ef41Sopenharmony_ci<p>Returns a string containing the negotiated SSL/TLS protocol version of the 15431cb0ef41Sopenharmony_cicurrent connection. The value <code>'unknown'</code> will be returned for connected 15441cb0ef41Sopenharmony_cisockets that have not completed the handshaking process. The value <code>null</code> will 15451cb0ef41Sopenharmony_cibe returned for server sockets or disconnected client sockets.</p> 15461cb0ef41Sopenharmony_ci<p>Protocol versions are:</p> 15471cb0ef41Sopenharmony_ci<ul> 15481cb0ef41Sopenharmony_ci<li><code>'SSLv3'</code></li> 15491cb0ef41Sopenharmony_ci<li><code>'TLSv1'</code></li> 15501cb0ef41Sopenharmony_ci<li><code>'TLSv1.1'</code></li> 15511cb0ef41Sopenharmony_ci<li><code>'TLSv1.2'</code></li> 15521cb0ef41Sopenharmony_ci<li><code>'TLSv1.3'</code></li> 15531cb0ef41Sopenharmony_ci</ul> 15541cb0ef41Sopenharmony_ci<p>See the OpenSSL <a href="https://www.openssl.org/docs/man1.1.1/man3/SSL_get_version.html"><code>SSL_get_version</code></a> documentation for more information.</p> 15551cb0ef41Sopenharmony_ci<h4><code>tlsSocket.getSession()</code><span><a class="mark" href="#tlssocketgetsession" id="tlssocketgetsession">#</a></span><a aria-hidden="true" class="legacy" id="tls_tlssocket_getsession"></a></h4> 15561cb0ef41Sopenharmony_ci<div class="api_metadata"> 15571cb0ef41Sopenharmony_ci<span>Added in: v0.11.4</span> 15581cb0ef41Sopenharmony_ci</div> 15591cb0ef41Sopenharmony_ci<ul> 15601cb0ef41Sopenharmony_ci<li><a href="buffer.html#class-buffer" class="type"><Buffer></a></li> 15611cb0ef41Sopenharmony_ci</ul> 15621cb0ef41Sopenharmony_ci<p>Returns the TLS session data or <code>undefined</code> if no session was 15631cb0ef41Sopenharmony_cinegotiated. On the client, the data can be provided to the <code>session</code> option of 15641cb0ef41Sopenharmony_ci<a href="#tlsconnectoptions-callback"><code>tls.connect()</code></a> to resume the connection. On the server, it may be useful 15651cb0ef41Sopenharmony_cifor debugging.</p> 15661cb0ef41Sopenharmony_ci<p>See <a href="#session-resumption">Session Resumption</a> for more information.</p> 15671cb0ef41Sopenharmony_ci<p>Note: <code>getSession()</code> works only for TLSv1.2 and below. For TLSv1.3, applications 15681cb0ef41Sopenharmony_cimust use the <a href="#event-session"><code>'session'</code></a> event (it also works for TLSv1.2 and below).</p> 15691cb0ef41Sopenharmony_ci<h4><code>tlsSocket.getSharedSigalgs()</code><span><a class="mark" href="#tlssocketgetsharedsigalgs" id="tlssocketgetsharedsigalgs">#</a></span><a aria-hidden="true" class="legacy" id="tls_tlssocket_getsharedsigalgs"></a></h4> 15701cb0ef41Sopenharmony_ci<div class="api_metadata"> 15711cb0ef41Sopenharmony_ci<span>Added in: v12.11.0</span> 15721cb0ef41Sopenharmony_ci</div> 15731cb0ef41Sopenharmony_ci<ul> 15741cb0ef41Sopenharmony_ci<li>Returns: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array" class="type"><Array></a> List of signature algorithms shared between the server and 15751cb0ef41Sopenharmony_cithe client in the order of decreasing preference.</li> 15761cb0ef41Sopenharmony_ci</ul> 15771cb0ef41Sopenharmony_ci<p>See 15781cb0ef41Sopenharmony_ci<a href="https://www.openssl.org/docs/man1.1.1/man3/SSL_get_shared_sigalgs.html">SSL_get_shared_sigalgs</a> 15791cb0ef41Sopenharmony_cifor more information.</p> 15801cb0ef41Sopenharmony_ci<h4><code>tlsSocket.getTLSTicket()</code><span><a class="mark" href="#tlssocketgettlsticket" id="tlssocketgettlsticket">#</a></span><a aria-hidden="true" class="legacy" id="tls_tlssocket_gettlsticket"></a></h4> 15811cb0ef41Sopenharmony_ci<div class="api_metadata"> 15821cb0ef41Sopenharmony_ci<span>Added in: v0.11.4</span> 15831cb0ef41Sopenharmony_ci</div> 15841cb0ef41Sopenharmony_ci<ul> 15851cb0ef41Sopenharmony_ci<li><a href="buffer.html#class-buffer" class="type"><Buffer></a></li> 15861cb0ef41Sopenharmony_ci</ul> 15871cb0ef41Sopenharmony_ci<p>For a client, returns the TLS session ticket if one is available, or 15881cb0ef41Sopenharmony_ci<code>undefined</code>. For a server, always returns <code>undefined</code>.</p> 15891cb0ef41Sopenharmony_ci<p>It may be useful for debugging.</p> 15901cb0ef41Sopenharmony_ci<p>See <a href="#session-resumption">Session Resumption</a> for more information.</p> 15911cb0ef41Sopenharmony_ci<h4><code>tlsSocket.getX509Certificate()</code><span><a class="mark" href="#tlssocketgetx509certificate" id="tlssocketgetx509certificate">#</a></span><a aria-hidden="true" class="legacy" id="tls_tlssocket_getx509certificate"></a></h4> 15921cb0ef41Sopenharmony_ci<div class="api_metadata"> 15931cb0ef41Sopenharmony_ci<span>Added in: v15.9.0</span> 15941cb0ef41Sopenharmony_ci</div> 15951cb0ef41Sopenharmony_ci<ul> 15961cb0ef41Sopenharmony_ci<li>Returns: <a href="crypto.html#class-x509certificate" class="type"><X509Certificate></a></li> 15971cb0ef41Sopenharmony_ci</ul> 15981cb0ef41Sopenharmony_ci<p>Returns the local certificate as an <a href="crypto.html#class-x509certificate" class="type"><X509Certificate></a> object.</p> 15991cb0ef41Sopenharmony_ci<p>If there is no local certificate, or the socket has been destroyed, 16001cb0ef41Sopenharmony_ci<code>undefined</code> will be returned.</p> 16011cb0ef41Sopenharmony_ci<h4><code>tlsSocket.isSessionReused()</code><span><a class="mark" href="#tlssocketissessionreused" id="tlssocketissessionreused">#</a></span><a aria-hidden="true" class="legacy" id="tls_tlssocket_issessionreused"></a></h4> 16021cb0ef41Sopenharmony_ci<div class="api_metadata"> 16031cb0ef41Sopenharmony_ci<span>Added in: v0.5.6</span> 16041cb0ef41Sopenharmony_ci</div> 16051cb0ef41Sopenharmony_ci<ul> 16061cb0ef41Sopenharmony_ci<li>Returns: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type" class="type"><boolean></a> <code>true</code> if the session was reused, <code>false</code> otherwise.</li> 16071cb0ef41Sopenharmony_ci</ul> 16081cb0ef41Sopenharmony_ci<p>See <a href="#session-resumption">Session Resumption</a> for more information.</p> 16091cb0ef41Sopenharmony_ci<h4><code>tlsSocket.localAddress</code><span><a class="mark" href="#tlssocketlocaladdress" id="tlssocketlocaladdress">#</a></span><a aria-hidden="true" class="legacy" id="tls_tlssocket_localaddress"></a></h4> 16101cb0ef41Sopenharmony_ci<div class="api_metadata"> 16111cb0ef41Sopenharmony_ci<span>Added in: v0.11.4</span> 16121cb0ef41Sopenharmony_ci</div> 16131cb0ef41Sopenharmony_ci<ul> 16141cb0ef41Sopenharmony_ci<li><a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a></li> 16151cb0ef41Sopenharmony_ci</ul> 16161cb0ef41Sopenharmony_ci<p>Returns the string representation of the local IP address.</p> 16171cb0ef41Sopenharmony_ci<h4><code>tlsSocket.localPort</code><span><a class="mark" href="#tlssocketlocalport" id="tlssocketlocalport">#</a></span><a aria-hidden="true" class="legacy" id="tls_tlssocket_localport"></a></h4> 16181cb0ef41Sopenharmony_ci<div class="api_metadata"> 16191cb0ef41Sopenharmony_ci<span>Added in: v0.11.4</span> 16201cb0ef41Sopenharmony_ci</div> 16211cb0ef41Sopenharmony_ci<ul> 16221cb0ef41Sopenharmony_ci<li><a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><integer></a></li> 16231cb0ef41Sopenharmony_ci</ul> 16241cb0ef41Sopenharmony_ci<p>Returns the numeric representation of the local port.</p> 16251cb0ef41Sopenharmony_ci<h4><code>tlsSocket.remoteAddress</code><span><a class="mark" href="#tlssocketremoteaddress" id="tlssocketremoteaddress">#</a></span><a aria-hidden="true" class="legacy" id="tls_tlssocket_remoteaddress"></a></h4> 16261cb0ef41Sopenharmony_ci<div class="api_metadata"> 16271cb0ef41Sopenharmony_ci<span>Added in: v0.11.4</span> 16281cb0ef41Sopenharmony_ci</div> 16291cb0ef41Sopenharmony_ci<ul> 16301cb0ef41Sopenharmony_ci<li><a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a></li> 16311cb0ef41Sopenharmony_ci</ul> 16321cb0ef41Sopenharmony_ci<p>Returns the string representation of the remote IP address. For example, 16331cb0ef41Sopenharmony_ci<code>'74.125.127.100'</code> or <code>'2001:4860:a005::68'</code>.</p> 16341cb0ef41Sopenharmony_ci<h4><code>tlsSocket.remoteFamily</code><span><a class="mark" href="#tlssocketremotefamily" id="tlssocketremotefamily">#</a></span><a aria-hidden="true" class="legacy" id="tls_tlssocket_remotefamily"></a></h4> 16351cb0ef41Sopenharmony_ci<div class="api_metadata"> 16361cb0ef41Sopenharmony_ci<span>Added in: v0.11.4</span> 16371cb0ef41Sopenharmony_ci</div> 16381cb0ef41Sopenharmony_ci<ul> 16391cb0ef41Sopenharmony_ci<li><a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a></li> 16401cb0ef41Sopenharmony_ci</ul> 16411cb0ef41Sopenharmony_ci<p>Returns the string representation of the remote IP family. <code>'IPv4'</code> or <code>'IPv6'</code>.</p> 16421cb0ef41Sopenharmony_ci<h4><code>tlsSocket.remotePort</code><span><a class="mark" href="#tlssocketremoteport" id="tlssocketremoteport">#</a></span><a aria-hidden="true" class="legacy" id="tls_tlssocket_remoteport"></a></h4> 16431cb0ef41Sopenharmony_ci<div class="api_metadata"> 16441cb0ef41Sopenharmony_ci<span>Added in: v0.11.4</span> 16451cb0ef41Sopenharmony_ci</div> 16461cb0ef41Sopenharmony_ci<ul> 16471cb0ef41Sopenharmony_ci<li><a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><integer></a></li> 16481cb0ef41Sopenharmony_ci</ul> 16491cb0ef41Sopenharmony_ci<p>Returns the numeric representation of the remote port. For example, <code>443</code>.</p> 16501cb0ef41Sopenharmony_ci<h4><code>tlsSocket.renegotiate(options, callback)</code><span><a class="mark" href="#tlssocketrenegotiateoptions-callback" id="tlssocketrenegotiateoptions-callback">#</a></span><a aria-hidden="true" class="legacy" id="tls_tlssocket_renegotiate_options_callback"></a></h4> 16511cb0ef41Sopenharmony_ci<div class="api_metadata"> 16521cb0ef41Sopenharmony_ci<details class="changelog"><summary>History</summary> 16531cb0ef41Sopenharmony_ci<table> 16541cb0ef41Sopenharmony_ci<tbody><tr><th>Version</th><th>Changes</th></tr> 16551cb0ef41Sopenharmony_ci<tr><td>v18.0.0</td> 16561cb0ef41Sopenharmony_ci<td><p>Passing an invalid callback to the <code>callback</code> argument now throws <code>ERR_INVALID_ARG_TYPE</code> instead of <code>ERR_INVALID_CALLBACK</code>.</p></td></tr> 16571cb0ef41Sopenharmony_ci<tr><td>v0.11.8</td> 16581cb0ef41Sopenharmony_ci<td><p><span>Added in: v0.11.8</span></p></td></tr> 16591cb0ef41Sopenharmony_ci</tbody></table> 16601cb0ef41Sopenharmony_ci</details> 16611cb0ef41Sopenharmony_ci</div> 16621cb0ef41Sopenharmony_ci<ul> 16631cb0ef41Sopenharmony_ci<li> 16641cb0ef41Sopenharmony_ci<p><code>options</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object" class="type"><Object></a></p> 16651cb0ef41Sopenharmony_ci<ul> 16661cb0ef41Sopenharmony_ci<li><code>rejectUnauthorized</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type" class="type"><boolean></a> If not <code>false</code>, the server certificate is 16671cb0ef41Sopenharmony_civerified against the list of supplied CAs. An <code>'error'</code> event is emitted if 16681cb0ef41Sopenharmony_civerification fails; <code>err.code</code> contains the OpenSSL error code. <strong>Default:</strong> 16691cb0ef41Sopenharmony_ci<code>true</code>.</li> 16701cb0ef41Sopenharmony_ci<li><code>requestCert</code></li> 16711cb0ef41Sopenharmony_ci</ul> 16721cb0ef41Sopenharmony_ci</li> 16731cb0ef41Sopenharmony_ci<li> 16741cb0ef41Sopenharmony_ci<p><code>callback</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function" class="type"><Function></a> If <code>renegotiate()</code> returned <code>true</code>, callback is 16751cb0ef41Sopenharmony_ciattached once to the <code>'secure'</code> event. If <code>renegotiate()</code> returned <code>false</code>, 16761cb0ef41Sopenharmony_ci<code>callback</code> will be called in the next tick with an error, unless the 16771cb0ef41Sopenharmony_ci<code>tlsSocket</code> has been destroyed, in which case <code>callback</code> will not be called 16781cb0ef41Sopenharmony_ciat all.</p> 16791cb0ef41Sopenharmony_ci</li> 16801cb0ef41Sopenharmony_ci<li> 16811cb0ef41Sopenharmony_ci<p>Returns: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type" class="type"><boolean></a> <code>true</code> if renegotiation was initiated, <code>false</code> otherwise.</p> 16821cb0ef41Sopenharmony_ci</li> 16831cb0ef41Sopenharmony_ci</ul> 16841cb0ef41Sopenharmony_ci<p>The <code>tlsSocket.renegotiate()</code> method initiates a TLS renegotiation process. 16851cb0ef41Sopenharmony_ciUpon completion, the <code>callback</code> function will be passed a single argument 16861cb0ef41Sopenharmony_cithat is either an <code>Error</code> (if the request failed) or <code>null</code>.</p> 16871cb0ef41Sopenharmony_ci<p>This method can be used to request a peer's certificate after the secure 16881cb0ef41Sopenharmony_ciconnection has been established.</p> 16891cb0ef41Sopenharmony_ci<p>When running as the server, the socket will be destroyed with an error after 16901cb0ef41Sopenharmony_ci<code>handshakeTimeout</code> timeout.</p> 16911cb0ef41Sopenharmony_ci<p>For TLSv1.3, renegotiation cannot be initiated, it is not supported by the 16921cb0ef41Sopenharmony_ciprotocol.</p> 16931cb0ef41Sopenharmony_ci<h4><code>tlsSocket.setMaxSendFragment(size)</code><span><a class="mark" href="#tlssocketsetmaxsendfragmentsize" id="tlssocketsetmaxsendfragmentsize">#</a></span><a aria-hidden="true" class="legacy" id="tls_tlssocket_setmaxsendfragment_size"></a></h4> 16941cb0ef41Sopenharmony_ci<div class="api_metadata"> 16951cb0ef41Sopenharmony_ci<span>Added in: v0.11.11</span> 16961cb0ef41Sopenharmony_ci</div> 16971cb0ef41Sopenharmony_ci<ul> 16981cb0ef41Sopenharmony_ci<li><code>size</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><number></a> The maximum TLS fragment size. The maximum value is <code>16384</code>. 16991cb0ef41Sopenharmony_ci<strong>Default:</strong> <code>16384</code>.</li> 17001cb0ef41Sopenharmony_ci<li>Returns: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type" class="type"><boolean></a></li> 17011cb0ef41Sopenharmony_ci</ul> 17021cb0ef41Sopenharmony_ci<p>The <code>tlsSocket.setMaxSendFragment()</code> method sets the maximum TLS fragment size. 17031cb0ef41Sopenharmony_ciReturns <code>true</code> if setting the limit succeeded; <code>false</code> otherwise.</p> 17041cb0ef41Sopenharmony_ci<p>Smaller fragment sizes decrease the buffering latency on the client: larger 17051cb0ef41Sopenharmony_cifragments are buffered by the TLS layer until the entire fragment is received 17061cb0ef41Sopenharmony_ciand its integrity is verified; large fragments can span multiple roundtrips 17071cb0ef41Sopenharmony_ciand their processing can be delayed due to packet loss or reordering. However, 17081cb0ef41Sopenharmony_cismaller fragments add extra TLS framing bytes and CPU overhead, which may 17091cb0ef41Sopenharmony_cidecrease overall server throughput.</p> 17101cb0ef41Sopenharmony_ci</section><section><h3><code>tls.checkServerIdentity(hostname, cert)</code><span><a class="mark" href="#tlscheckserveridentityhostname-cert" id="tlscheckserveridentityhostname-cert">#</a></span><a aria-hidden="true" class="legacy" id="tls_tls_checkserveridentity_hostname_cert"></a></h3> 17111cb0ef41Sopenharmony_ci<div class="api_metadata"> 17121cb0ef41Sopenharmony_ci<details class="changelog"><summary>History</summary> 17131cb0ef41Sopenharmony_ci<table> 17141cb0ef41Sopenharmony_ci<tbody><tr><th>Version</th><th>Changes</th></tr> 17151cb0ef41Sopenharmony_ci<tr><td>v17.3.1, v16.13.2, v14.18.3, v12.22.9</td> 17161cb0ef41Sopenharmony_ci<td><p>Support for <code>uniformResourceIdentifier</code> subject alternative names has been disabled in response to CVE-2021-44531.</p></td></tr> 17171cb0ef41Sopenharmony_ci<tr><td>v0.8.4</td> 17181cb0ef41Sopenharmony_ci<td><p><span>Added in: v0.8.4</span></p></td></tr> 17191cb0ef41Sopenharmony_ci</tbody></table> 17201cb0ef41Sopenharmony_ci</details> 17211cb0ef41Sopenharmony_ci</div> 17221cb0ef41Sopenharmony_ci<ul> 17231cb0ef41Sopenharmony_ci<li><code>hostname</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> The host name or IP address to verify the certificate 17241cb0ef41Sopenharmony_ciagainst.</li> 17251cb0ef41Sopenharmony_ci<li><code>cert</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object" class="type"><Object></a> A <a href="#certificate-object">certificate object</a> representing the peer's certificate.</li> 17261cb0ef41Sopenharmony_ci<li>Returns: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error" class="type"><Error></a> | <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Undefined_type" class="type"><undefined></a></li> 17271cb0ef41Sopenharmony_ci</ul> 17281cb0ef41Sopenharmony_ci<p>Verifies the certificate <code>cert</code> is issued to <code>hostname</code>.</p> 17291cb0ef41Sopenharmony_ci<p>Returns <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error" class="type"><Error></a> object, populating it with <code>reason</code>, <code>host</code>, and <code>cert</code> on 17301cb0ef41Sopenharmony_cifailure. On success, returns <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Undefined_type" class="type"><undefined></a>.</p> 17311cb0ef41Sopenharmony_ci<p>This function is intended to be used in combination with the 17321cb0ef41Sopenharmony_ci<code>checkServerIdentity</code> option that can be passed to <a href="#tlsconnectoptions-callback"><code>tls.connect()</code></a> and as 17331cb0ef41Sopenharmony_cisuch operates on a <a href="#certificate-object">certificate object</a>. For other purposes, consider using 17341cb0ef41Sopenharmony_ci<a href="crypto.html#x509checkhostname-options"><code>x509.checkHost()</code></a> instead.</p> 17351cb0ef41Sopenharmony_ci<p>This function can be overwritten by providing an alternative function as the 17361cb0ef41Sopenharmony_ci<code>options.checkServerIdentity</code> option that is passed to <code>tls.connect()</code>. The 17371cb0ef41Sopenharmony_cioverwriting function can call <code>tls.checkServerIdentity()</code> of course, to augment 17381cb0ef41Sopenharmony_cithe checks done with additional verification.</p> 17391cb0ef41Sopenharmony_ci<p>This function is only called if the certificate passed all other checks, such as 17401cb0ef41Sopenharmony_cibeing issued by trusted CA (<code>options.ca</code>).</p> 17411cb0ef41Sopenharmony_ci<p>Earlier versions of Node.js incorrectly accepted certificates for a given 17421cb0ef41Sopenharmony_ci<code>hostname</code> if a matching <code>uniformResourceIdentifier</code> subject alternative name 17431cb0ef41Sopenharmony_ciwas present (see <a href="https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2021-44531">CVE-2021-44531</a>). Applications that wish to accept 17441cb0ef41Sopenharmony_ci<code>uniformResourceIdentifier</code> subject alternative names can use a custom 17451cb0ef41Sopenharmony_ci<code>options.checkServerIdentity</code> function that implements the desired behavior.</p> 17461cb0ef41Sopenharmony_ci</section><section><h3><code>tls.connect(options[, callback])</code><span><a class="mark" href="#tlsconnectoptions-callback" id="tlsconnectoptions-callback">#</a></span><a aria-hidden="true" class="legacy" id="tls_tls_connect_options_callback"></a></h3> 17471cb0ef41Sopenharmony_ci<div class="api_metadata"> 17481cb0ef41Sopenharmony_ci<details class="changelog"><summary>History</summary> 17491cb0ef41Sopenharmony_ci<table> 17501cb0ef41Sopenharmony_ci<tbody><tr><th>Version</th><th>Changes</th></tr> 17511cb0ef41Sopenharmony_ci<tr><td>v15.1.0, v14.18.0</td> 17521cb0ef41Sopenharmony_ci<td><p>Added <code>onread</code> option.</p></td></tr> 17531cb0ef41Sopenharmony_ci<tr><td>v14.1.0, v13.14.0</td> 17541cb0ef41Sopenharmony_ci<td><p>The <code>highWaterMark</code> option is accepted now.</p></td></tr> 17551cb0ef41Sopenharmony_ci<tr><td>v13.6.0, v12.16.0</td> 17561cb0ef41Sopenharmony_ci<td><p>The <code>pskCallback</code> option is now supported.</p></td></tr> 17571cb0ef41Sopenharmony_ci<tr><td>v12.9.0</td> 17581cb0ef41Sopenharmony_ci<td><p>Support the <code>allowHalfOpen</code> option.</p></td></tr> 17591cb0ef41Sopenharmony_ci<tr><td>v12.4.0</td> 17601cb0ef41Sopenharmony_ci<td><p>The <code>hints</code> option is now supported.</p></td></tr> 17611cb0ef41Sopenharmony_ci<tr><td>v12.2.0</td> 17621cb0ef41Sopenharmony_ci<td><p>The <code>enableTrace</code> option is now supported.</p></td></tr> 17631cb0ef41Sopenharmony_ci<tr><td>v11.8.0, v10.16.0</td> 17641cb0ef41Sopenharmony_ci<td><p>The <code>timeout</code> option is supported now.</p></td></tr> 17651cb0ef41Sopenharmony_ci<tr><td>v8.0.0</td> 17661cb0ef41Sopenharmony_ci<td><p>The <code>lookup</code> option is supported now.</p></td></tr> 17671cb0ef41Sopenharmony_ci<tr><td>v8.0.0</td> 17681cb0ef41Sopenharmony_ci<td><p>The <code>ALPNProtocols</code> option can be a <code>TypedArray</code> or <code>DataView</code> now.</p></td></tr> 17691cb0ef41Sopenharmony_ci<tr><td>v5.0.0</td> 17701cb0ef41Sopenharmony_ci<td><p>ALPN options are supported now.</p></td></tr> 17711cb0ef41Sopenharmony_ci<tr><td>v5.3.0, v4.7.0</td> 17721cb0ef41Sopenharmony_ci<td><p>The <code>secureContext</code> option is supported now.</p></td></tr> 17731cb0ef41Sopenharmony_ci<tr><td>v0.11.3</td> 17741cb0ef41Sopenharmony_ci<td><p><span>Added in: v0.11.3</span></p></td></tr> 17751cb0ef41Sopenharmony_ci</tbody></table> 17761cb0ef41Sopenharmony_ci</details> 17771cb0ef41Sopenharmony_ci</div> 17781cb0ef41Sopenharmony_ci<ul> 17791cb0ef41Sopenharmony_ci<li><code>options</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object" class="type"><Object></a> 17801cb0ef41Sopenharmony_ci<ul> 17811cb0ef41Sopenharmony_ci<li> 17821cb0ef41Sopenharmony_ci<p><code>enableTrace</code>: See <a href="#tlscreateserveroptions-secureconnectionlistener"><code>tls.createServer()</code></a></p> 17831cb0ef41Sopenharmony_ci</li> 17841cb0ef41Sopenharmony_ci<li> 17851cb0ef41Sopenharmony_ci<p><code>host</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> Host the client should connect to. <strong>Default:</strong> 17861cb0ef41Sopenharmony_ci<code>'localhost'</code>.</p> 17871cb0ef41Sopenharmony_ci</li> 17881cb0ef41Sopenharmony_ci<li> 17891cb0ef41Sopenharmony_ci<p><code>port</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><number></a> Port the client should connect to.</p> 17901cb0ef41Sopenharmony_ci</li> 17911cb0ef41Sopenharmony_ci<li> 17921cb0ef41Sopenharmony_ci<p><code>path</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> Creates Unix socket connection to path. If this option is 17931cb0ef41Sopenharmony_cispecified, <code>host</code> and <code>port</code> are ignored.</p> 17941cb0ef41Sopenharmony_ci</li> 17951cb0ef41Sopenharmony_ci<li> 17961cb0ef41Sopenharmony_ci<p><code>socket</code> <a href="stream.html#class-streamduplex" class="type"><stream.Duplex></a> Establish secure connection on a given socket 17971cb0ef41Sopenharmony_cirather than creating a new socket. Typically, this is an instance of 17981cb0ef41Sopenharmony_ci<a href="net.html#class-netsocket"><code>net.Socket</code></a>, but any <code>Duplex</code> stream is allowed. 17991cb0ef41Sopenharmony_ciIf this option is specified, <code>path</code>, <code>host</code>, and <code>port</code> are ignored, 18001cb0ef41Sopenharmony_ciexcept for certificate validation. Usually, a socket is already connected 18011cb0ef41Sopenharmony_ciwhen passed to <code>tls.connect()</code>, but it can be connected later. 18021cb0ef41Sopenharmony_ciConnection/disconnection/destruction of <code>socket</code> is the user's 18031cb0ef41Sopenharmony_ciresponsibility; calling <code>tls.connect()</code> will not cause <code>net.connect()</code> to be 18041cb0ef41Sopenharmony_cicalled.</p> 18051cb0ef41Sopenharmony_ci</li> 18061cb0ef41Sopenharmony_ci<li> 18071cb0ef41Sopenharmony_ci<p><code>allowHalfOpen</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type" class="type"><boolean></a> If set to <code>false</code>, then the socket will 18081cb0ef41Sopenharmony_ciautomatically end the writable side when the readable side ends. If the 18091cb0ef41Sopenharmony_ci<code>socket</code> option is set, this option has no effect. See the <code>allowHalfOpen</code> 18101cb0ef41Sopenharmony_cioption of <a href="net.html#class-netsocket"><code>net.Socket</code></a> for details. <strong>Default:</strong> <code>false</code>.</p> 18111cb0ef41Sopenharmony_ci</li> 18121cb0ef41Sopenharmony_ci<li> 18131cb0ef41Sopenharmony_ci<p><code>rejectUnauthorized</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type" class="type"><boolean></a> If not <code>false</code>, the server certificate is 18141cb0ef41Sopenharmony_civerified against the list of supplied CAs. An <code>'error'</code> event is emitted if 18151cb0ef41Sopenharmony_civerification fails; <code>err.code</code> contains the OpenSSL error code. <strong>Default:</strong> 18161cb0ef41Sopenharmony_ci<code>true</code>.</p> 18171cb0ef41Sopenharmony_ci</li> 18181cb0ef41Sopenharmony_ci<li> 18191cb0ef41Sopenharmony_ci<p><code>pskCallback</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function" class="type"><Function></a></p> 18201cb0ef41Sopenharmony_ci<ul> 18211cb0ef41Sopenharmony_ci<li>hint: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> optional message sent from the server to help client 18221cb0ef41Sopenharmony_cidecide which identity to use during negotiation. 18231cb0ef41Sopenharmony_ciAlways <code>null</code> if TLS 1.3 is used.</li> 18241cb0ef41Sopenharmony_ci<li>Returns: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object" class="type"><Object></a> in the form 18251cb0ef41Sopenharmony_ci<code>{ psk: <Buffer|TypedArray|DataView>, identity: <string> }</code> 18261cb0ef41Sopenharmony_cior <code>null</code> to stop the negotiation process. <code>psk</code> must be 18271cb0ef41Sopenharmony_cicompatible with the selected cipher's digest. 18281cb0ef41Sopenharmony_ci<code>identity</code> must use UTF-8 encoding.</li> 18291cb0ef41Sopenharmony_ci</ul> 18301cb0ef41Sopenharmony_ci<p>When negotiating TLS-PSK (pre-shared keys), this function is called 18311cb0ef41Sopenharmony_ciwith optional identity <code>hint</code> provided by the server or <code>null</code> 18321cb0ef41Sopenharmony_ciin case of TLS 1.3 where <code>hint</code> was removed. 18331cb0ef41Sopenharmony_ciIt will be necessary to provide a custom <code>tls.checkServerIdentity()</code> 18341cb0ef41Sopenharmony_cifor the connection as the default one will try to check host name/IP 18351cb0ef41Sopenharmony_ciof the server against the certificate but that's not applicable for PSK 18361cb0ef41Sopenharmony_cibecause there won't be a certificate present. 18371cb0ef41Sopenharmony_ciMore information can be found in the <a href="https://tools.ietf.org/html/rfc4279">RFC 4279</a>.</p> 18381cb0ef41Sopenharmony_ci</li> 18391cb0ef41Sopenharmony_ci<li> 18401cb0ef41Sopenharmony_ci<p><code>ALPNProtocols</code>: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string[]></a> | <a href="buffer.html#class-buffer" class="type"><Buffer[]></a> | <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/TypedArray" class="type"><TypedArray[]></a> | <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/DataView" class="type"><DataView[]></a> | <a href="buffer.html#class-buffer" class="type"><Buffer></a> | <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/TypedArray" class="type"><TypedArray></a> | <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/DataView" class="type"><DataView></a> 18411cb0ef41Sopenharmony_ciAn array of strings, <code>Buffer</code>s, <code>TypedArray</code>s, or <code>DataView</code>s, or a 18421cb0ef41Sopenharmony_cisingle <code>Buffer</code>, <code>TypedArray</code>, or <code>DataView</code> containing the supported ALPN 18431cb0ef41Sopenharmony_ciprotocols. <code>Buffer</code>s should have the format <code>[len][name][len][name]...</code> 18441cb0ef41Sopenharmony_cie.g. <code>'\x08http/1.1\x08http/1.0'</code>, where the <code>len</code> byte is the length of the 18451cb0ef41Sopenharmony_cinext protocol name. Passing an array is usually much simpler, e.g. 18461cb0ef41Sopenharmony_ci<code>['http/1.1', 'http/1.0']</code>. Protocols earlier in the list have higher 18471cb0ef41Sopenharmony_cipreference than those later.</p> 18481cb0ef41Sopenharmony_ci</li> 18491cb0ef41Sopenharmony_ci<li> 18501cb0ef41Sopenharmony_ci<p><code>servername</code>: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> Server name for the SNI (Server Name Indication) TLS 18511cb0ef41Sopenharmony_ciextension. It is the name of the host being connected to, and must be a host 18521cb0ef41Sopenharmony_ciname, and not an IP address. It can be used by a multi-homed server to 18531cb0ef41Sopenharmony_cichoose the correct certificate to present to the client, see the 18541cb0ef41Sopenharmony_ci<code>SNICallback</code> option to <a href="#tlscreateserveroptions-secureconnectionlistener"><code>tls.createServer()</code></a>.</p> 18551cb0ef41Sopenharmony_ci</li> 18561cb0ef41Sopenharmony_ci<li> 18571cb0ef41Sopenharmony_ci<p><code>checkServerIdentity(servername, cert)</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function" class="type"><Function></a> A callback function 18581cb0ef41Sopenharmony_cito be used (instead of the builtin <code>tls.checkServerIdentity()</code> function) 18591cb0ef41Sopenharmony_ciwhen checking the server's host name (or the provided <code>servername</code> when 18601cb0ef41Sopenharmony_ciexplicitly set) against the certificate. This should return an <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error" class="type"><Error></a> if 18611cb0ef41Sopenharmony_civerification fails. The method should return <code>undefined</code> if the <code>servername</code> 18621cb0ef41Sopenharmony_ciand <code>cert</code> are verified.</p> 18631cb0ef41Sopenharmony_ci</li> 18641cb0ef41Sopenharmony_ci<li> 18651cb0ef41Sopenharmony_ci<p><code>session</code> <a href="buffer.html#class-buffer" class="type"><Buffer></a> A <code>Buffer</code> instance, containing TLS session.</p> 18661cb0ef41Sopenharmony_ci</li> 18671cb0ef41Sopenharmony_ci<li> 18681cb0ef41Sopenharmony_ci<p><code>minDHSize</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><number></a> Minimum size of the DH parameter in bits to accept a 18691cb0ef41Sopenharmony_ciTLS connection. When a server offers a DH parameter with a size less 18701cb0ef41Sopenharmony_cithan <code>minDHSize</code>, the TLS connection is destroyed and an error is thrown. 18711cb0ef41Sopenharmony_ci<strong>Default:</strong> <code>1024</code>.</p> 18721cb0ef41Sopenharmony_ci</li> 18731cb0ef41Sopenharmony_ci<li> 18741cb0ef41Sopenharmony_ci<p><code>highWaterMark</code>: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><number></a> Consistent with the readable stream <code>highWaterMark</code> parameter. 18751cb0ef41Sopenharmony_ci<strong>Default:</strong> <code>16 * 1024</code>.</p> 18761cb0ef41Sopenharmony_ci</li> 18771cb0ef41Sopenharmony_ci<li> 18781cb0ef41Sopenharmony_ci<p><code>secureContext</code>: TLS context object created with 18791cb0ef41Sopenharmony_ci<a href="#tlscreatesecurecontextoptions"><code>tls.createSecureContext()</code></a>. If a <code>secureContext</code> is <em>not</em> provided, one 18801cb0ef41Sopenharmony_ciwill be created by passing the entire <code>options</code> object to 18811cb0ef41Sopenharmony_ci<code>tls.createSecureContext()</code>.</p> 18821cb0ef41Sopenharmony_ci</li> 18831cb0ef41Sopenharmony_ci<li> 18841cb0ef41Sopenharmony_ci<p><code>onread</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object" class="type"><Object></a> If the <code>socket</code> option is missing, incoming data is 18851cb0ef41Sopenharmony_cistored in a single <code>buffer</code> and passed to the supplied <code>callback</code> when 18861cb0ef41Sopenharmony_cidata arrives on the socket, otherwise the option is ignored. See the 18871cb0ef41Sopenharmony_ci<code>onread</code> option of <a href="net.html#class-netsocket"><code>net.Socket</code></a> for details.</p> 18881cb0ef41Sopenharmony_ci</li> 18891cb0ef41Sopenharmony_ci<li> 18901cb0ef41Sopenharmony_ci<p>...: <a href="#tlscreatesecurecontextoptions"><code>tls.createSecureContext()</code></a> options that are used if the 18911cb0ef41Sopenharmony_ci<code>secureContext</code> option is missing, otherwise they are ignored.</p> 18921cb0ef41Sopenharmony_ci</li> 18931cb0ef41Sopenharmony_ci<li> 18941cb0ef41Sopenharmony_ci<p>...: Any <a href="net.html#socketconnectoptions-connectlistener"><code>socket.connect()</code></a> option not already listed.</p> 18951cb0ef41Sopenharmony_ci</li> 18961cb0ef41Sopenharmony_ci</ul> 18971cb0ef41Sopenharmony_ci</li> 18981cb0ef41Sopenharmony_ci<li><code>callback</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function" class="type"><Function></a></li> 18991cb0ef41Sopenharmony_ci<li>Returns: <a href="tls.html#class-tlstlssocket" class="type"><tls.TLSSocket></a></li> 19001cb0ef41Sopenharmony_ci</ul> 19011cb0ef41Sopenharmony_ci<p>The <code>callback</code> function, if specified, will be added as a listener for the 19021cb0ef41Sopenharmony_ci<a href="#event-secureconnect"><code>'secureConnect'</code></a> event.</p> 19031cb0ef41Sopenharmony_ci<p><code>tls.connect()</code> returns a <a href="#class-tlstlssocket"><code>tls.TLSSocket</code></a> object.</p> 19041cb0ef41Sopenharmony_ci<p>Unlike the <code>https</code> API, <code>tls.connect()</code> does not enable the 19051cb0ef41Sopenharmony_ciSNI (Server Name Indication) extension by default, which may cause some 19061cb0ef41Sopenharmony_ciservers to return an incorrect certificate or reject the connection 19071cb0ef41Sopenharmony_cialtogether. To enable SNI, set the <code>servername</code> option in addition 19081cb0ef41Sopenharmony_cito <code>host</code>.</p> 19091cb0ef41Sopenharmony_ci<p>The following illustrates a client for the echo server example from 19101cb0ef41Sopenharmony_ci<a href="#tlscreateserveroptions-secureconnectionlistener"><code>tls.createServer()</code></a>:</p> 19111cb0ef41Sopenharmony_ci<pre><code class="language-js"><span class="hljs-comment">// Assumes an echo server that is listening on port 8000.</span> 19121cb0ef41Sopenharmony_ci<span class="hljs-keyword">const</span> tls = <span class="hljs-built_in">require</span>(<span class="hljs-string">'node:tls'</span>); 19131cb0ef41Sopenharmony_ci<span class="hljs-keyword">const</span> fs = <span class="hljs-built_in">require</span>(<span class="hljs-string">'node:fs'</span>); 19141cb0ef41Sopenharmony_ci 19151cb0ef41Sopenharmony_ci<span class="hljs-keyword">const</span> options = { 19161cb0ef41Sopenharmony_ci <span class="hljs-comment">// Necessary only if the server requires client certificate authentication.</span> 19171cb0ef41Sopenharmony_ci <span class="hljs-attr">key</span>: fs.<span class="hljs-title function_">readFileSync</span>(<span class="hljs-string">'client-key.pem'</span>), 19181cb0ef41Sopenharmony_ci <span class="hljs-attr">cert</span>: fs.<span class="hljs-title function_">readFileSync</span>(<span class="hljs-string">'client-cert.pem'</span>), 19191cb0ef41Sopenharmony_ci 19201cb0ef41Sopenharmony_ci <span class="hljs-comment">// Necessary only if the server uses a self-signed certificate.</span> 19211cb0ef41Sopenharmony_ci <span class="hljs-attr">ca</span>: [ fs.<span class="hljs-title function_">readFileSync</span>(<span class="hljs-string">'server-cert.pem'</span>) ], 19221cb0ef41Sopenharmony_ci 19231cb0ef41Sopenharmony_ci <span class="hljs-comment">// Necessary only if the server's cert isn't for "localhost".</span> 19241cb0ef41Sopenharmony_ci <span class="hljs-attr">checkServerIdentity</span>: <span class="hljs-function">() =></span> { <span class="hljs-keyword">return</span> <span class="hljs-literal">null</span>; }, 19251cb0ef41Sopenharmony_ci}; 19261cb0ef41Sopenharmony_ci 19271cb0ef41Sopenharmony_ci<span class="hljs-keyword">const</span> socket = tls.<span class="hljs-title function_">connect</span>(<span class="hljs-number">8000</span>, options, <span class="hljs-function">() =></span> { 19281cb0ef41Sopenharmony_ci <span class="hljs-variable language_">console</span>.<span class="hljs-title function_">log</span>(<span class="hljs-string">'client connected'</span>, 19291cb0ef41Sopenharmony_ci socket.<span class="hljs-property">authorized</span> ? <span class="hljs-string">'authorized'</span> : <span class="hljs-string">'unauthorized'</span>); 19301cb0ef41Sopenharmony_ci process.<span class="hljs-property">stdin</span>.<span class="hljs-title function_">pipe</span>(socket); 19311cb0ef41Sopenharmony_ci process.<span class="hljs-property">stdin</span>.<span class="hljs-title function_">resume</span>(); 19321cb0ef41Sopenharmony_ci}); 19331cb0ef41Sopenharmony_cisocket.<span class="hljs-title function_">setEncoding</span>(<span class="hljs-string">'utf8'</span>); 19341cb0ef41Sopenharmony_cisocket.<span class="hljs-title function_">on</span>(<span class="hljs-string">'data'</span>, <span class="hljs-function">(<span class="hljs-params">data</span>) =></span> { 19351cb0ef41Sopenharmony_ci <span class="hljs-variable language_">console</span>.<span class="hljs-title function_">log</span>(data); 19361cb0ef41Sopenharmony_ci}); 19371cb0ef41Sopenharmony_cisocket.<span class="hljs-title function_">on</span>(<span class="hljs-string">'end'</span>, <span class="hljs-function">() =></span> { 19381cb0ef41Sopenharmony_ci <span class="hljs-variable language_">console</span>.<span class="hljs-title function_">log</span>(<span class="hljs-string">'server ends connection'</span>); 19391cb0ef41Sopenharmony_ci});</code> <button class="copy-button">copy</button></pre> 19401cb0ef41Sopenharmony_ci</section><section><h3><code>tls.connect(path[, options][, callback])</code><span><a class="mark" href="#tlsconnectpath-options-callback" id="tlsconnectpath-options-callback">#</a></span><a aria-hidden="true" class="legacy" id="tls_tls_connect_path_options_callback"></a></h3> 19411cb0ef41Sopenharmony_ci<div class="api_metadata"> 19421cb0ef41Sopenharmony_ci<span>Added in: v0.11.3</span> 19431cb0ef41Sopenharmony_ci</div> 19441cb0ef41Sopenharmony_ci<ul> 19451cb0ef41Sopenharmony_ci<li><code>path</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> Default value for <code>options.path</code>.</li> 19461cb0ef41Sopenharmony_ci<li><code>options</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object" class="type"><Object></a> See <a href="#tlsconnectoptions-callback"><code>tls.connect()</code></a>.</li> 19471cb0ef41Sopenharmony_ci<li><code>callback</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function" class="type"><Function></a> See <a href="#tlsconnectoptions-callback"><code>tls.connect()</code></a>.</li> 19481cb0ef41Sopenharmony_ci<li>Returns: <a href="tls.html#class-tlstlssocket" class="type"><tls.TLSSocket></a></li> 19491cb0ef41Sopenharmony_ci</ul> 19501cb0ef41Sopenharmony_ci<p>Same as <a href="#tlsconnectoptions-callback"><code>tls.connect()</code></a> except that <code>path</code> can be provided 19511cb0ef41Sopenharmony_cias an argument instead of an option.</p> 19521cb0ef41Sopenharmony_ci<p>A path option, if specified, will take precedence over the path argument.</p> 19531cb0ef41Sopenharmony_ci</section><section><h3><code>tls.connect(port[, host][, options][, callback])</code><span><a class="mark" href="#tlsconnectport-host-options-callback" id="tlsconnectport-host-options-callback">#</a></span><a aria-hidden="true" class="legacy" id="tls_tls_connect_port_host_options_callback"></a></h3> 19541cb0ef41Sopenharmony_ci<div class="api_metadata"> 19551cb0ef41Sopenharmony_ci<span>Added in: v0.11.3</span> 19561cb0ef41Sopenharmony_ci</div> 19571cb0ef41Sopenharmony_ci<ul> 19581cb0ef41Sopenharmony_ci<li><code>port</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><number></a> Default value for <code>options.port</code>.</li> 19591cb0ef41Sopenharmony_ci<li><code>host</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> Default value for <code>options.host</code>.</li> 19601cb0ef41Sopenharmony_ci<li><code>options</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object" class="type"><Object></a> See <a href="#tlsconnectoptions-callback"><code>tls.connect()</code></a>.</li> 19611cb0ef41Sopenharmony_ci<li><code>callback</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function" class="type"><Function></a> See <a href="#tlsconnectoptions-callback"><code>tls.connect()</code></a>.</li> 19621cb0ef41Sopenharmony_ci<li>Returns: <a href="tls.html#class-tlstlssocket" class="type"><tls.TLSSocket></a></li> 19631cb0ef41Sopenharmony_ci</ul> 19641cb0ef41Sopenharmony_ci<p>Same as <a href="#tlsconnectoptions-callback"><code>tls.connect()</code></a> except that <code>port</code> and <code>host</code> can be provided 19651cb0ef41Sopenharmony_cias arguments instead of options.</p> 19661cb0ef41Sopenharmony_ci<p>A port or host option, if specified, will take precedence over any port or host 19671cb0ef41Sopenharmony_ciargument.</p> 19681cb0ef41Sopenharmony_ci</section><section><h3><code>tls.createSecureContext([options])</code><span><a class="mark" href="#tlscreatesecurecontextoptions" id="tlscreatesecurecontextoptions">#</a></span><a aria-hidden="true" class="legacy" id="tls_tls_createsecurecontext_options"></a></h3> 19691cb0ef41Sopenharmony_ci<div class="api_metadata"> 19701cb0ef41Sopenharmony_ci<details class="changelog"><summary>History</summary> 19711cb0ef41Sopenharmony_ci<table> 19721cb0ef41Sopenharmony_ci<tbody><tr><th>Version</th><th>Changes</th></tr> 19731cb0ef41Sopenharmony_ci<tr><td>v18.16.0</td> 19741cb0ef41Sopenharmony_ci<td><p>The <code>dhparam</code> option can now be set to <code>'auto'</code> to enable DHE with appropriate well-known parameters.</p></td></tr> 19751cb0ef41Sopenharmony_ci<tr><td>v12.12.0</td> 19761cb0ef41Sopenharmony_ci<td><p>Added <code>privateKeyIdentifier</code> and <code>privateKeyEngine</code> options to get private key from an OpenSSL engine.</p></td></tr> 19771cb0ef41Sopenharmony_ci<tr><td>v12.11.0</td> 19781cb0ef41Sopenharmony_ci<td><p>Added <code>sigalgs</code> option to override supported signature algorithms.</p></td></tr> 19791cb0ef41Sopenharmony_ci<tr><td>v12.0.0</td> 19801cb0ef41Sopenharmony_ci<td><p>TLSv1.3 support added.</p></td></tr> 19811cb0ef41Sopenharmony_ci<tr><td>v11.5.0</td> 19821cb0ef41Sopenharmony_ci<td><p>The <code>ca:</code> option now supports <code>BEGIN TRUSTED CERTIFICATE</code>.</p></td></tr> 19831cb0ef41Sopenharmony_ci<tr><td>v11.4.0, v10.16.0</td> 19841cb0ef41Sopenharmony_ci<td><p>The <code>minVersion</code> and <code>maxVersion</code> can be used to restrict the allowed TLS protocol versions.</p></td></tr> 19851cb0ef41Sopenharmony_ci<tr><td>v10.0.0</td> 19861cb0ef41Sopenharmony_ci<td><p>The <code>ecdhCurve</code> cannot be set to <code>false</code> anymore due to a change in OpenSSL.</p></td></tr> 19871cb0ef41Sopenharmony_ci<tr><td>v9.3.0</td> 19881cb0ef41Sopenharmony_ci<td><p>The <code>options</code> parameter can now include <code>clientCertEngine</code>.</p></td></tr> 19891cb0ef41Sopenharmony_ci<tr><td>v9.0.0</td> 19901cb0ef41Sopenharmony_ci<td><p>The <code>ecdhCurve</code> option can now be multiple <code>':'</code> separated curve names or <code>'auto'</code>.</p></td></tr> 19911cb0ef41Sopenharmony_ci<tr><td>v7.3.0</td> 19921cb0ef41Sopenharmony_ci<td><p>If the <code>key</code> option is an array, individual entries do not need a <code>passphrase</code> property anymore. <code>Array</code> entries can also just be <code>string</code>s or <code>Buffer</code>s now.</p></td></tr> 19931cb0ef41Sopenharmony_ci<tr><td>v5.2.0</td> 19941cb0ef41Sopenharmony_ci<td><p>The <code>ca</code> option can now be a single string containing multiple CA certificates.</p></td></tr> 19951cb0ef41Sopenharmony_ci<tr><td>v0.11.13</td> 19961cb0ef41Sopenharmony_ci<td><p><span>Added in: v0.11.13</span></p></td></tr> 19971cb0ef41Sopenharmony_ci</tbody></table> 19981cb0ef41Sopenharmony_ci</details> 19991cb0ef41Sopenharmony_ci</div> 20001cb0ef41Sopenharmony_ci<ul> 20011cb0ef41Sopenharmony_ci<li><code>options</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object" class="type"><Object></a> 20021cb0ef41Sopenharmony_ci<ul> 20031cb0ef41Sopenharmony_ci<li><code>ca</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> | <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string[]></a> | <a href="buffer.html#class-buffer" class="type"><Buffer></a> | <a href="buffer.html#class-buffer" class="type"><Buffer[]></a> Optionally override the trusted CA 20041cb0ef41Sopenharmony_cicertificates. Default is to trust the well-known CAs curated by Mozilla. 20051cb0ef41Sopenharmony_ciMozilla's CAs are completely replaced when CAs are explicitly specified 20061cb0ef41Sopenharmony_ciusing this option. The value can be a string or <code>Buffer</code>, or an <code>Array</code> of 20071cb0ef41Sopenharmony_cistrings and/or <code>Buffer</code>s. Any string or <code>Buffer</code> can contain multiple PEM 20081cb0ef41Sopenharmony_ciCAs concatenated together. The peer's certificate must be chainable to a CA 20091cb0ef41Sopenharmony_citrusted by the server for the connection to be authenticated. When using 20101cb0ef41Sopenharmony_cicertificates that are not chainable to a well-known CA, the certificate's CA 20111cb0ef41Sopenharmony_cimust be explicitly specified as a trusted or the connection will fail to 20121cb0ef41Sopenharmony_ciauthenticate. 20131cb0ef41Sopenharmony_ciIf the peer uses a certificate that doesn't match or chain to one of the 20141cb0ef41Sopenharmony_cidefault CAs, use the <code>ca</code> option to provide a CA certificate that the peer's 20151cb0ef41Sopenharmony_cicertificate can match or chain to. 20161cb0ef41Sopenharmony_ciFor self-signed certificates, the certificate is its own CA, and must be 20171cb0ef41Sopenharmony_ciprovided. 20181cb0ef41Sopenharmony_ciFor PEM encoded certificates, supported types are "TRUSTED CERTIFICATE", 20191cb0ef41Sopenharmony_ci"X509 CERTIFICATE", and "CERTIFICATE". 20201cb0ef41Sopenharmony_ciSee also <a href="#tlsrootcertificates"><code>tls.rootCertificates</code></a>.</li> 20211cb0ef41Sopenharmony_ci<li><code>cert</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> | <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string[]></a> | <a href="buffer.html#class-buffer" class="type"><Buffer></a> | <a href="buffer.html#class-buffer" class="type"><Buffer[]></a> Cert chains in PEM format. One 20221cb0ef41Sopenharmony_cicert chain should be provided per private key. Each cert chain should 20231cb0ef41Sopenharmony_ciconsist of the PEM formatted certificate for a provided private <code>key</code>, 20241cb0ef41Sopenharmony_cifollowed by the PEM formatted intermediate certificates (if any), in order, 20251cb0ef41Sopenharmony_ciand not including the root CA (the root CA must be pre-known to the peer, 20261cb0ef41Sopenharmony_cisee <code>ca</code>). When providing multiple cert chains, they do not have to be in 20271cb0ef41Sopenharmony_cithe same order as their private keys in <code>key</code>. If the intermediate 20281cb0ef41Sopenharmony_cicertificates are not provided, the peer will not be able to validate the 20291cb0ef41Sopenharmony_cicertificate, and the handshake will fail.</li> 20301cb0ef41Sopenharmony_ci<li><code>sigalgs</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> Colon-separated list of supported signature algorithms. 20311cb0ef41Sopenharmony_ciThe list can contain digest algorithms (<code>SHA256</code>, <code>MD5</code> etc.), public key 20321cb0ef41Sopenharmony_cialgorithms (<code>RSA-PSS</code>, <code>ECDSA</code> etc.), combination of both (e.g 20331cb0ef41Sopenharmony_ci'RSA+SHA384') or TLS v1.3 scheme names (e.g. <code>rsa_pss_pss_sha512</code>). 20341cb0ef41Sopenharmony_ciSee <a href="https://www.openssl.org/docs/man1.1.1/man3/SSL_CTX_set1_sigalgs_list.html">OpenSSL man pages</a> 20351cb0ef41Sopenharmony_cifor more info.</li> 20361cb0ef41Sopenharmony_ci<li><code>ciphers</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> Cipher suite specification, replacing the default. For 20371cb0ef41Sopenharmony_cimore information, see <a href="#modifying-the-default-tls-cipher-suite">Modifying the default TLS cipher suite</a>. Permitted 20381cb0ef41Sopenharmony_ciciphers can be obtained via <a href="#tlsgetciphers"><code>tls.getCiphers()</code></a>. Cipher names must be 20391cb0ef41Sopenharmony_ciuppercased in order for OpenSSL to accept them.</li> 20401cb0ef41Sopenharmony_ci<li><code>clientCertEngine</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> Name of an OpenSSL engine which can provide the 20411cb0ef41Sopenharmony_ciclient certificate.</li> 20421cb0ef41Sopenharmony_ci<li><code>crl</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> | <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string[]></a> | <a href="buffer.html#class-buffer" class="type"><Buffer></a> | <a href="buffer.html#class-buffer" class="type"><Buffer[]></a> PEM formatted CRLs (Certificate 20431cb0ef41Sopenharmony_ciRevocation Lists).</li> 20441cb0ef41Sopenharmony_ci<li><code>dhparam</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> | <a href="buffer.html#class-buffer" class="type"><Buffer></a> <code>'auto'</code> or custom Diffie-Hellman parameters, 20451cb0ef41Sopenharmony_cirequired for non-ECDHE <a href="#perfect-forward-secrecy">perfect forward secrecy</a>. If omitted or invalid, 20461cb0ef41Sopenharmony_cithe parameters are silently discarded and DHE ciphers will not be available. 20471cb0ef41Sopenharmony_ci<a href="https://en.wikipedia.org/wiki/Elliptic_curve_Diffie%E2%80%93Hellman">ECDHE</a>-based <a href="#perfect-forward-secrecy">perfect forward secrecy</a> will still be available.</li> 20481cb0ef41Sopenharmony_ci<li><code>ecdhCurve</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> A string describing a named curve or a colon separated 20491cb0ef41Sopenharmony_cilist of curve NIDs or names, for example <code>P-521:P-384:P-256</code>, to use for 20501cb0ef41Sopenharmony_ciECDH key agreement. Set to <code>auto</code> to select the 20511cb0ef41Sopenharmony_cicurve automatically. Use <a href="crypto.html#cryptogetcurves"><code>crypto.getCurves()</code></a> to obtain a list of 20521cb0ef41Sopenharmony_ciavailable curve names. On recent releases, <code>openssl ecparam -list_curves</code> 20531cb0ef41Sopenharmony_ciwill also display the name and description of each available elliptic curve. 20541cb0ef41Sopenharmony_ci<strong>Default:</strong> <a href="#tlsdefault_ecdh_curve"><code>tls.DEFAULT_ECDH_CURVE</code></a>.</li> 20551cb0ef41Sopenharmony_ci<li><code>honorCipherOrder</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type" class="type"><boolean></a> Attempt to use the server's cipher suite 20561cb0ef41Sopenharmony_cipreferences instead of the client's. When <code>true</code>, causes 20571cb0ef41Sopenharmony_ci<code>SSL_OP_CIPHER_SERVER_PREFERENCE</code> to be set in <code>secureOptions</code>, see 20581cb0ef41Sopenharmony_ci<a href="crypto.html#openssl-options">OpenSSL Options</a> for more information.</li> 20591cb0ef41Sopenharmony_ci<li><code>key</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> | <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string[]></a> | <a href="buffer.html#class-buffer" class="type"><Buffer></a> | <a href="buffer.html#class-buffer" class="type"><Buffer[]></a> | <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object" class="type"><Object[]></a> Private keys in PEM 20601cb0ef41Sopenharmony_ciformat. PEM allows the option of private keys being encrypted. Encrypted 20611cb0ef41Sopenharmony_cikeys will be decrypted with <code>options.passphrase</code>. Multiple keys using 20621cb0ef41Sopenharmony_cidifferent algorithms can be provided either as an array of unencrypted key 20631cb0ef41Sopenharmony_cistrings or buffers, or an array of objects in the form 20641cb0ef41Sopenharmony_ci<code>{pem: <string|buffer>[, passphrase: <string>]}</code>. The object form can only 20651cb0ef41Sopenharmony_cioccur in an array. <code>object.passphrase</code> is optional. Encrypted keys will be 20661cb0ef41Sopenharmony_cidecrypted with <code>object.passphrase</code> if provided, or <code>options.passphrase</code> if 20671cb0ef41Sopenharmony_ciit is not.</li> 20681cb0ef41Sopenharmony_ci<li><code>privateKeyEngine</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> Name of an OpenSSL engine to get private key 20691cb0ef41Sopenharmony_cifrom. Should be used together with <code>privateKeyIdentifier</code>.</li> 20701cb0ef41Sopenharmony_ci<li><code>privateKeyIdentifier</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> Identifier of a private key managed by 20711cb0ef41Sopenharmony_cian OpenSSL engine. Should be used together with <code>privateKeyEngine</code>. 20721cb0ef41Sopenharmony_ciShould not be set together with <code>key</code>, because both options define a 20731cb0ef41Sopenharmony_ciprivate key in different ways.</li> 20741cb0ef41Sopenharmony_ci<li><code>maxVersion</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> Optionally set the maximum TLS version to allow. One 20751cb0ef41Sopenharmony_ciof <code>'TLSv1.3'</code>, <code>'TLSv1.2'</code>, <code>'TLSv1.1'</code>, or <code>'TLSv1'</code>. Cannot be specified 20761cb0ef41Sopenharmony_cialong with the <code>secureProtocol</code> option; use one or the other. 20771cb0ef41Sopenharmony_ci<strong>Default:</strong> <a href="#tlsdefault_max_version"><code>tls.DEFAULT_MAX_VERSION</code></a>.</li> 20781cb0ef41Sopenharmony_ci<li><code>minVersion</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> Optionally set the minimum TLS version to allow. One 20791cb0ef41Sopenharmony_ciof <code>'TLSv1.3'</code>, <code>'TLSv1.2'</code>, <code>'TLSv1.1'</code>, or <code>'TLSv1'</code>. Cannot be specified 20801cb0ef41Sopenharmony_cialong with the <code>secureProtocol</code> option; use one or the other. Avoid 20811cb0ef41Sopenharmony_cisetting to less than TLSv1.2, but it may be required for 20821cb0ef41Sopenharmony_ciinteroperability. 20831cb0ef41Sopenharmony_ci<strong>Default:</strong> <a href="#tlsdefault_min_version"><code>tls.DEFAULT_MIN_VERSION</code></a>.</li> 20841cb0ef41Sopenharmony_ci<li><code>passphrase</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> Shared passphrase used for a single private key and/or 20851cb0ef41Sopenharmony_cia PFX.</li> 20861cb0ef41Sopenharmony_ci<li><code>pfx</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> | <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string[]></a> | <a href="buffer.html#class-buffer" class="type"><Buffer></a> | <a href="buffer.html#class-buffer" class="type"><Buffer[]></a> | <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object" class="type"><Object[]></a> PFX or PKCS12 encoded 20871cb0ef41Sopenharmony_ciprivate key and certificate chain. <code>pfx</code> is an alternative to providing 20881cb0ef41Sopenharmony_ci<code>key</code> and <code>cert</code> individually. PFX is usually encrypted, if it is, 20891cb0ef41Sopenharmony_ci<code>passphrase</code> will be used to decrypt it. Multiple PFX can be provided either 20901cb0ef41Sopenharmony_cias an array of unencrypted PFX buffers, or an array of objects in the form 20911cb0ef41Sopenharmony_ci<code>{buf: <string|buffer>[, passphrase: <string>]}</code>. The object form can only 20921cb0ef41Sopenharmony_cioccur in an array. <code>object.passphrase</code> is optional. Encrypted PFX will be 20931cb0ef41Sopenharmony_cidecrypted with <code>object.passphrase</code> if provided, or <code>options.passphrase</code> if 20941cb0ef41Sopenharmony_ciit is not.</li> 20951cb0ef41Sopenharmony_ci<li><code>secureOptions</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><number></a> Optionally affect the OpenSSL protocol behavior, 20961cb0ef41Sopenharmony_ciwhich is not usually necessary. This should be used carefully if at all! 20971cb0ef41Sopenharmony_ciValue is a numeric bitmask of the <code>SSL_OP_*</code> options from 20981cb0ef41Sopenharmony_ci<a href="crypto.html#openssl-options">OpenSSL Options</a>.</li> 20991cb0ef41Sopenharmony_ci<li><code>secureProtocol</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> Legacy mechanism to select the TLS protocol 21001cb0ef41Sopenharmony_civersion to use, it does not support independent control of the minimum and 21011cb0ef41Sopenharmony_cimaximum version, and does not support limiting the protocol to TLSv1.3. Use 21021cb0ef41Sopenharmony_ci<code>minVersion</code> and <code>maxVersion</code> instead. The possible values are listed as 21031cb0ef41Sopenharmony_ci<a href="https://www.openssl.org/docs/man1.1.1/man7/ssl.html#Dealing-with-Protocol-Methods">SSL_METHODS</a>, use the function names as strings. For example, 21041cb0ef41Sopenharmony_ciuse <code>'TLSv1_1_method'</code> to force TLS version 1.1, or <code>'TLS_method'</code> to allow 21051cb0ef41Sopenharmony_ciany TLS protocol version up to TLSv1.3. It is not recommended to use TLS 21061cb0ef41Sopenharmony_civersions less than 1.2, but it may be required for interoperability. 21071cb0ef41Sopenharmony_ci<strong>Default:</strong> none, see <code>minVersion</code>.</li> 21081cb0ef41Sopenharmony_ci<li><code>sessionIdContext</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> Opaque identifier used by servers to ensure 21091cb0ef41Sopenharmony_cisession state is not shared between applications. Unused by clients.</li> 21101cb0ef41Sopenharmony_ci<li><code>ticketKeys</code>: <a href="buffer.html#class-buffer" class="type"><Buffer></a> 48-bytes of cryptographically strong pseudorandom 21111cb0ef41Sopenharmony_cidata. See <a href="#session-resumption">Session Resumption</a> for more information.</li> 21121cb0ef41Sopenharmony_ci<li><code>sessionTimeout</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><number></a> The number of seconds after which a TLS session 21131cb0ef41Sopenharmony_cicreated by the server will no longer be resumable. See 21141cb0ef41Sopenharmony_ci<a href="#session-resumption">Session Resumption</a> for more information. <strong>Default:</strong> <code>300</code>.</li> 21151cb0ef41Sopenharmony_ci</ul> 21161cb0ef41Sopenharmony_ci</li> 21171cb0ef41Sopenharmony_ci</ul> 21181cb0ef41Sopenharmony_ci<p><a href="#tlscreateserveroptions-secureconnectionlistener"><code>tls.createServer()</code></a> sets the default value of the <code>honorCipherOrder</code> option 21191cb0ef41Sopenharmony_cito <code>true</code>, other APIs that create secure contexts leave it unset.</p> 21201cb0ef41Sopenharmony_ci<p><a href="#tlscreateserveroptions-secureconnectionlistener"><code>tls.createServer()</code></a> uses a 128 bit truncated SHA1 hash value generated 21211cb0ef41Sopenharmony_cifrom <code>process.argv</code> as the default value of the <code>sessionIdContext</code> option, other 21221cb0ef41Sopenharmony_ciAPIs that create secure contexts have no default value.</p> 21231cb0ef41Sopenharmony_ci<p>The <code>tls.createSecureContext()</code> method creates a <code>SecureContext</code> object. It is 21241cb0ef41Sopenharmony_ciusable as an argument to several <code>tls</code> APIs, such as <a href="#serveraddcontexthostname-context"><code>server.addContext()</code></a>, 21251cb0ef41Sopenharmony_cibut has no public methods. The <a href="#class-tlsserver"><code>tls.Server</code></a> constructor and the 21261cb0ef41Sopenharmony_ci<a href="#tlscreateserveroptions-secureconnectionlistener"><code>tls.createServer()</code></a> method do not support the <code>secureContext</code> option.</p> 21271cb0ef41Sopenharmony_ci<p>A key is <em>required</em> for ciphers that use certificates. Either <code>key</code> or 21281cb0ef41Sopenharmony_ci<code>pfx</code> can be used to provide it.</p> 21291cb0ef41Sopenharmony_ci<p>If the <code>ca</code> option is not given, then Node.js will default to using 21301cb0ef41Sopenharmony_ci<a href="https://hg.mozilla.org/mozilla-central/raw-file/tip/security/nss/lib/ckfw/builtins/certdata.txt">Mozilla's publicly trusted list of CAs</a>.</p> 21311cb0ef41Sopenharmony_ci<p>Custom DHE parameters are discouraged in favor of the new <code>dhparam: 'auto'</code> 21321cb0ef41Sopenharmony_cioption. When set to <code>'auto'</code>, well-known DHE parameters of sufficient strength 21331cb0ef41Sopenharmony_ciwill be selected automatically. Otherwise, if necessary, <code>openssl dhparam</code> can 21341cb0ef41Sopenharmony_cibe used to create custom parameters. The key length must be greater than or 21351cb0ef41Sopenharmony_ciequal to 1024 bits or else an error will be thrown. Although 1024 bits is 21361cb0ef41Sopenharmony_cipermissible, use 2048 bits or larger for stronger security.</p> 21371cb0ef41Sopenharmony_ci</section><section><h3><code>tls.createSecurePair([context][, isServer][, requestCert][, rejectUnauthorized][, options])</code><span><a class="mark" href="#tlscreatesecurepaircontext-isserver-requestcert-rejectunauthorized-options" id="tlscreatesecurepaircontext-isserver-requestcert-rejectunauthorized-options">#</a></span><a aria-hidden="true" class="legacy" id="tls_tls_createsecurepair_context_isserver_requestcert_rejectunauthorized_options"></a></h3> 21381cb0ef41Sopenharmony_ci<div class="api_metadata"> 21391cb0ef41Sopenharmony_ci<details class="changelog"><summary>History</summary> 21401cb0ef41Sopenharmony_ci<table> 21411cb0ef41Sopenharmony_ci<tbody><tr><th>Version</th><th>Changes</th></tr> 21421cb0ef41Sopenharmony_ci<tr><td>v5.0.0</td> 21431cb0ef41Sopenharmony_ci<td><p>ALPN options are supported now.</p></td></tr> 21441cb0ef41Sopenharmony_ci<tr><td>v0.11.3</td> 21451cb0ef41Sopenharmony_ci<td><p><span>Deprecated since: v0.11.3</span></p></td></tr> 21461cb0ef41Sopenharmony_ci<tr><td>v0.3.2</td> 21471cb0ef41Sopenharmony_ci<td><p><span>Added in: v0.3.2</span></p></td></tr> 21481cb0ef41Sopenharmony_ci</tbody></table> 21491cb0ef41Sopenharmony_ci</details> 21501cb0ef41Sopenharmony_ci</div> 21511cb0ef41Sopenharmony_ci<p></p><div class="api_stability api_stability_0"><a href="documentation.html#stability-index">Stability: 0</a> - Deprecated: Use <a href="#class-tlstlssocket"><code>tls.TLSSocket</code></a> instead.</div><p></p> 21521cb0ef41Sopenharmony_ci<ul> 21531cb0ef41Sopenharmony_ci<li><code>context</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object" class="type"><Object></a> A secure context object as returned by 21541cb0ef41Sopenharmony_ci<code>tls.createSecureContext()</code></li> 21551cb0ef41Sopenharmony_ci<li><code>isServer</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type" class="type"><boolean></a> <code>true</code> to specify that this TLS connection should be 21561cb0ef41Sopenharmony_ciopened as a server.</li> 21571cb0ef41Sopenharmony_ci<li><code>requestCert</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type" class="type"><boolean></a> <code>true</code> to specify whether a server should request a 21581cb0ef41Sopenharmony_cicertificate from a connecting client. Only applies when <code>isServer</code> is <code>true</code>.</li> 21591cb0ef41Sopenharmony_ci<li><code>rejectUnauthorized</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type" class="type"><boolean></a> If not <code>false</code> a server automatically reject 21601cb0ef41Sopenharmony_ciclients with invalid certificates. Only applies when <code>isServer</code> is <code>true</code>.</li> 21611cb0ef41Sopenharmony_ci<li><code>options</code> 21621cb0ef41Sopenharmony_ci<ul> 21631cb0ef41Sopenharmony_ci<li><code>enableTrace</code>: See <a href="#tlscreateserveroptions-secureconnectionlistener"><code>tls.createServer()</code></a></li> 21641cb0ef41Sopenharmony_ci<li><code>secureContext</code>: A TLS context object from <a href="#tlscreatesecurecontextoptions"><code>tls.createSecureContext()</code></a></li> 21651cb0ef41Sopenharmony_ci<li><code>isServer</code>: If <code>true</code> the TLS socket will be instantiated in server-mode. 21661cb0ef41Sopenharmony_ci<strong>Default:</strong> <code>false</code>.</li> 21671cb0ef41Sopenharmony_ci<li><code>server</code> <a href="net.html#class-netserver" class="type"><net.Server></a> A <a href="net.html#class-netserver"><code>net.Server</code></a> instance</li> 21681cb0ef41Sopenharmony_ci<li><code>requestCert</code>: See <a href="#tlscreateserveroptions-secureconnectionlistener"><code>tls.createServer()</code></a></li> 21691cb0ef41Sopenharmony_ci<li><code>rejectUnauthorized</code>: See <a href="#tlscreateserveroptions-secureconnectionlistener"><code>tls.createServer()</code></a></li> 21701cb0ef41Sopenharmony_ci<li><code>ALPNProtocols</code>: See <a href="#tlscreateserveroptions-secureconnectionlistener"><code>tls.createServer()</code></a></li> 21711cb0ef41Sopenharmony_ci<li><code>SNICallback</code>: See <a href="#tlscreateserveroptions-secureconnectionlistener"><code>tls.createServer()</code></a></li> 21721cb0ef41Sopenharmony_ci<li><code>session</code> <a href="buffer.html#class-buffer" class="type"><Buffer></a> A <code>Buffer</code> instance containing a TLS session.</li> 21731cb0ef41Sopenharmony_ci<li><code>requestOCSP</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type" class="type"><boolean></a> If <code>true</code>, specifies that the OCSP status request 21741cb0ef41Sopenharmony_ciextension will be added to the client hello and an <code>'OCSPResponse'</code> event 21751cb0ef41Sopenharmony_ciwill be emitted on the socket before establishing a secure communication.</li> 21761cb0ef41Sopenharmony_ci</ul> 21771cb0ef41Sopenharmony_ci</li> 21781cb0ef41Sopenharmony_ci</ul> 21791cb0ef41Sopenharmony_ci<p>Creates a new secure pair object with two streams, one of which reads and writes 21801cb0ef41Sopenharmony_cithe encrypted data and the other of which reads and writes the cleartext data. 21811cb0ef41Sopenharmony_ciGenerally, the encrypted stream is piped to/from an incoming encrypted data 21821cb0ef41Sopenharmony_cistream and the cleartext one is used as a replacement for the initial encrypted 21831cb0ef41Sopenharmony_cistream.</p> 21841cb0ef41Sopenharmony_ci<p><code>tls.createSecurePair()</code> returns a <code>tls.SecurePair</code> object with <code>cleartext</code> and 21851cb0ef41Sopenharmony_ci<code>encrypted</code> stream properties.</p> 21861cb0ef41Sopenharmony_ci<p>Using <code>cleartext</code> has the same API as <a href="#class-tlstlssocket"><code>tls.TLSSocket</code></a>.</p> 21871cb0ef41Sopenharmony_ci<p>The <code>tls.createSecurePair()</code> method is now deprecated in favor of 21881cb0ef41Sopenharmony_ci<code>tls.TLSSocket()</code>. For example, the code:</p> 21891cb0ef41Sopenharmony_ci<pre><code class="language-js">pair = tls.<span class="hljs-title function_">createSecurePair</span>(<span class="hljs-comment">/* ... */</span>); 21901cb0ef41Sopenharmony_cipair.<span class="hljs-property">encrypted</span>.<span class="hljs-title function_">pipe</span>(socket); 21911cb0ef41Sopenharmony_cisocket.<span class="hljs-title function_">pipe</span>(pair.<span class="hljs-property">encrypted</span>);</code> <button class="copy-button">copy</button></pre> 21921cb0ef41Sopenharmony_ci<p>can be replaced by:</p> 21931cb0ef41Sopenharmony_ci<pre><code class="language-js">secureSocket = tls.<span class="hljs-title class_">TLSSocket</span>(socket, options);</code> <button class="copy-button">copy</button></pre> 21941cb0ef41Sopenharmony_ci<p>where <code>secureSocket</code> has the same API as <code>pair.cleartext</code>.</p> 21951cb0ef41Sopenharmony_ci</section><section><h3><code>tls.createServer([options][, secureConnectionListener])</code><span><a class="mark" href="#tlscreateserveroptions-secureconnectionlistener" id="tlscreateserveroptions-secureconnectionlistener">#</a></span><a aria-hidden="true" class="legacy" id="tls_tls_createserver_options_secureconnectionlistener"></a></h3> 21961cb0ef41Sopenharmony_ci<div class="api_metadata"> 21971cb0ef41Sopenharmony_ci<details class="changelog"><summary>History</summary> 21981cb0ef41Sopenharmony_ci<table> 21991cb0ef41Sopenharmony_ci<tbody><tr><th>Version</th><th>Changes</th></tr> 22001cb0ef41Sopenharmony_ci<tr><td>v18.19.0</td> 22011cb0ef41Sopenharmony_ci<td><p>The <code>options</code> parameter can now include <code>ALPNCallback</code>.</p></td></tr> 22021cb0ef41Sopenharmony_ci<tr><td>v12.3.0</td> 22031cb0ef41Sopenharmony_ci<td><p>The <code>options</code> parameter now supports <code>net.createServer()</code> options.</p></td></tr> 22041cb0ef41Sopenharmony_ci<tr><td>v9.3.0</td> 22051cb0ef41Sopenharmony_ci<td><p>The <code>options</code> parameter can now include <code>clientCertEngine</code>.</p></td></tr> 22061cb0ef41Sopenharmony_ci<tr><td>v8.0.0</td> 22071cb0ef41Sopenharmony_ci<td><p>The <code>ALPNProtocols</code> option can be a <code>TypedArray</code> or <code>DataView</code> now.</p></td></tr> 22081cb0ef41Sopenharmony_ci<tr><td>v5.0.0</td> 22091cb0ef41Sopenharmony_ci<td><p>ALPN options are supported now.</p></td></tr> 22101cb0ef41Sopenharmony_ci<tr><td>v0.3.2</td> 22111cb0ef41Sopenharmony_ci<td><p><span>Added in: v0.3.2</span></p></td></tr> 22121cb0ef41Sopenharmony_ci</tbody></table> 22131cb0ef41Sopenharmony_ci</details> 22141cb0ef41Sopenharmony_ci</div> 22151cb0ef41Sopenharmony_ci<ul> 22161cb0ef41Sopenharmony_ci<li><code>options</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object" class="type"><Object></a> 22171cb0ef41Sopenharmony_ci<ul> 22181cb0ef41Sopenharmony_ci<li> 22191cb0ef41Sopenharmony_ci<p><code>ALPNProtocols</code>: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string[]></a> | <a href="buffer.html#class-buffer" class="type"><Buffer[]></a> | <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/TypedArray" class="type"><TypedArray[]></a> | <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/DataView" class="type"><DataView[]></a> | <a href="buffer.html#class-buffer" class="type"><Buffer></a> | <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/TypedArray" class="type"><TypedArray></a> | <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/DataView" class="type"><DataView></a> 22201cb0ef41Sopenharmony_ciAn array of strings, <code>Buffer</code>s, <code>TypedArray</code>s, or <code>DataView</code>s, or a single 22211cb0ef41Sopenharmony_ci<code>Buffer</code>, <code>TypedArray</code>, or <code>DataView</code> containing the supported ALPN 22221cb0ef41Sopenharmony_ciprotocols. <code>Buffer</code>s should have the format <code>[len][name][len][name]...</code> 22231cb0ef41Sopenharmony_cie.g. <code>0x05hello0x05world</code>, where the first byte is the length of the next 22241cb0ef41Sopenharmony_ciprotocol name. Passing an array is usually much simpler, e.g. 22251cb0ef41Sopenharmony_ci<code>['hello', 'world']</code>. (Protocols should be ordered by their priority.)</p> 22261cb0ef41Sopenharmony_ci</li> 22271cb0ef41Sopenharmony_ci<li> 22281cb0ef41Sopenharmony_ci<p><code>ALPNCallback</code>: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function" class="type"><Function></a> If set, this will be called when a 22291cb0ef41Sopenharmony_ciclient opens a connection using the ALPN extension. One argument will 22301cb0ef41Sopenharmony_cibe passed to the callback: an object containing <code>servername</code> and 22311cb0ef41Sopenharmony_ci<code>protocols</code> fields, respectively containing the server name from 22321cb0ef41Sopenharmony_cithe SNI extension (if any) and an array of ALPN protocol name strings. The 22331cb0ef41Sopenharmony_cicallback must return either one of the strings listed in 22341cb0ef41Sopenharmony_ci<code>protocols</code>, which will be returned to the client as the selected 22351cb0ef41Sopenharmony_ciALPN protocol, or <code>undefined</code>, to reject the connection with a fatal alert. 22361cb0ef41Sopenharmony_ciIf a string is returned that does not match one of the client's ALPN 22371cb0ef41Sopenharmony_ciprotocols, an error will be thrown. This option cannot be used with the 22381cb0ef41Sopenharmony_ci<code>ALPNProtocols</code> option, and setting both options will throw an error.</p> 22391cb0ef41Sopenharmony_ci</li> 22401cb0ef41Sopenharmony_ci<li> 22411cb0ef41Sopenharmony_ci<p><code>clientCertEngine</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> Name of an OpenSSL engine which can provide the 22421cb0ef41Sopenharmony_ciclient certificate.</p> 22431cb0ef41Sopenharmony_ci</li> 22441cb0ef41Sopenharmony_ci<li> 22451cb0ef41Sopenharmony_ci<p><code>enableTrace</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type" class="type"><boolean></a> If <code>true</code>, <a href="#tlssocketenabletrace"><code>tls.TLSSocket.enableTrace()</code></a> will be 22461cb0ef41Sopenharmony_cicalled on new connections. Tracing can be enabled after the secure 22471cb0ef41Sopenharmony_ciconnection is established, but this option must be used to trace the secure 22481cb0ef41Sopenharmony_ciconnection setup. <strong>Default:</strong> <code>false</code>.</p> 22491cb0ef41Sopenharmony_ci</li> 22501cb0ef41Sopenharmony_ci<li> 22511cb0ef41Sopenharmony_ci<p><code>handshakeTimeout</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><number></a> Abort the connection if the SSL/TLS handshake 22521cb0ef41Sopenharmony_cidoes not finish in the specified number of milliseconds. 22531cb0ef41Sopenharmony_ciA <code>'tlsClientError'</code> is emitted on the <code>tls.Server</code> object whenever 22541cb0ef41Sopenharmony_cia handshake times out. <strong>Default:</strong> <code>120000</code> (120 seconds).</p> 22551cb0ef41Sopenharmony_ci</li> 22561cb0ef41Sopenharmony_ci<li> 22571cb0ef41Sopenharmony_ci<p><code>rejectUnauthorized</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type" class="type"><boolean></a> If not <code>false</code> the server will reject any 22581cb0ef41Sopenharmony_ciconnection which is not authorized with the list of supplied CAs. This 22591cb0ef41Sopenharmony_cioption only has an effect if <code>requestCert</code> is <code>true</code>. <strong>Default:</strong> <code>true</code>.</p> 22601cb0ef41Sopenharmony_ci</li> 22611cb0ef41Sopenharmony_ci<li> 22621cb0ef41Sopenharmony_ci<p><code>requestCert</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type" class="type"><boolean></a> If <code>true</code> the server will request a certificate from 22631cb0ef41Sopenharmony_ciclients that connect and attempt to verify that certificate. <strong>Default:</strong> 22641cb0ef41Sopenharmony_ci<code>false</code>.</p> 22651cb0ef41Sopenharmony_ci</li> 22661cb0ef41Sopenharmony_ci<li> 22671cb0ef41Sopenharmony_ci<p><code>sessionTimeout</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><number></a> The number of seconds after which a TLS session 22681cb0ef41Sopenharmony_cicreated by the server will no longer be resumable. See 22691cb0ef41Sopenharmony_ci<a href="#session-resumption">Session Resumption</a> for more information. <strong>Default:</strong> <code>300</code>.</p> 22701cb0ef41Sopenharmony_ci</li> 22711cb0ef41Sopenharmony_ci<li> 22721cb0ef41Sopenharmony_ci<p><code>SNICallback(servername, callback)</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function" class="type"><Function></a> A function that will be 22731cb0ef41Sopenharmony_cicalled if the client supports SNI TLS extension. Two arguments will be 22741cb0ef41Sopenharmony_cipassed when called: <code>servername</code> and <code>callback</code>. <code>callback</code> is an 22751cb0ef41Sopenharmony_cierror-first callback that takes two optional arguments: <code>error</code> and <code>ctx</code>. 22761cb0ef41Sopenharmony_ci<code>ctx</code>, if provided, is a <code>SecureContext</code> instance. 22771cb0ef41Sopenharmony_ci<a href="#tlscreatesecurecontextoptions"><code>tls.createSecureContext()</code></a> can be used to get a proper <code>SecureContext</code>. 22781cb0ef41Sopenharmony_ciIf <code>callback</code> is called with a falsy <code>ctx</code> argument, the default secure 22791cb0ef41Sopenharmony_cicontext of the server will be used. If <code>SNICallback</code> wasn't provided the 22801cb0ef41Sopenharmony_cidefault callback with high-level API will be used (see below).</p> 22811cb0ef41Sopenharmony_ci</li> 22821cb0ef41Sopenharmony_ci<li> 22831cb0ef41Sopenharmony_ci<p><code>ticketKeys</code>: <a href="buffer.html#class-buffer" class="type"><Buffer></a> 48-bytes of cryptographically strong pseudorandom 22841cb0ef41Sopenharmony_cidata. See <a href="#session-resumption">Session Resumption</a> for more information.</p> 22851cb0ef41Sopenharmony_ci</li> 22861cb0ef41Sopenharmony_ci<li> 22871cb0ef41Sopenharmony_ci<p><code>pskCallback</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function" class="type"><Function></a></p> 22881cb0ef41Sopenharmony_ci<ul> 22891cb0ef41Sopenharmony_ci<li>socket: <a href="tls.html#class-tlstlssocket" class="type"><tls.TLSSocket></a> the server <a href="#class-tlstlssocket"><code>tls.TLSSocket</code></a> instance for 22901cb0ef41Sopenharmony_cithis connection.</li> 22911cb0ef41Sopenharmony_ci<li>identity: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> identity parameter sent from the client.</li> 22921cb0ef41Sopenharmony_ci<li>Returns: <a href="buffer.html#class-buffer" class="type"><Buffer></a> | <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/TypedArray" class="type"><TypedArray></a> | <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/DataView" class="type"><DataView></a> pre-shared key that must either be 22931cb0ef41Sopenharmony_cia buffer or <code>null</code> to stop the negotiation process. Returned PSK must be 22941cb0ef41Sopenharmony_cicompatible with the selected cipher's digest.</li> 22951cb0ef41Sopenharmony_ci</ul> 22961cb0ef41Sopenharmony_ci<p>When negotiating TLS-PSK (pre-shared keys), this function is called 22971cb0ef41Sopenharmony_ciwith the identity provided by the client. 22981cb0ef41Sopenharmony_ciIf the return value is <code>null</code> the negotiation process will stop and an 22991cb0ef41Sopenharmony_ci"unknown_psk_identity" alert message will be sent to the other party. 23001cb0ef41Sopenharmony_ciIf the server wishes to hide the fact that the PSK identity was not known, 23011cb0ef41Sopenharmony_cithe callback must provide some random data as <code>psk</code> to make the connection 23021cb0ef41Sopenharmony_cifail with "decrypt_error" before negotiation is finished. 23031cb0ef41Sopenharmony_ciPSK ciphers are disabled by default, and using TLS-PSK thus 23041cb0ef41Sopenharmony_cirequires explicitly specifying a cipher suite with the <code>ciphers</code> option. 23051cb0ef41Sopenharmony_ciMore information can be found in the <a href="https://tools.ietf.org/html/rfc4279">RFC 4279</a>.</p> 23061cb0ef41Sopenharmony_ci</li> 23071cb0ef41Sopenharmony_ci<li> 23081cb0ef41Sopenharmony_ci<p><code>pskIdentityHint</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> optional hint to send to a client to help 23091cb0ef41Sopenharmony_ciwith selecting the identity during TLS-PSK negotiation. Will be ignored 23101cb0ef41Sopenharmony_ciin TLS 1.3. Upon failing to set pskIdentityHint <code>'tlsClientError'</code> will be 23111cb0ef41Sopenharmony_ciemitted with <code>'ERR_TLS_PSK_SET_IDENTIY_HINT_FAILED'</code> code.</p> 23121cb0ef41Sopenharmony_ci</li> 23131cb0ef41Sopenharmony_ci<li> 23141cb0ef41Sopenharmony_ci<p>...: Any <a href="#tlscreatesecurecontextoptions"><code>tls.createSecureContext()</code></a> option can be provided. For 23151cb0ef41Sopenharmony_ciservers, the identity options (<code>pfx</code>, <code>key</code>/<code>cert</code>, or <code>pskCallback</code>) 23161cb0ef41Sopenharmony_ciare usually required.</p> 23171cb0ef41Sopenharmony_ci</li> 23181cb0ef41Sopenharmony_ci<li> 23191cb0ef41Sopenharmony_ci<p>...: Any <a href="net.html#netcreateserveroptions-connectionlistener"><code>net.createServer()</code></a> option can be provided.</p> 23201cb0ef41Sopenharmony_ci</li> 23211cb0ef41Sopenharmony_ci</ul> 23221cb0ef41Sopenharmony_ci</li> 23231cb0ef41Sopenharmony_ci<li><code>secureConnectionListener</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function" class="type"><Function></a></li> 23241cb0ef41Sopenharmony_ci<li>Returns: <a href="tls.html#class-tlsserver" class="type"><tls.Server></a></li> 23251cb0ef41Sopenharmony_ci</ul> 23261cb0ef41Sopenharmony_ci<p>Creates a new <a href="#class-tlsserver"><code>tls.Server</code></a>. The <code>secureConnectionListener</code>, if provided, is 23271cb0ef41Sopenharmony_ciautomatically set as a listener for the <a href="#event-secureconnection"><code>'secureConnection'</code></a> event.</p> 23281cb0ef41Sopenharmony_ci<p>The <code>ticketKeys</code> options is automatically shared between <code>node:cluster</code> module 23291cb0ef41Sopenharmony_ciworkers.</p> 23301cb0ef41Sopenharmony_ci<p>The following illustrates a simple echo server:</p> 23311cb0ef41Sopenharmony_ci<pre><code class="language-js"><span class="hljs-keyword">const</span> tls = <span class="hljs-built_in">require</span>(<span class="hljs-string">'node:tls'</span>); 23321cb0ef41Sopenharmony_ci<span class="hljs-keyword">const</span> fs = <span class="hljs-built_in">require</span>(<span class="hljs-string">'node:fs'</span>); 23331cb0ef41Sopenharmony_ci 23341cb0ef41Sopenharmony_ci<span class="hljs-keyword">const</span> options = { 23351cb0ef41Sopenharmony_ci <span class="hljs-attr">key</span>: fs.<span class="hljs-title function_">readFileSync</span>(<span class="hljs-string">'server-key.pem'</span>), 23361cb0ef41Sopenharmony_ci <span class="hljs-attr">cert</span>: fs.<span class="hljs-title function_">readFileSync</span>(<span class="hljs-string">'server-cert.pem'</span>), 23371cb0ef41Sopenharmony_ci 23381cb0ef41Sopenharmony_ci <span class="hljs-comment">// This is necessary only if using client certificate authentication.</span> 23391cb0ef41Sopenharmony_ci <span class="hljs-attr">requestCert</span>: <span class="hljs-literal">true</span>, 23401cb0ef41Sopenharmony_ci 23411cb0ef41Sopenharmony_ci <span class="hljs-comment">// This is necessary only if the client uses a self-signed certificate.</span> 23421cb0ef41Sopenharmony_ci <span class="hljs-attr">ca</span>: [ fs.<span class="hljs-title function_">readFileSync</span>(<span class="hljs-string">'client-cert.pem'</span>) ], 23431cb0ef41Sopenharmony_ci}; 23441cb0ef41Sopenharmony_ci 23451cb0ef41Sopenharmony_ci<span class="hljs-keyword">const</span> server = tls.<span class="hljs-title function_">createServer</span>(options, <span class="hljs-function">(<span class="hljs-params">socket</span>) =></span> { 23461cb0ef41Sopenharmony_ci <span class="hljs-variable language_">console</span>.<span class="hljs-title function_">log</span>(<span class="hljs-string">'server connected'</span>, 23471cb0ef41Sopenharmony_ci socket.<span class="hljs-property">authorized</span> ? <span class="hljs-string">'authorized'</span> : <span class="hljs-string">'unauthorized'</span>); 23481cb0ef41Sopenharmony_ci socket.<span class="hljs-title function_">write</span>(<span class="hljs-string">'welcome!\n'</span>); 23491cb0ef41Sopenharmony_ci socket.<span class="hljs-title function_">setEncoding</span>(<span class="hljs-string">'utf8'</span>); 23501cb0ef41Sopenharmony_ci socket.<span class="hljs-title function_">pipe</span>(socket); 23511cb0ef41Sopenharmony_ci}); 23521cb0ef41Sopenharmony_ciserver.<span class="hljs-title function_">listen</span>(<span class="hljs-number">8000</span>, <span class="hljs-function">() =></span> { 23531cb0ef41Sopenharmony_ci <span class="hljs-variable language_">console</span>.<span class="hljs-title function_">log</span>(<span class="hljs-string">'server bound'</span>); 23541cb0ef41Sopenharmony_ci});</code> <button class="copy-button">copy</button></pre> 23551cb0ef41Sopenharmony_ci<p>The server can be tested by connecting to it using the example client from 23561cb0ef41Sopenharmony_ci<a href="#tlsconnectoptions-callback"><code>tls.connect()</code></a>.</p> 23571cb0ef41Sopenharmony_ci</section><section><h3><code>tls.getCiphers()</code><span><a class="mark" href="#tlsgetciphers" id="tlsgetciphers">#</a></span><a aria-hidden="true" class="legacy" id="tls_tls_getciphers"></a></h3> 23581cb0ef41Sopenharmony_ci<div class="api_metadata"> 23591cb0ef41Sopenharmony_ci<span>Added in: v0.10.2</span> 23601cb0ef41Sopenharmony_ci</div> 23611cb0ef41Sopenharmony_ci<ul> 23621cb0ef41Sopenharmony_ci<li>Returns: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string[]></a></li> 23631cb0ef41Sopenharmony_ci</ul> 23641cb0ef41Sopenharmony_ci<p>Returns an array with the names of the supported TLS ciphers. The names are 23651cb0ef41Sopenharmony_cilower-case for historical reasons, but must be uppercased to be used in 23661cb0ef41Sopenharmony_cithe <code>ciphers</code> option of <a href="#tlscreatesecurecontextoptions"><code>tls.createSecureContext()</code></a>.</p> 23671cb0ef41Sopenharmony_ci<p>Not all supported ciphers are enabled by default. See 23681cb0ef41Sopenharmony_ci<a href="#modifying-the-default-tls-cipher-suite">Modifying the default TLS cipher suite</a>.</p> 23691cb0ef41Sopenharmony_ci<p>Cipher names that start with <code>'tls_'</code> are for TLSv1.3, all the others are for 23701cb0ef41Sopenharmony_ciTLSv1.2 and below.</p> 23711cb0ef41Sopenharmony_ci<pre><code class="language-js"><span class="hljs-variable language_">console</span>.<span class="hljs-title function_">log</span>(tls.<span class="hljs-title function_">getCiphers</span>()); <span class="hljs-comment">// ['aes128-gcm-sha256', 'aes128-sha', ...]</span></code> <button class="copy-button">copy</button></pre> 23721cb0ef41Sopenharmony_ci</section><section><h3><code>tls.rootCertificates</code><span><a class="mark" href="#tlsrootcertificates" id="tlsrootcertificates">#</a></span><a aria-hidden="true" class="legacy" id="tls_tls_rootcertificates"></a></h3> 23731cb0ef41Sopenharmony_ci<div class="api_metadata"> 23741cb0ef41Sopenharmony_ci<span>Added in: v12.3.0</span> 23751cb0ef41Sopenharmony_ci</div> 23761cb0ef41Sopenharmony_ci<ul> 23771cb0ef41Sopenharmony_ci<li><a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string[]></a></li> 23781cb0ef41Sopenharmony_ci</ul> 23791cb0ef41Sopenharmony_ci<p>An immutable array of strings representing the root certificates (in PEM format) 23801cb0ef41Sopenharmony_cifrom the bundled Mozilla CA store as supplied by the current Node.js version.</p> 23811cb0ef41Sopenharmony_ci<p>The bundled CA store, as supplied by Node.js, is a snapshot of Mozilla CA store 23821cb0ef41Sopenharmony_cithat is fixed at release time. It is identical on all supported platforms.</p> 23831cb0ef41Sopenharmony_ci</section><section><h3><code>tls.DEFAULT_ECDH_CURVE</code><span><a class="mark" href="#tlsdefault_ecdh_curve" id="tlsdefault_ecdh_curve">#</a></span><a aria-hidden="true" class="legacy" id="tls_tls_default_ecdh_curve"></a></h3> 23841cb0ef41Sopenharmony_ci<div class="api_metadata"> 23851cb0ef41Sopenharmony_ci<details class="changelog"><summary>History</summary> 23861cb0ef41Sopenharmony_ci<table> 23871cb0ef41Sopenharmony_ci<tbody><tr><th>Version</th><th>Changes</th></tr> 23881cb0ef41Sopenharmony_ci<tr><td>v10.0.0</td> 23891cb0ef41Sopenharmony_ci<td><p>Default value changed to <code>'auto'</code>.</p></td></tr> 23901cb0ef41Sopenharmony_ci<tr><td>v0.11.13</td> 23911cb0ef41Sopenharmony_ci<td><p><span>Added in: v0.11.13</span></p></td></tr> 23921cb0ef41Sopenharmony_ci</tbody></table> 23931cb0ef41Sopenharmony_ci</details> 23941cb0ef41Sopenharmony_ci</div> 23951cb0ef41Sopenharmony_ci<p>The default curve name to use for ECDH key agreement in a tls server. The 23961cb0ef41Sopenharmony_cidefault value is <code>'auto'</code>. See <a href="#tlscreatesecurecontextoptions"><code>tls.createSecureContext()</code></a> for further 23971cb0ef41Sopenharmony_ciinformation.</p> 23981cb0ef41Sopenharmony_ci</section><section><h3><code>tls.DEFAULT_MAX_VERSION</code><span><a class="mark" href="#tlsdefault_max_version" id="tlsdefault_max_version">#</a></span><a aria-hidden="true" class="legacy" id="tls_tls_default_max_version"></a></h3> 23991cb0ef41Sopenharmony_ci<div class="api_metadata"> 24001cb0ef41Sopenharmony_ci<span>Added in: v11.4.0</span> 24011cb0ef41Sopenharmony_ci</div> 24021cb0ef41Sopenharmony_ci<ul> 24031cb0ef41Sopenharmony_ci<li><a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> The default value of the <code>maxVersion</code> option of 24041cb0ef41Sopenharmony_ci<a href="#tlscreatesecurecontextoptions"><code>tls.createSecureContext()</code></a>. It can be assigned any of the supported TLS 24051cb0ef41Sopenharmony_ciprotocol versions, <code>'TLSv1.3'</code>, <code>'TLSv1.2'</code>, <code>'TLSv1.1'</code>, or <code>'TLSv1'</code>. 24061cb0ef41Sopenharmony_ci<strong>Default:</strong> <code>'TLSv1.3'</code>, unless changed using CLI options. Using 24071cb0ef41Sopenharmony_ci<code>--tls-max-v1.2</code> sets the default to <code>'TLSv1.2'</code>. Using <code>--tls-max-v1.3</code> sets 24081cb0ef41Sopenharmony_cithe default to <code>'TLSv1.3'</code>. If multiple of the options are provided, the 24091cb0ef41Sopenharmony_cihighest maximum is used.</li> 24101cb0ef41Sopenharmony_ci</ul> 24111cb0ef41Sopenharmony_ci</section><section><h3><code>tls.DEFAULT_MIN_VERSION</code><span><a class="mark" href="#tlsdefault_min_version" id="tlsdefault_min_version">#</a></span><a aria-hidden="true" class="legacy" id="tls_tls_default_min_version"></a></h3> 24121cb0ef41Sopenharmony_ci<div class="api_metadata"> 24131cb0ef41Sopenharmony_ci<span>Added in: v11.4.0</span> 24141cb0ef41Sopenharmony_ci</div> 24151cb0ef41Sopenharmony_ci<ul> 24161cb0ef41Sopenharmony_ci<li><a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> The default value of the <code>minVersion</code> option of 24171cb0ef41Sopenharmony_ci<a href="#tlscreatesecurecontextoptions"><code>tls.createSecureContext()</code></a>. It can be assigned any of the supported TLS 24181cb0ef41Sopenharmony_ciprotocol versions, <code>'TLSv1.3'</code>, <code>'TLSv1.2'</code>, <code>'TLSv1.1'</code>, or <code>'TLSv1'</code>. 24191cb0ef41Sopenharmony_ci<strong>Default:</strong> <code>'TLSv1.2'</code>, unless changed using CLI options. Using 24201cb0ef41Sopenharmony_ci<code>--tls-min-v1.0</code> sets the default to <code>'TLSv1'</code>. Using <code>--tls-min-v1.1</code> sets 24211cb0ef41Sopenharmony_cithe default to <code>'TLSv1.1'</code>. Using <code>--tls-min-v1.3</code> sets the default to 24221cb0ef41Sopenharmony_ci<code>'TLSv1.3'</code>. If multiple of the options are provided, the lowest minimum is 24231cb0ef41Sopenharmony_ciused.</li> 24241cb0ef41Sopenharmony_ci</ul> 24251cb0ef41Sopenharmony_ci</section><section><h3><code>tls.DEFAULT_CIPHERS</code><span><a class="mark" href="#tlsdefault_ciphers" id="tlsdefault_ciphers">#</a></span><a aria-hidden="true" class="legacy" id="tls_tls_default_ciphers"></a></h3> 24261cb0ef41Sopenharmony_ci<div class="api_metadata"> 24271cb0ef41Sopenharmony_ci<span>Added in: v18.16.0</span> 24281cb0ef41Sopenharmony_ci</div> 24291cb0ef41Sopenharmony_ci<ul> 24301cb0ef41Sopenharmony_ci<li><a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> The default value of the <code>ciphers</code> option of 24311cb0ef41Sopenharmony_ci<a href="#tlscreatesecurecontextoptions"><code>tls.createSecureContext()</code></a>. It can be assigned any of the supported 24321cb0ef41Sopenharmony_ciOpenSSL ciphers. Defaults to the content of 24331cb0ef41Sopenharmony_ci<code>crypto.constants.defaultCoreCipherList</code>, unless changed using CLI options 24341cb0ef41Sopenharmony_ciusing <code>--tls-default-ciphers</code>.</li> 24351cb0ef41Sopenharmony_ci</ul></section> 24361cb0ef41Sopenharmony_ci <!-- API END --> 24371cb0ef41Sopenharmony_ci </div> 24381cb0ef41Sopenharmony_ci </div> 24391cb0ef41Sopenharmony_ci </div> 24401cb0ef41Sopenharmony_ci</body> 24411cb0ef41Sopenharmony_ci</html> 2442