decrypt

Decrypts a ciphertext given a corresponding key.

decryptkey, envelopeplaintext

name	type	description
key	`SymmetricKey` `SharedKey`	Key to be used in the decryption operation.
envelope	`Envelope`	Wrapper for the ciphertext and nonce.
plaintext	`Message`	Wrapper for the plaintext resulting from decrypting the envelope.

decrypt is a generic function, accepting an encryption key and ciphertext to return a plaintext.

When given a SymmetricKey, decrypt uses symmetric decryption.
When given a SharedKey, decrypt uses authenticated, asymmetric decryption.

The ciphertext must encapsulated in an instance of Envelope, returned by encrypt. You may use Envelope.from to derive an instance from an encoded envelope.

decrypt returns an instance of Message, and the original plaintext can be restored using Message::to.

If decrypt cannot decrypt a ciphertext (ex: the incorrect key is provided), it throws.

Examples

Symmetric Decryption

import assert from "assert"
import {confidential} from "panda-confidential"
{decrypt, Envelope} = confidential()
import {keyLookup, read} from "my-library"

do ->
  alice = keyLookup "Alice/private"

  serialized = read "greeting"
  envelope = Envelope.from "base64", serialized

  plaintext = await decrypt alice, envelope

  # You may format the plaintext with the instance method `to`.
  assert.equal (plaintext.to: "utf8"), "Hello, Alice!"

Asymmetric Decryption

import assert from "assert"
import {confidential} from "panda-confidential"
{SharedKey, decrypt, Envelope} = confidential()
import {keyLookup, receive} from "my-library"

do ->
  alice = keyLookup "Alice/public"
  bob = keyLookup "Bob/private"
  toBobFromAlice = SharedKey.create alice, bob

  serialized = receive "Bob"
  envelope = Envelope.from "base64", serialized

  plaintext = await decrypt toBobFromAlice, envelope

  # You may format the plaintext with the instance method `to`.
  assert.equal (plaintext.to: "utf8"), "Hello, Bob!"