sat-suite / certificates
SAT certificates tools
Requires
- php: ^8.3
- ext-openssl: *
Requires (Dev)
- pestphp/pest: ^3.0
- phpstan/phpstan: ^2.1
- squizlabs/php_codesniffer: ^3.8
Suggests
- ext-bcmath: Serial number conversion fallback when ext-gmp is not available
- ext-gmp: Faster serial number conversion for certificates without serialNumberHex
Provides
None
Conflicts
None
Replaces
None
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-builderla usa para obtenerNoCertificadoyCertificadoy para firmar la cadena original, que da elSello. - Cancelación:
sat-suite/cfdi-cancel-xmlfirma el XML de cancelación (XMLDSig, RSA-SHA1). - Descarga Masiva:
sat-suite/ws-descargaautentica y firma sus solicitudes SOAP con la FIEL.
Requisitos
- PHP
^8.3 ext-openssl(requerida)- Opcionales (
suggest):ext-gmpo, si no está,ext-bcmath. Sólo se usan para calcular el número de certificado cuando OpenSSL no entregaserialNumberHex. Sin ninguna de las dos se recurre abase_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:
| Entrada | Formatos aceptados |
|---|---|
| Llave privada | DER (el .key del SAT), PEM PKCS#8 en claro o cifrado, PEM PKCS#5 en claro o cifrado |
| Certificado | DER (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ón | Cuándo |
|---|---|
PrivateKeyFileNotReadableException / PublicKeyFileNotReadableException | El archivo existe pero no se puede leer |
PrivateKeyProcessingException | La llave no se puede abrir: contraseña incorrecta o contenido inválido |
PrivateKeyInfoParsingException | OpenSSL no puede leer los detalles de la llave |
PublicKeyInfoParsingException | El contenido no es un certificado X.509 válido |
FiscalCredentialsMismatchException | La 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()ygetCurp()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
PrivateKeysó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.