SubtleCrypto
============

La interfaz **`SubtleCrypto`** de la Web Crypto API provee una serie de funciones criptográficas de bajo nivel. Se accede a ella a través de las propiedades `Crypto.subtle` disponible en un contexto de la ventana (via `Window.crypto`).

**Advertencia:** Esta API proporciona una serie de primitivos criptográficos de bajo nivel. Es muy fácil hacer un mal uso de ellos, y las trampas involucradas pueden ser muy sutiles.

Incluso suponiendo que se utilicen correctamente las funciones criptográficas básicas, la gestión segura de las claves y el diseño general del sistema de seguridad son extremadamente difíciles de conseguir correctamente, y generalmente son el dominio de expertos en seguridad especializados.

Los errores en el diseño e implementación del sistema de seguridad pueden hacer que la seguridad del sistema sea completamente ineficaz.

**Si no estás seguro de saber lo que estás haciendo, probablemente no deberías usar esta API.**

Descripción general
-------------------

Podemos dividir las funciones implementadas por esta API en dos grupos: funciones criptográficas y funciones de administración de claves.

### Funciones criptográficas

Estas son las funciones que puedes utilizar para implementar características de seguridad como la privacidad y la autenticación en un sistema. El API de `SubtleCrypto` proporciona las siguientes funciones criptográficas:

* `sign()` (en-US) y `verify()` (en-US): crea y verifica las firmas digitales.
* `encrypt()` y `decrypt()` (en-US): encripta y desencripta datos.
* `digest()`: crea un digest de longitud fija y resistente a colisiones de algunos datos.
### Funciones de gestión clave

Excepto para `digest()`, todas las funciones de criptografía de la API utilizan claves criptográficas. En la API `SubtleCrypto` una clave criptográfica se representa usando un objeto `CryptoKey` (en-US). Para realizar operaciones como firmado y encriptación, provee un objeto `CryptoKey` (en-US) a la función `sign()` (en-US) o `encrypt()`.

#### Generando y derivando claves

Las funciones `generateKey()` (en-US) y `deriveKey()` (en-US) ambos crean un nuevo objeto `CryptoKey` (en-US).

La diferencia es que `generateKey()` generará un nuevo valor clave distinto cada vez que lo llames, mientras que `deriveKey()` deriva una llave de algún material inicial de claves. Si proporcionas el mismo material de claves a dos llamadas separadas a `deriveKey()`, obtendrás dos objetos `CryptoKey` que tienen el mismo valor de base. Esto es útil si, por ejemplo, se quiere derivar una clave de cifrado de una contraseña y luego derivar la misma clave de la misma contraseña para descifrar los datos.

#### Importación y exportación de claves

Para hacer que las claves estén disponibles fuera de tu aplicación, necesitas exportar la clave, y para eso sirve `exportKey()` (en-US).Puedes elegir uno de varios formatos de exportación.

El inverso de `exportKey()` es `importKey()` (en-US). Puedes importar claves de otros sistemas, y la compatibilidad con formatos estándar como PKCS #8 y JSON Web Key te ayudan a hacer esto. La función `exportKey()` exporta la clave en un formato no codificado.

Si la clave es sensible, deberías usar `wrapKey()` (en-US), que exporta la clave y luego la encripta usando otra clave; el API llama a una "llave de envoltura".

El inverso de `wrapKey()` es `unwrapKey()` (en-US), que descifra y luego importa la llave.

#### Almacenamiento de claves

Epecification objetos `CryptoKey` pueden ser almacenados usando el structured clone algorithm (en-US), lo que significa que puedes almacenarlos y recuperarlos usando las API de almacenamiento web estándar. La especificación espera que la mayoría de los desarrolladores usen el IndexedDB API para almacenar objetos `CryptoKey`.

### Algoritmos Suportados

Las funciones criptográficas que proporciona la Web Crypto API pueden ser realizadas por uno o más *algoritmos criptográficos* diferentes: El argumento `algorithm` de la función indica el algoritmo a utilizar. Algunos algoritmos necesitan parámetros adicionales: en estos casos el argumento `algorithm` es un objeto de diccionario que incluye los parámetros adicionales.

En el cuadro que figura a continuación se resume qué algoritmos son adecuados para cada operación criptográfica:

