vikaskumr / dark-crystal-implemenation

Dark Crystal Key Backup Crypto

Crypto operations and functionality for Dark Crystal key backup

This library adds:

• Packing secret together with a descriptive label using a protocol buffer.
• Generating signing keypairs, signing and verifying shards
• Deriving encryption keypairs from signing keypairs
• Encrypting and decrypting a message (asymmetric) to a single recipient
• One-way encrypting and decrypting a message (asymmetric) to a single recipient, ensuring that the sender cannot also decrypt the message. This is used for encrypting shards.
• Encrypting and decrypting a message to one or two recipients using [private-box])(https://github.com/auditdrivencrypto/private-box)

Note: to avoid confusion between signing keys and encryption keys, all the encryption functions here take signing keys and convert them internally.

Example

See example.js

API

packLabel

const packed = packLabel(secret, label)

Pack a secret together with a descriptive label, using a protocol buffer.

• secret should be a buffer or a string.
• label is an optional argument which if given should be a string containing some useful contextual information about the secret.
• returns a buffer

unpackLabel

const { secret, label } = unpackLabel(packed)

• packed is a buffer created with packLabel
• returns an object with properties secret and label, which will be a buffer and a string respectively. If no label was given, label will be the empty string.

keypair

const keypair = keypair()

Generate a keypair for signing.

• Returns a keypair object with properties publicKey, secretKey which are buffers.

signShard

const signedShard = signShard(shard, keypair)

Sign a message, and pack the signature together with the message.

• shard is a buffer
• keypair is either a keypair object or a secret key given as a buffer.
• returns a buffer, which contains both the shard and the signature.

openShard

const verifiedShard = openShard (signedShard, publicKey)

Verify a signed message, and if valid return the message without the signature.

• publicKey is a buffer
• signedShard is a buffer
• returns either a buffer with the verified shard, or false if the shard could not be verified

removeSignature

const shard = removeSignature(signedShard)

Remove the signature component from a signed shard.

This allows us to retrieve the shard data even if we were not able to validate it.

• signedShard is a buffer.
• returns a buffer.

encryptionKeypair

const boxKeypair = encryptionKeypair()

Generates a diffie-hellman asymmetric encryption keypair. Since the encryption functions given here derive encryption keys from signing keys internally, you should only need to use this for ephemeral encryption keys.

• Returns an object with properties publicKey, secretKey, both of which are buffers.

signingKeypairToEncryptionKeypair

const boxKeypair = signingKeypairToEncryptionKeypair(keypair)

Derives a diffie-hellman encryption keypair for use with box and unbox from a signing keypair. Since the encryption functions given here do this internally, you should not need to use this.

• keypair is a keypair object generated with signingKeypair()
• returns a keypair object, with properties publicKey and secretKey

box

const cipherText = box(message, recipientPublicKey, senderSecretKey)

Encrypt a message to a specified recipient's key. The sender may also decrypt this message, giving a personal record of what was sent.

• message - a buffer containing the data to encrypt.
• recipientPublicKey - a buffer containing the signing public key of the recipient.
• senderSecretKey - a buffer containing the signing secret key of the sender (ourself).
• Returns the cipher text as a buffer.

unbox

const message = unbox(cipherText, senderPublicKey, recipientSecretKey)

Decrypt a message encrypted to your own key. Or attempt to decrypt a message in order to find out whether it is encrypted to your own key.

• cipherText - a buffer generated by box.
• senderPublicKey - a buffer containing the public signing key of the author of the message.
• recipientSecretKey - a buffer containing our own secret signing key.
• returns either false if the decryption was unsuccessful, or the decrypted message as a buffer.

oneWayBox

const cipherText = oneWayBox(message, publicKey)

Encrypt a message to a particular recipient such that only the recipient and not the sender can decrypt it. Inspired by private-box, see this note in the design document. This is used for encrypting shard data so the secret owner may not read it themselves. We could also just use private-box itself for this, but this method is simpler and gives us smaller shards.

• message - should be a buffer of any length.
• publicKey - a buffer containing the public signing key of the recipient
• returns a buffer containing the cipher text. Note that this will be 32 bytes longer than if it was created with box, since it also contains an ephemeral public key.

oneWayUnbox

const message = oneWayUnbox(cipherText, secretKey)

Decrypt a message encrypted with oneWayBox.

• cipherText should be a buffer.
• secretKey should be a buffer containing the secret signing key of the recipient.
• Returns either false if the decryption was unsuccessful, or the decrypted message as a buffer.

privateBox

const cipherText = privateBox(message, publicKeys)

Encrypt a message to up to two recipients, without revealing who they are in the metadata.

• message - should be a buffer of any length.
• publicKeys - should be an array of up to two public signing keys. If a buffer is given, it will be interpreted as a single public key.
• Returns a buffer.

privateUnbox

const plainText = privateUnbox(cipherText, secretKey)

Decrypt a message encrypted with privateBox

• cipherText should be a buffer.
• secretKey should be a buffer containing the secret signing key of the recipient.
• Returns either false if the decryption was unsuccessful, or the decrypted message as a buffer.