Search by

sat-suite / certificates

xaamin

SAT certificates tools

Package info

gitlab.com/sat-suite/certificates

Issues

pkg:composer/sat-suite/certificates

Statistics

Installs: 3 176

Dependents: 0

Suggesters: 0

Stars: 0

1.0.0 2026-11-14 19:33 UTC

This package is auto-updated.

Last update: 2026-11-20 17:17:13 UTC


README

Carga y valida las credenciales fiscales del SAT, ya sea el Certificado de Sello Digital (CSD) o la e.firma (FIEL). Trabaja con el certificado público .cer (X.509) y con la llave privada .key (PKCS#8 DER cifrada) y su contraseña. Expone los datos del certificado: RFC, razón social, CURP, número de certificado (NoCertificado), vigencia y tipo (CSD o FIEL). También firma y verifica datos con OpenSSL.

Es la pieza de firma de la suite y no conoce XML ni cadena original, sólo los bytes que se firman:

  • Sellado (pre-timbrado): sat-suite/cfdi-builder la usa para obtener NoCertificado y Certificado y para firmar la cadena original, que da el Sello.
  • Cancelación: sat-suite/cfdi-cancel-xml firma el XML de cancelación (XMLDSig, RSA-SHA1).
  • Descarga Masiva: sat-suite/ws-descarga autentica y firma sus solicitudes SOAP con la FIEL.

Requisitos

  • PHP ^8.3
  • ext-openssl (requerida)
  • Opcionales (suggest): ext-gmp o, si no está, ext-bcmath. Sólo se usan para calcular el número de certificado cuando OpenSSL no entrega serialNumberHex. Sin ninguna de las dos se recurre a base_convert.

Instalación

composer require sat-suite/certificates

Uso

Cargar un CSD o una FIEL

FiscalCredentials::load($llavePrivada, $certificado, $contrasena) lee ambos archivos y comprueba que la llave privada corresponda al certificado. Si no coinciden, lanza FiscalCredentialsMismatchException.

use SatSuite\Certificates\FiscalCredentials;

$credentials = (new FiscalCredentials())->load(
    '/ruta/CSD_EKU9003173C9.key',   // llave privada
    '/ruta/CSD_EKU9003173C9.cer',   // certificado
    '12345678a'                     // contraseña de la llave
);

$privateKey  = $credentials->private(); // SatSuite\Certificates\KeyPairs\PrivateKey
$certificate = $credentials->public();  // SatSuite\Certificates\KeyPairs\PublicKey

Cada argumento acepta una ruta o el contenido. Si la cadena (sin bytes \0) es un archivo existente, se lee; si no, se trata como contenido. Se aceptan estos formatos:

EntradaFormatos aceptados
Llave privadaDER (el .key del SAT), PEM PKCS#8 en claro o cifrado, PEM PKCS#5 en claro o cifrado
CertificadoDER (el .cer del SAT), PEM, o DER en base64 (también en varias líneas)
$credentials = (new FiscalCredentials())->load(
    file_get_contents('/ruta/csd.key'),
    base64_encode(file_get_contents('/ruta/csd.cer')),
    '12345678a'
);

Leer los datos del certificado

$certificate = $credentials->public();

$certificate->getRfc();            // "EKU9003173C9": RFC del titular (null si no lo trae)
$certificate->getRazonSocial();    // "ESCUELA KEMPER URGATE SA DE CV" (subject.name)
$certificate->getCurp();           // CURP del titular, o null si no la trae
$certificate->getSerialNumber();   // "30001000000500003416": NoCertificado de 20 dígitos
$certificate->getSerialNumberHex();// número de serie en hexadecimal

$certificate->getIssuedAt();       // DateTimeImmutable (UTC), inicio de vigencia
$certificate->getExpiresAt();      // DateTimeImmutable (UTC), fin de vigencia
$certificate->isExpired();         // bool

$certificate->isCsd();             // true si es un CSD
$certificate->isFiel();            // true si es una e.firma
$certificate->getUsage();          // "Digital Signature, Non Repudiation"

$certificate->getCertificate();    // certificado en base64 sin saltos (atributo Certificado del CFDI)
$certificate->getCertificate(true);// igual, pero con los encabezados BEGIN/END CERTIFICATE
$certificate->getPublicKey();      // llave pública RSA en base64

$certificate->getData();           // arreglo completo de openssl_x509_parse()
$certificate->{'subject.x500UniqueIdentifier'}; // acceso con dot-notation a getData()

Para leer sólo el certificado, sin llave privada:

use SatSuite\Certificates\KeyPairs\PublicKey;

$certificate = new PublicKey($pem); // PEM (ruta o contenido)
// o: (new \SatSuite\Certificates\Parsers\PublicKeyParser())->load('/ruta/csd.cer'), que también acepta DER

Firmar y verificar

sign() devuelve la firma binaria y verify() devuelve el resultado de openssl_verify(): 1 si es válida, 0 si no lo es y -1 o false si hay error. El algoritmo por defecto es OPENSSL_ALGO_SHA256.

// Sello de CFDI 3.3/4.0 y Retenciones 2.0: RSA-SHA256
$sello = base64_encode($credentials->sign($cadenaOriginal));

$credentials->verify($cadenaOriginal, base64_decode($sello)); // 1

// Retenciones 1.0, cancelación y Descarga Masiva: RSA-SHA1
$firma = $credentials->sign($datos, OPENSSL_ALGO_SHA1);
$credentials->verify($datos, $firma, OPENSSL_ALGO_SHA1);      // 1

PrivateKey::sign($data, $algorithm) y PublicKey::verify($data, $signature, $algorithm) hacen lo mismo cuando se trabaja con cada pieza por separado.

Errores

Las fallas de carga extienden SatSuite\Certificates\Exceptions\FiscalCredentialsProcessingException:

ExcepciónCuándo
PrivateKeyFileNotReadableException / PublicKeyFileNotReadableExceptionEl archivo existe pero no se puede leer
PrivateKeyProcessingExceptionLa llave no se puede abrir: contraseña incorrecta o contenido inválido
PrivateKeyInfoParsingExceptionOpenSSL no puede leer los detalles de la llave
PublicKeyInfoParsingExceptionEl contenido no es un certificado X.509 válido
FiscalCredentialsMismatchExceptionLa llave privada no corresponde al certificado (Key pairs mismatch)

SignatureGenerationException (lanzada por sign()) extiende RuntimeException y no forma parte de esa jerarquía.

use SatSuite\Certificates\Exceptions\FiscalCredentialsProcessingException;

try {
    $credentials = (new FiscalCredentials())->load($key, $cer, $password);
} catch (FiscalCredentialsProcessingException $e) {
    // credenciales inválidas, contraseña incorrecta o pareja que no coincide
}

Notas de comportamiento

  • CSD o FIEL: se determina por el conjunto exacto de valores de keyUsage, sin importar orden, mayúsculas ni espacios. Un CSD tiene Digital Signature y Non Repudiation; una FIEL tiene además Data Encipherment y Key Agreement.
  • RFC y CURP: el SAT las guarda como "titular / representante legal". getRfc() y getCurp() devuelven el primer valor no vacío, es decir, el del titular.
  • NoCertificado: el número de serie del SAT es una cadena ASCII de dígitos. getSerialNumber() toma el segundo dígito hexadecimal de cada byte para obtener los 20 dígitos.
  • La llave privada se descifra una sola vez y se conserva en memoria para las firmas siguientes. Al serializar un PrivateKey sólo se guardan el contenido y la contraseña, y la llave se vuelve a abrir cuando se necesita.
  • La carga de la llave sólo comprueba que se pueda leer. No conserva sus componentes (d, p, q…).
  • El autoload registra la función global array_get() si no existe. Si Laravel ya la definió, se usa la de Laravel.

Desarrollo

composer install && npm install   # npm instala los hooks de husky (commitlint)
npm test                          # Pest (suites Unit y Feature)
npm run lint:check                # phpcs PSR12 sobre src/
npm run code:scan                 # phpstan nivel 5

Las pruebas no usan credenciales reales ni red. Generan en tiempo de ejecución, con OpenSSL, un CSD, una FIEL, un CSD que no coincide y otro vencido (tests/Support/TestCredentials.php), con la misma forma que los del SAT. El caso del certificado vencido requiere el CLI openssl 3.4 o superior; sin él, esa prueba se omite.

Los commits siguen Conventional Commits. Para publicar una versión, npm run release (o release:patch, release:minor, release:major) actualiza package.json, composer.json y CHANGELOG.md, hace el commit y crea la etiqueta vX.Y.Z. Después se ejecuta git push --follow-tags.

Licencia

MIT. Consulta LICENSE.