sodium_compat
Version 2.1.0
Sodium Compat é um polyfill PHP puro para a biblioteca de criptografia Sodium (libsodium), uma extensão central no PHP 7.2.0+ e disponível em PECL.
Se você tiver a extensão PHP instalada, o Sodium Compat usará a extensão PHP de forma oportunista e transparente em vez de nossa implementação.
sódio_compat v1.21.0 foi a última versão v1.x do branch master. De agora em diante, todas as versões futuras que suportam PHP 5.2 - 8.0 e números inteiros de 32 bits estarão na ramificação v1.x
Versões mais recentes do sódio_compat (ou seja, v2.0.0) continuarão a existir no branch master, a menos que uma nova versão principal seja necessária. O objetivo deste trabalho é melhorar a legibilidade e o desempenho do código, ao mesmo tempo que reduz o código padrão.
Em caso de dúvida, consulte o arquivo README na ramificação master para obter as informações mais recentes sobre a versão.
| versão de sódio_compat | Versões PHP suportadas | Suporte de 32 bits? | Filial |
|---|---|---|---|
v1.xy | 5.2.4 - ÚLTIMO | SIM | v1.x |
v2.xy | 8.1 - ÚLTIMO | NÃO | mestre |
Se você precisar de suporte PHP de 32 bits ( PHP_INT_SIZE == 4 ), continue usando o sódio_compat v1.x. Se você deseja melhor desempenho e dependências menores, use v2.x.
Recomendamos que bibliotecas e estruturas definam uma restrição de versão do Composer da seguinte forma:
{
"require" : {
/* ... */
"paragonie/sodium_compat" : ">= 1"
/* ... */
}
}Os aplicativos devem, por outro lado, especificar a versão real que é importante para eles e suas implantações.
Esta biblioteca de criptografia não foi formalmente auditada por terceiros independentes especializados em criptografia ou criptoanálise.
Se você precisar de tal auditoria antes de poder usar o sódio_compat em seus projetos e ter os fundos para tal auditoria, abra um problema ou entre em contato com security at paragonie dot com para que possamos ajudar a dar o pontapé inicial.
No entanto, o sodium_compat foi adotado por projetos de código aberto de alto perfil, como o Joomla! e Magento. Além disso, o sódio_compat foi desenvolvido pela Paragon Initiative Enterprises, uma empresa especializada em desenvolvimento seguro de PHP e criptografia PHP, e foi revisado informalmente por muitos outros especialistas em segurança que também são especializados em PHP.
Se você quiser saber mais sobre as medidas defensivas de segurança que tomamos para evitar que o sodium_compat seja uma fonte de vulnerabilidade em seus sistemas, leia Desenvolvimento PHP Criptograficamente Seguro .
Se você estiver usando o Composer:
composer require paragonie/sodium_compat Se você não estiver usando o Composer, baixe um tarball de lançamento (que deve ser assinado com nossa chave pública GnuPG), extraia seu conteúdo e inclua nosso script autoload.php em seu projeto.
<?php
require_once " /path/to/sodium_compat/autoload.php " ;Desde a versão 1.3.0, as versões do sodium_compat incluem um arquivo PHP (arquivo .phar) e assinatura GPG associada. Primeiro, baixe os dois arquivos e verifique-os com nossa chave pública GPG, assim:
# 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 verification 33[0m "
exit 1
fi
fi
# Verifying the PHP Archive
gpg --verify sodium-compat.phar.sig sodium-compat.pharAgora, basta incluir este arquivo .phar em sua aplicação.
<?php
require_once " /path/to/sodium-compat.phar " ;O suporte comercial para libsodium está disponível em vários fornecedores. Se precisar de ajuda para usar o sodium_compat em um de seus projetos, entre em contato com a Paragon Initiative Enterprises.
Relatórios não comerciais serão facilitados por meio de questões do Github. Não oferecemos garantias de nossa disponibilidade para resolver questões sobre a integração gratuita do sódio_compat em software de terceiros, mas nos esforçaremos para corrigir quaisquer bugs (relacionados à segurança ou não) em nossa biblioteca.
Se sua empresa usa esta biblioteca em seus produtos ou serviços, você pode estar interessado em adquirir um contrato de suporte da Paragon Initiative Enterprises.
De acordo com a segunda votação na RFC da libsodium, o PHP 7.2 usa sodium_* em vez de 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 ' );
} Se seus usuários usam PHP < 5.3, ou você deseja escrever um código que funcione independentemente de a extensão PECL estar disponível ou não, você desejará usar a classe ParagonIE_Sodium_Compat para a maioria de suas necessidades de libsodium.
O exemplo acima, escrito para uso geral:
<?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 ' );
} Geralmente: Se você substituir sodium_ por ParagonIE_Sodium_Compat:: , qualquer código já escrito para a extensão PHP libsodium deverá funcionar com nosso polyfill sem alterações adicionais no código.
Como isso não requer um namespace, esta API está exposta no PHP 5.2.
Desde a versão 0.7.0, temos nossa própria API com namespace ( ParagonIESodium* ) para permitir brevidade em software que usa PHP 5.3+. Isso é útil se você quiser usar nossos recursos de criptografia de arquivos sem escrever ParagonIE_Sodium_File todas as vezes. Isso não é exposto em PHP < 5.3, portanto, se o seu projeto suportar PHP < 5.3, use o método de sublinhado.
Para aprender como usar o Libsodium, leia Usando o Libsodium em projetos PHP .
Existem três maneiras de tornar isso rápido:
ParagonIE_Sodium_Compat::$fastMult = true; sem prejudicar a segurança de suas chaves de criptografia. Se o seu processador não for seguro, decida se deseja velocidade ou segurança, porque não pode ter os dois. Desde a versão 1.8, você pode usar o método estático polyfill_is_fast() para determinar se sodium_compat será lento em tempo de execução.
<?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 ();
}Primeiro, você vai querer ler a Referência Rápida do Libsodium. O objetivo é responder: "Qual função devo usar para [problema comum]?".
Se você não encontrar as respostas na página de Referência Rápida, confira Usando Libsodium em Projetos PHP .
Finalmente, a documentação oficial da libsodium (que foi escrita para a biblioteca C, não para a biblioteca PHP) também contém muitas informações técnicas esclarecedoras que você pode achar úteis.
Leitura recomendada: Referência rápida do Libsodium
crypto_auth()crypto_auth_verify()crypto_box()crypto_box_open()crypto_scalarmult()crypto_secretbox()crypto_secretbox_open()crypto_sign()crypto_sign_open()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() sodium_memzero() - Embora exponhamos esse endpoint da API, não podemos zerar buffers do PHP de maneira confiável.
Se você tiver a extensão PHP instalada, o sódio_compat usará a implementação nativa para zerar a string fornecida. Caso contrário, lançará um SodiumException .
sodium_crypto_pwhash() - Não é viável fazer polyfill scrypt ou Argon2 em PHP e obter um desempenho razoável. Os usuários se sentiriam motivados a selecionar parâmetros que reduzissem a segurança para evitar ataques de negação de serviço (DoS).
A única jogada vencedora é não jogar.
Se ext/sodium ou ext/libsodium estiver instalado, esses métodos de API passarão pela extensão. Caso contrário, nossa biblioteca polyfill lançará uma SodiumException .
Para detectar suporte para Argon2i em tempo de execução, use ParagonIE_Sodium_Compat::crypto_pwhash_is_available() , que retorna um valor booleano ( TRUE ou FALSE ).
A API HKDF do Libsodium ( crypto_kdf_hkdf_*() ) não está incluída porque o PHP tem seus próprios recursos HMAC e não foi considerado necessário.
Para usuários de sódio_compat e que utilizam PHPCompatibility em seu processo de CI, agora há um conjunto de regras personalizado disponível que pode ser usado para evitar que falsos positivos sejam lançados por PHPCompatibility para a funcionalidade nativa do PHP sendo preenchida por este repositório.
Você pode encontrar o repositório do conjunto de regras PHPCompatibilityParagonieSodiumCompat aqui no Github e no Packagist.
