lioness

Documentation

Overview

Package lioness implements the LIONESS Large Block Cipher with some modifications: Instead of using a standard stream cipher, it only allows usage of block ciphers that implement the cipher.Block interface. Furthermore it does not use the suggested hash operation but instead uses an HMAC everywhere a hash is used in the original design Paper: http://www.cl.cam.ac.uk/~rja14/Papers/bear-lion.pdf In addition, this implementation supports two modes. ModeZero, which uses an all zero IV for the R-operation, and ModeIV, which uses the content of L as the IV.

Index

• Constants
• Variables
• type Lioness
  • func Construct(blockcipher func([]byte) (cipher.Block, error), hash func() hash.Hash, ...) (*Lioness, error)
  • func New(key []byte) (*Lioness, error)
  • func (l *Lioness) Decrypt(data []byte) ([]byte, error)
  • func (l *Lioness) Encrypt(data []byte) ([]byte, error)
  • func (l *Lioness) ExplodeKey(key []byte) error
  • func (l *Lioness) Setkeys(k1, k2, k3, k4 []byte) error

Examples

• Construct
• Lioness.Setkeys
• New

Constants

const (
	// ModeIV uses L as the IV for encryption
	ModeIV = iota
	// ModeZero uses all zeros as the IV for encryption
	ModeZero
)

Variables

var (
	// ErrConstructed is returned if working with a lioness that hasn't been set up
	ErrConstructed = errors.New("lioness: Missing setup")
	// ErrKeyHashSize is returned if the key size is larger than the hash size
	ErrKeyHashSize = errors.New("lioness: Hash smaller than key")
	// ErrKeyLen is returned when the keys given do not match the key length
	ErrKeyLen = errors.New("lioness: Keys have wrong size")
	// ErrDataSize is returned when the data is too small (<=keylen)
	ErrDataSize = errors.New("lioness: Not enough data")
	// ErrNoKeys is returned if using a lioness without keys
	ErrNoKeys = errors.New("lioness: Keys not set")
)

Types

type Lioness

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

Lioness holds internal data

func Construct

func Construct(blockcipher func([]byte) (cipher.Block, error), hash func() hash.Hash, keylen int, key []byte, mode int) (*Lioness, error)

Construct returns a new Lioness. Takes block cipher, hash function and keylen. Key can be nil. mode is either ModeIV or ModeZero

Example

// Define encryption key and data to be encrypted
key := []byte("This is the secret encryption key")
// Data must be keylen +1 bytes or longer
data := []byte("Some data to be encrypted. It must be long enough to cover at least one key length.")

// Create new lioness. aes will be used for stream encryption (in CTR mode), sha256 is our hmac hash.
// The keylen is set to 32 (AES256) and we are using ModeZero (IV is all zero). The key given will
// be expanded automatically to fill the subkeys k1-k4.
l, err := Construct(aes.NewCipher, sha256.New, 32, key, ModeZero)

// Errors returned if keylength and algorithm choice conflict.
if err != nil {
	fmt.Printf("Error occured in New: %s", err)
}

// Encrypt data. Error is returned if data is not long enough
encrypted, err := l.Encrypt(data)
if err != nil {
	fmt.Printf("Error occured in Encrypt: %s", err)
}

// Decrypt data.
decrypted, err := l.Decrypt(encrypted)
if err != nil {
	fmt.Printf("Error occured in Decrypt: %s", err)
}
fmt.Printf("Data after decryption: %s\n", decrypted)

Output:

Data after decryption: Some data to be encrypted. It must be long enough to cover at least one key length.

func New

func New(key []byte) (*Lioness, error)

New is shorthand for Construct with aes256 and sha256 in ModeZero

Example

// Define encryption key and data to be encrypted
key := []byte("This is the secret encryption key")
// Data must be keylen +1 bytes or longer
data := []byte("Some data to be encrypted. It must be long enough to cover at least one key length.")

// Create new lioness with default algorithms, mode and automatic key expansion.
l, err := New(key)

// Errors returned if keylength and algorithm choice conflict.
if err != nil {
	fmt.Printf("Error occured in New: %s", err)
}

// Encrypt data. Error is returned if data is not long enough
encrypted, err := l.Encrypt(data)
if err != nil {
	fmt.Printf("Error occured in Encrypt: %s", err)
}

// Decrypt data.
decrypted, err := l.Decrypt(encrypted)
if err != nil {
	fmt.Printf("Error occured in Decrypt: %s", err)
}
fmt.Printf("Data after decryption: %s\n", decrypted)

Output:

Data after decryption: Some data to be encrypted. It must be long enough to cover at least one key length.

func (*Lioness) Decrypt

func (l *Lioness) Decrypt(data []byte) ([]byte, error)

Decrypt the data, return error if too little data is given

func (*Lioness) Encrypt

func (l *Lioness) Encrypt(data []byte) ([]byte, error)

Encrypt the data, return error if too little data is given

func (*Lioness) ExplodeKey

func (l *Lioness) ExplodeKey(key []byte) error

ExplodeKey generates the Lioness keys from a single input key by calculating repeated HMACs (which is of questionable security)

func (*Lioness) Setkeys

func (l *Lioness) Setkeys(k1, k2, k3, k4 []byte) error

Setkeys sets the keys and verifies that they are of keylen length

Example

// Define four (independent) encryption keys. Keys must have keylen length.
key1 := []byte("11111178901234567890123456781111")
key2 := []byte("22222278901234567890123456782222")
key3 := []byte("33333378901234567890123456783333")
key4 := []byte("44444478901234567890123456784444")

// Data must be keylen +1 bytes or longer
data := []byte("Some data to be encrypted. It must be long enough to cover at least one key length.")

// Create new lioness. aes will be used for stream encryption (in CTR mode), sha256 is our hmac hash.
// The keylen is set to 32 (AES256) and we are using ModeIV (L is used as IV). Key is nil, we will use
// SetKeys instead
l, err := Construct(aes.NewCipher, sha256.New, 32, nil, ModeIV)
if err != nil {
	fmt.Printf("Error occured in New: %s", err)
}

// Set the four keys required for the operation. An error will occur if the key lengths != keylen
err = l.Setkeys(key1, key2, key3, key4)
if err != nil {
	fmt.Printf("Error occured in EetKey: %s", err)
}

// Encrypt data. Error is returned if data is not long enough
encrypted, err := l.Encrypt(data)
if err != nil {
	fmt.Printf("Error occured in Encrypt: %s", err)
}

// Decrypt data.
decrypted, err := l.Decrypt(encrypted)
if err != nil {
	fmt.Printf("Error occured in Decrypt: %s", err)
}
fmt.Printf("Data after setkeys and decryption: %s\n", decrypted)

Output:

Data after setkeys and decryption: Some data to be encrypted. It must be long enough to cover at least one key length.