PHP: полный мануал с примерами, функциями и ООП

<?php
declare(strict_types=1);

$available = sodium_crypto_aead_aes256gcm_is_available();
echo $available ? "AES-GCM: доступен\n" : "AES-GCM: недоступен\n";

AES-GCM: доступен

Проверка относится к текущей машине. Переносимый формат не должен молча рассчитывать, что AES-GCM есть в каждой сборке.

<?php
declare(strict_types=1);

if (!sodium_crypto_aead_aes256gcm_is_available()) { echo "AES-GCM: недоступен\n"; return; }
$key = sodium_crypto_aead_aes256gcm_keygen();
$nonce = random_bytes(SODIUM_CRYPTO_AEAD_AES256GCM_NPUBBYTES);
$orderId = 'order:742';
$plain = 'Сумма 1250 ₽';
$cipher = sodium_crypto_aead_aes256gcm_encrypt($plain, $orderId, $nonce, $key);
$restored = sodium_crypto_aead_aes256gcm_decrypt($cipher, $orderId, $nonce, $key);
$wrongOrder = sodium_crypto_aead_aes256gcm_decrypt($cipher, 'order:743', $nonce, $key);

echo 'восстановлено: ', $restored, "\n";
echo 'подмена ID: ', $wrongOrder === false ? 'отклонена' : 'пропущена', "\n";
echo 'служебные данные открыты: ', $orderId, "\n";

восстановлено: Сумма 1250 ₽
подмена ID: отклонена
служебные данные открыты: order:742

Это модель записи заказа: nonce и order ID можно хранить рядом с шифротекстом, ключ — отдельно. Изменение AAD обнаруживается до выдачи текста.

<?php
declare(strict_types=1);

if (!sodium_crypto_aead_aes256gcm_is_available()) { echo "AES-GCM: недоступен\n"; return; }
$key = sodium_crypto_aead_aes256gcm_keygen();
$nonce = random_bytes(SODIUM_CRYPTO_AEAD_AES256GCM_NPUBBYTES);
$orderId = 'order:742';
$plain = 'Сумма 1250 ₽';
$cipher = sodium_crypto_aead_aes256gcm_encrypt($plain, $orderId, $nonce, $key);
$restored = sodium_crypto_aead_aes256gcm_decrypt($cipher, $orderId, $nonce, $key);
$wrongOrder = sodium_crypto_aead_aes256gcm_decrypt($cipher, 'order:743', $nonce, $key);

echo 'восстановлено: ', $restored, "\n";
echo 'подмена ID: ', $wrongOrder === false ? 'отклонена' : 'пропущена', "\n";
echo 'служебные данные открыты: ', $orderId, "\n";

восстановлено: Сумма 1250 ₽
подмена ID: отклонена
служебные данные открыты: order:742

Это модель записи заказа: nonce и order ID можно хранить рядом с шифротекстом, ключ — отдельно. Изменение AAD обнаруживается до выдачи текста.

<?php
declare(strict_types=1);

$key = sodium_crypto_aead_aes256gcm_keygen();
echo 'ключ создан: ', strlen($key), ' байт', "\n";

ключ создан: 32 байт

Выводим только длину случайного ключа. Сам ключ намеренно не попадает ни в страницу, ни в журнал.

<?php
declare(strict_types=1);

$key = sodium_crypto_aead_aegis128l_keygen();
$nonce = random_bytes(SODIUM_CRYPTO_AEAD_AEGIS128L_NPUBBYTES);
$orderId = 'order:742';
$plain = 'Сумма 1250 ₽';
$cipher = sodium_crypto_aead_aegis128l_encrypt($plain, $orderId, $nonce, $key);
$restored = sodium_crypto_aead_aegis128l_decrypt($cipher, $orderId, $nonce, $key);
$wrongOrder = sodium_crypto_aead_aegis128l_decrypt($cipher, 'order:743', $nonce, $key);

echo 'восстановлено: ', $restored, "\n";
echo 'подмена ID: ', $wrongOrder === false ? 'отклонена' : 'пропущена', "\n";
echo 'служебные данные открыты: ', $orderId, "\n";

восстановлено: Сумма 1250 ₽
подмена ID: отклонена
служебные данные открыты: order:742

Это модель записи заказа: nonce и order ID можно хранить рядом с шифротекстом, ключ — отдельно. Изменение AAD обнаруживается до выдачи текста.

<?php
declare(strict_types=1);

$key = sodium_crypto_aead_aegis128l_keygen();
$nonce = random_bytes(SODIUM_CRYPTO_AEAD_AEGIS128L_NPUBBYTES);
$orderId = 'order:742';
$plain = 'Сумма 1250 ₽';
$cipher = sodium_crypto_aead_aegis128l_encrypt($plain, $orderId, $nonce, $key);
$restored = sodium_crypto_aead_aegis128l_decrypt($cipher, $orderId, $nonce, $key);
$wrongOrder = sodium_crypto_aead_aegis128l_decrypt($cipher, 'order:743', $nonce, $key);

echo 'восстановлено: ', $restored, "\n";
echo 'подмена ID: ', $wrongOrder === false ? 'отклонена' : 'пропущена', "\n";
echo 'служебные данные открыты: ', $orderId, "\n";

восстановлено: Сумма 1250 ₽
подмена ID: отклонена
служебные данные открыты: order:742

Это модель записи заказа: nonce и order ID можно хранить рядом с шифротекстом, ключ — отдельно. Изменение AAD обнаруживается до выдачи текста.

<?php
declare(strict_types=1);

$key = sodium_crypto_aead_aegis128l_keygen();
echo 'ключ создан: ', strlen($key), ' байт', "\n";

ключ создан: 16 байт

Выводим только длину случайного ключа. Сам ключ намеренно не попадает ни в страницу, ни в журнал.

<?php
declare(strict_types=1);

$key = sodium_crypto_aead_aegis256_keygen();
$nonce = random_bytes(SODIUM_CRYPTO_AEAD_AEGIS256_NPUBBYTES);
$orderId = 'order:742';
$plain = 'Сумма 1250 ₽';
$cipher = sodium_crypto_aead_aegis256_encrypt($plain, $orderId, $nonce, $key);
$restored = sodium_crypto_aead_aegis256_decrypt($cipher, $orderId, $nonce, $key);
$wrongOrder = sodium_crypto_aead_aegis256_decrypt($cipher, 'order:743', $nonce, $key);

echo 'восстановлено: ', $restored, "\n";
echo 'подмена ID: ', $wrongOrder === false ? 'отклонена' : 'пропущена', "\n";
echo 'служебные данные открыты: ', $orderId, "\n";

восстановлено: Сумма 1250 ₽
подмена ID: отклонена
служебные данные открыты: order:742

Это модель записи заказа: nonce и order ID можно хранить рядом с шифротекстом, ключ — отдельно. Изменение AAD обнаруживается до выдачи текста.

<?php
declare(strict_types=1);

