padsecret

README

padsecret (golang package)

Padsecret provides a simple way to encrypt or decrypt a message using NaCl secret key cryptography. Optionally it can compress the data before encrypting them.

The encryption key is padded with a user provided pad. Padsecret is very fast, thus it is useful when you want to exchange many messages. It is less secure from saltsecret, due to the constant user provided pad and some other design decisions (i.e key arguments as strings).

Beyond the default methods (Encrypt(msg []byte), Decrypt(msg []byte)), it also provides an io.Reader and an io.Writer interface to decrypt or encrypt data. Since we don't have a stream cipher, these methods need to have available all the data before they make available their output. For Writer this means you have to Flush() or Close() before you can read the io.Writer you passed to the Writer. For Reader it means it will block until it reads all the data from the io.Reader you passed to it.

Read and Write are slower than Decrypt and Encrypt.

I use it for symmetric-key encryption schemes. Depending on your usage it may or may not be a safe option. I do not claim any expertise in cryptography.

Note: The compression status is set inside the message (last bit of the nonce), thus whilst you do need to have a common key and padding between two processes exchanging messages, you do not need to have a common compression setting.

Usage

import "github.com/andmarios/crypto/nacl/padsecret"

Example

You may find more examples in the examples directory.

package main

import (
	"github.com/andmarios/crypto/nacl/padsecret"
	"log"
)

func main() {
	// Create a padsecret instance with "qwerty" key and no compression.
	c, err := padsecret.New("qwerty", "qwertyuiopasdfghjklzxcvbnm123456", false)
	if err != nil {
		log.Fatalln(err)
	}

	// Message to be encrypted
	msg := []byte("Hello World")

	// Encrypt message
	encMsg, err := c.Encrypt(msg)
	if err != nil {
		log.Fatalln(err.Error())
	}

	// Decrypt message
	decMsg, err := c.Decrypt(encMsg)
	if err != nil {
		log.Fatalln("Could not decrypt message")
	}
	log.Printf("Decrypted message is '%s'.\n", decMsg)
}

License

You can find more information inside the LICENSE file. In short this software uses a BSD 3-Clause license.

Documentation

Overview

Package padsecret implements a simple library for on-the-fly NaCl secret key (symmetric) encryption and decryption with a padded key.

It is meant to be used for symmetric-key encryption schemes. Optionally it can (de)compress the data before (dec)encryption.

The user key is padded with a user provided pad. The key is common for all messages that come from a padsecret instance. This makes padsecret very fast, albeit less secure.

Beyond the recommended methods (Encrypt, Decrypt) it also implements the io.ReadWriter interface which is slower. You may run the benchmarks from padsecret_test.go to decide if it is acceptable.

One bit of the NaCl's nonce is used to indicate whether the message was compressed before encrypting. Still the algorithm should remain safe since nonce collisions are again extremely rare.

Index

• Constants
• type PadSecret
  • func New(key, pad string, compress bool) (*PadSecret, error)
  • func (c PadSecret) Decrypt(msg []byte) ([]byte, error)
  • func (c PadSecret) Encrypt(msg []byte) (out []byte, e error)
• type Reader
  • func NewReader(r io.Reader, key, pad string, mode int, compress bool) (*Reader, error)
  • func (d *Reader) Read(p []byte) (n int, err error)
  • func (d *Reader) Reset(r io.Reader)
• type Writer
  • func NewWriter(w io.Writer, key, pad string, mode int, compress bool) (*Writer, error)
  • func (e *Writer) Close() error
  • func (e *Writer) Flush() error
  • func (e *Writer) Reset(w io.Writer)
  • func (e *Writer) Write(p []byte) (n int, err error)

Examples

• PadSecret.Decrypt
• PadSecret.Encrypt

Constants

const (
	ENCRYPT = iota
	DECRYPT
)

Operation mode for Reader and Writer

Types

type PadSecret

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

A PadSecret holds the instance's key and the compression settings.

func New

func New(key, pad string, compress bool) (*PadSecret, error)

New creates a new PadSecret instance. key is the key used for encryption, pad is the padding to be used (at least 32 bytes), if the key is smaller than 32 bytes. compress indicates whether the data should be compessed (zlib) before encrypting. The pad can be a const in your code.

func (PadSecret) Decrypt

func (c PadSecret) Decrypt(msg []byte) ([]byte, error)

