HS256 Secret Key Requirements: Specifications, Code Examples, and Common Traps

HMAC combines a cryptographic hash function (SHA-256) with a secret key. In the HMAC construction: $$\text{HMAC}(K, m) = H((K' \oplus \text{opad}) \parallel H((K' \oplus \text{ipad}) \parallel m))$$ If the secret key $K$ is shorter than the block size of the hash function (64 bytes for SHA-256), it must be padded. If it is shorter than the digest length (32 bytes / 256 bits), it represents a weak link.

When verifying an HS256 token, always explicitly declare the allowed algorithms. Never permit the library to accept whatever algorithm is declared in the untrusted token header!

const jwt = require('jsonwebtoken');

// Always enforce algorithms whitelist:
jwt.verify(token, process.env.JWT_SECRET, {
  algorithms: ['HS256'], // Enforces HS256; rejects "none" or "RS256"
  issuer: 'https://api.jwtsecretkey.com',
  audience: 'https://jwtsecretkey.com',
});