encryptedbox

README

encryptedbox

EncryptedBox is an easy to use module for Go that can encrypt or sign any type of data. It is especially useful when you must serialize your structured data before encrypting or signing it.

There are a number of examples provided in this repo, which should make it easy to understand how to use this library.

How it works

EncryptedBox provides a Cipher component which can be configured to encrypt and decrypt data using an easy to understand pipeline which includes serial and deserialization. Alternatively, it can also sign and verify data.

1. Serialize structured data to raw binary data
2. (Optional) Compress the binary data
3. Encrypt or Sign
4. (Optional) Encode encrypted data or signature as a string

The inverse steps must be done in reverse order when decrypting. Encryptedbox allows you fit these pieces together in a way where the implementation for any of the steps can be easily changed to suit your needs.

Serialization

Encryption works on binary data, so the first step to encrypt anything is to turn it into a stream of bytes.

encryptedbox can work with easily with Go data structures by serializing them into JSON. You can also use other provided serializers or create your own to pack your structs into binary more efficiently.

Compression

Encrypted data appears random, and so compression is no longer possible. If the data is compressible and you want to compress it, you should do it before encryption.

* Note in some circumstances, compressing data can cause information to be leaked, especially if an attacker can control part of the message being compressed. See for instance CRIME (Compression Ratio Info-leak Made Easy).

Encrypt or Sign

EncryptedBox includes components for encrypting with AES for private key encryption and RSA for public key encryption. It also includes components for HMAC-SHA for symmetric signatures and RSA signing for asymmetric signatures.

The library chooses reasonably safe defaults out of the box:

• the same plaintext will produce different ciphertext each time it is run
• you can encrypt as many blocks as you want

Encode encrypted data or signature as a string

It is common the encrypted payload will need to be encoded into a safe format in order to be transmitted in different contexts, such as a query parameter. At the expense of the message size, encryptedbox has two convenience functions to make this easier, Cipher.EncryptToString() and Cipher.DecryptString(). The encoding used by this function can be changed if you are unhappy with the default of base64.RawURLEncoding.

Examples

The most basic example that can be contrived is the following snippet, which encrypts and decrypts "Hello world!"

key, _ := aesutil.NewKey256()
cipher, _ := encryptedbox.NewAESCipher(key)

ciphertext, _ := cipher.Encrypt("Hello world!")

var decrypted string
_ = cipher.Decrypt(ciphertext, &decrypted)

fmt.Println(decrypted)

There are several more examples located in the examples directory.

Documentation

Index

• type Cipher
  • func NewAESCipher(aesKey []byte) (*Cipher, error)
  • func NewHMACSHA256Signer(aesKey []byte) (*Cipher, error)
  • func NewRSACipher(privateKeyPem []byte) (*Cipher, error)
  • func NewRSAEncryptOnlyCipher(publicKeypem []byte) (*Cipher, error)
  • func NewRSASigner(privateKeyPem []byte) (*Cipher, error)
  • func NewRSASignerVerifyOnly(publicKeypem []byte) (*Cipher, error)
  • func (c Cipher) Decrypt(ciphertext []byte, dst interface{}) error
  • func (c Cipher) DecryptString(ciphertext string, dst interface{}) error
  • func (c Cipher) Encrypt(data interface{}) ([]byte, error)
  • func (c Cipher) EncryptToString(data interface{}) (string, error)
  • func (c Cipher) Sign(data interface{}) (signature string, bytesSigned []byte, err error)
  • func (c Cipher) SignToString(data interface{}) (signature string, signedData string, err error)
  • func (c Cipher) Verify(data interface{}, signature string) error
  • func (c Cipher) VerifyAndLoad(signedData []byte, signature string, dst interface{}) error
  • func (c Cipher) VerifyStringAndLoad(signedData string, signature string, dst interface{}) error
• type Compressor
  • func GzipCompression(level int) Compressor
  • func ZlibCompression(level int) Compressor
• type Encrypter
  • func AES(key []byte) (Encrypter, error)
  • func RSA(privateKeyPem []byte) (Encrypter, error)
  • func RSAEncryptOnly(publicKeyPem []byte) (Encrypter, error)
• type Serializer
• type Signer
  • func HMACSHA256(key []byte) (Signer, error)
  • func RSASigner(privateKeyPem []byte) (Signer, error)
  • func RSAVerifyOnly(publicKeyPem []byte) (Signer, error)
• type StringEncoder

Types

type Cipher

type Cipher struct {
	// Serializer performs the first (or final) step of converting the input data to a []byte
	Serializer Serializer

	// Compressor is an optional component to compress the output (or input) of the Serializer.
	Compressor Compressor

	// Encrypter controls the encryption and decryption steps.
	Encrypter Encrypter

	// Signer controls the signing and verification steps.
	Signer Signer

	// StringEncoder must implement the StringEncoder interface
	//
	// There are many Encodings from "encoding/base32", "encoding/base64",
	// and "encoding/hex" which satisfy the StringEncoder interface
	StringEncoder StringEncoder
}

