edwinjuarezpe/cr-mh-sign

PHP library for Costa Rica MH e-invoicing: XMLDSig/XAdES-EPES electronic signatures for XML documents.

v1.0.0 2026-07-26 00:38 UTC

Requires

• php: ^8.1
• ext-dom: *
• ext-libxml: *
• ext-openssl: *

MIT

• Edwin Juarez

Published on Packagist.org on 2026-07-26 00:40 UTC

README

Librería para firmar XML de comprobantes electrónicos de Ministerio de Hacienda (Costa Rica) usando XMLDSig + XAdES-EPES (RSA + SHA-256 por defecto).

Características

• Firma enveloped (ds:Signature dentro del XML).
• Perfil XAdES-EPES con SignaturePolicyIdentifier de MH.
• Soporta SHA1 / SHA256 / SHA384 / SHA512.
• Firma a partir de archivo XML o string XML.
• Incluye X509Data y RSAKeyValue desde el .p12.

Requisitos

• PHP ^8.1
• Extensiones: ext-dom, ext-libxml, ext-openssl
• Certificado PKCS#12 (.p12) con certificado y clave privada

Instalación

composer require edwinjuarezpe/cr-mh-sign

Uso rápido

1) Firmar archivo XML

<?php
require __DIR__ . '/vendor/autoload.php';

use EdwinJuarez\Mh\Facade\MhSigner;
use EdwinJuarez\Mh\Signing\Algorithm;

$certPath       = __DIR__ . '/examples/cert/mi-certificado.p12';
$certPassword   = 'mi_password';
$unsignedXmlPath = __DIR__ . '/examples/xml_unsigned/mi_comprobante.xml';
$signedXmlPath  = __DIR__ . '/examples/xml_signed/mi_comprobante.xml';

$signer = MhSigner::fromP12($certPath, $certPassword);
$signed = $signer->signXmlFile($unsignedXmlPath);

file_put_contents($signedXmlPath, rtrim($signed, PHP_EOL));
echo "OK: firmado en $signedXmlPath", PHP_EOL;

2) Firmar string XML

<?php
require __DIR__ . '/vendor/autoload.php';

use EdwinJuarez\Mh\Facade\MhSigner;
use EdwinJuarez\Mh\Signing\Algorithm;

$certPath     = __DIR__ . '/examples/cert/mi-certificado.p12';
$certPassword = 'mi_password';

$xmlString = file_get_contents(__DIR__ . '/examples/xml_unsigned/mi_comprobante.xml');

$signer = MhSigner::fromP12($certPath, $certPassword);
$signed = $signer->signXmlString($xmlString);

echo $signed; // o guardar con file_put_contents(...)

Compatibilidad de comprobantes

La firma es enveloped sobre el documento completo. Funciona para los tipos de MH (Factura, Tiquete Electrónico, Nota débito/crédito, etc.) siempre que el XML siga los namespaces y XSD oficiales. La validación fiscal final depende de los esquemas de MH.

Estructura relevante

• src/Facade/MhSigner.php — Fachada de alto nivel para firmar XML (desde archivo, string o DOM) cargando el .p12.
• src/Signing/XadesEpesSigner.php — Lógica de firma XAdES-EPES (XMLDSig + policy de MH).
• src/Signing/Algorithm.php — Mapeo de hash/URIs y constantes OPENSSL_ALGO_*.
• src/Signing/Pkcs12.php — Carga y parseo del certificado .p12/.pfx (certificado, clave y datos derivados).
• examples/ — Scripts de ejemplo (sign_file.php, sign_string.php).

Licencia

MIT

Autor

Edwin Juarez C.
Web: https://www.edwin-juarez.com/
LinkedIn: https://linkedin.com/in/edwin-juarez-c-7018681b9

☕ Donación

Si este proyecto te ayuda, invítame una taza de café:
PayPal: [e-mail]