Detox crypto 
High-level utilities that combine under simple interfaces complexity of the cryptographic layer used in Detox project.
Essentially provides wrapper functions and objects for:
- Ed25519 and X25519 keys creation
- AEZ block cipher
- Noise protocol (Noise_NK_25519_ChaChaPoly_BLAKE2b, Noise_N_25519_ChaChaPoly_BLAKE2b)
How to install
npm install @detox/crypto
How to use
NOTE: In modern versions of Node.js (4.x and higher) Buffer inherits Uint8Array, so you can pass Buffer directly whenever Uint8Array is expected.
Node.js:
var detox_crypto = require('@detox/crypto')
detox_crypto.ready(function () {
// Do stuff
});Browser:
requirejs(['@detox/crypto'], function (detox_crypto) {
detox_crypto.ready(function () {
// Do stuff
});
})API
detox_crypto.ready(callback)
-
callback- Callback function that is called when library is ready for use
detox_crypto.create_keypair(seed = null : Uint8Array) : Object
Creates keypairs from specified seed (if not specified, random seed will be generated).
Returns an object with properties:
-
seed(same as argument or random generate otherwise) -
ed25519- Ed25519 keypair-
public- Public key -
private- Private key (already hashed, as used in orlp/ed25519)
-
-
x25519- X25519 keypair-
public- Public key -
private- Private key
-
detox_crypto.convert_public_key(ed25519_public_key : Uint8Array) : Uint8Array
Converts Ed25519 public key into X25519/Curve25519 public key. Returns null if conversion fails.
detox_crypto.sign(data : Uint8Array, ed25519_public_key : Uint8Array, ed25519_private_key : Uint8Array) : Uint8Array
Signs data and returns 64 bytes signature.
detox_crypto.verify(signature : Uint8Array, data : Uint8Array, ed25519_public_key : Uint8Array) : boolean
Verifies that signature corresponds to specified data and public key.
detox_crypto.Rewrapper(key = null : Uint8Array) : detox_crypto.Rewrapper
Constructor for Rewrapper object. Can be initialized with key (48 bytes, typically done on responder side) or key will be generated automatically (typically done on initiator side).
Uses AEZ block cipher.
detox_crypto.Rewrapper.get_key() : Uint8Array
Key that was specified during initialization or that was generated automatically.
detox_crypto.Rewrapper.wrap(plaintext : Uint8Array) : Uint8Array
Wraps plaintext into ciphertext.
detox_crypto.Rewrapper.unwrap(plaintext : Uint8Array) : Uint8Array
Unwraps plaintext from ciphertext, inverse to wrap().
detox_crypto.Encryptor(initiator : boolean, key : Uint8Array) : detox_crypto.Encryptor
Constructor for Encryptor object. If initialized for initiator then key will be public key (X25519) of the responder. If initialized for responder then key will be private key (X25519) of the responder.
Uses Noise protocol (Noise_NK_25519_ChaChaPoly_BLAKE2b).
Constructor and all methods can throw Error if something goes wrong, be ready to catch exceptions.
detox_crypto.Encryptor.ready() : boolean
Quick check if handshake was finished and Encryptor is ready for encryption/decryption.
detox_crypto.Encryptor.get_handshake_message() : Unt8Array
Get handshake message that should be send to another side.
detox_crypto.Encryptor.put_handshake_message(message : Unt8Array)
Put handshake message that was received from another side.
detox_crypto.Encryptor.get_rewrapper_keys() : Array
Get rewrapper keys derived from handshake. 2 elements are Uint8Arrays of 48 bytes, first one most be used for sending data (wrapping) and second for receiving (unwrapping).
detox_crypto.Encryptor.encrypt(plaintext : Uint8Array) : Unt8Array
Encrypts plaintext into ciphertext for another side.
detox_crypto.Encryptor.decrypt(plaintext : Uint8Array) : Unt8Array
Decrypts plaintext from ciphertext from another side.
detox_crypto.Encryptor.destroy()
Destroys stateful data structures and makes Encryptor unusable.
detox_crypto.one_way_encrypt(public_key : Uint8Array, plaintext : Uint8Array) : Uint8Array
One-way encryption for specified X25519 public key.
Uses Noise protocol (Noise_N_25519_ChaChaPoly_BLAKE2b).
Returns combined handshake message and ciphertext.
detox_crypto.one_way_decrypt(private_key : Uint8Array, message : Uint8Array) : Uint8Array
One-way decryption of the message for specified X25519 private key.
Uses Noise protocol (Noise_N_25519_ChaChaPoly_BLAKE2b).
Takes combined handshake message and ciphertext as input message and returns plaintext.
detox_crypto.blake2b_256(data : Uint8Array) : Uint8Array
Returns Blake2b-256 hash of data.
Take a look at src/index.ls for JsDoc sections with arguments and return types as well as methods description, look at tests/index.ls for usage examples.
Contribution
Feel free to create issues and send pull requests (for big changes create an issue first and link it from the PR), they are highly appreciated!
When reading LiveScript code make sure to configure 1 tab to be 4 spaces (GitHub uses 8 by default), otherwise code might be hard to read.
License
Free Public License 1.0.0 / Zero Clause BSD License