crypto

Documentation

Overview

Package crypto provides all cryptographic operations needed in restic.

Index

• Constants
• Variables
• func NewRandomNonce() []byte
• func NewSalt() ([]byte, error)
• type EncryptionKey
  • func (k *EncryptionKey) MarshalJSON() ([]byte, error)
  • func (k *EncryptionKey) UnmarshalJSON(data []byte) error
  • func (k *EncryptionKey) Valid() bool
• type Key
  • func KDF(p Params, salt []byte, password string) (*Key, error)
  • func NewRandomKey() *Key
  • func (k *Key) NonceSize() int
  • func (k *Key) Open(dst, nonce, ciphertext, additionalData []byte) ([]byte, error)
  • func (k *Key) Overhead() int
  • func (k *Key) Seal(dst, nonce, plaintext, additionalData []byte) []byte
  • func (k *Key) Valid() bool
• type MACKey
  • func (m *MACKey) MarshalJSON() ([]byte, error)
  • func (m *MACKey) UnmarshalJSON(data []byte) error
  • func (m *MACKey) Valid() bool
• type Params
  • func Calibrate(timeout time.Duration, memory int) (Params, error)

Constants

const (

	// Extension is the number of bytes a plaintext is enlarged by encrypting it.
	Extension = ivSize + macSize
)

Variables

var DefaultKDFParams = Params{
	N: sscrypt.DefaultParams.N,
	R: sscrypt.DefaultParams.R,
	P: sscrypt.DefaultParams.P,
}

DefaultKDFParams are the default parameters used for Calibrate and KDF().

var ErrInvalidCiphertext = errors.New("invalid ciphertext, same slice used for plaintext")

ErrInvalidCiphertext is returned when trying to encrypt into the slice that holds the plaintext.

var (
	// ErrUnauthenticated is returned when ciphertext verification has failed.
	ErrUnauthenticated = errors.New("ciphertext verification failed")
)

Functions

func NewRandomNonce

func NewRandomNonce() []byte

NewRandomNonce returns a new random nonce. It panics on error so that the program is safely terminated.

func NewSalt

func NewSalt() ([]byte, error)

NewSalt returns new random salt bytes to use with KDF(). If NewSalt returns an error, this is a grave situation and the program must abort and terminate.

Types

type EncryptionKey

type EncryptionKey [32]byte

EncryptionKey is key used for encryption

func (*EncryptionKey) MarshalJSON

func (k *EncryptionKey) MarshalJSON() ([]byte, error)

MarshalJSON converts the EncryptionKey to JSON.

func (*EncryptionKey) UnmarshalJSON

func (k *EncryptionKey) UnmarshalJSON(data []byte) error

UnmarshalJSON fills the key k with data from the JSON representation.

func (*EncryptionKey) Valid

func (k *EncryptionKey) Valid() bool

Valid tests whether the key k is valid (i.e. not zero).

type Key

type Key struct {
	MACKey        `json:"mac"`
	EncryptionKey `json:"encrypt"`
}

Key holds encryption and message authentication keys for a repository. It is stored encrypted and authenticated as a JSON data structure in the Data field of the Key structure.

func KDF

func KDF(p Params, salt []byte, password string) (*Key, error)

KDF derives encryption and message authentication keys from the password using the supplied parameters N, R and P and the Salt.

func NewRandomKey

func NewRandomKey() *Key

NewRandomKey returns new encryption and message authentication keys.

func (*Key) NonceSize

func (k *Key) NonceSize() int

NonceSize returns the size of the nonce that must be passed to Seal and Open.

func (*Key) Open

func (k *Key) Open(dst, nonce, ciphertext, additionalData []byte) ([]byte, error)

Open decrypts and authenticates ciphertext, authenticates the additional data and, if successful, appends the resulting plaintext to dst, returning the updated slice. The nonce must be NonceSize() bytes long and both it and the additional data must match the value passed to Seal.

The ciphertext and dst may alias exactly or not at all. To reuse ciphertext's storage for the decrypted output, use ciphertext[:0] as dst.

Even if the function fails, the contents of dst, up to its capacity, may be overwritten.

func (*Key) Overhead

func (k *Key) Overhead() int

Overhead returns the maximum difference between the lengths of a plaintext and its ciphertext.

func (*Key) Seal

func (k *Key) Seal(dst, nonce, plaintext, additionalData []byte) []byte

Seal encrypts and authenticates plaintext, authenticates the additional data and appends the result to dst, returning the updated slice. The nonce must be NonceSize() bytes long and unique for all time, for a given key.

The plaintext and dst may alias exactly or not at all. To reuse plaintext's storage for the encrypted output, use plaintext[:0] as dst.

func (*Key) Valid

func (k *Key) Valid() bool

Valid tests if the key is valid.

type MACKey

type MACKey struct {
	K [16]byte // for AES-128
	R [16]byte // for Poly1305
	// contains filtered or unexported fields
}

MACKey is used to sign (authenticate) data.

func (*MACKey) MarshalJSON

func (m *MACKey) MarshalJSON() ([]byte, error)

MarshalJSON converts the MACKey to JSON.

func (*MACKey) UnmarshalJSON

func (m *MACKey) UnmarshalJSON(data []byte) error

UnmarshalJSON fills the key m with data from the JSON representation.

func (*MACKey) Valid

func (m *MACKey) Valid() bool

Valid tests whether the key k is valid (i.e. not zero).

type Params

type Params struct {
	N int
	R int
	P int
}

Params are the default parameters used for the key derivation function KDF().

func Calibrate

func Calibrate(timeout time.Duration, memory int) (Params, error)

Calibrate determines new KDF parameters for the current hardware.