nginstack

Class: Crypto

@nginstack/engine/lib/crypto/Crypto~ Crypto

new Crypto()

Classe que agrupa funções de criptografia simétricas, geradores de chaves e de valores aleatórios. Não devem ser construídas instâncias de Crypto, devendo ser utilizados os métodos e propriedades estáticas desta classe.

Members

<static, constant> AES_CBC :string

Indica que deve ser utilizado o algoritmo de criptografia AES no modo CBC.

Deve ser utilizada uma chave de criptografia de 128, 192 ou 256 bits (16, 24 ou 32 bytes) e um vetor de inicialização de 16 bytes.

Type:
  • string

<static, constant> AES_ECB :string

Indica que deve ser utilizado o algoritmo de criptografia AES no modo ECB.

Deve ser utilizada uma chave de criptografia de 128, 192 ou 256 bits (16, 24 ou 32 bytes). No modo ECB, o vetor de inicialização deve ser vazio ou null.

Importante: o modo ECB é inerentemente inseguro e deve ser substituído por outros modos, preferencialmente o GCM.

Type:
  • string
Deprecated:
  • Yes

<static, constant> AES_GCM :string

Indica que deve ser utilizado o algoritmo de criptografia AES no modo GCM (Galois/Counter Mode).

Deve ser utilizada uma chave de criptografia de 128, 192 ou 256 bits (16, 24 ou 32 bytes) e um vetor de inicialização único (nonce) para cada operação de criptografia realizada com a mesma chave, preferencialmente de 12 bytes. O reuso do IV para uma mesma chave é uma falha grave e pode expor o conteúdo criptografado pela chave. Por esse motivo, IVs sequenciais únicos são preferíveis em relação aos IVs aleatórios. Eles permitem uma quantidade maior de operações seguras utilizando uma mesma chave de criptografia.

Type:
  • string

<static, constant> BLOWFISH_CBC :string

Indica que deve ser utilizado o algoritmo de criptografia Blowfish no modo CBC.

Type:
  • string

<static, constant> BLOWFISH_CFB :string

Indica que deve ser utilizado o algoritmo de criptografia Blowfish no modo CFB.

Type:
  • string

<static, constant> BLOWFISH_ECB :string

Indica que deve ser utilizado o algoritmo de criptografia Blowfish no modo ECB.

Type:
  • string

<static, constant> BLOWFISH_OFB :string

Indica que deve ser utilizado o algoritmo de criptografia Blowfish no modo OFB.

Type:
  • string

<static, constant> DES3_CBC :string

Indica que deve ser utilizado o algoritmo de criptografia Tripe DES no modo CBC.

Type:
  • string

<static, constant> DES3_CFB :string

Indica que deve ser utilizado o algoritmo de criptografia Tripe DES no modo CFB.

Type:
  • string

<static, constant> DES3_ECB :string

Indica que deve ser utilizado o algoritmo de criptografia Tripe DES no modo ECB.

Type:
  • string

<static, constant> DES3_OFB :string

Indica que deve ser utilizado o algoritmo de criptografia Tripe DES no modo OFB.

Type:
  • string

<static, constant> DES_CBC :string

Indica que deve ser utilizado o algoritmo de criptografia DES no modo CBC.

Type:
  • string

<static, constant> DES_CFB :string

Indica que deve ser utilizado o algoritmo de criptografia DES no modo CFB.

Type:
  • string

<static, constant> DES_ECB :string

Indica que deve ser utilizado o algoritmo de criptografia DES no modo ECB.

Type:
  • string

<static, constant> DES_OFB :string

Indica que deve ser utilizado o algoritmo de criptografia DES no modo OFB.

Type:
  • string

<static, constant> RC2_CBC :string

Indica que deve ser utilizado o algoritmo de criptografia RC2 no modo CBC.

Type:
  • string

<static, constant> RC2_CFB :string

Indica que deve ser utilizado o algoritmo de criptografia RC2 no modo CFB.

