cryptoutil

Documentation

Overview

Package cryptoutil implements utility functions for signing, checking, encrypting and decrypting values.

Index

• Variables
• type Cipherer
• type EncryptSigner
  • func (e *EncryptSigner) EncryptSign(data []byte) (string, error)
  • func (e *EncryptSigner) UnsignDecrypt(data string) ([]byte, error)
• type Encrypter
  • func (e *Encrypter) Decrypt(data []byte) ([]byte, error)
  • func (e *Encrypter) Encrypt(data []byte) ([]byte, error)
• type Hasher
• type Signer
  • func (s *Signer) Sign(data []byte) (string, error)
  • func (s *Signer) Unsign(signed string) ([]byte, error)

Variables

var (
	// Tried to encrypt a value without specifying a key.
	ErrNoEncryptionKey = errors.New("no encryption key specified")
	// Could not decrypt encrypted value (it was probably tampered with).
	ErrCouldNotDecrypt = errors.New("could not decrypt value")
)

var (
	// Tried to sign with an empty key.
	ErrNoSigningKey = errors.New("no signing key specified")
	// The value does not seem to be signed.
	ErrNotSigned = errors.New("value does look like it was signed")
	// Signature does not match (definitely tampered).
	ErrTampered = errors.New("the value has been tampered with")
)

Types

type Cipherer

type Cipherer func(key []byte) (cipher.Block, error)

Cipherer is a function type which returns a cipher.Block from a given key.

type EncryptSigner

type EncryptSigner struct {
	// Encrypter used for encryption/decryption.
	Encrypter *Encrypter
	// Signer used for signing/unsigning.
	Signer *Signer
}

EncryptSigner is a conveniency type which performs encryption with and then signs the encrypted data.

func (*EncryptSigner) EncryptSign

func (e *EncryptSigner) EncryptSign(data []byte) (string, error)

EncryptSign encrypts the data using the EncryptSigner Encrypter and the signs it using its Signer.

func (*EncryptSigner) UnsignDecrypt

func (e *EncryptSigner) UnsignDecrypt(data string) ([]byte, error)

UnsignDecrypt takes an encrypted and signed string, previously returned from EncryptSign, checks its signature and returns the decrypted data. If the signature does not match or the data can't be correctly decrypted an error is returned.

type Encrypter

type Encrypter struct {
	// Cipherer returns a cipher.Block initialized with
	// the given key. If nil, it defaults to aes.NewCipher
	Cipherer Cipherer
	// Key is the encryption key. If empty, all public methods
	// will return ErrNoEncryptionKey.
	Key []byte
}

Encrypter performs symmetrical encryption and decryption using a block cipher in CTR mode and a random IV. It's important to note that the output from Encrypt must also be authenticated in other to be secure. One easy way to the that is using Signer.

func (*Encrypter) Decrypt

func (e *Encrypter) Decrypt(data []byte) ([]byte, error)

Decrypt decrypts the given data using the Encrypter's Cipherer and Key.

func (*Encrypter) Encrypt

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

Encrypt encrypts the given data using the Encrypter's Cipherer and Key, using a random initialization vector.

type Hasher

type Hasher func(key []byte) (hash.Hash, error)

Hasher represents a function type which returns a hash.Hash with the given key.

type Signer

type Signer struct {
	// Hasher is the function used to obtain a hash.Hash from the
	// Key.
	Hasher Hasher
	// Key is the key used for signing the data.
	Key []byte
	// Salt is prepended to the value to be signed. See the Signer
	// documentation for security considerations about the salt.
	Salt []byte
}

Signer signs messages using the provided Hasher function, Key and, optionally but highly recommended, a Salt. The data and the signature are base64 encoded, removing any padding ('=') characters, so its output can be safely used in cookies, urls or headers. Note that you MUST use a unique salt in every system of your app which uses a Signer, otherwise you might be exposing yourself to security risks (e.g. if you use signing in your forms and in some authentication system, it's ok to use the same salt for all the forms, but not to use the same salt for the forms and the authentication).

func (*Signer) Sign

func (s *Signer) Sign(data []byte) (string, error)

Sign signs the given data and returns the data plus the signature as a string. See Signer documentation for the characteristics of the returned string.

func (*Signer) Unsign

func (s *Signer) Unsign(signed string) ([]byte, error)

Unsign takes a string, previously returned from Sign, checks that its signature is valid and, in that case, returns the initial data. If the signature is not valid, an error is returned.