sodium_compat Скачать - sodium_compat Загрузка исходного кода

sodium_compat

Другие категории

Version 2.1.0

Скачать

Натрий Совместим

Sodium Compat — это чистый PHP-полифил для криптографической библиотеки Sodium (libsodium), основного расширения PHP 7.2.0+, доступного в других случаях в PECL.

Если у вас установлено расширение PHP, Sodium Compat будет гибко и прозрачно использовать расширение PHP вместо нашей реализации.

Основные версии и ветки

odium_compat v1.21.0 был последним выпуском v1.x из основной ветки. С этого момента все будущие выпуски, поддерживающие PHP 5.2–8.0 и 32-битные целые числа, будут находиться в ветке v1.x

Более новые версии натрия_компата (т. е. v2.0.0) будут продолжать находиться в основной ветке, если только не потребуется новая основная версия. Целью этой работы является улучшение читаемости и производительности кода при одновременном сокращении количества шаблонного кода.

В случае сомнений обратитесь к файлу README в основной ветке для получения последней информации о версии.

Какую версию мне следует использовать?

версия натрия_compat	Поддерживаемые версии PHP	Поддержка 32-бит?	Ветвь
`v1.xy`	5.2.4 – ПОСЛЕДНИЕ	ДА	v1.x
`v2.xy`	8.1 – ПОСЛЕДНИЕ	НЕТ	владелец

Если вам нужна поддержка 32-битного PHP ( PHP_INT_SIZE == 4 ), продолжайте использоватьodium_compat v1.x. Если вы хотите повысить производительность и уменьшить зависимости, используйте v2.x.

Мы рекомендуем библиотекам и платформам установить ограничение версии Composer следующим образом:

 {
    "require" : {
        /* ... */
        "paragonie/sodium_compat" : ">= 1"
        /* ... */
    }
}

Приложения, наоборот, должны указывать фактическую версию, которая важна для них и их развертываний.

ВАЖНЫЙ!

Эта криптографическая библиотека не прошла официальный аудит независимой третьей стороны, специализирующейся на криптографии или криптоанализе.

Если вам требуется такой аудит, прежде чем вы сможете использовать натрия_compat в своих проектах и иметь средства для такого аудита, пожалуйста, откройте проблему или свяжитесь со security at paragonie dot com чтобы мы могли помочь сдвинуть дело с мертвой точки.

Тем не менее, натрий_компат был принят известными проектами с открытым исходным кодом, такими как Joomla! и Мадженто. Кроме того, натрий_компат был разработан Paragon Initiative Enterprises, компанией, которая специализируется на безопасной разработке PHP и криптографии PHP, и был неофициально проверен многими другими экспертами по безопасности, которые также специализируются на PHP.

Если вы хотите узнать больше о мерах защитной безопасности, которые мы приняли, чтобы предотвратить превращение натрия_компата в источник уязвимостей в ваших системах, прочтите «Криптографически безопасная разработка PHP» .

Установка Sodium Compat

Если вы используете Composer:

composer require paragonie/sodium_compat

Установить из источника

Если вы не используете Composer, загрузите архив-архив версии (который должен быть подписан нашим открытым ключом GnuPG), извлеките его содержимое, а затем включите наш скрипт autoload.php в свой проект.

 <?php
require_once " /path/to/sodium_compat/autoload.php " ;

Релизы PHP-архивов (Phar)

Начиная с версии 1.3.0, выпуски натрия_компата включают архив PHP (файл .phar) и связанную с ним подпись GPG. Сначала загрузите оба файла и проверьте их с помощью нашего открытого ключа GPG, например:

 # Getting our public key from the keyserver:
