ara-crypto

Cryptographic functions used in ARA modules for Node.js.

Status

This project is in active development.

Stability

> Stability: 1 - Experimental. This feature is still under > active development and subject to non-backwards compatible changes, or even > removal, in any future version. Use of the feature is not recommended > in production environments. Experimental features are not subject to > the Node.js Semantic Versioning model.

Installation

$ npm install arablocks/ara-crypto

Usage

const crypto = require('ara-crypto')

const message = Buffer.from('message')
const bytes = crypto.randomBytes(32)
const hash = crypto.blake2b(message)
const { publicKey, secretKey } = crypto.keyPair(hash) // hash seed optional
const signature = crypto.sign(message, secretKey)
const verified = crypto.verify(signature, message, publicKey)
const buffer = crypto.uint64.encode(80)
const number = crypto.uint64.decode(buffer) // 80

API

Most of the functions exported by this module will check for input correctness. If given incorrect input, a function will throw a TypeError with a message describing the error. In most functions, inputs should always be a Buffer.

• crypto.randomBytes(size)
• crypto.blake2b(data)
• crypto.discoveryKey([seed][, size][, key])
• crypto.keyPair([seed])
• crypto.sign(message, secretKey)
• crypto.verify(signature, message, publicKey)
• crypto.curve25519.keyPair([seed])
• crypto.curve25519.shared(secretKey, publicKey)
• crypto.ed25519.keyPair([seed])
• crypto.ed25519.sign(message, secretKey)
• crypto.ed25519.verify(signature, message, publicKey)
• crypto.uint64.encode(number)
• crypto.uint64.decode(buffer)
• crypto.box(buffer, opts)
• crypto.unbox(buffer, opts)
• crypto.createBoxStream(opts)
• crypto.createUnboxStream(opts)
• crypto.auth(message, key)
• crypto.auth.verify(mac, message, key)
• crypto.kx.keyPair([seed])
• crypto.kx.client(opts)
• crypto.kx.server(opts)
• crypto.seal(message, opts)
• crypto.seal.open(message, opts)
• crypto.shash(message, secretKey)

crypto.randomBytes(size)

> Stability: 2 - Stable

Generate a buffer of random bytes where size is an unsigned integer greater than 0. This function will throw a TypeError if given incorrect input. This function calls sodium.randombytes_buf internally.

const bytes = crypto.randomBytes(32)

crypto.blake2b(buffer[, size])

> Stability: 2 - Stable

Generates a blake2b digest hash from input of a given size defaulting to 32 bytes. This function calls crypto_generichash_batch internally.

const hash = crypto.blake2b(Buffer.from("message"))

crypto.discoveryKey([seed][, size][, key])

> Stability: 2 - Stable

Generate a discovery key useful for network keys. This function calls crypto_generichash internally.

const { publicKey, secretKey } = crypto.keyPair()
const discoveryKey = crypto.discoveryKey(publicKey)

crypto.keyPair([seed])

An alias for crypto.ed25519.keyPair.

crypto.sign(message, secretKey)

An alias for crypto.ed25519.sign.

crypto.verify(signature, message, publicKey)

An alias for crypto.ed25519.verify.

crypto.curve25519.keyPair([seed])

> Stability: 2 - Stable

Generate a Curve25519 public and secret key pair from an optional seed buffer. This function calls crypto_sign_seed_keypair and crypto_sign_keypair internally and converts to Curve25519 key pair calling crypto_sign_ed25519_pk_to_curve25519 and crypto_sign_ed25519_sk_to_curve25519.

const seed = crypto.randomBytes(32)
const { publicKey, secretKey } = crypto.curve25519.keyPair(seed)

crypto.curve25519.shared(secretKey, publicKey)

Compute a shared key from a 32 byte secret key and a 32 byte public key. If keys are larger than 32 bytes, they will be truncated when read.

const alice = crypto.curve25519.keyPair()
const bob = crypto.curve25519.keyPair()
const shared = crypto.curve25519.shared(alice.secretKey, bob.publicKey)

crypto.ed25519.keyPair([seed])

> Stability: 2 - Stable