$key = sodium_crypto_aead_aegis256_keygen();
$nonce = random_bytes(SODIUM_CRYPTO_AEAD_AEGIS256_NPUBBYTES);
$orderId = 'order:742';
$plain = 'Сумма 1250 ₽';
$cipher = sodium_crypto_aead_aegis256_encrypt($plain, $orderId, $nonce, $key);
$restored = sodium_crypto_aead_aegis256_decrypt($cipher, $orderId, $nonce, $key);
$wrongOrder = sodium_crypto_aead_aegis256_decrypt($cipher, 'order:743', $nonce, $key);

echo 'восстановлено: ', $restored, "\n";
echo 'подмена ID: ', $wrongOrder === false ? 'отклонена' : 'пропущена', "\n";
echo 'служебные данные открыты: ', $orderId, "\n";

восстановлено: Сумма 1250 ₽
подмена ID: отклонена
служебные данные открыты: order:742

Это модель записи заказа: nonce и order ID можно хранить рядом с шифротекстом, ключ — отдельно. Изменение AAD обнаруживается до выдачи текста.

<?php
declare(strict_types=1);

$key = sodium_crypto_aead_aegis256_keygen();
echo 'ключ создан: ', strlen($key), ' байт', "\n";

ключ создан: 32 байт

Выводим только длину случайного ключа. Сам ключ намеренно не попадает ни в страницу, ни в журнал.

<?php
declare(strict_types=1);

$key = sodium_crypto_aead_chacha20poly1305_keygen();
$nonce = random_bytes(SODIUM_CRYPTO_AEAD_CHACHA20POLY1305_NPUBBYTES);
$orderId = 'order:742';
$plain = 'Сумма 1250 ₽';
$cipher = sodium_crypto_aead_chacha20poly1305_encrypt($plain, $orderId, $nonce, $key);
$restored = sodium_crypto_aead_chacha20poly1305_decrypt($cipher, $orderId, $nonce, $key);
$wrongOrder = sodium_crypto_aead_chacha20poly1305_decrypt($cipher, 'order:743', $nonce, $key);

echo 'восстановлено: ', $restored, "\n";
echo 'подмена ID: ', $wrongOrder === false ? 'отклонена' : 'пропущена', "\n";
echo 'служебные данные открыты: ', $orderId, "\n";

восстановлено: Сумма 1250 ₽
подмена ID: отклонена
служебные данные открыты: order:742

Это модель записи заказа: nonce и order ID можно хранить рядом с шифротекстом, ключ — отдельно. Изменение AAD обнаруживается до выдачи текста.

<?php
declare(strict_types=1);

$key = sodium_crypto_aead_chacha20poly1305_keygen();
$nonce = random_bytes(SODIUM_CRYPTO_AEAD_CHACHA20POLY1305_NPUBBYTES);
$orderId = 'order:742';
$plain = 'Сумма 1250 ₽';
$cipher = sodium_crypto_aead_chacha20poly1305_encrypt($plain, $orderId, $nonce, $key);
$restored = sodium_crypto_aead_chacha20poly1305_decrypt($cipher, $orderId, $nonce, $key);
$wrongOrder = sodium_crypto_aead_chacha20poly1305_decrypt($cipher, 'order:743', $nonce, $key);

echo 'восстановлено: ', $restored, "\n";
echo 'подмена ID: ', $wrongOrder === false ? 'отклонена' : 'пропущена', "\n";
echo 'служебные данные открыты: ', $orderId, "\n";

восстановлено: Сумма 1250 ₽
подмена ID: отклонена
служебные данные открыты: order:742

Это модель записи заказа: nonce и order ID можно хранить рядом с шифротекстом, ключ — отдельно. Изменение AAD обнаруживается до выдачи текста.

<?php
declare(strict_types=1);

$key = sodium_crypto_aead_chacha20poly1305_keygen();
echo 'ключ создан: ', strlen($key), ' байт', "\n";

ключ создан: 32 байт

Выводим только длину случайного ключа. Сам ключ намеренно не попадает ни в страницу, ни в журнал.

<?php
declare(strict_types=1);

$key = sodium_crypto_aead_chacha20poly1305_ietf_keygen();
$nonce = random_bytes(SODIUM_CRYPTO_AEAD_CHACHA20POLY1305_IETF_NPUBBYTES);
$orderId = 'order:742';
$plain = 'Сумма 1250 ₽';
$cipher = sodium_crypto_aead_chacha20poly1305_ietf_encrypt($plain, $orderId, $nonce, $key);
$restored = sodium_crypto_aead_chacha20poly1305_ietf_decrypt($cipher, $orderId, $nonce, $key);
$wrongOrder = sodium_crypto_aead_chacha20poly1305_ietf_decrypt($cipher, 'order:743', $nonce, $key);

echo 'восстановлено: ', $restored, "\n";
echo 'подмена ID: ', $wrongOrder === false ? 'отклонена' : 'пропущена', "\n";
echo 'служебные данные открыты: ', $orderId, "\n";

восстановлено: Сумма 1250 ₽
подмена ID: отклонена
служебные данные открыты: order:742

Это модель записи заказа: nonce и order ID можно хранить рядом с шифротекстом, ключ — отдельно. Изменение AAD обнаруживается до выдачи текста.

<?php
declare(strict_types=1);

$key = sodium_crypto_aead_chacha20poly1305_ietf_keygen();
$nonce = random_bytes(SODIUM_CRYPTO_AEAD_CHACHA20POLY1305_IETF_NPUBBYTES);
$orderId = 'order:742';
$plain = 'Сумма 1250 ₽';
$cipher = sodium_crypto_aead_chacha20poly1305_ietf_encrypt($plain, $orderId, $nonce, $key);
$restored = sodium_crypto_aead_chacha20poly1305_ietf_decrypt($cipher, $orderId, $nonce, $key);
$wrongOrder = sodium_crypto_aead_chacha20poly1305_ietf_decrypt($cipher, 'order:743', $nonce, $key);

echo 'восстановлено: ', $restored, "\n";
echo 'подмена ID: ', $wrongOrder === false ? 'отклонена' : 'пропущена', "\n";
echo 'служебные данные открыты: ', $orderId, "\n";

восстановлено: Сумма 1250 ₽
подмена ID: отклонена
служебные данные открыты: order:742

Это модель записи заказа: nonce и order ID можно хранить рядом с шифротекстом, ключ — отдельно. Изменение AAD обнаруживается до выдачи текста.

<?php
declare(strict_types=1);

$key = sodium_crypto_aead_chacha20poly1305_ietf_keygen();
echo 'ключ создан: ', strlen($key), ' байт', "\n";

ключ создан: 32 байт

Выводим только длину случайного ключа. Сам ключ намеренно не попадает ни в страницу, ни в журнал.

<?php
declare(strict_types=1);

$key = sodium_crypto_aead_xchacha20poly1305_ietf_keygen();
$nonce = random_bytes(SODIUM_CRYPTO_AEAD_XCHACHA20POLY1305_IETF_NPUBBYTES);
$orderId = 'order:742';
$plain = 'Сумма 1250 ₽';
$cipher = sodium_crypto_aead_xchacha20poly1305_ietf_encrypt($plain, $orderId, $nonce, $key);
$restored = sodium_crypto_aead_xchacha20poly1305_ietf_decrypt($cipher, $orderId, $nonce, $key);
$wrongOrder = sodium_crypto_aead_xchacha20poly1305_ietf_decrypt($cipher, 'order:743', $nonce, $key);

