@mainframe/utils-crypto NPM

utils-crypto

Cryptographic primitives using sodium.

Installation

yarn add @mainframe/utils-crypto

Types

KeyPair

Object containing the public and secret parts of the key:

interface KeyPair {
  publicKey: Buffer
  secretKey: Buffer
}

EncryptedBox

interface EncryptedBox {
  cipher: Buffer
  nonce: Buffer
}

API

createBoxKeyPair()

Creates a KeyPair for encryption, using the optionally provided seed to generate it.

Arguments

seed?: Buffer

Returns KeyPair

createBoxPublicFromSign()

Converts a public signing key to an encryption one.

Arguments

signKey: Buffer

Returns public encryption key Buffer

createBoxKeyPairFromSign()

Converts a signing KeyPair to an encryption one.

Arguments

signPair: KeyPair

Returns encryption KeyPair

encryptBox()

Creates an EncryptedBox of the provided data using the fromSecretKey so it can be decrypted by the owner of the forPublicKey.

Arguments

data: Buffer
forPublicKey: Buffer
fromSecretKey: Buffer

Returns EncryptedBox

decryptBox()

Decrypts the provided EncryptedBox using the fromPublicKey and forSecretKey.

Arguments

encrypted: EncryptedBox
fromPublicKey: Buffer
forSecretKey: Buffer

Returns Buffer if decryption is successfull, null otherwise

createSecretBoxKey()

Creates a random secret box encryption key.

Returns Buffer with length SECRETBOX_KEYBYTES (crypto_secretbox_KEYBYTES)

createSecretBoxKeyFromPassword()

Creates a secret box encryption key from the provided password and other arguments. See hashPassword() for more details about the arguments values.

Arguments

password: Buffer
salt: Buffer
opslimit?: number, defaults to PASSWORDHASH_OPSLIMIT_SENSITIVE
memlimit?: number, defaults to PASSWORDHASH_MEMLIMIT_SENSITIVE
algorithm?: number

Returns Promise<Buffer>

encryptSecretBox()

Creates an EncryptedBox of the provided data using the key.

Arguments

data: Buffer
key: Buffer

Returns EncryptedBox

decryptSecretBox()

Decrypts the provided EncryptedBox using the key.

Arguments

data: Buffer
key: Buffer

Returns Buffer if decryption is successfull, null otherwise

hash()

Hashes the provided input to a buffer of the optional size, using the key if provided.

Arguments

input: Buffer
size?: number
key?: Buffer

Returns Buffer

hashStream()

Hashes the provided readable stream to a buffer of the optional size.

Arguments

stream: Readable
size?: number

Returns Promise<Buffer>

createPasswordHashSalt()

Creates a random salt for password hashing.

Returns Buffer with length PASSWORDHASH_SALT_BYTES (crypto_pwhash_SALTBYTES)

hashPassword()

Hashes the provided password to the hash buffer.

Arguments

hash: Buffer with length between PASSWORDHASH_BYTES_MIN (crypto_pwhash_BYTES_MIN) and PASSWORDHASH_BYTES_MAX (crypto_pwhash_BYTES_MAX)
password: Buffer
salt: Buffer with length PASSWORDHASH_SALT_BYTES (crypto_pwhash_SALTBYTES)
opslimit?: number between PASSWORDHASH_OPSLIMIT_MIN (crypto_pwhash_OPSLIMIT_MIN) and PASSWORDHASH_OPSLIMIT_MAX (crypto_pwhash_OPSLIMIT_MAX), defaults to PASSWORDHASH_OPSLIMIT_MODERATE (crypto_pwhash_OPSLIMIT_MODERATE)
memlimit?: number between PASSWORDHASH_MEMLIMIT_MIN (crypto_pwhash_MEMLIMIT_MIN) and PASSWORDHASH_MEMLIMIT_MAX (crypto_pwhash_MEMLIMIT_MAX), defaults to PASSWORDHASH_MEMLIMIT_MODERATE (crypto_pwhash_MEMLIMIT_MODERATE)
algorithm?: number, defaults to PASSWORDHASH_ALG_ARGON2ID13 (crypto_pwhash_ALG_ARGON2ID13)

Returns Promise<Buffer>

randomBytes()

Generates a buffer of random data having the provided size.

Arguments

size: number

Returns Buffer

secureRandomBytes()

Generates a secure buffer (protected memory) of random data having the provided size.

Arguments

size: number

Returns Buffer

createSecretStreamKey()

Creates a random secret stream encryption key.

Returns Buffer with length SECRETSTREAM_KEYBYTES (crypto_secretstream_xchacha20poly1305_KEYBYTES)

createEncryptStream()

Creates a Transform stream encrypting contents using the provided key. This transform will add the encryption headers of length SECRETSTREAM_HEADERBYTES (crypto_secretstream_xchacha20poly1305_HEADERBYTES) to the output stream.

Arguments

key: Buffer of length SECRETSTREAM_KEYBYTES

Returns Transform stream

createDecryptStream()

Creates a Transform stream decrypting contents using the provided key. This transform expects the encryption headers to be present in the first SECRETSTREAM_HEADERBYTES (crypto_secretstream_xchacha20poly1305_HEADERBYTES) bytes of the input stream, as added by the createEncryptStream() function.

Arguments