pcs

README

pcs

Go module implementing the Particle Cloud Security (PCS) core: math transforms, footer v1 codec, and streaming encoder/decoder.

Part of the PCS project family alongside pcs-demo, pcs-service, pcs-files-gateway, and pcs-s3-gateway.

Install

go get github.com/eclipse-pcs/pcs@v0.1.0

Requires Go 1.26+. No dependencies beyond the standard library.

Packages

Package	Purpose
github.com/eclipse-pcs/pcs	PCS math (Split, Merge, Encrypt, Decrypt, parity), layout helpers (.ec / .oc / … suffixes, storage roles), buffered Encode / DecodeWithRecovery, SHA-256 fingerprint shards
github.com/eclipse-pcs/pcs/footer	64-byte footer v1: parse/marshal, cross-CRC and WriteID verification
github.com/eclipse-pcs/pcs/stream	O(chunk) streaming encoder and decoder with footer v1

On-disk particle layout: [ payload ][ 64-byte footer ]. See design/footer-v1.md for the canonical format spec.

Quick example

import "github.com/eclipse-pcs/pcs"

secret := []byte("Hello Freiburg")
result, err := pcs.Encode(secret)
if err != nil { /* ... */ }

particles := map[pcs.ParticleKind][]byte{}
for _, kind := range pcs.AllParticleKinds {
    particles[kind] = pcs.EncodeResultShard(result, kind)
}

inv, _ := pcs.InventoryFromPresent(map[pcs.ParticleKind]bool{ /* ... */ })
decoded, usedParity, err := pcs.DecodeWithRecovery(inv, particles, int64(len(secret)))

Consumers attach footers and handle file/object I/O themselves; this module stays storage-agnostic.

Test

go test ./...

License

Licensed under the Eclipse Public License 2.0. See NOTICE.

Documentation

Index

• Constants
• Variables
• func AllShardKeys(logicalKey string) map[ParticleKind]string
• func CRC32IEEE(data []byte) uint32
• func DecodeFingerprint(present map[ParticleKind]bool, shards map[ParticleKind][]byte) ([32]byte, error)
• func DecodeFromParticles(evenCypher, oddCypher, evenNoise, oddNoise []byte) ([]byte, error)
• func DecodeWithRecovery(inv *ParticleInventory, particles map[ParticleKind][]byte, logicalSize int64) ([]byte, bool, error)
• func Decrypt(cypher, noise []byte) ([]byte, error)
• func EncodeResultShard(r *EncodeResult, kind ParticleKind) []byte
• func Encrypt(secret, noise []byte) []byte
• func IsParticleShard(key string) bool
• func Merge(even, odd []byte) []byte
• func ParityPadded(even, odd []byte) []byte
• func ParticleSuffix(kind ParticleKind) string
• func RandomNoise(n int) ([]byte, error)
• func ReconstructEvenFromParityOdd(haveOdd, parity []byte) ([]byte, error)
• func ReconstructFromParityEven(have, parity []byte) ([]byte, error)
• func ReconstructOddFromParityOdd(haveEven, parity []byte) ([]byte, error)
• func RecoverAllFingerprintShards(present map[ParticleKind]bool, shards map[ParticleKind][]byte) (map[ParticleKind][]byte, error)
• func RecoverCoreParticlesInto(inv *ParticleInventory, data map[ParticleKind][]byte, logicalSize int64) error
• func ShardKey(logicalKey string, kind ParticleKind) string
• func Split(text []byte) ([]byte, []byte)
• func StorageForParticle(kind ParticleKind) string
• type EncodeResult
  • func Encode(secret []byte) (*EncodeResult, error)
  • func EncodeFingerprint(digest [32]byte) (*EncodeResult, error)
  • func EncodeWithNoise(secret, noise []byte) (*EncodeResult, error)
• type ParticleInventory
  • func InventoryFromPresent(present map[ParticleKind]bool) (*ParticleInventory, error)
  • func NewParticleInventory(present map[ParticleKind]bool) *ParticleInventory
  • func (inv *ParticleInventory) MissingCoreParticles() []ParticleKind
  • func (inv *ParticleInventory) NeedsParityRecovery() bool
• type ParticleKind
  • func LogicalKeyFromShard(shardKey string) (logicalKey string, kind ParticleKind, ok bool)
  • func (k ParticleKind) String() string

Constants

const (
	StorageA = "storageA"
	StorageB = "storageB"
	StorageC = "storageC"
)

Logical storage roles.

Variables

var (
	// AllParticleKinds lists all six particle kinds in stable order.
	AllParticleKinds = []ParticleKind{
		EvenCypher, OddCypher, EvenNoise, OddNoise, CypherParity, NoiseParity,
	}
	// CoreParticleKinds are the four payload-determining particles.
	CoreParticleKinds = []ParticleKind{EvenCypher, OddCypher, EvenNoise, OddNoise}
)

Functions

func AllShardKeys

func AllShardKeys(logicalKey string) map[ParticleKind]string

AllShardKeys returns all six shard keys for a logical object key.

func CRC32IEEE

func CRC32IEEE(data []byte) uint32

CRC32IEEE returns the CRC-32 (IEEE) checksum of data.

func DecodeFingerprint