echo 'восстановлено: ', $restored, "\n";
echo 'подмена ID: ', $wrongOrder === false ? 'отклонена' : 'пропущена', "\n";
echo 'служебные данные открыты: ', $orderId, "\n";

восстановлено: Сумма 1250 ₽
подмена ID: отклонена
служебные данные открыты: order:742

Это модель записи заказа: nonce и order ID можно хранить рядом с шифротекстом, ключ — отдельно. Изменение AAD обнаруживается до выдачи текста.

<?php
declare(strict_types=1);

$key = sodium_crypto_aead_xchacha20poly1305_ietf_keygen();
echo 'ключ создан: ', strlen($key), ' байт', "\n";

ключ создан: 32 байт

Выводим только длину случайного ключа. Сам ключ намеренно не попадает ни в страницу, ни в журнал.

<?php
declare(strict_types=1);

$key = sodium_crypto_aead_xchacha20poly1305_ietf_keygen();
$nonce = random_bytes(SODIUM_CRYPTO_AEAD_XCHACHA20POLY1305_IETF_NPUBBYTES);
$orderId = 'order:742';
$plain = 'Сумма 1250 ₽';
$cipher = sodium_crypto_aead_xchacha20poly1305_ietf_encrypt($plain, $orderId, $nonce, $key);
$restored = sodium_crypto_aead_xchacha20poly1305_ietf_decrypt($cipher, $orderId, $nonce, $key);
$wrongOrder = sodium_crypto_aead_xchacha20poly1305_ietf_decrypt($cipher, 'order:743', $nonce, $key);

echo 'восстановлено: ', $restored, "\n";
echo 'подмена ID: ', $wrongOrder === false ? 'отклонена' : 'пропущена', "\n";
echo 'служебные данные открыты: ', $orderId, "\n";

восстановлено: Сумма 1250 ₽
подмена ID: отклонена
служебные данные открыты: order:742

Это модель записи заказа: nonce и order ID можно хранить рядом с шифротекстом, ключ — отдельно. Изменение AAD обнаруживается до выдачи текста.

<?php
declare(strict_types=1);

$key = sodium_crypto_auth_keygen();
$message = 'webhook:order=742';
$mac = sodium_crypto_auth($message, $key);
echo 'MAC: ', strlen($mac), ' байт', "\n";
echo sodium_crypto_auth_verify($mac, $message, $key) ? "верно\n" : "ошибка\n";
echo sodium_crypto_auth_verify($mac, $message . '0', $key) ? "подмена пропущена\n" : "подмена отклонена\n";

MAC: 32 байт
верно
подмена отклонена

Отправитель и получатель знают один ключ. Этот пример подтверждает целостность webhook, но не скрывает его текст.

<?php
declare(strict_types=1);

$key = sodium_crypto_auth_keygen();
echo 'ключ создан: ', strlen($key), ' байт', "\n";

ключ создан: 32 байт

Выводим только длину случайного ключа. Сам ключ намеренно не попадает ни в страницу, ни в журнал.

<?php
declare(strict_types=1);

$key = sodium_crypto_auth_keygen();
$message = 'webhook:order=742';
$mac = sodium_crypto_auth($message, $key);
echo 'MAC: ', strlen($mac), ' байт', "\n";
echo sodium_crypto_auth_verify($mac, $message, $key) ? "верно\n" : "ошибка\n";
echo sodium_crypto_auth_verify($mac, $message . '0', $key) ? "подмена пропущена\n" : "подмена отклонена\n";

MAC: 32 байт
верно
подмена отклонена

Отправитель и получатель знают один ключ. Этот пример подтверждает целостность webhook, но не скрывает его текст.

<?php
declare(strict_types=1);

$alice = sodium_crypto_box_keypair();
$bob = sodium_crypto_box_keypair();
$senderPair = sodium_crypto_box_keypair_from_secretkey_and_publickey(
    sodium_crypto_box_secretkey($alice), sodium_crypto_box_publickey($bob)
);
$receiverPair = sodium_crypto_box_keypair_from_secretkey_and_publickey(
    sodium_crypto_box_secretkey($bob), sodium_crypto_box_publickey($alice)
);
$nonce = random_bytes(SODIUM_CRYPTO_BOX_NONCEBYTES);
$cipher = sodium_crypto_box('счёт №742', $nonce, $senderPair);
$plain = sodium_crypto_box_open($cipher, $nonce, $receiverPair);
echo 'Боб получил: ', $plain, "\n";
echo 'подмена: ', sodium_crypto_box_open($cipher . "x", $nonce, $receiverPair) === false ? 'отклонена' : 'пропущена', "\n";

Боб получил: счёт №742
подмена: отклонена

Пары для отправки и приёма собираются зеркально. Nonce отправляют рядом с ciphertext и не повторяют для того же направления ключей.

<?php
declare(strict_types=1);

$pair = sodium_crypto_box_keypair();
echo 'пара: ', strlen($pair), ' байт', "\n";
echo 'открытый: ', strlen(sodium_crypto_box_publickey($pair)), "\n";
echo 'секретный: ', strlen(sodium_crypto_box_secretkey($pair)), "\n";

пара: 64 байт
открытый: 32
секретный: 32

Пара — бинарная упаковка двух частей. Публичную часть можно передать, секретную оставляют владельцу.

<?php
declare(strict_types=1);

$seed = str_repeat("\x01", SODIUM_CRYPTO_BOX_SEEDBYTES);
$first = sodium_crypto_box_seed_keypair($seed);
$second = sodium_crypto_box_seed_keypair($seed);
echo hash_equals($first, $second) ? "одинаковая пара\n" : "ошибка\n";

одинаковая пара

Одинаковый seed воспроизводит пару. В приложении seed должен иметь полную энтропию и защищаться как секретный ключ.

<?php
declare(strict_types=1);

$pair = sodium_crypto_box_keypair();
$rebuilt = sodium_crypto_box_keypair_from_secretkey_and_publickey(
    sodium_crypto_box_secretkey($pair),
    sodium_crypto_box_publickey($pair)
);
echo hash_equals($pair, $rebuilt) ? "пара собрана\n" : "ошибка\n";

пара собрана

Функция нужна на границе хранения, когда две части уже прочитаны из разных безопасных мест.

<?php
declare(strict_types=1);

$alice = sodium_crypto_box_keypair();
$bob = sodium_crypto_box_keypair();
$senderPair = sodium_crypto_box_keypair_from_secretkey_and_publickey(
    sodium_crypto_box_secretkey($alice), sodium_crypto_box_publickey($bob)
);
$receiverPair = sodium_crypto_box_keypair_from_secretkey_and_publickey(
    sodium_crypto_box_secretkey($bob), sodium_crypto_box_publickey($alice)
);
$nonce = random_bytes(SODIUM_CRYPTO_BOX_NONCEBYTES);
$cipher = sodium_crypto_box('счёт №742', $nonce, $senderPair);
$plain = sodium_crypto_box_open($cipher, $nonce, $receiverPair);
echo 'Боб получил: ', $plain, "\n";
echo 'подмена: ', sodium_crypto_box_open($cipher . "x", $nonce, $receiverPair) === false ? 'отклонена' : 'пропущена', "\n";