Decrypt decrypts an encrypted message and returns it (plaintext). If you have enabled compression, it wil detect it and decompress the msg after decrypting it.

Example

package main

import (
	"fmt"
	"log"

	"github.com/andmarios/crypto/nacl/padsecret"
)

func main() {
	// Create a padsecret instance with "password" key and no compression.
	c, err := padsecret.New("password", "qwertyuiopasdfghjklzxcvbnm123456", false)
	if err != nil {
		log.Fatalln(err)
	}

	encryptedMsg := []byte{24, 68, 38, 21, 142, 73, 109, 222, 45, 135, 233,
		83, 12, 196, 148, 10, 195, 133, 33, 12, 86, 15, 78, 100, 164,
		74, 190, 96, 174, 182, 134, 119, 13, 12, 132, 189, 125, 16, 205,
		79, 14, 204, 15, 20, 235, 42, 24, 4, 7, 82, 39}

	// Decrypt message
	decryptedMsg, err := c.Decrypt(encryptedMsg)
	if err != nil {
		log.Fatalln(err)
	}
	fmt.Printf("Decrypted message is '%s'.\n", decryptedMsg)
}

Output:

Decrypted message is 'Hello World'.

func (PadSecret) Encrypt

func (c PadSecret) Encrypt(msg []byte) (out []byte, e error)

Encrypt encrypts a message and returns the encrypted msg (nonce + ciphertext). If you have enabled compression, it will compress the msg before encrypting it.

Example

package main

import (
	"fmt"
	"log"

	"github.com/andmarios/crypto/nacl/padsecret"
)

func main() {
	// Create a padsecret instance with "password" key and no compression.
	c, err := padsecret.New("password", "qwertyuiopasdfghjklzxcvbnm123456", false)
	if err != nil {
		log.Fatalln(err)
	}

	// Message to be encrypted
	msg := []byte("Hello World")

	// Encrypt message
	encryptedMsg, err := c.Encrypt(msg)
	if err != nil {
		log.Fatalln(err)
	}

	fmt.Println("Encrypted message:", encryptedMsg)
}

type Reader

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

A Reader reads data from another Reader, encrypts or decrypts and, if needed, (de)compress them into a []byte variable. A Reader may be re-used by using Reset.

func NewReader

func NewReader(r io.Reader, key, pad string, mode int, compress bool) (*Reader, error)

NewReader creates a new Reader. Reads from the returned Reader read, encrypt or decrypt (and (de)compress, if needed), data from r. The implementation needs to read all data from r at once, since we do not use a stream cipher. mode is either saltsecret.ENCRYPT (0), or saltsecret.DECRYPT (1). Pad should be at least 32 bytes long.

func (*Reader) Read

func (d *Reader) Read(p []byte) (n int, err error)

Read reads into p an encrypted or decrypted and, if needed, (de)compressed form of the bytes from the underlying Reader. Read needs to read all data from the underlying Reader before it can operate on them.

func (*Reader) Reset

func (d *Reader) Reset(r io.Reader)

Reset returns Reader to its initial state, except it now reads from r.

type Writer

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

A Writer takes data written to it and writes the encrypted or decrypted and, if needed, (de)compressed form of that data to an underlying writer.

func NewWriter

func NewWriter(w io.Writer, key, pad string, mode int, compress bool) (*Writer, error)

NewWriter creates a new writer. Writes to the returned Writer are encrypted or decrypted and, if needed, (de)compressed and written to w.

It is the caller's responsibility to call Close() on WriteCloser when done, since we do not use a stream cipher, we need to have all the data before operating on them. Pad should be at least 32 bytes long.

func (*Writer) Close

func (e *Writer) Close() error

Close acts as a placeholder for Flush.

func (*Writer) Flush

func (e *Writer) Flush() error

Flush encrypt or decrypts and (de)compresses, if needed, the data written to the writer. After a Flush, the writer has to be Reset in order to write to it again.

func (*Writer) Reset

func (e *Writer) Reset(w io.Writer)

Reset clears the sate of the Writer w such that it is equivalent to its initial state from NewWriter, but instead writing to w.

func (*Writer) Write

func (e *Writer) Write(p []byte) (n int, err error)

Write writes and encrypts or decrypts (and, if needed, a (de)compressed) form of p to the underlying io.Writer. The produced bytes are not written until the Writer is closed or explicitly flushed.