naclpipe

README

naclpipe

NaCL Pipe Go Package

Purpose

A simple experimental Go package providing an io.Reader/io.Writer interface with an NaCL (pronounced 'Salt') crypto backend.

• np* is the previously called naclpipe tool using this Go package.

ChangeLog

• 2018-11-17

  • remove old unsafe backware compatibility code.
  • tagged 0.2.0

• 2018-06-24

  • added argon2id key derivation function.
  • upgraded the key derivation function and the parameters to a 2018 flavor.
  • added some godoc documentation

• 2018-04-01

  • separating command 'np' and package 'naclpipe', this way package can eventually be reused as "crypto" stream.
  • reusable io.Reader/Writer interface.
  • Starting 'semver' and documenting, first version will be 0.1.0

• 2018-03-24

  • fixing the empty scrypt salt reported by Tom Eklof
  • better handling of pipe input.
  • the structure has changed as the CSPRNG'ed salt is prefixed to the series of blocks

Package Example Usage

import "github.com/unix4fun/naclpipe"

// block size can be arbitrary, we read in block of datas
block := make([]byte, 8192)

// initilize my reader from stdin
cryptoReader, err := naclpipe.NewReader(os.Stdin, "mysuperduperpassword", naclpipe.DerivateArgon2id)
if err != nil {
    log.Fatalf("naclpipe error")
}

// read & decipher in block
_, err := cryptoReader.Read(b)

Package Usage Example / Tool

see np.

Package Doc

• godoc

Featuring (because there is always a star in your production..)

• NaCL ECC 25519 box/secretbox Go implementation AEAD using Salsa20 w/ Poly1305 MAC
• Argon2 for today key stretching.
• Scrypt for key stretching.
• SHA-3 for NONCE generation.
• Go because it works.

Documentation

Overview

Package naclpipe provides io.Reader / io.Writer compatible crypto interface it is possible to create a transparent crypto interface on top of an io.Reader/io.Writer pattern.

Index

• Constants
• Variables
• func NewReader(r io.Reader, password string, derivation int) (io.Reader, error)
• func NewWriter(w io.Writer, password string, derivation int) (io.Writer, error)
• type Argon2Params
• type NaclPipe
  • func (c *NaclPipe) Read(p []byte) (n int, err error)
  • func (c *NaclPipe) Write(p []byte) (n int, err error)
• type ScryptParams

Constants

const (
	SaltLength    = 32
	OldSaltLength = 16

	// we use argon 2id by default
	DerivateScrypt = iota
	DerivateArgon2id
)

INIT / INTERNAL

const Version string = "0.2.0"

Variables

var (
	// ErrUnsupported triggers for using an unsupported derivation function.
	ErrUnsupported = errors.New("unsupported option")
	// ErrUnsafe triggers for unsafe key derivation function.
	ErrUnsafe = errors.New("unsafe option")
	// ErrRead triggers on an error from the underlying io.Reader
	ErrRead = errors.New("read error")
	// ErrWrite triggers on an error from the underlying io.Writer
	ErrWrite = errors.New("write error")
)

Functions

func NewReader

func NewReader(r io.Reader, password string, derivation int) (io.Reader, error)

NewReader initialize an io.Reader using 'password' and the selected derivation function. Example:

cryptoReader, err := naclpipe.NewReader(os.Stdin, "mypassword", naclpipe.DerivateScrypt)
if err != nil {
	return err
}

func NewWriter

func NewWriter(w io.Writer, password string, derivation int) (io.Writer, error)

NewWriter initialize an io.Writer using 'password' and the selected derivation function. Example:

cryptoWriter, err := naclpipe.NewWriter(os.Stdout, "mypassword", naclpipe.DerivateScrypt)
if err != nil {
	return err
}

Types

type Argon2Params

type Argon2Params struct {
	CostTime    uint32
	CostMemory  uint32
	CostThreads uint8
	KeyLength   uint32
}

Argon2Params describes the parameters used for calling the Argon2id key derivation function.

type NaclPipe

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

NaclPipe define the structure that handle the crypto pipe operation it also holds all internal datas related to the running pipe.

func (*NaclPipe) Read

func (c *NaclPipe) Read(p []byte) (n int, err error)

Read will read the amount of

func (*NaclPipe) Write

func (c *NaclPipe) Write(p []byte) (n int, err error)

SHA3 the counter use it as nonce

type ScryptParams

type ScryptParams struct {
	CostParam int
	CostN     int
	CostP     int
	SaltLen   int
	KeyLength int
}

ScryptParams describes the parameters used for calling the scrypt key derivation function.