Type:
  • string

<static, constant> RC2_ECB :string

Indica que deve ser utilizado o algoritmo de criptografia RC2 no modo ECB.

Type:
  • string

<static, constant> RC2_OFB :string

Indica que deve ser utilizado o algoritmo de criptografia RC2 no modo OFB.

Type:
  • string

Methods

<static> decrypt(data, key [, cipher] [, iv])

Decodifica um conteúdo encriptado usando um algoritmo de criptografia simétrica.

Esta função trata as strings como se fossem uma sequência de bytes no formato conhecido por "Binary String", onde cada caractere da string representa um byte do conteúdo binário.

Para desencriptar conteúdos binários ou textos que não sejam ASCII, é recomendado o uso da função Crypto.decryptBytes. Para desencriptar strings, utilize a classe TextEncoder para converter uma string em um Uint8Array, tornando explícita a codificação adotada.

Parameters:
Name Type Argument Description
data string

O dado a ser decodificado.
key string | Uint8Array | ArrayBuffer

A chave de criptografia.
cipher string <optional>

O nome da cifra, sendo AES_ECB o valor padrão.
iv string | Uint8Array | ArrayBuffer <optional>

Vetor de inicialização
See:
Returns:

O dado decodificado.

Type
string

<static> decryptBytes(cipher, data, key, iv [, options])

Decodifica um conteúdo encriptado usando um algoritmo de criptografia simétrica.

Parameters:
Name Type Argument Description
cipher string

O nome da cifra, sendo AES_ECB o valor padrão.
data Uint8Array | ArrayBuffer

O dado a ser decodificado.
key Uint8Array | ArrayBuffer

A chave de criptografia.
iv Uint8Array | ArrayBuffer

Vetor de inicialização.
options DecryptOptions <optional>

Opções adicionais do algoritmo de criptografia.
See:
Returns:

O dado decodificado.

Type
Uint8Array

<static> encrypt(data, key [, cipher] [, iv])

Realiza uma operação de encriptação usando um algoritmo de criptografia simétrica. A encriptação dos dados é realizada em uma única chamada, sendo recomendado o uso deste método apenas para pequenos volumes de dados, que possam ser alocados totalmente em memória.

Esta função trata as strings como se fossem uma sequência de bytes no formato conhecido por "Binary String", onde cada caractere da string representa um byte do conteúdo binário. Para encriptar conteúdos binários ou textos que não sejam ASCII, é recomendado o uso da função Crypto.encryptBytes. Para encriptar strings, utilize a classe TextEncoder para converter uma string em um Uint8Array, tornando explícita a codificação adotada.

Parameters:
Name Type Argument Description
data string

O dado a ser encriptado.
key string | Uint8Array | ArrayBuffer

A chave de criptografia.
cipher string <optional>

O nome da cifra, sendo AES_ECB o valor padrão.
iv string | Uint8Array | ArrayBuffer <optional>

Vetor de inicialização.
See:
Returns:

O dado encriptado

Type
string

<static> encryptBytes(cipher, data, key, iv [, options])

Realiza uma operação de encriptação usando um algoritmo de criptografia simétrica. A encriptação dos dados é realizada em uma única chamada, sendo recomendado o uso deste método apenas para pequenos volumes de dados, que possam ser alocados totalmente em memória.

Parameters:
Name Type Argument Description
cipher string

Algoritmo de criptografia que deve ser utilizado.
data Uint8Array | ArrayBuffer

O dado a ser encriptado.
key Uint8Array | ArrayBuffer

A chave de criptografia.
iv Uint8Array | ArrayBuffer

Vetor de inicialização.
options EncryptOptions <optional>

Opções adicionais do algoritmo de criptografia.
See:
Returns:

O dado encriptado.

Type
Uint8Array

<static> encryptBytesWithAuth(cipher, data, key, iv [, options])