|  | sign() (en-US)verify() (en-US) | encrypt()decrypt() (en-US) | digest() | deriveBits() (en-US)deriveKey() (en-US) | wrapKey() (en-US)unwrapKey() (en-US) |
| --- | --- | --- | --- | --- | --- |
| RSASSA-PKCS1-v1\_5 | ✓ |  |  |  |  |
| RSA-PSS | ✓ |  |  |  |  |
| ECDSA | ✓ |  |  |  |  |
| HMAC | ✓ |  |  |  |  |
| RSA-OAEP |  | ✓ |  |  | ✓ |
| AES-CTR |  | ✓ |  |  | ✓ |
| AES-CBC |  | ✓ |  |  | ✓ |
| AES-GCM |  | ✓ |  |  | ✓ |
| SHA-1 |  |  | ✓ |  |  |
| SHA-256 |  |  | ✓ |  |  |
| SHA-384 |  |  | ✓ |  |  |
| SHA-512 |  |  | ✓ |  |  |
| ECDH |  |  |  | ✓ |  |
| HKDF |  |  |  | ✓ |  |
| PBKDF2 |  |  |  | ✓ |  |
| AES-KW |  |  |  |  | ✓ |

Propiedades
-----------

*Esta interfaz no hereda ni implementa ninguna propiedad.*

Métodos
-------

*Esta interfaz no hereda ningún método.*

`SubtleCrypto.encrypt()`

Retorna un `Promise` que se completa con los datos codificados correspondientes al texto sin cifrar, el algoritmo y la clave dados como parámetros.

`SubtleCrypto.decrypt()` (en-US)

Retorna un `Promise` que se completa con los datos claros correspondientes al texto encriptado, el algoritmo y la clave dados como parámetros.

`SubtleCrypto.sign()` (en-US)

Retorna un `Promise` que se completa con la firma correspondiente al texto, algoritmo y clave dados como parámetros.

`SubtleCrypto.verify()` (en-US)

Retorna un `Promise` que se completa con un valor `Boolean` indicando si la firma dada como parámetro coincide con el texto, el algoritmo y la clave que también se dan como parámetros.

`SubtleCrypto.digest()`

Retorna un `Promise` que se completa con digest generado a partir del algoritmo y el texto dados como parámetros.

`SubtleCrypto.generateKey()` (en-US)

Retorna un `Promise` que se completa con un recién generado `CryptoKey` (en-US), para algoritmos simétricos, o un `CryptoKeyPair` (en-US), que contiene dos claves recién generadas, para algoritmos asimétricos. Estas coincidirán con el algoritmo, usos y extraíbles dados como parámetros.

`SubtleCrypto.deriveKey()` (en-US)

Retorna un `Promise` que se completa con un recién generado `CryptoKey` (en-US) derivado de la clave maestra y el algoritmo específico dados como parámetros.

`SubtleCrypto.deriveBits()` (en-US)

Retorna un `Promise` que se completa con un recién generado buffer de bits pseudo-aleatorios derivado de la clave maestra y el algoritmo específico dados como parámetros.

`SubtleCrypto.importKey()` (en-US)

Retorna un `Promise` que se completa con un `CryptoKey` (en-US) correspondiente al formato, el algoritmo, los datos clave en bruto, los usos y la extraíbilidad dados como parámetros.

`SubtleCrypto.exportKey()` (en-US)

Retorna un `Promise` que se completa con un buffer que contiene la clave en el formato solicitado.

`SubtleCrypto.wrapKey()` (en-US)

Retorna un `Promise` que se completa con una llave simétrica envuelta para su uso (transferencia y almacenamiento) en entornos inseguros. La llave envuelta coincide con el formato especificado en los parámetros dados, y la envoltura se hace con la llave envuelta dada, usando el algoritmo especificado.

`SubtleCrypto.unwrapKey()` (en-US)

Retorna un `Promise` que se completa con un `CryptoKey` (en-US) correspondiente a la llave envuelta dada en el parámetro.

Especificaciones
----------------

| Specification |
| --- |
| Web Cryptography API # subtlecrypto-interface |

Compatibilidad con navegadores
------------------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

Ver también
-----------

* `Crypto` and `Crypto.subtle`.
* Crypto 101: un curso de introducción a la criptografía (en inglés).