3554 lines
277 KiB
HTML
3554 lines
277 KiB
HTML
<!doctype html>
|
|
<html lang="en">
|
|
<head>
|
|
<meta charset="utf-8">
|
|
<meta name="viewport" content="width=device-width">
|
|
<meta name="nodejs.org:node-version" content="v12.22.12">
|
|
<title>Crypto | Node.js v12.22.12 Documentation</title>
|
|
<link rel="stylesheet" href="https://fonts.googleapis.com/css?family=Lato:400,700,400italic&display=fallback">
|
|
<link rel="stylesheet" href="assets/style.css">
|
|
<link rel="stylesheet" href="assets/hljs.css">
|
|
<link rel="canonical" href="https://nodejs.org/api/crypto.html">
|
|
</head>
|
|
<body class="alt apidoc" id="api-section-crypto">
|
|
<div id="content" class="clearfix">
|
|
<div id="column2" class="interior">
|
|
<div id="intro" class="interior">
|
|
<a href="/" title="Go back to the home page">
|
|
Node.js
|
|
</a>
|
|
</div>
|
|
<ul>
|
|
<li><a href="documentation.html" class="nav-documentation">About this documentation</a></li>
|
|
<li><a href="synopsis.html" class="nav-synopsis">Usage and example</a></li>
|
|
</ul>
|
|
<hr class="line">
|
|
<ul>
|
|
<li><a href="assert.html" class="nav-assert">Assertion testing</a></li>
|
|
<li><a href="async_hooks.html" class="nav-async_hooks">Async hooks</a></li>
|
|
<li><a href="buffer.html" class="nav-buffer">Buffer</a></li>
|
|
<li><a href="addons.html" class="nav-addons">C++ Addons</a></li>
|
|
<li><a href="n-api.html" class="nav-n-api">C/C++ Addons with N-API</a></li>
|
|
<li><a href="embedding.html" class="nav-embedding">C++ Embedder API</a></li>
|
|
<li><a href="child_process.html" class="nav-child_process">Child Processes</a></li>
|
|
<li><a href="cluster.html" class="nav-cluster">Cluster</a></li>
|
|
<li><a href="cli.html" class="nav-cli">Command line options</a></li>
|
|
<li><a href="console.html" class="nav-console">Console</a></li>
|
|
<li><a href="crypto.html" class="nav-crypto active">Crypto</a></li>
|
|
<li><a href="debugger.html" class="nav-debugger">Debugger</a></li>
|
|
<li><a href="deprecations.html" class="nav-deprecations">Deprecated APIs</a></li>
|
|
<li><a href="dns.html" class="nav-dns">DNS</a></li>
|
|
<li><a href="domain.html" class="nav-domain">Domain</a></li>
|
|
<li><a href="errors.html" class="nav-errors">Errors</a></li>
|
|
<li><a href="events.html" class="nav-events">Events</a></li>
|
|
<li><a href="fs.html" class="nav-fs">File system</a></li>
|
|
<li><a href="globals.html" class="nav-globals">Globals</a></li>
|
|
<li><a href="http.html" class="nav-http">HTTP</a></li>
|
|
<li><a href="http2.html" class="nav-http2">HTTP/2</a></li>
|
|
<li><a href="https.html" class="nav-https">HTTPS</a></li>
|
|
<li><a href="inspector.html" class="nav-inspector">Inspector</a></li>
|
|
<li><a href="intl.html" class="nav-intl">Internationalization</a></li>
|
|
<li><a href="modules.html" class="nav-modules">Modules: CommonJS modules</a></li>
|
|
<li><a href="esm.html" class="nav-esm">Modules: ECMAScript modules</a></li>
|
|
<li><a href="module.html" class="nav-module">Modules: <code>module</code> API</a></li>
|
|
<li><a href="packages.html" class="nav-packages">Modules: Packages</a></li>
|
|
<li><a href="net.html" class="nav-net">Net</a></li>
|
|
<li><a href="os.html" class="nav-os">OS</a></li>
|
|
<li><a href="path.html" class="nav-path">Path</a></li>
|
|
<li><a href="perf_hooks.html" class="nav-perf_hooks">Performance hooks</a></li>
|
|
<li><a href="policy.html" class="nav-policy">Policies</a></li>
|
|
<li><a href="process.html" class="nav-process">Process</a></li>
|
|
<li><a href="punycode.html" class="nav-punycode">Punycode</a></li>
|
|
<li><a href="querystring.html" class="nav-querystring">Query strings</a></li>
|
|
<li><a href="readline.html" class="nav-readline">Readline</a></li>
|
|
<li><a href="repl.html" class="nav-repl">REPL</a></li>
|
|
<li><a href="report.html" class="nav-report">Report</a></li>
|
|
<li><a href="stream.html" class="nav-stream">Stream</a></li>
|
|
<li><a href="string_decoder.html" class="nav-string_decoder">String decoder</a></li>
|
|
<li><a href="timers.html" class="nav-timers">Timers</a></li>
|
|
<li><a href="tls.html" class="nav-tls">TLS/SSL</a></li>
|
|
<li><a href="tracing.html" class="nav-tracing">Trace events</a></li>
|
|
<li><a href="tty.html" class="nav-tty">TTY</a></li>
|
|
<li><a href="dgram.html" class="nav-dgram">UDP/datagram</a></li>
|
|
<li><a href="url.html" class="nav-url">URL</a></li>
|
|
<li><a href="util.html" class="nav-util">Utilities</a></li>
|
|
<li><a href="v8.html" class="nav-v8">V8</a></li>
|
|
<li><a href="vm.html" class="nav-vm">VM</a></li>
|
|
<li><a href="wasi.html" class="nav-wasi">WASI</a></li>
|
|
<li><a href="worker_threads.html" class="nav-worker_threads">Worker threads</a></li>
|
|
<li><a href="zlib.html" class="nav-zlib">Zlib</a></li>
|
|
</ul>
|
|
<hr class="line">
|
|
<ul>
|
|
<li><a href="https://github.com/nodejs/node" class="nav-https-github-com-nodejs-node">Code repository and issue tracker</a></li>
|
|
</ul>
|
|
</div>
|
|
|
|
<div id="column1" data-id="crypto" class="interior">
|
|
<header>
|
|
<h1>Node.js v12.22.12 Documentation</h1>
|
|
<div id="gtoc">
|
|
<ul>
|
|
<li>
|
|
<a href="index.html">Index</a>
|
|
</li>
|
|
<li>
|
|
<a href="all.html">View on single page</a>
|
|
</li>
|
|
<li>
|
|
<a href="crypto.json">View as JSON</a>
|
|
</li>
|
|
|
|
<li class="version-picker">
|
|
<a href="#">View another version <span>▼</span></a>
|
|
<ol class="version-picker"><li><a href="https://nodejs.org/docs/latest-v17.x/api/crypto.html">17.x</a></li>
|
|
<li><a href="https://nodejs.org/docs/latest-v16.x/api/crypto.html">16.x <b>LTS</b></a></li>
|
|
<li><a href="https://nodejs.org/docs/latest-v15.x/api/crypto.html">15.x</a></li>
|
|
<li><a href="https://nodejs.org/docs/latest-v14.x/api/crypto.html">14.x <b>LTS</b></a></li>
|
|
<li><a href="https://nodejs.org/docs/latest-v13.x/api/crypto.html">13.x</a></li>
|
|
<li><a href="https://nodejs.org/docs/latest-v12.x/api/crypto.html">12.x <b>LTS</b></a></li>
|
|
<li><a href="https://nodejs.org/docs/latest-v11.x/api/crypto.html">11.x</a></li>
|
|
<li><a href="https://nodejs.org/docs/latest-v10.x/api/crypto.html">10.x</a></li>
|
|
<li><a href="https://nodejs.org/docs/latest-v9.x/api/crypto.html">9.x</a></li>
|
|
<li><a href="https://nodejs.org/docs/latest-v8.x/api/crypto.html">8.x</a></li>
|
|
<li><a href="https://nodejs.org/docs/latest-v7.x/api/crypto.html">7.x</a></li>
|
|
<li><a href="https://nodejs.org/docs/latest-v6.x/api/crypto.html">6.x</a></li>
|
|
<li><a href="https://nodejs.org/docs/latest-v5.x/api/crypto.html">5.x</a></li>
|
|
<li><a href="https://nodejs.org/docs/latest-v4.x/api/crypto.html">4.x</a></li>
|
|
<li><a href="https://nodejs.org/docs/latest-v0.12.x/api/crypto.html">0.12.x</a></li>
|
|
<li><a href="https://nodejs.org/docs/latest-v0.10.x/api/crypto.html">0.10.x</a></li></ol>
|
|
</li>
|
|
|
|
<li class="edit_on_github"><a href="https://github.com/nodejs/node/edit/master/doc/api/crypto.md"><span class="github_icon"><svg height="16" width="16" viewBox="0 0 16.1 16.1" fill="currentColor"><path d="M8 0a8 8 0 0 0-2.5 15.6c.4 0 .5-.2.5-.4v-1.5c-2 .4-2.5-.5-2.7-1 0-.1-.5-.9-.8-1-.3-.2-.7-.6 0-.6.6 0 1 .6 1.2.8.7 1.2 1.9 1 2.4.7 0-.5.2-.9.5-1-1.8-.3-3.7-1-3.7-4 0-.9.3-1.6.8-2.2 0-.2-.3-1 .1-2 0 0 .7-.3 2.2.7a7.4 7.4 0 0 1 4 0c1.5-1 2.2-.8 2.2-.8.5 1.1.2 2 .1 2.1.5.6.8 1.3.8 2.2 0 3-1.9 3.7-3.6 4 .3.2.5.7.5 1.4v2.2c0 .2.1.5.5.4A8 8 0 0 0 16 8a8 8 0 0 0-8-8z"/></svg></span>Edit on GitHub</a></li>
|
|
</ul>
|
|
</div>
|
|
<hr>
|
|
</header>
|
|
|
|
<div id="toc">
|
|
<h2>Table of Contents</h2>
|
|
<ul>
|
|
<li><span class="stability_2"><a href="#crypto_crypto">Crypto</a></span>
|
|
<ul>
|
|
<li><a href="#crypto_determining_if_crypto_support_is_unavailable">Determining if crypto support is unavailable</a></li>
|
|
<li><a href="#crypto_class_certificate">Class: <code>Certificate</code></a>
|
|
<ul>
|
|
<li><a href="#crypto_certificate_exportchallenge_spkac"><code>Certificate.exportChallenge(spkac)</code></a></li>
|
|
<li><a href="#crypto_certificate_exportpublickey_spkac_encoding"><code>Certificate.exportPublicKey(spkac[, encoding])</code></a></li>
|
|
<li><a href="#crypto_certificate_verifyspkac_spkac"><code>Certificate.verifySpkac(spkac)</code></a></li>
|
|
<li><a href="#crypto_legacy_api">Legacy API</a>
|
|
<ul>
|
|
<li><a href="#crypto_new_crypto_certificate"><code>new crypto.Certificate()</code></a></li>
|
|
<li><a href="#crypto_certificate_exportchallenge_spkac_1"><code>certificate.exportChallenge(spkac)</code></a></li>
|
|
<li><a href="#crypto_certificate_exportpublickey_spkac"><code>certificate.exportPublicKey(spkac)</code></a></li>
|
|
<li><a href="#crypto_certificate_verifyspkac_spkac_1"><code>certificate.verifySpkac(spkac)</code></a></li>
|
|
</ul>
|
|
</li>
|
|
</ul>
|
|
</li>
|
|
<li><a href="#crypto_class_cipher">Class: <code>Cipher</code></a>
|
|
<ul>
|
|
<li><a href="#crypto_cipher_final_outputencoding"><code>cipher.final([outputEncoding])</code></a></li>
|
|
<li><a href="#crypto_cipher_setaad_buffer_options"><code>cipher.setAAD(buffer[, options])</code></a></li>
|
|
<li><a href="#crypto_cipher_getauthtag"><code>cipher.getAuthTag()</code></a></li>
|
|
<li><a href="#crypto_cipher_setautopadding_autopadding"><code>cipher.setAutoPadding([autoPadding])</code></a></li>
|
|
<li><a href="#crypto_cipher_update_data_inputencoding_outputencoding"><code>cipher.update(data[, inputEncoding][, outputEncoding])</code></a></li>
|
|
</ul>
|
|
</li>
|
|
<li><a href="#crypto_class_decipher">Class: <code>Decipher</code></a>
|
|
<ul>
|
|
<li><a href="#crypto_decipher_final_outputencoding"><code>decipher.final([outputEncoding])</code></a></li>
|
|
<li><a href="#crypto_decipher_setaad_buffer_options"><code>decipher.setAAD(buffer[, options])</code></a></li>
|
|
<li><a href="#crypto_decipher_setauthtag_buffer"><code>decipher.setAuthTag(buffer)</code></a></li>
|
|
<li><a href="#crypto_decipher_setautopadding_autopadding"><code>decipher.setAutoPadding([autoPadding])</code></a></li>
|
|
<li><a href="#crypto_decipher_update_data_inputencoding_outputencoding"><code>decipher.update(data[, inputEncoding][, outputEncoding])</code></a></li>
|
|
</ul>
|
|
</li>
|
|
<li><a href="#crypto_class_diffiehellman">Class: <code>DiffieHellman</code></a>
|
|
<ul>
|
|
<li><a href="#crypto_diffiehellman_computesecret_otherpublickey_inputencoding_outputencoding"><code>diffieHellman.computeSecret(otherPublicKey[, inputEncoding][, outputEncoding])</code></a></li>
|
|
<li><a href="#crypto_diffiehellman_generatekeys_encoding"><code>diffieHellman.generateKeys([encoding])</code></a></li>
|
|
<li><a href="#crypto_diffiehellman_getgenerator_encoding"><code>diffieHellman.getGenerator([encoding])</code></a></li>
|
|
<li><a href="#crypto_diffiehellman_getprime_encoding"><code>diffieHellman.getPrime([encoding])</code></a></li>
|
|
<li><a href="#crypto_diffiehellman_getprivatekey_encoding"><code>diffieHellman.getPrivateKey([encoding])</code></a></li>
|
|
<li><a href="#crypto_diffiehellman_getpublickey_encoding"><code>diffieHellman.getPublicKey([encoding])</code></a></li>
|
|
<li><a href="#crypto_diffiehellman_setprivatekey_privatekey_encoding"><code>diffieHellman.setPrivateKey(privateKey[, encoding])</code></a></li>
|
|
<li><a href="#crypto_diffiehellman_setpublickey_publickey_encoding"><code>diffieHellman.setPublicKey(publicKey[, encoding])</code></a></li>
|
|
<li><a href="#crypto_diffiehellman_verifyerror"><code>diffieHellman.verifyError</code></a></li>
|
|
</ul>
|
|
</li>
|
|
<li><a href="#crypto_class_diffiehellmangroup">Class: <code>DiffieHellmanGroup</code></a></li>
|
|
<li><a href="#crypto_class_ecdh">Class: <code>ECDH</code></a>
|
|
<ul>
|
|
<li><a href="#crypto_static_method_ecdh_convertkey_key_curve_inputencoding_outputencoding_format">Static method: <code>ECDH.convertKey(key, curve[, inputEncoding[, outputEncoding[, format]]])</code></a></li>
|
|
<li><a href="#crypto_ecdh_computesecret_otherpublickey_inputencoding_outputencoding"><code>ecdh.computeSecret(otherPublicKey[, inputEncoding][, outputEncoding])</code></a></li>
|
|
<li><a href="#crypto_ecdh_generatekeys_encoding_format"><code>ecdh.generateKeys([encoding[, format]])</code></a></li>
|
|
<li><a href="#crypto_ecdh_getprivatekey_encoding"><code>ecdh.getPrivateKey([encoding])</code></a></li>
|
|
<li><a href="#crypto_ecdh_getpublickey_encoding_format"><code>ecdh.getPublicKey([encoding][, format])</code></a></li>
|
|
<li><a href="#crypto_ecdh_setprivatekey_privatekey_encoding"><code>ecdh.setPrivateKey(privateKey[, encoding])</code></a></li>
|
|
<li><span class="stability_0"><a href="#crypto_ecdh_setpublickey_publickey_encoding"><code>ecdh.setPublicKey(publicKey[, encoding])</code></a></span></li>
|
|
</ul>
|
|
</li>
|
|
<li><a href="#crypto_class_hash">Class: <code>Hash</code></a>
|
|
<ul>
|
|
<li><a href="#crypto_hash_copy_options"><code>hash.copy([options])</code></a></li>
|
|
<li><a href="#crypto_hash_digest_encoding"><code>hash.digest([encoding])</code></a></li>
|
|
<li><a href="#crypto_hash_update_data_inputencoding"><code>hash.update(data[, inputEncoding])</code></a></li>
|
|
</ul>
|
|
</li>
|
|
<li><a href="#crypto_class_hmac">Class: <code>Hmac</code></a>
|
|
<ul>
|
|
<li><a href="#crypto_hmac_digest_encoding"><code>hmac.digest([encoding])</code></a></li>
|
|
<li><a href="#crypto_hmac_update_data_inputencoding"><code>hmac.update(data[, inputEncoding])</code></a></li>
|
|
</ul>
|
|
</li>
|
|
<li><a href="#crypto_class_keyobject">Class: <code>KeyObject</code></a>
|
|
<ul>
|
|
<li><a href="#crypto_keyobject_asymmetrickeytype"><code>keyObject.asymmetricKeyType</code></a></li>
|
|
<li><a href="#crypto_keyobject_export_options"><code>keyObject.export([options])</code></a></li>
|
|
<li><a href="#crypto_keyobject_symmetrickeysize"><code>keyObject.symmetricKeySize</code></a></li>
|
|
<li><a href="#crypto_keyobject_type"><code>keyObject.type</code></a></li>
|
|
</ul>
|
|
</li>
|
|
<li><a href="#crypto_class_sign">Class: <code>Sign</code></a>
|
|
<ul>
|
|
<li><a href="#crypto_sign_sign_privatekey_outputencoding"><code>sign.sign(privateKey[, outputEncoding])</code></a></li>
|
|
<li><a href="#crypto_sign_update_data_inputencoding"><code>sign.update(data[, inputEncoding])</code></a></li>
|
|
</ul>
|
|
</li>
|
|
<li><a href="#crypto_class_verify">Class: <code>Verify</code></a>
|
|
<ul>
|
|
<li><a href="#crypto_verify_update_data_inputencoding"><code>verify.update(data[, inputEncoding])</code></a></li>
|
|
<li><a href="#crypto_verify_verify_object_signature_signatureencoding"><code>verify.verify(object, signature[, signatureEncoding])</code></a></li>
|
|
</ul>
|
|
</li>
|
|
<li><a href="#crypto_crypto_module_methods_and_properties"><code>crypto</code> module methods and properties</a>
|
|
<ul>
|
|
<li><a href="#crypto_crypto_constants"><code>crypto.constants</code></a></li>
|
|
<li><span class="stability_0"><a href="#crypto_crypto_default_encoding"><code>crypto.DEFAULT_ENCODING</code></a></span></li>
|
|
<li><span class="stability_0"><a href="#crypto_crypto_fips"><code>crypto.fips</code></a></span></li>
|
|
<li><span class="stability_0"><a href="#crypto_crypto_createcipher_algorithm_password_options"><code>crypto.createCipher(algorithm, password[, options])</code></a></span></li>
|
|
<li><a href="#crypto_crypto_createcipheriv_algorithm_key_iv_options"><code>crypto.createCipheriv(algorithm, key, iv[, options])</code></a></li>
|
|
<li><span class="stability_0"><a href="#crypto_crypto_createdecipher_algorithm_password_options"><code>crypto.createDecipher(algorithm, password[, options])</code></a></span></li>
|
|
<li><a href="#crypto_crypto_createdecipheriv_algorithm_key_iv_options"><code>crypto.createDecipheriv(algorithm, key, iv[, options])</code></a></li>
|
|
<li><a href="#crypto_crypto_creatediffiehellman_prime_primeencoding_generator_generatorencoding"><code>crypto.createDiffieHellman(prime[, primeEncoding][, generator][, generatorEncoding])</code></a></li>
|
|
<li><a href="#crypto_crypto_creatediffiehellman_primelength_generator"><code>crypto.createDiffieHellman(primeLength[, generator])</code></a></li>
|
|
<li><a href="#crypto_crypto_creatediffiehellmangroup_name"><code>crypto.createDiffieHellmanGroup(name)</code></a></li>
|
|
<li><a href="#crypto_crypto_createecdh_curvename"><code>crypto.createECDH(curveName)</code></a></li>
|
|
<li><a href="#crypto_crypto_createhash_algorithm_options"><code>crypto.createHash(algorithm[, options])</code></a></li>
|
|
<li><a href="#crypto_crypto_createhmac_algorithm_key_options"><code>crypto.createHmac(algorithm, key[, options])</code></a></li>
|
|
<li><a href="#crypto_crypto_createprivatekey_key"><code>crypto.createPrivateKey(key)</code></a></li>
|
|
<li><a href="#crypto_crypto_createpublickey_key"><code>crypto.createPublicKey(key)</code></a></li>
|
|
<li><a href="#crypto_crypto_createsecretkey_key"><code>crypto.createSecretKey(key)</code></a></li>
|
|
<li><a href="#crypto_crypto_createsign_algorithm_options"><code>crypto.createSign(algorithm[, options])</code></a></li>
|
|
<li><a href="#crypto_crypto_createverify_algorithm_options"><code>crypto.createVerify(algorithm[, options])</code></a></li>
|
|
<li><a href="#crypto_crypto_diffiehellman_options"><code>crypto.diffieHellman(options)</code></a></li>
|
|
<li><a href="#crypto_crypto_generatekeypair_type_options_callback"><code>crypto.generateKeyPair(type, options, callback)</code></a></li>
|
|
<li><a href="#crypto_crypto_generatekeypairsync_type_options"><code>crypto.generateKeyPairSync(type, options)</code></a></li>
|
|
<li><a href="#crypto_crypto_getciphers"><code>crypto.getCiphers()</code></a></li>
|
|
<li><a href="#crypto_crypto_getcurves"><code>crypto.getCurves()</code></a></li>
|
|
<li><a href="#crypto_crypto_getdiffiehellman_groupname"><code>crypto.getDiffieHellman(groupName)</code></a></li>
|
|
<li><a href="#crypto_crypto_getfips"><code>crypto.getFips()</code></a></li>
|
|
<li><a href="#crypto_crypto_gethashes"><code>crypto.getHashes()</code></a></li>
|
|
<li><a href="#crypto_crypto_pbkdf2_password_salt_iterations_keylen_digest_callback"><code>crypto.pbkdf2(password, salt, iterations, keylen, digest, callback)</code></a></li>
|
|
<li><a href="#crypto_crypto_pbkdf2sync_password_salt_iterations_keylen_digest"><code>crypto.pbkdf2Sync(password, salt, iterations, keylen, digest)</code></a></li>
|
|
<li><a href="#crypto_crypto_privatedecrypt_privatekey_buffer"><code>crypto.privateDecrypt(privateKey, buffer)</code></a></li>
|
|
<li><a href="#crypto_crypto_privateencrypt_privatekey_buffer"><code>crypto.privateEncrypt(privateKey, buffer)</code></a></li>
|
|
<li><a href="#crypto_crypto_publicdecrypt_key_buffer"><code>crypto.publicDecrypt(key, buffer)</code></a></li>
|
|
<li><a href="#crypto_crypto_publicencrypt_key_buffer"><code>crypto.publicEncrypt(key, buffer)</code></a></li>
|
|
<li><a href="#crypto_crypto_randombytes_size_callback"><code>crypto.randomBytes(size[, callback])</code></a></li>
|
|
<li><a href="#crypto_crypto_randomfillsync_buffer_offset_size"><code>crypto.randomFillSync(buffer[, offset][, size])</code></a></li>
|
|
<li><a href="#crypto_crypto_randomfill_buffer_offset_size_callback"><code>crypto.randomFill(buffer[, offset][, size], callback)</code></a></li>
|
|
<li><a href="#crypto_crypto_randomint_min_max_callback"><code>crypto.randomInt([min, ]max[, callback])</code></a></li>
|
|
<li><a href="#crypto_crypto_scrypt_password_salt_keylen_options_callback"><code>crypto.scrypt(password, salt, keylen[, options], callback)</code></a></li>
|
|
<li><a href="#crypto_crypto_scryptsync_password_salt_keylen_options"><code>crypto.scryptSync(password, salt, keylen[, options])</code></a></li>
|
|
<li><a href="#crypto_crypto_setengine_engine_flags"><code>crypto.setEngine(engine[, flags])</code></a></li>
|
|
<li><a href="#crypto_crypto_setfips_bool"><code>crypto.setFips(bool)</code></a></li>
|
|
<li><a href="#crypto_crypto_sign_algorithm_data_key"><code>crypto.sign(algorithm, data, key)</code></a></li>
|
|
<li><a href="#crypto_crypto_timingsafeequal_a_b"><code>crypto.timingSafeEqual(a, b)</code></a></li>
|
|
<li><a href="#crypto_crypto_verify_algorithm_data_key_signature"><code>crypto.verify(algorithm, data, key, signature)</code></a></li>
|
|
</ul>
|
|
</li>
|
|
<li><a href="#crypto_notes">Notes</a>
|
|
<ul>
|
|
<li><a href="#crypto_legacy_streams_api_prior_to_node_js_0_10">Legacy Streams API (prior to Node.js 0.10)</a></li>
|
|
<li><a href="#crypto_recent_ecdh_changes">Recent ECDH changes</a></li>
|
|
<li><a href="#crypto_support_for_weak_or_compromised_algorithms">Support for weak or compromised algorithms</a></li>
|
|
<li><a href="#crypto_ccm_mode">CCM mode</a></li>
|
|
</ul>
|
|
</li>
|
|
<li><a href="#crypto_crypto_constants_1">Crypto constants</a>
|
|
<ul>
|
|
<li><a href="#crypto_openssl_options">OpenSSL options</a></li>
|
|
<li><a href="#crypto_openssl_engine_constants">OpenSSL engine constants</a></li>
|
|
<li><a href="#crypto_other_openssl_constants">Other OpenSSL constants</a></li>
|
|
<li><a href="#crypto_node_js_crypto_constants">Node.js crypto constants</a></li>
|
|
</ul>
|
|
</li>
|
|
</ul>
|
|
</li>
|
|
</ul>
|
|
</div>
|
|
|
|
<div id="apicontent">
|
|
<h1>Crypto<span><a class="mark" href="#crypto_crypto" id="crypto_crypto">#</a></span></h1>
|
|
|
|
<p></p><div class="api_stability api_stability_2"><a href="documentation.html#documentation_stability_index">Stability: 2</a> - Stable</div><p></p>
|
|
<p><strong>Source Code:</strong> <a href="https://github.com/nodejs/node/blob/v12.22.12/lib/crypto.js">lib/crypto.js</a></p>
|
|
<p>The <code>crypto</code> module provides cryptographic functionality that includes a set of
|
|
wrappers for OpenSSL's hash, HMAC, cipher, decipher, sign, and verify functions.</p>
|
|
<p>Use <code>require('crypto')</code> to access this module.</p>
|
|
<pre><code class="language-js"><span class="hljs-keyword">const</span> crypto = <span class="hljs-built_in">require</span>(<span class="hljs-string">'crypto'</span>);
|
|
|
|
<span class="hljs-keyword">const</span> secret = <span class="hljs-string">'abcdefg'</span>;
|
|
<span class="hljs-keyword">const</span> hash = crypto.createHmac(<span class="hljs-string">'sha256'</span>, secret)
|
|
.update(<span class="hljs-string">'I love cupcakes'</span>)
|
|
.digest(<span class="hljs-string">'hex'</span>);
|
|
<span class="hljs-built_in">console</span>.log(hash);
|
|
<span class="hljs-comment">// Prints:</span>
|
|
<span class="hljs-comment">// c0fa1bc00531bd78ef38c628449c5102aeabd49b5dc3a2a516ea6ea959d6658e</span></code></pre>
|
|
<h2>Determining if crypto support is unavailable<span><a class="mark" href="#crypto_determining_if_crypto_support_is_unavailable" id="crypto_determining_if_crypto_support_is_unavailable">#</a></span></h2>
|
|
<p>It is possible for Node.js to be built without including support for the
|
|
<code>crypto</code> module. In such cases, calling <code>require('crypto')</code> will result in an
|
|
error being thrown.</p>
|
|
<pre><code class="language-js"><span class="hljs-keyword">let</span> crypto;
|
|
<span class="hljs-keyword">try</span> {
|
|
crypto = <span class="hljs-built_in">require</span>(<span class="hljs-string">'crypto'</span>);
|
|
} <span class="hljs-keyword">catch</span> (err) {
|
|
<span class="hljs-built_in">console</span>.log(<span class="hljs-string">'crypto support is disabled!'</span>);
|
|
}</code></pre>
|
|
<h2>Class: <code>Certificate</code><span><a class="mark" href="#crypto_class_certificate" id="crypto_class_certificate">#</a></span></h2>
|
|
<div class="api_metadata">
|
|
<span>Added in: v0.11.8</span>
|
|
</div>
|
|
<p>SPKAC is a Certificate Signing Request mechanism originally implemented by
|
|
Netscape and was specified formally as part of <a href="https://developer.mozilla.org/en-US/docs/Web/HTML/Element/keygen">HTML5's <code>keygen</code> element</a>.</p>
|
|
<p><code><keygen></code> is deprecated since <a href="https://www.w3.org/TR/html52/changes.html#features-removed">HTML 5.2</a> and new projects
|
|
should not use this element anymore.</p>
|
|
<p>The <code>crypto</code> module provides the <code>Certificate</code> class for working with SPKAC
|
|
data. The most common usage is handling output generated by the HTML5
|
|
<code><keygen></code> element. Node.js uses <a href="https://www.openssl.org/docs/man1.1.0/apps/openssl-spkac.html">OpenSSL's SPKAC implementation</a> internally.</p>
|
|
<h3><code>Certificate.exportChallenge(spkac)</code><span><a class="mark" href="#crypto_certificate_exportchallenge_spkac" id="crypto_certificate_exportchallenge_spkac">#</a></span></h3>
|
|
<div class="api_metadata">
|
|
<span>Added in: v9.0.0</span>
|
|
</div>
|
|
<ul>
|
|
<li><code>spkac</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> | <a href="buffer.html#buffer_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></li>
|
|
<li>Returns: <a href="buffer.html#buffer_class_buffer" class="type"><Buffer></a> The challenge component of the <code>spkac</code> data structure, which
|
|
includes a public key and a challenge.</li>
|
|
</ul>
|
|
<pre><code class="language-js"><span class="hljs-keyword">const</span> { Certificate } = <span class="hljs-built_in">require</span>(<span class="hljs-string">'crypto'</span>);
|
|
<span class="hljs-keyword">const</span> spkac = getSpkacSomehow();
|
|
<span class="hljs-keyword">const</span> challenge = Certificate.exportChallenge(spkac);
|
|
<span class="hljs-built_in">console</span>.log(challenge.toString(<span class="hljs-string">'utf8'</span>));
|
|
<span class="hljs-comment">// Prints: the challenge as a UTF8 string</span></code></pre>
|
|
<h3><code>Certificate.exportPublicKey(spkac[, encoding])</code><span><a class="mark" href="#crypto_certificate_exportpublickey_spkac_encoding" id="crypto_certificate_exportpublickey_spkac_encoding">#</a></span></h3>
|
|
<div class="api_metadata">
|
|
<span>Added in: v9.0.0</span>
|
|
</div>
|
|
<ul>
|
|
<li><code>spkac</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> | <a href="buffer.html#buffer_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></li>
|
|
<li><code>encoding</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> The <a href="buffer.html#buffer_buffers_and_character_encodings">encoding</a> of the <code>spkac</code> string.</li>
|
|
<li>Returns: <a href="buffer.html#buffer_class_buffer" class="type"><Buffer></a> The public key component of the <code>spkac</code> data structure,
|
|
which includes a public key and a challenge.</li>
|
|
</ul>
|
|
<pre><code class="language-js"><span class="hljs-keyword">const</span> { Certificate } = <span class="hljs-built_in">require</span>(<span class="hljs-string">'crypto'</span>);
|
|
<span class="hljs-keyword">const</span> spkac = getSpkacSomehow();
|
|
<span class="hljs-keyword">const</span> publicKey = Certificate.exportPublicKey(spkac);
|
|
<span class="hljs-built_in">console</span>.log(publicKey);
|
|
<span class="hljs-comment">// Prints: the public key as <Buffer ...></span></code></pre>
|
|
<h3><code>Certificate.verifySpkac(spkac)</code><span><a class="mark" href="#crypto_certificate_verifyspkac_spkac" id="crypto_certificate_verifyspkac_spkac">#</a></span></h3>
|
|
<div class="api_metadata">
|
|
<span>Added in: v9.0.0</span>
|
|
</div>
|
|
<ul>
|
|
<li><code>spkac</code> <a href="buffer.html#buffer_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></li>
|
|
<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 given <code>spkac</code> data structure is valid,
|
|
<code>false</code> otherwise.</li>
|
|
</ul>
|
|
<pre><code class="language-js"><span class="hljs-keyword">const</span> { Certificate } = <span class="hljs-built_in">require</span>(<span class="hljs-string">'crypto'</span>);
|
|
<span class="hljs-keyword">const</span> spkac = getSpkacSomehow();
|
|
<span class="hljs-built_in">console</span>.log(Certificate.verifySpkac(Buffer.from(spkac)));
|
|
<span class="hljs-comment">// Prints: true or false</span></code></pre>
|
|
<h3>Legacy API<span><a class="mark" href="#crypto_legacy_api" id="crypto_legacy_api">#</a></span></h3>
|
|
<p>As a still supported legacy interface, it is possible to create new instances of
|
|
the <code>crypto.Certificate</code> class as illustrated in the examples below.</p>
|
|
<h4><code>new crypto.Certificate()</code><span><a class="mark" href="#crypto_new_crypto_certificate" id="crypto_new_crypto_certificate">#</a></span></h4>
|
|
<p>Instances of the <code>Certificate</code> class can be created using the <code>new</code> keyword
|
|
or by calling <code>crypto.Certificate()</code> as a function:</p>
|
|
<pre><code class="language-js"><span class="hljs-keyword">const</span> crypto = <span class="hljs-built_in">require</span>(<span class="hljs-string">'crypto'</span>);
|
|
|
|
<span class="hljs-keyword">const</span> cert1 = <span class="hljs-keyword">new</span> crypto.Certificate();
|
|
<span class="hljs-keyword">const</span> cert2 = crypto.Certificate();</code></pre>
|
|
<h4><code>certificate.exportChallenge(spkac)</code><span><a class="mark" href="#crypto_certificate_exportchallenge_spkac_1" id="crypto_certificate_exportchallenge_spkac_1">#</a></span></h4>
|
|
<div class="api_metadata">
|
|
<span>Added in: v0.11.8</span>
|
|
</div>
|
|
<ul>
|
|
<li><code>spkac</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> | <a href="buffer.html#buffer_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></li>
|
|
<li>Returns: <a href="buffer.html#buffer_class_buffer" class="type"><Buffer></a> The challenge component of the <code>spkac</code> data structure, which
|
|
includes a public key and a challenge.</li>
|
|
</ul>
|
|
<pre><code class="language-js"><span class="hljs-keyword">const</span> cert = <span class="hljs-built_in">require</span>(<span class="hljs-string">'crypto'</span>).Certificate();
|
|
<span class="hljs-keyword">const</span> spkac = getSpkacSomehow();
|
|
<span class="hljs-keyword">const</span> challenge = cert.exportChallenge(spkac);
|
|
<span class="hljs-built_in">console</span>.log(challenge.toString(<span class="hljs-string">'utf8'</span>));
|
|
<span class="hljs-comment">// Prints: the challenge as a UTF8 string</span></code></pre>
|
|
<h4><code>certificate.exportPublicKey(spkac)</code><span><a class="mark" href="#crypto_certificate_exportpublickey_spkac" id="crypto_certificate_exportpublickey_spkac">#</a></span></h4>
|
|
<div class="api_metadata">
|
|
<span>Added in: v0.11.8</span>
|
|
</div>
|
|
<ul>
|
|
<li><code>spkac</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> | <a href="buffer.html#buffer_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></li>
|
|
<li>Returns: <a href="buffer.html#buffer_class_buffer" class="type"><Buffer></a> The public key component of the <code>spkac</code> data structure,
|
|
which includes a public key and a challenge.</li>
|
|
</ul>
|
|
<pre><code class="language-js"><span class="hljs-keyword">const</span> cert = <span class="hljs-built_in">require</span>(<span class="hljs-string">'crypto'</span>).Certificate();
|
|
<span class="hljs-keyword">const</span> spkac = getSpkacSomehow();
|
|
<span class="hljs-keyword">const</span> publicKey = cert.exportPublicKey(spkac);
|
|
<span class="hljs-built_in">console</span>.log(publicKey);
|
|
<span class="hljs-comment">// Prints: the public key as <Buffer ...></span></code></pre>
|
|
<h4><code>certificate.verifySpkac(spkac)</code><span><a class="mark" href="#crypto_certificate_verifyspkac_spkac_1" id="crypto_certificate_verifyspkac_spkac_1">#</a></span></h4>
|
|
<div class="api_metadata">
|
|
<span>Added in: v0.11.8</span>
|
|
</div>
|
|
<ul>
|
|
<li><code>spkac</code> <a href="buffer.html#buffer_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></li>
|
|
<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 given <code>spkac</code> data structure is valid,
|
|
<code>false</code> otherwise.</li>
|
|
</ul>
|
|
<pre><code class="language-js"><span class="hljs-keyword">const</span> cert = <span class="hljs-built_in">require</span>(<span class="hljs-string">'crypto'</span>).Certificate();
|
|
<span class="hljs-keyword">const</span> spkac = getSpkacSomehow();
|
|
<span class="hljs-built_in">console</span>.log(cert.verifySpkac(Buffer.from(spkac)));
|
|
<span class="hljs-comment">// Prints: true or false</span></code></pre>
|
|
<h2>Class: <code>Cipher</code><span><a class="mark" href="#crypto_class_cipher" id="crypto_class_cipher">#</a></span></h2>
|
|
<div class="api_metadata">
|
|
<span>Added in: v0.1.94</span>
|
|
</div>
|
|
<ul>
|
|
<li>Extends: <a href="stream.html#stream_class_stream_transform" class="type"><stream.Transform></a></li>
|
|
</ul>
|
|
<p>Instances of the <code>Cipher</code> class are used to encrypt data. The class can be
|
|
used in one of two ways:</p>
|
|
<ul>
|
|
<li>As a <a href="stream.html">stream</a> that is both readable and writable, where plain unencrypted
|
|
data is written to produce encrypted data on the readable side, or</li>
|
|
<li>Using the <a href="#crypto_cipher_update_data_inputencoding_outputencoding"><code>cipher.update()</code></a> and <a href="#crypto_cipher_final_outputencoding"><code>cipher.final()</code></a> methods to produce
|
|
the encrypted data.</li>
|
|
</ul>
|
|
<p>The <a href="#crypto_crypto_createcipher_algorithm_password_options"><code>crypto.createCipher()</code></a> or <a href="#crypto_crypto_createcipheriv_algorithm_key_iv_options"><code>crypto.createCipheriv()</code></a> methods are
|
|
used to create <code>Cipher</code> instances. <code>Cipher</code> objects are not to be created
|
|
directly using the <code>new</code> keyword.</p>
|
|
<p>Example: Using <code>Cipher</code> objects as streams:</p>
|
|
<pre><code class="language-js"><span class="hljs-keyword">const</span> crypto = <span class="hljs-built_in">require</span>(<span class="hljs-string">'crypto'</span>);
|
|
|
|
<span class="hljs-keyword">const</span> algorithm = <span class="hljs-string">'aes-192-cbc'</span>;
|
|
<span class="hljs-keyword">const</span> password = <span class="hljs-string">'Password used to generate key'</span>;
|
|
<span class="hljs-comment">// Key length is dependent on the algorithm. In this case for aes192, it is</span>
|
|
<span class="hljs-comment">// 24 bytes (192 bits).</span>
|
|
<span class="hljs-comment">// Use async `crypto.scrypt()` instead.</span>
|
|
<span class="hljs-keyword">const</span> key = crypto.scryptSync(password, <span class="hljs-string">'salt'</span>, <span class="hljs-number">24</span>);
|
|
<span class="hljs-comment">// Use `crypto.randomBytes()` to generate a random iv instead of the static iv</span>
|
|
<span class="hljs-comment">// shown here.</span>
|
|
<span class="hljs-keyword">const</span> iv = Buffer.alloc(<span class="hljs-number">16</span>, <span class="hljs-number">0</span>); <span class="hljs-comment">// Initialization vector.</span>
|
|
|
|
<span class="hljs-keyword">const</span> cipher = crypto.createCipheriv(algorithm, key, iv);
|
|
|
|
<span class="hljs-keyword">let</span> encrypted = <span class="hljs-string">''</span>;
|
|
cipher.on(<span class="hljs-string">'readable'</span>, <span class="hljs-function">() =></span> {
|
|
<span class="hljs-keyword">let</span> chunk;
|
|
<span class="hljs-keyword">while</span> (<span class="hljs-literal">null</span> !== (chunk = cipher.read())) {
|
|
encrypted += chunk.toString(<span class="hljs-string">'hex'</span>);
|
|
}
|
|
});
|
|
cipher.on(<span class="hljs-string">'end'</span>, <span class="hljs-function">() =></span> {
|
|
<span class="hljs-built_in">console</span>.log(encrypted);
|
|
<span class="hljs-comment">// Prints: e5f79c5915c02171eec6b212d5520d44480993d7d622a7c4c2da32f6efda0ffa</span>
|
|
});
|
|
|
|
cipher.write(<span class="hljs-string">'some clear text data'</span>);
|
|
cipher.end();</code></pre>
|
|
<p>Example: Using <code>Cipher</code> and piped streams:</p>
|
|
<pre><code class="language-js"><span class="hljs-keyword">const</span> crypto = <span class="hljs-built_in">require</span>(<span class="hljs-string">'crypto'</span>);
|
|
<span class="hljs-keyword">const</span> fs = <span class="hljs-built_in">require</span>(<span class="hljs-string">'fs'</span>);
|
|
|
|
<span class="hljs-keyword">const</span> algorithm = <span class="hljs-string">'aes-192-cbc'</span>;
|
|
<span class="hljs-keyword">const</span> password = <span class="hljs-string">'Password used to generate key'</span>;
|
|
<span class="hljs-comment">// Use the async `crypto.scrypt()` instead.</span>
|
|
<span class="hljs-keyword">const</span> key = crypto.scryptSync(password, <span class="hljs-string">'salt'</span>, <span class="hljs-number">24</span>);
|
|
<span class="hljs-comment">// Use `crypto.randomBytes()` to generate a random iv instead of the static iv</span>
|
|
<span class="hljs-comment">// shown here.</span>
|
|
<span class="hljs-keyword">const</span> iv = Buffer.alloc(<span class="hljs-number">16</span>, <span class="hljs-number">0</span>); <span class="hljs-comment">// Initialization vector.</span>
|
|
|
|
<span class="hljs-keyword">const</span> cipher = crypto.createCipheriv(algorithm, key, iv);
|
|
|
|
<span class="hljs-keyword">const</span> input = fs.createReadStream(<span class="hljs-string">'test.js'</span>);
|
|
<span class="hljs-keyword">const</span> output = fs.createWriteStream(<span class="hljs-string">'test.enc'</span>);
|
|
|
|
input.pipe(cipher).pipe(output);</code></pre>
|
|
<p>Example: Using the <a href="#crypto_cipher_update_data_inputencoding_outputencoding"><code>cipher.update()</code></a> and <a href="#crypto_cipher_final_outputencoding"><code>cipher.final()</code></a> methods:</p>
|
|
<pre><code class="language-js"><span class="hljs-keyword">const</span> crypto = <span class="hljs-built_in">require</span>(<span class="hljs-string">'crypto'</span>);
|
|
|
|
<span class="hljs-keyword">const</span> algorithm = <span class="hljs-string">'aes-192-cbc'</span>;
|
|
<span class="hljs-keyword">const</span> password = <span class="hljs-string">'Password used to generate key'</span>;
|
|
<span class="hljs-comment">// Use the async `crypto.scrypt()` instead.</span>
|
|
<span class="hljs-keyword">const</span> key = crypto.scryptSync(password, <span class="hljs-string">'salt'</span>, <span class="hljs-number">24</span>);
|
|
<span class="hljs-comment">// Use `crypto.randomBytes` to generate a random iv instead of the static iv</span>
|
|
<span class="hljs-comment">// shown here.</span>
|
|
<span class="hljs-keyword">const</span> iv = Buffer.alloc(<span class="hljs-number">16</span>, <span class="hljs-number">0</span>); <span class="hljs-comment">// Initialization vector.</span>
|
|
|
|
<span class="hljs-keyword">const</span> cipher = crypto.createCipheriv(algorithm, key, iv);
|
|
|
|
<span class="hljs-keyword">let</span> encrypted = cipher.update(<span class="hljs-string">'some clear text data'</span>, <span class="hljs-string">'utf8'</span>, <span class="hljs-string">'hex'</span>);
|
|
encrypted += cipher.final(<span class="hljs-string">'hex'</span>);
|
|
<span class="hljs-built_in">console</span>.log(encrypted);
|
|
<span class="hljs-comment">// Prints: e5f79c5915c02171eec6b212d5520d44480993d7d622a7c4c2da32f6efda0ffa</span></code></pre>
|
|
<h3><code>cipher.final([outputEncoding])</code><span><a class="mark" href="#crypto_cipher_final_outputencoding" id="crypto_cipher_final_outputencoding">#</a></span></h3>
|
|
<div class="api_metadata">
|
|
<span>Added in: v0.1.94</span>
|
|
</div>
|
|
<ul>
|
|
<li><code>outputEncoding</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> The <a href="buffer.html#buffer_buffers_and_character_encodings">encoding</a> of the return value.</li>
|
|
<li>Returns: <a href="buffer.html#buffer_class_buffer" class="type"><Buffer></a> | <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> Any remaining enciphered contents.
|
|
If <code>outputEncoding</code> is specified, a string is
|
|
returned. If an <code>outputEncoding</code> is not provided, a <a href="buffer.html"><code>Buffer</code></a> is returned.</li>
|
|
</ul>
|
|
<p>Once the <code>cipher.final()</code> method has been called, the <code>Cipher</code> object can no
|
|
longer be used to encrypt data. Attempts to call <code>cipher.final()</code> more than
|
|
once will result in an error being thrown.</p>
|
|
<h3><code>cipher.setAAD(buffer[, options])</code><span><a class="mark" href="#crypto_cipher_setaad_buffer_options" id="crypto_cipher_setaad_buffer_options">#</a></span></h3>
|
|
<div class="api_metadata">
|
|
<span>Added in: v1.0.0</span>
|
|
</div>
|
|
<ul>
|
|
<li><code>buffer</code> <a href="buffer.html#buffer_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></li>
|
|
<li><code>options</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object" class="type"><Object></a> <a href="stream.html#stream_new_stream_transform_options"><code>stream.transform</code> options</a>
|
|
<ul>
|
|
<li><code>plaintextLength</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><number></a></li>
|
|
</ul>
|
|
</li>
|
|
<li>Returns: <a href="crypto.html#crypto_class_cipher" class="type"><Cipher></a> for method chaining.</li>
|
|
</ul>
|
|
<p>When using an authenticated encryption mode (<code>GCM</code>, <code>CCM</code> and <code>OCB</code> are
|
|
currently supported), the <code>cipher.setAAD()</code> method sets the value used for the
|
|
<em>additional authenticated data</em> (AAD) input parameter.</p>
|
|
<p>The <code>options</code> argument is optional for <code>GCM</code> and <code>OCB</code>. When using <code>CCM</code>, the
|
|
<code>plaintextLength</code> option must be specified and its value must match the length
|
|
of the plaintext in bytes. See <a href="#crypto_ccm_mode">CCM mode</a>.</p>
|
|
<p>The <code>cipher.setAAD()</code> method must be called before <a href="#crypto_cipher_update_data_inputencoding_outputencoding"><code>cipher.update()</code></a>.</p>
|
|
<h3><code>cipher.getAuthTag()</code><span><a class="mark" href="#crypto_cipher_getauthtag" id="crypto_cipher_getauthtag">#</a></span></h3>
|
|
<div class="api_metadata">
|
|
<span>Added in: v1.0.0</span>
|
|
</div>
|
|
<ul>
|
|
<li>Returns: <a href="buffer.html#buffer_class_buffer" class="type"><Buffer></a> When using an authenticated encryption mode (<code>GCM</code>, <code>CCM</code>
|
|
and <code>OCB</code> are currently supported), the <code>cipher.getAuthTag()</code> method returns a
|
|
<a href="buffer.html"><code>Buffer</code></a> containing the <em>authentication tag</em> that has been computed from
|
|
the given data.</li>
|
|
</ul>
|
|
<p>The <code>cipher.getAuthTag()</code> method should only be called after encryption has
|
|
been completed using the <a href="#crypto_cipher_final_outputencoding"><code>cipher.final()</code></a> method.</p>
|
|
<h3><code>cipher.setAutoPadding([autoPadding])</code><span><a class="mark" href="#crypto_cipher_setautopadding_autopadding" id="crypto_cipher_setautopadding_autopadding">#</a></span></h3>
|
|
<div class="api_metadata">
|
|
<span>Added in: v0.7.1</span>
|
|
</div>
|
|
<ul>
|
|
<li><code>autoPadding</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type" class="type"><boolean></a> <strong>Default:</strong> <code>true</code></li>
|
|
<li>Returns: <a href="crypto.html#crypto_class_cipher" class="type"><Cipher></a> for method chaining.</li>
|
|
</ul>
|
|
<p>When using block encryption algorithms, the <code>Cipher</code> class will automatically
|
|
add padding to the input data to the appropriate block size. To disable the
|
|
default padding call <code>cipher.setAutoPadding(false)</code>.</p>
|
|
<p>When <code>autoPadding</code> is <code>false</code>, the length of the entire input data must be a
|
|
multiple of the cipher's block size or <a href="#crypto_cipher_final_outputencoding"><code>cipher.final()</code></a> will throw an error.
|
|
Disabling automatic padding is useful for non-standard padding, for instance
|
|
using <code>0x0</code> instead of PKCS padding.</p>
|
|
<p>The <code>cipher.setAutoPadding()</code> method must be called before
|
|
<a href="#crypto_cipher_final_outputencoding"><code>cipher.final()</code></a>.</p>
|
|
<h3><code>cipher.update(data[, inputEncoding][, outputEncoding])</code><span><a class="mark" href="#crypto_cipher_update_data_inputencoding_outputencoding" id="crypto_cipher_update_data_inputencoding_outputencoding">#</a></span></h3>
|
|
<div class="api_metadata">
|
|
<details class="changelog"><summary>History</summary>
|
|
<table>
|
|
<tbody><tr><th>Version</th><th>Changes</th></tr>
|
|
<tr><td>v6.0.0</td>
|
|
<td><p>The default <code>inputEncoding</code> changed from <code>binary</code> to <code>utf8</code>.</p></td></tr>
|
|
<tr><td>v0.1.94</td>
|
|
<td><p><span>Added in: v0.1.94</span></p></td></tr>
|
|
</tbody></table>
|
|
</details>
|
|
</div>
|
|
<ul>
|
|
<li><code>data</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> | <a href="buffer.html#buffer_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></li>
|
|
<li><code>inputEncoding</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> The <a href="buffer.html#buffer_buffers_and_character_encodings">encoding</a> of the data.</li>
|
|
<li><code>outputEncoding</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> The <a href="buffer.html#buffer_buffers_and_character_encodings">encoding</a> of the return value.</li>
|
|
<li>Returns: <a href="buffer.html#buffer_class_buffer" class="type"><Buffer></a> | <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a></li>
|
|
</ul>
|
|
<p>Updates the cipher with <code>data</code>. If the <code>inputEncoding</code> argument is given,
|
|
the <code>data</code>
|
|
argument is a string using the specified encoding. If the <code>inputEncoding</code>
|
|
argument is not given, <code>data</code> must be a <a href="buffer.html"><code>Buffer</code></a>, <code>TypedArray</code>, or
|
|
<code>DataView</code>. If <code>data</code> is a <a href="buffer.html"><code>Buffer</code></a>, <code>TypedArray</code>, or <code>DataView</code>, then
|
|
<code>inputEncoding</code> is ignored.</p>
|
|
<p>The <code>outputEncoding</code> specifies the output format of the enciphered
|
|
data. If the <code>outputEncoding</code>
|
|
is specified, a string using the specified encoding is returned. If no
|
|
<code>outputEncoding</code> is provided, a <a href="buffer.html"><code>Buffer</code></a> is returned.</p>
|
|
<p>The <code>cipher.update()</code> method can be called multiple times with new data until
|
|
<a href="#crypto_cipher_final_outputencoding"><code>cipher.final()</code></a> is called. Calling <code>cipher.update()</code> after
|
|
<a href="#crypto_cipher_final_outputencoding"><code>cipher.final()</code></a> will result in an error being thrown.</p>
|
|
<h2>Class: <code>Decipher</code><span><a class="mark" href="#crypto_class_decipher" id="crypto_class_decipher">#</a></span></h2>
|
|
<div class="api_metadata">
|
|
<span>Added in: v0.1.94</span>
|
|
</div>
|
|
<ul>
|
|
<li>Extends: <a href="stream.html#stream_class_stream_transform" class="type"><stream.Transform></a></li>
|
|
</ul>
|
|
<p>Instances of the <code>Decipher</code> class are used to decrypt data. The class can be
|
|
used in one of two ways:</p>
|
|
<ul>
|
|
<li>As a <a href="stream.html">stream</a> that is both readable and writable, where plain encrypted
|
|
data is written to produce unencrypted data on the readable side, or</li>
|
|
<li>Using the <a href="#crypto_decipher_update_data_inputencoding_outputencoding"><code>decipher.update()</code></a> and <a href="#crypto_decipher_final_outputencoding"><code>decipher.final()</code></a> methods to
|
|
produce the unencrypted data.</li>
|
|
</ul>
|
|
<p>The <a href="#crypto_crypto_createdecipher_algorithm_password_options"><code>crypto.createDecipher()</code></a> or <a href="#crypto_crypto_createdecipheriv_algorithm_key_iv_options"><code>crypto.createDecipheriv()</code></a> methods are
|
|
used to create <code>Decipher</code> instances. <code>Decipher</code> objects are not to be created
|
|
directly using the <code>new</code> keyword.</p>
|
|
<p>Example: Using <code>Decipher</code> objects as streams:</p>
|
|
<pre><code class="language-js"><span class="hljs-keyword">const</span> crypto = <span class="hljs-built_in">require</span>(<span class="hljs-string">'crypto'</span>);
|
|
|
|
<span class="hljs-keyword">const</span> algorithm = <span class="hljs-string">'aes-192-cbc'</span>;
|
|
<span class="hljs-keyword">const</span> password = <span class="hljs-string">'Password used to generate key'</span>;
|
|
<span class="hljs-comment">// Key length is dependent on the algorithm. In this case for aes192, it is</span>
|
|
<span class="hljs-comment">// 24 bytes (192 bits).</span>
|
|
<span class="hljs-comment">// Use the async `crypto.scrypt()` instead.</span>
|
|
<span class="hljs-keyword">const</span> key = crypto.scryptSync(password, <span class="hljs-string">'salt'</span>, <span class="hljs-number">24</span>);
|
|
<span class="hljs-comment">// The IV is usually passed along with the ciphertext.</span>
|
|
<span class="hljs-keyword">const</span> iv = Buffer.alloc(<span class="hljs-number">16</span>, <span class="hljs-number">0</span>); <span class="hljs-comment">// Initialization vector.</span>
|
|
|
|
<span class="hljs-keyword">const</span> decipher = crypto.createDecipheriv(algorithm, key, iv);
|
|
|
|
<span class="hljs-keyword">let</span> decrypted = <span class="hljs-string">''</span>;
|
|
decipher.on(<span class="hljs-string">'readable'</span>, <span class="hljs-function">() =></span> {
|
|
<span class="hljs-keyword">while</span> (<span class="hljs-literal">null</span> !== (chunk = decipher.read())) {
|
|
decrypted += chunk.toString(<span class="hljs-string">'utf8'</span>);
|
|
}
|
|
});
|
|
decipher.on(<span class="hljs-string">'end'</span>, <span class="hljs-function">() =></span> {
|
|
<span class="hljs-built_in">console</span>.log(decrypted);
|
|
<span class="hljs-comment">// Prints: some clear text data</span>
|
|
});
|
|
|
|
<span class="hljs-comment">// Encrypted with same algorithm, key and iv.</span>
|
|
<span class="hljs-keyword">const</span> encrypted =
|
|
<span class="hljs-string">'e5f79c5915c02171eec6b212d5520d44480993d7d622a7c4c2da32f6efda0ffa'</span>;
|
|
decipher.write(encrypted, <span class="hljs-string">'hex'</span>);
|
|
decipher.end();</code></pre>
|
|
<p>Example: Using <code>Decipher</code> and piped streams:</p>
|
|
<pre><code class="language-js"><span class="hljs-keyword">const</span> crypto = <span class="hljs-built_in">require</span>(<span class="hljs-string">'crypto'</span>);
|
|
<span class="hljs-keyword">const</span> fs = <span class="hljs-built_in">require</span>(<span class="hljs-string">'fs'</span>);
|
|
|
|
<span class="hljs-keyword">const</span> algorithm = <span class="hljs-string">'aes-192-cbc'</span>;
|
|
<span class="hljs-keyword">const</span> password = <span class="hljs-string">'Password used to generate key'</span>;
|
|
<span class="hljs-comment">// Use the async `crypto.scrypt()` instead.</span>
|
|
<span class="hljs-keyword">const</span> key = crypto.scryptSync(password, <span class="hljs-string">'salt'</span>, <span class="hljs-number">24</span>);
|
|
<span class="hljs-comment">// The IV is usually passed along with the ciphertext.</span>
|
|
<span class="hljs-keyword">const</span> iv = Buffer.alloc(<span class="hljs-number">16</span>, <span class="hljs-number">0</span>); <span class="hljs-comment">// Initialization vector.</span>
|
|
|
|
<span class="hljs-keyword">const</span> decipher = crypto.createDecipheriv(algorithm, key, iv);
|
|
|
|
<span class="hljs-keyword">const</span> input = fs.createReadStream(<span class="hljs-string">'test.enc'</span>);
|
|
<span class="hljs-keyword">const</span> output = fs.createWriteStream(<span class="hljs-string">'test.js'</span>);
|
|
|
|
input.pipe(decipher).pipe(output);</code></pre>
|
|
<p>Example: Using the <a href="#crypto_decipher_update_data_inputencoding_outputencoding"><code>decipher.update()</code></a> and <a href="#crypto_decipher_final_outputencoding"><code>decipher.final()</code></a> methods:</p>
|
|
<pre><code class="language-js"><span class="hljs-keyword">const</span> crypto = <span class="hljs-built_in">require</span>(<span class="hljs-string">'crypto'</span>);
|
|
|
|
<span class="hljs-keyword">const</span> algorithm = <span class="hljs-string">'aes-192-cbc'</span>;
|
|
<span class="hljs-keyword">const</span> password = <span class="hljs-string">'Password used to generate key'</span>;
|
|
<span class="hljs-comment">// Use the async `crypto.scrypt()` instead.</span>
|
|
<span class="hljs-keyword">const</span> key = crypto.scryptSync(password, <span class="hljs-string">'salt'</span>, <span class="hljs-number">24</span>);
|
|
<span class="hljs-comment">// The IV is usually passed along with the ciphertext.</span>
|
|
<span class="hljs-keyword">const</span> iv = Buffer.alloc(<span class="hljs-number">16</span>, <span class="hljs-number">0</span>); <span class="hljs-comment">// Initialization vector.</span>
|
|
|
|
<span class="hljs-keyword">const</span> decipher = crypto.createDecipheriv(algorithm, key, iv);
|
|
|
|
<span class="hljs-comment">// Encrypted using same algorithm, key and iv.</span>
|
|
<span class="hljs-keyword">const</span> encrypted =
|
|
<span class="hljs-string">'e5f79c5915c02171eec6b212d5520d44480993d7d622a7c4c2da32f6efda0ffa'</span>;
|
|
<span class="hljs-keyword">let</span> decrypted = decipher.update(encrypted, <span class="hljs-string">'hex'</span>, <span class="hljs-string">'utf8'</span>);
|
|
decrypted += decipher.final(<span class="hljs-string">'utf8'</span>);
|
|
<span class="hljs-built_in">console</span>.log(decrypted);
|
|
<span class="hljs-comment">// Prints: some clear text data</span></code></pre>
|
|
<h3><code>decipher.final([outputEncoding])</code><span><a class="mark" href="#crypto_decipher_final_outputencoding" id="crypto_decipher_final_outputencoding">#</a></span></h3>
|
|
<div class="api_metadata">
|
|
<span>Added in: v0.1.94</span>
|
|
</div>
|
|
<ul>
|
|
<li><code>outputEncoding</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> The <a href="buffer.html#buffer_buffers_and_character_encodings">encoding</a> of the return value.</li>
|
|
<li>Returns: <a href="buffer.html#buffer_class_buffer" class="type"><Buffer></a> | <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> Any remaining deciphered contents.
|
|
If <code>outputEncoding</code> is specified, a string is
|
|
returned. If an <code>outputEncoding</code> is not provided, a <a href="buffer.html"><code>Buffer</code></a> is returned.</li>
|
|
</ul>
|
|
<p>Once the <code>decipher.final()</code> method has been called, the <code>Decipher</code> object can
|
|
no longer be used to decrypt data. Attempts to call <code>decipher.final()</code> more
|
|
than once will result in an error being thrown.</p>
|
|
<h3><code>decipher.setAAD(buffer[, options])</code><span><a class="mark" href="#crypto_decipher_setaad_buffer_options" id="crypto_decipher_setaad_buffer_options">#</a></span></h3>
|
|
<div class="api_metadata">
|
|
<details class="changelog"><summary>History</summary>
|
|
<table>
|
|
<tbody><tr><th>Version</th><th>Changes</th></tr>
|
|
<tr><td>v7.2.0</td>
|
|
<td><p>This method now returns a reference to <code>decipher</code>.</p></td></tr>
|
|
<tr><td>v1.0.0</td>
|
|
<td><p><span>Added in: v1.0.0</span></p></td></tr>
|
|
</tbody></table>
|
|
</details>
|
|
</div>
|
|
<ul>
|
|
<li><code>buffer</code> <a href="buffer.html#buffer_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></li>
|
|
<li><code>options</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object" class="type"><Object></a> <a href="stream.html#stream_new_stream_transform_options"><code>stream.transform</code> options</a>
|
|
<ul>
|
|
<li><code>plaintextLength</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><number></a></li>
|
|
</ul>
|
|
</li>
|
|
<li>Returns: <a href="crypto.html#crypto_class_decipher" class="type"><Decipher></a> for method chaining.</li>
|
|
</ul>
|
|
<p>When using an authenticated encryption mode (<code>GCM</code>, <code>CCM</code> and <code>OCB</code> are
|
|
currently supported), the <code>decipher.setAAD()</code> method sets the value used for the
|
|
<em>additional authenticated data</em> (AAD) input parameter.</p>
|
|
<p>The <code>options</code> argument is optional for <code>GCM</code>. When using <code>CCM</code>, the
|
|
<code>plaintextLength</code> option must be specified and its value must match the length
|
|
of the ciphertext in bytes. See <a href="#crypto_ccm_mode">CCM mode</a>.</p>
|
|
<p>The <code>decipher.setAAD()</code> method must be called before <a href="#crypto_decipher_update_data_inputencoding_outputencoding"><code>decipher.update()</code></a>.</p>
|
|
<h3><code>decipher.setAuthTag(buffer)</code><span><a class="mark" href="#crypto_decipher_setauthtag_buffer" id="crypto_decipher_setauthtag_buffer">#</a></span></h3>
|
|
<div class="api_metadata">
|
|
<details class="changelog"><summary>History</summary>
|
|
<table>
|
|
<tbody><tr><th>Version</th><th>Changes</th></tr>
|
|
<tr><td>v11.0.0</td>
|
|
<td><p>This method now throws if the GCM tag length is invalid.</p></td></tr>
|
|
<tr><td>v7.2.0</td>
|
|
<td><p>This method now returns a reference to <code>decipher</code>.</p></td></tr>
|
|
<tr><td>v1.0.0</td>
|
|
<td><p><span>Added in: v1.0.0</span></p></td></tr>
|
|
</tbody></table>
|
|
</details>
|
|
</div>
|
|
<ul>
|
|
<li><code>buffer</code> <a href="buffer.html#buffer_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></li>
|
|
<li>Returns: <a href="crypto.html#crypto_class_decipher" class="type"><Decipher></a> for method chaining.</li>
|
|
</ul>
|
|
<p>When using an authenticated encryption mode (<code>GCM</code>, <code>CCM</code> and <code>OCB</code> are
|
|
currently supported), the <code>decipher.setAuthTag()</code> method is used to pass in the
|
|
received <em>authentication tag</em>. If no tag is provided, or if the cipher text
|
|
has been tampered with, <a href="#crypto_decipher_final_outputencoding"><code>decipher.final()</code></a> will throw, indicating that the
|
|
cipher text should be discarded due to failed authentication. If the tag length
|
|
is invalid according to <a href="https://nvlpubs.nist.gov/nistpubs/Legacy/SP/nistspecialpublication800-38d.pdf">NIST SP 800-38D</a> or does not match the value of the
|
|
<code>authTagLength</code> option, <code>decipher.setAuthTag()</code> will throw an error.</p>
|
|
<p>The <code>decipher.setAuthTag()</code> method must be called before <a href="#crypto_decipher_update_data_inputencoding_outputencoding"><code>decipher.update()</code></a>
|
|
for <code>CCM</code> mode or before <a href="#crypto_decipher_final_outputencoding"><code>decipher.final()</code></a> for <code>GCM</code> and <code>OCB</code> modes.
|
|
<code>decipher.setAuthTag()</code> can only be called once.</p>
|
|
<h3><code>decipher.setAutoPadding([autoPadding])</code><span><a class="mark" href="#crypto_decipher_setautopadding_autopadding" id="crypto_decipher_setautopadding_autopadding">#</a></span></h3>
|
|
<div class="api_metadata">
|
|
<span>Added in: v0.7.1</span>
|
|
</div>
|
|
<ul>
|
|
<li><code>autoPadding</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type" class="type"><boolean></a> <strong>Default:</strong> <code>true</code></li>
|
|
<li>Returns: <a href="crypto.html#crypto_class_decipher" class="type"><Decipher></a> for method chaining.</li>
|
|
</ul>
|
|
<p>When data has been encrypted without standard block padding, calling
|
|
<code>decipher.setAutoPadding(false)</code> will disable automatic padding to prevent
|
|
<a href="#crypto_decipher_final_outputencoding"><code>decipher.final()</code></a> from checking for and removing padding.</p>
|
|
<p>Turning auto padding off will only work if the input data's length is a
|
|
multiple of the ciphers block size.</p>
|
|
<p>The <code>decipher.setAutoPadding()</code> method must be called before
|
|
<a href="#crypto_decipher_final_outputencoding"><code>decipher.final()</code></a>.</p>
|
|
<h3><code>decipher.update(data[, inputEncoding][, outputEncoding])</code><span><a class="mark" href="#crypto_decipher_update_data_inputencoding_outputencoding" id="crypto_decipher_update_data_inputencoding_outputencoding">#</a></span></h3>
|
|
<div class="api_metadata">
|
|
<details class="changelog"><summary>History</summary>
|
|
<table>
|
|
<tbody><tr><th>Version</th><th>Changes</th></tr>
|
|
<tr><td>v6.0.0</td>
|
|
<td><p>The default <code>inputEncoding</code> changed from <code>binary</code> to <code>utf8</code>.</p></td></tr>
|
|
<tr><td>v0.1.94</td>
|
|
<td><p><span>Added in: v0.1.94</span></p></td></tr>
|
|
</tbody></table>
|
|
</details>
|
|
</div>
|
|
<ul>
|
|
<li><code>data</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> | <a href="buffer.html#buffer_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></li>
|
|
<li><code>inputEncoding</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> The <a href="buffer.html#buffer_buffers_and_character_encodings">encoding</a> of the <code>data</code> string.</li>
|
|
<li><code>outputEncoding</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> The <a href="buffer.html#buffer_buffers_and_character_encodings">encoding</a> of the return value.</li>
|
|
<li>Returns: <a href="buffer.html#buffer_class_buffer" class="type"><Buffer></a> | <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a></li>
|
|
</ul>
|
|
<p>Updates the decipher with <code>data</code>. If the <code>inputEncoding</code> argument is given,
|
|
the <code>data</code>
|
|
argument is a string using the specified encoding. If the <code>inputEncoding</code>
|
|
argument is not given, <code>data</code> must be a <a href="buffer.html"><code>Buffer</code></a>. If <code>data</code> is a
|
|
<a href="buffer.html"><code>Buffer</code></a> then <code>inputEncoding</code> is ignored.</p>
|
|
<p>The <code>outputEncoding</code> specifies the output format of the enciphered
|
|
data. If the <code>outputEncoding</code>
|
|
is specified, a string using the specified encoding is returned. If no
|
|
<code>outputEncoding</code> is provided, a <a href="buffer.html"><code>Buffer</code></a> is returned.</p>
|
|
<p>The <code>decipher.update()</code> method can be called multiple times with new data until
|
|
<a href="#crypto_decipher_final_outputencoding"><code>decipher.final()</code></a> is called. Calling <code>decipher.update()</code> after
|
|
<a href="#crypto_decipher_final_outputencoding"><code>decipher.final()</code></a> will result in an error being thrown.</p>
|
|
<h2>Class: <code>DiffieHellman</code><span><a class="mark" href="#crypto_class_diffiehellman" id="crypto_class_diffiehellman">#</a></span></h2>
|
|
<div class="api_metadata">
|
|
<span>Added in: v0.5.0</span>
|
|
</div>
|
|
<p>The <code>DiffieHellman</code> class is a utility for creating Diffie-Hellman key
|
|
exchanges.</p>
|
|
<p>Instances of the <code>DiffieHellman</code> class can be created using the
|
|
<a href="#crypto_crypto_creatediffiehellman_prime_primeencoding_generator_generatorencoding"><code>crypto.createDiffieHellman()</code></a> function.</p>
|
|
<pre><code class="language-js"><span class="hljs-keyword">const</span> crypto = <span class="hljs-built_in">require</span>(<span class="hljs-string">'crypto'</span>);
|
|
<span class="hljs-keyword">const</span> assert = <span class="hljs-built_in">require</span>(<span class="hljs-string">'assert'</span>);
|
|
|
|
<span class="hljs-comment">// Generate Alice's keys...</span>
|
|
<span class="hljs-keyword">const</span> alice = crypto.createDiffieHellman(<span class="hljs-number">2048</span>);
|
|
<span class="hljs-keyword">const</span> aliceKey = alice.generateKeys();
|
|
|
|
<span class="hljs-comment">// Generate Bob's keys...</span>
|
|
<span class="hljs-keyword">const</span> bob = crypto.createDiffieHellman(alice.getPrime(), alice.getGenerator());
|
|
<span class="hljs-keyword">const</span> bobKey = bob.generateKeys();
|
|
|
|
<span class="hljs-comment">// Exchange and generate the secret...</span>
|
|
<span class="hljs-keyword">const</span> aliceSecret = alice.computeSecret(bobKey);
|
|
<span class="hljs-keyword">const</span> bobSecret = bob.computeSecret(aliceKey);
|
|
|
|
<span class="hljs-comment">// OK</span>
|
|
assert.strictEqual(aliceSecret.toString(<span class="hljs-string">'hex'</span>), bobSecret.toString(<span class="hljs-string">'hex'</span>));</code></pre>
|
|
<h3><code>diffieHellman.computeSecret(otherPublicKey[, inputEncoding][, outputEncoding])</code><span><a class="mark" href="#crypto_diffiehellman_computesecret_otherpublickey_inputencoding_outputencoding" id="crypto_diffiehellman_computesecret_otherpublickey_inputencoding_outputencoding">#</a></span></h3>
|
|
<div class="api_metadata">
|
|
<span>Added in: v0.5.0</span>
|
|
</div>
|
|
<ul>
|
|
<li><code>otherPublicKey</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> | <a href="buffer.html#buffer_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></li>
|
|
<li><code>inputEncoding</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> The <a href="buffer.html#buffer_buffers_and_character_encodings">encoding</a> of an <code>otherPublicKey</code> string.</li>
|
|
<li><code>outputEncoding</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> The <a href="buffer.html#buffer_buffers_and_character_encodings">encoding</a> of the return value.</li>
|
|
<li>Returns: <a href="buffer.html#buffer_class_buffer" class="type"><Buffer></a> | <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a></li>
|
|
</ul>
|
|
<p>Computes the shared secret using <code>otherPublicKey</code> as the other
|
|
party's public key and returns the computed shared secret. The supplied
|
|
key is interpreted using the specified <code>inputEncoding</code>, and secret is
|
|
encoded using specified <code>outputEncoding</code>.
|
|
If the <code>inputEncoding</code> is not
|
|
provided, <code>otherPublicKey</code> is expected to be a <a href="buffer.html"><code>Buffer</code></a>,
|
|
<code>TypedArray</code>, or <code>DataView</code>.</p>
|
|
<p>If <code>outputEncoding</code> is given a string is returned; otherwise, a
|
|
<a href="buffer.html"><code>Buffer</code></a> is returned.</p>
|
|
<h3><code>diffieHellman.generateKeys([encoding])</code><span><a class="mark" href="#crypto_diffiehellman_generatekeys_encoding" id="crypto_diffiehellman_generatekeys_encoding">#</a></span></h3>
|
|
<div class="api_metadata">
|
|
<span>Added in: v0.5.0</span>
|
|
</div>
|
|
<ul>
|
|
<li><code>encoding</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> The <a href="buffer.html#buffer_buffers_and_character_encodings">encoding</a> of the return value.</li>
|
|
<li>Returns: <a href="buffer.html#buffer_class_buffer" class="type"><Buffer></a> | <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a></li>
|
|
</ul>
|
|
<p>Generates private and public Diffie-Hellman key values, and returns
|
|
the public key in the specified <code>encoding</code>. This key should be
|
|
transferred to the other party.
|
|
If <code>encoding</code> is provided a string is returned; otherwise a
|
|
<a href="buffer.html"><code>Buffer</code></a> is returned.</p>
|
|
<h3><code>diffieHellman.getGenerator([encoding])</code><span><a class="mark" href="#crypto_diffiehellman_getgenerator_encoding" id="crypto_diffiehellman_getgenerator_encoding">#</a></span></h3>
|
|
<div class="api_metadata">
|
|
<span>Added in: v0.5.0</span>
|
|
</div>
|
|
<ul>
|
|
<li><code>encoding</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> The <a href="buffer.html#buffer_buffers_and_character_encodings">encoding</a> of the return value.</li>
|
|
<li>Returns: <a href="buffer.html#buffer_class_buffer" class="type"><Buffer></a> | <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a></li>
|
|
</ul>
|
|
<p>Returns the Diffie-Hellman generator in the specified <code>encoding</code>.
|
|
If <code>encoding</code> is provided a string is
|
|
returned; otherwise a <a href="buffer.html"><code>Buffer</code></a> is returned.</p>
|
|
<h3><code>diffieHellman.getPrime([encoding])</code><span><a class="mark" href="#crypto_diffiehellman_getprime_encoding" id="crypto_diffiehellman_getprime_encoding">#</a></span></h3>
|
|
<div class="api_metadata">
|
|
<span>Added in: v0.5.0</span>
|
|
</div>
|
|
<ul>
|
|
<li><code>encoding</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> The <a href="buffer.html#buffer_buffers_and_character_encodings">encoding</a> of the return value.</li>
|
|
<li>Returns: <a href="buffer.html#buffer_class_buffer" class="type"><Buffer></a> | <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a></li>
|
|
</ul>
|
|
<p>Returns the Diffie-Hellman prime in the specified <code>encoding</code>.
|
|
If <code>encoding</code> is provided a string is
|
|
returned; otherwise a <a href="buffer.html"><code>Buffer</code></a> is returned.</p>
|
|
<h3><code>diffieHellman.getPrivateKey([encoding])</code><span><a class="mark" href="#crypto_diffiehellman_getprivatekey_encoding" id="crypto_diffiehellman_getprivatekey_encoding">#</a></span></h3>
|
|
<div class="api_metadata">
|
|
<span>Added in: v0.5.0</span>
|
|
</div>
|
|
<ul>
|
|
<li><code>encoding</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> The <a href="buffer.html#buffer_buffers_and_character_encodings">encoding</a> of the return value.</li>
|
|
<li>Returns: <a href="buffer.html#buffer_class_buffer" class="type"><Buffer></a> | <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a></li>
|
|
</ul>
|
|
<p>Returns the Diffie-Hellman private key in the specified <code>encoding</code>.
|
|
If <code>encoding</code> is provided a
|
|
string is returned; otherwise a <a href="buffer.html"><code>Buffer</code></a> is returned.</p>
|
|
<h3><code>diffieHellman.getPublicKey([encoding])</code><span><a class="mark" href="#crypto_diffiehellman_getpublickey_encoding" id="crypto_diffiehellman_getpublickey_encoding">#</a></span></h3>
|
|
<div class="api_metadata">
|
|
<span>Added in: v0.5.0</span>
|
|
</div>
|
|
<ul>
|
|
<li><code>encoding</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> The <a href="buffer.html#buffer_buffers_and_character_encodings">encoding</a> of the return value.</li>
|
|
<li>Returns: <a href="buffer.html#buffer_class_buffer" class="type"><Buffer></a> | <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a></li>
|
|
</ul>
|
|
<p>Returns the Diffie-Hellman public key in the specified <code>encoding</code>.
|
|
If <code>encoding</code> is provided a
|
|
string is returned; otherwise a <a href="buffer.html"><code>Buffer</code></a> is returned.</p>
|
|
<h3><code>diffieHellman.setPrivateKey(privateKey[, encoding])</code><span><a class="mark" href="#crypto_diffiehellman_setprivatekey_privatekey_encoding" id="crypto_diffiehellman_setprivatekey_privatekey_encoding">#</a></span></h3>
|
|
<div class="api_metadata">
|
|
<span>Added in: v0.5.0</span>
|
|
</div>
|
|
<ul>
|
|
<li><code>privateKey</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> | <a href="buffer.html#buffer_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></li>
|
|
<li><code>encoding</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> The <a href="buffer.html#buffer_buffers_and_character_encodings">encoding</a> of the <code>privateKey</code> string.</li>
|
|
</ul>
|
|
<p>Sets the Diffie-Hellman private key. If the <code>encoding</code> argument is provided,
|
|
<code>privateKey</code> is expected
|
|
to be a string. If no <code>encoding</code> is provided, <code>privateKey</code> is expected
|
|
to be a <a href="buffer.html"><code>Buffer</code></a>, <code>TypedArray</code>, or <code>DataView</code>.</p>
|
|
<h3><code>diffieHellman.setPublicKey(publicKey[, encoding])</code><span><a class="mark" href="#crypto_diffiehellman_setpublickey_publickey_encoding" id="crypto_diffiehellman_setpublickey_publickey_encoding">#</a></span></h3>
|
|
<div class="api_metadata">
|
|
<span>Added in: v0.5.0</span>
|
|
</div>
|
|
<ul>
|
|
<li><code>publicKey</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> | <a href="buffer.html#buffer_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></li>
|
|
<li><code>encoding</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> The <a href="buffer.html#buffer_buffers_and_character_encodings">encoding</a> of the <code>publicKey</code> string.</li>
|
|
</ul>
|
|
<p>Sets the Diffie-Hellman public key. If the <code>encoding</code> argument is provided,
|
|
<code>publicKey</code> is expected
|
|
to be a string. If no <code>encoding</code> is provided, <code>publicKey</code> is expected
|
|
to be a <a href="buffer.html"><code>Buffer</code></a>, <code>TypedArray</code>, or <code>DataView</code>.</p>
|
|
<h3><code>diffieHellman.verifyError</code><span><a class="mark" href="#crypto_diffiehellman_verifyerror" id="crypto_diffiehellman_verifyerror">#</a></span></h3>
|
|
<div class="api_metadata">
|
|
<span>Added in: v0.11.12</span>
|
|
</div>
|
|
<p>A bit field containing any warnings and/or errors resulting from a check
|
|
performed during initialization of the <code>DiffieHellman</code> object.</p>
|
|
<p>The following values are valid for this property (as defined in <code>constants</code>
|
|
module):</p>
|
|
<ul>
|
|
<li><code>DH_CHECK_P_NOT_SAFE_PRIME</code></li>
|
|
<li><code>DH_CHECK_P_NOT_PRIME</code></li>
|
|
<li><code>DH_UNABLE_TO_CHECK_GENERATOR</code></li>
|
|
<li><code>DH_NOT_SUITABLE_GENERATOR</code></li>
|
|
</ul>
|
|
<h2>Class: <code>DiffieHellmanGroup</code><span><a class="mark" href="#crypto_class_diffiehellmangroup" id="crypto_class_diffiehellmangroup">#</a></span></h2>
|
|
<div class="api_metadata">
|
|
<span>Added in: v0.7.5</span>
|
|
</div>
|
|
<p>The <code>DiffieHellmanGroup</code> class takes a well-known modp group as its argument but
|
|
otherwise works the same as <code>DiffieHellman</code>.</p>
|
|
<pre><code class="language-js"><span class="hljs-keyword">const</span> name = <span class="hljs-string">'modp1'</span>;
|
|
<span class="hljs-keyword">const</span> dh = crypto.createDiffieHellmanGroup(name);</code></pre>
|
|
<p><code>name</code> is taken from <a href="https://www.rfc-editor.org/rfc/rfc2412.txt">RFC 2412</a> (modp1 and 2) and <a href="https://www.rfc-editor.org/rfc/rfc3526.txt">RFC 3526</a>:</p>
|
|
<pre><code class="language-console"><span class="hljs-meta">$</span><span class="bash"> perl -ne <span class="hljs-string">'print "$1\n" if /"(modp\d+)"/'</span> src/node_crypto_groups.h</span>
|
|
modp1 # 768 bits
|
|
modp2 # 1024 bits
|
|
modp5 # 1536 bits
|
|
modp14 # 2048 bits
|
|
modp15 # etc.
|
|
modp16
|
|
modp17
|
|
modp18</code></pre>
|
|
<h2>Class: <code>ECDH</code><span><a class="mark" href="#crypto_class_ecdh" id="crypto_class_ecdh">#</a></span></h2>
|
|
<div class="api_metadata">
|
|
<span>Added in: v0.11.14</span>
|
|
</div>
|
|
<p>The <code>ECDH</code> class is a utility for creating Elliptic Curve Diffie-Hellman (ECDH)
|
|
key exchanges.</p>
|
|
<p>Instances of the <code>ECDH</code> class can be created using the
|
|
<a href="#crypto_crypto_createecdh_curvename"><code>crypto.createECDH()</code></a> function.</p>
|
|
<pre><code class="language-js"><span class="hljs-keyword">const</span> crypto = <span class="hljs-built_in">require</span>(<span class="hljs-string">'crypto'</span>);
|
|
<span class="hljs-keyword">const</span> assert = <span class="hljs-built_in">require</span>(<span class="hljs-string">'assert'</span>);
|
|
|
|
<span class="hljs-comment">// Generate Alice's keys...</span>
|
|
<span class="hljs-keyword">const</span> alice = crypto.createECDH(<span class="hljs-string">'secp521r1'</span>);
|
|
<span class="hljs-keyword">const</span> aliceKey = alice.generateKeys();
|
|
|
|
<span class="hljs-comment">// Generate Bob's keys...</span>
|
|
<span class="hljs-keyword">const</span> bob = crypto.createECDH(<span class="hljs-string">'secp521r1'</span>);
|
|
<span class="hljs-keyword">const</span> bobKey = bob.generateKeys();
|
|
|
|
<span class="hljs-comment">// Exchange and generate the secret...</span>
|
|
<span class="hljs-keyword">const</span> aliceSecret = alice.computeSecret(bobKey);
|
|
<span class="hljs-keyword">const</span> bobSecret = bob.computeSecret(aliceKey);
|
|
|
|
assert.strictEqual(aliceSecret.toString(<span class="hljs-string">'hex'</span>), bobSecret.toString(<span class="hljs-string">'hex'</span>));
|
|
<span class="hljs-comment">// OK</span></code></pre>
|
|
<h3>Static method: <code>ECDH.convertKey(key, curve[, inputEncoding[, outputEncoding[, format]]])</code><span><a class="mark" href="#crypto_static_method_ecdh_convertkey_key_curve_inputencoding_outputencoding_format" id="crypto_static_method_ecdh_convertkey_key_curve_inputencoding_outputencoding_format">#</a></span></h3>
|
|
<div class="api_metadata">
|
|
<span>Added in: v10.0.0</span>
|
|
</div>
|
|
<ul>
|
|
<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="buffer.html#buffer_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></li>
|
|
<li><code>curve</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a></li>
|
|
<li><code>inputEncoding</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> The <a href="buffer.html#buffer_buffers_and_character_encodings">encoding</a> of the <code>key</code> string.</li>
|
|
<li><code>outputEncoding</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> The <a href="buffer.html#buffer_buffers_and_character_encodings">encoding</a> of the return value.</li>
|
|
<li><code>format</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> <strong>Default:</strong> <code>'uncompressed'</code></li>
|
|
<li>Returns: <a href="buffer.html#buffer_class_buffer" class="type"><Buffer></a> | <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a></li>
|
|
</ul>
|
|
<p>Converts the EC Diffie-Hellman public key specified by <code>key</code> and <code>curve</code> to the
|
|
format specified by <code>format</code>. The <code>format</code> argument specifies point encoding
|
|
and can be <code>'compressed'</code>, <code>'uncompressed'</code> or <code>'hybrid'</code>. The supplied key is
|
|
interpreted using the specified <code>inputEncoding</code>, and the returned key is encoded
|
|
using the specified <code>outputEncoding</code>.</p>
|
|
<p>Use <a href="#crypto_crypto_getcurves"><code>crypto.getCurves()</code></a> to obtain a list of available curve names.
|
|
On recent OpenSSL releases, <code>openssl ecparam -list_curves</code> will also display
|
|
the name and description of each available elliptic curve.</p>
|
|
<p>If <code>format</code> is not specified the point will be returned in <code>'uncompressed'</code>
|
|
format.</p>
|
|
<p>If the <code>inputEncoding</code> is not provided, <code>key</code> is expected to be a <a href="buffer.html"><code>Buffer</code></a>,
|
|
<code>TypedArray</code>, or <code>DataView</code>.</p>
|
|
<p>Example (uncompressing a key):</p>
|
|
<pre><code class="language-js"><span class="hljs-keyword">const</span> { createECDH, ECDH } = <span class="hljs-built_in">require</span>(<span class="hljs-string">'crypto'</span>);
|
|
|
|
<span class="hljs-keyword">const</span> ecdh = createECDH(<span class="hljs-string">'secp256k1'</span>);
|
|
ecdh.generateKeys();
|
|
|
|
<span class="hljs-keyword">const</span> compressedKey = ecdh.getPublicKey(<span class="hljs-string">'hex'</span>, <span class="hljs-string">'compressed'</span>);
|
|
|
|
<span class="hljs-keyword">const</span> uncompressedKey = ECDH.convertKey(compressedKey,
|
|
<span class="hljs-string">'secp256k1'</span>,
|
|
<span class="hljs-string">'hex'</span>,
|
|
<span class="hljs-string">'hex'</span>,
|
|
<span class="hljs-string">'uncompressed'</span>);
|
|
|
|
<span class="hljs-comment">// The converted key and the uncompressed public key should be the same</span>
|
|
<span class="hljs-built_in">console</span>.log(uncompressedKey === ecdh.getPublicKey(<span class="hljs-string">'hex'</span>));</code></pre>
|
|
<h3><code>ecdh.computeSecret(otherPublicKey[, inputEncoding][, outputEncoding])</code><span><a class="mark" href="#crypto_ecdh_computesecret_otherpublickey_inputencoding_outputencoding" id="crypto_ecdh_computesecret_otherpublickey_inputencoding_outputencoding">#</a></span></h3>
|
|
<div class="api_metadata">
|
|
<details class="changelog"><summary>History</summary>
|
|
<table>
|
|
<tbody><tr><th>Version</th><th>Changes</th></tr>
|
|
<tr><td>v10.0.0</td>
|
|
<td><p>Changed error format to better support invalid public key error</p></td></tr>
|
|
<tr><td>v6.0.0</td>
|
|
<td><p>The default <code>inputEncoding</code> changed from <code>binary</code> to <code>utf8</code></p></td></tr>
|
|
<tr><td>v0.11.14</td>
|
|
<td><p><span>Added in: v0.11.14</span></p></td></tr>
|
|
</tbody></table>
|
|
</details>
|
|
</div>
|
|
<ul>
|
|
<li><code>otherPublicKey</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> | <a href="buffer.html#buffer_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></li>
|
|
<li><code>inputEncoding</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> The <a href="buffer.html#buffer_buffers_and_character_encodings">encoding</a> of the <code>otherPublicKey</code> string.</li>
|
|
<li><code>outputEncoding</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> The <a href="buffer.html#buffer_buffers_and_character_encodings">encoding</a> of the return value.</li>
|
|
<li>Returns: <a href="buffer.html#buffer_class_buffer" class="type"><Buffer></a> | <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a></li>
|
|
</ul>
|
|
<p>Computes the shared secret using <code>otherPublicKey</code> as the other
|
|
party's public key and returns the computed shared secret. The supplied
|
|
key is interpreted using specified <code>inputEncoding</code>, and the returned secret
|
|
is encoded using the specified <code>outputEncoding</code>.
|
|
If the <code>inputEncoding</code> is not
|
|
provided, <code>otherPublicKey</code> is expected to be a <a href="buffer.html"><code>Buffer</code></a>, <code>TypedArray</code>, or
|
|
<code>DataView</code>.</p>
|
|
<p>If <code>outputEncoding</code> is given a string will be returned; otherwise a
|
|
<a href="buffer.html"><code>Buffer</code></a> is returned.</p>
|
|
<p><code>ecdh.computeSecret</code> will throw an
|
|
<code>ERR_CRYPTO_ECDH_INVALID_PUBLIC_KEY</code> error when <code>otherPublicKey</code>
|
|
lies outside of the elliptic curve. Since <code>otherPublicKey</code> is
|
|
usually supplied from a remote user over an insecure network,
|
|
be sure to handle this exception accordingly.</p>
|
|
<h3><code>ecdh.generateKeys([encoding[, format]])</code><span><a class="mark" href="#crypto_ecdh_generatekeys_encoding_format" id="crypto_ecdh_generatekeys_encoding_format">#</a></span></h3>
|
|
<div class="api_metadata">
|
|
<span>Added in: v0.11.14</span>
|
|
</div>
|
|
<ul>
|
|
<li><code>encoding</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> The <a href="buffer.html#buffer_buffers_and_character_encodings">encoding</a> of the return value.</li>
|
|
<li><code>format</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> <strong>Default:</strong> <code>'uncompressed'</code></li>
|
|
<li>Returns: <a href="buffer.html#buffer_class_buffer" class="type"><Buffer></a> | <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a></li>
|
|
</ul>
|
|
<p>Generates private and public EC Diffie-Hellman key values, and returns
|
|
the public key in the specified <code>format</code> and <code>encoding</code>. This key should be
|
|
transferred to the other party.</p>
|
|
<p>The <code>format</code> argument specifies point encoding and can be <code>'compressed'</code> or
|
|
<code>'uncompressed'</code>. If <code>format</code> is not specified, the point will be returned in
|
|
<code>'uncompressed'</code> format.</p>
|
|
<p>If <code>encoding</code> is provided a string is returned; otherwise a <a href="buffer.html"><code>Buffer</code></a>
|
|
is returned.</p>
|
|
<h3><code>ecdh.getPrivateKey([encoding])</code><span><a class="mark" href="#crypto_ecdh_getprivatekey_encoding" id="crypto_ecdh_getprivatekey_encoding">#</a></span></h3>
|
|
<div class="api_metadata">
|
|
<span>Added in: v0.11.14</span>
|
|
</div>
|
|
<ul>
|
|
<li><code>encoding</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> The <a href="buffer.html#buffer_buffers_and_character_encodings">encoding</a> of the return value.</li>
|
|
<li>Returns: <a href="buffer.html#buffer_class_buffer" class="type"><Buffer></a> | <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> The EC Diffie-Hellman in the specified <code>encoding</code>.</li>
|
|
</ul>
|
|
<p>If <code>encoding</code> is specified, a string is returned; otherwise a <a href="buffer.html"><code>Buffer</code></a> is
|
|
returned.</p>
|
|
<h3><code>ecdh.getPublicKey([encoding][, format])</code><span><a class="mark" href="#crypto_ecdh_getpublickey_encoding_format" id="crypto_ecdh_getpublickey_encoding_format">#</a></span></h3>
|
|
<div class="api_metadata">
|
|
<span>Added in: v0.11.14</span>
|
|
</div>
|
|
<ul>
|
|
<li><code>encoding</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> The <a href="buffer.html#buffer_buffers_and_character_encodings">encoding</a> of the return value.</li>
|
|
<li><code>format</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> <strong>Default:</strong> <code>'uncompressed'</code></li>
|
|
<li>Returns: <a href="buffer.html#buffer_class_buffer" class="type"><Buffer></a> | <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> The EC Diffie-Hellman public key in the specified
|
|
<code>encoding</code> and <code>format</code>.</li>
|
|
</ul>
|
|
<p>The <code>format</code> argument specifies point encoding and can be <code>'compressed'</code> or
|
|
<code>'uncompressed'</code>. If <code>format</code> is not specified the point will be returned in
|
|
<code>'uncompressed'</code> format.</p>
|
|
<p>If <code>encoding</code> is specified, a string is returned; otherwise a <a href="buffer.html"><code>Buffer</code></a> is
|
|
returned.</p>
|
|
<h3><code>ecdh.setPrivateKey(privateKey[, encoding])</code><span><a class="mark" href="#crypto_ecdh_setprivatekey_privatekey_encoding" id="crypto_ecdh_setprivatekey_privatekey_encoding">#</a></span></h3>
|
|
<div class="api_metadata">
|
|
<span>Added in: v0.11.14</span>
|
|
</div>
|
|
<ul>
|
|
<li><code>privateKey</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> | <a href="buffer.html#buffer_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></li>
|
|
<li><code>encoding</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> The <a href="buffer.html#buffer_buffers_and_character_encodings">encoding</a> of the <code>privateKey</code> string.</li>
|
|
</ul>
|
|
<p>Sets the EC Diffie-Hellman private key.
|
|
If <code>encoding</code> is provided, <code>privateKey</code> is expected
|
|
to be a string; otherwise <code>privateKey</code> is expected to be a <a href="buffer.html"><code>Buffer</code></a>,
|
|
<code>TypedArray</code>, or <code>DataView</code>.</p>
|
|
<p>If <code>privateKey</code> is not valid for the curve specified when the <code>ECDH</code> object was
|
|
created, an error is thrown. Upon setting the private key, the associated
|
|
public point (key) is also generated and set in the <code>ECDH</code> object.</p>
|
|
<h3><code>ecdh.setPublicKey(publicKey[, encoding])</code><span><a class="mark" href="#crypto_ecdh_setpublickey_publickey_encoding" id="crypto_ecdh_setpublickey_publickey_encoding">#</a></span></h3>
|
|
<div class="api_metadata">
|
|
<span>Added in: v0.11.14</span><span>Deprecated since: v5.2.0</span>
|
|
</div>
|
|
<p></p><div class="api_stability api_stability_0"><a href="documentation.html#documentation_stability_index">Stability: 0</a> - Deprecated</div><p></p>
|
|
<ul>
|
|
<li><code>publicKey</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> | <a href="buffer.html#buffer_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></li>
|
|
<li><code>encoding</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> The <a href="buffer.html#buffer_buffers_and_character_encodings">encoding</a> of the <code>publicKey</code> string.</li>
|
|
</ul>
|
|
<p>Sets the EC Diffie-Hellman public key.
|
|
If <code>encoding</code> is provided <code>publicKey</code> is expected to
|
|
be a string; otherwise a <a href="buffer.html"><code>Buffer</code></a>, <code>TypedArray</code>, or <code>DataView</code> is expected.</p>
|
|
<p>There is not normally a reason to call this method because <code>ECDH</code>
|
|
only requires a private key and the other party's public key to compute the
|
|
shared secret. Typically either <a href="#crypto_ecdh_generatekeys_encoding_format"><code>ecdh.generateKeys()</code></a> or
|
|
<a href="#crypto_ecdh_setprivatekey_privatekey_encoding"><code>ecdh.setPrivateKey()</code></a> will be called. The <a href="#crypto_ecdh_setprivatekey_privatekey_encoding"><code>ecdh.setPrivateKey()</code></a> method
|
|
attempts to generate the public point/key associated with the private key being
|
|
set.</p>
|
|
<p>Example (obtaining a shared secret):</p>
|
|
<pre><code class="language-js"><span class="hljs-keyword">const</span> crypto = <span class="hljs-built_in">require</span>(<span class="hljs-string">'crypto'</span>);
|
|
<span class="hljs-keyword">const</span> alice = crypto.createECDH(<span class="hljs-string">'secp256k1'</span>);
|
|
<span class="hljs-keyword">const</span> bob = crypto.createECDH(<span class="hljs-string">'secp256k1'</span>);
|
|
|
|
<span class="hljs-comment">// This is a shortcut way of specifying one of Alice's previous private</span>
|
|
<span class="hljs-comment">// keys. It would be unwise to use such a predictable private key in a real</span>
|
|
<span class="hljs-comment">// application.</span>
|
|
alice.setPrivateKey(
|
|
crypto.createHash(<span class="hljs-string">'sha256'</span>).update(<span class="hljs-string">'alice'</span>, <span class="hljs-string">'utf8'</span>).digest()
|
|
);
|
|
|
|
<span class="hljs-comment">// Bob uses a newly generated cryptographically strong</span>
|
|
<span class="hljs-comment">// pseudorandom key pair</span>
|
|
bob.generateKeys();
|
|
|
|
<span class="hljs-keyword">const</span> aliceSecret = alice.computeSecret(bob.getPublicKey(), <span class="hljs-literal">null</span>, <span class="hljs-string">'hex'</span>);
|
|
<span class="hljs-keyword">const</span> bobSecret = bob.computeSecret(alice.getPublicKey(), <span class="hljs-literal">null</span>, <span class="hljs-string">'hex'</span>);
|
|
|
|
<span class="hljs-comment">// aliceSecret and bobSecret should be the same shared secret value</span>
|
|
<span class="hljs-built_in">console</span>.log(aliceSecret === bobSecret);</code></pre>
|
|
<h2>Class: <code>Hash</code><span><a class="mark" href="#crypto_class_hash" id="crypto_class_hash">#</a></span></h2>
|
|
<div class="api_metadata">
|
|
<span>Added in: v0.1.92</span>
|
|
</div>
|
|
<ul>
|
|
<li>Extends: <a href="stream.html#stream_class_stream_transform" class="type"><stream.Transform></a></li>
|
|
</ul>
|
|
<p>The <code>Hash</code> class is a utility for creating hash digests of data. It can be
|
|
used in one of two ways:</p>
|
|
<ul>
|
|
<li>As a <a href="stream.html">stream</a> that is both readable and writable, where data is written
|
|
to produce a computed hash digest on the readable side, or</li>
|
|
<li>Using the <a href="#crypto_hash_update_data_inputencoding"><code>hash.update()</code></a> and <a href="#crypto_hash_digest_encoding"><code>hash.digest()</code></a> methods to produce the
|
|
computed hash.</li>
|
|
</ul>
|
|
<p>The <a href="#crypto_crypto_createhash_algorithm_options"><code>crypto.createHash()</code></a> method is used to create <code>Hash</code> instances. <code>Hash</code>
|
|
objects are not to be created directly using the <code>new</code> keyword.</p>
|
|
<p>Example: Using <code>Hash</code> objects as streams:</p>
|
|
<pre><code class="language-js"><span class="hljs-keyword">const</span> crypto = <span class="hljs-built_in">require</span>(<span class="hljs-string">'crypto'</span>);
|
|
<span class="hljs-keyword">const</span> hash = crypto.createHash(<span class="hljs-string">'sha256'</span>);
|
|
|
|
hash.on(<span class="hljs-string">'readable'</span>, <span class="hljs-function">() =></span> {
|
|
<span class="hljs-comment">// Only one element is going to be produced by the</span>
|
|
<span class="hljs-comment">// hash stream.</span>
|
|
<span class="hljs-keyword">const</span> data = hash.read();
|
|
<span class="hljs-keyword">if</span> (data) {
|
|
<span class="hljs-built_in">console</span>.log(data.toString(<span class="hljs-string">'hex'</span>));
|
|
<span class="hljs-comment">// Prints:</span>
|
|
<span class="hljs-comment">// 6a2da20943931e9834fc12cfe5bb47bbd9ae43489a30726962b576f4e3993e50</span>
|
|
}
|
|
});
|
|
|
|
hash.write(<span class="hljs-string">'some data to hash'</span>);
|
|
hash.end();</code></pre>
|
|
<p>Example: Using <code>Hash</code> and piped streams:</p>
|
|
<pre><code class="language-js"><span class="hljs-keyword">const</span> crypto = <span class="hljs-built_in">require</span>(<span class="hljs-string">'crypto'</span>);
|
|
<span class="hljs-keyword">const</span> fs = <span class="hljs-built_in">require</span>(<span class="hljs-string">'fs'</span>);
|
|
<span class="hljs-keyword">const</span> hash = crypto.createHash(<span class="hljs-string">'sha256'</span>);
|
|
|
|
<span class="hljs-keyword">const</span> input = fs.createReadStream(<span class="hljs-string">'test.js'</span>);
|
|
input.pipe(hash).pipe(process.stdout);</code></pre>
|
|
<p>Example: Using the <a href="#crypto_hash_update_data_inputencoding"><code>hash.update()</code></a> and <a href="#crypto_hash_digest_encoding"><code>hash.digest()</code></a> methods:</p>
|
|
<pre><code class="language-js"><span class="hljs-keyword">const</span> crypto = <span class="hljs-built_in">require</span>(<span class="hljs-string">'crypto'</span>);
|
|
<span class="hljs-keyword">const</span> hash = crypto.createHash(<span class="hljs-string">'sha256'</span>);
|
|
|
|
hash.update(<span class="hljs-string">'some data to hash'</span>);
|
|
<span class="hljs-built_in">console</span>.log(hash.digest(<span class="hljs-string">'hex'</span>));
|
|
<span class="hljs-comment">// Prints:</span>
|
|
<span class="hljs-comment">// 6a2da20943931e9834fc12cfe5bb47bbd9ae43489a30726962b576f4e3993e50</span></code></pre>
|
|
<h3><code>hash.copy([options])</code><span><a class="mark" href="#crypto_hash_copy_options" id="crypto_hash_copy_options">#</a></span></h3>
|
|
<div class="api_metadata">
|
|
<span>Added in: v12.16.0</span>
|
|
</div>
|
|
<ul>
|
|
<li><code>options</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object" class="type"><Object></a> <a href="stream.html#stream_new_stream_transform_options"><code>stream.transform</code> options</a></li>
|
|
<li>Returns: <a href="crypto.html#crypto_class_hash" class="type"><Hash></a></li>
|
|
</ul>
|
|
<p>Creates a new <code>Hash</code> object that contains a deep copy of the internal state
|
|
of the current <code>Hash</code> object.</p>
|
|
<p>The optional <code>options</code> argument controls stream behavior. For XOF hash
|
|
functions such as <code>'shake256'</code>, the <code>outputLength</code> option can be used to
|
|
specify the desired output length in bytes.</p>
|
|
<p>An error is thrown when an attempt is made to copy the <code>Hash</code> object after
|
|
its <a href="#crypto_hash_digest_encoding"><code>hash.digest()</code></a> method has been called.</p>
|
|
<pre><code class="language-js"><span class="hljs-comment">// Calculate a rolling hash.</span>
|
|
<span class="hljs-keyword">const</span> crypto = <span class="hljs-built_in">require</span>(<span class="hljs-string">'crypto'</span>);
|
|
<span class="hljs-keyword">const</span> hash = crypto.createHash(<span class="hljs-string">'sha256'</span>);
|
|
|
|
hash.update(<span class="hljs-string">'one'</span>);
|
|
<span class="hljs-built_in">console</span>.log(hash.copy().digest(<span class="hljs-string">'hex'</span>));
|
|
|
|
hash.update(<span class="hljs-string">'two'</span>);
|
|
<span class="hljs-built_in">console</span>.log(hash.copy().digest(<span class="hljs-string">'hex'</span>));
|
|
|
|
hash.update(<span class="hljs-string">'three'</span>);
|
|
<span class="hljs-built_in">console</span>.log(hash.copy().digest(<span class="hljs-string">'hex'</span>));
|
|
|
|
<span class="hljs-comment">// Etc.</span></code></pre>
|
|
<h3><code>hash.digest([encoding])</code><span><a class="mark" href="#crypto_hash_digest_encoding" id="crypto_hash_digest_encoding">#</a></span></h3>
|
|
<div class="api_metadata">
|
|
<span>Added in: v0.1.92</span>
|
|
</div>
|
|
<ul>
|
|
<li><code>encoding</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> The <a href="buffer.html#buffer_buffers_and_character_encodings">encoding</a> of the return value.</li>
|
|
<li>Returns: <a href="buffer.html#buffer_class_buffer" class="type"><Buffer></a> | <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a></li>
|
|
</ul>
|
|
<p>Calculates the digest of all of the data passed to be hashed (using the
|
|
<a href="#crypto_hash_update_data_inputencoding"><code>hash.update()</code></a> method).
|
|
If <code>encoding</code> is provided a string will be returned; otherwise
|
|
a <a href="buffer.html"><code>Buffer</code></a> is returned.</p>
|
|
<p>The <code>Hash</code> object can not be used again after <code>hash.digest()</code> method has been
|
|
called. Multiple calls will cause an error to be thrown.</p>
|
|
<h3><code>hash.update(data[, inputEncoding])</code><span><a class="mark" href="#crypto_hash_update_data_inputencoding" id="crypto_hash_update_data_inputencoding">#</a></span></h3>
|
|
<div class="api_metadata">
|
|
<details class="changelog"><summary>History</summary>
|
|
<table>
|
|
<tbody><tr><th>Version</th><th>Changes</th></tr>
|
|
<tr><td>v6.0.0</td>
|
|
<td><p>The default <code>inputEncoding</code> changed from <code>binary</code> to <code>utf8</code>.</p></td></tr>
|
|
<tr><td>v0.1.92</td>
|
|
<td><p><span>Added in: v0.1.92</span></p></td></tr>
|
|
</tbody></table>
|
|
</details>
|
|
</div>
|
|
<ul>
|
|
<li><code>data</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> | <a href="buffer.html#buffer_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></li>
|
|
<li><code>inputEncoding</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> The <a href="buffer.html#buffer_buffers_and_character_encodings">encoding</a> of the <code>data</code> string.</li>
|
|
</ul>
|
|
<p>Updates the hash content with the given <code>data</code>, the encoding of which
|
|
is given in <code>inputEncoding</code>.
|
|
If <code>encoding</code> is not provided, and the <code>data</code> is a string, an
|
|
encoding of <code>'utf8'</code> is enforced. If <code>data</code> is a <a href="buffer.html"><code>Buffer</code></a>, <code>TypedArray</code>, or
|
|
<code>DataView</code>, then <code>inputEncoding</code> is ignored.</p>
|
|
<p>This can be called many times with new data as it is streamed.</p>
|
|
<h2>Class: <code>Hmac</code><span><a class="mark" href="#crypto_class_hmac" id="crypto_class_hmac">#</a></span></h2>
|
|
<div class="api_metadata">
|
|
<span>Added in: v0.1.94</span>
|
|
</div>
|
|
<ul>
|
|
<li>Extends: <a href="stream.html#stream_class_stream_transform" class="type"><stream.Transform></a></li>
|
|
</ul>
|
|
<p>The <code>Hmac</code> class is a utility for creating cryptographic HMAC digests. It can
|
|
be used in one of two ways:</p>
|
|
<ul>
|
|
<li>As a <a href="stream.html">stream</a> that is both readable and writable, where data is written
|
|
to produce a computed HMAC digest on the readable side, or</li>
|
|
<li>Using the <a href="#crypto_hmac_update_data_inputencoding"><code>hmac.update()</code></a> and <a href="#crypto_hmac_digest_encoding"><code>hmac.digest()</code></a> methods to produce the
|
|
computed HMAC digest.</li>
|
|
</ul>
|
|
<p>The <a href="#crypto_crypto_createhmac_algorithm_key_options"><code>crypto.createHmac()</code></a> method is used to create <code>Hmac</code> instances. <code>Hmac</code>
|
|
objects are not to be created directly using the <code>new</code> keyword.</p>
|
|
<p>Example: Using <code>Hmac</code> objects as streams:</p>
|
|
<pre><code class="language-js"><span class="hljs-keyword">const</span> crypto = <span class="hljs-built_in">require</span>(<span class="hljs-string">'crypto'</span>);
|
|
<span class="hljs-keyword">const</span> hmac = crypto.createHmac(<span class="hljs-string">'sha256'</span>, <span class="hljs-string">'a secret'</span>);
|
|
|
|
hmac.on(<span class="hljs-string">'readable'</span>, <span class="hljs-function">() =></span> {
|
|
<span class="hljs-comment">// Only one element is going to be produced by the</span>
|
|
<span class="hljs-comment">// hash stream.</span>
|
|
<span class="hljs-keyword">const</span> data = hmac.read();
|
|
<span class="hljs-keyword">if</span> (data) {
|
|
<span class="hljs-built_in">console</span>.log(data.toString(<span class="hljs-string">'hex'</span>));
|
|
<span class="hljs-comment">// Prints:</span>
|
|
<span class="hljs-comment">// 7fd04df92f636fd450bc841c9418e5825c17f33ad9c87c518115a45971f7f77e</span>
|
|
}
|
|
});
|
|
|
|
hmac.write(<span class="hljs-string">'some data to hash'</span>);
|
|
hmac.end();</code></pre>
|
|
<p>Example: Using <code>Hmac</code> and piped streams:</p>
|
|
<pre><code class="language-js"><span class="hljs-keyword">const</span> crypto = <span class="hljs-built_in">require</span>(<span class="hljs-string">'crypto'</span>);
|
|
<span class="hljs-keyword">const</span> fs = <span class="hljs-built_in">require</span>(<span class="hljs-string">'fs'</span>);
|
|
<span class="hljs-keyword">const</span> hmac = crypto.createHmac(<span class="hljs-string">'sha256'</span>, <span class="hljs-string">'a secret'</span>);
|
|
|
|
<span class="hljs-keyword">const</span> input = fs.createReadStream(<span class="hljs-string">'test.js'</span>);
|
|
input.pipe(hmac).pipe(process.stdout);</code></pre>
|
|
<p>Example: Using the <a href="#crypto_hmac_update_data_inputencoding"><code>hmac.update()</code></a> and <a href="#crypto_hmac_digest_encoding"><code>hmac.digest()</code></a> methods:</p>
|
|
<pre><code class="language-js"><span class="hljs-keyword">const</span> crypto = <span class="hljs-built_in">require</span>(<span class="hljs-string">'crypto'</span>);
|
|
<span class="hljs-keyword">const</span> hmac = crypto.createHmac(<span class="hljs-string">'sha256'</span>, <span class="hljs-string">'a secret'</span>);
|
|
|
|
hmac.update(<span class="hljs-string">'some data to hash'</span>);
|
|
<span class="hljs-built_in">console</span>.log(hmac.digest(<span class="hljs-string">'hex'</span>));
|
|
<span class="hljs-comment">// Prints:</span>
|
|
<span class="hljs-comment">// 7fd04df92f636fd450bc841c9418e5825c17f33ad9c87c518115a45971f7f77e</span></code></pre>
|
|
<h3><code>hmac.digest([encoding])</code><span><a class="mark" href="#crypto_hmac_digest_encoding" id="crypto_hmac_digest_encoding">#</a></span></h3>
|
|
<div class="api_metadata">
|
|
<span>Added in: v0.1.94</span>
|
|
</div>
|
|
<ul>
|
|
<li><code>encoding</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> The <a href="buffer.html#buffer_buffers_and_character_encodings">encoding</a> of the return value.</li>
|
|
<li>Returns: <a href="buffer.html#buffer_class_buffer" class="type"><Buffer></a> | <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a></li>
|
|
</ul>
|
|
<p>Calculates the HMAC digest of all of the data passed using <a href="#crypto_hmac_update_data_inputencoding"><code>hmac.update()</code></a>.
|
|
If <code>encoding</code> is
|
|
provided a string is returned; otherwise a <a href="buffer.html"><code>Buffer</code></a> is returned;</p>
|
|
<p>The <code>Hmac</code> object can not be used again after <code>hmac.digest()</code> has been
|
|
called. Multiple calls to <code>hmac.digest()</code> will result in an error being thrown.</p>
|
|
<h3><code>hmac.update(data[, inputEncoding])</code><span><a class="mark" href="#crypto_hmac_update_data_inputencoding" id="crypto_hmac_update_data_inputencoding">#</a></span></h3>
|
|
<div class="api_metadata">
|
|
<details class="changelog"><summary>History</summary>
|
|
<table>
|
|
<tbody><tr><th>Version</th><th>Changes</th></tr>
|
|
<tr><td>v6.0.0</td>
|
|
<td><p>The default <code>inputEncoding</code> changed from <code>binary</code> to <code>utf8</code>.</p></td></tr>
|
|
<tr><td>v0.1.94</td>
|
|
<td><p><span>Added in: v0.1.94</span></p></td></tr>
|
|
</tbody></table>
|
|
</details>
|
|
</div>
|
|
<ul>
|
|
<li><code>data</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> | <a href="buffer.html#buffer_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></li>
|
|
<li><code>inputEncoding</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> The <a href="buffer.html#buffer_buffers_and_character_encodings">encoding</a> of the <code>data</code> string.</li>
|
|
</ul>
|
|
<p>Updates the <code>Hmac</code> content with the given <code>data</code>, the encoding of which
|
|
is given in <code>inputEncoding</code>.
|
|
If <code>encoding</code> is not provided, and the <code>data</code> is a string, an
|
|
encoding of <code>'utf8'</code> is enforced. If <code>data</code> is a <a href="buffer.html"><code>Buffer</code></a>, <code>TypedArray</code>, or
|
|
<code>DataView</code>, then <code>inputEncoding</code> is ignored.</p>
|
|
<p>This can be called many times with new data as it is streamed.</p>
|
|
<h2>Class: <code>KeyObject</code><span><a class="mark" href="#crypto_class_keyobject" id="crypto_class_keyobject">#</a></span></h2>
|
|
<div class="api_metadata">
|
|
<details class="changelog"><summary>History</summary>
|
|
<table>
|
|
<tbody><tr><th>Version</th><th>Changes</th></tr>
|
|
<tr><td>v12.19.0</td>
|
|
<td><p>Instances of this class can now be passed to worker threads using <code>postMessage</code>.</p></td></tr>
|
|
<tr><td>v11.13.0</td>
|
|
<td><p>This class is now exported.</p></td></tr>
|
|
<tr><td>v11.6.0</td>
|
|
<td><p><span>Added in: v11.6.0</span></p></td></tr>
|
|
</tbody></table>
|
|
</details>
|
|
</div>
|
|
<p>Node.js uses a <code>KeyObject</code> class to represent a symmetric or asymmetric key,
|
|
and each kind of key exposes different functions. The
|
|
<a href="#crypto_crypto_createsecretkey_key"><code>crypto.createSecretKey()</code></a>, <a href="#crypto_crypto_createpublickey_key"><code>crypto.createPublicKey()</code></a> and
|
|
<a href="#crypto_crypto_createprivatekey_key"><code>crypto.createPrivateKey()</code></a> methods are used to create <code>KeyObject</code>
|
|
instances. <code>KeyObject</code> objects are not to be created directly using the <code>new</code>
|
|
keyword.</p>
|
|
<p>Most applications should consider using the new <code>KeyObject</code> API instead of
|
|
passing keys as strings or <code>Buffer</code>s due to improved security features.</p>
|
|
<p><code>KeyObject</code> instances can be passed to other threads via <a href="worker_threads.html#worker_threads_port_postmessage_value_transferlist"><code>postMessage()</code></a>.
|
|
The receiver obtains a cloned <code>KeyObject</code>, and the <code>KeyObject</code> does not need to
|
|
be listed in the <code>transferList</code> argument.</p>
|
|
<h3><code>keyObject.asymmetricKeyType</code><span><a class="mark" href="#crypto_keyobject_asymmetrickeytype" id="crypto_keyobject_asymmetrickeytype">#</a></span></h3>
|
|
<div class="api_metadata">
|
|
<details class="changelog"><summary>History</summary>
|
|
<table>
|
|
<tbody><tr><th>Version</th><th>Changes</th></tr>
|
|
<tr><td>v12.17.0</td>
|
|
<td><p>Added support for <code>'dh'</code>.</p></td></tr>
|
|
<tr><td>v12.0.0</td>
|
|
<td><p>Added support for <code>'rsa-pss'</code></p></td></tr>
|
|
<tr><td>v12.0.0</td>
|
|
<td><p>This property now returns <code>undefined</code> for KeyObject instances of unrecognized type instead of aborting.</p></td></tr>
|
|
<tr><td>v12.0.0</td>
|
|
<td><p>Added support for <code>'x25519'</code> and <code>'x448'</code></p></td></tr>
|
|
<tr><td>v12.0.0</td>
|
|
<td><p>Added support for <code>'ed25519'</code> and <code>'ed448'</code>.</p></td></tr>
|
|
<tr><td>v11.6.0</td>
|
|
<td><p><span>Added in: v11.6.0</span></p></td></tr>
|
|
</tbody></table>
|
|
</details>
|
|
</div>
|
|
<ul>
|
|
<li><a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a></li>
|
|
</ul>
|
|
<p>For asymmetric keys, this property represents the type of the key. Supported key
|
|
types are:</p>
|
|
<ul>
|
|
<li><code>'rsa'</code> (OID 1.2.840.113549.1.1.1)</li>
|
|
<li><code>'rsa-pss'</code> (OID 1.2.840.113549.1.1.10)</li>
|
|
<li><code>'dsa'</code> (OID 1.2.840.10040.4.1)</li>
|
|
<li><code>'ec'</code> (OID 1.2.840.10045.2.1)</li>
|
|
<li><code>'x25519'</code> (OID 1.3.101.110)</li>
|
|
<li><code>'x448'</code> (OID 1.3.101.111)</li>
|
|
<li><code>'ed25519'</code> (OID 1.3.101.112)</li>
|
|
<li><code>'ed448'</code> (OID 1.3.101.113)</li>
|
|
<li><code>'dh'</code> (OID 1.2.840.113549.1.3.1)</li>
|
|
</ul>
|
|
<p>This property is <code>undefined</code> for unrecognized <code>KeyObject</code> types and symmetric
|
|
keys.</p>
|
|
<h3><code>keyObject.export([options])</code><span><a class="mark" href="#crypto_keyobject_export_options" id="crypto_keyobject_export_options">#</a></span></h3>
|
|
<div class="api_metadata">
|
|
<span>Added in: v11.6.0</span>
|
|
</div>
|
|
<ul>
|
|
<li><code>options</code>: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object" class="type"><Object></a></li>
|
|
<li>Returns: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> | <a href="buffer.html#buffer_class_buffer" class="type"><Buffer></a></li>
|
|
</ul>
|
|
<p>For symmetric keys, this function allocates a <code>Buffer</code> containing the key
|
|
material and ignores any options.</p>
|
|
<p>For asymmetric keys, the <code>options</code> parameter is used to determine the export
|
|
format.</p>
|
|
<p>For public keys, the following encoding options can be used:</p>
|
|
<ul>
|
|
<li><code>type</code>: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> Must be one of <code>'pkcs1'</code> (RSA only) or <code>'spki'</code>.</li>
|
|
<li><code>format</code>: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> Must be <code>'pem'</code> or <code>'der'</code>.</li>
|
|
</ul>
|
|
<p>For private keys, the following encoding options can be used:</p>
|
|
<ul>
|
|
<li><code>type</code>: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> Must be one of <code>'pkcs1'</code> (RSA only), <code>'pkcs8'</code> or
|
|
<code>'sec1'</code> (EC only).</li>
|
|
<li><code>format</code>: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> Must be <code>'pem'</code> or <code>'der'</code>.</li>
|
|
<li><code>cipher</code>: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> If specified, the private key will be encrypted with
|
|
the given <code>cipher</code> and <code>passphrase</code> using PKCS#5 v2.0 password based
|
|
encryption.</li>
|
|
<li><code>passphrase</code>: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> | <a href="buffer.html#buffer_class_buffer" class="type"><Buffer></a> The passphrase to use for encryption, see
|
|
<code>cipher</code>.</li>
|
|
</ul>
|
|
<p>When PEM encoding was selected, the result will be a string, otherwise it will
|
|
be a buffer containing the data encoded as DER.</p>
|
|
<p>PKCS#1, SEC1, and PKCS#8 type keys can be encrypted by using a combination of
|
|
the <code>cipher</code> and <code>format</code> options. The PKCS#8 <code>type</code> can be used with any
|
|
<code>format</code> to encrypt any key algorithm (RSA, EC, or DH) by specifying a
|
|
<code>cipher</code>. PKCS#1 and SEC1 can only be encrypted by specifying a <code>cipher</code>
|
|
when the PEM <code>format</code> is used. For maximum compatibility, use PKCS#8 for
|
|
encrypted private keys. Since PKCS#8 defines its own
|
|
encryption mechanism, PEM-level encryption is not supported when encrypting
|
|
a PKCS#8 key. See <a href="https://www.rfc-editor.org/rfc/rfc5208.txt">RFC 5208</a> for PKCS#8 encryption and <a href="https://www.rfc-editor.org/rfc/rfc1421.txt">RFC 1421</a> for
|
|
PKCS#1 and SEC1 encryption.</p>
|
|
<h3><code>keyObject.symmetricKeySize</code><span><a class="mark" href="#crypto_keyobject_symmetrickeysize" id="crypto_keyobject_symmetrickeysize">#</a></span></h3>
|
|
<div class="api_metadata">
|
|
<span>Added in: v11.6.0</span>
|
|
</div>
|
|
<ul>
|
|
<li><a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><number></a></li>
|
|
</ul>
|
|
<p>For secret keys, this property represents the size of the key in bytes. This
|
|
property is <code>undefined</code> for asymmetric keys.</p>
|
|
<h3><code>keyObject.type</code><span><a class="mark" href="#crypto_keyobject_type" id="crypto_keyobject_type">#</a></span></h3>
|
|
<div class="api_metadata">
|
|
<span>Added in: v11.6.0</span>
|
|
</div>
|
|
<ul>
|
|
<li><a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a></li>
|
|
</ul>
|
|
<p>Depending on the type of this <code>KeyObject</code>, this property is either
|
|
<code>'secret'</code> for secret (symmetric) keys, <code>'public'</code> for public (asymmetric) keys
|
|
or <code>'private'</code> for private (asymmetric) keys.</p>
|
|
<h2>Class: <code>Sign</code><span><a class="mark" href="#crypto_class_sign" id="crypto_class_sign">#</a></span></h2>
|
|
<div class="api_metadata">
|
|
<span>Added in: v0.1.92</span>
|
|
</div>
|
|
<ul>
|
|
<li>Extends: <a href="stream.html#stream_class_stream_writable" class="type"><stream.Writable></a></li>
|
|
</ul>
|
|
<p>The <code>Sign</code> class is a utility for generating signatures. It can be used in one
|
|
of two ways:</p>
|
|
<ul>
|
|
<li>As a writable <a href="stream.html">stream</a>, where data to be signed is written and the
|
|
<a href="#crypto_sign_sign_privatekey_outputencoding"><code>sign.sign()</code></a> method is used to generate and return the signature, or</li>
|
|
<li>Using the <a href="#crypto_sign_update_data_inputencoding"><code>sign.update()</code></a> and <a href="#crypto_sign_sign_privatekey_outputencoding"><code>sign.sign()</code></a> methods to produce the
|
|
signature.</li>
|
|
</ul>
|
|
<p>The <a href="#crypto_crypto_createsign_algorithm_options"><code>crypto.createSign()</code></a> method is used to create <code>Sign</code> instances. The
|
|
argument is the string name of the hash function to use. <code>Sign</code> objects are not
|
|
to be created directly using the <code>new</code> keyword.</p>
|
|
<p>Example: Using <code>Sign</code> and <a href="#crypto_class_verify"><code>Verify</code></a> objects as streams:</p>
|
|
<pre><code class="language-js"><span class="hljs-keyword">const</span> crypto = <span class="hljs-built_in">require</span>(<span class="hljs-string">'crypto'</span>);
|
|
|
|
<span class="hljs-keyword">const</span> { privateKey, publicKey } = crypto.generateKeyPairSync(<span class="hljs-string">'ec'</span>, {
|
|
<span class="hljs-attr">namedCurve</span>: <span class="hljs-string">'sect239k1'</span>
|
|
});
|
|
|
|
<span class="hljs-keyword">const</span> sign = crypto.createSign(<span class="hljs-string">'SHA256'</span>);
|
|
sign.write(<span class="hljs-string">'some data to sign'</span>);
|
|
sign.end();
|
|
<span class="hljs-keyword">const</span> signature = sign.sign(privateKey, <span class="hljs-string">'hex'</span>);
|
|
|
|
<span class="hljs-keyword">const</span> verify = crypto.createVerify(<span class="hljs-string">'SHA256'</span>);
|
|
verify.write(<span class="hljs-string">'some data to sign'</span>);
|
|
verify.end();
|
|
<span class="hljs-built_in">console</span>.log(verify.verify(publicKey, signature, <span class="hljs-string">'hex'</span>));
|
|
<span class="hljs-comment">// Prints: true</span></code></pre>
|
|
<p>Example: Using the <a href="#crypto_sign_update_data_inputencoding"><code>sign.update()</code></a> and <a href="#crypto_verify_update_data_inputencoding"><code>verify.update()</code></a> methods:</p>
|
|
<pre><code class="language-js"><span class="hljs-keyword">const</span> crypto = <span class="hljs-built_in">require</span>(<span class="hljs-string">'crypto'</span>);
|
|
|
|
<span class="hljs-keyword">const</span> { privateKey, publicKey } = crypto.generateKeyPairSync(<span class="hljs-string">'rsa'</span>, {
|
|
<span class="hljs-attr">modulusLength</span>: <span class="hljs-number">2048</span>,
|
|
});
|
|
|
|
<span class="hljs-keyword">const</span> sign = crypto.createSign(<span class="hljs-string">'SHA256'</span>);
|
|
sign.update(<span class="hljs-string">'some data to sign'</span>);
|
|
sign.end();
|
|
<span class="hljs-keyword">const</span> signature = sign.sign(privateKey);
|
|
|
|
<span class="hljs-keyword">const</span> verify = crypto.createVerify(<span class="hljs-string">'SHA256'</span>);
|
|
verify.update(<span class="hljs-string">'some data to sign'</span>);
|
|
verify.end();
|
|
<span class="hljs-built_in">console</span>.log(verify.verify(publicKey, signature));
|
|
<span class="hljs-comment">// Prints: true</span></code></pre>
|
|
<h3><code>sign.sign(privateKey[, outputEncoding])</code><span><a class="mark" href="#crypto_sign_sign_privatekey_outputencoding" id="crypto_sign_sign_privatekey_outputencoding">#</a></span></h3>
|
|
<div class="api_metadata">
|
|
<details class="changelog"><summary>History</summary>
|
|
<table>
|
|
<tbody><tr><th>Version</th><th>Changes</th></tr>
|
|
<tr><td>v12.0.0</td>
|
|
<td><p>This function now supports RSA-PSS keys.</p></td></tr>
|
|
<tr><td>v11.6.0</td>
|
|
<td><p>This function now supports key objects.</p></td></tr>
|
|
<tr><td>v8.0.0</td>
|
|
<td><p>Support for RSASSA-PSS and additional options was added.</p></td></tr>
|
|
<tr><td>v0.1.92</td>
|
|
<td><p><span>Added in: v0.1.92</span></p></td></tr>
|
|
</tbody></table>
|
|
</details>
|
|
</div>
|
|
<ul>
|
|
<li><code>privateKey</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object" class="type"><Object></a> | <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> | <a href="buffer.html#buffer_class_buffer" class="type"><Buffer></a> | <a href="crypto.html#crypto_class_keyobject" class="type"><KeyObject></a>
|
|
<ul>
|
|
<li><code>dsaEncoding</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a></li>
|
|
<li><code>padding</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><integer></a></li>
|
|
<li><code>saltLength</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><integer></a></li>
|
|
</ul>
|
|
</li>
|
|
<li><code>outputEncoding</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> The <a href="buffer.html#buffer_buffers_and_character_encodings">encoding</a> of the return value.</li>
|
|
<li>Returns: <a href="buffer.html#buffer_class_buffer" class="type"><Buffer></a> | <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a></li>
|
|
</ul>
|
|
<p>Calculates the signature on all the data passed through using either
|
|
<a href="#crypto_sign_update_data_inputencoding"><code>sign.update()</code></a> or <a href="stream.html#stream_writable_write_chunk_encoding_callback"><code>sign.write()</code></a>.</p>
|
|
<p>If <code>privateKey</code> is not a <a href="#crypto_class_keyobject"><code>KeyObject</code></a>, this function behaves as if
|
|
<code>privateKey</code> had been passed to <a href="#crypto_crypto_createprivatekey_key"><code>crypto.createPrivateKey()</code></a>. If it is an
|
|
object, the following additional properties can be passed:</p>
|
|
<ul>
|
|
<li>
|
|
<p><code>dsaEncoding</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> For DSA and ECDSA, this option specifies the
|
|
format of the generated signature. It can be one of the following:</p>
|
|
<ul>
|
|
<li><code>'der'</code> (default): DER-encoded ASN.1 signature structure encoding <code>(r, s)</code>.</li>
|
|
<li><code>'ieee-p1363'</code>: Signature format <code>r || s</code> as proposed in IEEE-P1363.</li>
|
|
</ul>
|
|
</li>
|
|
<li>
|
|
<p><code>padding</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><integer></a> Optional padding value for RSA, one of the following:</p>
|
|
<ul>
|
|
<li><code>crypto.constants.RSA_PKCS1_PADDING</code> (default)</li>
|
|
<li><code>crypto.constants.RSA_PKCS1_PSS_PADDING</code></li>
|
|
</ul>
|
|
<p><code>RSA_PKCS1_PSS_PADDING</code> will use MGF1 with the same hash function
|
|
used to sign the message as specified in section 3.1 of <a href="https://www.rfc-editor.org/rfc/rfc4055.txt">RFC 4055</a>, unless
|
|
an MGF1 hash function has been specified as part of the key in compliance with
|
|
section 3.3 of <a href="https://www.rfc-editor.org/rfc/rfc4055.txt">RFC 4055</a>.</p>
|
|
</li>
|
|
<li>
|
|
<p><code>saltLength</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><integer></a> Salt length for when padding is
|
|
<code>RSA_PKCS1_PSS_PADDING</code>. The special value
|
|
<code>crypto.constants.RSA_PSS_SALTLEN_DIGEST</code> sets the salt length to the digest
|
|
size, <code>crypto.constants.RSA_PSS_SALTLEN_MAX_SIGN</code> (default) sets it to the
|
|
maximum permissible value.</p>
|
|
</li>
|
|
</ul>
|
|
<p>If <code>outputEncoding</code> is provided a string is returned; otherwise a <a href="buffer.html"><code>Buffer</code></a>
|
|
is returned.</p>
|
|
<p>The <code>Sign</code> object can not be again used after <code>sign.sign()</code> method has been
|
|
called. Multiple calls to <code>sign.sign()</code> will result in an error being thrown.</p>
|
|
<h3><code>sign.update(data[, inputEncoding])</code><span><a class="mark" href="#crypto_sign_update_data_inputencoding" id="crypto_sign_update_data_inputencoding">#</a></span></h3>
|
|
<div class="api_metadata">
|
|
<details class="changelog"><summary>History</summary>
|
|
<table>
|
|
<tbody><tr><th>Version</th><th>Changes</th></tr>
|
|
<tr><td>v6.0.0</td>
|
|
<td><p>The default <code>inputEncoding</code> changed from <code>binary</code> to <code>utf8</code>.</p></td></tr>
|
|
<tr><td>v0.1.92</td>
|
|
<td><p><span>Added in: v0.1.92</span></p></td></tr>
|
|
</tbody></table>
|
|
</details>
|
|
</div>
|
|
<ul>
|
|
<li><code>data</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> | <a href="buffer.html#buffer_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></li>
|
|
<li><code>inputEncoding</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> The <a href="buffer.html#buffer_buffers_and_character_encodings">encoding</a> of the <code>data</code> string.</li>
|
|
</ul>
|
|
<p>Updates the <code>Sign</code> content with the given <code>data</code>, the encoding of which
|
|
is given in <code>inputEncoding</code>.
|
|
If <code>encoding</code> is not provided, and the <code>data</code> is a string, an
|
|
encoding of <code>'utf8'</code> is enforced. If <code>data</code> is a <a href="buffer.html"><code>Buffer</code></a>, <code>TypedArray</code>, or
|
|
<code>DataView</code>, then <code>inputEncoding</code> is ignored.</p>
|
|
<p>This can be called many times with new data as it is streamed.</p>
|
|
<h2>Class: <code>Verify</code><span><a class="mark" href="#crypto_class_verify" id="crypto_class_verify">#</a></span></h2>
|
|
<div class="api_metadata">
|
|
<span>Added in: v0.1.92</span>
|
|
</div>
|
|
<ul>
|
|
<li>Extends: <a href="stream.html#stream_class_stream_writable" class="type"><stream.Writable></a></li>
|
|
</ul>
|
|
<p>The <code>Verify</code> class is a utility for verifying signatures. It can be used in one
|
|
of two ways:</p>
|
|
<ul>
|
|
<li>As a writable <a href="stream.html">stream</a> where written data is used to validate against the
|
|
supplied signature, or</li>
|
|
<li>Using the <a href="#crypto_verify_update_data_inputencoding"><code>verify.update()</code></a> and <a href="#crypto_verify_verify_object_signature_signatureencoding"><code>verify.verify()</code></a> methods to verify
|
|
the signature.</li>
|
|
</ul>
|
|
<p>The <a href="#crypto_crypto_createverify_algorithm_options"><code>crypto.createVerify()</code></a> method is used to create <code>Verify</code> instances.
|
|
<code>Verify</code> objects are not to be created directly using the <code>new</code> keyword.</p>
|
|
<p>See <a href="#crypto_class_sign"><code>Sign</code></a> for examples.</p>
|
|
<h3><code>verify.update(data[, inputEncoding])</code><span><a class="mark" href="#crypto_verify_update_data_inputencoding" id="crypto_verify_update_data_inputencoding">#</a></span></h3>
|
|
<div class="api_metadata">
|
|
<details class="changelog"><summary>History</summary>
|
|
<table>
|
|
<tbody><tr><th>Version</th><th>Changes</th></tr>
|
|
<tr><td>v6.0.0</td>
|
|
<td><p>The default <code>inputEncoding</code> changed from <code>binary</code> to <code>utf8</code>.</p></td></tr>
|
|
<tr><td>v0.1.92</td>
|
|
<td><p><span>Added in: v0.1.92</span></p></td></tr>
|
|
</tbody></table>
|
|
</details>
|
|
</div>
|
|
<ul>
|
|
<li><code>data</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> | <a href="buffer.html#buffer_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></li>
|
|
<li><code>inputEncoding</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> The <a href="buffer.html#buffer_buffers_and_character_encodings">encoding</a> of the <code>data</code> string.</li>
|
|
</ul>
|
|
<p>Updates the <code>Verify</code> content with the given <code>data</code>, the encoding of which
|
|
is given in <code>inputEncoding</code>.
|
|
If <code>inputEncoding</code> is not provided, and the <code>data</code> is a string, an
|
|
encoding of <code>'utf8'</code> is enforced. If <code>data</code> is a <a href="buffer.html"><code>Buffer</code></a>, <code>TypedArray</code>, or
|
|
<code>DataView</code>, then <code>inputEncoding</code> is ignored.</p>
|
|
<p>This can be called many times with new data as it is streamed.</p>
|
|
<h3><code>verify.verify(object, signature[, signatureEncoding])</code><span><a class="mark" href="#crypto_verify_verify_object_signature_signatureencoding" id="crypto_verify_verify_object_signature_signatureencoding">#</a></span></h3>
|
|
<div class="api_metadata">
|
|
<details class="changelog"><summary>History</summary>
|
|
<table>
|
|
<tbody><tr><th>Version</th><th>Changes</th></tr>
|
|
<tr><td>v12.0.0</td>
|
|
<td><p>This function now supports RSA-PSS keys.</p></td></tr>
|
|
<tr><td>v11.7.0</td>
|
|
<td><p>The key can now be a private key.</p></td></tr>
|
|
<tr><td>v8.0.0</td>
|
|
<td><p>Support for RSASSA-PSS and additional options was added.</p></td></tr>
|
|
<tr><td>v0.1.92</td>
|
|
<td><p><span>Added in: v0.1.92</span></p></td></tr>
|
|
</tbody></table>
|
|
</details>
|
|
</div>
|
|
<ul>
|
|
<li><code>object</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object" class="type"><Object></a> | <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> | <a href="buffer.html#buffer_class_buffer" class="type"><Buffer></a> | <a href="crypto.html#crypto_class_keyobject" class="type"><KeyObject></a>
|
|
<ul>
|
|
<li><code>dsaEncoding</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a></li>
|
|
<li><code>padding</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><integer></a></li>
|
|
<li><code>saltLength</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><integer></a></li>
|
|
</ul>
|
|
</li>
|
|
<li><code>signature</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> | <a href="buffer.html#buffer_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></li>
|
|
<li><code>signatureEncoding</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> The <a href="buffer.html#buffer_buffers_and_character_encodings">encoding</a> of the <code>signature</code> string.</li>
|
|
<li>Returns: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type" class="type"><boolean></a> <code>true</code> or <code>false</code> depending on the validity of the
|
|
signature for the data and public key.</li>
|
|
</ul>
|
|
<p>Verifies the provided data using the given <code>object</code> and <code>signature</code>.</p>
|
|
<p>If <code>object</code> is not a <a href="#crypto_class_keyobject"><code>KeyObject</code></a>, this function behaves as if
|
|
<code>object</code> had been passed to <a href="#crypto_crypto_createpublickey_key"><code>crypto.createPublicKey()</code></a>. If it is an
|
|
object, the following additional properties can be passed:</p>
|
|
<ul>
|
|
<li>
|
|
<p><code>dsaEncoding</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> For DSA and ECDSA, this option specifies the
|
|
format of the generated signature. It can be one of the following:</p>
|
|
<ul>
|
|
<li><code>'der'</code> (default): DER-encoded ASN.1 signature structure encoding <code>(r, s)</code>.</li>
|
|
<li><code>'ieee-p1363'</code>: Signature format <code>r || s</code> as proposed in IEEE-P1363.</li>
|
|
</ul>
|
|
</li>
|
|
<li>
|
|
<p><code>padding</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><integer></a> Optional padding value for RSA, one of the following:</p>
|
|
<ul>
|
|
<li><code>crypto.constants.RSA_PKCS1_PADDING</code> (default)</li>
|
|
<li><code>crypto.constants.RSA_PKCS1_PSS_PADDING</code></li>
|
|
</ul>
|
|
<p><code>RSA_PKCS1_PSS_PADDING</code> will use MGF1 with the same hash function
|
|
used to verify the message as specified in section 3.1 of <a href="https://www.rfc-editor.org/rfc/rfc4055.txt">RFC 4055</a>, unless
|
|
an MGF1 hash function has been specified as part of the key in compliance with
|
|
section 3.3 of <a href="https://www.rfc-editor.org/rfc/rfc4055.txt">RFC 4055</a>.</p>
|
|
</li>
|
|
<li>
|
|
<p><code>saltLength</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><integer></a> Salt length for when padding is
|
|
<code>RSA_PKCS1_PSS_PADDING</code>. The special value
|
|
<code>crypto.constants.RSA_PSS_SALTLEN_DIGEST</code> sets the salt length to the digest
|
|
size, <code>crypto.constants.RSA_PSS_SALTLEN_AUTO</code> (default) causes it to be
|
|
determined automatically.</p>
|
|
</li>
|
|
</ul>
|
|
<p>The <code>signature</code> argument is the previously calculated signature for the data, in
|
|
the <code>signatureEncoding</code>.
|
|
If a <code>signatureEncoding</code> is specified, the <code>signature</code> is expected to be a
|
|
string; otherwise <code>signature</code> is expected to be a <a href="buffer.html"><code>Buffer</code></a>,
|
|
<code>TypedArray</code>, or <code>DataView</code>.</p>
|
|
<p>The <code>verify</code> object can not be used again after <code>verify.verify()</code> has been
|
|
called. Multiple calls to <code>verify.verify()</code> will result in an error being
|
|
thrown.</p>
|
|
<p>Because public keys can be derived from private keys, a private key may
|
|
be passed instead of a public key.</p>
|
|
<h2><code>crypto</code> module methods and properties<span><a class="mark" href="#crypto_crypto_module_methods_and_properties" id="crypto_crypto_module_methods_and_properties">#</a></span></h2>
|
|
<h3><code>crypto.constants</code><span><a class="mark" href="#crypto_crypto_constants" id="crypto_crypto_constants">#</a></span></h3>
|
|
<div class="api_metadata">
|
|
<span>Added in: v6.3.0</span>
|
|
</div>
|
|
<ul>
|
|
<li>Returns: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object" class="type"><Object></a> An object containing commonly used constants for crypto and
|
|
security related operations. The specific constants currently defined are
|
|
described in <a href="#crypto_crypto_constants_1">Crypto constants</a>.</li>
|
|
</ul>
|
|
<h3><code>crypto.DEFAULT_ENCODING</code><span><a class="mark" href="#crypto_crypto_default_encoding" id="crypto_crypto_default_encoding">#</a></span></h3>
|
|
<div class="api_metadata">
|
|
<span>Added in: v0.9.3</span><span>Deprecated since: v10.0.0</span>
|
|
</div>
|
|
<p></p><div class="api_stability api_stability_0"><a href="documentation.html#documentation_stability_index">Stability: 0</a> - Deprecated</div><p></p>
|
|
<p>The default encoding to use for functions that can take either strings
|
|
or <a href="buffer.html">buffers</a>. The default value is <code>'buffer'</code>, which makes methods
|
|
default to <a href="buffer.html"><code>Buffer</code></a> objects.</p>
|
|
<p>The <code>crypto.DEFAULT_ENCODING</code> mechanism is provided for backward compatibility
|
|
with legacy programs that expect <code>'latin1'</code> to be the default encoding.</p>
|
|
<p>New applications should expect the default to be <code>'buffer'</code>.</p>
|
|
<p>This property is deprecated.</p>
|
|
<h3><code>crypto.fips</code><span><a class="mark" href="#crypto_crypto_fips" id="crypto_crypto_fips">#</a></span></h3>
|
|
<div class="api_metadata">
|
|
<span>Added in: v6.0.0</span><span>Deprecated since: v10.0.0</span>
|
|
</div>
|
|
<p></p><div class="api_stability api_stability_0"><a href="documentation.html#documentation_stability_index">Stability: 0</a> - Deprecated</div><p></p>
|
|
<p>Property for checking and controlling whether a FIPS compliant crypto provider
|
|
is currently in use. Setting to true requires a FIPS build of Node.js.</p>
|
|
<p>This property is deprecated. Please use <code>crypto.setFips()</code> and
|
|
<code>crypto.getFips()</code> instead.</p>
|
|
<h3><code>crypto.createCipher(algorithm, password[, options])</code><span><a class="mark" href="#crypto_crypto_createcipher_algorithm_password_options" id="crypto_crypto_createcipher_algorithm_password_options">#</a></span></h3>
|
|
<div class="api_metadata">
|
|
<details class="changelog"><summary>History</summary>
|
|
<table>
|
|
<tbody><tr><th>Version</th><th>Changes</th></tr>
|
|
<tr><td>v10.10.0</td>
|
|
<td><p>Ciphers in OCB mode are now supported.</p></td></tr>
|
|
<tr><td>v10.2.0</td>
|
|
<td><p>The <code>authTagLength</code> option can now be used to produce shorter authentication tags in GCM mode and defaults to 16 bytes.</p></td></tr>
|
|
<tr><td>v10.0.0</td>
|
|
<td><p><span>Deprecated since: v10.0.0</span></p></td></tr>
|
|
<tr><td>v0.1.94</td>
|
|
<td><p><span>Added in: v0.1.94</span></p></td></tr>
|
|
</tbody></table>
|
|
</details>
|
|
</div>
|
|
<p></p><div class="api_stability api_stability_0"><a href="documentation.html#documentation_stability_index">Stability: 0</a> - Deprecated: Use <a href="#crypto_crypto_createcipheriv_algorithm_key_iv_options"><code>crypto.createCipheriv()</code></a> instead.</div><p></p>
|
|
<ul>
|
|
<li><code>algorithm</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a></li>
|
|
<li><code>password</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> | <a href="buffer.html#buffer_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></li>
|
|
<li><code>options</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object" class="type"><Object></a> <a href="stream.html#stream_new_stream_transform_options"><code>stream.transform</code> options</a></li>
|
|
<li>Returns: <a href="crypto.html#crypto_class_cipher" class="type"><Cipher></a></li>
|
|
</ul>
|
|
<p>Creates and returns a <code>Cipher</code> object that uses the given <code>algorithm</code> and
|
|
<code>password</code>.</p>
|
|
<p>The <code>options</code> argument controls stream behavior and is optional except when a
|
|
cipher in CCM or OCB mode is used (e.g. <code>'aes-128-ccm'</code>). In that case, the
|
|
<code>authTagLength</code> option is required and specifies the length of the
|
|
authentication tag in bytes, see <a href="#crypto_ccm_mode">CCM mode</a>. In GCM mode, the <code>authTagLength</code>
|
|
option is not required but can be used to set the length of the authentication
|
|
tag that will be returned by <code>getAuthTag()</code> and defaults to 16 bytes.</p>
|
|
<p>The <code>algorithm</code> is dependent on OpenSSL, examples are <code>'aes192'</code>, etc. On
|
|
recent OpenSSL releases, <code>openssl list -cipher-algorithms</code>
|
|
(<code>openssl list-cipher-algorithms</code> for older versions of OpenSSL) will
|
|
display the available cipher algorithms.</p>
|
|
<p>The <code>password</code> is used to derive the cipher key and initialization vector (IV).
|
|
The value must be either a <code>'latin1'</code> encoded string, a <a href="buffer.html"><code>Buffer</code></a>, a
|
|
<code>TypedArray</code>, or a <code>DataView</code>.</p>
|
|
<p>The implementation of <code>crypto.createCipher()</code> derives keys using the OpenSSL
|
|
function <a href="https://www.openssl.org/docs/man1.1.0/crypto/EVP_BytesToKey.html"><code>EVP_BytesToKey</code></a> with the digest algorithm set to MD5, one
|
|
iteration, and no salt. The lack of salt allows dictionary attacks as the same
|
|
password always creates the same key. The low iteration count and
|
|
non-cryptographically secure hash algorithm allow passwords to be tested very
|
|
rapidly.</p>
|
|
<p>In line with OpenSSL's recommendation to use a more modern algorithm instead of
|
|
<a href="https://www.openssl.org/docs/man1.1.0/crypto/EVP_BytesToKey.html"><code>EVP_BytesToKey</code></a> it is recommended that developers derive a key and IV on
|
|
their own using <a href="#crypto_crypto_scrypt_password_salt_keylen_options_callback"><code>crypto.scrypt()</code></a> and to use <a href="#crypto_crypto_createcipheriv_algorithm_key_iv_options"><code>crypto.createCipheriv()</code></a>
|
|
to create the <code>Cipher</code> object. Users should not use ciphers with counter mode
|
|
(e.g. CTR, GCM, or CCM) in <code>crypto.createCipher()</code>. A warning is emitted when
|
|
they are used in order to avoid the risk of IV reuse that causes
|
|
vulnerabilities. For the case when IV is reused in GCM, see <a href="https://github.com/nonce-disrespect/nonce-disrespect">Nonce-Disrespecting
|
|
Adversaries</a> for details.</p>
|
|
<h3><code>crypto.createCipheriv(algorithm, key, iv[, options])</code><span><a class="mark" href="#crypto_crypto_createcipheriv_algorithm_key_iv_options" id="crypto_crypto_createcipheriv_algorithm_key_iv_options">#</a></span></h3>
|
|
<div class="api_metadata">
|
|
<details class="changelog"><summary>History</summary>
|
|
<table>
|
|
<tbody><tr><th>Version</th><th>Changes</th></tr>
|
|
<tr><td>v11.6.0</td>
|
|
<td><p>The <code>key</code> argument can now be a <code>KeyObject</code>.</p></td></tr>
|
|
<tr><td>v11.2.0</td>
|
|
<td><p>The cipher <code>chacha20-poly1305</code> is now supported.</p></td></tr>
|
|
<tr><td>v10.10.0</td>
|
|
<td><p>Ciphers in OCB mode are now supported.</p></td></tr>
|
|
<tr><td>v10.2.0</td>
|
|
<td><p>The <code>authTagLength</code> option can now be used to produce shorter authentication tags in GCM mode and defaults to 16 bytes.</p></td></tr>
|
|
<tr><td>v9.9.0</td>
|
|
<td><p>The <code>iv</code> parameter may now be <code>null</code> for ciphers which do not need an initialization vector.</p></td></tr>
|
|
<tr><td>v0.1.94</td>
|
|
<td><p><span>Added in: v0.1.94</span></p></td></tr>
|
|
</tbody></table>
|
|
</details>
|
|
</div>
|
|
<ul>
|
|
<li><code>algorithm</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a></li>
|
|
<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="buffer.html#buffer_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="crypto.html#crypto_class_keyobject" class="type"><KeyObject></a></li>
|
|
<li><code>iv</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> | <a href="buffer.html#buffer_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="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Null_type" class="type"><null></a></li>
|
|
<li><code>options</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object" class="type"><Object></a> <a href="stream.html#stream_new_stream_transform_options"><code>stream.transform</code> options</a></li>
|
|
<li>Returns: <a href="crypto.html#crypto_class_cipher" class="type"><Cipher></a></li>
|
|
</ul>
|
|
<p>Creates and returns a <code>Cipher</code> object, with the given <code>algorithm</code>, <code>key</code> and
|
|
initialization vector (<code>iv</code>).</p>
|
|
<p>The <code>options</code> argument controls stream behavior and is optional except when a
|
|
cipher in CCM or OCB mode is used (e.g. <code>'aes-128-ccm'</code>). In that case, the
|
|
<code>authTagLength</code> option is required and specifies the length of the
|
|
authentication tag in bytes, see <a href="#crypto_ccm_mode">CCM mode</a>. In GCM mode, the <code>authTagLength</code>
|
|
option is not required but can be used to set the length of the authentication
|
|
tag that will be returned by <code>getAuthTag()</code> and defaults to 16 bytes.</p>
|
|
<p>The <code>algorithm</code> is dependent on OpenSSL, examples are <code>'aes192'</code>, etc. On
|
|
recent OpenSSL releases, <code>openssl list -cipher-algorithms</code>
|
|
(<code>openssl list-cipher-algorithms</code> for older versions of OpenSSL) will
|
|
display the available cipher algorithms.</p>
|
|
<p>The <code>key</code> is the raw key used by the <code>algorithm</code> and <code>iv</code> is an
|
|
<a href="https://en.wikipedia.org/wiki/Initialization_vector">initialization vector</a>. Both arguments must be <code>'utf8'</code> encoded strings,
|
|
<a href="buffer.html">Buffers</a>, <code>TypedArray</code>, or <code>DataView</code>s. The <code>key</code> may optionally be
|
|
a <a href="#crypto_class_keyobject"><code>KeyObject</code></a> of type <code>secret</code>. If the cipher does not need
|
|
an initialization vector, <code>iv</code> may be <code>null</code>.</p>
|
|
<p>Initialization vectors should be unpredictable and unique; ideally, they will be
|
|
cryptographically random. They do not have to be secret: IVs are typically just
|
|
added to ciphertext messages unencrypted. It may sound contradictory that
|
|
something has to be unpredictable and unique, but does not have to be secret;
|
|
remember that an attacker must not be able to predict ahead of time what a
|
|
given IV will be.</p>
|
|
<h3><code>crypto.createDecipher(algorithm, password[, options])</code><span><a class="mark" href="#crypto_crypto_createdecipher_algorithm_password_options" id="crypto_crypto_createdecipher_algorithm_password_options">#</a></span></h3>
|
|
<div class="api_metadata">
|
|
<details class="changelog"><summary>History</summary>
|
|
<table>
|
|
<tbody><tr><th>Version</th><th>Changes</th></tr>
|
|
<tr><td>v10.10.0</td>
|
|
<td><p>Ciphers in OCB mode are now supported.</p></td></tr>
|
|
<tr><td>v10.0.0</td>
|
|
<td><p><span>Deprecated since: v10.0.0</span></p></td></tr>
|
|
<tr><td>v0.1.94</td>
|
|
<td><p><span>Added in: v0.1.94</span></p></td></tr>
|
|
</tbody></table>
|
|
</details>
|
|
</div>
|
|
<p></p><div class="api_stability api_stability_0"><a href="documentation.html#documentation_stability_index">Stability: 0</a> - Deprecated: Use <a href="#crypto_crypto_createdecipheriv_algorithm_key_iv_options"><code>crypto.createDecipheriv()</code></a> instead.</div><p></p>
|
|
<ul>
|
|
<li><code>algorithm</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a></li>
|
|
<li><code>password</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> | <a href="buffer.html#buffer_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></li>
|
|
<li><code>options</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object" class="type"><Object></a> <a href="stream.html#stream_new_stream_transform_options"><code>stream.transform</code> options</a></li>
|
|
<li>Returns: <a href="crypto.html#crypto_class_decipher" class="type"><Decipher></a></li>
|
|
</ul>
|
|
<p>Creates and returns a <code>Decipher</code> object that uses the given <code>algorithm</code> and
|
|
<code>password</code> (key).</p>
|
|
<p>The <code>options</code> argument controls stream behavior and is optional except when a
|
|
cipher in CCM or OCB mode is used (e.g. <code>'aes-128-ccm'</code>). In that case, the
|
|
<code>authTagLength</code> option is required and specifies the length of the
|
|
authentication tag in bytes, see <a href="#crypto_ccm_mode">CCM mode</a>.</p>
|
|
<p>The implementation of <code>crypto.createDecipher()</code> derives keys using the OpenSSL
|
|
function <a href="https://www.openssl.org/docs/man1.1.0/crypto/EVP_BytesToKey.html"><code>EVP_BytesToKey</code></a> with the digest algorithm set to MD5, one
|
|
iteration, and no salt. The lack of salt allows dictionary attacks as the same
|
|
password always creates the same key. The low iteration count and
|
|
non-cryptographically secure hash algorithm allow passwords to be tested very
|
|
rapidly.</p>
|
|
<p>In line with OpenSSL's recommendation to use a more modern algorithm instead of
|
|
<a href="https://www.openssl.org/docs/man1.1.0/crypto/EVP_BytesToKey.html"><code>EVP_BytesToKey</code></a> it is recommended that developers derive a key and IV on
|
|
their own using <a href="#crypto_crypto_scrypt_password_salt_keylen_options_callback"><code>crypto.scrypt()</code></a> and to use <a href="#crypto_crypto_createdecipheriv_algorithm_key_iv_options"><code>crypto.createDecipheriv()</code></a>
|
|
to create the <code>Decipher</code> object.</p>
|
|
<h3><code>crypto.createDecipheriv(algorithm, key, iv[, options])</code><span><a class="mark" href="#crypto_crypto_createdecipheriv_algorithm_key_iv_options" id="crypto_crypto_createdecipheriv_algorithm_key_iv_options">#</a></span></h3>
|
|
<div class="api_metadata">
|
|
<details class="changelog"><summary>History</summary>
|
|
<table>
|
|
<tbody><tr><th>Version</th><th>Changes</th></tr>
|
|
<tr><td>v11.6.0</td>
|
|
<td><p>The <code>key</code> argument can now be a <code>KeyObject</code>.</p></td></tr>
|
|
<tr><td>v11.2.0</td>
|
|
<td><p>The cipher <code>chacha20-poly1305</code> is now supported.</p></td></tr>
|
|
<tr><td>v10.10.0</td>
|
|
<td><p>Ciphers in OCB mode are now supported.</p></td></tr>
|
|
<tr><td>v10.2.0</td>
|
|
<td><p>The <code>authTagLength</code> option can now be used to restrict accepted GCM authentication tag lengths.</p></td></tr>
|
|
<tr><td>v9.9.0</td>
|
|
<td><p>The <code>iv</code> parameter may now be <code>null</code> for ciphers which do not need an initialization vector.</p></td></tr>
|
|
<tr><td>v0.1.94</td>
|
|
<td><p><span>Added in: v0.1.94</span></p></td></tr>
|
|
</tbody></table>
|
|
</details>
|
|
</div>
|
|
<ul>
|
|
<li><code>algorithm</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a></li>
|
|
<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="buffer.html#buffer_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="crypto.html#crypto_class_keyobject" class="type"><KeyObject></a></li>
|
|
<li><code>iv</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> | <a href="buffer.html#buffer_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="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Null_type" class="type"><null></a></li>
|
|
<li><code>options</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object" class="type"><Object></a> <a href="stream.html#stream_new_stream_transform_options"><code>stream.transform</code> options</a></li>
|
|
<li>Returns: <a href="crypto.html#crypto_class_decipher" class="type"><Decipher></a></li>
|
|
</ul>
|
|
<p>Creates and returns a <code>Decipher</code> object that uses the given <code>algorithm</code>, <code>key</code>
|
|
and initialization vector (<code>iv</code>).</p>
|
|
<p>The <code>options</code> argument controls stream behavior and is optional except when a
|
|
cipher in CCM or OCB mode is used (e.g. <code>'aes-128-ccm'</code>). In that case, the
|
|
<code>authTagLength</code> option is required and specifies the length of the
|
|
authentication tag in bytes, see <a href="#crypto_ccm_mode">CCM mode</a>. In GCM mode, the <code>authTagLength</code>
|
|
option is not required but can be used to restrict accepted authentication tags
|
|
to those with the specified length.</p>
|
|
<p>The <code>algorithm</code> is dependent on OpenSSL, examples are <code>'aes192'</code>, etc. On
|
|
recent OpenSSL releases, <code>openssl list -cipher-algorithms</code>
|
|
(<code>openssl list-cipher-algorithms</code> for older versions of OpenSSL) will
|
|
display the available cipher algorithms.</p>
|
|
<p>The <code>key</code> is the raw key used by the <code>algorithm</code> and <code>iv</code> is an
|
|
<a href="https://en.wikipedia.org/wiki/Initialization_vector">initialization vector</a>. Both arguments must be <code>'utf8'</code> encoded strings,
|
|
<a href="buffer.html">Buffers</a>, <code>TypedArray</code>, or <code>DataView</code>s. The <code>key</code> may optionally be
|
|
a <a href="#crypto_class_keyobject"><code>KeyObject</code></a> of type <code>secret</code>. If the cipher does not need
|
|
an initialization vector, <code>iv</code> may be <code>null</code>.</p>
|
|
<p>Initialization vectors should be unpredictable and unique; ideally, they will be
|
|
cryptographically random. They do not have to be secret: IVs are typically just
|
|
added to ciphertext messages unencrypted. It may sound contradictory that
|
|
something has to be unpredictable and unique, but does not have to be secret;
|
|
remember that an attacker must not be able to predict ahead of time what a given
|
|
IV will be.</p>
|
|
<h3><code>crypto.createDiffieHellman(prime[, primeEncoding][, generator][, generatorEncoding])</code><span><a class="mark" href="#crypto_crypto_creatediffiehellman_prime_primeencoding_generator_generatorencoding" id="crypto_crypto_creatediffiehellman_prime_primeencoding_generator_generatorencoding">#</a></span></h3>
|
|
<div class="api_metadata">
|
|
<details class="changelog"><summary>History</summary>
|
|
<table>
|
|
<tbody><tr><th>Version</th><th>Changes</th></tr>
|
|
<tr><td>v8.0.0</td>
|
|
<td><p>The <code>prime</code> argument can be any <code>TypedArray</code> or <code>DataView</code> now.</p></td></tr>
|
|
<tr><td>v8.0.0</td>
|
|
<td><p>The <code>prime</code> argument can be a <code>Uint8Array</code> now.</p></td></tr>
|
|
<tr><td>v6.0.0</td>
|
|
<td><p>The default for the encoding parameters changed from <code>binary</code> to <code>utf8</code>.</p></td></tr>
|
|
<tr><td>v0.11.12</td>
|
|
<td><p><span>Added in: v0.11.12</span></p></td></tr>
|
|
</tbody></table>
|
|
</details>
|
|
</div>
|
|
<ul>
|
|
<li><code>prime</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> | <a href="buffer.html#buffer_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></li>
|
|
<li><code>primeEncoding</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> The <a href="buffer.html#buffer_buffers_and_character_encodings">encoding</a> of the <code>prime</code> string.</li>
|
|
<li><code>generator</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><number></a> | <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> | <a href="buffer.html#buffer_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> <strong>Default:</strong>
|
|
<code>2</code></li>
|
|
<li><code>generatorEncoding</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> The <a href="buffer.html#buffer_buffers_and_character_encodings">encoding</a> of the <code>generator</code> string.</li>
|
|
<li>Returns: <a href="crypto.html#crypto_class_diffiehellman" class="type"><DiffieHellman></a></li>
|
|
</ul>
|
|
<p>Creates a <code>DiffieHellman</code> key exchange object using the supplied <code>prime</code> and an
|
|
optional specific <code>generator</code>.</p>
|
|
<p>The <code>generator</code> argument can be a number, string, or <a href="buffer.html"><code>Buffer</code></a>. If
|
|
<code>generator</code> is not specified, the value <code>2</code> is used.</p>
|
|
<p>If <code>primeEncoding</code> is specified, <code>prime</code> is expected to be a string; otherwise
|
|
a <a href="buffer.html"><code>Buffer</code></a>, <code>TypedArray</code>, or <code>DataView</code> is expected.</p>
|
|
<p>If <code>generatorEncoding</code> is specified, <code>generator</code> is expected to be a string;
|
|
otherwise a number, <a href="buffer.html"><code>Buffer</code></a>, <code>TypedArray</code>, or <code>DataView</code> is expected.</p>
|
|
<h3><code>crypto.createDiffieHellman(primeLength[, generator])</code><span><a class="mark" href="#crypto_crypto_creatediffiehellman_primelength_generator" id="crypto_crypto_creatediffiehellman_primelength_generator">#</a></span></h3>
|
|
<div class="api_metadata">
|
|
<span>Added in: v0.5.0</span>
|
|
</div>
|
|
<ul>
|
|
<li><code>primeLength</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><number></a></li>
|
|
<li><code>generator</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><number></a> <strong>Default:</strong> <code>2</code></li>
|
|
<li>Returns: <a href="crypto.html#crypto_class_diffiehellman" class="type"><DiffieHellman></a></li>
|
|
</ul>
|
|
<p>Creates a <code>DiffieHellman</code> key exchange object and generates a prime of
|
|
<code>primeLength</code> bits using an optional specific numeric <code>generator</code>.
|
|
If <code>generator</code> is not specified, the value <code>2</code> is used.</p>
|
|
<h3><code>crypto.createDiffieHellmanGroup(name)</code><span><a class="mark" href="#crypto_crypto_creatediffiehellmangroup_name" id="crypto_crypto_creatediffiehellmangroup_name">#</a></span></h3>
|
|
<div class="api_metadata">
|
|
<span>Added in: v0.9.3</span>
|
|
</div>
|
|
<ul>
|
|
<li><code>name</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a></li>
|
|
<li>Returns: <a href="crypto.html#crypto_class_diffiehellmangroup" class="type"><DiffieHellmanGroup></a></li>
|
|
</ul>
|
|
<p>An alias for <a href="#crypto_crypto_getdiffiehellman_groupname"><code>crypto.getDiffieHellman()</code></a></p>
|
|
<h3><code>crypto.createECDH(curveName)</code><span><a class="mark" href="#crypto_crypto_createecdh_curvename" id="crypto_crypto_createecdh_curvename">#</a></span></h3>
|
|
<div class="api_metadata">
|
|
<span>Added in: v0.11.14</span>
|
|
</div>
|
|
<ul>
|
|
<li><code>curveName</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a></li>
|
|
<li>Returns: <a href="crypto.html#crypto_class_ecdh" class="type"><ECDH></a></li>
|
|
</ul>
|
|
<p>Creates an Elliptic Curve Diffie-Hellman (<code>ECDH</code>) key exchange object using a
|
|
predefined curve specified by the <code>curveName</code> string. Use
|
|
<a href="#crypto_crypto_getcurves"><code>crypto.getCurves()</code></a> to obtain a list of available curve names. On recent
|
|
OpenSSL releases, <code>openssl ecparam -list_curves</code> will also display the name
|
|
and description of each available elliptic curve.</p>
|
|
<h3><code>crypto.createHash(algorithm[, options])</code><span><a class="mark" href="#crypto_crypto_createhash_algorithm_options" id="crypto_crypto_createhash_algorithm_options">#</a></span></h3>
|
|
<div class="api_metadata">
|
|
<details class="changelog"><summary>History</summary>
|
|
<table>
|
|
<tbody><tr><th>Version</th><th>Changes</th></tr>
|
|
<tr><td>v12.8.0</td>
|
|
<td><p>The <code>outputLength</code> option was added for XOF hash functions.</p></td></tr>
|
|
<tr><td>v0.1.92</td>
|
|
<td><p><span>Added in: v0.1.92</span></p></td></tr>
|
|
</tbody></table>
|
|
</details>
|
|
</div>
|
|
<ul>
|
|
<li><code>algorithm</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a></li>
|
|
<li><code>options</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object" class="type"><Object></a> <a href="stream.html#stream_new_stream_transform_options"><code>stream.transform</code> options</a></li>
|
|
<li>Returns: <a href="crypto.html#crypto_class_hash" class="type"><Hash></a></li>
|
|
</ul>
|
|
<p>Creates and returns a <code>Hash</code> object that can be used to generate hash digests
|
|
using the given <code>algorithm</code>. Optional <code>options</code> argument controls stream
|
|
behavior. For XOF hash functions such as <code>'shake256'</code>, the <code>outputLength</code> option
|
|
can be used to specify the desired output length in bytes.</p>
|
|
<p>The <code>algorithm</code> is dependent on the available algorithms supported by the
|
|
version of OpenSSL on the platform. Examples are <code>'sha256'</code>, <code>'sha512'</code>, etc.
|
|
On recent releases of OpenSSL, <code>openssl list -digest-algorithms</code>
|
|
(<code>openssl list-message-digest-algorithms</code> for older versions of OpenSSL) will
|
|
display the available digest algorithms.</p>
|
|
<p>Example: generating the sha256 sum of a file</p>
|
|
<pre><code class="language-js"><span class="hljs-keyword">const</span> filename = process.argv[<span class="hljs-number">2</span>];
|
|
<span class="hljs-keyword">const</span> crypto = <span class="hljs-built_in">require</span>(<span class="hljs-string">'crypto'</span>);
|
|
<span class="hljs-keyword">const</span> fs = <span class="hljs-built_in">require</span>(<span class="hljs-string">'fs'</span>);
|
|
|
|
<span class="hljs-keyword">const</span> hash = crypto.createHash(<span class="hljs-string">'sha256'</span>);
|
|
|
|
<span class="hljs-keyword">const</span> input = fs.createReadStream(filename);
|
|
input.on(<span class="hljs-string">'readable'</span>, <span class="hljs-function">() =></span> {
|
|
<span class="hljs-comment">// Only one element is going to be produced by the</span>
|
|
<span class="hljs-comment">// hash stream.</span>
|
|
<span class="hljs-keyword">const</span> data = input.read();
|
|
<span class="hljs-keyword">if</span> (data)
|
|
hash.update(data);
|
|
<span class="hljs-keyword">else</span> {
|
|
<span class="hljs-built_in">console</span>.log(<span class="hljs-string">`<span class="hljs-subst">${hash.digest(<span class="hljs-string">'hex'</span>)}</span> <span class="hljs-subst">${filename}</span>`</span>);
|
|
}
|
|
});</code></pre>
|
|
<h3><code>crypto.createHmac(algorithm, key[, options])</code><span><a class="mark" href="#crypto_crypto_createhmac_algorithm_key_options" id="crypto_crypto_createhmac_algorithm_key_options">#</a></span></h3>
|
|
<div class="api_metadata">
|
|
<details class="changelog"><summary>History</summary>
|
|
<table>
|
|
<tbody><tr><th>Version</th><th>Changes</th></tr>
|
|
<tr><td>v11.6.0</td>
|
|
<td><p>The <code>key</code> argument can now be a <code>KeyObject</code>.</p></td></tr>
|
|
<tr><td>v0.1.94</td>
|
|
<td><p><span>Added in: v0.1.94</span></p></td></tr>
|
|
</tbody></table>
|
|
</details>
|
|
</div>
|
|
<ul>
|
|
<li><code>algorithm</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a></li>
|
|
<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="buffer.html#buffer_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="crypto.html#crypto_class_keyobject" class="type"><KeyObject></a></li>
|
|
<li><code>options</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object" class="type"><Object></a> <a href="stream.html#stream_new_stream_transform_options"><code>stream.transform</code> options</a></li>
|
|
<li>Returns: <a href="crypto.html#crypto_class_hmac" class="type"><Hmac></a></li>
|
|
</ul>
|
|
<p>Creates and returns an <code>Hmac</code> object that uses the given <code>algorithm</code> and <code>key</code>.
|
|
Optional <code>options</code> argument controls stream behavior.</p>
|
|
<p>The <code>algorithm</code> is dependent on the available algorithms supported by the
|
|
version of OpenSSL on the platform. Examples are <code>'sha256'</code>, <code>'sha512'</code>, etc.
|
|
On recent releases of OpenSSL, <code>openssl list -digest-algorithms</code>
|
|
(<code>openssl list-message-digest-algorithms</code> for older versions of OpenSSL) will
|
|
display the available digest algorithms.</p>
|
|
<p>The <code>key</code> is the HMAC key used to generate the cryptographic HMAC hash. If it is
|
|
a <a href="#crypto_class_keyobject"><code>KeyObject</code></a>, its type must be <code>secret</code>.</p>
|
|
<p>Example: generating the sha256 HMAC of a file</p>
|
|
<pre><code class="language-js"><span class="hljs-keyword">const</span> filename = process.argv[<span class="hljs-number">2</span>];
|
|
<span class="hljs-keyword">const</span> crypto = <span class="hljs-built_in">require</span>(<span class="hljs-string">'crypto'</span>);
|
|
<span class="hljs-keyword">const</span> fs = <span class="hljs-built_in">require</span>(<span class="hljs-string">'fs'</span>);
|
|
|
|
<span class="hljs-keyword">const</span> hmac = crypto.createHmac(<span class="hljs-string">'sha256'</span>, <span class="hljs-string">'a secret'</span>);
|
|
|
|
<span class="hljs-keyword">const</span> input = fs.createReadStream(filename);
|
|
input.on(<span class="hljs-string">'readable'</span>, <span class="hljs-function">() =></span> {
|
|
<span class="hljs-comment">// Only one element is going to be produced by the</span>
|
|
<span class="hljs-comment">// hash stream.</span>
|
|
<span class="hljs-keyword">const</span> data = input.read();
|
|
<span class="hljs-keyword">if</span> (data)
|
|
hmac.update(data);
|
|
<span class="hljs-keyword">else</span> {
|
|
<span class="hljs-built_in">console</span>.log(<span class="hljs-string">`<span class="hljs-subst">${hmac.digest(<span class="hljs-string">'hex'</span>)}</span> <span class="hljs-subst">${filename}</span>`</span>);
|
|
}
|
|
});</code></pre>
|
|
<h3><code>crypto.createPrivateKey(key)</code><span><a class="mark" href="#crypto_crypto_createprivatekey_key" id="crypto_crypto_createprivatekey_key">#</a></span></h3>
|
|
<div class="api_metadata">
|
|
<span>Added in: v11.6.0</span>
|
|
</div>
|
|
<ul>
|
|
<li><code>key</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object" class="type"><Object></a> | <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> | <a href="buffer.html#buffer_class_buffer" class="type"><Buffer></a>
|
|
<ul>
|
|
<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="buffer.html#buffer_class_buffer" class="type"><Buffer></a> The key material, either in PEM or DER format.</li>
|
|
<li><code>format</code>: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> Must be <code>'pem'</code> or <code>'der'</code>. <strong>Default:</strong> <code>'pem'</code>.</li>
|
|
<li><code>type</code>: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> Must be <code>'pkcs1'</code>, <code>'pkcs8'</code> or <code>'sec1'</code>. This option is
|
|
required only if the <code>format</code> is <code>'der'</code> and ignored if it is <code>'pem'</code>.</li>
|
|
<li><code>passphrase</code>: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> | <a href="buffer.html#buffer_class_buffer" class="type"><Buffer></a> The passphrase to use for decryption.</li>
|
|
</ul>
|
|
</li>
|
|
<li>Returns: <a href="crypto.html#crypto_class_keyobject" class="type"><KeyObject></a></li>
|
|
</ul>
|
|
<p>Creates and returns a new key object containing a private key. If <code>key</code> is a
|
|
string or <code>Buffer</code>, <code>format</code> is assumed to be <code>'pem'</code>; otherwise, <code>key</code>
|
|
must be an object with the properties described above.</p>
|
|
<p>If the private key is encrypted, a <code>passphrase</code> must be specified. The length
|
|
of the passphrase is limited to 1024 bytes.</p>
|
|
<h3><code>crypto.createPublicKey(key)</code><span><a class="mark" href="#crypto_crypto_createpublickey_key" id="crypto_crypto_createpublickey_key">#</a></span></h3>
|
|
<div class="api_metadata">
|
|
<details class="changelog"><summary>History</summary>
|
|
<table>
|
|
<tbody><tr><th>Version</th><th>Changes</th></tr>
|
|
<tr><td>v11.13.0</td>
|
|
<td><p>The <code>key</code> argument can now be a <code>KeyObject</code> with type <code>private</code>.</p></td></tr>
|
|
<tr><td>v11.7.0</td>
|
|
<td><p>The <code>key</code> argument can now be a private key.</p></td></tr>
|
|
<tr><td>v11.6.0</td>
|
|
<td><p><span>Added in: v11.6.0</span></p></td></tr>
|
|
</tbody></table>
|
|
</details>
|
|
</div>
|
|
<ul>
|
|
<li><code>key</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object" class="type"><Object></a> | <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> | <a href="buffer.html#buffer_class_buffer" class="type"><Buffer></a> | <a href="crypto.html#crypto_class_keyobject" class="type"><KeyObject></a>
|
|
<ul>
|
|
<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="buffer.html#buffer_class_buffer" class="type"><Buffer></a></li>
|
|
<li><code>format</code>: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> Must be <code>'pem'</code> or <code>'der'</code>. <strong>Default:</strong> <code>'pem'</code>.</li>
|
|
<li><code>type</code>: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> Must be <code>'pkcs1'</code> or <code>'spki'</code>. This option is required
|
|
only if the <code>format</code> is <code>'der'</code>.</li>
|
|
</ul>
|
|
</li>
|
|
<li>Returns: <a href="crypto.html#crypto_class_keyobject" class="type"><KeyObject></a></li>
|
|
</ul>
|
|
<p>Creates and returns a new key object containing a public key. If <code>key</code> is a
|
|
string or <code>Buffer</code>, <code>format</code> is assumed to be <code>'pem'</code>; if <code>key</code> is a <code>KeyObject</code>
|
|
with type <code>'private'</code>, the public key is derived from the given private key;
|
|
otherwise, <code>key</code> must be an object with the properties described above.</p>
|
|
<p>If the format is <code>'pem'</code>, the <code>'key'</code> may also be an X.509 certificate.</p>
|
|
<p>Because public keys can be derived from private keys, a private key may be
|
|
passed instead of a public key. In that case, this function behaves as if
|
|
<a href="#crypto_crypto_createprivatekey_key"><code>crypto.createPrivateKey()</code></a> had been called, except that the type of the
|
|
returned <code>KeyObject</code> will be <code>'public'</code> and that the private key cannot be
|
|
extracted from the returned <code>KeyObject</code>. Similarly, if a <code>KeyObject</code> with type
|
|
<code>'private'</code> is given, a new <code>KeyObject</code> with type <code>'public'</code> will be returned
|
|
and it will be impossible to extract the private key from the returned object.</p>
|
|
<h3><code>crypto.createSecretKey(key)</code><span><a class="mark" href="#crypto_crypto_createsecretkey_key" id="crypto_crypto_createsecretkey_key">#</a></span></h3>
|
|
<div class="api_metadata">
|
|
<span>Added in: v11.6.0</span>
|
|
</div>
|
|
<ul>
|
|
<li><code>key</code> <a href="buffer.html#buffer_class_buffer" class="type"><Buffer></a></li>
|
|
<li>Returns: <a href="crypto.html#crypto_class_keyobject" class="type"><KeyObject></a></li>
|
|
</ul>
|
|
<p>Creates and returns a new key object containing a secret key for symmetric
|
|
encryption or <code>Hmac</code>.</p>
|
|
<h3><code>crypto.createSign(algorithm[, options])</code><span><a class="mark" href="#crypto_crypto_createsign_algorithm_options" id="crypto_crypto_createsign_algorithm_options">#</a></span></h3>
|
|
<div class="api_metadata">
|
|
<span>Added in: v0.1.92</span>
|
|
</div>
|
|
<ul>
|
|
<li><code>algorithm</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a></li>
|
|
<li><code>options</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object" class="type"><Object></a> <a href="stream.html#stream_new_stream_writable_options"><code>stream.Writable</code> options</a></li>
|
|
<li>Returns: <a href="crypto.html#crypto_class_sign" class="type"><Sign></a></li>
|
|
</ul>
|
|
<p>Creates and returns a <code>Sign</code> object that uses the given <code>algorithm</code>. Use
|
|
<a href="#crypto_crypto_gethashes"><code>crypto.getHashes()</code></a> to obtain the names of the available digest algorithms.
|
|
Optional <code>options</code> argument controls the <code>stream.Writable</code> behavior.</p>
|
|
<p>In some cases, a <code>Sign</code> instance can be created using the name of a signature
|
|
algorithm, such as <code>'RSA-SHA256'</code>, instead of a digest algorithm. This will use
|
|
the corresponding digest algorithm. This does not work for all signature
|
|
algorithms, such as <code>'ecdsa-with-SHA256'</code>, so it is best to always use digest
|
|
algorithm names.</p>
|
|
<h3><code>crypto.createVerify(algorithm[, options])</code><span><a class="mark" href="#crypto_crypto_createverify_algorithm_options" id="crypto_crypto_createverify_algorithm_options">#</a></span></h3>
|
|
<div class="api_metadata">
|
|
<span>Added in: v0.1.92</span>
|
|
</div>
|
|
<ul>
|
|
<li><code>algorithm</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a></li>
|
|
<li><code>options</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object" class="type"><Object></a> <a href="stream.html#stream_new_stream_writable_options"><code>stream.Writable</code> options</a></li>
|
|
<li>Returns: <a href="crypto.html#crypto_class_verify" class="type"><Verify></a></li>
|
|
</ul>
|
|
<p>Creates and returns a <code>Verify</code> object that uses the given algorithm.
|
|
Use <a href="#crypto_crypto_gethashes"><code>crypto.getHashes()</code></a> to obtain an array of names of the available
|
|
signing algorithms. Optional <code>options</code> argument controls the
|
|
<code>stream.Writable</code> behavior.</p>
|
|
<p>In some cases, a <code>Verify</code> instance can be created using the name of a signature
|
|
algorithm, such as <code>'RSA-SHA256'</code>, instead of a digest algorithm. This will use
|
|
the corresponding digest algorithm. This does not work for all signature
|
|
algorithms, such as <code>'ecdsa-with-SHA256'</code>, so it is best to always use digest
|
|
algorithm names.</p>
|
|
<h3><code>crypto.diffieHellman(options)</code><span><a class="mark" href="#crypto_crypto_diffiehellman_options" id="crypto_crypto_diffiehellman_options">#</a></span></h3>
|
|
<div class="api_metadata">
|
|
<span>Added in: v12.17.0</span>
|
|
</div>
|
|
<ul>
|
|
<li><code>options</code>: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object" class="type"><Object></a>
|
|
<ul>
|
|
<li><code>privateKey</code>: <a href="crypto.html#crypto_class_keyobject" class="type"><KeyObject></a></li>
|
|
<li><code>publicKey</code>: <a href="crypto.html#crypto_class_keyobject" class="type"><KeyObject></a></li>
|
|
</ul>
|
|
</li>
|
|
<li>Returns: <a href="buffer.html#buffer_class_buffer" class="type"><Buffer></a></li>
|
|
</ul>
|
|
<p>Computes the Diffie-Hellman secret based on a <code>privateKey</code> and a <code>publicKey</code>.
|
|
Both keys must have the same <code>asymmetricKeyType</code>, which must be one of <code>'dh'</code>
|
|
(for Diffie-Hellman), <code>'ec'</code> (for ECDH), <code>'x448'</code>, or <code>'x25519'</code> (for ECDH-ES).</p>
|
|
<h3><code>crypto.generateKeyPair(type, options, callback)</code><span><a class="mark" href="#crypto_crypto_generatekeypair_type_options_callback" id="crypto_crypto_generatekeypair_type_options_callback">#</a></span></h3>
|
|
<div class="api_metadata">
|
|
<details class="changelog"><summary>History</summary>
|
|
<table>
|
|
<tbody><tr><th>Version</th><th>Changes</th></tr>
|
|
<tr><td>v12.17.0</td>
|
|
<td><p>Add support for Diffie-Hellman.</p></td></tr>
|
|
<tr><td>v12.0.0</td>
|
|
<td><p>Add ability to generate X25519 and X448 key pairs.</p></td></tr>
|
|
<tr><td>v12.0.0</td>
|
|
<td><p>Add ability to generate Ed25519 and Ed448 key pairs.</p></td></tr>
|
|
<tr><td>v11.6.0</td>
|
|
<td><p>The <code>generateKeyPair</code> and <code>generateKeyPairSync</code> functions now produce key objects if no encoding was specified.</p></td></tr>
|
|
<tr><td>v10.12.0</td>
|
|
<td><p><span>Added in: v10.12.0</span></p></td></tr>
|
|
</tbody></table>
|
|
</details>
|
|
</div>
|
|
<ul>
|
|
<li><code>type</code>: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> Must be <code>'rsa'</code>, <code>'dsa'</code>, <code>'ec'</code>, <code>'ed25519'</code>, <code>'ed448'</code>,
|
|
<code>'x25519'</code>, <code>'x448'</code>, or <code>'dh'</code>.</li>
|
|
<li><code>options</code>: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object" class="type"><Object></a>
|
|
<ul>
|
|
<li><code>modulusLength</code>: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><number></a> Key size in bits (RSA, DSA).</li>
|
|
<li><code>publicExponent</code>: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><number></a> Public exponent (RSA). <strong>Default:</strong> <code>0x10001</code>.</li>
|
|
<li><code>divisorLength</code>: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><number></a> Size of <code>q</code> in bits (DSA).</li>
|
|
<li><code>namedCurve</code>: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> Name of the curve to use (EC).</li>
|
|
<li><code>prime</code>: <a href="buffer.html#buffer_class_buffer" class="type"><Buffer></a> The prime parameter (DH).</li>
|
|
<li><code>primeLength</code>: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><number></a> Prime length in bits (DH).</li>
|
|
<li><code>generator</code>: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><number></a> Custom generator (DH). <strong>Default:</strong> <code>2</code>.</li>
|
|
<li><code>groupName</code>: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> Diffie-Hellman group name (DH). See
|
|
<a href="#crypto_crypto_getdiffiehellman_groupname"><code>crypto.getDiffieHellman()</code></a>.</li>
|
|
<li><code>publicKeyEncoding</code>: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object" class="type"><Object></a> See <a href="#crypto_keyobject_export_options"><code>keyObject.export()</code></a>.</li>
|
|
<li><code>privateKeyEncoding</code>: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object" class="type"><Object></a> See <a href="#crypto_keyobject_export_options"><code>keyObject.export()</code></a>.</li>
|
|
</ul>
|
|
</li>
|
|
<li><code>callback</code>: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function" class="type"><Function></a>
|
|
<ul>
|
|
<li><code>err</code>: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error" class="type"><Error></a></li>
|
|
<li><code>publicKey</code>: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> | <a href="buffer.html#buffer_class_buffer" class="type"><Buffer></a> | <a href="crypto.html#crypto_class_keyobject" class="type"><KeyObject></a></li>
|
|
<li><code>privateKey</code>: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> | <a href="buffer.html#buffer_class_buffer" class="type"><Buffer></a> | <a href="crypto.html#crypto_class_keyobject" class="type"><KeyObject></a></li>
|
|
</ul>
|
|
</li>
|
|
</ul>
|
|
<p>Generates a new asymmetric key pair of the given <code>type</code>. RSA, DSA, EC, Ed25519,
|
|
Ed448, X25519, X448, and DH are currently supported.</p>
|
|
<p>If a <code>publicKeyEncoding</code> or <code>privateKeyEncoding</code> was specified, this function
|
|
behaves as if <a href="#crypto_keyobject_export_options"><code>keyObject.export()</code></a> had been called on its result. Otherwise,
|
|
the respective part of the key is returned as a <a href="#crypto_class_keyobject"><code>KeyObject</code></a>.</p>
|
|
<p>It is recommended to encode public keys as <code>'spki'</code> and private keys as
|
|
<code>'pkcs8'</code> with encryption for long-term storage:</p>
|
|
<pre><code class="language-js"><span class="hljs-keyword">const</span> { generateKeyPair } = <span class="hljs-built_in">require</span>(<span class="hljs-string">'crypto'</span>);
|
|
generateKeyPair(<span class="hljs-string">'rsa'</span>, {
|
|
<span class="hljs-attr">modulusLength</span>: <span class="hljs-number">4096</span>,
|
|
<span class="hljs-attr">publicKeyEncoding</span>: {
|
|
<span class="hljs-attr">type</span>: <span class="hljs-string">'spki'</span>,
|
|
<span class="hljs-attr">format</span>: <span class="hljs-string">'pem'</span>
|
|
},
|
|
<span class="hljs-attr">privateKeyEncoding</span>: {
|
|
<span class="hljs-attr">type</span>: <span class="hljs-string">'pkcs8'</span>,
|
|
<span class="hljs-attr">format</span>: <span class="hljs-string">'pem'</span>,
|
|
<span class="hljs-attr">cipher</span>: <span class="hljs-string">'aes-256-cbc'</span>,
|
|
<span class="hljs-attr">passphrase</span>: <span class="hljs-string">'top secret'</span>
|
|
}
|
|
}, <span class="hljs-function">(<span class="hljs-params">err, publicKey, privateKey</span>) =></span> {
|
|
<span class="hljs-comment">// Handle errors and use the generated key pair.</span>
|
|
});</code></pre>
|
|
<p>On completion, <code>callback</code> will be called with <code>err</code> set to <code>undefined</code> and
|
|
<code>publicKey</code> / <code>privateKey</code> representing the generated key pair.</p>
|
|
<p>If this method is invoked as its <a href="util.html#util_util_promisify_original"><code>util.promisify()</code></a>ed version, it returns
|
|
a <code>Promise</code> for an <code>Object</code> with <code>publicKey</code> and <code>privateKey</code> properties.</p>
|
|
<h3><code>crypto.generateKeyPairSync(type, options)</code><span><a class="mark" href="#crypto_crypto_generatekeypairsync_type_options" id="crypto_crypto_generatekeypairsync_type_options">#</a></span></h3>
|
|
<div class="api_metadata">
|
|
<details class="changelog"><summary>History</summary>
|
|
<table>
|
|
<tbody><tr><th>Version</th><th>Changes</th></tr>
|
|
<tr><td>v12.17.0</td>
|
|
<td><p>Add support for Diffie-Hellman.</p></td></tr>
|
|
<tr><td>v12.0.0</td>
|
|
<td><p>Add ability to generate Ed25519 and Ed448 key pairs.</p></td></tr>
|
|
<tr><td>v11.6.0</td>
|
|
<td><p>The <code>generateKeyPair</code> and <code>generateKeyPairSync</code> functions now produce key objects if no encoding was specified.</p></td></tr>
|
|
<tr><td>v10.12.0</td>
|
|
<td><p><span>Added in: v10.12.0</span></p></td></tr>
|
|
</tbody></table>
|
|
</details>
|
|
</div>
|
|
<ul>
|
|
<li><code>type</code>: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> Must be <code>'rsa'</code>, <code>'dsa'</code>, <code>'ec'</code>, <code>'ed25519'</code>, <code>'ed448'</code>,
|
|
<code>'x25519'</code>, <code>'x448'</code>, or <code>'dh'</code>.</li>
|
|
<li><code>options</code>: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object" class="type"><Object></a>
|
|
<ul>
|
|
<li><code>modulusLength</code>: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><number></a> Key size in bits (RSA, DSA).</li>
|
|
<li><code>publicExponent</code>: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><number></a> Public exponent (RSA). <strong>Default:</strong> <code>0x10001</code>.</li>
|
|
<li><code>divisorLength</code>: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><number></a> Size of <code>q</code> in bits (DSA).</li>
|
|
<li><code>namedCurve</code>: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> Name of the curve to use (EC).</li>
|
|
<li><code>prime</code>: <a href="buffer.html#buffer_class_buffer" class="type"><Buffer></a> The prime parameter (DH).</li>
|
|
<li><code>primeLength</code>: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><number></a> Prime length in bits (DH).</li>
|
|
<li><code>generator</code>: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><number></a> Custom generator (DH). <strong>Default:</strong> <code>2</code>.</li>
|
|
<li><code>groupName</code>: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> Diffie-Hellman group name (DH). See
|
|
<a href="#crypto_crypto_getdiffiehellman_groupname"><code>crypto.getDiffieHellman()</code></a>.</li>
|
|
<li><code>publicKeyEncoding</code>: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object" class="type"><Object></a> See <a href="#crypto_keyobject_export_options"><code>keyObject.export()</code></a>.</li>
|
|
<li><code>privateKeyEncoding</code>: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object" class="type"><Object></a> See <a href="#crypto_keyobject_export_options"><code>keyObject.export()</code></a>.</li>
|
|
</ul>
|
|
</li>
|
|
<li>Returns: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object" class="type"><Object></a>
|
|
<ul>
|
|
<li><code>publicKey</code>: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> | <a href="buffer.html#buffer_class_buffer" class="type"><Buffer></a> | <a href="crypto.html#crypto_class_keyobject" class="type"><KeyObject></a></li>
|
|
<li><code>privateKey</code>: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> | <a href="buffer.html#buffer_class_buffer" class="type"><Buffer></a> | <a href="crypto.html#crypto_class_keyobject" class="type"><KeyObject></a></li>
|
|
</ul>
|
|
</li>
|
|
</ul>
|
|
<p>Generates a new asymmetric key pair of the given <code>type</code>. RSA, DSA, EC, Ed25519,
|
|
Ed448, X25519, X448, and DH are currently supported.</p>
|
|
<p>If a <code>publicKeyEncoding</code> or <code>privateKeyEncoding</code> was specified, this function
|
|
behaves as if <a href="#crypto_keyobject_export_options"><code>keyObject.export()</code></a> had been called on its result. Otherwise,
|
|
the respective part of the key is returned as a <a href="#crypto_class_keyobject"><code>KeyObject</code></a>.</p>
|
|
<p>When encoding public keys, it is recommended to use <code>'spki'</code>. When encoding
|
|
private keys, it is recommended to use <code>'pkcs8'</code> with a strong passphrase,
|
|
and to keep the passphrase confidential.</p>
|
|
<pre><code class="language-js"><span class="hljs-keyword">const</span> { generateKeyPairSync } = <span class="hljs-built_in">require</span>(<span class="hljs-string">'crypto'</span>);
|
|
<span class="hljs-keyword">const</span> { publicKey, privateKey } = generateKeyPairSync(<span class="hljs-string">'rsa'</span>, {
|
|
<span class="hljs-attr">modulusLength</span>: <span class="hljs-number">4096</span>,
|
|
<span class="hljs-attr">publicKeyEncoding</span>: {
|
|
<span class="hljs-attr">type</span>: <span class="hljs-string">'spki'</span>,
|
|
<span class="hljs-attr">format</span>: <span class="hljs-string">'pem'</span>
|
|
},
|
|
<span class="hljs-attr">privateKeyEncoding</span>: {
|
|
<span class="hljs-attr">type</span>: <span class="hljs-string">'pkcs8'</span>,
|
|
<span class="hljs-attr">format</span>: <span class="hljs-string">'pem'</span>,
|
|
<span class="hljs-attr">cipher</span>: <span class="hljs-string">'aes-256-cbc'</span>,
|
|
<span class="hljs-attr">passphrase</span>: <span class="hljs-string">'top secret'</span>
|
|
}
|
|
});</code></pre>
|
|
<p>The return value <code>{ publicKey, privateKey }</code> represents the generated key pair.
|
|
When PEM encoding was selected, the respective key will be a string, otherwise
|
|
it will be a buffer containing the data encoded as DER.</p>
|
|
<h3><code>crypto.getCiphers()</code><span><a class="mark" href="#crypto_crypto_getciphers" id="crypto_crypto_getciphers">#</a></span></h3>
|
|
<div class="api_metadata">
|
|
<span>Added in: v0.9.3</span>
|
|
</div>
|
|
<ul>
|
|
<li>Returns: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string[]></a> An array with the names of the supported cipher
|
|
algorithms.</li>
|
|
</ul>
|
|
<pre><code class="language-js"><span class="hljs-keyword">const</span> ciphers = crypto.getCiphers();
|
|
<span class="hljs-built_in">console</span>.log(ciphers); <span class="hljs-comment">// ['aes-128-cbc', 'aes-128-ccm', ...]</span></code></pre>
|
|
<h3><code>crypto.getCurves()</code><span><a class="mark" href="#crypto_crypto_getcurves" id="crypto_crypto_getcurves">#</a></span></h3>
|
|
<div class="api_metadata">
|
|
<span>Added in: v2.3.0</span>
|
|
</div>
|
|
<ul>
|
|
<li>Returns: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string[]></a> An array with the names of the supported elliptic curves.</li>
|
|
</ul>
|
|
<pre><code class="language-js"><span class="hljs-keyword">const</span> curves = crypto.getCurves();
|
|
<span class="hljs-built_in">console</span>.log(curves); <span class="hljs-comment">// ['Oakley-EC2N-3', 'Oakley-EC2N-4', ...]</span></code></pre>
|
|
<h3><code>crypto.getDiffieHellman(groupName)</code><span><a class="mark" href="#crypto_crypto_getdiffiehellman_groupname" id="crypto_crypto_getdiffiehellman_groupname">#</a></span></h3>
|
|
<div class="api_metadata">
|
|
<span>Added in: v0.7.5</span>
|
|
</div>
|
|
<ul>
|
|
<li><code>groupName</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a></li>
|
|
<li>Returns: <a href="crypto.html#crypto_class_diffiehellmangroup" class="type"><DiffieHellmanGroup></a></li>
|
|
</ul>
|
|
<p>Creates a predefined <code>DiffieHellmanGroup</code> key exchange object. The
|
|
supported groups are: <code>'modp1'</code>, <code>'modp2'</code>, <code>'modp5'</code> (defined in
|
|
<a href="https://www.rfc-editor.org/rfc/rfc2412.txt">RFC 2412</a>, but see <a href="#crypto_support_for_weak_or_compromised_algorithms">Caveats</a>) and <code>'modp14'</code>, <code>'modp15'</code>,
|
|
<code>'modp16'</code>, <code>'modp17'</code>, <code>'modp18'</code> (defined in <a href="https://www.rfc-editor.org/rfc/rfc3526.txt">RFC 3526</a>). The
|
|
returned object mimics the interface of objects created by
|
|
<a href="#crypto_crypto_creatediffiehellman_prime_primeencoding_generator_generatorencoding"><code>crypto.createDiffieHellman()</code></a>, but will not allow changing
|
|
the keys (with <a href="#crypto_diffiehellman_setpublickey_publickey_encoding"><code>diffieHellman.setPublicKey()</code></a>, for example). The
|
|
advantage of using this method is that the parties do not have to
|
|
generate nor exchange a group modulus beforehand, saving both processor
|
|
and communication time.</p>
|
|
<p>Example (obtaining a shared secret):</p>
|
|
<pre><code class="language-js"><span class="hljs-keyword">const</span> crypto = <span class="hljs-built_in">require</span>(<span class="hljs-string">'crypto'</span>);
|
|
<span class="hljs-keyword">const</span> alice = crypto.getDiffieHellman(<span class="hljs-string">'modp14'</span>);
|
|
<span class="hljs-keyword">const</span> bob = crypto.getDiffieHellman(<span class="hljs-string">'modp14'</span>);
|
|
|
|
alice.generateKeys();
|
|
bob.generateKeys();
|
|
|
|
<span class="hljs-keyword">const</span> aliceSecret = alice.computeSecret(bob.getPublicKey(), <span class="hljs-literal">null</span>, <span class="hljs-string">'hex'</span>);
|
|
<span class="hljs-keyword">const</span> bobSecret = bob.computeSecret(alice.getPublicKey(), <span class="hljs-literal">null</span>, <span class="hljs-string">'hex'</span>);
|
|
|
|
<span class="hljs-comment">/* aliceSecret and bobSecret should be the same */</span>
|
|
<span class="hljs-built_in">console</span>.log(aliceSecret === bobSecret);</code></pre>
|
|
<h3><code>crypto.getFips()</code><span><a class="mark" href="#crypto_crypto_getfips" id="crypto_crypto_getfips">#</a></span></h3>
|
|
<div class="api_metadata">
|
|
<span>Added in: v10.0.0</span>
|
|
</div>
|
|
<ul>
|
|
<li>Returns: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><number></a> <code>1</code> if and only if a FIPS compliant crypto provider is
|
|
currently in use, <code>0</code> otherwise. A future semver-major release may change
|
|
the return type of this API to a <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type" class="type"><boolean></a>.</li>
|
|
</ul>
|
|
<h3><code>crypto.getHashes()</code><span><a class="mark" href="#crypto_crypto_gethashes" id="crypto_crypto_gethashes">#</a></span></h3>
|
|
<div class="api_metadata">
|
|
<span>Added in: v0.9.3</span>
|
|
</div>
|
|
<ul>
|
|
<li>Returns: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string[]></a> An array of the names of the supported hash algorithms,
|
|
such as <code>'RSA-SHA256'</code>. Hash algorithms are also called "digest" algorithms.</li>
|
|
</ul>
|
|
<pre><code class="language-js"><span class="hljs-keyword">const</span> hashes = crypto.getHashes();
|
|
<span class="hljs-built_in">console</span>.log(hashes); <span class="hljs-comment">// ['DSA', 'DSA-SHA', 'DSA-SHA1', ...]</span></code></pre>
|
|
<h3><code>crypto.pbkdf2(password, salt, iterations, keylen, digest, callback)</code><span><a class="mark" href="#crypto_crypto_pbkdf2_password_salt_iterations_keylen_digest_callback" id="crypto_crypto_pbkdf2_password_salt_iterations_keylen_digest_callback">#</a></span></h3>
|
|
<div class="api_metadata">
|
|
<details class="changelog"><summary>History</summary>
|
|
<table>
|
|
<tbody><tr><th>Version</th><th>Changes</th></tr>
|
|
<tr><td>v8.0.0</td>
|
|
<td><p>The <code>digest</code> parameter is always required now.</p></td></tr>
|
|
<tr><td>v6.0.0</td>
|
|
<td><p>Calling this function without passing the <code>digest</code> parameter is deprecated now and will emit a warning.</p></td></tr>
|
|
<tr><td>v6.0.0</td>
|
|
<td><p>The default encoding for <code>password</code> if it is a string changed from <code>binary</code> to <code>utf8</code>.</p></td></tr>
|
|
<tr><td>v0.5.5</td>
|
|
<td><p><span>Added in: v0.5.5</span></p></td></tr>
|
|
</tbody></table>
|
|
</details>
|
|
</div>
|
|
<ul>
|
|
<li><code>password</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> | <a href="buffer.html#buffer_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></li>
|
|
<li><code>salt</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> | <a href="buffer.html#buffer_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></li>
|
|
<li><code>iterations</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><number></a></li>
|
|
<li><code>keylen</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><number></a></li>
|
|
<li><code>digest</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a></li>
|
|
<li><code>callback</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function" class="type"><Function></a>
|
|
<ul>
|
|
<li><code>err</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error" class="type"><Error></a></li>
|
|
<li><code>derivedKey</code> <a href="buffer.html#buffer_class_buffer" class="type"><Buffer></a></li>
|
|
</ul>
|
|
</li>
|
|
</ul>
|
|
<p>Provides an asynchronous Password-Based Key Derivation Function 2 (PBKDF2)
|
|
implementation. A selected HMAC digest algorithm specified by <code>digest</code> is
|
|
applied to derive a key of the requested byte length (<code>keylen</code>) from the
|
|
<code>password</code>, <code>salt</code> and <code>iterations</code>.</p>
|
|
<p>The supplied <code>callback</code> function is called with two arguments: <code>err</code> and
|
|
<code>derivedKey</code>. If an error occurs while deriving the key, <code>err</code> will be set;
|
|
otherwise <code>err</code> will be <code>null</code>. By default, the successfully generated
|
|
<code>derivedKey</code> will be passed to the callback as a <a href="buffer.html"><code>Buffer</code></a>. An error will be
|
|
thrown if any of the input arguments specify invalid values or types.</p>
|
|
<p>If <code>digest</code> is <code>null</code>, <code>'sha1'</code> will be used. This behavior is deprecated,
|
|
please specify a <code>digest</code> explicitly.</p>
|
|
<p>The <code>iterations</code> argument must be a number set as high as possible. The
|
|
higher the number of iterations, the more secure the derived key will be,
|
|
but will take a longer amount of time to complete.</p>
|
|
<p>The <code>salt</code> should be as unique as possible. It is recommended that a salt is
|
|
random and at least 16 bytes long. See <a href="https://nvlpubs.nist.gov/nistpubs/Legacy/SP/nistspecialpublication800-132.pdf">NIST SP 800-132</a> for details.</p>
|
|
<pre><code class="language-js"><span class="hljs-keyword">const</span> crypto = <span class="hljs-built_in">require</span>(<span class="hljs-string">'crypto'</span>);
|
|
crypto.pbkdf2(<span class="hljs-string">'secret'</span>, <span class="hljs-string">'salt'</span>, <span class="hljs-number">100000</span>, <span class="hljs-number">64</span>, <span class="hljs-string">'sha512'</span>, <span class="hljs-function">(<span class="hljs-params">err, derivedKey</span>) =></span> {
|
|
<span class="hljs-keyword">if</span> (err) <span class="hljs-keyword">throw</span> err;
|
|
<span class="hljs-built_in">console</span>.log(derivedKey.toString(<span class="hljs-string">'hex'</span>)); <span class="hljs-comment">// '3745e48...08d59ae'</span>
|
|
});</code></pre>
|
|
<p>The <code>crypto.DEFAULT_ENCODING</code> property can be used to change the way the
|
|
<code>derivedKey</code> is passed to the callback. This property, however, has been
|
|
deprecated and use should be avoided.</p>
|
|
<pre><code class="language-js"><span class="hljs-keyword">const</span> crypto = <span class="hljs-built_in">require</span>(<span class="hljs-string">'crypto'</span>);
|
|
crypto.DEFAULT_ENCODING = <span class="hljs-string">'hex'</span>;
|
|
crypto.pbkdf2(<span class="hljs-string">'secret'</span>, <span class="hljs-string">'salt'</span>, <span class="hljs-number">100000</span>, <span class="hljs-number">512</span>, <span class="hljs-string">'sha512'</span>, <span class="hljs-function">(<span class="hljs-params">err, derivedKey</span>) =></span> {
|
|
<span class="hljs-keyword">if</span> (err) <span class="hljs-keyword">throw</span> err;
|
|
<span class="hljs-built_in">console</span>.log(derivedKey); <span class="hljs-comment">// '3745e48...aa39b34'</span>
|
|
});</code></pre>
|
|
<p>An array of supported digest functions can be retrieved using
|
|
<a href="#crypto_crypto_gethashes"><code>crypto.getHashes()</code></a>.</p>
|
|
<p>This API uses libuv's threadpool, which can have surprising and
|
|
negative performance implications for some applications; see the
|
|
<a href="cli.html#cli_uv_threadpool_size_size"><code>UV_THREADPOOL_SIZE</code></a> documentation for more information.</p>
|
|
<h3><code>crypto.pbkdf2Sync(password, salt, iterations, keylen, digest)</code><span><a class="mark" href="#crypto_crypto_pbkdf2sync_password_salt_iterations_keylen_digest" id="crypto_crypto_pbkdf2sync_password_salt_iterations_keylen_digest">#</a></span></h3>
|
|
<div class="api_metadata">
|
|
<details class="changelog"><summary>History</summary>
|
|
<table>
|
|
<tbody><tr><th>Version</th><th>Changes</th></tr>
|
|
<tr><td>v6.0.0</td>
|
|
<td><p>Calling this function without passing the <code>digest</code> parameter is deprecated now and will emit a warning.</p></td></tr>
|
|
<tr><td>v6.0.0</td>
|
|
<td><p>The default encoding for <code>password</code> if it is a string changed from <code>binary</code> to <code>utf8</code>.</p></td></tr>
|
|
<tr><td>v0.9.3</td>
|
|
<td><p><span>Added in: v0.9.3</span></p></td></tr>
|
|
</tbody></table>
|
|
</details>
|
|
</div>
|
|
<ul>
|
|
<li><code>password</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> | <a href="buffer.html#buffer_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></li>
|
|
<li><code>salt</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> | <a href="buffer.html#buffer_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></li>
|
|
<li><code>iterations</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><number></a></li>
|
|
<li><code>keylen</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><number></a></li>
|
|
<li><code>digest</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a></li>
|
|
<li>Returns: <a href="buffer.html#buffer_class_buffer" class="type"><Buffer></a></li>
|
|
</ul>
|
|
<p>Provides a synchronous Password-Based Key Derivation Function 2 (PBKDF2)
|
|
implementation. A selected HMAC digest algorithm specified by <code>digest</code> is
|
|
applied to derive a key of the requested byte length (<code>keylen</code>) from the
|
|
<code>password</code>, <code>salt</code> and <code>iterations</code>.</p>
|
|
<p>If an error occurs an <code>Error</code> will be thrown, otherwise the derived key will be
|
|
returned as a <a href="buffer.html"><code>Buffer</code></a>.</p>
|
|
<p>If <code>digest</code> is <code>null</code>, <code>'sha1'</code> will be used. This behavior is deprecated,
|
|
please specify a <code>digest</code> explicitly.</p>
|
|
<p>The <code>iterations</code> argument must be a number set as high as possible. The
|
|
higher the number of iterations, the more secure the derived key will be,
|
|
but will take a longer amount of time to complete.</p>
|
|
<p>The <code>salt</code> should be as unique as possible. It is recommended that a salt is
|
|
random and at least 16 bytes long. See <a href="https://nvlpubs.nist.gov/nistpubs/Legacy/SP/nistspecialpublication800-132.pdf">NIST SP 800-132</a> for details.</p>
|
|
<pre><code class="language-js"><span class="hljs-keyword">const</span> crypto = <span class="hljs-built_in">require</span>(<span class="hljs-string">'crypto'</span>);
|
|
<span class="hljs-keyword">const</span> key = crypto.pbkdf2Sync(<span class="hljs-string">'secret'</span>, <span class="hljs-string">'salt'</span>, <span class="hljs-number">100000</span>, <span class="hljs-number">64</span>, <span class="hljs-string">'sha512'</span>);
|
|
<span class="hljs-built_in">console</span>.log(key.toString(<span class="hljs-string">'hex'</span>)); <span class="hljs-comment">// '3745e48...08d59ae'</span></code></pre>
|
|
<p>The <code>crypto.DEFAULT_ENCODING</code> property may be used to change the way the
|
|
<code>derivedKey</code> is returned. This property, however, is deprecated and use
|
|
should be avoided.</p>
|
|
<pre><code class="language-js"><span class="hljs-keyword">const</span> crypto = <span class="hljs-built_in">require</span>(<span class="hljs-string">'crypto'</span>);
|
|
crypto.DEFAULT_ENCODING = <span class="hljs-string">'hex'</span>;
|
|
<span class="hljs-keyword">const</span> key = crypto.pbkdf2Sync(<span class="hljs-string">'secret'</span>, <span class="hljs-string">'salt'</span>, <span class="hljs-number">100000</span>, <span class="hljs-number">512</span>, <span class="hljs-string">'sha512'</span>);
|
|
<span class="hljs-built_in">console</span>.log(key); <span class="hljs-comment">// '3745e48...aa39b34'</span></code></pre>
|
|
<p>An array of supported digest functions can be retrieved using
|
|
<a href="#crypto_crypto_gethashes"><code>crypto.getHashes()</code></a>.</p>
|
|
<h3><code>crypto.privateDecrypt(privateKey, buffer)</code><span><a class="mark" href="#crypto_crypto_privatedecrypt_privatekey_buffer" id="crypto_crypto_privatedecrypt_privatekey_buffer">#</a></span></h3>
|
|
<div class="api_metadata">
|
|
<details class="changelog"><summary>History</summary>
|
|
<table>
|
|
<tbody><tr><th>Version</th><th>Changes</th></tr>
|
|
<tr><td>v12.11.0</td>
|
|
<td><p>The <code>oaepLabel</code> option was added.</p></td></tr>
|
|
<tr><td>v12.9.0</td>
|
|
<td><p>The <code>oaepHash</code> option was added.</p></td></tr>
|
|
<tr><td>v11.6.0</td>
|
|
<td><p>This function now supports key objects.</p></td></tr>
|
|
<tr><td>v0.11.14</td>
|
|
<td><p><span>Added in: v0.11.14</span></p></td></tr>
|
|
</tbody></table>
|
|
</details>
|
|
</div>
|
|
<ul>
|
|
<li><code>privateKey</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object" class="type"><Object></a> | <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> | <a href="buffer.html#buffer_class_buffer" class="type"><Buffer></a> | <a href="crypto.html#crypto_class_keyobject" class="type"><KeyObject></a>
|
|
<ul>
|
|
<li><code>oaepHash</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> The hash function to use for OAEP padding and MGF1.
|
|
<strong>Default:</strong> <code>'sha1'</code></li>
|
|
<li><code>oaepLabel</code> <a href="buffer.html#buffer_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> The label to use for OAEP
|
|
padding. If not specified, no label is used.</li>
|
|
<li><code>padding</code> <a href="crypto.html#crypto_crypto_constants_1" class="type"><crypto.constants></a> An optional padding value defined in
|
|
<code>crypto.constants</code>, which may be: <code>crypto.constants.RSA_NO_PADDING</code>,
|
|
<code>crypto.constants.RSA_PKCS1_PADDING</code>, or
|
|
<code>crypto.constants.RSA_PKCS1_OAEP_PADDING</code>.</li>
|
|
</ul>
|
|
</li>
|
|
<li><code>buffer</code> <a href="buffer.html#buffer_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></li>
|
|
<li>Returns: <a href="buffer.html#buffer_class_buffer" class="type"><Buffer></a> A new <code>Buffer</code> with the decrypted content.</li>
|
|
</ul>
|
|
<p>Decrypts <code>buffer</code> with <code>privateKey</code>. <code>buffer</code> was previously encrypted using
|
|
the corresponding public key, for example using <a href="#crypto_crypto_publicencrypt_key_buffer"><code>crypto.publicEncrypt()</code></a>.</p>
|
|
<p>If <code>privateKey</code> is not a <a href="#crypto_class_keyobject"><code>KeyObject</code></a>, this function behaves as if
|
|
<code>privateKey</code> had been passed to <a href="#crypto_crypto_createprivatekey_key"><code>crypto.createPrivateKey()</code></a>. If it is an
|
|
object, the <code>padding</code> property can be passed. Otherwise, this function uses
|
|
<code>RSA_PKCS1_OAEP_PADDING</code>.</p>
|
|
<h3><code>crypto.privateEncrypt(privateKey, buffer)</code><span><a class="mark" href="#crypto_crypto_privateencrypt_privatekey_buffer" id="crypto_crypto_privateencrypt_privatekey_buffer">#</a></span></h3>
|
|
<div class="api_metadata">
|
|
<details class="changelog"><summary>History</summary>
|
|
<table>
|
|
<tbody><tr><th>Version</th><th>Changes</th></tr>
|
|
<tr><td>v11.6.0</td>
|
|
<td><p>This function now supports key objects.</p></td></tr>
|
|
<tr><td>v1.1.0</td>
|
|
<td><p><span>Added in: v1.1.0</span></p></td></tr>
|
|
</tbody></table>
|
|
</details>
|
|
</div>
|
|
<ul>
|
|
<li><code>privateKey</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object" class="type"><Object></a> | <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> | <a href="buffer.html#buffer_class_buffer" class="type"><Buffer></a> | <a href="crypto.html#crypto_class_keyobject" class="type"><KeyObject></a>
|
|
<ul>
|
|
<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="buffer.html#buffer_class_buffer" class="type"><Buffer></a> | <a href="crypto.html#crypto_class_keyobject" class="type"><KeyObject></a> A PEM encoded private key.</li>
|
|
<li><code>passphrase</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> | <a href="buffer.html#buffer_class_buffer" class="type"><Buffer></a> An optional passphrase for the private key.</li>
|
|
<li><code>padding</code> <a href="crypto.html#crypto_crypto_constants_1" class="type"><crypto.constants></a> An optional padding value defined in
|
|
<code>crypto.constants</code>, which may be: <code>crypto.constants.RSA_NO_PADDING</code> or
|
|
<code>crypto.constants.RSA_PKCS1_PADDING</code>.</li>
|
|
</ul>
|
|
</li>
|
|
<li><code>buffer</code> <a href="buffer.html#buffer_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></li>
|
|
<li>Returns: <a href="buffer.html#buffer_class_buffer" class="type"><Buffer></a> A new <code>Buffer</code> with the encrypted content.</li>
|
|
</ul>
|
|
<p>Encrypts <code>buffer</code> with <code>privateKey</code>. The returned data can be decrypted using
|
|
the corresponding public key, for example using <a href="#crypto_crypto_publicdecrypt_key_buffer"><code>crypto.publicDecrypt()</code></a>.</p>
|
|
<p>If <code>privateKey</code> is not a <a href="#crypto_class_keyobject"><code>KeyObject</code></a>, this function behaves as if
|
|
<code>privateKey</code> had been passed to <a href="#crypto_crypto_createprivatekey_key"><code>crypto.createPrivateKey()</code></a>. If it is an
|
|
object, the <code>padding</code> property can be passed. Otherwise, this function uses
|
|
<code>RSA_PKCS1_PADDING</code>.</p>
|
|
<h3><code>crypto.publicDecrypt(key, buffer)</code><span><a class="mark" href="#crypto_crypto_publicdecrypt_key_buffer" id="crypto_crypto_publicdecrypt_key_buffer">#</a></span></h3>
|
|
<div class="api_metadata">
|
|
<details class="changelog"><summary>History</summary>
|
|
<table>
|
|
<tbody><tr><th>Version</th><th>Changes</th></tr>
|
|
<tr><td>v11.6.0</td>
|
|
<td><p>This function now supports key objects.</p></td></tr>
|
|
<tr><td>v1.1.0</td>
|
|
<td><p><span>Added in: v1.1.0</span></p></td></tr>
|
|
</tbody></table>
|
|
</details>
|
|
</div>
|
|
<ul>
|
|
<li><code>key</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object" class="type"><Object></a> | <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> | <a href="buffer.html#buffer_class_buffer" class="type"><Buffer></a> | <a href="crypto.html#crypto_class_keyobject" class="type"><KeyObject></a>
|
|
<ul>
|
|
<li><code>passphrase</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> | <a href="buffer.html#buffer_class_buffer" class="type"><Buffer></a> An optional passphrase for the private key.</li>
|
|
<li><code>padding</code> <a href="crypto.html#crypto_crypto_constants_1" class="type"><crypto.constants></a> An optional padding value defined in
|
|
<code>crypto.constants</code>, which may be: <code>crypto.constants.RSA_NO_PADDING</code> or
|
|
<code>crypto.constants.RSA_PKCS1_PADDING</code>.</li>
|
|
</ul>
|
|
</li>
|
|
<li><code>buffer</code> <a href="buffer.html#buffer_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></li>
|
|
<li>Returns: <a href="buffer.html#buffer_class_buffer" class="type"><Buffer></a> A new <code>Buffer</code> with the decrypted content.</li>
|
|
</ul>
|
|
<p>Decrypts <code>buffer</code> with <code>key</code>.<code>buffer</code> was previously encrypted using
|
|
the corresponding private key, for example using <a href="#crypto_crypto_privateencrypt_privatekey_buffer"><code>crypto.privateEncrypt()</code></a>.</p>
|
|
<p>If <code>key</code> is not a <a href="#crypto_class_keyobject"><code>KeyObject</code></a>, this function behaves as if
|
|
<code>key</code> had been passed to <a href="#crypto_crypto_createpublickey_key"><code>crypto.createPublicKey()</code></a>. If it is an
|
|
object, the <code>padding</code> property can be passed. Otherwise, this function uses
|
|
<code>RSA_PKCS1_PADDING</code>.</p>
|
|
<p>Because RSA public keys can be derived from private keys, a private key may
|
|
be passed instead of a public key.</p>
|
|
<h3><code>crypto.publicEncrypt(key, buffer)</code><span><a class="mark" href="#crypto_crypto_publicencrypt_key_buffer" id="crypto_crypto_publicencrypt_key_buffer">#</a></span></h3>
|
|
<div class="api_metadata">
|
|
<details class="changelog"><summary>History</summary>
|
|
<table>
|
|
<tbody><tr><th>Version</th><th>Changes</th></tr>
|
|
<tr><td>v12.11.0</td>
|
|
<td><p>The <code>oaepLabel</code> option was added.</p></td></tr>
|
|
<tr><td>v12.9.0</td>
|
|
<td><p>The <code>oaepHash</code> option was added.</p></td></tr>
|
|
<tr><td>v11.6.0</td>
|
|
<td><p>This function now supports key objects.</p></td></tr>
|
|
<tr><td>v0.11.14</td>
|
|
<td><p><span>Added in: v0.11.14</span></p></td></tr>
|
|
</tbody></table>
|
|
</details>
|
|
</div>
|
|
<ul>
|
|
<li><code>key</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object" class="type"><Object></a> | <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> | <a href="buffer.html#buffer_class_buffer" class="type"><Buffer></a> | <a href="crypto.html#crypto_class_keyobject" class="type"><KeyObject></a>
|
|
<ul>
|
|
<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="buffer.html#buffer_class_buffer" class="type"><Buffer></a> | <a href="crypto.html#crypto_class_keyobject" class="type"><KeyObject></a> A PEM encoded public or private key.</li>
|
|
<li><code>oaepHash</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> The hash function to use for OAEP padding and MGF1.
|
|
<strong>Default:</strong> <code>'sha1'</code></li>
|
|
<li><code>oaepLabel</code> <a href="buffer.html#buffer_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> The label to use for OAEP
|
|
padding. If not specified, no label is used.</li>
|
|
<li><code>passphrase</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> | <a href="buffer.html#buffer_class_buffer" class="type"><Buffer></a> An optional passphrase for the private key.</li>
|
|
<li><code>padding</code> <a href="crypto.html#crypto_crypto_constants_1" class="type"><crypto.constants></a> An optional padding value defined in
|
|
<code>crypto.constants</code>, which may be: <code>crypto.constants.RSA_NO_PADDING</code>,
|
|
<code>crypto.constants.RSA_PKCS1_PADDING</code>, or
|
|
<code>crypto.constants.RSA_PKCS1_OAEP_PADDING</code>.</li>
|
|
</ul>
|
|
</li>
|
|
<li><code>buffer</code> <a href="buffer.html#buffer_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></li>
|
|
<li>Returns: <a href="buffer.html#buffer_class_buffer" class="type"><Buffer></a> A new <code>Buffer</code> with the encrypted content.</li>
|
|
</ul>
|
|
<p>Encrypts the content of <code>buffer</code> with <code>key</code> and returns a new
|
|
<a href="buffer.html"><code>Buffer</code></a> with encrypted content. The returned data can be decrypted using
|
|
the corresponding private key, for example using <a href="#crypto_crypto_privatedecrypt_privatekey_buffer"><code>crypto.privateDecrypt()</code></a>.</p>
|
|
<p>If <code>key</code> is not a <a href="#crypto_class_keyobject"><code>KeyObject</code></a>, this function behaves as if
|
|
<code>key</code> had been passed to <a href="#crypto_crypto_createpublickey_key"><code>crypto.createPublicKey()</code></a>. If it is an
|
|
object, the <code>padding</code> property can be passed. Otherwise, this function uses
|
|
<code>RSA_PKCS1_OAEP_PADDING</code>.</p>
|
|
<p>Because RSA public keys can be derived from private keys, a private key may
|
|
be passed instead of a public key.</p>
|
|
<h3><code>crypto.randomBytes(size[, callback])</code><span><a class="mark" href="#crypto_crypto_randombytes_size_callback" id="crypto_crypto_randombytes_size_callback">#</a></span></h3>
|
|
<div class="api_metadata">
|
|
<details class="changelog"><summary>History</summary>
|
|
<table>
|
|
<tbody><tr><th>Version</th><th>Changes</th></tr>
|
|
<tr><td>v9.0.0</td>
|
|
<td><p>Passing <code>null</code> as the <code>callback</code> argument now throws <code>ERR_INVALID_CALLBACK</code>.</p></td></tr>
|
|
<tr><td>v0.5.8</td>
|
|
<td><p><span>Added in: v0.5.8</span></p></td></tr>
|
|
</tbody></table>
|
|
</details>
|
|
</div>
|
|
<ul>
|
|
<li><code>size</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><number></a></li>
|
|
<li><code>callback</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function" class="type"><Function></a>
|
|
<ul>
|
|
<li><code>err</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error" class="type"><Error></a></li>
|
|
<li><code>buf</code> <a href="buffer.html#buffer_class_buffer" class="type"><Buffer></a></li>
|
|
</ul>
|
|
</li>
|
|
<li>Returns: <a href="buffer.html#buffer_class_buffer" class="type"><Buffer></a> if the <code>callback</code> function is not provided.</li>
|
|
</ul>
|
|
<p>Generates cryptographically strong pseudo-random data. The <code>size</code> argument
|
|
is a number indicating the number of bytes to generate.</p>
|
|
<p>If a <code>callback</code> function is provided, the bytes are generated asynchronously
|
|
and the <code>callback</code> function is invoked with two arguments: <code>err</code> and <code>buf</code>.
|
|
If an error occurs, <code>err</code> will be an <code>Error</code> object; otherwise it is <code>null</code>. The
|
|
<code>buf</code> argument is a <a href="buffer.html"><code>Buffer</code></a> containing the generated bytes.</p>
|
|
<pre><code class="language-js"><span class="hljs-comment">// Asynchronous</span>
|
|
<span class="hljs-keyword">const</span> crypto = <span class="hljs-built_in">require</span>(<span class="hljs-string">'crypto'</span>);
|
|
crypto.randomBytes(<span class="hljs-number">256</span>, <span class="hljs-function">(<span class="hljs-params">err, buf</span>) =></span> {
|
|
<span class="hljs-keyword">if</span> (err) <span class="hljs-keyword">throw</span> err;
|
|
<span class="hljs-built_in">console</span>.log(<span class="hljs-string">`<span class="hljs-subst">${buf.length}</span> bytes of random data: <span class="hljs-subst">${buf.toString(<span class="hljs-string">'hex'</span>)}</span>`</span>);
|
|
});</code></pre>
|
|
<p>If the <code>callback</code> function is not provided, the random bytes are generated
|
|
synchronously and returned as a <a href="buffer.html"><code>Buffer</code></a>. An error will be thrown if
|
|
there is a problem generating the bytes.</p>
|
|
<pre><code class="language-js"><span class="hljs-comment">// Synchronous</span>
|
|
<span class="hljs-keyword">const</span> buf = crypto.randomBytes(<span class="hljs-number">256</span>);
|
|
<span class="hljs-built_in">console</span>.log(
|
|
<span class="hljs-string">`<span class="hljs-subst">${buf.length}</span> bytes of random data: <span class="hljs-subst">${buf.toString(<span class="hljs-string">'hex'</span>)}</span>`</span>);</code></pre>
|
|
<p>The <code>crypto.randomBytes()</code> method will not complete until there is
|
|
sufficient entropy available.
|
|
This should normally never take longer than a few milliseconds. The only time
|
|
when generating the random bytes may conceivably block for a longer period of
|
|
time is right after boot, when the whole system is still low on entropy.</p>
|
|
<p>This API uses libuv's threadpool, which can have surprising and
|
|
negative performance implications for some applications; see the
|
|
<a href="cli.html#cli_uv_threadpool_size_size"><code>UV_THREADPOOL_SIZE</code></a> documentation for more information.</p>
|
|
<p>The asynchronous version of <code>crypto.randomBytes()</code> is carried out in a single
|
|
threadpool request. To minimize threadpool task length variation, partition
|
|
large <code>randomBytes</code> requests when doing so as part of fulfilling a client
|
|
request.</p>
|
|
<h3><code>crypto.randomFillSync(buffer[, offset][, size])</code><span><a class="mark" href="#crypto_crypto_randomfillsync_buffer_offset_size" id="crypto_crypto_randomfillsync_buffer_offset_size">#</a></span></h3>
|
|
<div class="api_metadata">
|
|
<details class="changelog"><summary>History</summary>
|
|
<table>
|
|
<tbody><tr><th>Version</th><th>Changes</th></tr>
|
|
<tr><td>v9.0.0</td>
|
|
<td><p>The <code>buffer</code> argument may be any <code>TypedArray</code> or <code>DataView</code>.</p></td></tr>
|
|
<tr><td>v7.10.0, v6.13.0</td>
|
|
<td><p><span>Added in: v7.10.0, v6.13.0</span></p></td></tr>
|
|
</tbody></table>
|
|
</details>
|
|
</div>
|
|
<ul>
|
|
<li><code>buffer</code> <a href="buffer.html#buffer_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> Must be supplied.</li>
|
|
<li><code>offset</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><number></a> <strong>Default:</strong> <code>0</code></li>
|
|
<li><code>size</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><number></a> <strong>Default:</strong> <code>buffer.length - offset</code></li>
|
|
<li>Returns: <a href="buffer.html#buffer_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> The object passed as <code>buffer</code> argument.</li>
|
|
</ul>
|
|
<p>Synchronous version of <a href="#crypto_crypto_randomfill_buffer_offset_size_callback"><code>crypto.randomFill()</code></a>.</p>
|
|
<pre><code class="language-js"><span class="hljs-keyword">const</span> buf = Buffer.alloc(<span class="hljs-number">10</span>);
|
|
<span class="hljs-built_in">console</span>.log(crypto.randomFillSync(buf).toString(<span class="hljs-string">'hex'</span>));
|
|
|
|
crypto.randomFillSync(buf, <span class="hljs-number">5</span>);
|
|
<span class="hljs-built_in">console</span>.log(buf.toString(<span class="hljs-string">'hex'</span>));
|
|
|
|
<span class="hljs-comment">// The above is equivalent to the following:</span>
|
|
crypto.randomFillSync(buf, <span class="hljs-number">5</span>, <span class="hljs-number">5</span>);
|
|
<span class="hljs-built_in">console</span>.log(buf.toString(<span class="hljs-string">'hex'</span>));</code></pre>
|
|
<p>Any <code>TypedArray</code> or <code>DataView</code> instance may be passed as <code>buffer</code>.</p>
|
|
<pre><code class="language-js"><span class="hljs-keyword">const</span> a = <span class="hljs-keyword">new</span> <span class="hljs-built_in">Uint32Array</span>(<span class="hljs-number">10</span>);
|
|
<span class="hljs-built_in">console</span>.log(Buffer.from(crypto.randomFillSync(a).buffer,
|
|
a.byteOffset, a.byteLength).toString(<span class="hljs-string">'hex'</span>));
|
|
|
|
<span class="hljs-keyword">const</span> b = <span class="hljs-keyword">new</span> <span class="hljs-built_in">Float64Array</span>(<span class="hljs-number">10</span>);
|
|
<span class="hljs-built_in">console</span>.log(Buffer.from(crypto.randomFillSync(b).buffer,
|
|
b.byteOffset, b.byteLength).toString(<span class="hljs-string">'hex'</span>));
|
|
|
|
<span class="hljs-keyword">const</span> c = <span class="hljs-keyword">new</span> <span class="hljs-built_in">DataView</span>(<span class="hljs-keyword">new</span> <span class="hljs-built_in">ArrayBuffer</span>(<span class="hljs-number">10</span>));
|
|
<span class="hljs-built_in">console</span>.log(Buffer.from(crypto.randomFillSync(c).buffer,
|
|
c.byteOffset, c.byteLength).toString(<span class="hljs-string">'hex'</span>));</code></pre>
|
|
<h3><code>crypto.randomFill(buffer[, offset][, size], callback)</code><span><a class="mark" href="#crypto_crypto_randomfill_buffer_offset_size_callback" id="crypto_crypto_randomfill_buffer_offset_size_callback">#</a></span></h3>
|
|
<div class="api_metadata">
|
|
<details class="changelog"><summary>History</summary>
|
|
<table>
|
|
<tbody><tr><th>Version</th><th>Changes</th></tr>
|
|
<tr><td>v9.0.0</td>
|
|
<td><p>The <code>buffer</code> argument may be any <code>TypedArray</code> or <code>DataView</code>.</p></td></tr>
|
|
<tr><td>v7.10.0, v6.13.0</td>
|
|
<td><p><span>Added in: v7.10.0, v6.13.0</span></p></td></tr>
|
|
</tbody></table>
|
|
</details>
|
|
</div>
|
|
<ul>
|
|
<li><code>buffer</code> <a href="buffer.html#buffer_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> Must be supplied.</li>
|
|
<li><code>offset</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><number></a> <strong>Default:</strong> <code>0</code></li>
|
|
<li><code>size</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><number></a> <strong>Default:</strong> <code>buffer.length - offset</code></li>
|
|
<li><code>callback</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function" class="type"><Function></a> <code>function(err, buf) {}</code>.</li>
|
|
</ul>
|
|
<p>This function is similar to <a href="#crypto_crypto_randombytes_size_callback"><code>crypto.randomBytes()</code></a> but requires the first
|
|
argument to be a <a href="buffer.html"><code>Buffer</code></a> that will be filled. It also
|
|
requires that a callback is passed in.</p>
|
|
<p>If the <code>callback</code> function is not provided, an error will be thrown.</p>
|
|
<pre><code class="language-js"><span class="hljs-keyword">const</span> buf = Buffer.alloc(<span class="hljs-number">10</span>);
|
|
crypto.randomFill(buf, <span class="hljs-function">(<span class="hljs-params">err, buf</span>) =></span> {
|
|
<span class="hljs-keyword">if</span> (err) <span class="hljs-keyword">throw</span> err;
|
|
<span class="hljs-built_in">console</span>.log(buf.toString(<span class="hljs-string">'hex'</span>));
|
|
});
|
|
|
|
crypto.randomFill(buf, <span class="hljs-number">5</span>, <span class="hljs-function">(<span class="hljs-params">err, buf</span>) =></span> {
|
|
<span class="hljs-keyword">if</span> (err) <span class="hljs-keyword">throw</span> err;
|
|
<span class="hljs-built_in">console</span>.log(buf.toString(<span class="hljs-string">'hex'</span>));
|
|
});
|
|
|
|
<span class="hljs-comment">// The above is equivalent to the following:</span>
|
|
crypto.randomFill(buf, <span class="hljs-number">5</span>, <span class="hljs-number">5</span>, <span class="hljs-function">(<span class="hljs-params">err, buf</span>) =></span> {
|
|
<span class="hljs-keyword">if</span> (err) <span class="hljs-keyword">throw</span> err;
|
|
<span class="hljs-built_in">console</span>.log(buf.toString(<span class="hljs-string">'hex'</span>));
|
|
});</code></pre>
|
|
<p>Any <code>TypedArray</code> or <code>DataView</code> instance may be passed as <code>buffer</code>.</p>
|
|
<pre><code class="language-js"><span class="hljs-keyword">const</span> a = <span class="hljs-keyword">new</span> <span class="hljs-built_in">Uint32Array</span>(<span class="hljs-number">10</span>);
|
|
crypto.randomFill(a, <span class="hljs-function">(<span class="hljs-params">err, buf</span>) =></span> {
|
|
<span class="hljs-keyword">if</span> (err) <span class="hljs-keyword">throw</span> err;
|
|
<span class="hljs-built_in">console</span>.log(Buffer.from(buf.buffer, buf.byteOffset, buf.byteLength)
|
|
.toString(<span class="hljs-string">'hex'</span>));
|
|
});
|
|
|
|
<span class="hljs-keyword">const</span> b = <span class="hljs-keyword">new</span> <span class="hljs-built_in">Float64Array</span>(<span class="hljs-number">10</span>);
|
|
crypto.randomFill(b, <span class="hljs-function">(<span class="hljs-params">err, buf</span>) =></span> {
|
|
<span class="hljs-keyword">if</span> (err) <span class="hljs-keyword">throw</span> err;
|
|
<span class="hljs-built_in">console</span>.log(Buffer.from(buf.buffer, buf.byteOffset, buf.byteLength)
|
|
.toString(<span class="hljs-string">'hex'</span>));
|
|
});
|
|
|
|
<span class="hljs-keyword">const</span> c = <span class="hljs-keyword">new</span> <span class="hljs-built_in">DataView</span>(<span class="hljs-keyword">new</span> <span class="hljs-built_in">ArrayBuffer</span>(<span class="hljs-number">10</span>));
|
|
crypto.randomFill(c, <span class="hljs-function">(<span class="hljs-params">err, buf</span>) =></span> {
|
|
<span class="hljs-keyword">if</span> (err) <span class="hljs-keyword">throw</span> err;
|
|
<span class="hljs-built_in">console</span>.log(Buffer.from(buf.buffer, buf.byteOffset, buf.byteLength)
|
|
.toString(<span class="hljs-string">'hex'</span>));
|
|
});</code></pre>
|
|
<p>This API uses libuv's threadpool, which can have surprising and
|
|
negative performance implications for some applications; see the
|
|
<a href="cli.html#cli_uv_threadpool_size_size"><code>UV_THREADPOOL_SIZE</code></a> documentation for more information.</p>
|
|
<p>The asynchronous version of <code>crypto.randomFill()</code> is carried out in a single
|
|
threadpool request. To minimize threadpool task length variation, partition
|
|
large <code>randomFill</code> requests when doing so as part of fulfilling a client
|
|
request.</p>
|
|
<h3><code>crypto.randomInt([min, ]max[, callback])</code><span><a class="mark" href="#crypto_crypto_randomint_min_max_callback" id="crypto_crypto_randomint_min_max_callback">#</a></span></h3>
|
|
<div class="api_metadata">
|
|
<span>Added in: v12.19.0</span>
|
|
</div>
|
|
<ul>
|
|
<li><code>min</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><integer></a> Start of random range (inclusive). <strong>Default</strong>: <code>0</code>.</li>
|
|
<li><code>max</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><integer></a> End of random range (exclusive).</li>
|
|
<li><code>callback</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function" class="type"><Function></a> <code>function(err, n) {}</code>.</li>
|
|
</ul>
|
|
<p>Return a random integer <code>n</code> such that <code>min <= n < max</code>. This
|
|
implementation avoids <a href="https://en.wikipedia.org/wiki/Fisher%E2%80%93Yates_shuffle#Modulo_bias">modulo bias</a>.</p>
|
|
<p>The range (<code>max - min</code>) must be less than 2<sup>48</sup>. <code>min</code> and <code>max</code> must
|
|
be <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number/isSafeInteger">safe integers</a>.</p>
|
|
<p>If the <code>callback</code> function is not provided, the random integer is
|
|
generated synchronously.</p>
|
|
<pre><code class="language-js"><span class="hljs-comment">// Asynchronous</span>
|
|
crypto.randomInt(<span class="hljs-number">3</span>, <span class="hljs-function">(<span class="hljs-params">err, n</span>) =></span> {
|
|
<span class="hljs-keyword">if</span> (err) <span class="hljs-keyword">throw</span> err;
|
|
<span class="hljs-built_in">console</span>.log(<span class="hljs-string">`Random number chosen from (0, 1, 2): <span class="hljs-subst">${n}</span>`</span>);
|
|
});</code></pre>
|
|
<pre><code class="language-js"><span class="hljs-comment">// Synchronous</span>
|
|
<span class="hljs-keyword">const</span> n = crypto.randomInt(<span class="hljs-number">3</span>);
|
|
<span class="hljs-built_in">console</span>.log(<span class="hljs-string">`Random number chosen from (0, 1, 2): <span class="hljs-subst">${n}</span>`</span>);</code></pre>
|
|
<pre><code class="language-js"><span class="hljs-comment">// With `min` argument</span>
|
|
<span class="hljs-keyword">const</span> n = crypto.randomInt(<span class="hljs-number">1</span>, <span class="hljs-number">7</span>);
|
|
<span class="hljs-built_in">console</span>.log(<span class="hljs-string">`The dice rolled: <span class="hljs-subst">${n}</span>`</span>);</code></pre>
|
|
<h3><code>crypto.scrypt(password, salt, keylen[, options], callback)</code><span><a class="mark" href="#crypto_crypto_scrypt_password_salt_keylen_options_callback" id="crypto_crypto_scrypt_password_salt_keylen_options_callback">#</a></span></h3>
|
|
<div class="api_metadata">
|
|
<details class="changelog"><summary>History</summary>
|
|
<table>
|
|
<tbody><tr><th>Version</th><th>Changes</th></tr>
|
|
<tr><td>v12.8.0</td>
|
|
<td><p>The <code>maxmem</code> value can now be any safe integer.</p></td></tr>
|
|
<tr><td>v10.9.0</td>
|
|
<td><p>The <code>cost</code>, <code>blockSize</code> and <code>parallelization</code> option names have been added.</p></td></tr>
|
|
<tr><td>v10.5.0</td>
|
|
<td><p><span>Added in: v10.5.0</span></p></td></tr>
|
|
</tbody></table>
|
|
</details>
|
|
</div>
|
|
<ul>
|
|
<li><code>password</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> | <a href="buffer.html#buffer_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></li>
|
|
<li><code>salt</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> | <a href="buffer.html#buffer_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></li>
|
|
<li><code>keylen</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><number></a></li>
|
|
<li><code>options</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object" class="type"><Object></a>
|
|
<ul>
|
|
<li><code>cost</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><number></a> CPU/memory cost parameter. Must be a power of two greater
|
|
than one. <strong>Default:</strong> <code>16384</code>.</li>
|
|
<li><code>blockSize</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><number></a> Block size parameter. <strong>Default:</strong> <code>8</code>.</li>
|
|
<li><code>parallelization</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><number></a> Parallelization parameter. <strong>Default:</strong> <code>1</code>.</li>
|
|
<li><code>N</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><number></a> Alias for <code>cost</code>. Only one of both may be specified.</li>
|
|
<li><code>r</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><number></a> Alias for <code>blockSize</code>. Only one of both may be specified.</li>
|
|
<li><code>p</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><number></a> Alias for <code>parallelization</code>. Only one of both may be specified.</li>
|
|
<li><code>maxmem</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><number></a> Memory upper bound. It is an error when (approximately)
|
|
<code>128 * N * r > maxmem</code>. <strong>Default:</strong> <code>32 * 1024 * 1024</code>.</li>
|
|
</ul>
|
|
</li>
|
|
<li><code>callback</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function" class="type"><Function></a>
|
|
<ul>
|
|
<li><code>err</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error" class="type"><Error></a></li>
|
|
<li><code>derivedKey</code> <a href="buffer.html#buffer_class_buffer" class="type"><Buffer></a></li>
|
|
</ul>
|
|
</li>
|
|
</ul>
|
|
<p>Provides an asynchronous <a href="https://en.wikipedia.org/wiki/Scrypt">scrypt</a> implementation. Scrypt is a password-based
|
|
key derivation function that is designed to be expensive computationally and
|
|
memory-wise in order to make brute-force attacks unrewarding.</p>
|
|
<p>The <code>salt</code> should be as unique as possible. It is recommended that a salt is
|
|
random and at least 16 bytes long. See <a href="https://nvlpubs.nist.gov/nistpubs/Legacy/SP/nistspecialpublication800-132.pdf">NIST SP 800-132</a> for details.</p>
|
|
<p>The <code>callback</code> function is called with two arguments: <code>err</code> and <code>derivedKey</code>.
|
|
<code>err</code> is an exception object when key derivation fails, otherwise <code>err</code> is
|
|
<code>null</code>. <code>derivedKey</code> is passed to the callback as a <a href="buffer.html"><code>Buffer</code></a>.</p>
|
|
<p>An exception is thrown when any of the input arguments specify invalid values
|
|
or types.</p>
|
|
<pre><code class="language-js"><span class="hljs-keyword">const</span> crypto = <span class="hljs-built_in">require</span>(<span class="hljs-string">'crypto'</span>);
|
|
<span class="hljs-comment">// Using the factory defaults.</span>
|
|
crypto.scrypt(<span class="hljs-string">'secret'</span>, <span class="hljs-string">'salt'</span>, <span class="hljs-number">64</span>, <span class="hljs-function">(<span class="hljs-params">err, derivedKey</span>) =></span> {
|
|
<span class="hljs-keyword">if</span> (err) <span class="hljs-keyword">throw</span> err;
|
|
<span class="hljs-built_in">console</span>.log(derivedKey.toString(<span class="hljs-string">'hex'</span>)); <span class="hljs-comment">// '3745e48...08d59ae'</span>
|
|
});
|
|
<span class="hljs-comment">// Using a custom N parameter. Must be a power of two.</span>
|
|
crypto.scrypt(<span class="hljs-string">'secret'</span>, <span class="hljs-string">'salt'</span>, <span class="hljs-number">64</span>, { <span class="hljs-attr">N</span>: <span class="hljs-number">1024</span> }, <span class="hljs-function">(<span class="hljs-params">err, derivedKey</span>) =></span> {
|
|
<span class="hljs-keyword">if</span> (err) <span class="hljs-keyword">throw</span> err;
|
|
<span class="hljs-built_in">console</span>.log(derivedKey.toString(<span class="hljs-string">'hex'</span>)); <span class="hljs-comment">// '3745e48...aa39b34'</span>
|
|
});</code></pre>
|
|
<h3><code>crypto.scryptSync(password, salt, keylen[, options])</code><span><a class="mark" href="#crypto_crypto_scryptsync_password_salt_keylen_options" id="crypto_crypto_scryptsync_password_salt_keylen_options">#</a></span></h3>
|
|
<div class="api_metadata">
|
|
<details class="changelog"><summary>History</summary>
|
|
<table>
|
|
<tbody><tr><th>Version</th><th>Changes</th></tr>
|
|
<tr><td>v12.8.0</td>
|
|
<td><p>The <code>maxmem</code> value can now be any safe integer.</p></td></tr>
|
|
<tr><td>v10.9.0</td>
|
|
<td><p>The <code>cost</code>, <code>blockSize</code> and <code>parallelization</code> option names have been added.</p></td></tr>
|
|
<tr><td>v10.5.0</td>
|
|
<td><p><span>Added in: v10.5.0</span></p></td></tr>
|
|
</tbody></table>
|
|
</details>
|
|
</div>
|
|
<ul>
|
|
<li><code>password</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> | <a href="buffer.html#buffer_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></li>
|
|
<li><code>salt</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> | <a href="buffer.html#buffer_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></li>
|
|
<li><code>keylen</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><number></a></li>
|
|
<li><code>options</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object" class="type"><Object></a>
|
|
<ul>
|
|
<li><code>cost</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><number></a> CPU/memory cost parameter. Must be a power of two greater
|
|
than one. <strong>Default:</strong> <code>16384</code>.</li>
|
|
<li><code>blockSize</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><number></a> Block size parameter. <strong>Default:</strong> <code>8</code>.</li>
|
|
<li><code>parallelization</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><number></a> Parallelization parameter. <strong>Default:</strong> <code>1</code>.</li>
|
|
<li><code>N</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><number></a> Alias for <code>cost</code>. Only one of both may be specified.</li>
|
|
<li><code>r</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><number></a> Alias for <code>blockSize</code>. Only one of both may be specified.</li>
|
|
<li><code>p</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><number></a> Alias for <code>parallelization</code>. Only one of both may be specified.</li>
|
|
<li><code>maxmem</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><number></a> Memory upper bound. It is an error when (approximately)
|
|
<code>128 * N * r > maxmem</code>. <strong>Default:</strong> <code>32 * 1024 * 1024</code>.</li>
|
|
</ul>
|
|
</li>
|
|
<li>Returns: <a href="buffer.html#buffer_class_buffer" class="type"><Buffer></a></li>
|
|
</ul>
|
|
<p>Provides a synchronous <a href="https://en.wikipedia.org/wiki/Scrypt">scrypt</a> implementation. Scrypt is a password-based
|
|
key derivation function that is designed to be expensive computationally and
|
|
memory-wise in order to make brute-force attacks unrewarding.</p>
|
|
<p>The <code>salt</code> should be as unique as possible. It is recommended that a salt is
|
|
random and at least 16 bytes long. See <a href="https://nvlpubs.nist.gov/nistpubs/Legacy/SP/nistspecialpublication800-132.pdf">NIST SP 800-132</a> for details.</p>
|
|
<p>An exception is thrown when key derivation fails, otherwise the derived key is
|
|
returned as a <a href="buffer.html"><code>Buffer</code></a>.</p>
|
|
<p>An exception is thrown when any of the input arguments specify invalid values
|
|
or types.</p>
|
|
<pre><code class="language-js"><span class="hljs-keyword">const</span> crypto = <span class="hljs-built_in">require</span>(<span class="hljs-string">'crypto'</span>);
|
|
<span class="hljs-comment">// Using the factory defaults.</span>
|
|
<span class="hljs-keyword">const</span> key1 = crypto.scryptSync(<span class="hljs-string">'secret'</span>, <span class="hljs-string">'salt'</span>, <span class="hljs-number">64</span>);
|
|
<span class="hljs-built_in">console</span>.log(key1.toString(<span class="hljs-string">'hex'</span>)); <span class="hljs-comment">// '3745e48...08d59ae'</span>
|
|
<span class="hljs-comment">// Using a custom N parameter. Must be a power of two.</span>
|
|
<span class="hljs-keyword">const</span> key2 = crypto.scryptSync(<span class="hljs-string">'secret'</span>, <span class="hljs-string">'salt'</span>, <span class="hljs-number">64</span>, { <span class="hljs-attr">N</span>: <span class="hljs-number">1024</span> });
|
|
<span class="hljs-built_in">console</span>.log(key2.toString(<span class="hljs-string">'hex'</span>)); <span class="hljs-comment">// '3745e48...aa39b34'</span></code></pre>
|
|
<h3><code>crypto.setEngine(engine[, flags])</code><span><a class="mark" href="#crypto_crypto_setengine_engine_flags" id="crypto_crypto_setengine_engine_flags">#</a></span></h3>
|
|
<div class="api_metadata">
|
|
<span>Added in: v0.11.11</span>
|
|
</div>
|
|
<ul>
|
|
<li><code>engine</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a></li>
|
|
<li><code>flags</code> <a href="crypto.html#crypto_crypto_constants_1" class="type"><crypto.constants></a> <strong>Default:</strong> <code>crypto.constants.ENGINE_METHOD_ALL</code></li>
|
|
</ul>
|
|
<p>Load and set the <code>engine</code> for some or all OpenSSL functions (selected by flags).</p>
|
|
<p><code>engine</code> could be either an id or a path to the engine's shared library.</p>
|
|
<p>The optional <code>flags</code> argument uses <code>ENGINE_METHOD_ALL</code> by default. The <code>flags</code>
|
|
is a bit field taking one of or a mix of the following flags (defined in
|
|
<code>crypto.constants</code>):</p>
|
|
<ul>
|
|
<li><code>crypto.constants.ENGINE_METHOD_RSA</code></li>
|
|
<li><code>crypto.constants.ENGINE_METHOD_DSA</code></li>
|
|
<li><code>crypto.constants.ENGINE_METHOD_DH</code></li>
|
|
<li><code>crypto.constants.ENGINE_METHOD_RAND</code></li>
|
|
<li><code>crypto.constants.ENGINE_METHOD_EC</code></li>
|
|
<li><code>crypto.constants.ENGINE_METHOD_CIPHERS</code></li>
|
|
<li><code>crypto.constants.ENGINE_METHOD_DIGESTS</code></li>
|
|
<li><code>crypto.constants.ENGINE_METHOD_PKEY_METHS</code></li>
|
|
<li><code>crypto.constants.ENGINE_METHOD_PKEY_ASN1_METHS</code></li>
|
|
<li><code>crypto.constants.ENGINE_METHOD_ALL</code></li>
|
|
<li><code>crypto.constants.ENGINE_METHOD_NONE</code></li>
|
|
</ul>
|
|
<p>The flags below are deprecated in OpenSSL-1.1.0.</p>
|
|
<ul>
|
|
<li><code>crypto.constants.ENGINE_METHOD_ECDH</code></li>
|
|
<li><code>crypto.constants.ENGINE_METHOD_ECDSA</code></li>
|
|
<li><code>crypto.constants.ENGINE_METHOD_STORE</code></li>
|
|
</ul>
|
|
<h3><code>crypto.setFips(bool)</code><span><a class="mark" href="#crypto_crypto_setfips_bool" id="crypto_crypto_setfips_bool">#</a></span></h3>
|
|
<div class="api_metadata">
|
|
<span>Added in: v10.0.0</span>
|
|
</div>
|
|
<ul>
|
|
<li><code>bool</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type" class="type"><boolean></a> <code>true</code> to enable FIPS mode.</li>
|
|
</ul>
|
|
<p>Enables the FIPS compliant crypto provider in a FIPS-enabled Node.js build.
|
|
Throws an error if FIPS mode is not available.</p>
|
|
<h3><code>crypto.sign(algorithm, data, key)</code><span><a class="mark" href="#crypto_crypto_sign_algorithm_data_key" id="crypto_crypto_sign_algorithm_data_key">#</a></span></h3>
|
|
<div class="api_metadata">
|
|
<span>Added in: v12.0.0</span>
|
|
</div>
|
|
<ul>
|
|
<li><code>algorithm</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#Null_type" class="type"><null></a> | <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Undefined_type" class="type"><undefined></a></li>
|
|
<li><code>data</code> <a href="buffer.html#buffer_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></li>
|
|
<li><code>key</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object" class="type"><Object></a> | <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> | <a href="buffer.html#buffer_class_buffer" class="type"><Buffer></a> | <a href="crypto.html#crypto_class_keyobject" class="type"><KeyObject></a></li>
|
|
<li>Returns: <a href="buffer.html#buffer_class_buffer" class="type"><Buffer></a></li>
|
|
</ul>
|
|
<p>Calculates and returns the signature for <code>data</code> using the given private key and
|
|
algorithm. If <code>algorithm</code> is <code>null</code> or <code>undefined</code>, then the algorithm is
|
|
dependent upon the key type (especially Ed25519 and Ed448).</p>
|
|
<p>If <code>key</code> is not a <a href="#crypto_class_keyobject"><code>KeyObject</code></a>, this function behaves as if <code>key</code> had been
|
|
passed to <a href="#crypto_crypto_createprivatekey_key"><code>crypto.createPrivateKey()</code></a>. If it is an object, the following
|
|
additional properties can be passed:</p>
|
|
<ul>
|
|
<li>
|
|
<p><code>dsaEncoding</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> For DSA and ECDSA, this option specifies the
|
|
format of the generated signature. It can be one of the following:</p>
|
|
<ul>
|
|
<li><code>'der'</code> (default): DER-encoded ASN.1 signature structure encoding <code>(r, s)</code>.</li>
|
|
<li><code>'ieee-p1363'</code>: Signature format <code>r || s</code> as proposed in IEEE-P1363.</li>
|
|
</ul>
|
|
</li>
|
|
<li>
|
|
<p><code>padding</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><integer></a> Optional padding value for RSA, one of the following:</p>
|
|
<ul>
|
|
<li><code>crypto.constants.RSA_PKCS1_PADDING</code> (default)</li>
|
|
<li><code>crypto.constants.RSA_PKCS1_PSS_PADDING</code></li>
|
|
</ul>
|
|
<p><code>RSA_PKCS1_PSS_PADDING</code> will use MGF1 with the same hash function
|
|
used to sign the message as specified in section 3.1 of <a href="https://www.rfc-editor.org/rfc/rfc4055.txt">RFC 4055</a>.</p>
|
|
</li>
|
|
<li>
|
|
<p><code>saltLength</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><integer></a> Salt length for when padding is
|
|
<code>RSA_PKCS1_PSS_PADDING</code>. The special value
|
|
<code>crypto.constants.RSA_PSS_SALTLEN_DIGEST</code> sets the salt length to the digest
|
|
size, <code>crypto.constants.RSA_PSS_SALTLEN_MAX_SIGN</code> (default) sets it to the
|
|
maximum permissible value.</p>
|
|
</li>
|
|
</ul>
|
|
<h3><code>crypto.timingSafeEqual(a, b)</code><span><a class="mark" href="#crypto_crypto_timingsafeequal_a_b" id="crypto_crypto_timingsafeequal_a_b">#</a></span></h3>
|
|
<div class="api_metadata">
|
|
<span>Added in: v6.6.0</span>
|
|
</div>
|
|
<ul>
|
|
<li><code>a</code> <a href="buffer.html#buffer_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></li>
|
|
<li><code>b</code> <a href="buffer.html#buffer_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></li>
|
|
<li>Returns: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type" class="type"><boolean></a></li>
|
|
</ul>
|
|
<p>This function is based on a constant-time algorithm.
|
|
Returns true if <code>a</code> is equal to <code>b</code>, without leaking timing information that
|
|
would allow an attacker to guess one of the values. This is suitable for
|
|
comparing HMAC digests or secret values like authentication cookies or
|
|
<a href="https://www.w3.org/TR/capability-urls/">capability urls</a>.</p>
|
|
<p><code>a</code> and <code>b</code> must both be <code>Buffer</code>s, <code>TypedArray</code>s, or <code>DataView</code>s, and they
|
|
must have the same length.</p>
|
|
<p>Use of <code>crypto.timingSafeEqual</code> does not guarantee that the <em>surrounding</em> code
|
|
is timing-safe. Care should be taken to ensure that the surrounding code does
|
|
not introduce timing vulnerabilities.</p>
|
|
<h3><code>crypto.verify(algorithm, data, key, signature)</code><span><a class="mark" href="#crypto_crypto_verify_algorithm_data_key_signature" id="crypto_crypto_verify_algorithm_data_key_signature">#</a></span></h3>
|
|
<div class="api_metadata">
|
|
<span>Added in: v12.0.0</span>
|
|
</div>
|
|
<ul>
|
|
<li><code>algorithm</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#Null_type" class="type"><null></a> | <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Undefined_type" class="type"><undefined></a></li>
|
|
<li><code>data</code> <a href="buffer.html#buffer_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></li>
|
|
<li><code>key</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object" class="type"><Object></a> | <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> | <a href="buffer.html#buffer_class_buffer" class="type"><Buffer></a> | <a href="crypto.html#crypto_class_keyobject" class="type"><KeyObject></a></li>
|
|
<li><code>signature</code> <a href="buffer.html#buffer_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></li>
|
|
<li>Returns: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type" class="type"><boolean></a></li>
|
|
</ul>
|
|
<p>Verifies the given signature for <code>data</code> using the given key and algorithm. If
|
|
<code>algorithm</code> is <code>null</code> or <code>undefined</code>, then the algorithm is dependent upon the
|
|
key type (especially Ed25519 and Ed448).</p>
|
|
<p>If <code>key</code> is not a <a href="#crypto_class_keyobject"><code>KeyObject</code></a>, this function behaves as if <code>key</code> had been
|
|
passed to <a href="#crypto_crypto_createpublickey_key"><code>crypto.createPublicKey()</code></a>. If it is an object, the following
|
|
additional properties can be passed:</p>
|
|
<ul>
|
|
<li>
|
|
<p><code>dsaEncoding</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> For DSA and ECDSA, this option specifies the
|
|
format of the generated signature. It can be one of the following:</p>
|
|
<ul>
|
|
<li><code>'der'</code> (default): DER-encoded ASN.1 signature structure encoding <code>(r, s)</code>.</li>
|
|
<li><code>'ieee-p1363'</code>: Signature format <code>r || s</code> as proposed in IEEE-P1363.</li>
|
|
</ul>
|
|
</li>
|
|
<li>
|
|
<p><code>padding</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><integer></a> Optional padding value for RSA, one of the following:</p>
|
|
<ul>
|
|
<li><code>crypto.constants.RSA_PKCS1_PADDING</code> (default)</li>
|
|
<li><code>crypto.constants.RSA_PKCS1_PSS_PADDING</code></li>
|
|
</ul>
|
|
<p><code>RSA_PKCS1_PSS_PADDING</code> will use MGF1 with the same hash function
|
|
used to sign the message as specified in section 3.1 of <a href="https://www.rfc-editor.org/rfc/rfc4055.txt">RFC 4055</a>.</p>
|
|
</li>
|
|
<li>
|
|
<p><code>saltLength</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><integer></a> Salt length for when padding is
|
|
<code>RSA_PKCS1_PSS_PADDING</code>. The special value
|
|
<code>crypto.constants.RSA_PSS_SALTLEN_DIGEST</code> sets the salt length to the digest
|
|
size, <code>crypto.constants.RSA_PSS_SALTLEN_MAX_SIGN</code> (default) sets it to the
|
|
maximum permissible value.</p>
|
|
</li>
|
|
</ul>
|
|
<p>The <code>signature</code> argument is the previously calculated signature for the <code>data</code>.</p>
|
|
<p>Because public keys can be derived from private keys, a private key or a public
|
|
key may be passed for <code>key</code>.</p>
|
|
<h2>Notes<span><a class="mark" href="#crypto_notes" id="crypto_notes">#</a></span></h2>
|
|
<h3>Legacy Streams API (prior to Node.js 0.10)<span><a class="mark" href="#crypto_legacy_streams_api_prior_to_node_js_0_10" id="crypto_legacy_streams_api_prior_to_node_js_0_10">#</a></span></h3>
|
|
<p>The Crypto module was added to Node.js before there was the concept of a
|
|
unified Stream API, and before there were <a href="buffer.html"><code>Buffer</code></a> objects for handling
|
|
binary data. As such, the many of the <code>crypto</code> defined classes have methods not
|
|
typically found on other Node.js classes that implement the <a href="stream.html">streams</a>
|
|
API (e.g. <code>update()</code>, <code>final()</code>, or <code>digest()</code>). Also, many methods accepted
|
|
and returned <code>'latin1'</code> encoded strings by default rather than <code>Buffer</code>s. This
|
|
default was changed after Node.js v0.8 to use <a href="buffer.html"><code>Buffer</code></a> objects by default
|
|
instead.</p>
|
|
<h3>Recent ECDH changes<span><a class="mark" href="#crypto_recent_ecdh_changes" id="crypto_recent_ecdh_changes">#</a></span></h3>
|
|
<p>Usage of <code>ECDH</code> with non-dynamically generated key pairs has been simplified.
|
|
Now, <a href="#crypto_ecdh_setprivatekey_privatekey_encoding"><code>ecdh.setPrivateKey()</code></a> can be called with a preselected private key
|
|
and the associated public point (key) will be computed and stored in the object.
|
|
This allows code to only store and provide the private part of the EC key pair.
|
|
<a href="#crypto_ecdh_setprivatekey_privatekey_encoding"><code>ecdh.setPrivateKey()</code></a> now also validates that the private key is valid for
|
|
the selected curve.</p>
|
|
<p>The <a href="#crypto_ecdh_setpublickey_publickey_encoding"><code>ecdh.setPublicKey()</code></a> method is now deprecated as its inclusion in the
|
|
API is not useful. Either a previously stored private key should be set, which
|
|
automatically generates the associated public key, or <a href="#crypto_ecdh_generatekeys_encoding_format"><code>ecdh.generateKeys()</code></a>
|
|
should be called. The main drawback of using <a href="#crypto_ecdh_setpublickey_publickey_encoding"><code>ecdh.setPublicKey()</code></a> is that
|
|
it can be used to put the ECDH key pair into an inconsistent state.</p>
|
|
<h3>Support for weak or compromised algorithms<span><a class="mark" href="#crypto_support_for_weak_or_compromised_algorithms" id="crypto_support_for_weak_or_compromised_algorithms">#</a></span></h3>
|
|
<p>The <code>crypto</code> module still supports some algorithms which are already
|
|
compromised and are not currently recommended for use. The API also allows
|
|
the use of ciphers and hashes with a small key size that are too weak for safe
|
|
use.</p>
|
|
<p>Users should take full responsibility for selecting the crypto
|
|
algorithm and key size according to their security requirements.</p>
|
|
<p>Based on the recommendations of <a href="https://nvlpubs.nist.gov/nistpubs/SpecialPublications/NIST.SP.800-131Ar1.pdf">NIST SP 800-131A</a>:</p>
|
|
<ul>
|
|
<li>MD5 and SHA-1 are no longer acceptable where collision resistance is
|
|
required such as digital signatures.</li>
|
|
<li>The key used with RSA, DSA, and DH algorithms is recommended to have
|
|
at least 2048 bits and that of the curve of ECDSA and ECDH at least
|
|
224 bits, to be safe to use for several years.</li>
|
|
<li>The DH groups of <code>modp1</code>, <code>modp2</code> and <code>modp5</code> have a key size
|
|
smaller than 2048 bits and are not recommended.</li>
|
|
</ul>
|
|
<p>See the reference for other recommendations and details.</p>
|
|
<h3>CCM mode<span><a class="mark" href="#crypto_ccm_mode" id="crypto_ccm_mode">#</a></span></h3>
|
|
<p>CCM is one of the supported <a href="https://en.wikipedia.org/wiki/Authenticated_encryption">AEAD algorithms</a>. Applications which use this
|
|
mode must adhere to certain restrictions when using the cipher API:</p>
|
|
<ul>
|
|
<li>The authentication tag length must be specified during cipher creation by
|
|
setting the <code>authTagLength</code> option and must be one of 4, 6, 8, 10, 12, 14 or
|
|
16 bytes.</li>
|
|
<li>The length of the initialization vector (nonce) <code>N</code> must be between 7 and 13
|
|
bytes (<code>7 ≤ N ≤ 13</code>).</li>
|
|
<li>The length of the plaintext is limited to <code>2 ** (8 * (15 - N))</code> bytes.</li>
|
|
<li>When decrypting, the authentication tag must be set via <code>setAuthTag()</code> before
|
|
calling <code>update()</code>.
|
|
Otherwise, decryption will fail and <code>final()</code> will throw an error in
|
|
compliance with section 2.6 of <a href="https://www.rfc-editor.org/rfc/rfc3610.txt">RFC 3610</a>.</li>
|
|
<li>Using stream methods such as <code>write(data)</code>, <code>end(data)</code> or <code>pipe()</code> in CCM
|
|
mode might fail as CCM cannot handle more than one chunk of data per instance.</li>
|
|
<li>When passing additional authenticated data (AAD), the length of the actual
|
|
message in bytes must be passed to <code>setAAD()</code> via the <code>plaintextLength</code>
|
|
option.
|
|
Many crypto libraries include the authentication tag in the ciphertext,
|
|
which means that they produce ciphertexts of the length
|
|
<code>plaintextLength + authTagLength</code>. Node.js does not include the authentication
|
|
tag, so the ciphertext length is always <code>plaintextLength</code>.
|
|
This is not necessary if no AAD is used.</li>
|
|
<li>As CCM processes the whole message at once, <code>update()</code> can only be called
|
|
once.</li>
|
|
<li>Even though calling <code>update()</code> is sufficient to encrypt/decrypt the message,
|
|
applications <em>must</em> call <code>final()</code> to compute or verify the
|
|
authentication tag.</li>
|
|
</ul>
|
|
<pre><code class="language-js"><span class="hljs-keyword">const</span> crypto = <span class="hljs-built_in">require</span>(<span class="hljs-string">'crypto'</span>);
|
|
|
|
<span class="hljs-keyword">const</span> key = <span class="hljs-string">'keykeykeykeykeykeykeykey'</span>;
|
|
<span class="hljs-keyword">const</span> nonce = crypto.randomBytes(<span class="hljs-number">12</span>);
|
|
|
|
<span class="hljs-keyword">const</span> aad = Buffer.from(<span class="hljs-string">'0123456789'</span>, <span class="hljs-string">'hex'</span>);
|
|
|
|
<span class="hljs-keyword">const</span> cipher = crypto.createCipheriv(<span class="hljs-string">'aes-192-ccm'</span>, key, nonce, {
|
|
<span class="hljs-attr">authTagLength</span>: <span class="hljs-number">16</span>
|
|
});
|
|
<span class="hljs-keyword">const</span> plaintext = <span class="hljs-string">'Hello world'</span>;
|
|
cipher.setAAD(aad, {
|
|
<span class="hljs-attr">plaintextLength</span>: Buffer.byteLength(plaintext)
|
|
});
|
|
<span class="hljs-keyword">const</span> ciphertext = cipher.update(plaintext, <span class="hljs-string">'utf8'</span>);
|
|
cipher.final();
|
|
<span class="hljs-keyword">const</span> tag = cipher.getAuthTag();
|
|
|
|
<span class="hljs-comment">// Now transmit { ciphertext, nonce, tag }.</span>
|
|
|
|
<span class="hljs-keyword">const</span> decipher = crypto.createDecipheriv(<span class="hljs-string">'aes-192-ccm'</span>, key, nonce, {
|
|
<span class="hljs-attr">authTagLength</span>: <span class="hljs-number">16</span>
|
|
});
|
|
decipher.setAuthTag(tag);
|
|
decipher.setAAD(aad, {
|
|
<span class="hljs-attr">plaintextLength</span>: ciphertext.length
|
|
});
|
|
<span class="hljs-keyword">const</span> receivedPlaintext = decipher.update(ciphertext, <span class="hljs-literal">null</span>, <span class="hljs-string">'utf8'</span>);
|
|
|
|
<span class="hljs-keyword">try</span> {
|
|
decipher.final();
|
|
} <span class="hljs-keyword">catch</span> (err) {
|
|
<span class="hljs-built_in">console</span>.error(<span class="hljs-string">'Authentication failed!'</span>);
|
|
<span class="hljs-keyword">return</span>;
|
|
}
|
|
|
|
<span class="hljs-built_in">console</span>.log(receivedPlaintext);</code></pre>
|
|
<h2>Crypto constants<span><a class="mark" href="#crypto_crypto_constants_1" id="crypto_crypto_constants_1">#</a></span></h2>
|
|
<p>The following constants exported by <code>crypto.constants</code> apply to various uses of
|
|
the <code>crypto</code>, <code>tls</code>, and <code>https</code> modules and are generally specific to OpenSSL.</p>
|
|
<h3>OpenSSL options<span><a class="mark" href="#crypto_openssl_options" id="crypto_openssl_options">#</a></span></h3>
|
|
<table>
|
|
<tbody><tr>
|
|
<th>Constant</th>
|
|
<th>Description</th>
|
|
</tr>
|
|
<tr>
|
|
<td><code>SSL_OP_ALL</code></td>
|
|
<td>Applies multiple bug workarounds within OpenSSL. See
|
|
<a href="https://www.openssl.org/docs/man1.0.2/ssl/SSL_CTX_set_options.html">https://www.openssl.org/docs/man1.0.2/ssl/SSL_CTX_set_options.html</a>
|
|
for detail.</td>
|
|
</tr>
|
|
<tr>
|
|
<td><code>SSL_OP_ALLOW_NO_DHE_KEX</code></td>
|
|
<td>Instructs OpenSSL to allow a non-[EC]DHE-based key exchange mode
|
|
for TLS v1.3</td>
|
|
</tr>
|
|
<tr>
|
|
<td><code>SSL_OP_ALLOW_UNSAFE_LEGACY_RENEGOTIATION</code></td>
|
|
<td>Allows legacy insecure renegotiation between OpenSSL and unpatched
|
|
clients or servers. See
|
|
<a href="https://www.openssl.org/docs/man1.0.2/ssl/SSL_CTX_set_options.html">https://www.openssl.org/docs/man1.0.2/ssl/SSL_CTX_set_options.html</a>.</td>
|
|
</tr>
|
|
<tr>
|
|
<td><code>SSL_OP_CIPHER_SERVER_PREFERENCE</code></td>
|
|
<td>Attempts to use the server's preferences instead of the client's when
|
|
selecting a cipher. Behavior depends on protocol version. See
|
|
<a href="https://www.openssl.org/docs/man1.0.2/ssl/SSL_CTX_set_options.html">https://www.openssl.org/docs/man1.0.2/ssl/SSL_CTX_set_options.html</a>.</td>
|
|
</tr>
|
|
<tr>
|
|
<td><code>SSL_OP_CISCO_ANYCONNECT</code></td>
|
|
<td>Instructs OpenSSL to use Cisco's "speshul" version of DTLS_BAD_VER.</td>
|
|
</tr>
|
|
<tr>
|
|
<td><code>SSL_OP_COOKIE_EXCHANGE</code></td>
|
|
<td>Instructs OpenSSL to turn on cookie exchange.</td>
|
|
</tr>
|
|
<tr>
|
|
<td><code>SSL_OP_CRYPTOPRO_TLSEXT_BUG</code></td>
|
|
<td>Instructs OpenSSL to add server-hello extension from an early version
|
|
of the cryptopro draft.</td>
|
|
</tr>
|
|
<tr>
|
|
<td><code>SSL_OP_DONT_INSERT_EMPTY_FRAGMENTS</code></td>
|
|
<td>Instructs OpenSSL to disable a SSL 3.0/TLS 1.0 vulnerability
|
|
workaround added in OpenSSL 0.9.6d.</td>
|
|
</tr>
|
|
<tr>
|
|
<td><code>SSL_OP_EPHEMERAL_RSA</code></td>
|
|
<td>Instructs OpenSSL to always use the tmp_rsa key when performing RSA
|
|
operations.</td>
|
|
</tr>
|
|
<tr>
|
|
<td><code>SSL_OP_LEGACY_SERVER_CONNECT</code></td>
|
|
<td>Allows initial connection to servers that do not support RI.</td>
|
|
</tr>
|
|
<tr>
|
|
<td><code>SSL_OP_MICROSOFT_BIG_SSLV3_BUFFER</code></td>
|
|
<td></td>
|
|
</tr>
|
|
<tr>
|
|
<td><code>SSL_OP_MICROSOFT_SESS_ID_BUG</code></td>
|
|
<td></td>
|
|
</tr>
|
|
<tr>
|
|
<td><code>SSL_OP_MSIE_SSLV2_RSA_PADDING</code></td>
|
|
<td>Instructs OpenSSL to disable the workaround for a man-in-the-middle
|
|
protocol-version vulnerability in the SSL 2.0 server implementation.</td>
|
|
</tr>
|
|
<tr>
|
|
<td><code>SSL_OP_NETSCAPE_CA_DN_BUG</code></td>
|
|
<td></td>
|
|
</tr>
|
|
<tr>
|
|
<td><code>SSL_OP_NETSCAPE_CHALLENGE_BUG</code></td>
|
|
<td></td>
|
|
</tr>
|
|
<tr>
|
|
<td><code>SSL_OP_NETSCAPE_DEMO_CIPHER_CHANGE_BUG</code></td>
|
|
<td></td>
|
|
</tr>
|
|
<tr>
|
|
<td><code>SSL_OP_NETSCAPE_REUSE_CIPHER_CHANGE_BUG</code></td>
|
|
<td></td>
|
|
</tr>
|
|
<tr>
|
|
<td><code>SSL_OP_NO_COMPRESSION</code></td>
|
|
<td>Instructs OpenSSL to disable support for SSL/TLS compression.</td>
|
|
</tr>
|
|
<tr>
|
|
<td><code>SSL_OP_NO_ENCRYPT_THEN_MAC</code></td>
|
|
<td>Instructs OpenSSL to disable encrypt-then-MAC.</td>
|
|
</tr>
|
|
<tr>
|
|
<td><code>SSL_OP_NO_QUERY_MTU</code></td>
|
|
<td></td>
|
|
</tr>
|
|
<tr>
|
|
<td><code>SSL_OP_NO_RENEGOTIATION</code></td>
|
|
<td>Instructs OpenSSL to disable renegotiation.</td>
|
|
</tr>
|
|
<tr>
|
|
<td><code>SSL_OP_NO_SESSION_RESUMPTION_ON_RENEGOTIATION</code></td>
|
|
<td>Instructs OpenSSL to always start a new session when performing
|
|
renegotiation.</td>
|
|
</tr>
|
|
<tr>
|
|
<td><code>SSL_OP_NO_SSLv2</code></td>
|
|
<td>Instructs OpenSSL to turn off SSL v2</td>
|
|
</tr>
|
|
<tr>
|
|
<td><code>SSL_OP_NO_SSLv3</code></td>
|
|
<td>Instructs OpenSSL to turn off SSL v3</td>
|
|
</tr>
|
|
<tr>
|
|
<td><code>SSL_OP_NO_TICKET</code></td>
|
|
<td>Instructs OpenSSL to disable use of RFC4507bis tickets.</td>
|
|
</tr>
|
|
<tr>
|
|
<td><code>SSL_OP_NO_TLSv1</code></td>
|
|
<td>Instructs OpenSSL to turn off TLS v1</td>
|
|
</tr>
|
|
<tr>
|
|
<td><code>SSL_OP_NO_TLSv1_1</code></td>
|
|
<td>Instructs OpenSSL to turn off TLS v1.1</td>
|
|
</tr>
|
|
<tr>
|
|
<td><code>SSL_OP_NO_TLSv1_2</code></td>
|
|
<td>Instructs OpenSSL to turn off TLS v1.2</td>
|
|
</tr>
|
|
<tr>
|
|
<td><code>SSL_OP_NO_TLSv1_3</code></td>
|
|
<td>Instructs OpenSSL to turn off TLS v1.3</td>
|
|
</tr>
|
|
<tr><td><code>SSL_OP_PKCS1_CHECK_1</code></td>
|
|
<td></td>
|
|
</tr>
|
|
<tr>
|
|
<td><code>SSL_OP_PKCS1_CHECK_2</code></td>
|
|
<td></td>
|
|
</tr>
|
|
<tr>
|
|
<td><code>SSL_OP_PRIORITIZE_CHACHA</code></td>
|
|
<td>Instructs OpenSSL server to prioritize ChaCha20Poly1305
|
|
when client does.
|
|
This option has no effect if
|
|
<code>SSL_OP_CIPHER_SERVER_PREFERENCE</code>
|
|
is not enabled.</td>
|
|
</tr>
|
|
<tr>
|
|
<td><code>SSL_OP_SINGLE_DH_USE</code></td>
|
|
<td>Instructs OpenSSL to always create a new key when using
|
|
temporary/ephemeral DH parameters.</td>
|
|
</tr>
|
|
<tr>
|
|
<td><code>SSL_OP_SINGLE_ECDH_USE</code></td>
|
|
<td>Instructs OpenSSL to always create a new key when using
|
|
temporary/ephemeral ECDH parameters.</td>
|
|
</tr>
|
|
<tr><td><code>SSL_OP_SSLEAY_080_CLIENT_DH_BUG</code></td>
|
|
<td></td>
|
|
</tr>
|
|
<tr>
|
|
<td><code>SSL_OP_SSLREF2_REUSE_CERT_TYPE_BUG</code></td>
|
|
<td></td>
|
|
</tr>
|
|
<tr>
|
|
<td><code>SSL_OP_TLS_BLOCK_PADDING_BUG</code></td>
|
|
<td></td>
|
|
</tr>
|
|
<tr>
|
|
<td><code>SSL_OP_TLS_D5_BUG</code></td>
|
|
<td></td>
|
|
</tr>
|
|
<tr>
|
|
<td><code>SSL_OP_TLS_ROLLBACK_BUG</code></td>
|
|
<td>Instructs OpenSSL to disable version rollback attack detection.</td>
|
|
</tr>
|
|
</tbody></table>
|
|
<h3>OpenSSL engine constants<span><a class="mark" href="#crypto_openssl_engine_constants" id="crypto_openssl_engine_constants">#</a></span></h3>
|
|
<table>
|
|
<tbody><tr>
|
|
<th>Constant</th>
|
|
<th>Description</th>
|
|
</tr>
|
|
<tr>
|
|
<td><code>ENGINE_METHOD_RSA</code></td>
|
|
<td>Limit engine usage to RSA</td>
|
|
</tr>
|
|
<tr>
|
|
<td><code>ENGINE_METHOD_DSA</code></td>
|
|
<td>Limit engine usage to DSA</td>
|
|
</tr>
|
|
<tr>
|
|
<td><code>ENGINE_METHOD_DH</code></td>
|
|
<td>Limit engine usage to DH</td>
|
|
</tr>
|
|
<tr>
|
|
<td><code>ENGINE_METHOD_RAND</code></td>
|
|
<td>Limit engine usage to RAND</td>
|
|
</tr>
|
|
<tr>
|
|
<td><code>ENGINE_METHOD_EC</code></td>
|
|
<td>Limit engine usage to EC</td>
|
|
</tr>
|
|
<tr>
|
|
<td><code>ENGINE_METHOD_CIPHERS</code></td>
|
|
<td>Limit engine usage to CIPHERS</td>
|
|
</tr>
|
|
<tr>
|
|
<td><code>ENGINE_METHOD_DIGESTS</code></td>
|
|
<td>Limit engine usage to DIGESTS</td>
|
|
</tr>
|
|
<tr>
|
|
<td><code>ENGINE_METHOD_PKEY_METHS</code></td>
|
|
<td>Limit engine usage to PKEY_METHDS</td>
|
|
</tr>
|
|
<tr>
|
|
<td><code>ENGINE_METHOD_PKEY_ASN1_METHS</code></td>
|
|
<td>Limit engine usage to PKEY_ASN1_METHS</td>
|
|
</tr>
|
|
<tr>
|
|
<td><code>ENGINE_METHOD_ALL</code></td>
|
|
<td></td>
|
|
</tr>
|
|
<tr>
|
|
<td><code>ENGINE_METHOD_NONE</code></td>
|
|
<td></td>
|
|
</tr>
|
|
</tbody></table>
|
|
<h3>Other OpenSSL constants<span><a class="mark" href="#crypto_other_openssl_constants" id="crypto_other_openssl_constants">#</a></span></h3>
|
|
<p>See the <a href="https://wiki.openssl.org/index.php/List_of_SSL_OP_Flags#Table_of_Options">list of SSL OP Flags</a> for details.</p>
|
|
<table>
|
|
<tbody><tr>
|
|
<th>Constant</th>
|
|
<th>Description</th>
|
|
</tr>
|
|
<tr>
|
|
<td><code>DH_CHECK_P_NOT_SAFE_PRIME</code></td>
|
|
<td></td>
|
|
</tr>
|
|
<tr>
|
|
<td><code>DH_CHECK_P_NOT_PRIME</code></td>
|
|
<td></td>
|
|
</tr>
|
|
<tr>
|
|
<td><code>DH_UNABLE_TO_CHECK_GENERATOR</code></td>
|
|
<td></td>
|
|
</tr>
|
|
<tr>
|
|
<td><code>DH_NOT_SUITABLE_GENERATOR</code></td>
|
|
<td></td>
|
|
</tr>
|
|
<tr>
|
|
<td><code>ALPN_ENABLED</code></td>
|
|
<td></td>
|
|
</tr>
|
|
<tr>
|
|
<td><code>RSA_PKCS1_PADDING</code></td>
|
|
<td></td>
|
|
</tr>
|
|
<tr>
|
|
<td><code>RSA_SSLV23_PADDING</code></td>
|
|
<td></td>
|
|
</tr>
|
|
<tr>
|
|
<td><code>RSA_NO_PADDING</code></td>
|
|
<td></td>
|
|
</tr>
|
|
<tr>
|
|
<td><code>RSA_PKCS1_OAEP_PADDING</code></td>
|
|
<td></td>
|
|
</tr>
|
|
<tr>
|
|
<td><code>RSA_X931_PADDING</code></td>
|
|
<td></td>
|
|
</tr>
|
|
<tr>
|
|
<td><code>RSA_PKCS1_PSS_PADDING</code></td>
|
|
<td></td>
|
|
</tr>
|
|
<tr>
|
|
<td><code>RSA_PSS_SALTLEN_DIGEST</code></td>
|
|
<td>Sets the salt length for <code>RSA_PKCS1_PSS_PADDING</code> to the
|
|
digest size when signing or verifying.</td>
|
|
</tr>
|
|
<tr>
|
|
<td><code>RSA_PSS_SALTLEN_MAX_SIGN</code></td>
|
|
<td>Sets the salt length for <code>RSA_PKCS1_PSS_PADDING</code> to the
|
|
maximum permissible value when signing data.</td>
|
|
</tr>
|
|
<tr>
|
|
<td><code>RSA_PSS_SALTLEN_AUTO</code></td>
|
|
<td>Causes the salt length for <code>RSA_PKCS1_PSS_PADDING</code> to be
|
|
determined automatically when verifying a signature.</td>
|
|
</tr>
|
|
<tr>
|
|
<td><code>POINT_CONVERSION_COMPRESSED</code></td>
|
|
<td></td>
|
|
</tr>
|
|
<tr>
|
|
<td><code>POINT_CONVERSION_UNCOMPRESSED</code></td>
|
|
<td></td>
|
|
</tr>
|
|
<tr>
|
|
<td><code>POINT_CONVERSION_HYBRID</code></td>
|
|
<td></td>
|
|
</tr>
|
|
</tbody></table>
|
|
<h3>Node.js crypto constants<span><a class="mark" href="#crypto_node_js_crypto_constants" id="crypto_node_js_crypto_constants">#</a></span></h3>
|
|
<table>
|
|
<tbody><tr>
|
|
<th>Constant</th>
|
|
<th>Description</th>
|
|
</tr>
|
|
<tr>
|
|
<td><code>defaultCoreCipherList</code></td>
|
|
<td>Specifies the built-in default cipher list used by Node.js.</td>
|
|
</tr>
|
|
<tr>
|
|
<td><code>defaultCipherList</code></td>
|
|
<td>Specifies the active default cipher list used by the current Node.js
|
|
process.</td>
|
|
</tr>
|
|
</tbody></table>
|
|
<!-- API END -->
|
|
</div>
|
|
</div>
|
|
</div>
|
|
</body>
|
|
</html>
|