Skip to content

Implement IMPROVEMENTS.md items 1-8 and 12 (rest after #10/#11) - #12

Merged
skalvinnathan merged 13 commits into
mainfrom
feat/improvements-impl-v2
Nov 15, 2026
Merged

skalvinnathan merged 13 commits into
mainfrom
feat/improvements-impl-v2

Conversation

@skalvinnathan

Copy link
Copy Markdown
Member

Implements the remaining items in IMPROVEMENTS.md (#9), on top of main (which includes #8, #10 and #11). One commit per item. Items 9 (release notes) and 10 (TPM / cloud identity) were out of scope.

Dropped or narrowed because #10 / #11 already cover them

Items

# Status
1 Done (remainder). Grace record sealed under a per-license key. Future-dated records are still ignored.
2 Done (protocol). Real verifiers not done. POST /v1/challenge issues a single-use, MACed challenge. The evidence commits to AttestationBinding(license, challenge, ephemeral X25519 key). The secret is returned sealed to that key, signed (the signed input binds signing_key_id, like #11's). attest.Verifier is unchanged. SEV-SNP and TDX verifiers need hardware, so they are not included.
3 Done. binding.secret_v 2 (default) derives the secret per policy, so an online server cannot release attested secrets. Legacy licenses still work. Server flag: --no-legacy-secrets. Issuer flag: issue --server-secret-version 0.
4 Done, strictly opt-in, off by default. CRYPTSHIP_APP_USER (separate-uid extraction + privilege drop) and CRYPTSHIP_EXEC_MEMFD (one ELF binary from a sealed memfd). #10 judged these "not practical for a general multi-file interpreter app". Both are unset by default and change nothing unless set. The memfd mode is documented as single-binary only. Owner decision: keep them or drop commit feat(loader): separate-uid extraction… (and demo step 7). Also adds pkg/harden (Go) and helpers/python/cryptship_harden.py to re-apply PR_SET_DUMPABLE.
5 Done. A binding-derived state key (crypto.DeriveStateKey, keyprovider.Unlocker) seals the clock and revocation-grace records. Old clock records are migrated once. Not done: a copy in the extract-dir manifest. That dir is tmpfs and is emptied on every start, so the copy would not survive. Deleting the record still resets the check, and the docs say so.
6 Done (remainder). --enforce-seats / issue --max-machines: the server verifies the signed license and returns 409 when the seats are full. Seats expire after a lease and can be saved to a file. Seats trust the fingerprint the loader reports (an honest-customer limit).
7 Done. --expires-end-of-day (23:59:59 UTC). Passing --expires and --days together is now an error.
8 Done. check-mermaid.sh uses a 0755 temp dir, mounts it read-only, and has mmdc write the SVG to stdout. CI passed before only because the runner's uid is 1001, the same as the container user's.
12 Done. Seven fuzz targets (license, tar, ReadFile, three response decoders, challenge); CI fuzzes each for 10s. They found a real bug: License.Marshal HTML-escaped &<> in raw claims, which changes the signed bytes. Fixed in its own commit.

Compatibility

  • Loaders built before this PR reject licenses that contain secret_v. Until they are updated, issue with --server-secret-version 0.
  • online.AttestationNonce is replaced by AttestationBinding. Plain requests on a verifier server must use secret_v 2.

Tests run

  • golang:1.24 container (arm64, root): gofmt -l . (clean), go vet ./..., go build ./..., go build -tags cryptship_devfp ./cmd/cryptship-loader, go test -race -count=1 ./...: all pass.
  • Fuzz: each target ran for 15s (FuzzParse for 90s after the fix) with no findings.
  • Python helper unittest in python:3.12-slim: passes.
  • Demos: demo.sh (with new step 7, the hardened docker run from deploy/README.md), demo-online.sh, demo-compiled.sh: all pass.
  • check-mermaid.sh in the colima Linux VM (uid 501, umask 077): all diagrams valid.
  • Not run here: amd64 (CI covers it), and real SEV-SNP/TDX hardware.

skalvinnathan and others added 13 commits November 15, 2026 23:50
Keeps the signed /v1/check answers and the open / closed / grace semantics
from #10 and #11. Adds:

- pkg/online: VerifyKeyResponse, VerifyCheckResponse and SignCheck, used by
  the online provider, the loader and the server instead of inline code (and
  by the fuzz tests). Same rules as before; signing_key_id stays in the
  signed input.
- The revocation-grace record (time of the last signed success) is sealed
  with AES-GCM under a per-license key instead of a plain-text timestamp, so
  anyone who can write the state dir can no longer extend grace by editing
  it, and a record from another license does not open. Future-dated records
  are still ignored. The check now runs after key acquisition so the key is
  available; nothing is decrypted before it.

IMPROVEMENTS.md item 1 (the remainder after #10 / #11).
…t sealed to it

The attested flow could be replayed: the client chose the nonce and the
secret came back in clear. Now (the Trustee / KBS pattern):

- POST /v1/challenge returns a single-use, MACed, 2-minute challenge.
- The loader makes an ephemeral X25519 key and asks the attester for evidence
  over AttestationBinding(license id, challenge, ephemeral public key).
- The server spends the challenge, verifies the evidence against that binding,
  and returns the secret sealed to the ephemeral key (X25519, HKDF-SHA256,
  AES-256-GCM), signed with the vendor key over all of it.
- A server with a Verifier refuses plain requests; one without refuses the
  attested protocol.

The attest.Verifier interface is unchanged. Real SEV-SNP / TDX verifiers still
need hardware; tests use attesttest.

IMPROVEMENTS.md item 2.
A server without a verifier that shared the master key would release an
attested license's secret. Licenses now carry binding.secret_v (2 by default):

- secret_v 2: HKDF(master, info = label || policy || license id), so the online
  and attested secrets of a license differ and the plain /v1/key path, which
  only ever derives the online secret, cannot open an attested license.
- secret_v absent (0): the old derivation, so existing online licenses keep
  working. cryptship-server --no-legacy-secrets refuses it once every license
  in use is reissued; a verifying server never serves it on the plain path.
- issue --server-secret-version 0 keeps the old format for loaders that predate
  the field (they reject unknown claims).

IMPROVEMENTS.md item 3.
- CRYPTSHIP_APP_USER=uid[:gid] (loader started as root): the extracted tree
  is owned by CRYPTSHIP_EXTRACT_OWNER (default root) and the app's group,
  0750/0640, then the loader drops to the app uid/gid (no supplementary
  groups, root cannot be regained) before exec. The app can read and run its
  code but not change it; other non-root users cannot read it. Set without
  root, it is an error.
- CRYPTSHIP_EXEC_MEMFD=<entry>: run a single ELF binary from a sealed,
  close-on-exec memfd via /proc/self/fd; nothing is extracted to disk.
  linux/amd64 and arm64.
- pkg/harden (Go) and helpers/python/cryptship_harden.py re-apply
  PR_SET_DUMPABLE in the app, since execve resets it. CI runs the Python test.

End-to-end tests run the loader in a child process (root parts run in the
golang container).

IMPROVEMENTS.md item 4.
- crypto.DeriveStateKey: HKDF over the binding material (fingerprint, unbound
  or server secret), license id and claims context, under its own label.
- keyprovider: optional Unlocker interface and Unlocked{ContentKey, StateKey};
  all built-in providers implement it, and ContentKey still works.
- The loader seals the clock-rollback and revocation-grace records with the
  state key, so a record is tied to this license and binding, not to the
  build's content key. A third-party provider without a state key falls back
  to the content key.
- A clock record written by an older loader is honoured once and rewritten,
  so upgrading does not reset the check.
- The online grace cache from #11 now stores content key || state key, so a
  start served from the cache reads the same records. Its 32-byte records
  (content key only) still open.

Deleting the record still resets the check; that needs trusted storage (TPM)
and is documented.

IMPROVEMENTS.md item 5.
The live --revoke-file denylist (#10) and the authenticated grace cache
(#10, #11) are kept as they are. Adds:

- Seats: cryptship-server --enforce-seats limits each license to binding.max
  distinct machines (issue --max-machines N). The loader sends its signed
  license and machine fingerprint; the server verifies the license (against
  --license-keys, default the --sign public key), checks id and policy, and
  answers 409 when the seats are full (ErrSeatLimit in the loader). Seats
  lapse after --seat-lease (30 days) and persist in --seats-file. A modified
  loader can report any fingerprint, so this is an honest-customer limit.
- 502/503/504 from a proxy in front of the server count as an outage for
  CRYPTSHIP_ONLINE_GRACE; 410 still wins.

IMPROVEMENTS.md item 6 (the remainder after #10 / #11).
--expires YYYY-MM-DD still means 00:00:00 UTC on that date (unchanged, so
existing scripts keep their meaning); --expires-end-of-day makes the license
valid through 23:59:59 UTC. issue now prints the exact expiry instant, and
refuses --expires together with --days instead of silently ignoring --days.

IMPROVEMENTS.md item 7.
mktemp -d creates the work dir 0700, and on Linux the bind mount keeps that,
so the mermaid-cli container user (uid 1001) could not read the blocks
("Input file ... doesn't exist"). It passed in CI only because the GitHub
runner user happens to be uid 1001 too.

Open the dir 0755 with 0644 blocks, mount it read-only, and have mmdc write the
SVG to stdout. Running the container as our uid is not enough: Chromium
crashes without a passwd entry and home. Verified in the colima Linux VM as
uid 501 with umask 077: all diagrams render, and a broken block still fails.

IMPROVEMENTS.md item 8.
- FuzzParse: no panic; anything accepted round-trips, has a supported
  version, and never verifies under an unrelated key.
- FuzzUntar / FuzzReadFile: no panic, nothing written outside dest, no
  symlink in dest that points or resolves outside it, size limit held.
- FuzzVerifyKeyResponse / FuzzVerifyCheckResponse /
  FuzzVerifyAttestedKeyResponse: no panic; accepted answers match the license
  and nonce, carry a valid signature, and attested ones no plaintext secret.
- FuzzCheckChallenge: an accepted challenge is bound to its license and key.

Seeds run with go test; CI also fuzzes each target for 10s. Each ran 30s
locally with no findings.

IMPROVEMENTS.md item 12.
secureTree now sets the mode before the owner, while root still owns each
entry, so the loader needs only CAP_CHOWN, CAP_SETUID and CAP_SETGID (no
CAP_FOWNER) when CRYPTSHIP_EXTRACT_OWNER is not root.

demo.sh step 7 runs the image as root with --cap-drop=ALL plus those three,
no-new-privileges, the seccomp profile, a read-only rootfs and
CRYPTSHIP_APP_USER=65532:65532, and checks the app runs as 65532 and cannot
modify or add files in its code tree.
README, ARCHITECTURE, HOWTO, DIAGRAMS, deploy/README and CHANGELOG now cover:
the sealed revocation-grace record; the attested challenge / ephemeral-key
protocol; policy-bound server secrets (binding.secret_v,
--server-secret-version, --no-legacy-secrets); seats; gateway errors as
outages for the grace cache; the binding-derived state key; the opt-in
separate-uid extraction, memfd exec and dumpable helpers (with a tested
docker run recipe); --expires-end-of-day.

Known limits stay stated: no production SEV-SNP/TDX verifier, deleting state
resets the clock check, seats trust the reported fingerprint, the grace window
can be used on purpose by blocking the server, the app's own uid can read its
code, and the challenge spent-list is in memory.
FuzzParse found that License.Marshal changed the signed bytes of a license
whose claims contain a literal '&', '<' or '>': encoding/json HTML-escapes
raw JSON on output. Such a license (signed by a non-Go issuer, say) then no
longer verified after a Parse / Marshal round trip, which the seat check now
does on the server. Marshal now disables HTML escaping. Licenses made by
Sign are unchanged (their claims are already escaped).

The fuzz property now requires a byte-for-byte round trip for compact
claims; encoding/json still compacts hand-written whitespace.
… echo

The memfd test copied the system echo as the payload; on some runners echo is a
multi-call binary that rejects a mismatched argv[0] when run from a memfd
(argv[0]=tool vs exe /memfd:cryptship-app), which failed CI on amd64 while
passing elsewhere. Build a tiny static ELF that prints os.Args[1] instead.
@skalvinnathan
skalvinnathan merged commit 4855af4 into main Nov 15, 2026
2 checks passed
@skalvinnathan
skalvinnathan deleted the feat/improvements-impl-v2 branch November 15, 2026 18:48
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant