Контрольные суммы и ключи

Объект PK предоставляет 17 методов этой группы. Быстрые контрольные суммы сравнивают содержимое, парольные функции затрудняют перебор, производные ключи создают ключ заданного размера, а UUID служит только идентификатором. Одинаковый строковый тип результата не делает эти задачи взаимозаменяемыми.

Что выбрать

Функция HMAC и её поддерживаемые алгоритмы разобраны в справке in-Line Kit. Не придумывайте вызов PK.hmac: такого публичного метода нет.

Границы безопасности

Для методов с объектом параметров передавайте JSON.stringify({...}). Это сохраняет кавычки, обратные косые черты и переводы строк внутри пароля, соли или сообщения и исключает ручное составление JSON.

Простые контрольные суммы

Все четыре метода принимают input: string, не меняют состояние проекта и возвращают шестнадцатеричную строку в нижнем регистре. Примеры используют demo, чтобы результат можно было сверить буквально.

const digest = PK.md5("demo");
// digest === "fe01ce2a7fbac8fafaed7c982a04e229"

const digest = PK.sha1("demo");
// digest === "89e495e7941cf9e40e6980d14a16bf023ccd4c91"

Настраиваемая SHA-2

PK.SHA2Hash(input)

Принимает строку JSON с текстом, размером SHA-2 и видом результата. Неизвестное или повторяющееся поле возвращает строку ошибки.

const digest = PK.SHA2Hash(JSON.stringify({
  text: "demo",
  hashSizeBits: 256,
  outputFormat: "hexa",
}));

// digest === "2A97516C354B68848CDBD8F54A226A0A55B21ED138E207AD6C5CBB9C00AA5AEA"

Шестнадцатеричный результат здесь использует верхний регистр, в отличие от PK.sha256. Вариант base64url сохраняет конечные =. Все размеры и виды результата приведены в справке по SHA2HASH.

SHA-3 и XOF

PK.SHA3Hash(input)

Принимает строку JSON. Для обычной SHA-3 укажите type: "sha"; для результата расширяемой длины — type: "xof".

const digest = PK.SHA3Hash(JSON.stringify({
  text: "demo",
  type: "sha",
  hashSizeBits: 256,
  outputFormat: "hexa",
  version: 256,
}));

// digest === "7F23E6CA181CC91D57245809EDB1097A1F14ED011E4A9520A8DD10AA3EF82789"

outputFormat принимает hexa, base64, base64url или base32. Ошибочно указанное bytes и любое другое значение молча выбирает hexa. Поле version — необязательное целое, по умолчанию 256; оно передаётся движку SHA-3. Значение type приводится к нижнему регистру, после чего только sha включает обычную SHA-3; любое другое значение попадает в ветвь XOF, поэтому проверяйте это поле до вызова. Полный договор приведён в справке по SHA3HASH.

Другие контрольные суммы

Следующие четыре метода принимают input: string, вычисляют контрольную сумму текста UTF-8 и не меняют состояние проекта. При внутренней ошибке они возвращают обычную строку с началом Error: .

PK.blake2bEncode(input)

Использует BLAKE2b-256 и возвращает 32 байта как 64 шестнадцатеричных знака.

const digest = PK.blake2bEncode("SEO_AUDIT_2026");

Точная общая операция приведена в справке по BLAKE2BENCODE.

PK.whirlpoolEncode(input)

Использует Whirlpool и возвращает 64 байта как 128 шестнадцатеричных знаков.

const digest = PK.whirlpoolEncode("BrandSafetyCheck");

Точная общая операция приведена в справке по WHIRLPOOLENCODE.

PK.XXHashEncode(input)

Использует xxHash32 и возвращает только 4 байта как 8 шестнадцатеричных знаков. Это быстрая контрольная сумма для таблиц, разбиения и обнаружения случайных изменений, а не средство безопасности.

const bucketDigest = PK.XXHashEncode("feed/products?page=4");

Назначение и размер объяснены в справке по XXHASHENCODE.

PK.keccak256Hash(input)

Использует Keccak-256 и возвращает 32 байта как 64 шестнадцатеричных знака. Keccak-256 и стандартизованная SHA3-256 применяют разные правила дополнения и дают разные результаты.