gpg --fingerprint 7F52D5C61D1255C731362E826B97A1C2826404DA
if [ $? -ne 0 ] ; then
    echo -e " 33[33mDownloading PGP Public Key...33[0m "
    gpg  --keyserver pgp.mit.edu --recv-keys 7F52D5C61D1255C731362E826B97A1C2826404DA
    # Security <[email protected]>
    gpg --fingerprint 7F52D5C61D1255C731362E826B97A1C2826404DA
    if [ $? -ne 0 ] ; then
        echo -e " 33[31mCould not download PGP public key for verification33[0m "
        exit 1
    fi
fi

# Verifying the PHP Archive
gpg --verify sodium-compat.phar.sig sodium-compat.phar

Теперь просто включите этот файл .phar в свое приложение.

 <?php
require_once " /path/to/sodium-compat.phar " ;

Поддерживать

Коммерческая поддержка libsodium доступна от нескольких поставщиков. Если вам нужна помощь в использовании натрия_compat в одном из ваших проектов, свяжитесь с Paragon Initiative Enterprises.

Некоммерческий отчет будет создаваться через выпуски Github. Мы не даем никаких гарантий своей готовности бесплатно решить вопросы по интеграции натрия_компата в стороннее программное обеспечение, но постараемся исправить любые ошибки (связанные с безопасностью или иные) в нашей библиотеке.

Контракты на поддержку

Если ваша компания использует эту библиотеку в своих продуктах или услугах, вы можете быть заинтересованы в приобретении контракта на поддержку у Paragon Initiative Enterprises.

Использование совместимости натрия

Настоящий полифилл

Согласно второму голосованию по libsodium RFC, PHP 7.2 использует sodium_* вместо Sodium* .

 <?php
require_once " /path/to/sodium_compat/autoload.php " ;

$ alice_kp = sodium_crypto_sign_keypair ();
$ alice_sk = sodium_crypto_sign_secretkey ( $ alice_kp );
$ alice_pk = sodium_crypto_sign_publickey ( $ alice_kp );

$ message = ' This is a test message. ' ;
$ signature = sodium_crypto_sign_detached ( $ message , $ alice_sk );
if ( sodium_crypto_sign_verify_detached ( $ signature , $ message , $ alice_pk )) {
    echo ' OK ' , PHP_EOL ;
} else {
    throw new Exception ( ' Invalid signature ' );
}

Полифил общего назначения

Если ваши пользователи используют PHP < 5.3 или вы хотите написать код, который будет работать независимо от того, доступно ли расширение PECL, вам нужно будет использовать класс ParagonIE_Sodium_Compat для большинства ваших потребностей libsodium.

Приведенный выше пример написан для общего использования:

 <?php
require_once " /path/to/sodium_compat/autoload.php " ;

$ alice_kp = ParagonIE_Sodium_Compat:: crypto_sign_keypair ();
$ alice_sk = ParagonIE_Sodium_Compat:: crypto_sign_secretkey ( $ alice_kp );
$ alice_pk = ParagonIE_Sodium_Compat:: crypto_sign_publickey ( $ alice_kp );

$ message = ' This is a test message. ' ;
$ signature = ParagonIE_Sodium_Compat:: crypto_sign_detached ( $ message , $ alice_sk );
if (ParagonIE_Sodium_Compat:: crypto_sign_verify_detached ( $ signature , $ message , $ alice_pk )) {
    echo ' OK ' , PHP_EOL ;
} else {
    throw new Exception ( ' Invalid signature ' );
}

В целом: если вы замените sodium_ на ParagonIE_Sodium_Compat:: , любой код, уже написанный для PHP-расширения libsodium, должен работать с нашим полифиллом без дополнительных изменений кода.

Поскольку для этого не требуется пространство имен, этот API доступен в PHP 5.2.

Начиная с версии 0.7.0, у нас есть собственный API с пространством имен ( ParagonIESodium* ), чтобы обеспечить краткость программного обеспечения, использующего PHP 5.3+. Это полезно, если вы хотите использовать наши функции шифрования файлов, не записывая каждый раз ParagonIE_Sodium_File . Это не отображается в PHP < 5.3, поэтому, если ваш проект поддерживает PHP < 5.3, вместо этого используйте метод подчеркивания.

