-
Notifications
You must be signed in to change notification settings - Fork 4
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
docs: 📝 update readme to remove old documentation of library and add …
…new link for doc
- Loading branch information
1 parent
a86fc87
commit be72dee
Showing
1 changed file
with
6 additions
and
140 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -31,145 +31,11 @@ proceso de firmar, verificar firma y obtener datos particulares del archivo de c | |
| Con esta librería no es necesario convertir los archivos generados por el SAT a otro formato, se pueden utilizar tal y | ||
| como el SAT los entrega. | ||
|
|
||
| Esta librería ha sido inspirada por la versión para php <https://github.com/phpcfdi/credentials> | ||
| Esta librería ha sido inspirada por la versión para php https://github.com/phpcfdi/credentials | ||
|
|
||
| ## Instalación | ||
| ## Documentación | ||
|
|
||
| ### NPM | ||
|
|
||
| ```bash | ||
| npm i @nodecfdi/credentials --save | ||
| ``` | ||
|
|
||
| ### YARN | ||
|
|
||
| ```bash | ||
| yarn add @nodecfdi/credentials | ||
| ``` | ||
|
|
||
| ### PNPM | ||
|
|
||
| ```bash | ||
| pnpm add @nodecfdi/credentials | ||
| ``` | ||
|
|
||
| ### CDN - Browser | ||
|
|
||
| Usa la versión mas reciente publicada cambiando `<latest-version>` por la última versión. Por ejemplo [email protected]/dist... | ||
|
|
||
| ```html | ||
| <script src="https://unpkg.com/@nodecfdi/credentials@<latest-version>/dist/credentials.global.js"></script> | ||
| ``` | ||
|
|
||
| ## Ejemplo básico de uso | ||
|
|
||
| ```ts | ||
| import * as fs from 'fs'; | ||
| import { Credential } from '@nodecfdi/credentials'; | ||
| // se puede mandar el path o el contenido | ||
| const certFile = fs.readFileSync('fiel/certificado.cer', 'binary'); | ||
| const keyFile = fs.readFileSync('fiel/privatekey.key', 'binary'); | ||
| const passPhrase = '12345678a'; // contraseña para abrir la llave privada | ||
| const fiel = Credential.create(certFile, keyFile, passPhrase); | ||
| const sourceString = 'texto a firmar'; | ||
| // alias de privateKey/sign/verify | ||
| const signature = fiel.sign(sourceString); | ||
| console.log(signature); | ||
| // alias de certificado/publicKey/verify | ||
| const verify = fiel.verify(sourceString, signature); | ||
| console.log(verify); // boolean(true) | ||
| // objeto certificado | ||
| const certificado = fiel.certificate(); | ||
| console.log(certificado.rfc()); // el RFC del certificado | ||
| console.log(certificado.legalName()); // el nombre del propietario del certificado | ||
| console.log(certificado.branchName()); // el nombre de la sucursal (en CSD, en FIEL está vacía) | ||
| console.log(certificado.serialNumber().bytes()); // número de serie del certificado | ||
| ``` | ||
|
|
||
| Para ver un ejemplo en browser checa la carpeta examples. | ||
|
|
||
| ## Acerca de los archivos de certificado y llave privada | ||
|
|
||
| Los archivos de certificado vienen en formato `X.509 DER` y los de llave privada en formato `PKCS#8 DER`. | ||
|
|
||
| ### Crear un objeto de certificado `Certificate` | ||
|
|
||
| El objeto `Certificate` no se creará si contiene datos no válidos. | ||
|
|
||
| El SAT entrega el certificado en formato `X.509 DER`, por lo que internamente se puede convertir a `X.509 PEM`. | ||
| También es frecuente usar el formato `X.509 DER base64`, por ejemplo, en el atributo `Comprobante@Certificado` | ||
| o en las firmas XML, por este motivo, los formatos soportados para crear un objeto `Certificate` son | ||
| `X.509 DER`, `X.509 DER base64` y `X.509 PEM`. | ||
|
|
||
| - Para abrir usando un archivo local: `const certificate = Certificate.openFile(filename);` | ||
| - Para abrir usando una cadena de caracteres: `const certificate = new Certificate(content);` | ||
| - Si `content` es un certificado en formato `X.509 PEM` con cabeceras ese se utiliza. | ||
| - Si `content` está totalmente en `base64`, se interpreta como `X.509 DER base64` y se formatea a `X.509 PEM` | ||
| - En otro caso, se interpreta como formato `X.509 DER`, por lo que se formatea a `X.509 PEM`. | ||
|
|
||
| ### Crear un objeto de llave privada `PrivateKey` | ||
|
|
||
| El objeto `PrivateKey` no se creará si contiene datos no válidos. | ||
|
|
||
| En SAT entrega la llave en formato `PKCS#8 DER`, por lo que internamente se puede convertir a `PKCS#8 PEM` | ||
| (con la misma contraseña). | ||
|
|
||
| Una vez abierta la llave también se puede cambiar o eliminar la contraseña, creando así un nuevo objeto `PrivateKey`. | ||
|
|
||
| - Para abrir usando un archivo local: `const key = PrivateKey.openFile(filename, passPhrase);` | ||
| - Para abrir usando una cadena de caracteres: `const key = new PrivateKey(content, passPhrase);` | ||
| - Si `content` es una llave privada en formato `PEM` (`PKCS#8` o `PKCS#5`) se utiliza. | ||
| - En otro caso, se interpreta como formato `PKCS#8 DER`, por lo que se formatea a `PKCS#8 PEM`. | ||
|
|
||
| Notas de tratamiento de archivos `DER`: | ||
|
|
||
| - Al convertir `PKCS#8 DER` a `PKCS#8 PEM` se determina si es una llave encriptada si se estableció | ||
| una contraseña, si no se estableció se tratará como una llave plana (no encriptada). | ||
| - No se sabe reconocer de forma automática si se trata de un archivo `PKCS#5 DER` por lo que este | ||
| tipo de llave se deben convertir _manualmente_ antes de intentar abrirlos, su cabecera es `RSA PRIVATE KEY`. | ||
| - A diferencia de los certificados que pueden interpretar un formato `DER base64`, la lectura de llave | ||
| privada no hace esta distinción, si desea trabajar con un formato sin caracteres especiales use `PEM`. | ||
|
|
||
| Para entender más de los formatos de llaves privadas se puede consultar la siguiente liga: | ||
| <https://github.com/kjur/jsrsasign/wiki/Tutorial-for-PKCS5-and-PKCS8-PEM-private-key-formats-differences> | ||
|
|
||
| ## Leer y exportar archivos PFX | ||
|
|
||
| Esta librería soporta obtener el objeto `Credential` desde un archivo PFX (PKCS #12) y vicerversa. | ||
|
|
||
| Para exportar el archivo PFX en NodeJS: | ||
|
|
||
| ```ts | ||
| import { Credential, PfxExporter } from '@nodecfdi/credentials'; | ||
|
|
||
| const credential = Credential.openFiles( | ||
| 'certificate/certificado.cer', | ||
| 'certificate/private-key.key', | ||
| 'password', | ||
| ); | ||
| const pfxExporter = new PfxExporter(credential); | ||
|
|
||
| // Crea el binary string usando la contraseña dada | ||
| const pfxContents = pfxExporter.export('pfx-passphrase'); | ||
|
|
||
| // Crea un base64String usando la contraseña dada | ||
| const pfxContentsb64 = pfxExporter.exportToBase64('pfx-passphrase'); | ||
| ``` | ||
|
|
||
| Para leer el archivo PFX y obtener un objeto `Credential`: | ||
|
|
||
| ```ts | ||
| import { PfxReader } from '@nodecfdi/credentials'; | ||
|
|
||
| // Crea un objeto Credential dado el contenido de un archivo pfx | ||
| const credential = PfxReader.createCredentialFromContents( | ||
| 'contenido-del-archivo', | ||
| 'pfx-passphrase', | ||
| ); | ||
|
|
||
| // Crea un objeto Credential dada la ruta de un archivo pfx | ||
| const credential = PfxReader.createCredentialsFromFile('pfxFilePath', 'pfx-passphrase'); | ||
| ``` | ||
| La documentación está disponible en el sitio web [NodeCfdi](https://nodecfdi.com/librarys/credentials/gettting-started) | ||
|
|
||
| ## Soporte | ||
|
|
||
|
|
@@ -192,13 +58,13 @@ Las contribuciones con bienvenidas. Por favor lee [CONTRIBUTING][] para más det | |
|
|
||
| The `@nodecfdi/credentials` library is copyright © [NodeCfdi](https://github.com/nodecfdi) - [OcelotlStudio](https://ocelotlstudio.com) and licensed for use under the MIT License (MIT). Please see [LICENSE][] for more information. | ||
|
|
||
| [contributing]: https://github.com/nodecfdi/credentials/blob/main/CONTRIBUTING.md | ||
| [contributing]: https://github.com/nodecfdi/.github/blob/main/docs/CONTRIBUTING.md | ||
| [changelog]: https://github.com/nodecfdi/credentials/blob/main/CHANGELOG.md | ||
| [source]: https://github.com/nodecfdi/credentials | ||
| [node-version]: https://www.npmjs.com/package/@nodecfdi/credentials | ||
| [discord]: https://discord.gg/AsqX8fkW2k | ||
| [release]: https://www.npmjs.com/package/@nodecfdi/credentials | ||
| [license]: https://github.com/nodecfdi/credentials/blob/main/LICENSE | ||
| [license]: https://github.com/nodecfdi/credentials/blob/main/LICENSE.md | ||
| [build]: https://github.com/nodecfdi/credentials/actions/workflows/build.yml?query=branch:main | ||
| [reliability]: https://sonarcloud.io/component_measures?id=nodecfdi_credentials&metric=Reliability | ||
| [maintainability]: https://sonarcloud.io/component_measures?id=nodecfdi_credentials&metric=Maintainability | ||
|
|
@@ -210,7 +76,7 @@ The `@nodecfdi/credentials` library is copyright © [NodeCfdi](https://github.co | |
| [badge-discord]: https://img.shields.io/discord/459860554090283019?logo=discord | ||
| [badge-release]: https://img.shields.io/npm/v/@nodecfdi/credentials.svg?logo=npm | ||
| [badge-license]: https://img.shields.io/github/license/nodecfdi/credentials.svg?logo=open-source-initiative | ||
| [badge-build]: https://img.shields.io/github/actions/workflow/status/nodecfdi/credentials/build.yml?branch=main&logo=github-actions | ||
| [badge-build]: https://img.shields.io/github/actions/workflow/status/nodecfdi/credentials/build.yml?branch=main | ||
| [badge-reliability]: https://sonarcloud.io/api/project_badges/measure?project=nodecfdi_credentials&metric=reliability_rating | ||
| [badge-maintainability]: https://sonarcloud.io/api/project_badges/measure?project=nodecfdi_credentials&metric=sqale_rating | ||
| [badge-coverage]: https://img.shields.io/sonar/coverage/nodecfdi_credentials/main?logo=sonarcloud&server=https%3A%2F%2Fsonarcloud.io | ||
|
|
||