Realiza uma operação de encriptação usando um algoritmo de criptografia simétrica com autenticação de dados. A encriptação dos dados é realizada em uma única chamada, sendo recomendado o uso deste método apenas para pequenos volumes de dados, que possam ser alocados totalmente em memória.

Este método deve ser utilizado apenas com algoritmos que suportam a autenticação dos dados encriptados. Atualmente, apenas o algoritmo Crypto.AES_GCM é suportado.

Diferentemente dos métodos encrypt e encryptBytes, que retornam os dados criptografados, este método retorna um objeto contendo duas propriedades:

  • data: dados criptografados.
  • authTag: tag de autenticação que deverá ser informada ao método decryptBytes para verificar a autenticidade dos dados descriptografados.
Parameters:
Name Type Argument Description
cipher string

Algoritmo de criptografia que deve ser utilizado.
data Uint8Array | ArrayBuffer

O dado a ser encriptado.
key Uint8Array | ArrayBuffer

A chave de criptografia.
iv Uint8Array | ArrayBuffer

Vetor de inicialização.
options EncryptOptions <optional>

Opções adicionais do algoritmo de criptografia.
See:
Returns:

Dados encriptados e a tag de autenticação dos dados.

Type
Object
Example
const Crypto = require('@nginstack/engine/lib/crypto/Crypto.js');
const textEncoder = new TextEncoder();
const plainData = textEncoder.encode('Test');
const key = Crypto.randomBytes(32);
const iv = Crypto.randomBytes(12); // In production usage, use a 12 byte nonce
const aad = textEncoder.encode('auth data');
const result = Crypto.encryptBytesWithAuth(Crypto.AES_GCM, plainData, key, iv, {
  aad: aad
});

const cipherData = result.data;
const authTag = result.authTag;
const originalData = Crypto.decryptBytes(Crypto.AES_GCM, cipherData, key, iv, {
  aad: aad,
  authTag: authTag
});
new TextDecoder().decode(originalData); // => 'Test'

<static> randomBytes(size [, resultType])

Produz uma sequência pseudo-aleatória de bytes.

Parameters:
Name Type Argument Description
size number

Número de bytes.
resultType string <optional>

O tipo do resultado gerado por esta função. Os valores possíveis são "uint8array", "arraybuffer" e "binarystring". Caso não seja informado, será retornado um ArrayBuffer.
Returns:

Buffer contendo a sequência pseudo-aleatória de bytes gerada.

Type
ArrayBuffer | Uint8Array | string

<static> scrypt(password, salt, keylen [, params])

Scrypt é uma função de derivação de chaves projetada para exigir um esforço computacional alto com o objetivo de dificultar ataques de força bruta.

O salt informado deve ser aleatório e deve ter ao menos 16 bytes, conforme recomendações em NIST SP 800-132.

Quando valores do tipo string são informados em password e salt, eles são codificados em UTF-8.

Mais detalhes do algoritmo Scrypt podem ser observados em Wikipedia Scrypt.

Parameters:
Name Type Argument Description
password Uint8Array | ArrayBuffer | string

Palavra chave que será digerida pela função.
salt Uint8Array | ArrayBuffer | string

Sequência de bytes aleatórios que tem o objetivo de defender o algoritmo contra ataques de dicionário e de ataques pré-computados via "rainbow tables". O salt utilizado deve ser guardado juntamente com o resultado desta função.
keylen number

Tamanho em bytes da chave derivada que será gerada por esta função.
params Object <optional>

Parâmetros de esforço computacional do algoritmo Scrypt.

Properties
Name Type Argument Description
N number <optional>

Parâmetro que define o custo de CPU e memória. Deve ser uma potência de dois, maior que um. Valor padrão: 16384.
r number <optional>

Parâmetro que define o tamanho do bloco. Valor padrão: 8.
p number <optional>

Parâmetro que define a paralelização. Valor padrão: 1.
Returns:

Chave derivada gerada a partir da senha informada.

Type
Uint8Array