Чтобы узнать, как использовать Libsodium, прочтите «Использование Libsodium в проектах PHP» .

Помогите, Sodium_Compat работает медленно! Как я могу сделать это быстро?

Есть три способа сделать это быстро:

Используйте более новую версию PHP (не ниже 7.2).
Установите PHP-расширение libsodium из PECL.
Только если предыдущие два варианта вам недоступны:
1. Убедитесь, что используемый вами процессор действительно реализует умножение с постоянным временем. Sodium_compat это делает, но ему приходится жертвовать некоторой скоростью, чтобы обеспечить кроссплатформенную безопасность.
2. Только если вы на 100% уверены, что ваш процессор безопасен, вы можете установить ParagonIE_Sodium_Compat::$fastMult = true; без ущерба для безопасности ваших криптографических ключей. Если ваш процессор небезопасен , решите, хотите ли вы скорости или безопасности, потому что вы не можете иметь и то, и другое.

Как я могу определить, будет ли натрия_компат работать медленно во время выполнения?

Начиная с версии 1.8, вы можете использовать статический метод polyfill_is_fast() , чтобы определить, будет ли натрия_компат работать медленно во время выполнения.

 <?php
if (ParagonIE_Sodium_Compat:: polyfill_is_fast ()) {
    // Use libsodium now
    $ process -> execute ();
} else {
    // Defer to a cron job or other sort of asynchronous process
    $ process -> enqueue ();
}

Документация

Сначала вам нужно прочитать Краткий справочник Libsodium. Его цель — ответить на вопрос: «Какую функцию мне следует использовать для решения [частой проблемы]?».

Если вы не нашли ответы на странице «Краткий справочник», ознакомьтесь с разделом «Использование Libsodium в проектах PHP» .

Наконец, официальная документация libsodium (которая была написана для библиотеки C, а не для библиотеки PHP) также содержит много полезной технической информации, которая может оказаться полезной.

Покрытие API

Рекомендуемая литература: Краткий справочник по Libsodium.

Основные характеристики NaCl
- crypto_auth()
- crypto_auth_verify()
- crypto_box()
- crypto_box_open()
- crypto_scalarmult()
- crypto_secretbox()
- crypto_secretbox_open()
- crypto_sign()
- crypto_sign_open()
Особенности PECL Libsodium
- crypto_aead_aegis128l_encrypt()
- crypto_aead_aegis128l_decrypt()
- crypto_aead_aegis256_encrypt()
- crypto_aead_aegis256_decrypt()
- crypto_aead_aes256gcm_encrypt()
- crypto_aead_aes256gcm_decrypt()
- crypto_aead_chacha20poly1305_encrypt()
- crypto_aead_chacha20poly1305_decrypt()
- crypto_aead_chacha20poly1305_ietf_encrypt()
- crypto_aead_chacha20poly1305_ietf_decrypt()
- crypto_aead_xchacha20poly1305_ietf_encrypt()
- crypto_aead_xchacha20poly1305_ietf_decrypt()
- crypto_box_xchacha20poly1305()
- crypto_box_xchacha20poly1305_open()
- crypto_box_seal()
- crypto_box_seal_open()
- crypto_generichash()
- crypto_generichash_init()
- crypto_generichash_update()
- crypto_generichash_final()
- crypto_kx()
- crypto_secretbox_xchacha20poly1305()
- crypto_secretbox_xchacha20poly1305_open()
- crypto_shorthash()
- crypto_sign_detached()
- crypto_sign_ed25519_pk_to_curve25519()
- crypto_sign_ed25519_sk_to_curve25519()
- crypto_sign_verify_detached()
- Только для опытных пользователей:
  - crypto_core_ristretto255_add()
  - crypto_core_ristretto255_from_hash()
  - crypto_core_ristretto255_is_valid_point()
  - crypto_core_ristretto255_random()
  - crypto_core_ristretto255_scalar_add()
  - crypto_core_ristretto255_scalar_complement()
  - crypto_core_ristretto255_scalar_invert()
  - crypto_core_ristretto255_scalar_mul()
  - crypto_core_ristretto255_scalar_negate()
  - crypto_core_ristretto255_scalar_random()
  - crypto_core_ristretto255_scalar_reduce()
  - crypto_core_ristretto255_scalar_sub()
  - crypto_core_ristretto255_sub()
  - crypto_scalarmult_ristretto255_base()
  - crypto_scalarmult_ristretto255()
  - crypto_stream()
  - crypto_stream_keygen()
  - crypto_stream_xor()
  - crypto_stream_xchacha20()
  - crypto_stream_xchacha20_keygen()
  - crypto_stream_xchacha20_xor()
  - crypto_stream_xchacha20_xor_ic()
