control

package
v0.0.0-...-c6d7338 Latest Latest
Warning

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

 Go to latest Published: Oct 10, 2026 License: Apache-2.0 Imports: 17 Imported by: 0

Documentation

Overview

Package control defines the authenticated local microvmd control plane and its bounded, versioned guest handshake.

Index

Constants

View Source 
const (
	// ProtocolVersion is the only guest protocol version accepted by this release.
	ProtocolVersion uint16 = 1
	// DefaultMaxMessageBytes is the hard upper bound negotiated for protocol messages.
	DefaultMaxMessageBytes uint32 = 1 << 20
)
View Source 
const GuestControlPort uint32 = 10777

GuestControlPort is the reserved versioned guest-control vsock port.

Variables

View Source 
var (
	// ErrUnauthenticatedPeer means the Unix peer is not the configured daemon account.
	ErrUnauthenticatedPeer = errors.New("microvm control peer is not authenticated")
	// ErrBindingMismatch means an operation does not match its registered owner/session/ref/generation.
	ErrBindingMismatch = errors.New("microvm control binding mismatch")
)
View Source 
var (
	// ErrCapabilityMismatch reports a missing mandatory guest capability.
	ErrCapabilityMismatch = errors.New("microvm guest capability mismatch")
	// ErrMessageBound reports a missing or invalid negotiated message bound.
	ErrMessageBound = errors.New("microvm guest message bound is missing")
	// ErrProtocolVersion reports an incompatible guest protocol version.
	ErrProtocolVersion = errors.New("microvm guest protocol version mismatch")
	// ErrFrameTooLarge reports a frame larger than the codec's immutable bound.
	ErrFrameTooLarge = errors.New("microvm protocol frame exceeds bound")
	// ErrMalformedFrame reports invalid bounded protocol framing or JSON.
	ErrMalformedFrame = errors.New("malformed microvm protocol frame")
)
View Source 
var (
	// ErrUnauthenticatedCapability reports an invalid, stale, replayed, or wrongly bound guest capability.
	ErrUnauthenticatedCapability = errors.New("microvm guest capability is not authenticated")
)

Functions

func GuestControlOption 

func GuestControlOption(socketPath string) (gomicrovm.Option, error)

GuestControlOption wires the guest control channel through go-microvm's vsock-to-Unix-domain-socket primitive. SSH and host-local fallbacks are not part of the control protocol.

func ServeBoundRegisteredMultiplex 

func ServeBoundRegisteredMultiplex(ctx context.Context, stream io.ReadWriteCloser, resolve BoundHandlerResolver, maxMessageBytes uint32) error

ServeBoundRegisteredMultiplex serves repository data without the generic transferable-capability replay table. The resolver must consume the registration incarnation exactly once.

func ServeMultiplex 

func ServeMultiplex(ctx context.Context, stream io.ReadWriteCloser, expected Binding, verifier *CapabilityVerifier, handlers map[ServiceName]Handler, maxMessageBytes uint32) error

ServeMultiplex authenticates one capability, negotiates services, and dispatches request IDs.

func ServeRegisteredMultiplex 

func ServeRegisteredMultiplex(ctx context.Context, stream io.ReadWriteCloser, verifier *CapabilityVerifier, resolve RegisteredHandlerResolver, maxMessageBytes uint32) error

ServeRegisteredMultiplex authenticates a logical binding before selecting any assigned-root handler. Each connection remains bound to that exact tuple.

Types

type Agreement 

type Agreement struct {
	Version         uint16       `json:"version"`
	Capabilities    Capabilities `json:"capabilities"`
	MaxMessageBytes uint32       `json:"max_message_bytes"`
}

Agreement is the capability set and bound selected for a connection.

type Binding 

type Binding struct {
	Owner         string `json:"owner"`
	SessionID     string `json:"session_id"`
	EnvironmentID string `json:"environment_id"`
	Ref           string `json:"ref"`
	Generation    uint32 `json:"generation"`
	// AssignedRoot is the guest-visible root authenticated for repository-logical
	// environments. Protocol inputs without it are not valid logical bindings.
	AssignedRoot string `json:"assigned_root,omitempty"`
}

Binding identifies one immutable environment generation. Its fields are identifiers, not credentials; authorization additionally requires an authenticated Unix peer.

func (Binding) ValidateLogical 

func (b Binding) ValidateLogical(owner string, generation uint32) error

ValidateLogical verifies the complete repository-logical authentication tuple.

type BoundHandlerResolver 

type BoundHandlerResolver func(Binding, string) (map[ServiceName]Handler, bool)

BoundHandlerResolver consumes one registration incarnation while resolving a repository binding on an already mutually authenticated boot channel.

type Capabilities 

type Capabilities []Capability

Capabilities is a deterministic capability list.

func RequiredCapabilities 

func RequiredCapabilities() Capabilities

RequiredCapabilities returns a fresh list of all mandatory version-1 capabilities.

func (Capabilities) Without 

func (c Capabilities) Without(capability Capability) Capabilities

Without returns a copy excluding capability.

type Capability 

type Capability string

Capability is a guest service property required before any operation is sent. 

const (
	// CapabilityFilesystem requires version-aware guest filesystem operations.
	CapabilityFilesystem Capability = "filesystem"
	// CapabilityStreaming requires ordered output streaming.
	CapabilityStreaming Capability = "streaming"
	// CapabilityCancellation requires guest process-group cancellation.
	CapabilityCancellation Capability = "cancellation"
	// CapabilityGenerationBinding requires every operation to bind one generation.
	CapabilityGenerationBinding Capability = "generation-binding"
	// CapabilityMessageBound requires a negotiated maximum message size.
	CapabilityMessageBound Capability = "message-bound"
)