Боб получил: счёт №742
подмена: отклонена

Пары для отправки и приёма собираются зеркально. Nonce отправляют рядом с ciphertext и не повторяют для того же направления ключей.

<?php
declare(strict_types=1);

$part = sodium_crypto_box_publickey(sodium_crypto_box_keypair());
echo 'открытый: ', strlen($part), ' байт', "\n";

открытый: 32 байт

Извлекается одна часть упаковки. Секретную часть не кодируют ради публикации.

<?php
declare(strict_types=1);

$pair = sodium_crypto_box_keypair();
$fromPair = sodium_crypto_box_publickey($pair);
$fromSecret = sodium_crypto_box_publickey_from_secretkey(sodium_crypto_box_secretkey($pair));
echo hash_equals($fromPair, $fromSecret) ? "ключ совпал\n" : "ошибка\n";

ключ совпал

Открытый ключ можно восстановить из секретного; обратное вычисление невозможно.

<?php
declare(strict_types=1);

$recipient = sodium_crypto_box_keypair();
$public = sodium_crypto_box_publickey($recipient);
$cipher = sodium_crypto_box_seal('результат анализа', $public);
$plain = sodium_crypto_box_seal_open($cipher, $recipient);
echo 'получатель прочитал: ', $plain, "\n";
echo 'накладные байты: ', strlen($cipher) - strlen('результат анализа'), "\n";

получатель прочитал: результат анализа
накладные байты: 48

Отправителю нужен только открытый ключ получателя. Sealed box не сообщает получателю, кто отправитель.

<?php
declare(strict_types=1);

$recipient = sodium_crypto_box_keypair();
$public = sodium_crypto_box_publickey($recipient);
$cipher = sodium_crypto_box_seal('результат анализа', $public);
$plain = sodium_crypto_box_seal_open($cipher, $recipient);
echo 'получатель прочитал: ', $plain, "\n";
echo 'накладные байты: ', strlen($cipher) - strlen('результат анализа'), "\n";

получатель прочитал: результат анализа
накладные байты: 48

Отправителю нужен только открытый ключ получателя. Sealed box не сообщает получателю, кто отправитель.

<?php
declare(strict_types=1);

$part = sodium_crypto_box_secretkey(sodium_crypto_box_keypair());
echo 'секретный: ', strlen($part), ' байт', "\n";

секретный: 32 байт

Извлекается одна часть упаковки. Секретную часть не кодируют ради публикации.

<?php
declare(strict_types=1);

$p = sodium_crypto_core_ristretto255_random();
$q = sodium_crypto_core_ristretto255_random();
$sum = sodium_crypto_core_ristretto255_add($p, $q);
$restored = sodium_crypto_core_ristretto255_sub($sum, $q);
echo hash_equals($p, $restored) ? "точка восстановлена\n" : "ошибка\n";

точка восстановлена

Сложение и обратное вычитание показывают алгебраическое свойство. Это не схема шифрования.

<?php
declare(strict_types=1);

$wide = str_repeat("\x42", SODIUM_CRYPTO_CORE_RISTRETTO255_HASHBYTES);
$point = sodium_crypto_core_ristretto255_from_hash($wide);
echo sodium_crypto_core_ristretto255_is_valid_point($point) ? "допустимая точка\n" : "ошибка\n";

допустимая точка

Операция отображает ровно 64 равномерных байта в точку; произвольный пользовательский пароль таким входом не является.

<?php
declare(strict_types=1);

$point = sodium_crypto_core_ristretto255_random();
var_dump(sodium_crypto_core_ristretto255_is_valid_point($point));
var_dump(sodium_crypto_core_ristretto255_is_valid_point(str_repeat("\xff", strlen($point))));

bool(true)
bool(false)

Проверка должна предшествовать низкоуровневой операции над внешней точкой.

<?php
declare(strict_types=1);

$point = sodium_crypto_core_ristretto255_random();
echo 'точка: ', strlen($point), ' байт; допустима: ', sodium_crypto_core_ristretto255_is_valid_point($point) ? 'да' : 'нет', "\n";

точка: 32 байт; допустима: да

Случайный результат уже является корректной кодировкой точки. Это не ключ прикладного шифрования.

<?php
declare(strict_types=1);

$x = sodium_crypto_core_ristretto255_scalar_random();
$y = sodium_crypto_core_ristretto255_scalar_random();
$sum = sodium_crypto_core_ristretto255_scalar_add($x, $y);
$restored = sodium_crypto_core_ristretto255_scalar_sub($sum, $y);
echo hash_equals($x, $restored) ? "скаляр восстановлен\n" : "ошибка\n";

скаляр восстановлен

Пример показывает пару обратных операций, а не прикладной алгоритм.

<?php
declare(strict_types=1);

$scalar = sodium_crypto_core_ristretto255_scalar_random();
$twice = sodium_crypto_core_ristretto255_scalar_complement(
    sodium_crypto_core_ristretto255_scalar_complement($scalar)
);
echo hash_equals($scalar, $twice) ? "двойное дополнение вернуло скаляр\n" : "ошибка\n";

двойное дополнение вернуло скаляр

Свойство делает результат наблюдаемым, не выдавая случайный скаляр.

<?php
declare(strict_types=1);

$scalar = sodium_crypto_core_ristretto255_scalar_random();
$twice = sodium_crypto_core_ristretto255_scalar_invert(
    sodium_crypto_core_ristretto255_scalar_invert($scalar)
);
echo hash_equals($scalar, $twice) ? "двойное обращение вернуло скаляр\n" : "ошибка\n";

двойное обращение вернуло скаляр

Обращение нулевого скаляра недопустимо; random даёт подходящий ненулевой вход.

<?php
declare(strict_types=1);

$x = sodium_crypto_core_ristretto255_scalar_random();
$one = str_repeat("\0", SODIUM_CRYPTO_CORE_RISTRETTO255_SCALARBYTES);
$one[0] = "\x01";
$product = sodium_crypto_core_ristretto255_scalar_mul($x, $one);
echo hash_equals($x, $product) ? "умножение на единицу сохранило скаляр\n" : "ошибка\n";

умножение на единицу сохранило скаляр

Байты one заданы в little-endian форме поля; это низкоуровневый тест свойства.

<?php
declare(strict_types=1);

$x = sodium_crypto_core_ristretto255_scalar_random();
$zero = sodium_crypto_core_ristretto255_scalar_add($x, sodium_crypto_core_ristretto255_scalar_negate($x));
echo hash_equals($zero, str_repeat("\0", strlen($zero))) ? "x + (-x) = 0\n" : "ошибка\n";

x + (-x) = 0

Отрицание здесь относится к полю скаляров, не к целому числу PHP.

