Documentation
¶
Index ¶
- Constants
- Variables
- func CleanupStages(locator string) error
- func ExecImage(candidate ImageEvidence, argv, env []string) error
- func ExecSupported() bool
- func IsDarwinExecObserved(method string) bool
- func ReadEmbeddedVersion(path string) (string, error)
- func ReadEmbeddedVersionFromOpenFile(image *os.File) (string, error)
- func RefusedCandidatesContain(candidates []RefusedCandidate, evidence ImageEvidence) bool
- func RunBoundedProbe(ctx context.Context, path string, args []string, options BoundedProbeOptions) ([]byte, error)
- func SameCandidateIdentity(first, second ImageEvidence) bool
- func SameDarwinStagedImageEvidence(first, second ImageEvidence) bool
- func SameImageEvidenceExceptMethodPath(first, second ImageEvidence) bool
- func SameRefusedCandidates(first, second []RefusedCandidate) bool
- func ValidSHA256(value string) bool
- func ValidateAttempt(attempt Attempt) error
- func ValidateAttemptForPlatform(attempt Attempt, platform string) error
- func ValidateAttempts(attempts []Attempt) error
- func ValidateImageEvidence(evidence ImageEvidence) error
- func ValidateImageEvidenceForPlatform(evidence ImageEvidence, platform string) error
- func VersionStrictlyNewer(incumbent, candidate string) bool
- type Attempt
- func AddAttempt(attempts []Attempt, addition Attempt, now time.Time) ([]Attempt, error)
- func MergeAttempts(current, desired []Attempt, now time.Time) ([]Attempt, error)
- func NewAttempt(evidence ImageEvidence, now time.Time) Attempt
- func PruneExpiredAttempts(attempts []Attempt, now time.Time) []Attempt
- type BoundedProbeOptions
- type ImageEvidence
- func CaptureImageEvidence(path, embeddedVersion string) (ImageEvidence, error)
- func CaptureImageEvidenceFromOpenFile(file *os.File, executionPath, embeddedVersion, method string) (ImageEvidence, error)
- func CaptureImageEvidenceFromOpenFileWithMutator(file *os.File, executionPath, embeddedVersion, method string, mutator func()) (ImageEvidence, error)
- func CaptureImageEvidenceWithEmbeddedVersion(path string) (ImageEvidence, error)
- func CaptureImageEvidenceWithMutator(path, embeddedVersion string, mutator func()) (ImageEvidence, error)
- type RefusedCandidate
Constants ¶
const ( AttemptStatusAttempt = "attempt" AttemptStatusSettled = "settled" AttemptMaxAge = 24 * time.Hour AttemptFutureSkew = time.Hour AttemptLimit = 8 )
const ( ImageEvidenceSchemaV1 = 1 ImageMethodFDExec = "fd_exec" ImageMethodPathnameObserved = "pathname_observed" ImageMethodPathnameExecObserved = "pathname_exec_observed" ImageMethodPathnameExecVerifiedLegacy = "pathname_execve_verified" ImageMethodPathnameExecVerified = ImageMethodPathnameExecVerifiedLegacy )
const RefusalLimit = 8
Variables ¶
var ErrExecUnsupported = errors.New("self-upgrade exec is unsupported on this platform")
var ErrImageChangedWhileHashing = errors.New("wake image changed while hashing")
Functions ¶
func CleanupStages ¶
CleanupStages removes only the private Darwin stage directories created by ExecImage. A successful Darwin exec cannot run cleanup in the old image, so the replacement performs this bounded cleanup after capturing its image.
func ExecImage ¶
func ExecImage(candidate ImageEvidence, argv, env []string) error
ExecImage verifies the named image again at the exec boundary and then replaces the current process with that image. Linux binds the verified file descriptor for fexecve via /proc/self/fd; Darwin re-verifies a private stage immediately before pathname exec because it has no fexecve primitive.
func ExecSupported ¶
func ExecSupported() bool
ExecSupported reports whether this platform has a verified in-place image replacement implementation.
func IsDarwinExecObserved ¶
func ReadEmbeddedVersion ¶
ReadEmbeddedVersion reads the version from Go build metadata without running the candidate. An image whose build-info region cannot be read has no trustworthy version and therefore returns an error so callers defer.
func ReadEmbeddedVersionFromOpenFile ¶
ReadEmbeddedVersionFromOpenFile reads build metadata from an already opened image. Callers that also need image evidence should use this fd-bound form so the version and digest describe the same opened file.
func RefusedCandidatesContain ¶
func RefusedCandidatesContain(candidates []RefusedCandidate, evidence ImageEvidence) bool
func RunBoundedProbe ¶
func RunBoundedProbe( ctx context.Context, path string, args []string, options BoundedProbeOptions, ) ([]byte, error)
RunBoundedProbe runs a short-lived probe with bounded stdout and stderr and process cleanup. Callers must use it only after binding and verifying the image. A wake uses this for the post-bind preflight of the exact image it already verified; it is not a candidate-version discovery mechanism.
func SameCandidateIdentity ¶
func SameCandidateIdentity(first, second ImageEvidence) bool
func SameDarwinStagedImageEvidence ¶
func SameDarwinStagedImageEvidence(first, second ImageEvidence) bool
SameDarwinStagedImageEvidence ignores the ctime and path changes caused by Darwin hardlink staging. Device, inode, size, digest, and version remain the content and identity proof.
func SameImageEvidenceExceptMethodPath ¶
func SameImageEvidenceExceptMethodPath(first, second ImageEvidence) bool
SameImageEvidenceExceptMethodPath compares image authority while ignoring how and where the image was observed.
func SameRefusedCandidates ¶
func SameRefusedCandidates(first, second []RefusedCandidate) bool
func ValidSHA256 ¶
func ValidateAttempt ¶
func ValidateAttempts ¶
ValidateAttempts validates the bounded ledger and rejects duplicate image identities. A duplicate would make settlement and refusal ownership ambiguous after a concurrent publication.
func ValidateImageEvidence ¶
func ValidateImageEvidence(evidence ImageEvidence) error
func ValidateImageEvidenceForPlatform ¶
func ValidateImageEvidenceForPlatform(evidence ImageEvidence, platform string) error
func VersionStrictlyNewer ¶
Types ¶
type Attempt ¶
type Attempt struct {
Status string `json:"status"`
Candidate RefusedCandidate `json:"candidate"`
UnixTime int64 `json:"unix_time"`
}
Attempt records the stable identity of an image that was about to replace the current process. It deliberately excludes paths and observation methods.
func AddAttempt ¶
AddAttempt appends a new attempt without evicting a fresh unresolved attempt. It returns an error when the bounded ledger contains no safe entry to evict.
func MergeAttempts ¶
MergeAttempts unions two controller views while preserving the bounded ledger invariant. Settled entries are terminal, so a stale unresolved view cannot reopen an entry that another controller settled.
func NewAttempt ¶
func NewAttempt(evidence ImageEvidence, now time.Time) Attempt
func PruneExpiredAttempts ¶
PruneExpiredAttempts removes only unresolved attempts that are past the refusal window. Settled entries remain available for bounded ledger merge and audit until they are evicted by a newer attempt.
func (Attempt) Matches ¶
func (attempt Attempt) Matches(evidence ImageEvidence) bool
func (Attempt) RefusalReason ¶
type BoundedProbeOptions ¶
BoundedProbeOptions carries the inherited process state needed by a probe. The file descriptors remain owned by the caller.
type ImageEvidence ¶
type ImageEvidence struct {
Schema int `json:"schema"`
Platform string `json:"platform"`
Method string `json:"method"`
ExecutionPath string `json:"execution_path"`
Device uint64 `json:"device"`
Inode uint64 `json:"inode"`
Size int64 `json:"size"`
CTimeNS int64 `json:"ctime_ns"`
SHA256 string `json:"sha256"`
EmbeddedVersion string `json:"embedded_version"`
}
ImageEvidence records image metadata and the authority method used to observe it. A pathname observation is diagnostic; fd_exec and the Darwin pathname exec methods describe execution-bound evidence.
func CaptureImageEvidence ¶
func CaptureImageEvidence(path, embeddedVersion string) (ImageEvidence, error)
func CaptureImageEvidenceFromOpenFile ¶
func CaptureImageEvidenceFromOpenFile( file *os.File, executionPath, embeddedVersion, method string, ) (ImageEvidence, error)
func CaptureImageEvidenceFromOpenFileWithMutator ¶
func CaptureImageEvidenceFromOpenFileWithMutator( file *os.File, executionPath, embeddedVersion, method string, mutator func(), ) (ImageEvidence, error)
func CaptureImageEvidenceWithEmbeddedVersion ¶
func CaptureImageEvidenceWithEmbeddedVersion(path string) (ImageEvidence, error)
CaptureImageEvidenceWithEmbeddedVersion reads the candidate version and captures its evidence from the same opened file.
func CaptureImageEvidenceWithMutator ¶
func CaptureImageEvidenceWithMutator(path, embeddedVersion string, mutator func()) (ImageEvidence, error)
CaptureImageEvidenceWithMutator exists for race tests that mutate the file between the before-hash and after-hash observations.
type RefusedCandidate ¶
type RefusedCandidate struct {
Platform string `json:"platform"`
Device uint64 `json:"device"`
Inode uint64 `json:"inode"`
Size int64 `json:"size"`
SHA256 string `json:"sha256"`
EmbeddedVersion string `json:"embedded_version"`
}
RefusedCandidate is a path-free, content-bound identity for one refused candidate. ctime, method, and execution path are excluded because Darwin staging changes them.
func RefusedCandidateFromEvidence ¶
func RefusedCandidateFromEvidence(evidence ImageEvidence) RefusedCandidate
func RememberRefusal ¶
func RememberRefusal(candidates []RefusedCandidate, evidence ImageEvidence) []RefusedCandidate
RememberRefusal appends a distinct refusal as the newest item and retains only the most recent bounded set.
Source Files