Documentacion PWR Rubrica

Instalacion

Rubrica es un unico archivo PHP con dos backends de firma posibles.

PHP

require_once __DIR__ . '/core/rubrica.php';

Requisitos minimos

PHP 7.4 o superior
Para ML-DSA (post-cuantico): Extension ffi + libreria liboqs instalada
Para Ed25519 (clasico): Extension sodium (incluida en PHP 7.2+)
Al menos uno de los dos backends debe estar disponible

Auto-deteccion: Rubrica detecta automaticamente que backends estan disponibles y usa ML-DSA si es posible, con fallback a Ed25519. Puedes forzar el algoritmo al generar claves.

Inicio rapido

Genera claves, firma un texto y verificalo.

PHP

require_once 'core/rubrica.php';

$claves = pwr_rubrica_generar_claves();
$firma = pwr_rubrica_firmar('Documento importante', $claves['privada']);
$valido = pwr_rubrica_verificar('Documento importante', $firma['firma'], $claves['publica']);

Funciones

pwr_rubrica_generar_claves()

Genera un par de claves (publica/privada) para firmar. Soporta ML-DSA-65, Ed25519 o auto-deteccion.

Firma

pwr_rubrica_generar_claves(string $algoritmo = 'auto'): array

Parametro	Tipo	Descripcion
`$algoritmo`	`string`	`'auto'` (mejor disponible), `'ml-dsa'` (post-cuantico) o `'ed25519'` (clasico)

Retorna: array con ok, publica (base64), privada (base64), algoritmo.

pwr_rubrica_firmar()

Firma una cadena de texto con la clave privada.

Firma

pwr_rubrica_firmar(string $datos, string $clave_privada_b64): array

Parametro	Tipo	Descripcion
`$datos`	`string`	Texto o datos a firmar
`$clave_privada_b64`	`string`	Clave privada en base64

Retorna: array con ok, firma (base64), algoritmo, timestamp.

pwr_rubrica_verificar()

Verifica una firma digital contra los datos originales y la clave publica.

Firma

pwr_rubrica_verificar(string $datos, string $firma_b64, string $clave_publica_b64): array

Parametro	Tipo	Descripcion
`$datos`	`string`	Datos originales firmados
`$firma_b64`	`string`	Firma en base64
`$clave_publica_b64`	`string`	Clave publica en base64

Retorna: array con ok, valido (bool), algoritmo.

pwr_rubrica_firmar_archivo()

Firma un archivo completo. Calcula el hash del contenido y firma el hash.

Firma

pwr_rubrica_firmar_archivo(string $ruta, string $clave_privada_b64): array

Retorna: array con ok, firma, hash, algoritmo, archivo.

pwr_rubrica_verificar_archivo()

Verifica la firma de un archivo.

Firma

pwr_rubrica_verificar_archivo(string $ruta, string $firma_b64, string $clave_publica_b64): array

Retorna: array con ok, valido (bool).

pwr_rubrica_exportar_firma()

Exporta una firma a formato JSON portable, incluyendo metadatos del firmante y timestamp.

Firma

pwr_rubrica_exportar_firma(array $firma_resultado, string $firmante = ''): string

Parametro	Tipo	Descripcion
`$firma_resultado`	`array`	Resultado de `pwr_rubrica_firmar()`
`$firmante`	`string`	Nombre o identificador del firmante (opcional)

Retorna: string JSON con la firma exportada.

pwr_rubrica_importar_firma()

Importa una firma desde JSON portable para su verificacion.

Firma

pwr_rubrica_importar_firma(string $json_string): array

Retorna: array con los datos de la firma: firma, algoritmo, firmante, timestamp.

pwr_rubrica_disponible()

Comprueba que backends de firma estan disponibles en el sistema.

Firma

pwr_rubrica_disponible(): array

Retorna: array con ml_dsa (bool), ed25519 (bool), mejor (string).

pwr_rubrica_info()

Devuelve informacion del modulo: version, backends disponibles y algoritmo preferido.

Firma

pwr_rubrica_info(): array

Retorna: array con version, backends, algoritmo_preferido.

Configuracion

Rubrica no requiere archivo de configuracion. Los algoritmos se auto-detectan segun las extensiones disponibles en el servidor.

Backend	Algoritmo	Requisitos	Nivel
liboqs + FFI	ML-DSA-65 (Dilithium)	`ext-ffi` + `liboqs.so/dll`	Post-cuantico
ext-sodium	Ed25519	`ext-sodium` (PHP 7.2+)	Clasico

Recomendacion: Para maxima seguridad a largo plazo, instala liboqs para habilitar firmas ML-DSA resistentes a computacion cuantica. Ed25519 sigue siendo seguro hoy, pero no resistira ataques cuanticos futuros.

Ejemplos

Firmar y verificar un documento

PHP

require_once 'core/rubrica.php';

// Generar par de claves (auto-detecta mejor algoritmo)
$claves = pwr_rubrica_generar_claves();
echo 'Algoritmo: ' . $claves['algoritmo'];

// Firmar texto
$documento = 'Contrato entre parte A y parte B, firmado el 15/01/2025';
$firma = pwr_rubrica_firmar($documento, $claves['privada']);

// Verificar firma
$verificacion = pwr_rubrica_verificar($documento, $firma['firma'], $claves['publica']);
echo $verificacion['valido'] ? 'Firma valida' : 'Firma invalida';

Firmar un archivo PDF

PHP

require_once 'core/rubrica.php';

$claves = pwr_rubrica_generar_claves('ml-dsa');

// Firmar archivo
$firma = pwr_rubrica_firmar_archivo('/documentos/contrato.pdf', $claves['privada']);

// Exportar firma a JSON portable
$json = pwr_rubrica_exportar_firma($firma, 'Departamento Legal');
file_put_contents('contrato.pdf.sig', $json);

Verificar firma importada

PHP

require_once 'core/rubrica.php';

// Importar firma desde JSON
$json = file_get_contents('contrato.pdf.sig');
$firma_importada = pwr_rubrica_importar_firma($json);

// Verificar archivo contra la firma importada
$resultado = pwr_rubrica_verificar_archivo(
    '/documentos/contrato.pdf',
    $firma_importada['firma'],
    $firma_importada['clave_publica']
);

echo $resultado['valido'] ? 'Archivo integro' : 'Archivo modificado';

Comprobar backends disponibles

PHP

require_once 'core/rubrica.php';

$backends = pwr_rubrica_disponible();
echo 'ML-DSA: ' . ($backends['ml_dsa'] ? 'Si' : 'No');
echo 'Ed25519: ' . ($backends['ed25519'] ? 'Si' : 'No');
echo 'Mejor algoritmo: ' . $backends['mejor'];

$info = pwr_rubrica_info();
echo 'Rubrica v' . $info['version'];