portdirect

Documentation

Overview

Package portdirect defines the bounded caller-facing handshake that precedes every byte of a direct SecondBox data-plane connection.

The caller connects over pinned TLS, writes exactly one credential frame, and reads exactly one admission frame. Port payload bytes flow raw in both directions only after an admitted verdict, so the framing never has to be re-entered mid-stream.

The privileged Runner owns an identical definition in its own module. The two are separate because the Runner module deliberately shares no dependency graph with the control plane, the same reason the generated protocol code is duplicated. Any change here must be mirrored in runner/internal/portdirect/framing.go.

Index

• Constants
• Variables
• func ReadTypedMessage(reader io.Reader) ([]byte, error)
• func TLSConfigForSPKIPin(pin string) (*tls.Config, error)
• func WriteCredential(writer io.Writer, kind SessionKind, credential string) error
• func WriteTypedMessage(writer io.Writer, payload []byte) error
• func WriteVerdict(writer io.Writer, verdict Verdict, detail string) error
• type Credential
  • func ReadCredential(reader io.Reader) (Credential, error)
• type SessionKind
  • func (kind SessionKind) String() string
• type Verdict
  • func ReadVerdict(reader io.Reader) (Verdict, string, error)

Constants

const (
	// MaximumCredentialBytes bounds the credential an unauthenticated peer can
	// force the Runner to buffer.
	MaximumCredentialBytes = 2048
	// MaximumDetailBytes bounds the safe detail returned with a verdict.
	MaximumDetailBytes = 128
	// MaximumTypedMessageBytes bounds one length-prefixed Exec or File message.
	MaximumTypedMessageBytes = 2 << 20
)

const Magic = "SBXDP1"

Magic identifies generation one of the direct data-plane handshake.

Variables

var ErrHandshakeMalformed = errors.New("SecondBox direct data-plane handshake is malformed")

ErrHandshakeMalformed identifies a peer that is not speaking this protocol.

Functions

func ReadTypedMessage

func ReadTypedMessage(reader io.Reader) ([]byte, error)

ReadTypedMessage reads one bounded length-prefixed Exec or File message.

func TLSConfigForSPKIPin

func TLSConfigForSPKIPin(pin string) (*tls.Config, error)

TLSConfigForSPKIPin returns a TLS 1.3 client configuration for the exact certificate public key admitted by the control plane. Runners are commonly addressed by IP, so SPKI pinning avoids imposing a DNS naming scheme solely for hostname verification while still authenticating the presented key.

func WriteCredential

func WriteCredential(writer io.Writer, kind SessionKind, credential string) error

WriteCredential emits the leading credential frame.

func WriteTypedMessage

func WriteTypedMessage(writer io.Writer, payload []byte) error

WriteTypedMessage writes one bounded length-prefixed Exec or File message.

func WriteVerdict

func WriteVerdict(writer io.Writer, verdict Verdict, detail string) error

WriteVerdict emits the single admission frame. The detail is truncated rather than rejected so a denial always reaches the caller.

Types

type Credential

type Credential struct {
	SessionKind SessionKind
	Value       string
}

Credential is the bounded authority presented for one session kind.

func ReadCredential

func ReadCredential(reader io.Reader) (Credential, error)

ReadCredential consumes the leading credential frame and nothing beyond it.

type SessionKind

type SessionKind byte

SessionKind identifies the admitted data-plane operation.

const (
	SessionKindPort SessionKind = iota
	SessionKindExec
	SessionKindPTY
	SessionKindFile
)

func (SessionKind) String

func (kind SessionKind) String() string

type Verdict

type Verdict byte

Verdict is the single admission outcome for one caller connection.

const (
	// VerdictAdmitted precedes bidirectional payload bytes.
	VerdictAdmitted Verdict = 0
	// VerdictDenied is terminal; the Runner closes the connection after it.
	VerdictDenied Verdict = 1
	// VerdictSessionKindUnsupported rejects a valid kind with no wired transport.
	VerdictSessionKindUnsupported Verdict = 2
)

func ReadVerdict

func ReadVerdict(reader io.Reader) (Verdict, string, error)

ReadVerdict consumes the single admission frame and nothing beyond it.