func DecodeFingerprint(present map[ParticleKind]bool, shards map[ParticleKind][]byte) ([32]byte, error)

DecodeFingerprint reconstructs the digest from six fingerprint shard blobs.

func DecodeFromParticles

func DecodeFromParticles(evenCypher, oddCypher, evenNoise, oddNoise []byte) ([]byte, error)

DecodeFromParticles reconstructs the original secret from four core particles.

func DecodeWithRecovery

func DecodeWithRecovery(inv *ParticleInventory, particles map[ParticleKind][]byte, logicalSize int64) ([]byte, bool, error)

DecodeWithRecovery reconstructs the secret using parity when cores are missing.

func Decrypt

func Decrypt(cypher, noise []byte) ([]byte, error)

Decrypt XORs cypher with noise to recover the secret.

func EncodeResultShard

func EncodeResultShard(r *EncodeResult, kind ParticleKind) []byte

EncodeResultShard returns the particle bytes for kind from an encode result.

func Encrypt

func Encrypt(secret, noise []byte) []byte

Encrypt XORs secret with noise of equal length.

func IsParticleShard

func IsParticleShard(key string) bool

IsParticleShard reports whether key ends with a known particle suffix.

func Merge

func Merge(even, odd []byte) []byte

Merge interleaves even and odd streams back into original byte order.

func ParityPadded

func ParityPadded(even, odd []byte) []byte

ParityPadded computes XOR parity with odd-length tail handling.

func ParticleSuffix

func ParticleSuffix(kind ParticleKind) string

ParticleSuffix returns the unified particle suffix for kind.

func RandomNoise

func RandomNoise(n int) ([]byte, error)

RandomNoise returns n cryptographically secure random bytes.

func ReconstructEvenFromParityOdd

func ReconstructEvenFromParityOdd(haveOdd, parity []byte) ([]byte, error)

ReconstructEvenFromParityOdd rebuilds the even particle from odd + parity (odd original length).

func ReconstructFromParityEven

func ReconstructFromParityEven(have, parity []byte) ([]byte, error)

ReconstructFromParityEven rebuilds the missing partner when both particles are equal length.

func ReconstructOddFromParityOdd

func ReconstructOddFromParityOdd(haveEven, parity []byte) ([]byte, error)

ReconstructOddFromParityOdd rebuilds the odd particle from even + parity (odd original length).

func RecoverAllFingerprintShards

func RecoverAllFingerprintShards(present map[ParticleKind]bool, shards map[ParticleKind][]byte) (map[ParticleKind][]byte, error)

RecoverAllFingerprintShards recovers missing fingerprint shards via parity math.

func RecoverCoreParticlesInto

func RecoverCoreParticlesInto(inv *ParticleInventory, data map[ParticleKind][]byte, logicalSize int64) error

RecoverCoreParticlesInto fills missing core particles using parity shards.

func ShardKey

func ShardKey(logicalKey string, kind ParticleKind) string

ShardKey returns the full shard key for a logical key and particle kind.

func Split

func Split(text []byte) ([]byte, []byte)

Split separates text into even-indexed and odd-indexed bytes.

func StorageForParticle

func StorageForParticle(kind ParticleKind) string

StorageForParticle returns the storage role that holds the given particle.

Types

type EncodeResult

type EncodeResult struct {
	EvenCypher   []byte
	OddCypher    []byte
	EvenNoise    []byte
	OddNoise     []byte
	CypherParity []byte
	NoiseParity  []byte
}

EncodeResult holds the six particle payloads from a PCS encode.

func Encode

func Encode(secret []byte) (*EncodeResult, error)

Encode generates random noise and PCS-encodes secret.

func EncodeFingerprint

func EncodeFingerprint(digest [32]byte) (*EncodeResult, error)

EncodeFingerprint PCS-encodes a 32-byte SHA-256 digest.

func EncodeWithNoise

func EncodeWithNoise(secret, noise []byte) (*EncodeResult, error)

EncodeWithNoise runs the PCS encode pipeline with caller-supplied noise.

type ParticleInventory

type ParticleInventory struct {
	Present map[ParticleKind]bool
}

ParticleInventory tracks which particles are present for one logical object.

func InventoryFromPresent

func InventoryFromPresent(present map[ParticleKind]bool) (*ParticleInventory, error)

InventoryFromPresent builds an inventory from remote presence information.

func NewParticleInventory

func NewParticleInventory(present map[ParticleKind]bool) *ParticleInventory

NewParticleInventory builds an inventory from a presence map.

func (*ParticleInventory) MissingCoreParticles

func (inv *ParticleInventory) MissingCoreParticles() []ParticleKind

func (*ParticleInventory) NeedsParityRecovery

func (inv *ParticleInventory) NeedsParityRecovery() bool

type ParticleKind

type ParticleKind int

ParticleKind identifies one of the six particles in footer order.

const (
	EvenCypher ParticleKind = iota
	OddCypher
	EvenNoise
	OddNoise
	CypherParity
	NoiseParity
)

func LogicalKeyFromShard

func LogicalKeyFromShard(shardKey string) (logicalKey string, kind ParticleKind, ok bool)

LogicalKeyFromShard strips a known particle suffix and returns the logical key.

func (ParticleKind) String

func (k ParticleKind) String() string