- Другие утилиты (например, crypto_*_keypair() )
  - add()
  - base642bin()
  - bin2base64()
  - bin2hex()
  - hex2bin()
  - crypto_kdf_derive_from_key()
  - crypto_kx_client_session_keys()
  - crypto_kx_server_session_keys()
  - crypto_secretstream_xchacha20poly1305_init_push()
  - crypto_secretstream_xchacha20poly1305_push()
  - crypto_secretstream_xchacha20poly1305_init_pull()
  - crypto_secretstream_xchacha20poly1305_pull()
  - crypto_secretstream_xchacha20poly1305_rekey()
  - pad()
  - unpad()

Предоставленные криптографические примитивы

X25519 — эллиптическая кривая Диффи-Хеллмана над кривой 25519
Ed25519 - Алгоритм цифровой подписи кривой Эдвардса на основе Curve25519
Xsalsa20 — потоковый шифр Salsa20 с расширенным одноразовым номером
ChaCha20 — Потоковое шифрование
Xchacha20 — потоковый шифр ChaCha20 с расширенным одноразовым номером.
Poly1305 — Код аутентификации сообщения полиномиальной оценки по модулю 2^130 — 5
BLAKE2b — криптографическая хэш-функция
SipHash-2-4 — быстрый хеш, но не устойчивый к коллизиям; идеально подходит для хеш-таблиц.

Функции, исключенные из этого полифилла

sodium_memzero() — хотя мы предоставляем эту конечную точку API, мы не можем надежно обнулить буферы из PHP.
Если у вас установлено расширение PHP, натрия_компат будет использовать собственную реализацию для обнуления предоставленной строки. В противном случае будет выдано исключение SodiumException .
sodium_crypto_pwhash() — невозможно полифиллить scrypt или Argon2 в PHP и получить приемлемую производительность. Пользователи будут чувствовать мотивацию выбирать параметры, снижающие уровень безопасности, чтобы избежать атак типа «отказ в обслуживании» (DoS).
Единственный выигрышный ход – не играть.
Если установлено ext/sodium или ext/libsodium, эти методы API будут перенесены в расширение. В противном случае наша библиотека полифилов выдаст исключение SodiumException .
Чтобы обнаружить поддержку Argon2i во время выполнения, используйте ParagonIE_Sodium_Compat::crypto_pwhash_is_available() , который возвращает логическое значение ( TRUE или FALSE ).
API HKDF Libsodium ( crypto_kdf_hkdf_*() ) не включен, поскольку PHP имеет свои собственные функции HMAC, и это не было сочтено необходимым.

Набор правил совместимости PHP

Для пользователей натрия_compat, которые используют PHPCompatibility в своем процессе CI, теперь доступен собственный набор правил, который можно использовать для предотвращения ложных срабатываний, выдаваемых PHPCompatibility для встроенной функциональности PHP, заполняемой этим репозиторием.

Репозиторий набора правил PHPCompatibilityParagonieSodiumCompat можно найти здесь, на Github и Packagist.

Расширять

Дополнительная информация