<?php
declare(strict_types=1);

$scalar = sodium_crypto_core_ristretto255_scalar_random();
echo 'скаляр: ', strlen($scalar), ' байт', "\n";

скаляр: 32 байт

Функция возвращает допустимый ненулевой скаляр для протокола Ristretto255.

<?php
declare(strict_types=1);

$wide = str_repeat("\x7f", SODIUM_CRYPTO_CORE_RISTRETTO255_NONREDUCEDSCALARBYTES);
$scalar = sodium_crypto_core_ristretto255_scalar_reduce($wide);
echo 'сокращено: ', strlen($wide), ' → ', strlen($scalar), ' байт', "\n";

сокращено: 64 → 32 байт

Reduce интерпретирует широкий равномерный вход и приводит его по модулю порядка группы.

<?php
declare(strict_types=1);

$x = sodium_crypto_core_ristretto255_scalar_random();
$y = sodium_crypto_core_ristretto255_scalar_random();
$sum = sodium_crypto_core_ristretto255_scalar_add($x, $y);
$restored = sodium_crypto_core_ristretto255_scalar_sub($sum, $y);
echo hash_equals($x, $restored) ? "скаляр восстановлен\n" : "ошибка\n";

скаляр восстановлен

Пример показывает пару обратных операций, а не прикладной алгоритм.

<?php
declare(strict_types=1);

$p = sodium_crypto_core_ristretto255_random();
$q = sodium_crypto_core_ristretto255_random();
$sum = sodium_crypto_core_ristretto255_add($p, $q);
$restored = sodium_crypto_core_ristretto255_sub($sum, $q);
echo hash_equals($p, $restored) ? "точка восстановлена\n" : "ошибка\n";

точка восстановлена

Сложение и обратное вычитание показывают алгебраическое свойство. Это не схема шифрования.

<?php
declare(strict_types=1);

$pair = sodium_crypto_kx_keypair();
echo 'пара KX: ', strlen($pair), ' байт', "\n";

пара KX: 64 байт

Пара предназначена для KX; формат другой криптосистемы нельзя подставлять только из-за одинаковой длины.

<?php
declare(strict_types=1);

$part = sodium_crypto_kx_publickey(sodium_crypto_kx_keypair());
echo 'открытый: ', strlen($part), ' байт', "\n";

открытый: 32 байт

Часть извлекают для обмена или защищённого хранения; пара остаётся типизированной назначением протокола.

<?php
declare(strict_types=1);

$part = sodium_crypto_kx_secretkey(sodium_crypto_kx_keypair());
echo 'секретный: ', strlen($part), ' байт', "\n";

секретный: 32 байт

Часть извлекают для обмена или защищённого хранения; пара остаётся типизированной назначением протокола.

<?php
declare(strict_types=1);

$seed = str_repeat("\x02", SODIUM_CRYPTO_KX_SEEDBYTES);
$a = sodium_crypto_kx_seed_keypair($seed);
$b = sodium_crypto_kx_seed_keypair($seed);
echo hash_equals($a, $b) ? "пара воспроизводится\n" : "ошибка\n";

пара воспроизводится

Детерминированность полезна для восстановления из защищённого seed; короткая фраза seed не заменяет.

<?php
declare(strict_types=1);

$client = sodium_crypto_kx_keypair();
$server = sodium_crypto_kx_keypair();
[$clientRx, $clientTx] = sodium_crypto_kx_client_session_keys(
    $client, sodium_crypto_kx_publickey($server)
);
[$serverRx, $serverTx] = sodium_crypto_kx_server_session_keys(
    $server, sodium_crypto_kx_publickey($client)
);
echo hash_equals($clientTx, $serverRx) ? "client TX = server RX\n" : "ошибка\n";
echo hash_equals($serverTx, $clientRx) ? "server TX = client RX\n" : "ошибка\n";
echo hash_equals($clientTx, $clientRx) ? "направления совпали\n" : "направления разделены\n";

client TX = server RX
server TX = client RX
направления разделены

KX сразу разделяет ключи направлений. Их затем передают AEAD/secretstream, а не используют как выводимый токен.

<?php
declare(strict_types=1);

$client = sodium_crypto_kx_keypair();
$server = sodium_crypto_kx_keypair();
[$clientRx, $clientTx] = sodium_crypto_kx_client_session_keys(
    $client, sodium_crypto_kx_publickey($server)
);
[$serverRx, $serverTx] = sodium_crypto_kx_server_session_keys(
    $server, sodium_crypto_kx_publickey($client)
);
echo hash_equals($clientTx, $serverRx) ? "client TX = server RX\n" : "ошибка\n";
echo hash_equals($serverTx, $clientRx) ? "server TX = client RX\n" : "ошибка\n";
echo hash_equals($clientTx, $clientRx) ? "направления совпали\n" : "направления разделены\n";

client TX = server RX
server TX = client RX
направления разделены

KX сразу разделяет ключи направлений. Их затем передают AEAD/secretstream, а не используют как выводимый токен.

<?php
declare(strict_types=1);

$digest = sodium_crypto_generichash('invoice=742');
echo sodium_bin2hex($digest), "\n";
echo 'байт: ', strlen($digest), "\n";

6ae8454ac0f3a7a58cec11b911cd0921d2c753dba5a1c28fb3a8e97afd34e047
байт: 32

Один и тот же набор байтов даёт один digest. Он помогает сверять данные, но без ключа не доказывает отправителя.

<?php
declare(strict_types=1);

$key = sodium_crypto_generichash_keygen();
echo 'ключ создан: ', strlen($key), ' байт', "\n";

ключ создан: 32 байт

Выводим только длину случайного ключа. Сам ключ намеренно не попадает ни в страницу, ни в журнал.

<?php
declare(strict_types=1);

$state = sodium_crypto_generichash_init('', 32);
$updated = sodium_crypto_generichash_update($state, 'invoice=');
sodium_crypto_generichash_update($state, '742');
$chunked = sodium_crypto_generichash_final($state, 32);
$oneShot = sodium_crypto_generichash('invoice=742', '', 32);
echo $updated ? "состояние обновлено\n" : "ошибка\n";
echo hash_equals($oneShot, $chunked) ? "части = целое\n" : "не совпало\n";

состояние обновлено
части = целое

Потоковая форма нужна для файла или HTTP-тела, которое нельзя разумно держать целиком в памяти.

<?php
declare(strict_types=1);

$state = sodium_crypto_generichash_init('', 32);
$updated = sodium_crypto_generichash_update($state, 'invoice=');
sodium_crypto_generichash_update($state, '742');
$chunked = sodium_crypto_generichash_final($state, 32);
$oneShot = sodium_crypto_generichash('invoice=742', '', 32);
echo $updated ? "состояние обновлено\n" : "ошибка\n";
echo hash_equals($oneShot, $chunked) ? "части = целое\n" : "не совпало\n";

состояние обновлено
части = целое

Потоковая форма нужна для файла или HTTP-тела, которое нельзя разумно держать целиком в памяти.

<?php
declare(strict_types=1);