Generate a public and secret key pair from an optional seed buffer. This function will throw a TypeError if given incorrect input. This function calls crypto_sign_seed_keypair and crypto_sign_keypair internally.

const seed = crypto.randomBytes(32)
const { publicKey, secretKey } = crypto.keyPair(seed)

crypto.ed25519.sign(message, secretKey)

> Stability: 2 - Stable

Sign a message buffer with a secret key buffer. This function will throw a TypeError if given incorrect input. This function calls crypto_sign_detached on a buffer of size crypto_sign_BYTES.

const { publicKey, secretKey } = crypto.keyPair()
const signature = crypto.sign(Buffer.from("hello"), secretKey)

crypto.ed25519.verify(signature, message, publicKey)

> Stability: 2 - Stable

Verify signature for a message signed with a given public key. This function will throw a TypeError if given incorrect input. This function calls crypto_sign_verify_detached internally.

const { publicKey, secretKey } = crypto.keyPair()
const message = Buffer.from("hello")
const signature = crypto.sign(message, secretKey)
const verified = crypto.verify(signature, message, publicKey)
if (verified) {
  // message was signed with secret key (corresponding
  // to the given public key) that generated the given signature
}

crypto.uint64.encode(value, size)

> Stability: 2 - Stable

Encode an unsigned 64-bit big endian number into a buffer of a given size defaulting to 8 bytes.

const buffer = crypto.uint64.encode(80)

crypto.uint64.decode(buffer)

> Stability: 2 - Stable

Decode an unsigned 64-bit big endian buffer into a number

const buffer = crypto.uint64.encode(80)
const number = crypto.uint64.decode(buffer) // 80

crypto.box(buffer, opts)

> Stability: 1 - Experimental

"Boxes", or encrypts, a buffer from a 32 byte encryption key and a 24-byte nonce.

const key = Buffer.alloc(32); key.fill('SECRET!KEY')
const nonce = crypto.randomBytes(24)
const secret = Buffer.concat([ key, nonce ])
const buffer = Buffer.from('hello!')
const boxed = crypto.box(buffer, { secret }) // or crypto.box(buffer, { nonce, key })
console.log(boxed) // 

crypto.unbox(buffer, opts)

> Stability: 1 - Experimental

"Unboxes" or decrypts a buffer from a 32-byte encryption key and a 24-byte nonce.

const key = Buffer.alloc(32); key.fill('SECRET!KEY')
const nonce = crypto.randomBytes(24)
const secret = Buffer.concat([ key, nonce ])
const buffer = Buffer.from('hello!')
const boxed = crypto.box(buffer, { secret }) // or crypto.box(buffer, { nonce, key })
const unboxed = crypto.unbox(boxed, { secret }) // or crypto.unbox(boxed, { nonce, key })
console.log(unboxed) // hello!

crypto.createBoxStream(opts)

> Stability: 1 - Experimental

Creates a transform stream that "boxes" messages written to it.

const key = Buffer.alloc(32); key.fill('SECRET!KEY')
const nonce = crypto.randomBytes(24)
const secret = Buffer.concat([ key, nonce ])
const buffer = Buffer.from('hello!')
const stream = crypto.createBoxStream({ secret }) // or crypto.createBoxStream({ nonce, key })
stream.on('data', (chunk) => console.log(chunk)) // cipher text
stream.write(buffer)

crypto.createUnboxStream(opts)

> Stability: 1 - Experimental

Creates a transform stream that "unboxes" messages written to it.

const key = Buffer.alloc(32); key.fill('SECRET!KEY')
const nonce = crypto.randomBytes(24)
const secret = Buffer.concat([ key, nonce ])
const buffer = Buffer.from('hello!')
const stream = crypto.createUnboxStream({ secret }) // or crypto.createUnboxStream({ nonce, key })
const boxed = crypto.box(buffer, { secret })
stream.on('data', (chunk) => console.log(chunk)) // hello!
stream.write(boxed)

crypto.auth(message, key)

> Stability: 2 - Stable

Generates and returns a message authentication code (MAC) for a given message and secret key.

const message = Buffer.from('hello')
const key = crypto.randomBytes(32)
const mac = auth(message, key)

