eris

README

eris-go

eris-go is a package that implements encoding and decoding of the Encoding for Robust Immutable Storage (ERIS) format.

ERIS is an encoding of arbitrary content into a set of uniformly sized, encrypted and content-addressed blocks as well as a short identifier that can be encoded as an URN. The content can be reassembled from the blocks only with this identifier. The encoding is defined independent of any storage and transport layer or any specific application.

This package does not implement any storage layer, but only concerns itself with the encoding and decoding of content. Users of this package are expected to implement their own storage layer, which can be as simple as files stored on-disk. Example(s) of how to use this package are provided in the 'examples' directory.

This package intentionally does not have any dependencies other than Go's x/crypto library for cryptographic primitives.

See the spec for more details on the format.

Documentation

Overview

Package eris implements the Encoding for Robust Immutable Storage (ERIS) encoding, version 1.0.0, as described in the spec:

https://eris.codeberg.page/spec/

ERIS is an encoding of arbitrary content into a set of uniformly sized, encrypted and content-addressed blocks as well as a short identifier that can be encoded as an URN. The content can be reassembled from the blocks only with this identifier. The encoding is defined independent of any storage and transport layer or any specific application.

This package does not implement any storage layer, but only concerns itself with the encoding and decoding of content. Users of this package are expected to implement their own storage layer, which can be as simple as files stored on-disk. Example(s) of how to use this package are provided in the 'examples' directory.

This package intentionally does not have any dependencies other than Go's x/crypto library for cryptographic primitives.

Index

• Constants
• Variables
• func DecodeRecursive(ctx context.Context, fetch FetchFunc, rc ReadCapability) ([]byte, error)
• type Decoder
  • func NewDecoder(fetch FetchFunc, rc ReadCapability) *Decoder
  • func (d *Decoder) Block() []byte
  • func (d *Decoder) Err() error
  • func (d *Decoder) Next(ctx context.Context) bool
• type Encoder
  • func NewEncoder(content io.Reader, secret [ConvergenceSecretSize]byte, blockSize int) *Encoder
  • func (e *Encoder) Block() []byte
  • func (e *Encoder) Capability() ReadCapability
  • func (e *Encoder) Err() error
  • func (e *Encoder) Next() bool
  • func (e *Encoder) Reference() Reference
• type FetchFunc
• type Key
  • func (k Key) String() string
• type ReadCapability
  • func ParseReadCapabilityURN(urn string) (rc ReadCapability, err error)
  • func (rc ReadCapability) AppendBinary(data []byte) ([]byte, error)
  • func (rc ReadCapability) Equal(other ReadCapability) bool
  • func (rc ReadCapability) MarshalBinary() (data []byte, err error)
  • func (rc ReadCapability) MustURN() string
  • func (rc ReadCapability) URN() (string, error)
  • func (rc *ReadCapability) UnmarshalBinary(data []byte) error
• type Reference
  • func (r Reference) String() string
• type ReferenceKeyPair
  • func (rk ReferenceKeyPair) Equal(other ReferenceKeyPair) bool

Constants

const (
	// ReferenceSize is the size of the reference hash.
	ReferenceSize = blake2b.Size256

	// KeySize is the size of the encryption key.
	KeySize = chacha20.KeySize

	// ConvergenceSecretSize is the length of the convergence secret.
	ConvergenceSecretSize = 32
)

Variables

var (
	ErrInvalidBlockSize = errors.New("invalid block size")
	ErrInvalidBlock     = errors.New("invalid block")
	ErrInvalidPadding   = errors.New("invalid padding")
	ErrInvalidKey       = errors.New("key in read capability is invalid")
)

Functions

func DecodeRecursive

func DecodeRecursive(ctx context.Context, fetch FetchFunc, rc ReadCapability) ([]byte, error)

DecodeRecursive recursively decodes the content of an ERIS tree rooted at rc and returns the content, or an error if the content could not be decoded.

The fetch function is called to fetch blocks of data from some backing store; see the documentation for FetchFunc for the exact semantics.

The provided context is passed to the fetch function.

Types

type Decoder

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

Decoder provides a streaming interface that can be used to decode an ERIS-encoded stream of content into the original data. Successive calls to the Decoder.Next method will fetch blocks of the ERIS-encoded tree and decode them, until a block of data has been retrieved or an error occurs.

It is agnostic to how encrypted blocks of data are fetched or how output is written, and it is up to the caller to perform these operations.

func NewDecoder

func NewDecoder(fetch FetchFunc, rc ReadCapability) *Decoder

NewDecoder creates a new Decoder instance which will use the provided fetch function to fetch encrypted blocks of data, starting at the root of the tree as described by rc.

func (*Decoder) Block

func (d *Decoder) Block() []byte

Block returns the next block of the original content.

The underlying array may point to data that will be overwritten by a subsequent call to Next. It does no allocation.

func (*Decoder) Err

func (d *Decoder) Err() error

Err returns the error that occurred during decoding, if any.

func (*Decoder) Next