$state = sodium_crypto_generichash_init('', 32);
$updated = sodium_crypto_generichash_update($state, 'invoice=');
sodium_crypto_generichash_update($state, '742');
$chunked = sodium_crypto_generichash_final($state, 32);
$oneShot = sodium_crypto_generichash('invoice=742', '', 32);
echo $updated ? "состояние обновлено\n" : "ошибка\n";
echo hash_equals($oneShot, $chunked) ? "части = целое\n" : "не совпало\n";

состояние обновлено
части = целое

Потоковая форма нужна для файла или HTTP-тела, которое нельзя разумно держать целиком в памяти.

<?php
declare(strict_types=1);

$master = sodium_crypto_kdf_keygen();
$orders = sodium_crypto_kdf_derive_from_key(32, 1, 'ORDERS01', $master);
$uploads = sodium_crypto_kdf_derive_from_key(32, 1, 'UPLOAD01', $master);
$ordersV2 = sodium_crypto_kdf_derive_from_key(32, 2, 'ORDERS01', $master);
echo 'длина: ', strlen($orders), "\n";
echo hash_equals($orders, $uploads) ? "контексты совпали\n" : "контексты разделены\n";
echo hash_equals($orders, $ordersV2) ? "ID совпали\n" : "ID разделены\n";

длина: 32
контексты разделены
ID разделены

Один master key обслуживает несколько подсистем без хранения десятков независимых корневых ключей.

<?php
declare(strict_types=1);

$key = sodium_crypto_kdf_keygen();
echo 'ключ создан: ', strlen($key), ' байт', "\n";

ключ создан: 32 байт

Выводим только длину случайного ключа. Сам ключ намеренно не попадает ни в страницу, ни в журнал.

<?php
declare(strict_types=1);

$salt = str_repeat("\x03", SODIUM_CRYPTO_PWHASH_SALTBYTES);
$key = sodium_crypto_pwhash(32, 'correct horse', $salt, SODIUM_CRYPTO_PWHASH_OPSLIMIT_INTERACTIVE, SODIUM_CRYPTO_PWHASH_MEMLIMIT_INTERACTIVE, SODIUM_CRYPTO_PWHASH_ALG_ARGON2ID13);
echo 'производный ключ: ', strlen($key), ' байт', "\n";
$other = sodium_crypto_pwhash(32, 'correct horse', str_repeat("\x04", SODIUM_CRYPTO_PWHASH_SALTBYTES), SODIUM_CRYPTO_PWHASH_OPSLIMIT_INTERACTIVE, SODIUM_CRYPTO_PWHASH_MEMLIMIT_INTERACTIVE, SODIUM_CRYPTO_PWHASH_ALG_ARGON2ID13);
echo hash_equals($key, $other) ? "соли не повлияли\n" : "другая соль → другой ключ\n";

производный ключ: 32 байт
другая соль → другой ключ

Низкоуровневый результат — бинарный ключ. Чтобы повторить его, надо хранить соль, алгоритм и оба лимита отдельно.

<?php
declare(strict_types=1);

$hash = sodium_crypto_pwhash_str('correct horse', SODIUM_CRYPTO_PWHASH_OPSLIMIT_INTERACTIVE, SODIUM_CRYPTO_PWHASH_MEMLIMIT_INTERACTIVE);
echo 'строка хранит параметры: ', str_starts_with($hash, '$') ? 'да' : 'нет', "\n";
echo 'проверка: ', sodium_crypto_pwhash_str_verify($hash, 'correct horse') ? 'успешна' : 'ошибка', "\n";

строка хранит параметры: да
проверка: успешна

Строка предназначена для хранения в одном поле: соль и параметры уже включены. Сам пароль не сохраняется.

<?php
declare(strict_types=1);

$hash = sodium_crypto_pwhash_str('correct horse', SODIUM_CRYPTO_PWHASH_OPSLIMIT_INTERACTIVE, SODIUM_CRYPTO_PWHASH_MEMLIMIT_INTERACTIVE);
var_dump(sodium_crypto_pwhash_str_verify($hash, 'correct horse'));
var_dump(sodium_crypto_pwhash_str_verify($hash, 'wrong horse'));

bool(true)
bool(false)

В базе хранится строка hash с параметрами, а при входе проверяется введённый пароль. Сравнивать строки вручную не нужно.

<?php
declare(strict_types=1);

$hash = sodium_crypto_pwhash_str(
    'correct horse',
    SODIUM_CRYPTO_PWHASH_OPSLIMIT_INTERACTIVE,
    SODIUM_CRYPTO_PWHASH_MEMLIMIT_INTERACTIVE
);
var_dump(sodium_crypto_pwhash_str_needs_rehash(
    $hash,
    SODIUM_CRYPTO_PWHASH_OPSLIMIT_INTERACTIVE,
    SODIUM_CRYPTO_PWHASH_MEMLIMIT_INTERACTIVE
));
var_dump(sodium_crypto_pwhash_str_needs_rehash(
    $hash,
    SODIUM_CRYPTO_PWHASH_OPSLIMIT_MODERATE,
    SODIUM_CRYPTO_PWHASH_MEMLIMIT_INTERACTIVE
));

bool(false)
bool(true)

После успешного входа true означает: создать новый hash с актуальными лимитами и заменить старый.

<?php
declare(strict_types=1);

$salt = str_repeat("\x03", SODIUM_CRYPTO_PWHASH_SCRYPTSALSA208SHA256_SALTBYTES);
$key = sodium_crypto_pwhash_scryptsalsa208sha256(32, 'correct horse', $salt, SODIUM_CRYPTO_PWHASH_SCRYPTSALSA208SHA256_OPSLIMIT_INTERACTIVE, SODIUM_CRYPTO_PWHASH_SCRYPTSALSA208SHA256_MEMLIMIT_INTERACTIVE);
echo 'производный ключ: ', strlen($key), ' байт', "\n";
$other = sodium_crypto_pwhash_scryptsalsa208sha256(32, 'correct horse', str_repeat("\x04", SODIUM_CRYPTO_PWHASH_SCRYPTSALSA208SHA256_SALTBYTES), SODIUM_CRYPTO_PWHASH_SCRYPTSALSA208SHA256_OPSLIMIT_INTERACTIVE, SODIUM_CRYPTO_PWHASH_SCRYPTSALSA208SHA256_MEMLIMIT_INTERACTIVE);
echo hash_equals($key, $other) ? "соли не повлияли\n" : "другая соль → другой ключ\n";

производный ключ: 32 байт
другая соль → другой ключ

Низкоуровневый результат — бинарный ключ. Чтобы повторить его, надо хранить соль, алгоритм и оба лимита отдельно.

<?php
declare(strict_types=1);

$hash = sodium_crypto_pwhash_scryptsalsa208sha256_str('correct horse', SODIUM_CRYPTO_PWHASH_SCRYPTSALSA208SHA256_OPSLIMIT_INTERACTIVE, SODIUM_CRYPTO_PWHASH_SCRYPTSALSA208SHA256_MEMLIMIT_INTERACTIVE);
echo 'строка хранит параметры: ', str_starts_with($hash, '$') ? 'да' : 'нет', "\n";
echo 'проверка: ', sodium_crypto_pwhash_scryptsalsa208sha256_str_verify($hash, 'correct horse') ? 'успешна' : 'ошибка', "\n";