Secret + Nonce based message authentication codes:

const message = Buffer.from('hello')
const secret = getSecretFromSomeWhere()
const nonce = crypto.randomBytes(32)
const key = crypto.blake2b(Buffer.concat([secret, nonce]))
const mac = auth(message, key)

crypto.auth.verify(mac, message, key)

> Stability: 2 - Stable

Verifies the authenticity of a message with a given message authentication code (MAC) and secret key.

const message = Buffer.from('hello')
const key = crypto.randomBytes(32)
const mac = auth(message, key)

if (false === verify(mac, message, key)) {
  throw new Error('Message forged!')
}

crypto.kx.keyPair([seed])

> Stability: 2 - Stable

Generates a key exchange key pair.

const seed = crypto.randomBytes(32)
const kp = crypto.kx.keyPair(seed)

crypto.kx.client(opts)

> Stability: 1 - Experimental

Compute sender (tx) and receiver (rx) session keys for a client based on a server's public key.

const serverPublicKey = getServerPublicKey()
const { publicKey, secretKey } = getClientKeyPair()
const client = kx.client({
  publicKey,
  secretKey,
  server: { publicKey: serverPublicKey }
})

crypto.kx.server(opts)

> Stability: 1 - Experimental

Compute sender (tx) and receiver (rx) session keys for a server based on a client's public key.

const clientPublicKey = getClientPublicKey()
const { publicKey, secretKey } = getServerKeyPair()
const server = kx.server({
  publicKey,
  secretKey,
  client: { publicKey: clientPublicKey }
})

crypto.kdf.keygen(key)

> Stability: 2 - Stable

Generate a master ("secret") key. This function calls crypto_kdf_keygen internally.

const key = crypto.kdf.keygen()

crypto.kdf.init(key, buffer)

> Stability: 2 - Stable

Initializes key and buffer with null subkey to return an object to update.

const buffer = Buffer.from('examples')
const key = crypto.kdf.keygen()
const ctx = crypto.kdf.init(key, buffer) // buffer optional

crypto.kdf.update(ctx, id)

> Stability: 2 - Stable

Updates context subkey from an ID. This function calls crypto_kdf_derive internally.

const buffer = Buffer.from('examples')
const key = crypto.kdf.keygen()
const ctx = crypto.kdf.init(key, buffer)
const subkey = crypto.kdf.update(ctx, 1)

crypto.kdf.final(ctx)

> Stability: 2 - Stable

Finalizes context by setting ctx.subkey to null.

const buffer = Buffer.from('examples')
const key = crypto.kdf.keygen()
const ctx = crypto.kdf.init(key, buffer)
const subkey = crypto.kdf.final(ctx)

crypto.kdf.derive(key, iterations, buffer)

> Stability: 2 - Stable

Derives a subkey from a key, number of iterations, and a context buffer. This function calls kdf.init, kdf.update, and kdf.final internally.

const buffer = Buffer.from('examples')
const key = crypto.kdf.keygen()
const subkey = crypto.kdf.derive(key, 1, buffer) // buffer optional

crypto.seal(message, opts)

> Stability: 2 - Stable

Seals a message based on a curve25519 public key for a recipient who has the corresponding secret key.

const publicKey = getServerPublicKey()
const message = Buffer.from('hello')
const sealed = crypto.seal(message, { publicKey })

crypto.seal.open(message, opts)

> Stability: 2 - Stable

Opens a sealed message based on a curve25519 public key for a recipient who has the corresponding secret key.

const { publicKey, secretKey } = getKeyPair()
const message = crypto.seal.open(ciphertext, { publicKey, secretKey })

crypto.shash(message, secretKey)

> Stability: 2 - Stable

Compute a 8 byte short hash for some message buffer based on a given secret key.

const message = Buffer.from('message')
const keyPair = crypto.curve25519.keyPair()
const key = crypto.blake2b(keyPair.secretKey, 16)
const mac = crypto.shash(message, key)

Contributing

• Commit message format
• Commit message examples
• How to contribute

See Also

• libsodium
• sodium-universal
• ara-identity
• Key derivation function
• Stability index

License

LGPL-3.0