sodium_crypto_pwhash

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_pwhash — Получает ключ из пароля алгоритмом Argon2

Описание

sodium_crypto_pwhash(
    int $length,
    #[\SensitiveParameter] string $password,
    string $salt,
    int $opslimit,
    int $memlimit,
    int $algo = SODIUM_CRYPTO_PWHASH_ALG_DEFAULT
): string

Функция предоставляет низкоуровневый доступ к функции crypto_pwhash библиотеки libsodium. Если у отсутствует принципиальная необходимость в этой функции, лучше пользоваться функциями sodium_crypto_pwhash_str() или password_hash().

Распространённая причина, по которой вызывают эту функцию — получить начальные числа для криптографических ключей из пароля и соли, а затем использовать эти начальные числа для генерации фактических ключей, необходимых для некоторых целей (например, подписать сообщение, как делает функция sodium_crypto_sign_detached()).

Список параметров

length: Целое число (int); Длина хеша пароля в байтах.
password: Строка (string); Пароль, для которого функция создаёт хеш.
salt: Соль, которую добавляют к паролю перед хешированием. Соль должна быть непредсказуемой, в идеале генерироваться из хорошего источника случайных чисел наподобие функции random_bytes() и быть длиной, равной значению константы SODIUM_CRYPTO_PWHASH_SALTBYTES.
opslimit: Представляет максимальное количество вычислений для выполнения Увеличение этого числа приведёт к тому, что функции потребуется больше циклов ЦП для вычисления ключа. Существуют константы, доступные для установки предела операций для соответствующих значений в зависимости от предполагаемого использования, в порядке убывания: SODIUM_CRYPTO_PWHASH_OPSLIMIT_INTERACTIVE, SODIUM_CRYPTO_PWHASH_OPSLIMIT_MODERATE и SODIUM_CRYPTO_PWHASH_OPSLIMIT_SENSITIVE.
memlimit: Максимальный объем ОЗУ в байтах, который будет использовать функция. Выбрать подходящее значение помогают константы в порядке размера: SODIUM_CRYPTO_PWHASH_MEMLIMIT_INTERACTIVE, SODIUM_CRYPTO_PWHASH_MEMLIMIT_MODERATE и SODIUM_CRYPTO_PWHASH_MEMLIMIT_SENSITIVE. Как правило, константы должны сочетаться со значениями opslimit, которым они соответствуют.
algo: Цело число (int), которое указывает алгоритм хеширования. По умолчанию задана константа SODIUM_CRYPTO_PWHASH_ALG_DEFAULT (рекомендуемый алгоритм, который изменяется от версии к версии модуля libsodium), или явно задать константу SODIUM_CRYPTO_PWHASH_ALG_ARGON2ID13, которая представляет версию алгоритма Argon2id 1.3.

Возвращаемые значения

Функция возвращает захешированный пароль. Возвращаемое значение — двоичная строка хеша, а не ASCII-представление, и не содержит дополнительной информации о параметрах, с которыми генерировался хеш, поэтому разработчик сам сохраняет значения параметров для проверки корректности хеша в будущем. Чтобы избежать этого, пользуются функцией sodium_crypto_pwhash_str().

Примеры

Пример #1 Пример использования функции password_hash()

<?php

// Для будущей проверки нужно сохранить соль
$salt = random_bytes(SODIUM_CRYPTO_PWHASH_SALTBYTES);

// Вызываем функцию bin2hex для удобочитаемости
echo bin2hex(
    sodium_crypto_pwhash(
        16, // == 128 бит
        'password',
        $salt,
        SODIUM_CRYPTO_PWHASH_OPSLIMIT_INTERACTIVE,
        SODIUM_CRYPTO_PWHASH_MEMLIMIT_INTERACTIVE,
        SODIUM_CRYPTO_PWHASH_ALG_ARGON2ID13
    )
);

?>

Вывод приведённого примера будет похож на:

a18f346ba57992eb7e4ae6abf3fd30ee