строка хранит параметры: да
проверка: успешна

Строка предназначена для хранения в одном поле: соль и параметры уже включены. Сам пароль не сохраняется.

<?php
declare(strict_types=1);

$hash = sodium_crypto_pwhash_scryptsalsa208sha256_str('correct horse', SODIUM_CRYPTO_PWHASH_SCRYPTSALSA208SHA256_OPSLIMIT_INTERACTIVE, SODIUM_CRYPTO_PWHASH_SCRYPTSALSA208SHA256_MEMLIMIT_INTERACTIVE);
var_dump(sodium_crypto_pwhash_scryptsalsa208sha256_str_verify($hash, 'correct horse'));
var_dump(sodium_crypto_pwhash_scryptsalsa208sha256_str_verify($hash, 'wrong horse'));

bool(true)
bool(false)

В базе хранится строка hash с параметрами, а при входе проверяется введённый пароль. Сравнивать строки вручную не нужно.

<?php
declare(strict_types=1);

$aliceSecret = random_bytes(SODIUM_CRYPTO_SCALARMULT_SCALARBYTES);
$bobSecret = random_bytes(SODIUM_CRYPTO_SCALARMULT_SCALARBYTES);
$alicePublic = sodium_crypto_scalarmult_base($aliceSecret);
$bobPublic = sodium_crypto_scalarmult_base($bobSecret);
$aliceShared = sodium_crypto_scalarmult($aliceSecret, $bobPublic);
$bobShared = sodium_crypto_scalarmult($bobSecret, $alicePublic);
echo hash_equals($aliceShared, $bobShared) ? "общая тайна совпала\n" : "ошибка\n";

общая тайна совпала

Совпадение демонстрирует X25519. Реальный протокол ещё должен подтвердить стороны и вывести ключи нужных назначений.

<?php
declare(strict_types=1);

$a = sodium_crypto_core_ristretto255_scalar_random();
$b = sodium_crypto_core_ristretto255_scalar_random();
$aPublic = sodium_crypto_scalarmult_ristretto255_base($a);
$bPublic = sodium_crypto_scalarmult_ristretto255_base($b);
$ab = sodium_crypto_scalarmult_ristretto255($a, $bPublic);
$ba = sodium_crypto_scalarmult_ristretto255($b, $aPublic);
echo hash_equals($ab, $ba) ? "результаты совпали\n" : "ошибка\n";

результаты совпали

Свойство показано на допустимых случайных скалярах и точках; схему аутентификации оно само не задаёт.

<?php
declare(strict_types=1);

$scalar = sodium_crypto_core_ristretto255_scalar_random();
$point = sodium_crypto_scalarmult_ristretto255_base($scalar);
echo sodium_crypto_core_ristretto255_is_valid_point($point) ? "получена допустимая точка\n" : "ошибка\n";

получена допустимая точка

Base умножает стандартную базовую точку; результат остаётся строительным блоком протокола.

<?php
declare(strict_types=1);

$key = sodium_crypto_secretbox_keygen();
$nonce = random_bytes(SODIUM_CRYPTO_SECRETBOX_NONCEBYTES);
$cipher = sodium_crypto_secretbox('api-token-demo', $nonce, $key);
$stored = sodium_bin2base64($nonce . $cipher, SODIUM_BASE64_VARIANT_URLSAFE_NO_PADDING);
$raw = sodium_base642bin($stored, SODIUM_BASE64_VARIANT_URLSAFE_NO_PADDING);
$restored = sodium_crypto_secretbox_open(
    substr($raw, SODIUM_CRYPTO_SECRETBOX_NONCEBYTES),
    substr($raw, 0, SODIUM_CRYPTO_SECRETBOX_NONCEBYTES),
    $key
);
echo 'из хранилища: ', $restored, "\n";
$raw[strlen($raw) - 1] = chr(ord($raw[strlen($raw) - 1]) ^ 1);
echo sodium_crypto_secretbox_open(substr($raw, SODIUM_CRYPTO_SECRETBOX_NONCEBYTES), substr($raw, 0, SODIUM_CRYPTO_SECRETBOX_NONCEBYTES), $key) === false
    ? "подмена отклонена\n" : "подмена пропущена\n";

из хранилища: api-token-demo
подмена отклонена

Практическая упаковка хранит nonce и ciphertext в Base64; ключ остаётся в секретном хранилище и не входит в запись.

<?php
declare(strict_types=1);

$key = sodium_crypto_secretbox_keygen();
echo 'ключ создан: ', strlen($key), ' байт', "\n";

ключ создан: 32 байт

Выводим только длину случайного ключа. Сам ключ намеренно не попадает ни в страницу, ни в журнал.

<?php
declare(strict_types=1);

$key = sodium_crypto_secretbox_keygen();
$nonce = random_bytes(SODIUM_CRYPTO_SECRETBOX_NONCEBYTES);
$cipher = sodium_crypto_secretbox('api-token-demo', $nonce, $key);
$stored = sodium_bin2base64($nonce . $cipher, SODIUM_BASE64_VARIANT_URLSAFE_NO_PADDING);
$raw = sodium_base642bin($stored, SODIUM_BASE64_VARIANT_URLSAFE_NO_PADDING);
$restored = sodium_crypto_secretbox_open(
    substr($raw, SODIUM_CRYPTO_SECRETBOX_NONCEBYTES),
    substr($raw, 0, SODIUM_CRYPTO_SECRETBOX_NONCEBYTES),
    $key
);
echo 'из хранилища: ', $restored, "\n";
$raw[strlen($raw) - 1] = chr(ord($raw[strlen($raw) - 1]) ^ 1);
echo sodium_crypto_secretbox_open(substr($raw, SODIUM_CRYPTO_SECRETBOX_NONCEBYTES), substr($raw, 0, SODIUM_CRYPTO_SECRETBOX_NONCEBYTES), $key) === false
    ? "подмена отклонена\n" : "подмена пропущена\n";

из хранилища: api-token-demo
подмена отклонена

Практическая упаковка хранит nonce и ciphertext в Base64; ключ остаётся в секретном хранилище и не входит в запись.

<?php
declare(strict_types=1);

$key = sodium_crypto_secretstream_xchacha20poly1305_keygen();
echo 'ключ создан: ', strlen($key), ' байт', "\n";

ключ создан: 32 байт

Выводим только длину случайного ключа. Сам ключ намеренно не попадает ни в страницу, ни в журнал.

<?php
declare(strict_types=1);

$key = sodium_crypto_secretstream_xchacha20poly1305_keygen();
[$state, $header] = sodium_crypto_secretstream_xchacha20poly1305_init_push($key);
echo 'заголовок: ', strlen($header), ' байт', "\n";
echo 'состояние создано: ', $state !== '' ? 'да' : 'нет', "\n";

заголовок: 24 байт
состояние создано: да

