README

Argon2 para Lazarus / Free Pascal (Windows)

Bindings em Object Pascal para a biblioteca Argon2, o algoritmo vencedor da Password Hashing Competition e referência atual para hashing seguro de senhas.

O projeto Argon2 oficial (P-H-C/phc-winner-argon2) não distribui DLLs pré-compiladas nem bindings para Lazarus/Free Pascal. Este repositório resolve os dois problemas:

• DLLs compiladas para Windows (32 e 64 bits), prontas para uso — sem precisar instalar MSYS2/MinGW ou compilar a lib C você mesmo.
• Units Pascal com as declarações external e helpers de alto nível, para chamar o Argon2 diretamente do Lazarus/FPC.

Por que este projeto existe

Ao pesquisar uma forma de usar Argon2 em uma aplicação Delphi/Lazarus, não encontrei nenhum binding pronto e mantido para Windows. A biblioteca oficial é em C, então o caminho foi:

1. Compilar a libargon2 como DLL para Windows (x86 e x64), a partir do código-fonte oficial.
2. Escrever as declarações cdecl; external em Pascal para expor as funções da DLL.
3. Organizar tudo em units reutilizáveis, prontas para dropar em qualquer projeto Lazarus.

Conteúdo do repositório

Requisitos

• Lazarus / Free Pascal Compiler (modo objfpc)
• Windows (as DLLs incluídas são para Windows; em Linux/macOS seria necessário compilar libargon2.so/.dylib — o binding estendido já prevê essas plataformas via {$IFDEF LINUX} / {$IFDEF DARWIN}, mas as bibliotecas não estão incluídas neste repositório)
• As DLLs devem estar no mesmo diretório do executável (ou em um diretório presente no PATH)

Instalação

1. Copie argon2_32.dll e argon2_64.dll para a pasta do seu executável.
2. Adicione argon2binding.pas ou argon2bindingex.pas ao seu projeto (uses).
3. Compile — a unit já seleciona automaticamente a DLL de 32 ou 64 bits via {$IFDEF CPU64}.

Uso básico

Exemplo usando a API de alto nível argon2id_hash_encoded / argon2id_verify (recomendada pela especificação oficial para a maioria dos casos):

program TesteArgon2;

{$mode objfpc}{$H+}

uses
  argon2binding;

const
  T_COST      = 2;      // iterações
  M_COST      = 65536;  // memória em KB (64 MB)
  PARALLELISM = 1;      // threads/lanes
  HASH_LEN    = 32;     // tamanho do hash em bytes

var
  senha: AnsiString;
  salt: array[0..15] of Byte;
  encoded: array[0..127] of AnsiChar;
  encodedLen: NativeUInt;
  resultado: Integer;
begin
  senha := 'MinhaSenhaSuperSecreta';

  // Em produção, gere o salt com um RNG criptograficamente seguro
  FillChar(salt, SizeOf(salt), $42);

  encodedLen := argon2_encodedlen(T_COST, M_COST, PARALLELISM,
    SizeOf(salt), HASH_LEN, Argon2_id);

  resultado := argon2id_hash_encoded(
    T_COST, M_COST, PARALLELISM,
    PAnsiChar(senha), Length(senha),
    @salt, SizeOf(salt),
    HASH_LEN,
    @encoded[0], encodedLen
  );

  if resultado = ARGON2_OK then
  begin
    WriteLn('Hash: ', PAnsiChar(@encoded[0]));

    // Verificação
    resultado := argon2id_verify(@encoded[0], PAnsiChar(senha), Length(senha));
    if resultado = ARGON2_OK then
      WriteLn('Senha válida!')
    else
      WriteLn('Senha inválida.');
  end
  else
    WriteLn('Erro ao gerar hash: ', argon2_error_message(resultado));
end.

Qual binding usar?

• argon2binding.pas — se você só precisa de argon2id (hash + verify), é o suficiente e mais enxuto.
• argon2bindingex.pas — se precisa escolher entre argon2i, argon2d e argon2id, usar a API raw (bytes puros, sem string codificada), montar contexto customizado (TArgon2Context, callbacks de alocação de memória) ou tratar todos os códigos de erro individualmente.

Sobre os parâmetros de custo

• t_cost — número de iterações. Quanto maior, mais lento e mais seguro.
• m_cost — memória usada, em KB. É o principal fator de resistência a ataques com GPU/ASIC.
• parallelism — número de lanes/threads.

Não há um valor único recomendado para todos os casos — ajuste conforme o hardware do servidor e o tempo de resposta aceitável. A documentação oficial do Argon2 traz orientações de calibração.

Compilando as DLLs você mesmo

As DLLs deste repositório foram compiladas a partir do código-fonte oficial (P-H-C/phc-winner-argon2) usando MinGW-w64. Caso prefira compilar a sua própria versão:

git clone https://github.com/P-H-C/phc-winner-argon2.git
cd phc-winner-argon2
make

Ajuste o Makefile/toolchain conforme necessário para gerar .dll em vez de .so, ou utilize um ambiente MSYS2/MinGW no Windows.

Licença

O código-fonte do Argon2 é distribuído sob dupla licença CC0 / Apache 2.0 pelos autores originais. Consulte a licença do projeto oficial em P-H-C/phc-winner-argon2 para os termos que se aplicam à biblioteca C e às DLLs geradas a partir dela.

As units Pascal deste repositório (argon2binding.pas, argon2bindingex.pas) estão disponíveis livremente para uso, sob os termos que você definir ao publicar (sugestão: MIT).

Contribuindo

Sugestões, correções e melhorias são bem-vindas — especialmente builds para Linux/macOS, testes automatizados e exemplos adicionais de uso.