@@ -18,10 +18,10 @@ Esta librería ha sido creada para poder trabajar con los archivos CSD y FIEL de
1818se simplifica el proceso de firmar, verificar firma y obtener datos particulares del archivo de certificado
1919así como de la llave pública.
2020
21- * El CSD (Certificado de Sello Digital) es utilizado para firmar Comprobantes Fiscales Digitales.
21+ - El CSD (Certificado de Sello Digital) es utilizado para firmar Comprobantes Fiscales Digitales.
2222
23- * La FIEL (o eFirma) es utilizada para firmar electrónicamente documentos (generalmente usando XML-SEC) y
24- está reconocida por el gobierno mexicano como una manera de firma legal de una persona física o moral.
23+ - La FIEL (o eFirma) es utilizada para firmar electrónicamente documentos (generalmente usando XML-SEC) y
24+ está reconocida por el gobierno mexicano como una manera de firma legal de una persona física o moral.
2525
2626
2727## Instalación
@@ -38,8 +38,8 @@ composer require phpcfdi/credentials
3838``` php
3939<?php declare(strict_types=1);
4040
41- $cerFile = 'fiel/certificado.cer'; // PEM o DER
42- $pemKeyFile = 'fiel/privatekey.pem'; // en formato PEM
41+ $cerFile = 'fiel/certificado.cer';
42+ $pemKeyFile = 'fiel/privatekey.key';
4343$passPhrase = '12345678a'; // contraseña para abrir la llave privada
4444
4545$fiel = PhpCfdi\Credentials\Credential::openFiles($cerFile, $pemKeyFile, $passPhrase);
@@ -63,10 +63,66 @@ echo $certificado->serialNumber()->bytes(), PHP_EOL; // número de serie del cer
6363```
6464
6565
66+ ## Acerca de los archivos de certificado y llave privada
67+
68+ Los archivos de certificado vienen en formato ` X.509 DER ` y los de llave privada en formato ` PKCS#8 DER ` .
69+ Ambos formatos no se pueden interpretar directamente en PHP (con ` ext-openssl ` ), sin embargo sí lo pueden hacer
70+ en el formatos compatible [ ` PEM ` ] ( https://en.wikipedia.org/wiki/Privacy-Enhanced_Mail ) .
71+
72+ Esta librería tiene la capacidad de hacer esta conversión internamente (sin ` openssl ` ), pues solo consiste en codificar
73+ a ` base64 ` , en renglones de 64 caracteres y con cabeceras específicas para certificado y llave privada.
74+
75+ De esta forma, para usar el certificado ` AAA010101AAA.cer ` o la llave privada ` AAA010101AAA.key ` provistos por
76+ el SAT, no es necesario convertirlos con ` openssl ` y la librería los detectará correctamente.
77+
78+
79+ ### Crear un objeto de certificado ` Certificate `
80+
81+ El objeto ` Certificate ` no se creará si contiene datos no válidos.
82+
83+ El SAT entrega el certificado en formato ` X.509 DER ` , por lo que internamente se puede convertir a ` X.509 PEM ` .
84+ También es frecuente usar el formato ` X.509 DER base64 ` , por ejemplo, en el atributo ` Comprobante@Certificado `
85+ o en las firmas XML, por este motivo, los formatos soportados para crear un objeto ` Certificate ` son
86+ ` X.509 DER ` , ` X.509 DER base64 ` y ` X.509 PEM ` .
87+
88+ - Para abrir usando un archivo local: ` $certificate = Certificate::openFile($filename); `
89+ - Para abrir usando una cadena de caracteres: ` $certificate = new Certificate($content); `
90+ - Si ` $content ` es un certificado en formato ` X.509 PEM ` con cabeceras ese se utiliza.
91+ - Si ` $content ` está totalmente en ` base64 ` , se interpreta como ` X.509 DER base64 ` y se formatea a ` X.509 PEM `
92+ - En otro caso, se interpreta como formato ` X.509 DER ` , por lo que se formatea a ` X.509 PEM ` .
93+
94+
95+ ### Crear un objeto de llave privada ` PrivateKey `
96+
97+ El objeto ` PrivateKey ` no se creará si contiene datos no válidos.
98+
99+ En SAT entrega la llave en formato ` PKCS#8 DER ` , por lo que internamente se puede convertir a ` PKCS#8 PEM `
100+ (con la misma contraseña) y usarla desde PHP.
101+
102+ Una vez abierta la llave también se puede cambiar o eliminar la contraseña, creando así un nuevo objeto ` PrivateKey ` .
103+
104+ - Para abrir usando un archivo local: ` $key = PrivateKey::openFile($filename, $passPhrase); `
105+ - Para abrir usando una cadena de caracteres: ` $key = new PrivateKey($content, $passPhrase); `
106+ - Si ` $content ` es una llave privada en formato ` PEM ` (` PKCS#8 ` o ` PKCS#5 ` ) se utiliza.
107+ - En otro caso, se interpreta como formato ` PKCS#8 DER ` , por lo que se formatea a ` PKCS#8 PEM ` .
108+
109+ Notas de tratamiento de archivos ` DER ` :
110+
111+ - Al convertir ` PKCS#8 DER ` a ` PKCS#8 PEM ` se determina si es una llave encriptada si se estableció
112+ una contraseña, si no se estableció se tratará como una llave plana (no encriptada).
113+ - No se sabe reconocer de forma automática si se trata de un archivo ` PKCS#5 DER ` por lo que este
114+ tipo de llave se deben convertir * manualmente* antes de intentar abrirlos, su cabecera es ` RSA PRIVATE KEY ` .
115+ - A diferencia de los certificados que pueden interpretar un formato ` DER base64 ` , la lectura de llave
116+ privada no hace esta distinción, si desea trabajar con un formato sin caracteres especiales use ` PEM ` .
117+
118+ Para entender más de los formatos de llaves privadas se puede consultar la siguiente liga:
119+ < https://github.com/kjur/jsrsasign/wiki/Tutorial-for-PKCS5-and-PKCS8-PEM-private-key-formats-differences >
120+
121+
66122## Compatilibilidad
67123
68124Esta librería se mantendrá compatible con al menos la versión con
69- [ soporte activo de PHP] ( http ://php.net/supported-versions.php) más reciente.
125+ [ soporte activo de PHP] ( https ://www. php.net/supported-versions.php) más reciente.
70126
71127También utilizamos [ Versionado Semántico 2.0.0] ( https://semver.org/lang/es/ ) por lo que puedes usar esta librería
72128sin temor a romper tu aplicación.
@@ -95,7 +151,7 @@ and licensed for use under the MIT License (MIT). Please see [LICENSE][] for mor
95151[ coverage ] : https://scrutinizer-ci.com/g/phpcfdi/credentials/code-structure/master/code-coverage/src/
96152[ downloads ] : https://packagist.org/packages/phpcfdi/credentials
97153
98- [ badge-source ] : http ://img.shields.io/badge/source-phpcfdi/credentials-blue?style=flat-square
154+ [ badge-source ] : https ://img.shields.io/badge/source-phpcfdi/credentials-blue?style=flat-square
99155[ badge-release ] : https://img.shields.io/github/release/phpcfdi/credentials?style=flat-square
100156[ badge-license ] : https://img.shields.io/github/license/phpcfdi/credentials?style=flat-square
101157[ badge-build ] : https://img.shields.io/travis/phpcfdi/credentials/master?style=flat-square
0 commit comments