@abubu/kaos 中文文档教程

Question

Ϗɐ⊕????

Kaos 是一个简单但高效的（希望难以破解） 数据加密器。

• It is tiny with no dependencies
• It implements Node.js' Transform streams
• It enables encryption / decryption by chunks
• Two consecutive encryptions with the same unsalted key generates different outputs

API

Stream.Transform encrypt (key, offset = undefined)

encrypt API 接受两个参数并返回一个 Stream.Transform 实例。

第一个参数是加密密钥，它可以是：

• A string
• A Buffer instance
• A Stream.Readable instance
• A key instance (used for chunks, see below)

如果使用了不受支持的类型，则Error 消息 Unsupported key type 被抛出。

当通过块 （参见示例） 完成加密时，必须仅使用第二个参数。

// Simple encryption

const { promisify } = require('util')
const pipeline = promisify(require('stream').pipeline)
const { createReadStream, createWriteStream } = require('fs')
const { encrypt } = require('@abubu/kaos')

pipeline(
  createReadStream('file to encrypt'),
  encrypt('my secret key'),
  createWriteStream('encrypted file')
)
  .then(() => console.log('Encryption succeeded.'))
  .catch(() => console.log('Encryption failed.'))

Encryption by chunks

如果要加密的数据按块可用（例如：通过数据包上传），则所有部分都必须使用相同的加盐密钥。 必须为所有但第一个块指定每个块的起始偏移量。

// Chunks encryption

const { promisify } = require('util')
const pipeline = promisify(require('stream').pipeline)
const { createReadStream, createWriteStream } = require('fs')
const { key, encrypt } = require('@abubu/kaos')

const myKey = key('my secret key')

myKey.salt()
  // mySaltedKey must be reused for each chunks
  .then(mySaltedKey => pipeline(
    createReadStream('file to encrypt', { start: 0, end: 50 }),
    encrypt(mySaltedKey), // /!\ No offset fo the first chunk
    createWriteStream('encrypted file')
  ))
  .then(() => pipeline(
    createReadStream('file to encrypt', { start: 51 }),
    encrypt(mySaltedKey, 51), // Start offset of this chunk
    createWriteStream('encrypted file', { flags: 'r+', start: 51 })
  ))
  .then(() => console.log('Encryption succeeded.'))
  .catch(() => console.log('Encryption failed.'))

Stream.Transform decrypt (key, range = undefined)

decrypt API 接受两个参数并返回一个 Stream.Transform 实例。

第一个参数是加密密钥，类似于 encrypt API。

仅当解密由块（参见示例） 完成时，才必须使用第二个参数。

注意：解密算法不验证数据是否被正确解密。

// Simple decryption

const { promisify } = require('util')
const pipeline = promisify(require('stream').pipeline)
const { createReadStream, createWriteStream } = require('fs')
const { decrypt } = require('@abubu/kaos')

pipeline(
  createReadStream('file to decrypt'),
  decrypt('my secret key'),
  createWriteStream('decrypted file')
)
  .then(() => console.log('Decryption succeeded.'))
  .catch(() => console.log('Decryption failed.'))

Decryption by chunks

当只有消息的特定部分 必须解码时，key API 提供有关从加密数据加载的范围 的信息。

第一步是阅读key salt。 加盐后，密钥可以重复使用 来解码相同加密数据 的其他范围。

// Chunks decryption

const { promisify } = require('util')
const pipeline = promisify(require('stream').pipeline)
const { createReadStream, createWriteStream } = require('fs')
const { key, decrypt } = require('@abubu/kaos')

const myKey = key('my secret key')

myKey.saltRange()
  .then(range => myKey.salt(createReadStream('file to decrypt', range)))
  // To decode bytes between 1000 and 1100 (inclusively)
  .then(saltedKey => saltedKey.byteRange(1000, 1100))
  .then(range => pipeline(
    createReadStream('file to decrypt', range),
    decrypt(saltedKey, range),
    createWriteStream('decrypted byte range')
  ))
  .then(() => console.log('Decryption succeeded.'))
  .catch(() => console.log('Decryption failed.'))