firecrackerbootprobeprotocol

package
v0.0.0-...-804b954 Latest Latest
Warning

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

Go to latest
Published: Aug 13, 2026 License: MIT Imports: 11 Imported by: 0

Documentation

Overview

Package firecrackerbootprobeprotocol owns the private signed M3-to-M4 boot-probe command and M4 observation wire.

Index

Constants

View Source
const (
	// Version is the distinct private M3-to-M4 boot-probe protocol. It never falls back to host-control v1.
	Version = "sandbox.host-control/v2/firecracker-boot-probe"
	// ObservationKind identifies the sole accepted signed host observation.
	ObservationKind = "boot-observation"
	// StageReadyKind identifies the sole M4-to-M3 pre-launch record.
	StageReadyKind = "stage-ready"
	// GuestProtocolPong is the sole guest observation a boot probe may report.
	GuestProtocolPong = "pong"
)

Variables

View Source
var (
	// ErrInvalidCommand identifies a malformed, detached, untrusted, or expired private boot-probe command.
	ErrInvalidCommand = errors.New("invalid Firecracker boot-probe v2 command")
	// ErrInvalidObservation identifies a malformed, altered, delayed, or detached private boot-probe observation.
	ErrInvalidObservation = errors.New("invalid Firecracker boot-probe v2 observation")
	// ErrInvalidStageReady identifies a malformed, detached, untrusted, or expired M4 stage-ready record.
	ErrInvalidStageReady = errors.New("invalid Firecracker boot-probe v2 stage-ready record")
)

Functions

func SignCommand

func SignCommand(session firecrackerbootprobev2.Session, grant firecrackerlaunchgrant.Grant, guestNonce string, privateKey ed25519.PrivateKey) ([]byte, error)

SignCommand writes one canonical M3-signed command after a caller has atomically recorded launch authorization. The caller owns durable CAS and enrolment; this function only seals a fixed-purpose command.

func SignObservation

func SignObservation(observation Observation, privateKey ed25519.PrivateKey) ([]byte, error)

SignObservation writes a canonical M4-signed bounded observation. Control must call VerifyObservation with the exact verified command before accepting it.

func SignStageReady

func SignStageReady(snapshot firecrackerbootprobev2.Snapshot, identity firecracker.TrustedM4Identity, guestNonce string, privateKey ed25519.PrivateKey) ([]byte, error)

SignStageReady writes the canonical M4-to-M3 record after M4 has compiled its exact staged identity. It neither grants nor starts a launch.

Types

type Command

type Command struct {
	ProtocolVersion       string                          `json:"protocol_version"`
	HostInstanceSessionID string                          `json:"host_instance_session_id"`
	Binding               firecrackerbootprobev2.Binding  `json:"binding"`
	Delivery              firecrackerbootprobev2.Delivery `json:"delivery"`
	Grant                 firecrackerlaunchgrant.Grant    `json:"grant"`
	GuestNonce            string                          `json:"guest_nonce"`
	Signature             string                          `json:"signature"`
}

Command is one M3-signed, launch-authorized delivery to an exact M4 host instance. It contains no plan, host path, fixture source, Jailer argument, credential, or public sandbox capability.

type HostTrust

type HostTrust struct {
	HostID               string
	HostGeneration       uint64
	ControlPublicKey     ed25519.PublicKey
	ObservationPublicKey ed25519.PublicKey
}

HostTrust is the bounded verification material returned by an authoritative enrollment resolver. It intentionally carries no certificate, secret, enrollment policy, or M4 identity.

type HostTrustResolver

type HostTrustResolver interface {
	ResolveBootProbeHostTrust(context.Context, string, uint64) (HostTrust, error)
}

HostTrustResolver resolves the already-enrolled control and observation keys for one exact host generation. It is an M3 authority seam: callers must not infer keys from a command or accept host-supplied key material.

type Observation

type Observation struct {
	ProtocolVersion       string                                   `json:"protocol_version"`
	Kind                  string                                   `json:"kind"`
	HostInstanceSessionID string                                   `json:"host_instance_session_id"`
	EnvelopeID            string                                   `json:"envelope_id"`
	DeliveryID            string                                   `json:"delivery_id"`
	Nonce                 string                                   `json:"nonce"`
	LeaseEpoch            uint64                                   `json:"lease_epoch"`
	FencingToken          uint64                                   `json:"fencing_token"`
	M4                    firecrackerlaunchgrant.TrustedM4Identity `json:"m4"`
	SerialMarker          string                                   `json:"serial_marker"`
	GuestNonce            string                                   `json:"guest_nonce"`
	GuestProtocolResult   string                                   `json:"guest_protocol_result"`
	ObservedAt            time.Time                                `json:"observed_at"`
	Signature             string                                   `json:"signature"`
}

Observation is one M4-signed, bounded result for the exact command delivery. Its identity is compared to the already verified command by VerifyObservation; an observation never grants launch authority.

func VerifyObservation

func VerifyObservation(wire []byte, verified VerifiedCommand, now time.Time) (Observation, error)

type StageReady

type StageReady struct {
	ProtocolVersion       string                                   `json:"protocol_version"`
	Kind                  string                                   `json:"kind"`
	HostInstanceSessionID string                                   `json:"host_instance_session_id"`
	ExpectedVersion       uint64                                   `json:"expected_version"`
	Binding               firecrackerbootprobev2.Binding           `json:"binding"`
	Delivery              firecrackerbootprobev2.Delivery          `json:"delivery"`
	M4                    firecrackerlaunchgrant.TrustedM4Identity `json:"m4"`
	GuestNonce            string                                   `json:"guest_nonce"`
	Signature             string                                   `json:"signature"`
}

StageReady is the M4-owned pre-launch request. Its identity is produced by the sealed local compiler, and its signature uses the separately enrolled observation key rather than the M3 control-signing key.

type VerifiedCommand

type VerifiedCommand struct {
	// contains filtered or unexported fields
}

VerifiedCommand is an opaque result of VerifyCommand. It prevents an observation path from accepting a caller-constructed command that has not passed the M3 signature, enrolled-host, and compiled-M4 identity checks.

func VerifyCommand

func VerifyCommand(ctx context.Context, wire []byte, now time.Time, resolver HostTrustResolver, identity firecracker.CompiledM4IdentityVerifier) (VerifiedCommand, error)

VerifyCommand strictly decodes and verifies an M3 command for the one enrolled host and locally compiled M4 identity. Passing a different self-reported M4 identity never widens the signed command's authority.

func (VerifiedCommand) Command

func (verified VerifiedCommand) Command() Command

Command returns a copy of the exact command that VerifyCommand accepted.

type VerifiedStageReady

type VerifiedStageReady struct {
	// contains filtered or unexported fields
}

VerifiedStageReady is the opaque result of VerifyStageReady. M3 must use it with its locked persisted session rather than trust a caller-built record.

func VerifyStageReady

func VerifyStageReady(ctx context.Context, wire []byte, now time.Time, resolver HostTrustResolver) (VerifiedStageReady, error)

VerifyStageReady verifies the distinct enrolled observation key and exact prepared-delivery shape. It does not mutate a session or authorize launch.

func (VerifiedStageReady) StageReady

func (verified VerifiedStageReady) StageReady() StageReady

StageReady returns a copy of the exact M4 record VerifyStageReady accepted.

Jump to

Keyboard shortcuts

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