Skip to content
Tutorials Center
My learning

Topics

Lesson 73 of 133 ยท Security and Cryptography

Hashing and HMAC

Learn hashing in Node.js with node:crypto - createHash, SHA-256 and SHA-3, digest encodings, HMAC signatures, timingSafeEqual, hashing files with streams and content addressing.

A hash function takes any amount of data, a word, a photo or a 4 GB video, and squeezes it into a short fixed-size fingerprint. Change a single bit of the input and the fingerprint changes completely. The same input always gives the same fingerprint. And you cannot go backwards: from the fingerprint there is no practical way to rebuild the data.

Those properties make hashes useful everywhere: verifying that a download is not corrupted, detecting whether a file changed, naming files by their content, building cache keys, signing webhooks, and deduplicating data. Node.js has everything built in through the node:crypto module, with no packages to install.

In this lesson you will compute hashes, see how digests are encoded, make keyed hashes (HMAC) to prove who sent a message, compare secrets without leaking information through timing, and hash files of any size using streams. One important warning first: a plain hash is not a way to store passwords. That job needs a slow, salted algorithm, which is the topic of Passwords, scrypt and Tokens.

Your first hash

createHash(algorithm) returns a hash object. You feed it data with update() and ask for the result with digest(). After digest() the object is finished and cannot be used again.

Node.js SHA-256 of a string

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

SHA-256 always produces 256 bits, which is 32 bytes, or 64 hexadecimal characters. Changing "hello" to "hellp" produces a result with no visible relation to the first. This is called the avalanche effect.

Because update() returns the hash object, you can chain calls, and you can call it many times. Feeding data in pieces gives exactly the same answer as feeding it at once, which is what makes hashing a stream possible.

Node.js Chaining update calls

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

The one-shot crypto.hash()

For small inputs that are already in memory, newer Node.js versions (21.7 and 20.12 and later, so all of 22 and 24) have a shortcut, crypto.hash(algorithm, data, outputEncoding). It is shorter and, for small data, faster than creating an object. For streams or large files, use createHash.

Node.js crypto.hash one-shot

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Choosing an algorithm

You can list what your Node.js build supports with getHashes(). The names that matter in practice:

Algorithm Output size Use it for
sha256 32 bytes The default choice: checksums, content IDs, signatures, HMAC
sha512 64 bytes Same family, larger output; often faster than SHA-256 on 64-bit CPUs
sha3-256 32 bytes A different design (Keccak). A good choice when you want diversity
blake2b512 64 bytes Fast and modern, available when OpenSSL provides it
sha1 20 bytes Broken for security (collisions exist). Only for legacy formats such as Git
md5 16 bytes Broken for security. Only for non-security checksums of legacy systems
Node.js Sizes of different algorithms

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Never invent your own hashing scheme and never use MD5 or SHA-1 where an attacker could benefit from a collision (two different inputs with the same hash). With such a weak hash an attacker could craft two documents, show you one and later replace it with the other. For new work, SHA-256 is the safe default.

Digest encodings

digest() without an argument returns a Buffer of raw bytes. With an encoding name it returns a string. The common choices:

  • 'hex': lowercase hex, 2 characters per byte. Easy to read and compare; used for checksums.
  • 'base64': about 33 percent shorter than hex, but it contains +, / and =, which are awkward in URLs and file names.
  • 'base64url': the URL- and filename-safe form, without padding. Good for IDs inside URLs.
Node.js One digest, four representations

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

See Buffers for more about these encodings. A frequent source of bugs: two systems "hash the same text" but get different results. The cause is almost always different bytes going into the hash. A string is converted to bytes with an encoding (UTF-8 by default), and a trailing newline, different Unicode normalization or Windows line endings all change the bytes. When you must match another system, compare the exact input bytes first.

Node.js Strings are hashed as UTF-8 bytes

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

The two spellings of "cafรฉ" look identical on screen but are different byte sequences, so their hashes differ. If you hash user-provided text for comparison, normalize it first with normalize('NFC') (see Text, Encodings and Unicode).

HMAC: a hash with a secret key

A plain hash proves nothing about who made it. Anyone can hash a message. If you send a message and its SHA-256 along, an attacker can change the message and recompute the hash. An HMAC (hash-based message authentication code) mixes a secret key into the hashing, so only someone who knows the key can create or verify the value. It proves two things: the message was not changed, and it came from someone with the key.

createHmac(algorithm, key) works just like createHash.

Node.js Signing and verifying a message with HMAC

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

HMAC is how many webhook systems sign their requests (the sender includes X-Signature and you recompute it), how session cookies are signed and how JWTs with HS256 work (see Passwords, scrypt and Tokens). Do not build "hash(secret + message)" yourself: that construction has known weaknesses (length extension). Always use HMAC.

Keep these rules:

  • The key must be random and long (at least 32 bytes for SHA-256). Generate one with randomBytes(32) (see Randomness and Identifiers) and store it in configuration, never in source code.
  • Include everything that must be protected in the signed message: if the timestamp is not signed, an attacker can replay an old message with a new time.
  • Add an expiry or a timestamp to stop replay of an old valid message.

Comparing safely with timingSafeEqual

Look at sign(message) === signature above. The === operator on strings stops at the first character that differs. If the first character is wrong it returns very quickly; if the first 30 are right it takes slightly longer. A patient attacker can measure these tiny differences over thousands of requests and discover the correct signature character by character. This is a timing attack. It works over a network more often than people expect.

