simplebox

README

simplebox

Package simplebox provides a simple, easy-to-use cryptographic API where all of the hard decisions have been made for you in advance. The backing cryptography is XSalsa20 and Poly1305, which are known to be secure and fast.

This package is a Golang port of the RbNaCl module of the same name.

Installation and Usage

go get github.com/brandur/simplebox

Please see godoc for usage information and examples.

Run tests

go test ./...

Cut a release

1. Fetch changes to the repo and any new tags. Export VERSION by incrementing the last tag according to semantic versioning:

   git checkout master && git pull --rebase
   export VERSION=v0.x.y
   

2. Prepare a PR with the changes, updating CHANGELOG.md with any necessary additions at the same time. Have it reviewed and merged.

3. Upon merge, pull down the changes, tag each module with the new version, and push the new tags:

   git pull origin master
   git tag $VERSION
   git push --tags
   

4. Cut a new GitHub release by visiting new release, selecting the new tag, and copying in the version's CHANGELOG.md content as the release body.

Documentation

Overview

Package simplebox provides a simple, easy-to-use cryptographic API where all of the hard decisions have been made for you in advance. The backing cryptography is XSalsa20 and Poly1305, which are known to be secure and fast.

This package uses NaCl's secretbox under the hood, but also includes a simple yet secure nonce generation strategy. A 24-byte random nonce is generated from a secure source, used to encrypt a message, and prepended to the resulting ciphertex. When it's time for decryption, the message is split back into nonce and ciphertext, and the message is decrypted.

Thanks to the size of the nonce, the chance of a collision is negligible. For example, after encrypting 2^64 messages, the odds of there having been a repeated nonce is approximately 2^-64.

Note that although this strategy assures the confidentiality of your messages, it doesn't provide any protection against messages being reordered and replayed by an active adversary.

This idea is entirely based on the SimpleBox implementation included with RbNaCl: https://github.com/cryptosphere/rbnacl/wiki/SimpleBox

Index

• Constants
• type SimpleBox
  • func NewFromSecretKey(secretKey *[KeySize]byte) *SimpleBox
  • func (b *SimpleBox) Decrypt(cipher []byte) ([]byte, error)
  • func (b *SimpleBox) Encrypt(plain []byte) []byte

Examples

• SimpleBox

Constants

const (
	// Length in bytes of a secret key used for encryption and decryption.
	KeySize = 32

	// Length in bytes of a nonce value (which must be unique and may be
	// random) used for encryption and decryption.
	NonceSize = 24
)

Types

type SimpleBox

type SimpleBox struct {
	// contains filtered or unexported fields
}

SimpleBox provides a simple wrapper around NaCl's secretbox with a self-contained random nonce strategy.

Example

package main

import (
	"crypto/rand"
	"fmt"

	"github.com/brandur/simplebox"
)

func main() {
	message := "hello"

	var secretKey [simplebox.KeySize]byte
	rand.Reader.Read(secretKey[:])
	box := simplebox.NewFromSecretKey(&secretKey)

	// Encrypt
	ciphertext := box.Encrypt([]byte(message))

	// Decrypt
	decrypted, err := box.Decrypt(ciphertext)
	if err != nil {
		panic(err)
	}

	// Prints:
	//
	// Decrypted: hello
	fmt.Printf("Decrypted: %v\n", decrypted)
}

func NewFromSecretKey

func NewFromSecretKey(secretKey *[KeySize]byte) *SimpleBox

Creates a SimpleBox from a secret key.

func (*SimpleBox) Decrypt

func (b *SimpleBox) Decrypt(cipher []byte) ([]byte, error)

Decrypts the given ciphertext and returns plaintext. An appropriate error is included if decryption failed.

func (*SimpleBox) Encrypt

func (b *SimpleBox) Encrypt(plain []byte) []byte

Encrypts the given plaintext and returns ciphertext.