const digest = PK.keccak256Hash("wallet-checksum-demo");

Отличие от SHA3-256 закреплено в справке по KECCAK256HASH.

Ключевой BLAKE3

PK.blake3Encode(input)

Принимает строку JSON с message и ключом key в шестнадцатеричной форме. Несмотря на необязательность поля при разборе, без ключа исполнитель не создаёт BLAKE3 и возвращает ошибку, поэтому в действующем договоре ключ обязателен.

const digest = PK.blake3Encode(JSON.stringify({
  message: "demo",
  key: "00112233445566778899aabbccddeeff00112233445566778899aabbccddeeff",
}));

Ключ в примере показывает только форму. Используйте отдельный секрет из защищённого источника и не записывайте его в журнал. Преобразователь не подтверждает, что каждый шестнадцатеричный знак прочитан успешно, поэтому входной ключ должен быть проверен на границе получения. Подробности приведены в справке по BLAKE3ENCODE.

Пароли и производные ключи

Соль не обязана быть секретной, но должна быть отдельной и уникальной для каждого пароля. Не создавайте её через PK.randomBytes: этот метод использует обычный псевдослучайный генератор, не предназначенный для защиты.

PK.generatePBKDF2Key(input)

Создаёт производный ключ PBKDF2 по строке JSON.

const key = PK.generatePBKDF2Key(JSON.stringify({
  text: "demo",
  salt: "salt123",
  keyLength: 256,
  hashSizeBits: 256,
  counter: 10000,
  hashFunction: "sha2",
  outputFormat: "hexa",
}));

keyLength: 256 создаёт 32 байта; значение 32 создало бы только 4 байта. Для SHA-1 hashSizeBits равен 160; для SHA-2 и SHA-3 доступны 224, 256, 384, 512. Полный договор приведён в справке по PBKDF2KEY.

PK.generateScryptKey(input)

Создаёт производный ключ scrypt и возвращает его шестнадцатеричную строку.

const key = PK.generateScryptKey(JSON.stringify({
  password: "demo",
  salt: "salt123",
  N: 16384,
  r: 8,
  p: 1,
  outputSize: 32,
}));

N должна быть степенью двойки больше единицы, r и p — положительными целыми. При N: 16384 и r: 8 один вызов требует примерно 16 МиБ основной памяти. Ошибка разбора обычно возвращает SCrypt error: ..., но часть ошибок вычисления возвращает пустую строку; принимайте только результат ожидаемой шестнадцатеричной длины. Подробности приведены в справке по SCRYPT.

PK.bcryptHash(input)

Создаёт 60-знаковую строку BCrypt. Передавайте объект JSON, чтобы опечатка в структуре не превратила весь аргумент в обычный пароль со стоимостью 10.

const passwordHash = PK.bcryptHash(JSON.stringify({
  text: "demo",
  cost: 10,
}));

Без поля salt каждый вызов создаёт новую соль, поэтому одинаковый пароль обычно даёт разные корректные строки. Не проверяйте пароль сравнением с новым вызовом: нужна проверка BCrypt по сохранённой строке, а отдельного публичного метода проверки у PK нет. Явная соль и точные формы разобраны в справке по BCRYPT.

PK.argon2Hash(input)

Создаёт производный результат Argon2 и возвращает только шестнадцатеричную строку. Соль и параметры в результат не включаются.

const passwordHash = PK.argon2Hash(JSON.stringify({
  password: "demo",
  salt: "salt123",
  iterations: 2,
  memory: 65536,
  parallelism: 1,
  type: "Argon2id",
  version: "1.3",
  outputLength: 32,
}));

Неизвестное значение type молча выбирает Argon2id, поэтому передавайте одно из трёх точных имён. Значение memory: 65536 требует около 64 МиБ на каждый одновременный вызов. Для последующей проверки сохраняйте точную соль, iterations, memory, parallelism, type, version и outputLength. Полный договор приведён в справке по ARGON2HASH.

Случайные данные и идентификатор

const byteValues = JSON.parse(PK.randomBytes(16));