func (d *Decoder) Next(ctx context.Context) bool

Next will fetch blocks of the ERIS-encoded tree and decode them until it retrieves a block of the original content or until an error occurs.

If an error occurs or decoding is finished, the function will return false. The caller should call the Err method to check if an error occurred.

If no error occurs and decoding is not finished, the function will return true and the Block function can be called to retrieve the next block of the original content.

The provided Context will be passed to the fetch function.

type Encoder

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

Encoder is used to encode some content into the ERIS format: a set of encrypted blocks, and a "read capability" that contains all the information needed to read and decrypt the content.

func NewEncoder

func NewEncoder(content io.Reader, secret [ConvergenceSecretSize]byte, blockSize int) *Encoder

func (*Encoder) Block

func (e *Encoder) Block() []byte

Block returns the current block of data that was encoded.

It is only valid to call this method after a call to the Next method has returned true.

func (*Encoder) Capability

func (e *Encoder) Capability() ReadCapability

Capability returns the read capability that can be used to read the encoded data.

It is only valid to call this method after a call to the Next method has returned false, and if there was no error.

func (*Encoder) Err

func (e *Encoder) Err() error

Err returns the error that caused the encoder to stop, if any.

func (*Encoder) Next

func (e *Encoder) Next() bool

Next will advance the state of the Encoder and return true if there is more work to be done.

When Next returns true, the caller should call the Block() method to get the next block of data that was encoded.

When Next returns false, the caller should first check the Err() method to see if there was an error. If no error occurred, the caller should then call the Capability() method to get the read capability that can be used to read the encoded data.

func (*Encoder) Reference

func (e *Encoder) Reference() Reference

Reference returns the Reference of the current block of data that was encoded.

It is only valid to call this method after a call to the Next method has returned true.

type FetchFunc

type FetchFunc func(ctx context.Context, ref Reference, buf []byte) ([]byte, error)

FetchFunc is the function signature for a function that fetches an encrypted block of data from some sort of storage given a block reference. The buf parameter is a slice that is guaranteed to be at least the size of a block; the function can reuse this storage if it wants, or it can allocate and return a new slice.

type Key

type Key [KeySize]byte

Key is the encryption key required to decrypt the block of data. It is defined in the ERIS specification as:

key is the ChaCha20 key to decrypt the block (32 bytes)

func (Key) String

func (k Key) String() string

String implements the fmt.Stringer interface.

type ReadCapability

type ReadCapability struct {
	// BlockSize is the size of the blocks that the content has been split
	// into.
	BlockSize int
	// Level is the level of the root node of the tree.
	Level int
	// Root is the reference-key pair for the root node of the tree.
	Root ReferenceKeyPair
}

ReadCapability is all the information required to read a piece of content that has been split and encrypted as per the ERIS specification.

func ParseReadCapabilityURN

func ParseReadCapabilityURN(urn string) (rc ReadCapability, err error)

ParseReadCapabilityURN parses a URN for a ReadCapability, as defined in the ERIS specification, section 2.7.

func (ReadCapability) AppendBinary

func (rc ReadCapability) AppendBinary(data []byte) ([]byte, error)

AppendBinary appends the binary representation of the ReadCapability to the given byte slice and returns it, or any error that occurs.

The binary representation of a ReadCapability is as per the ERIS specification, section 2.6.

func (ReadCapability) Equal

func (rc ReadCapability) Equal(other ReadCapability) bool

Equal returns true if the two ReadCapabilities are equal.

func (ReadCapability) MarshalBinary

func (rc ReadCapability) MarshalBinary() (data []byte, err error)

MarshalBinary implements the encoding.BinaryMarshaler interface.

The binary representation of a ReadCapability is as per the ERIS specification, section 2.6.

func (ReadCapability) MustURN

func (rc ReadCapability) MustURN() string

MustURN is like URN, but panics if an error occurs.

func (ReadCapability) URN

func (rc ReadCapability) URN() (string, error)

URN returns the URN for the ReadCapability, as defined in the ERIS specification, section 2.7.

func (*ReadCapability) UnmarshalBinary

func (rc *ReadCapability) UnmarshalBinary(data []byte) error

UnmarshalBinary implements the encoding.BinaryUnmarshaler interface.

The binary representation of a ReadCapability is as per the ERIS specification, section 2.6.

type Reference

type Reference [ReferenceSize]byte

Reference is a hash of an encrypted block of data. It is defined in the ERIS specification as:

The reference is the unkeyed Blake2b hash of the encrypted block (32 bytes)

func (Reference) String

func (r Reference) String() string

String implements the fmt.Stringer interface.

type ReferenceKeyPair

type ReferenceKeyPair struct {
	Reference Reference
	Key       Key
}

ReferenceKeyPair represents a pairing of a block reference and the key required to decrypt the block.

func (ReferenceKeyPair) Equal

func (rk ReferenceKeyPair) Equal(other ReferenceKeyPair) bool

Equal returns true if the two ReferenceKeyPairs are equal.