func NewAESCipher

func NewAESCipher(aesKey []byte) (*Cipher, error)

func NewHMACSHA256Signer

func NewHMACSHA256Signer(aesKey []byte) (*Cipher, error)

func NewRSACipher

func NewRSACipher(privateKeyPem []byte) (*Cipher, error)

func NewRSAEncryptOnlyCipher

func NewRSAEncryptOnlyCipher(publicKeypem []byte) (*Cipher, error)

func NewRSASigner

func NewRSASigner(privateKeyPem []byte) (*Cipher, error)

func NewRSASignerVerifyOnly

func NewRSASignerVerifyOnly(publicKeypem []byte) (*Cipher, error)

func (Cipher) Decrypt

func (c Cipher) Decrypt(ciphertext []byte, dst interface{}) error

func (Cipher) DecryptString

func (c Cipher) DecryptString(ciphertext string, dst interface{}) error

func (Cipher) Encrypt

func (c Cipher) Encrypt(data interface{}) ([]byte, error)

func (Cipher) EncryptToString

func (c Cipher) EncryptToString(data interface{}) (string, error)

func (Cipher) Sign

func (c Cipher) Sign(data interface{}) (signature string, bytesSigned []byte, err error)

func (Cipher) SignToString

func (c Cipher) SignToString(data interface{}) (signature string, signedData string, err error)

func (Cipher) Verify

func (c Cipher) Verify(data interface{}, signature string) error

func (Cipher) VerifyAndLoad

func (c Cipher) VerifyAndLoad(signedData []byte, signature string, dst interface{}) error

func (Cipher) VerifyStringAndLoad

func (c Cipher) VerifyStringAndLoad(signedData string, signature string, dst interface{}) error

type Compressor

type Compressor interface {
	Compress([]byte) ([]byte, error)
	Decompress([]byte) ([]byte, error)
}

The Compressor type compresses and decompresses []byte.

var (
	Zlib Compressor = ZlibCompression(zlib.BestCompression)
	Gzip Compressor = GzipCompression(gzip.BestCompression)
)

func GzipCompression

func GzipCompression(level int) Compressor

func ZlibCompression

func ZlibCompression(level int) Compressor

type Encrypter

type Encrypter interface {
	Encrypt(plaintext []byte) ([]byte, error)
	Decrypt(ciphertext []byte) ([]byte, error)
}

The Encrypter type encrypts and decrypts []byte.

Encrypters must know how to find the key they require as the key is not passed in as a function argument.

func AES

func AES(key []byte) (Encrypter, error)

AES will return a symmetric Encrypter using AES

func RSA

func RSA(privateKeyPem []byte) (Encrypter, error)

RSA will return an asymmetric Encrypter using RSA

func RSAEncryptOnly

func RSAEncryptOnly(publicKeyPem []byte) (Encrypter, error)

RSAEncryptOnly will return an asymmetric Encrypter using RSA which can only Encrypt.

type Serializer

type Serializer interface {
	Serialize(interface{}) ([]byte, error)
	Deserialize([]byte, interface{}) error
}

The Serializer type serializes and deserializes the input data types to a []byte.

var (
	String Serializer = stringSerializer{}
	Bytes  Serializer = bytesSerializer{}
	JSON   Serializer = jsonSerializer{}
	Gob    Serializer = gobSerializer{}
)

type Signer

type Signer interface {
	Sign(data []byte) ([]byte, error)
	Verify(data []byte, signature []byte) error
}

The Signer type signs and verify []byte.

Signers must know how to find the key they require as the key is not passed in as a function argument.

func HMACSHA256

func HMACSHA256(key []byte) (Signer, error)

HMACSHA256 will return a Signer which uses HMAC-SHA-256

func RSASigner

func RSASigner(privateKeyPem []byte) (Signer, error)

RSA will return an asymmetric Signer using RSA

func RSAVerifyOnly

func RSAVerifyOnly(publicKeyPem []byte) (Signer, error)

RSAVerifyOnly will return an asymmetric Encrypter using RSA which can only Verify, but not sign.

type StringEncoder

type StringEncoder interface {
	EncodeToString(src []byte) string
	DecodeString(s string) ([]byte, error)
}

The StringEncoder type encodes and decodes binary data to a string.

var DefaultStringEncoder StringEncoder = base64.RawURLEncoding

DefaultStringEncoder is the default encoder to use for Cipher.EncryptToString() and Cipher.DecryptString().

This value is filled into the Cipher struct by the NewXXXCipher functions.