README

Pacote Composer experimental para consultas Eloquent sobre campos criptografados no próprio banco, inspirado no CakeAes.

Estado: estrutura do pacote, perfis de banco e helpers de consulta estão implementados. A gravação e leitura automáticas no ciclo de vida dos models, as operações em lote e os testes de integração em servidores reais ainda estão pendentes. Não use em produção.

Requisitos

PHP 8.2 ou superior.
Laravel/Illuminate Database 12 ou 13; o Laravel 13 requer PHP 8.3.
MySQL/MariaDB ou PostgreSQL com pgcrypto habilitada.

Instalação durante o desenvolvimento

Em desenvolvimento local, configure um repositório path e instale o pacote:

{
  "repositories": [
    { "type": "path", "url": "/var/www/laravel-encrypt", "options": { "symlink": true } }
  ]
}

composer require gildonei/laravel-encrypt:dev-main
php artisan vendor:publish --tag=laravel-encrypt-config

O pacote ainda não foi publicado no Packagist.

Configure segredos diferentes fora do código versionado. Para criptografia de texto, use colunas BLOB/VARBINARY no MySQL ou bytea no PostgreSQL.

Uso atualmente implementado

Um model opta pelos campos e pode selecionar um perfil específico por campo:

use Gildonei\LaravelEncrypt\Concerns\HasEncryptedFields;
use Illuminate\Database\Eloquent\Model;

class Citizen extends Model
{
    use HasEncryptedFields;

    public function encryptedFields(): array
    {
        return ['name', 'phone'];
    }

    public function encryptedFieldProfiles(): array
    {
        return ['phone' => 'postgres-raw'];
    }
}

Os helpers implementados geram SQL para filtrar, ordenar ou selecionar texto descriptografado:

$citizens = Citizen::query()
    ->whereEncryptedLike('name', '%Santos%')
    ->whereEncryptedIn('phone', ['11999999999', '11888888888'])
    ->orderByEncrypted('name')
    ->get();

$names = Citizen::query()->selectEncrypted('name', 'display_name')->get();

Também existem whereEncrypted, orWhereEncrypted, whereEncryptedNotIn, encryptValue e decryptValue. Valores e chaves são passados em bindings. Identificadores, operadores e direções são validados.

Esses helpers não tornam create(), save(), refresh() ou acesso a propriedades transparentes. As colunas precisam conter ciphertext compatível antes de uma consulta protegida. SQL livre e DB::table() não recebem criptografia automática.

Configuração e formatos

Publique config/laravel-encrypt.php e defina as variáveis de ambiente para chaves. O arquivo inclui:

MySQL legado AES_ENCRYPT/AES_DECRYPT, com chave hexadecimal e modo de sessão validado quando o helper manual executa.
MySQL aes-256-ecb, com chave de 64 caracteres hexadecimais.
MariaDB no formato legado AES-128-ECB.
PostgreSQL PGP com pgp_sym_encrypt/pgp_sym_decrypt e AES-256.
PostgreSQL raw com encrypt/decrypt, tipo aes-cbc/pad:pkcs, chave AES explícita e conversão UTF-8.

PGP é o perfil padrão do PostgreSQL. O perfil raw é selecionado explicitamente e pode ser aplicado a um campo por encryptedFieldProfiles(). Os formatos são incompatíveis entre si e requerem migração para troca de perfil.

O formato MySQL legado em ECB e o formato PostgreSQL raw não autenticam ciphertext. O banco recebe a chave para executar as funções. Configure TLS e redija bindings sensíveis nos logs.

Desenvolvimento e verificação

composer install
composer test
find src tests -type f -name '*.php' -print0 | xargs -0 -n1 php -l

A suíte atual contém testes unitários de perfis e da SQL/bindings gerados. Ela não executa AES_ENCRYPT, pgcrypto ou consultas em servidores MySQL/PostgreSQL.

Próximas etapas

O plano detalhado, as decisões propostas e o backlog permanecem como especificação completa. A implementação iniciada atende ao núcleo dos itens LE-005 a LE-008B e LE-013/LE-014 para helpers explícitos; ainda não conclui o critério LE-002/LE-003, o ciclo automático Eloquent, interoperabilidade nem v0.1.0.

Referência

CakeAes, de Joacir Gonçalves dos Santos, é a referência de comportamento, publicada sob MIT. Os documentos do planejamento reconhecem essa origem. A licença MIT deste pacote se aplica ao código deste repositório.

gildonei / laravel-encrypt

Package info

Security

Statistics