Node crypto без ошибок: KDF, HMAC, подписи и сравнение за константное время

Хэш против HMAC: целостность, а затем аутентифицированная целостность

Обычный хэш отвечает на один вопрос: менялись ли эти байты? crypto.createHash('sha256') отображает вход в дайджест фиксированной длины, поэтому одинаковый вход всегда даёт одинаковый выход, и любая подмена его меняет. Это годится для контрольной суммы контента или ключа кэша — но ничего не доказывает о том, кто его произвёл. Дайджест может пересчитать кто угодно, поэтому атакующий, изменивший сообщение, просто пересчитает его хэш, и ты этого не отличишь.

HMAC закрывает этот пробел. Он подмешивает в хэш секретный ключ, поэтому валидный тег могут произвести или проверить только стороны, владеющие ключом. Используй обычный хэш для целостности против случайного повреждения; используй HMAC, когда нужна аутентифицированная целостность — доказательство, что значение пришло от того, кто знает ключ. Подписанные cookie, подписи webhook’ов (Stripe, GitHub) и stateless-токены опираются на HMAC, а не на голый хэш.

const crypto = require('node:crypto');

// Обычный хэш — только целостность, пересчитать может кто угодно
const digest = crypto.createHash('sha256').update(payload).digest('hex');

// HMAC — с ключом, валидный тег производят/проверяют только владельцы ключа
const key = process.env.WEBHOOK_SECRET;
const tag = crypto.createHmac('sha256', key).update(rawBody).digest('hex');
// позже: сравни `tag` со значением из заголовка через timingSafeEqual (ниже)

Паролям нужен KDF, а не быстрый хэш

Баг из хука — самая частая crypto-ошибка в веб-приложениях: хэширование паролей быстрым алгоритмом. SHA-256, SHA-512 и MD5 спроектированы быть быстрыми, а это ровно то, чего для паролей хотеть не надо: скорость помогает атакующему перебирать офлайн. Утёкшая база несолёных SHA-256-дайджестов падает под GPU, делающими миллиарды догадок в секунду, а одинаковые пароли дают одинаковые дайджесты, поэтому работают rainbow-таблицы и атаки «взломай раз — подбери многим».

Хранению паролей нужна функция вывода ключа (KDF): намеренно медленная, memory-hard и солёная для каждого пароля. Node поставляет scrypt и pbkdf2 нативно; argon2 и bcrypt доступны через библиотеки. Salt (из CSPRNG) делает каждый хэш уникальным, так что одинаковые пароли различаются, а rainbow-таблицы умирают; cost factor делает каждую догадку дорогой. Всегда используй асинхронную форму, чтобы не блокировать event loop, пока KDF намеренно жжёт CPU.

const crypto = require('node:crypto');

function hashPassword(password) {
  return new Promise((resolve, reject) => {
    const salt = crypto.randomBytes(16);          // уникальный на пароль, из CSPRNG
    // cost N=2**15, выход 64 байта; salt хранится рядом с хэшем.
    // maxmem нужно поднять: scrypt требует 128*N*r байт (здесь 32 МиБ), а
    // дефолтный лимит maxmem — ровно 32 МиБ, поэтому любой реальный cost падает без него.
    crypto.scrypt(password, salt, 64, { N: 2 ** 15, maxmem: 64 * 1024 * 1024 }, (err, hash) => {
      if (err) return reject(err);
      resolve(`${salt.toString('hex')}:${hash.toString('hex')}`);
    });
  });
}

function verifyPassword(password, stored) {
  return new Promise((resolve, reject) => {
    const [saltHex, hashHex] = stored.split(':');
    const salt = Buffer.from(saltHex, 'hex');
    const expected = Buffer.from(hashHex, 'hex');
    crypto.scrypt(password, salt, expected.length, { N: 2 ** 15, maxmem: 64 * 1024 * 1024 }, (err, actual) => {
      if (err) return reject(err);
      resolve(crypto.timingSafeEqual(actual, expected)); // константное время, ниже
    });
  });
}

// использование — хэш при регистрации, проверка при логине (и смоук-тест, что cost-параметры исполняются)
const stored = await hashPassword('correct horse battery staple');
console.log('verify correct:', await verifyPassword('correct horse battery staple', stored)); // true
console.log('verify wrong:  ', await verifyPassword('wrong', stored));                         // false

Асимметричные подписи: доказать происхождение без общего секрета

HMAC работает, когда обе стороны делят один секрет. Когда не могут — ты хочешь опубликовать нечто, что проверить может кто угодно, а произвести только ты (релиз ПО, JWT, подписанный сервером авторизации, лицензия) — нужна асимметричная подпись. Ты подписываешь приватным ключом, а проверяет любой соответствующим публичным. Публичный ключ не даёт никакой возможности подделать; подписать может только приватный.

const crypto = require('node:crypto');

const { privateKey, publicKey } = crypto.generateKeyPairSync('ed25519');

// Подпись приватным ключом (Ed25519 принимает null как аргумент алгоритма)
const signature = crypto.sign(null, Buffer.from(message), privateKey);

// Любой с публичным ключом проверяет — возвращает true/false
const ok = crypto.verify(null, Buffer.from(message), publicKey, signature);

Для потоковых или больших входов используй объектный API crypto.createSign('SHA256') / crypto.createVerify('SHA256') с ключами RSA или ECDSA: многократно .update(chunk), затем .sign(privateKey) / .verify(publicKey, sig). Выбор ключа — HMAC против подписи — про то, можно ли доверять проверяющим силу подписи.

Случайность и сравнение за константное время: два тихих footgun’а

Ещё две ошибки коварны, потому что код работает нормально. Когда тянешься за Math.random(), чтобы сгенерировать токен, всё работает — пока не перестаёт. Первая — случайность: Math.random() — это быстрый PRNG (псевдослучайный генератор) без криптографических гарантий; его выход предсказуем и никогда не должен генерировать токены, salt, session ID или ключи. Используй crypto.randomBytes(n) (CSPRNG — криптографически стойкий генератор псевдослучайных чисел) для сырых байтов и crypto.randomUUID() для идентификаторов. Вторая — сравнение: сравнение секретов через ===, == или Buffer.compare выходит на первом отличающемся байте, поэтому затраченное время утекает, сколько ведущих байтов совпало — и атакующий восстанавливает токен байт за байтом, измеряя время ответа. Используй crypto.timingSafeEqual(a, b), который сравнивает за константное время. Он требует два Buffer равной длины (иначе бросает исключение), поэтому сначала приведи обе стороны к фиксированной длине хэшем или проверь длину перед вызовом.

const crypto = require('node:crypto');

// НЕВЕРНО — утекает через тайминг, сколько ведущих байтов совпало
if (userToken === storedToken) grantAccess();

// ВЕРНО — константное время; оба Buffer должны быть равной длины
const a = Buffer.from(userToken);
const b = Buffer.from(storedToken);
if (a.length === b.length && crypto.timingSafeEqual(a, b)) grantAccess();