packseal

package
v0.7.15 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 10, 2026 License: MIT Imports: 11 Imported by: 0

Documentation

Overview

Package packseal is the sealed form of a knowledge pack: the pack's tree, as one tar, encrypted under a random data key of its own, so that neither a laptop's store nor Agentry's holds a pack's pages in the clear. The data key is never stored beside it in the clear: it is wrapped, by the registry the person is signed in to or, signed out, by a key on the machine. It is the core's, open, so the CLI, the desktop and the registry all read and write the same bytes.

The layout, all integers big-endian:

magic    "AGYPACK1\n"
uint32   header length, then the header (JSON, below)
frames:  uint32 length, then that many bytes of ciphertext

Each frame is at most ChunkSize bytes of plaintext sealed with AES-256-GCM under the data key. Its nonce is the header's random prefix and the frame's index; its additional data is the header's SHA-256, the frame's index and whether it is the last, so a frame cannot be altered, moved, dropped or repeated, the header cannot be changed, and a stream cut short at a frame boundary does not open (the last frame says it is the last). It follows the framing of the hosted run's sealed output (the enterprise build's runout package), with a data key in place of HPKE.

Index

Constants

View Source
const ChunkSize = 64 << 10

ChunkSize is the most plaintext one frame carries.

View Source
const KeySize = 32

KeySize is a data key's length: AES-256.

View Source
const Magic = "AGYPACK1\n"

Magic opens every sealed pack.

View Source
const MaxHeader = 2048

MaxHeader bounds the header a reader accepts.

Variables

View Source
var (
	// ErrFormat is a stream that is not a sealed pack of this version.
	ErrFormat = errors.New("packseal: not a sealed knowledge pack")
	// ErrOpen is every failure to open one: a wrong key, a header or a
	// frame altered, moved or missing. Which check failed is not the
	// reader's to learn.
	ErrOpen = errors.New("packseal: the sealed pack does not open with this key")
	// ErrKey is a data key of the wrong size.
	ErrKey = errors.New("packseal: a data key is 32 bytes")
)

Functions

func MaxSealedSize

func MaxSealedSize(plain int64) int64

MaxSealedSize is the most a sealed pack of plain bytes of plaintext can be, for a caller that bounds an upload by the pack's own cap.

func NewKey

func NewKey() ([]byte, error)

NewKey is a fresh random data key.

func Seal

func Seal(w io.Writer, key []byte, h Header, plain io.Reader) error

Seal writes plain, sealed under key, to w with the header h (its Version, AEAD, Nonce and Chunk are set here).

Types

type Header struct {
	// Version is the format's version, 1.
	Version int `json:"v"`
	// AEAD names the frames' cipher, "AES-256-GCM".
	AEAD string `json:"aead"`
	// Pack is the pack's own id (its manifest's id).
	Pack string `json:"pack"`
	// Digest is the pack's tree digest ("sha256:<hex>"), as its maker
	// computed it; whoever opens it may check it against the tree.
	Digest string `json:"digest"`
	// Nonce is the random prefix of every frame's nonce, 8 bytes; the
	// frame's index fills the last 4.
	Nonce []byte `json:"nonce"`
	// Chunk is the most plaintext a frame carries, ChunkSize.
	Chunk int `json:"chunk"`
}

Header is what may be read of a sealed pack without its key: which pack it is and the digest of the tree it holds.

func Open

func Open(r io.Reader, key []byte) (Header, io.Reader, error)

Open reads a sealed pack's header and returns a reader of its plaintext, which fails with ErrOpen the moment a frame does not verify, and at the end if the last frame never came.

func ReadHeader

func ReadHeader(r io.Reader) (Header, error)

ReadHeader reads a sealed pack's header, which needs no key.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL