output

package
v0.7.29 Latest Latest
Warning

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

Go to latest
Published: Nov 7, 2026 License: MIT Imports: 19 Imported by: 0

Documentation

Overview

Package output is a remote run's output at rest on the runhost: the run's output folder packed into one tar of the members a device takes back, and that tar sealed to every paired device's sealing key, so the server keeps no plaintext output once the run has ended.

The sealed layout, all integers big-endian:

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

The tar is encrypted with a random content key, AES-256-GCM, in frames of at most ChunkSize bytes of plaintext. Each frame's nonce is its index, and its additional data is the header's SHA-256, the index and whether it is the last, so a frame cannot be moved, dropped or repeated, a stream cut at a frame boundary does not open, and a header changed in any byte (a recipient added, the job renamed) opens no frame. The content key is sealed to each device with HPKE (RFC 9180: DHKEM(X25519, HKDF-SHA256), HKDF-SHA256, AES-256-GCM), whose info names the job and the device, so a key sealed for one job or device does not open as another's.

Index

Constants

View Source
const ChunkSize = 64 << 10

ChunkSize is the most plaintext one frame carries.

View Source
const Magic = "AGYRHO1\n"

Magic opens every sealed output.

View Source
const MaxHeader = 64 << 10

MaxHeader bounds the header a reader accepts.

View Source
const MaxOutput = 4 << 30

MaxOutput bounds the plaintext of one run's output: what Pack packs and Unpack takes.

Variables

View Source
var (
	// ErrFormat is a stream that is not a sealed output of this version.
	ErrFormat = errors.New("not a sealed runhost output")
	// ErrOpen is every failure to open one: not sealed to this device, for
	// another job, a frame altered, moved or missing. Which check failed is
	// not the caller's to know.
	ErrOpen = errors.New("the sealed output does not open with this device's key")
)

Functions

func Open

func Open(w io.Writer, r io.Reader, device string, key *ecdh.PrivateKey, job string) error

Open opens a sealed output r with device's sealing key, for job, and writes its plaintext to w. It fails before writing anything when the output was not sealed to this device or for this job; an error after that means w holds part of the plaintext, which the caller must discard.

func Pack

func Pack(w io.Writer, dir string) error

Pack writes a tar of dir's members to w: regular files only, so a link the run left never carries anything from outside the folder.

func Seal

func Seal(w io.Writer, plaintext io.Reader, to []To, job string) error

Seal writes plaintext, read to its end, to w sealed to every device in to for job.

func Unpack

func Unpack(r io.Reader, dir string) error

Unpack writes the tar r into dir, which it creates: regular files only, each a member under a clean relative name, so no entry lands outside the folder or outside the members a run's output may hold.

Types

type Header struct {
	Version    int         `json:"v"`
	KEM        string      `json:"kem"`
	KDF        string      `json:"kdf"`
	AEAD       string      `json:"aead"`
	Job        string      `json:"job"`
	Chunk      int         `json:"chunk"`
	Recipients []Recipient `json:"recipients"`
}

Header is what can be read of a sealed output without a key: the job it was sealed for and the devices it was sealed to.

func ReadHeader

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

ReadHeader reads the magic and the header from r and leaves r at the first frame.

type Recipient

type Recipient struct {
	Device string `json:"device"`
	Enc    []byte `json:"enc"`
	Key    []byte `json:"key"`
}

Recipient is one device's sealed copy of the content key.

type To

type To struct {
	Device string
	Key    *ecdh.PublicKey
}

To is a device an output is sealed to.

func Devices

func Devices(keys map[string][]byte) ([]To, error)

Devices is the To list for the paired devices' sealing keys, base64 X25519 public keys by device id.

Jump to

Keyboard shortcuts

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