Documentation
¶
Overview ¶
Package firecrackerbootprobeprotocol owns the private signed M3-to-M4 boot-probe command and M4 observation wire.
Index ¶
- Constants
- Variables
- func SignCommand(session firecrackerbootprobev2.Session, grant firecrackerlaunchgrant.Grant, ...) ([]byte, error)
- func SignObservation(observation Observation, privateKey ed25519.PrivateKey) ([]byte, error)
- func SignStageReady(snapshot firecrackerbootprobev2.Snapshot, ...) ([]byte, error)
- type Command
- type HostTrust
- type HostTrustResolver
- type Observation
- type StageReady
- type VerifiedCommand
- type VerifiedStageReady
Constants ¶
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 ¶
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.