Documentation
¶
Overview ¶
Package readyproto defines the newline-delimited JSON handshake toolboxd sends to sandboxd when a Docker sandbox's agent is ready to serve.
Index ¶
- Constants
- Variables
- func Encode(w io.Writer, sig ReadySignal) error
- func EncodeAdopt(w io.Writer, frame AdoptFrame) error
- func EncodeParked(w io.Writer, sig ParkedSignal) error
- func EnvDigest(nonce string, env map[string]string) string
- func EnvDigestMatches(nonce string, env map[string]string, digest string) bool
- func ValidateAdoptEnv(env map[string]string) error
- type AdoptFrame
- type ParkedSignal
- type ReadySignal
Constants ¶
const ( // EventReady is the guest→host readiness announcement after adopt or cold boot. EventReady = "ready" // EventParked is the guest→host hello from a warm-pool slot awaiting adopt. EventParked = "parked" // EventAdopt is the host→guest frame that binds real sandbox identity. EventAdopt = "adopt" // MaxLineBytes caps attacker-controlled read size on the host listener. MaxLineBytes = 4 << 10 // MaxAdoptLineBytes caps an adopt frame. It is far above MaxLineBytes // because the frame carries the sandbox's env (plans/cluster-phase-2.md // §2), and it is the only line the larger cap applies to: the adopt // frame is host→guest, written by sandboxd and read by toolboxd, so the // host listener, which reads the lines a guest controls (parked hello, // ready ack), keeps the 4 KiB cap on attacker-sized reads. MaxAdoptLineBytes = 256 << 10 // MaxAdoptEnvBytes is the largest JSON-encoded env an adopt frame may // carry. The rest of the frame (event, sandbox id, token, nonce) is what // every other line already fits in MaxLineBytes, so an env within this // bound always leaves a frame within MaxAdoptLineBytes, and a create // whose env is bigger is refused from the warm pool up front rather // than failing an adopt and burning a parked slot. MaxAdoptEnvBytes = MaxAdoptLineBytes - MaxLineBytes )
Variables ¶
var ErrEnvInvalid = errors.New("readyproto: env has an empty key, a key containing '=', a NUL byte, or bytes that are not UTF-8")
ErrEnvInvalid is returned for an env an adopt frame cannot carry: an empty key, a key containing '=', a NUL byte anywhere, or bytes that are not UTF-8 (encoding/json would replace them, so the guest would get a different value). The message names neither the key nor the value, since either could be a secret pasted into the wrong field.
var ErrEnvTooLarge = fmt.Errorf("readyproto: env exceeds %d encoded bytes", MaxAdoptEnvBytes)
ErrEnvTooLarge is returned for an env whose encoding exceeds MaxAdoptEnvBytes.
Functions ¶
func Encode ¶
func Encode(w io.Writer, sig ReadySignal) error
Encode writes one newline-terminated JSON line.
func EncodeAdopt ¶
func EncodeAdopt(w io.Writer, frame AdoptFrame) error
EncodeAdopt writes a host→guest adopt frame.
func EncodeParked ¶
func EncodeParked(w io.Writer, sig ParkedSignal) error
EncodeParked writes a parked hello line.
func EnvDigest ¶ added in v0.6.12
EnvDigest is the proof a guest's ready ack carries that it applied exactly the env an adopt frame held: hex HMAC-SHA256 keyed with the adopt nonce over the env in canonical form (entries sorted by key, each "key=value" then a NUL; keys hold neither '=' nor NUL and values hold no NUL, so the form is unambiguous). Keyed with the per-adopt nonce rather than a bare hash so the ack never holds a stable fingerprint of the env: a bare hash of a low-entropy secret could be matched by hashing guesses.
func EnvDigestMatches ¶ added in v0.6.12
EnvDigestMatches reports, in constant time, whether digest is EnvDigest(nonce, env). An empty digest never matches.
func ValidateAdoptEnv ¶ added in v0.6.12
ValidateAdoptEnv reports whether env can ride an adopt frame: every entry is one a process environment can carry, and the encoding fits within MaxAdoptEnvBytes. The host checks it before it takes a parked slot for a create, so an env the frame cannot carry sends the create cold instead of failing the adopt after the slot is spent. Errors are ErrEnvInvalid or ErrEnvTooLarge, which quote nothing from env.
Types ¶
type AdoptFrame ¶
type AdoptFrame struct {
Event string `json:"event"`
SandboxID string `json:"sandbox_id"`
Token string `json:"token"`
Nonce string `json:"nonce"`
// Env is the sandbox's env. The guest loads it before it takes the
// identity and starts the held-back image command, so that command,
// exec and sessions all see it. Omitted when empty, so an env-less
// adopt is the same bytes an older agent has always read.
Env map[string]string `json:"env,omitempty"`
}
AdoptFrame is the host→guest identity bind during warm-pool adoption.
func DecodeAdopt ¶
func DecodeAdopt(r io.Reader) (AdoptFrame, error)
DecodeAdopt reads a host→guest adopt frame.
type ParkedSignal ¶
type ParkedSignal struct {
Event string `json:"event"`
Token string `json:"token"`
Nonce string `json:"nonce"`
AgentVersion string `json:"agent_version,omitempty"`
}
ParkedSignal is the guest→host parked-slot hello.
func DecodeParked ¶
func DecodeParked(r io.Reader) (ParkedSignal, error)
DecodeParked reads a guest→host parked hello.
type ReadySignal ¶
type ReadySignal struct {
Event string `json:"event"`
SandboxID string `json:"sandbox_id"`
Token string `json:"token"`
Nonce string `json:"nonce"`
AgentVersion string `json:"agent_version,omitempty"`
// EnvDigest is set only in the ack of an adopt: EnvDigest(Nonce, env)
// over the env the guest applied. An agent built before adopt frames
// carried env leaves it out (encoding/json drops the unknown "env"
// field without a word), which is how the host tells an agent that
// ignored the env from one that applied it.
EnvDigest string `json:"env_digest,omitempty"`
}
ReadySignal is the guest→host readiness announcement.