type CapabilityIssuer 

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

CapabilityIssuer mints transferable, generation-bound guest capabilities. It contains only an independently provisioned signing key and shares no registry with the guest.

func NewCapabilityIssuer 

func NewCapabilityIssuer(key []byte) (*CapabilityIssuer, error)

NewCapabilityIssuer constructs an issuer from independently provisioned key material.

func (*CapabilityIssuer) Issue 

func (i *CapabilityIssuer) Issue(binding Binding) (string, error)

Issue mints a signed, single-use capability for one immutable binding.

type CapabilityVerifier 

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

CapabilityVerifier verifies capabilities using its own key copy and rejects nonce replay locally.

func NewCapabilityVerifier 

func NewCapabilityVerifier(key []byte) (*CapabilityVerifier, error)

NewCapabilityVerifier constructs a guest-side verifier from provisioned key material.

func (*CapabilityVerifier) Forget 

func (v *CapabilityVerifier) Forget(binding Binding)

Forget removes replay state belonging to one unregistered logical binding. It does not affect capabilities consumed by sibling environments.

func (*CapabilityVerifier) Verify 

func (v *CapabilityVerifier) Verify(token string, expected Binding) error

Verify authenticates and consumes a capability for expected.

type Client 

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

Client multiplexes concurrent workspace and exec requests over one authenticated stream.

func OpenBoundClient 

func OpenBoundClient(ctx context.Context, stream io.ReadWriteCloser, binding Binding, credential string, services []ServiceName, maxMessageBytes uint32) (*Client, error)

OpenBoundClient opens a multiplex client on an already mutually authenticated repository channel. credential is a registration incarnation, not a bearer credential: the surrounding channel authentication supplies peer authority.

func OpenClient 

func OpenClient(ctx context.Context, stream io.ReadWriteCloser, binding Binding, capability string, services []ServiceName, maxMessageBytes uint32) (*Client, error)

OpenClient authenticates one host stream and negotiates all requested services once.

func (*Client) Agreement 

func (c *Client) Agreement() Agreement

Agreement returns a copy of the services/capabilities negotiated by the production handshake.

func (*Client) Call 

func (c *Client) Call(ctx context.Context, service ServiceName, method string, request, response any) error

Call performs one unary multiplexed request.

func (*Client) Close 

func (c *Client) Close() error

Close closes the sole guest stream and unblocks all requests.

func (*Client) IsBoundTo 

func (c *Client) IsBoundTo(binding Binding) bool

IsBoundTo reports whether the authenticated connection owns binding.

func (*Client) Stream 

func (c *Client) Stream(ctx context.Context, service ServiceName, method string, request any, receive func(json.RawMessage) error, response any) error

Stream performs one request, delivering ordered stream payloads before the final response.

type Codec 

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

Codec reads and writes unsigned 32-bit big-endian length-prefixed JSON frames.

func NewCodec 

func NewCodec(maxMessageBytes uint32) Codec

NewCodec creates a codec with an immutable per-frame byte bound.

func (Codec) Read 

func (c Codec) Read(src io.Reader, value any) error

Read receives exactly one bounded frame and rejects trailing JSON values.

func (Codec) Write 

func (c Codec) Write(dst io.Writer, value any) error

Write emits exactly one bounded frame.

type Handler 

type Handler func(context.Context, string, json.RawMessage, func(any) error) (any, string, error)

Handler serves one negotiated multiplex service.

type PeerAuthenticator 

type PeerAuthenticator interface {
	PeerUID(net.Conn) (uint32, error)
}

PeerAuthenticator extracts kernel-authenticated credentials from a local connection.

type RegisteredHandlerResolver 

type RegisteredHandlerResolver func(Binding) (map[ServiceName]Handler, bool)

RegisteredHandlerResolver resolves one complete logical binding to its assigned-root handlers.

type RemoteError 

type RemoteError struct{ Code string }

RemoteError is a bounded service error code returned by the guest.

func (*RemoteError) Error 

func (e *RemoteError) Error() string

type Service 

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

Service authorizes local control operations against kernel peer credentials and the complete immutable environment binding.

func NewService 

func NewService(cfg ServiceConfig) (*Service, error)

NewService constructs a local control service. Bindings are copied.

func (*Service) Authenticate 

func (s *Service) Authenticate(conn net.Conn) error

Authenticate verifies the Unix peer before any caller-controlled identifier is read.

func (*Service) Authorize 

func (s *Service) Authorize(conn net.Conn, claim Binding) error

Authorize authenticates the Unix peer before looking up or comparing identifiers.

type ServiceConfig 

type ServiceConfig struct {
	AccountUID        uint32
	Bindings          []Binding
	PeerAuthenticator PeerAuthenticator
}

ServiceConfig configures the private local microvmd control service.

type ServiceName 

type ServiceName string

ServiceName identifies a negotiated guest data-plane service. 

const (
	// ServiceWorkspace selects version-aware filesystem operations.
	ServiceWorkspace ServiceName = "workspace"
	// ServiceExec selects bounded command execution and output streaming.
	ServiceExec ServiceName = "exec"
)

Source Files

View all Source files

Directories

Path Synopsis
Package controltest provides deterministic offline control-protocol fakes.
 Package controltest provides deterministic offline control-protocol fakes.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.