crypto: add Hash.prototype.copy() method

Make it possible to clone the internal state of a Hash object
into a new Hash object, i.e., to fork the state of the object.

Fixes: https://github.com/nodejs/node/issues/29903

PR-URL: https://github.com/nodejs/node/pull/29910
Reviewed-By: Colin Ihrig <cjihrig@gmail.com>
Reviewed-By: Sam Roberts <vieuxtech@gmail.com>
Reviewed-By: Tobias Nießen <tniessen@tnie.de>
Reviewed-By: David Carlier <devnexen@gmail.com>
Reviewed-By: James M Snell <jasnell@gmail.com>

1 files changed, 37 insertions, 0 deletions

diff --git a/doc/api/crypto.md b/doc/api/crypto.md
index 345ce54296..31fa812f91 100644
--- a/doc/api/crypto.md
+++ b/doc/api/crypto.md
@@ -1041,6 +1041,43 @@ console.log(hash.digest('hex'));
 //   6a2da20943931e9834fc12cfe5bb47bbd9ae43489a30726962b576f4e3993e50
 ```
 
+### hash.copy(\[options\])
+<!-- YAML
+added:
+  - version: REPLACEME
+    pr-url: https://github.com/nodejs/node/pull/29910
+-->
+
+* `options` {Object} [`stream.transform` options][]
+* Returns: {Hash}
+
+Creates a new `Hash` object that contains a deep copy of the internal state
+of the current `Hash` object.
+
+The optional `options` argument controls stream behavior. For XOF hash
+functions such as `'shake256'`, the `outputLength` option can be used to
+specify the desired output length in bytes.
+
+An error is thrown when an attempt is made to copy the `Hash` object after
+its [`hash.digest()`][] method has been called.
+
+```js
+// Calculate a rolling hash.
+const crypto = require('crypto');
+const hash = crypto.createHash('sha256');
+
+hash.update('one');
+console.log(hash.copy().digest('hex'));
+
+hash.update('two');
+console.log(hash.copy().digest('hex'));
+
+hash.update('three');
+console.log(hash.copy().digest('hex'));
+
+// Etc.
+```
+
 ### hash.digest(\[encoding\])
 <!-- YAML
 added: v0.1.92