Header передают получателю перед первым блоком. State не сериализуют как долговременный ключ.

<?php
declare(strict_types=1);

$key = sodium_crypto_secretstream_xchacha20poly1305_keygen();
[$push, $header] = sodium_crypto_secretstream_xchacha20poly1305_init_push($key);
$chunks = [
    sodium_crypto_secretstream_xchacha20poly1305_push($push, 'строка 1', '', SODIUM_CRYPTO_SECRETSTREAM_XCHACHA20POLY1305_TAG_MESSAGE),
    sodium_crypto_secretstream_xchacha20poly1305_push($push, 'строка 2', '', SODIUM_CRYPTO_SECRETSTREAM_XCHACHA20POLY1305_TAG_FINAL),
];
$pull = sodium_crypto_secretstream_xchacha20poly1305_init_pull($header, $key);
foreach ($chunks as $cipher) {
    $result = sodium_crypto_secretstream_xchacha20poly1305_pull($pull, $cipher);
    if ($result === false) { throw new RuntimeException('Повреждённый блок'); }
    [$plain, $tag] = $result;
    echo $plain, ' | ', $tag === SODIUM_CRYPTO_SECRETSTREAM_XCHACHA20POLY1305_TAG_FINAL ? 'FINAL' : 'MESSAGE', "\n";
}

строка 1 | MESSAGE
строка 2 | FINAL

Получатель проверяет каждый блок и видит финальную границу. Архив без FINAL следует считать оборванным.

<?php
declare(strict_types=1);

$key = sodium_crypto_secretstream_xchacha20poly1305_keygen();
[$push, $header] = sodium_crypto_secretstream_xchacha20poly1305_init_push($key);
$pull = sodium_crypto_secretstream_xchacha20poly1305_init_pull($header, $key);
echo 'приём готов: ', $pull !== '' ? 'да' : 'нет', "\n";

приём готов: да

Получатель использует тот же secret key и публичный header, чтобы создать независимое состояние чтения.

<?php
declare(strict_types=1);

$key = sodium_crypto_secretstream_xchacha20poly1305_keygen();
[$push, $header] = sodium_crypto_secretstream_xchacha20poly1305_init_push($key);
$chunks = [
    sodium_crypto_secretstream_xchacha20poly1305_push($push, 'строка 1', '', SODIUM_CRYPTO_SECRETSTREAM_XCHACHA20POLY1305_TAG_MESSAGE),
    sodium_crypto_secretstream_xchacha20poly1305_push($push, 'строка 2', '', SODIUM_CRYPTO_SECRETSTREAM_XCHACHA20POLY1305_TAG_FINAL),
];
$pull = sodium_crypto_secretstream_xchacha20poly1305_init_pull($header, $key);
foreach ($chunks as $cipher) {
    $result = sodium_crypto_secretstream_xchacha20poly1305_pull($pull, $cipher);
    if ($result === false) { throw new RuntimeException('Повреждённый блок'); }
    [$plain, $tag] = $result;
    echo $plain, ' | ', $tag === SODIUM_CRYPTO_SECRETSTREAM_XCHACHA20POLY1305_TAG_FINAL ? 'FINAL' : 'MESSAGE', "\n";
}

строка 1 | MESSAGE
строка 2 | FINAL

Получатель проверяет каждый блок и видит финальную границу. Архив без FINAL следует считать оборванным.

<?php
declare(strict_types=1);

$key = sodium_crypto_secretstream_xchacha20poly1305_keygen();
[$push, $header] = sodium_crypto_secretstream_xchacha20poly1305_init_push($key);
$pull = sodium_crypto_secretstream_xchacha20poly1305_init_pull($header, $key);
sodium_crypto_secretstream_xchacha20poly1305_rekey($push);
sodium_crypto_secretstream_xchacha20poly1305_rekey($pull);
$cipher = sodium_crypto_secretstream_xchacha20poly1305_push($push, 'после смены');
[$plain] = sodium_crypto_secretstream_xchacha20poly1305_pull($pull, $cipher);
echo $plain, "\n";

после смены

Обе стороны меняют состояние в одной логической позиции. Односторонний rekey рассинхронизирует поток.

<?php
declare(strict_types=1);

$key = sodium_crypto_shorthash_keygen();
$bucket = sodium_crypto_shorthash('attacker-controlled-key', $key);
echo 'короткий хеш: ', strlen($bucket), ' байт', "\n";

короткий хеш: 8 байт

Случайный ключ делает сам hex непредсказуемым, поэтому в проверяемой версии вывод заменяется стабильным фактом длины; значение не сохраняют как подпись.

<?php
declare(strict_types=1);

$key = sodium_crypto_shorthash_keygen();
echo 'ключ создан: ', strlen($key), ' байт', "\n";

ключ создан: 16 байт

Выводим только длину случайного ключа. Сам ключ намеренно не попадает ни в страницу, ни в журнал.

<?php
declare(strict_types=1);

$pair = sodium_crypto_sign_keypair();
$signed = sodium_crypto_sign('release-1.4.zip', sodium_crypto_sign_secretkey($pair));
$plain = sodium_crypto_sign_open($signed, sodium_crypto_sign_publickey($pair));
echo 'проверено: ', $plain, "\n";
$signed[0] = chr(ord($signed[0]) ^ 1);
echo sodium_crypto_sign_open($signed, sodium_crypto_sign_publickey($pair)) === false ? "подмена отклонена\n" : "подмена пропущена\n";

проверено: release-1.4.zip
подмена отклонена

Attached-форма возвращает подпись вместе с сообщением; open выдаёт сообщение только после проверки.

<?php
declare(strict_types=1);

$pair = sodium_crypto_sign_keypair();
$secret = sodium_crypto_sign_secretkey($pair);
$public = sodium_crypto_sign_publickey($pair);
$manifest = 'release=1.4;sha256=demo';
$signature = sodium_crypto_sign_detached($manifest, $secret);
echo sodium_crypto_sign_verify_detached($signature, $manifest, $public) ? "подпись верна\n" : "ошибка\n";
echo sodium_crypto_sign_verify_detached($signature, $manifest . 'x', $public) ? "подмена пропущена\n" : "подмена отклонена\n";

подпись верна
подмена отклонена

Detached-подпись удобно хранить рядом с manifest. Открытый ключ должен быть заранее доверенным.

<?php
declare(strict_types=1);

$pair = sodium_crypto_sign_keypair();
$converted = sodium_crypto_sign_ed25519_pk_to_curve25519(sodium_crypto_sign_publickey($pair));
echo 'публичный Curve25519: ', strlen($converted), ' байт', "\n";

публичный Curve25519: 32 байт

Преобразование нужно только протоколу, который явно связывает ключи Ed25519 и Curve25519; одинаковая личность ключа требует отдельной модели доверия.

<?php
declare(strict_types=1);

$pair = sodium_crypto_sign_keypair();
$converted = sodium_crypto_sign_ed25519_sk_to_curve25519(sodium_crypto_sign_secretkey($pair));
echo 'секретный Curve25519: ', strlen($converted), ' байт', "\n";