crypto.timingSafeEqual(a, b) compares two buffers in time that does not depend on where they differ. It requires both to have the same length and throws a RangeError otherwise, so check the length first. (Checking the length is fine to do quickly, because the length of an HMAC is public knowledge.)

Node.js Constant-time comparison

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

The last call shows the failure on purpose: lengths differ, so timingSafeEqual throws instead of returning false. Hence the explicit length check in verify. Use this function for any secret comparison: API keys, tokens, signatures, password reset codes.

Hashing files with streams

To checksum a large file you must not read it into memory. A Hash object is itself a stream (a Transform), so you can pipe the file into it. Use pipeline from node:stream/promises and read the result afterwards, as described in pipeline and Backpressure.

Node.js Hashing a file in chunks

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Memory use stays at a few chunks (64 KiB each) regardless of the size. A common real-world use is verifying a downloaded installer against the checksum published on the vendor's website, which is how sha256sum works on the command line.

If you also want to know how many bytes went through, count them in the same loop with for await:

Node.js Hash and size in one pass

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Content addressing and deduplication

If two pieces of data are equal exactly when their hashes are equal (which is true in practice for SHA-256), the hash can serve as the name of the data. This is called content addressing. Git works this way, as do Docker image layers and many build caches. The benefits are neat:

  • Deduplication. Storing the same file twice gives the same name, so you keep one copy.
  • Integrity. The name proves the content: if a hash does not match, the data is corrupted.
  • Cache busting. Web build tools put the content hash into file names (app.3f2a9c1d.js), so a changed file gets a new URL, and unchanged files stay cached forever.
Node.js A content-addressed store

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

The same trick makes good cache keys: hash the normalized request (URL, sorted parameters, user role) and use the digest as the key, as in Caching in Memory. It also gives short, uniform, safe file names for anything derived from user input.

Hash lengths, collisions and truncating

Sometimes you want a shorter ID, such as 8 characters for a build tag. Truncating a hash is allowed, but it raises the chance of an accidental collision. As a rough rule, with an n-bit identifier you will expect a collision after about 2^(n/2) items (the "birthday bound"). With 32 bits (8 hex characters) that is only about 65,000 items, so truncated hashes suit display labels, not unique keys for big datasets. For deduplication in a database keep the full digest.

Hashing is not encryption, and not for passwords

Two misunderstandings cause real damage.

Hashing is not encryption. You cannot decrypt a hash. If you need to get the original data back later, you want encryption (see Encryption: AES, RSA and Keys).

Plain SHA-256 is wrong for passwords. Hash functions are designed to be fast, and a graphics card can test billions of SHA-256 guesses per second. Attackers also use precomputed tables of common passwords. A password store needs a deliberately slow, memory-hungry function with a unique random salt per user, such as scrypt, which Node.js provides. We cover it in Passwords, scrypt and Tokens.

Do not store sha256(password) and do not sign cookies with sha256(secret + data). Use scrypt (or Argon2) for passwords and HMAC for authenticity.

Common mistakes

  • Reusing a finished hash object. After digest(), calling update() again throws ERR_CRYPTO_HASH_FINALIZED. Create a new object per computation.
  • Comparing with === when the value is secret. Use timingSafeEqual.
  • Hashing an object. update({a: 1}) throws a TypeError. Serialize it first, and remember JSON.stringify depends on key order, so use a canonical form if two systems must agree.
  • Forgetting the encoding. digest() returns a Buffer, and a Buffer in a template string prints bytes you did not expect. Ask for 'hex'.
  • Using MD5/SHA-1 "just to be quick". SHA-256 is fast enough for nearly everything.
Node.js Finalized hash and invalid input (fails on purpose)

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. Which property is true for every good hash function?

    Hashes are deterministic and show the avalanche effect. They are one-way. Collisions must exist in theory, but a good hash makes them infeasible to find.
  2. 2. What does an HMAC prove that a plain SHA-256 does not?

    Anyone can compute a plain hash. An HMAC needs the key, so only key holders can create a valid value. It does not hide the message.
  3. 3. Why use crypto.timingSafeEqual instead of === to compare signatures?

    String comparison stops at the first difference, so response times can reveal the right prefix. timingSafeEqual takes the same time either way.
  4. 4. What happens if you pass buffers of different lengths to timingSafeEqual?

    Both buffers must have equal length. Check the length yourself first and return false if it differs.
  5. 5. Why is SHA-256 alone a bad way to store passwords?

    Password storage needs a slow, salted algorithm such as scrypt. Fast hashes make brute force cheap.

Summary

  • createHash(alg).update(data).digest(encoding) computes a digest; crypto.hash(alg, data) is a one-shot shortcut for small in-memory inputs.
  • Use SHA-256 (or SHA-512/SHA-3) for new work. MD5 and SHA-1 are broken for security.
  • Digest encodings: Buffer, 'hex', 'base64', 'base64url'. Matching hashes need identical input bytes, including encoding and normalization.
  • HMAC with a secret key proves integrity and origin. Never roll your own hash(secret + message).
  • Compare secrets with timingSafeEqual after checking lengths.
  • A Hash is a stream: pipe files through it to checksum any size in constant memory.
  • Content addressing names data by its hash for deduplication, integrity and cache busting.
  • Hashing is not encryption and plain hashes are wrong for passwords.

Next: Randomness and Identifiers