lockbox

README

lockbox

Documentation can be found on godoc.org

Documentation

Overview

Package lockbox simplified asymmetric encryption with NaCl.

Lockbox uses NaCl's box API for public-key cryptography to provide a simplified API for asymmetric encryption. It is designed with the following goals:

* Provide a simple convention for managing encryption & decryption keys. An encryption key is a PEM encoded NaCl box public key with title "LOCKBOX PUBLIC ENCRYPTION KEY", stored with the file extension ".ekey". A decryption key is a PEM encoded NaCl box private key with title "LOCKBOX SECRET DECRYPTION KEY", stored with the file extension ".dkey".

* Provide a simplified API for setup & encryption/decryption. The Encryptor & Decryptor types are constructed with their corresponding key. The types have a single Encrypt/Decrypt method that take a cleartext/ciphertext byte slice parameter and returns a ciphertext/cleartext byte slice.

* Design the Encryptor so that it cannot decrypt the output of Encrypt once the function has returned. Isolating the role of decryption from encryption should be straightforward and easy.

Installation

Install lockbox via go get:

$ go get github.com/benburkert/lockbox/cmd/...

Example Command Usage

Generate a new keypair:

$ lockbox generate testpair
$ cat testpair.ekey
cat testpair.ekey
-----BEGIN LOCKBOX PUBLIC ENCRYPTION KEY-----
WSm+Qpliu+flFoKJoa8UQpAM9Lo2HwtQNdXAJec4gCo=
-----END LOCKBOX PUBLIC ENCRYPTION KEY-----
$ cat testpair.dkey
-----BEGIN LOCKBOX SECRET DECRYPTION KEY-----
8G2vsOGuyr7ut5J4G6Jat+bsft9BBoCOTHTdPjIS+1s=
-----END LOCKBOX SECRET DECRYPTION KEY-----

Encrypt a message:

$ echo "Kill all humans" | lockbox encrypt testpair.ekey > data.pem
$ cat data.pem
-----BEGIN LOCKBOX DATA-----
Fingerprint: WSm+Qpliu+flFoKJoa8UQpAM9Lo2HwtQNdXAJec4gCo=
Nonce: 14VYjF6Cli6zltBKyDgkkQIaWfDf1mBd
Public-Key: miZx64bMBx1NsOELM79Dx4y7FoVi7NgE+sdqz3zJ21A=

EDx6j97EMoNiBUBWqnHHnP7+3Hj2HNhgz4X5L9lVObQ=
-----END LOCKBOX DATA-----

Decrypt the message:

$ lockbox decrypt testpair.dkey < data.pem
Kill all humans

Example Package Usage

Encrypt & print a message:

encryptor := lockbox.LoadEncryptor("testpair.ekey")
data, err := encryptor.Encrypt([]byte("Kill all humans"))
fmt.Println(data)

Decrypt & print the message:

decryptor := lockbox.LoadDecryptor("testpair.dkey")
cleartext, err := decryptor.Decrypt(data)
fmt.Println(cleartext)

Caveats

Lockbox does not prevent a hostile party with access to the encryption key from replacing a message with a forgery. In this case, the decryptor is unable to detect if a message is a forgery. Lockbox data should only be transported over secure channels.

Index

• func GenerateKey() (ekey, dkey []byte, err error)
• type Decryptor
  • func LoadDecryptor(dkeyFile string) (*Decryptor, error)
  • func NewDecryptor(dkey *pem.Block) (*Decryptor, error)
  • func (d *Decryptor) Decrypt(data []byte) ([]byte, error)
• type Encryptor
  • func LoadEncryptor(ekeyFile string) (*Encryptor, error)
  • func NewEncryptor(ekey *pem.Block) (*Encryptor, error)
  • func (e *Encryptor) Encrypt(data []byte) ([]byte, error)

Functions

func GenerateKey

func GenerateKey() (ekey, dkey []byte, err error)

GenerateKey returns a new pem encoded keypair.

Types

type Decryptor

type Decryptor struct {
	PK, SK *[32]byte // public key, secret key
}

Decryptor decrypts data with a decryption (secret) key.

func LoadDecryptor

func LoadDecryptor(dkeyFile string) (*Decryptor, error)

LoadDecryptor returns a Decryptor for the decryption (private) key file.

func NewDecryptor

func NewDecryptor(dkey *pem.Block) (*Decryptor, error)

NewDecryptor returns a Decryptor for decrypting data encrypted with the encryption (public) key corresponding to the decryption (private) key.

func (*Decryptor) Decrypt

func (d *Decryptor) Decrypt(data []byte) ([]byte, error)

Decrypt returns the cleartext contents of the PEM encoded block of lockbox encrypted ciphertext in data.

type Encryptor

type Encryptor struct {
	PK     *[32]byte // public key
	Reader io.Reader // random data source
}

Encryptor encrypts data with an encryption (public) key.

func LoadEncryptor

func LoadEncryptor(ekeyFile string) (*Encryptor, error)

LoadEncryptor returns an Encryptor for the encryption (public) key file.

func NewEncryptor

func NewEncryptor(ekey *pem.Block) (*Encryptor, error)

NewEncryptor returns an Encryptor for the encryption (public) key PEM block.

func (*Encryptor) Encrypt

func (e *Encryptor) Encrypt(data []byte) ([]byte, error)

Encrypt returns the encrypted contents of data in a single PEM encoded block. The block type is 'LOCKBOX DATA' with base64 encoded headers:

Fingerprint: the identifying fingerprint of the decryption key
Public-Key:  public key portion of the keypair generated for encryption
Nonce:       nonce value used during encryption & decryption