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
- Variables
- func Open(w io.Writer, r io.Reader, device string, key *ecdh.PrivateKey, job string) error
- func Pack(w io.Writer, dir string) error
- func Seal(w io.Writer, plaintext io.Reader, to []To, job string) error
- func Unpack(r io.Reader, dir string) error
- type Header
- type Recipient
- type To
Constants ¶
const ChunkSize = 64 << 10
ChunkSize is the most plaintext one frame carries.
const Magic = "AGYRHO1\n"
Magic opens every sealed output.
const MaxHeader = 64 << 10
MaxHeader bounds the header a reader accepts.
const MaxOutput = 4 << 30
MaxOutput bounds the plaintext of one run's output: what Pack packs and Unpack takes.
Variables ¶
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 ¶
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 ¶
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.
Types ¶
type Header ¶
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.