chacha20guard

README

ChaCha20Guard

A pure Go implementation of ChaCha20 and its extended nonce variant XChaCha20 with MemGuard in order to protect the key in memory.

Before using read the Warning

The implementation is based on https://github.com/codahale/chacha20

Download/Install

go get -u github.com/alexzava/chacha20guard

Usage

Import

import (
	"log"
	"crypto/rand"

	"github.com/awnumar/memguard"
	"github.com/alexzava/chacha20guard"
)

ChaCha20

message := []byte("Hello World!")

//Generate random nonce
nonce := make([]byte, 8)
_, err := rand.Read(nonce)
if err != nil {
	log.Fatal(err)
}

//Generate random key with memguard
key, err := memguard.NewImmutableRandom(32)
if err != nil {
	log.Println(err)
	memguard.SafeExit(1)
}
defer key.Destroy()

c, err := chacha20guard.New(key, nonce)
if err != nil {
	log.Fatal(err)
}

ciphertext := make([]byte, len(message))
c.XORKeyStream(ciphertext, message)

XChaCha20

message := []byte("Hello World!")

//Generate random nonce
nonce := make([]byte, 24)
_, err := rand.Read(nonce)
if err != nil {
	log.Fatal(err)
}

//Generate random key with memguard
key, err := memguard.NewImmutableRandom(32)
if err != nil {
	log.Println(err)
	memguard.SafeExit(1)
}
defer key.Destroy()

c, err := chacha20guard.NewX(key, nonce)
if err != nil {
	log.Fatal(err)
}

ciphertext := make([]byte, len(message))
c.XORKeyStream(ciphertext, message)

Warning

The code may contain bugs or vulnerabilities, currently they have not been found but this does not guarantee absolute security.

Check the repository often because the code could be updated frequently.

Notes

If you find bugs or vulnerabilities please let me know so they can be fixed.

If you want to help improve the code contact me.

License

This project is licensed under the MIT License - see the LICENSE file for details.

Documentation

Index

• Constants
• Variables
• func New(key *memguard.LockedBuffer, nonce []byte) (cipher.Stream, error)
• func NewWithRounds(key *memguard.LockedBuffer, nonce []byte, rounds uint8) (cipher.Stream, error)
• func NewX(key *memguard.LockedBuffer, nonce []byte) (cipher.Stream, error)
• func NewXWithRounds(key *memguard.LockedBuffer, nonce []byte, rounds uint8) (cipher.Stream, error)

Constants

const (
	// KeySize is the length of ChaCha20 keys, in bytes.
	KeySize = 32
	// NonceSize is the length of ChaCha20 nonces, in bytes.
	NonceSize = 8
	// XNonceSize is the length of XChaCha20 nonces, in bytes.
	XNonceSize = 24
)

Variables

var (
	// ErrInvalidKey is returned when the provided key is not 256 bits long.
	ErrInvalidKey = errors.New("invalid key length (must be 256 bits)")
	// ErrInvalidNonce is returned when the provided nonce is not 64 bits long.
	ErrInvalidNonce = errors.New("invalid nonce length (must be 64 bits)")
	// ErrInvalidXNonce is returned when the provided nonce is not 192 bits
	// long.
	ErrInvalidXNonce = errors.New("invalid nonce length (must be 192 bits)")
	// ErrInvalidRounds is returned when the provided rounds is not
	// 8, 12, or 20.
	ErrInvalidRounds = errors.New("invalid rounds number (must be 8, 12, or 20)")
)

Functions

func New

func New(key *memguard.LockedBuffer, nonce []byte) (cipher.Stream, error)

New creates and returns a new cipher.Stream. The key must be 256 bits long, and the nonce argument must be 64 bits long. The nonce must be randomly generated or used only once.

func NewWithRounds

func NewWithRounds(key *memguard.LockedBuffer, nonce []byte, rounds uint8) (cipher.Stream, error)

NewWithRounds creates and returns a new cipher.Stream just like New but the rounds number of 8, 12, or 20 can be specified.

func NewX

func NewX(key *memguard.LockedBuffer, nonce []byte) (cipher.Stream, error)

NewX creates and returns a new cipher.Stream. The key must be 256 bits long, and the nonce argument must be 192 bits long.

func NewXWithRounds

func NewXWithRounds(key *memguard.LockedBuffer, nonce []byte, rounds uint8) (cipher.Stream, error)

NewXWithRounds creates and returns a new cipher.Stream just like NewX but the rounds number of 8, 12, or 20 can be specified.