planseal

package
v0.2.13 Latest Latest
Warning

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

Go to latest
Published: Nov 15, 2026 License: MIT Imports: 7 Imported by: 0

Documentation

Overview

Package planseal seals the Plan payload to a per-process manager key.

The runner holds the public half only: it seals the plan bytes it read and never needs to open anything. The manager holds the key pair and never persists the private half, so a restarted manager cannot open a Plan frame it sealed before the restart -- it re-plans instead, which is safe because Plan is read-only. See docs/site/src/content/docs/use/security.md, "Pod logs carry plans".

The primitive is NaCl's anonymous sealed box (X25519, XSalsa20, Poly1305 -- golang.org/x/crypto/nacl/box), the same construction libsodium calls crypto_box_seal. It needs no sender identity: box.SealAnonymous generates its own single-use ephemeral key pair internally and prepends the ephemeral public key to the ciphertext, which is exactly the runner's position -- it holds no private key and never will.

Index

Constants

View Source
const PublicKeySize = 32

PublicKeySize is the raw byte length of an X25519 public key.

Variables

This section is empty.

Functions

func Seal

func Seal(message []byte, recipient PublicKey) (string, error)

Seal encrypts message so that only the holder of the matching private key can read it back, using a fresh single-use ephemeral key pair the box package generates for this call alone. The result is the base64 encoding of the sealed box, safe to carry in a JSON string field or a frame written to standard output.

func SealPlan

func SealPlan(plan []byte, envelope Envelope, recipient PublicKey) (string, error)

SealPlan seals plan for recipient, wrapped in an envelope binding it to envelope's operation and Job. The wrapping is a compact JSON header, followed by one newline the header itself cannot contain, followed by plan unchanged: encoding/json never emits a literal newline for a struct of plain strings, so the split before decoding it back is unambiguous however many newlines the plan itself carries.

Types

type Envelope

type Envelope struct {
	OperationID string `json:"operationID"`
	JobName     string `json:"jobName"`
}

Envelope binds a sealed plan to the exact operation and Job it was computed for.

A NaCl sealed box carries no associated data: any plaintext sealed to a given public key opens the same way regardless of what it is, so opening successfully proves only that the manager's own key sealed it, never that it was sealed for the harvest now reading it. A validly sealed plan from one operation, with a self-consistent content digest, would otherwise open and validate as another's. The envelope closes that: it travels inside the sealed plaintext, where nothing that lacks the public key can forge it undetected, and the harvest path refuses a mismatch instead of trusting that the frame it read named the right operation.

JobName rather than a Job UID, because the runner seals before the Job it runs in exists as an API object: the UID is assigned on create, but the deterministic name is computed from the claim before dispatch and is already what the runner is given. It changes on every retry of the same operation, so it also tells apart two attempts the OperationID alone would not.

type KeyPair

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

KeyPair is a per-process X25519 key pair. Generate creates one; the zero value opens nothing (OpenAnonymous refuses a box addressed to the zero public key the same as any other key it does not hold).

The private half is never persisted, logged, or sent anywhere. It exists only in this process's memory for as long as the process runs.

func Generate

func Generate() (KeyPair, error)

Generate creates a fresh key pair from a cryptographically secure random source. Call it once per manager process at startup; never persist the result.

func (KeyPair) Open

func (k KeyPair) Open(sealed string) ([]byte, error)

Open decrypts a payload Seal produced for this pair's public half. A payload sealed to a different key, or corrupted in transit, is refused without distinguishing which -- either way this process cannot read it.

func (KeyPair) OpenPlan

func (k KeyPair) OpenPlan(sealed string, want Envelope) ([]byte, error)

OpenPlan opens a payload SealPlan produced and refuses one whose envelope is not exactly want: a plan sealed for a different operation or a different attempt of the same one, however validly it opens.

func (KeyPair) PublicKey

func (k KeyPair) PublicKey() PublicKey

PublicKey is the half that travels in the Plan Job's environment.

type PublicKey

type PublicKey [PublicKeySize]byte

PublicKey is the half of a KeyPair that travels in the Plan Job's environment. The zero value decodes and encodes like any other key; it is not a sentinel for "no key".

func DecodePublicKey

func DecodePublicKey(encoded string) (PublicKey, error)

DecodePublicKey reads the base64 form the Plan Job's environment carries. It refuses anything that does not decode to exactly PublicKeySize bytes, so a missing or truncated environment variable is refused here rather than silently treated as a key that seals to nobody.

func (PublicKey) Encode

func (p PublicKey) Encode() string

Encode is the base64 form carried in the Job's environment.

Jump to

Keyboard shortcuts

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