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 ¶
const PublicKeySize = 32
PublicKeySize is the raw byte length of an X25519 public key.
Variables ¶
This section is empty.
Functions ¶
func Seal ¶
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 ¶
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 ¶
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 ¶
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 ¶
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.
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 ¶
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.