GURDN

Documentation / Engineering

Updates

Signature, key standing, downgrade and staging containment.

The update path is one of the few places where a security product can become the attack. Everything below happens before anything is written to disk.

Figure 4, update verification

Input

Update package arrives

  • Signature over the manifestor refuse
  • Payload digest matchesor refuse
  • Key standing is current or previousor refuse
  • Not a downgradeor refuse
  • Manifest is still in dateor refuse
  • Staging path stays inside its directoryor refuse
Result

Staged, and only then installable

Every check must pass before anything is written to disk. A build with no release key configured accepts nothing at all, which is deliberate.

Signature and digest

A release manifest is signed, and the signature is checked against GURDN's release keys before the package is considered at all. The payload is then hashed and compared with the digest recorded in that signed manifest, so a package altered after signing is refused even though its signature covers the manifest.

Key standing

A key is current, previous, not yet valid, or revoked. Standing is checked separately from the mathematics:

  • Current keys are accepted.
  • Previous keys are accepted where policy permits, so a key rotation does not strand anyone who has not updated yet.
  • Not yet valid keys are refused.
  • Revoked keys are refused, and the refusal names the key.
A correct signature by a revoked key is still refused. Revocation takes precedence over cryptographic validity, because the whole point of revoking a key is that signatures made with it can no longer be trusted, including ones that verify perfectly.

Version direction

A package that would move the installation backwards is refused as a downgrade rather than quietly installed. Reinstalling the version already present is permitted, and is distinguishable in the record from an upgrade.

Freshness

A manifest past its shelf life is refused, so an old and once-valid package cannot be replayed indefinitely by whoever can serve it to you.

Containment of the staging path

The version named in the signed manifest decides where the package is staged. That value is treated as hostile input:

  • It must match a restricted character set and contain at least one digit.
  • It is length limited.
  • The resulting directory's parent must be the staging root itself, so a value containing traversal segments or an absolute path cannot escape.
  • Paths that cross a junction or other reparse point are refused, so a link planted in the staging area cannot redirect a write somewhere else.
  • The compatibility declaration, which the signature does not cover, is cross-checked against the signed manifest rather than believed.

A shipped build with no key accepts nothing

The trusted key set ships empty, so a build with no release key configured refuses every update. This is deliberate: an update mechanism that trusts a placeholder key is worse than one that trusts nothing, because the placeholder is a key whose private half somebody holds.

See release status for what that means today.