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 ¶
const ChunkSize = 64 << 10
ChunkSize is the most plaintext one frame carries.
const KeySize = 32
KeySize is a data key's length: AES-256.
const Magic = "AGYPACK1\n"
Magic opens every sealed pack.
const MaxHeader = 2048
MaxHeader bounds the header a reader accepts.
Variables ¶
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 ¶
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.
Types ¶
type Header ¶
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.