---
title: "PrivateKey y PublicKey"
description: "Maneja llaves privadas (.key) y públicas (.pem) para firmar datos, verificar firmas y cambiar contraseñas."
canonical_url: "https://nodecfdi.com/packages/credentials/usage/private-and-public-keys"
---

> Index of every page on this site: [llms.txt](https://nodecfdi.com/llms.txt)

Además de trabajar a través de [`Credential`](https://nodecfdi.com/packages/credentials/usage/credential), puedes utilizar las clases `PrivateKey` y `PublicKey` de manera individual.

## `PrivateKey` (Llave privada)

La clase `PrivateKey` soporta los siguientes formatos de entrada:

- **PKCS#8 DER** (el archivo `.key` binario cifrado tal como lo entrega el SAT, o sin cifrar).
- **PKCS#8 PEM** (`-----BEGIN ENCRYPTED PRIVATE KEY-----` o `-----BEGIN PRIVATE KEY-----`).
- **PKCS#5 PEM** (`-----BEGIN RSA PRIVATE KEY-----`, tanto plano como protegido con encabezados `Proc-Type` y `DEK-Info`).

### Abrir una llave privada

Si la llave privada no tiene contraseña (está desencriptada), pasa una cadena vacía `''` como `passPhrase`.

<code-group>

```ts [Desde archivo (Node.js)]
import { openPrivateKeyFile } from '@nodecfdi/credentials/node';

const privateKey = openPrivateKeyFile('/ruta/a/la/llave.key', '12345678a');
```

```ts [Desde contenido en memoria]
import { PrivateKey } from '@nodecfdi/credentials';

const privateKey = new PrivateKey(keyContents, '12345678a');
```

</code-group>

### Firmar datos con `PrivateKey`

El método `sign(data, algorithm?)` firma una cadena no vacía usando `'sha256'` por defecto (o cualquier algoritmo válido en [`Algorithm`](https://nodecfdi.com/packages/credentials/api-reference/exports-and-types)) y devuelve la firma como **cadena binaria**:

```ts [private-key-sign.ts]
import { Buffer } from 'node:buffer';

const signatureBinary = privateKey.sign('Cadena original a firmar', 'sha256');
const signatureBase64 = Buffer.from(signatureBinary, 'binary').toString('base64');
```

<warning>

Si intentas firmar una cadena vacía (`""`), `sign()` lanzará el error `Error: Cannot sign data: empty signature`.

</warning>

### Verificar pertenencia a un certificado

Puedes comprobar si una llave privada corresponde a un objeto [`Certificate`](https://nodecfdi.com/packages/credentials/usage/certificate) o a un certificado en texto PEM comparando sus módulos y exponentes RSA (`n` y `e`):

```ts [belongs-to.ts]
// Contra una instancia de Certificate
const matchesCert = privateKey.belongsTo(certificate);

// Contra una cadena PEM de certificado
const matchesPem = privateKey.belongsToPEMCertificate(certificate.pem());
```

### Cambiar o eliminar la contraseña (`changePassPhrase`)

El método `changePassPhrase(newPassPhrase)` genera una **nueva instancia** de `PrivateKey` en formato PKCS#8 PEM protegida con la nueva contraseña. Si pasas una cadena vacía `''`, genera una llave privada PKCS#8 PEM sin cifrar:

```ts [change-passphrase.ts]
// Recifrar con una nueva contraseña
const reEncryptedKey = privateKey.changePassPhrase('NuevaContraseñaSegura123');
console.log(reEncryptedKey.pem()); // -----BEGIN ENCRYPTED PRIVATE KEY----- ...

// Quitar la contraseña (llave en texto plano)
const plainKey = privateKey.changePassPhrase('');
console.log(plainKey.pem()); // -----BEGIN PRIVATE KEY----- ...
```

### Otros métodos de `PrivateKey`

<table>
<thead>
  <tr>
    <th>
      Método / Propiedad
    </th>
    
    <th>
      Retorno
    </th>
    
    <th>
      Descripción
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        pem()
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
    </td>
    
    <td>
      Contenido PEM de la llave privada.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        passPhrase()
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
    </td>
    
    <td>
      Contraseña utilizada al abrir la llave privada.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        publicKey()
      </code>
    </td>
    
    <td>
      <code>
        PublicKey
      </code>
    </td>
    
    <td>
      Obtiene la instancia <code>
        PublicKey
      </code>
      
       derivada de la llave privada.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        publicKeyContents()
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
    </td>
    
    <td>
      Contenido PEM de la llave pública asociada.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        numberOfBits()
      </code>
    </td>
    
    <td>
      <code>
        number
      </code>
    </td>
    
    <td>
      Longitud en bits del módulo RSA (ej. <code>
        2048
      </code>
      
      ).
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        type
      </code>
    </td>
    
    <td>
      <code>
        KeyTypeEnum
      </code>
    </td>
    
    <td>
      Tipo de llave (<code>
        privateKey.type.isRSA()
      </code>
      
      ).
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        isType(type)
      </code>
    </td>
    
    <td>
      <code>
        boolean
      </code>
    </td>
    
    <td>
      Comprueba el tipo de llave (ej. <code>
        privateKey.isType('RSA')
      </code>
      
      ).
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        callOnPrivateKey(fn)
      </code>
    </td>
    
    <td>
      <code>
        T
      </code>
    </td>
    
    <td>
      Ejecuta un callback recibiendo el objeto <code>
        forge.pki.rsa.PrivateKey
      </code>
      
       desencriptado (cacheado tras la primera apertura).
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        PrivateKey.convertDerToPem(contents, isEncrypted)
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
    </td>
    
    <td>
      Convierte contenido PKCS#8 DER binario a PKCS#8 PEM.
    </td>
  </tr>
</tbody>
</table>

---

## `PublicKey` (Llave pública)

La clase `PublicKey` representa una llave pública RSA. Puede construirse a partir de un archivo/texto PEM de llave pública (`-----BEGIN PUBLIC KEY-----`) o directamente desde el PEM de un certificado X.509 (`-----BEGIN CERTIFICATE-----`), o bien obtenerse desde `certificate.publicKey()` o `privateKey.publicKey()`.

### Abrir una llave pública

<code-group>

```ts [Desde archivo (Node.js)]
import { openPublicKeyFile } from '@nodecfdi/credentials/node';

const publicKey = openPublicKeyFile('/ruta/a/public_key.pem');
```

```ts [Desde contenido o Certificado]
import { PublicKey } from '@nodecfdi/credentials';

// Desde texto PEM (PUBLIC KEY o CERTIFICATE)
const publicKey = new PublicKey(publicKeyOrCertPem);

// O desde un Certificate / PrivateKey ya cargado:
const pubFromCert = certificate.publicKey();
const pubFromPriv = privateKey.publicKey();
```

</code-group>

### Verificar una firma con `PublicKey`

El método `verify(data, signature, algorithm?)` recibe el texto original, la firma como **cadena binaria** y el algoritmo (`'sha256'` por defecto):

```ts [public-key-verify.ts]
import { Buffer } from 'node:buffer';

const signatureBinary = Buffer.from(signatureBase64, 'base64').toString('binary');
const isValid = publicKey.verify('Cadena original a firmar', signatureBinary, 'sha256');

console.log('¿Es válida?:', isValid);
```

### Otros métodos de `PublicKey`

<table>
<thead>
  <tr>
    <th>
      Método / Propiedad
    </th>
    
    <th>
      Retorno
    </th>
    
    <th>
      Descripción
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        publicKeyContents()
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
    </td>
    
    <td>
      Contenido PEM de la llave pública (<code>
        -----BEGIN PUBLIC KEY-----
      </code>
      
      ).
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        numberOfBits()
      </code>
    </td>
    
    <td>
      <code>
        number
      </code>
    </td>
    
    <td>
      Número de bits de la llave RSA (ej. <code>
        2048
      </code>
      
      ).
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        type
      </code>
    </td>
    
    <td>
      <code>
        KeyTypeEnum
      </code>
    </td>
    
    <td>
      Tipo de llave (<code>
        publicKey.type.isRSA()
      </code>
      
      ).
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        isType(type)
      </code>
    </td>
    
    <td>
      <code>
        boolean
      </code>
    </td>
    
    <td>
      Comprueba si la llave es del tipo indicado (<code>
        'RSA'
      </code>
      
      ).
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        callOnPublicKey(fn)
      </code>
    </td>
    
    <td>
      <code>
        T
      </code>
    </td>
    
    <td>
      Ejecuta un callback recibiendo la instancia <code>
        forge.pki.rsa.PublicKey
      </code>
      
      .
    </td>
  </tr>
</tbody>
</table>

## Sitemap

See the full [sitemap](https://nodecfdi.com/sitemap.md) for all pages.
