Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
11 changes: 11 additions & 0 deletions .github/workflows/ci.yml
Original file line number Diff line number Diff line change
Expand Up @@ -38,6 +38,17 @@ jobs:
- name: test
run: go test -race ./...

- name: fuzz (10s per target)
run: |
for t in FuzzUntar:./pkg/archive FuzzReadFile:./pkg/archive FuzzParse:./pkg/license \
FuzzVerifyKeyResponse:./pkg/online FuzzVerifyCheckResponse:./pkg/online \
FuzzVerifyAttestedKeyResponse:./pkg/online FuzzCheckChallenge:./pkg/online; do
go test -run='^$' -fuzz="^${t%%:*}\$" -fuzztime=10s "${t#*:}"
done

- name: test Python helper
run: python3 -m unittest discover -s helpers/python -v

docs-diagrams:
runs-on: ubuntu-latest
steps:
Expand Down
24 changes: 24 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,6 +6,30 @@ GitHub releases.

## [Unreleased]

### Added (IMPROVEMENTS.md items)
- **Attested protocol:** server-issued single-use challenge (`POST /v1/challenge`),
evidence over `AttestationBinding(license, challenge, ephemeral key)`, and the
secret returned sealed to the ephemeral X25519 key. `online.AttestationNonce`
is replaced by `online.AttestationBinding`.
- **Policy-bound server secrets:** `binding.secret_v` 2 (default for new
licenses) derives the secret per binding policy, so an online server cannot
release an attested secret. `issue --server-secret-version 0` for old loaders;
`cryptship-server --no-legacy-secrets` once all licenses are reissued.
- **Seats:** `issue --max-machines N` + `cryptship-server --enforce-seats`
(`--seat-lease`, `--seats-file`, `--license-keys`).
- **Binding-derived state key** (`crypto.DeriveStateKey`, `keyprovider.Unlocker`)
seals the clock-rollback and revocation-grace records; the revocation-grace
record is no longer a plain-text timestamp.
- **Opt-in, off by default:** `CRYPTSHIP_APP_USER` (separate-uid extraction and
privilege drop) and `CRYPTSHIP_EXEC_MEMFD` (single ELF binary from a memfd);
`pkg/harden` and `helpers/python/cryptship_harden.py`.
- `issue --expires-end-of-day`; `--expires` with `--days` is now an error.
- 502/503/504 count as an outage for `CRYPTSHIP_ONLINE_GRACE`.
- Fuzz tests (license parsing, tar extraction, response decoders, challenges).

### Fixed
- `scripts/check-mermaid.sh` docker fallback on Linux (temp dir was 0700).

### Security / fixed (from a full code review)
- **Online grace cache reworked.** It now caches the **content key** instead of
the per-license binding secret (no portable license-wide credential), and the
Expand Down
50 changes: 30 additions & 20 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -63,8 +63,9 @@ Two checks remain ordinary code in the loader: the **signature** and the
unwraps on its own machine, so for enforced expiry use the `online` provider.
The loader also refuses to start when the clock is more than 24 hours behind
the latest start it recorded for an expiring license (sealed in
`CRYPTSHIP_STATE_DIR`), but deleting that state resets the check: it stops a
casual clock rollback, not a determined one. With binding `none`, the license
`CRYPTSHIP_STATE_DIR` under a key derived from the license's binding material),
but deleting that state resets the check: it stops a casual clock rollback, not
a determined one. With binding `none`, the license
itself carries the key material: treat it like a secret.

## Quickstart
Expand Down Expand Up @@ -112,15 +113,20 @@ acquired**. That is a single pluggable interface (`pkg/keyprovider`):
|---|---|---|---|
| **Air-gapped** | `offline` | machine fingerprint, or none | expiry only |
| **On-prem / cloud** | `online` | per-license secret held by your server | **real** — the server declines |
| **Confidential** | `attested` | SEV-SNP/TDX attestation gates the key | planned: interfaces + test-only verifier today |
| **Confidential** | `attested` | SEV-SNP/TDX attestation gates the key | protocol built (server challenge, key sealed to an ephemeral TEE key); SEV-SNP/TDX verifiers need hardware, test-only verifier today |

The loader, license format, crypto, and app are identical across all modes — only
the key provider differs. `offline` (none/strict/pool) and `online` are built and
tested; `online` uses the reference `cryptship-server` (a stateless key broker).
`attested` is built behind an `Attester` interface (loader) and an
`attest.Verifier` interface (server), each with a test-only implementation. There
is no production verifier yet, so `cryptship-server --require-attestation`
refuses to start rather than accept evidence it cannot check. Real SEV-SNP/TDX
`attest.Verifier` interface (server), each with a test-only implementation. The
protocol is replay-safe: the server issues a single-use challenge, the evidence
commits to it and to an ephemeral key made inside the TEE, and the secret comes
back encrypted to that key. Server secrets are derived per binding policy
(`binding.secret_v` 2), so an `online` server cannot release an `attested`
secret even with the same master key. There is no production verifier yet, so
`cryptship-server --require-attestation` refuses to start rather than accept
evidence it cannot check. Real SEV-SNP/TDX
quote generation needs confidential-compute hardware (see
[`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md)).

Expand All @@ -140,7 +146,11 @@ source reconstruction:
with the seccomp profile + non-root + dropped caps + read-only + tmpfs from
`deploy/`. Stops other non-root users in the container; anything running as
the app's own uid, container root or host root can still read the decrypted
files.
files. Optional: `CRYPTSHIP_APP_USER` extracts as a separate owner so the app
cannot modify its code, `CRYPTSHIP_EXEC_MEMFD` runs a single binary from
memory with no decrypted file on disk, and `pkg/harden` /
`helpers/python/cryptship_harden.py` let the app make itself non-dumpable
again after exec.
- **Per-license watermark** — the loader drops `.cryptship-manifest.json` and
exposes `CRYPTSHIP_LICENSE_ID` / `CRYPTSHIP_CUSTOMER` to the app, so a leaked
instance traces to its licensee (a deterrent — strippable).
Expand All @@ -163,19 +173,19 @@ for the full schema and the threat model.
**Built & tested:** AES-256-GCM payload encryption; Ed25519 licenses (detached
signature over the stored bytes); context-bound KEK (format v2: editing any claim breaks
the unwrap); machine binding (none / strict / pool); online key provider + reference
`cryptship-server`; signing-key rotation (key ring); configurable revocation
(open / closed / grace) with **signed** revocation checks; **live `--revoke-file`
revocation** (no restart); **online outage grace** (`CRYPTSHIP_ONLINE_GRACE`, a
machine-sealed cached content key with authenticated validity); the
compile/transform seam; loader + container hardening; per-license watermarking;
and the attested (confidential-compute) provider behind `Attester` /
`attest.Verifier` interfaces with test-only implementations (no production
verifier yet).

**Roadmap:** a real SEV-SNP/TDX `Attester` + Trustee-style KBS integration (and
the attested replay fix: server-issued challenge + ephemeral TEE key), TPM-sealed
binding, cloud-KMS wrapping, seat management, and chunked AEAD for very large
payloads.
`cryptship-server` (policy-bound server secrets, live denylist, seat limits,
sealed outage grace); signing-key rotation (key ring); signed, nonce-bound
revocation checks with configurable failure policy (open / closed / grace);
clock and grace state sealed under a binding-derived key; the compile/transform
seam; loader + container hardening (separate-uid extraction, memfd exec,
dumpable helpers); per-license watermarking; the attested (confidential-compute)
protocol behind `Attester` / `attest.Verifier` interfaces with test-only
implementations (no production verifier yet); and fuzz tests for license
parsing, extraction and the response decoders.

**Roadmap:** real SEV-SNP/TDX attesters and verifiers, TPM-sealed binding and
cloud instance identity, cloud-KMS wrapping, server-signed time for offline
expiry, and chunked AEAD for very large payloads.

## Crypto

Expand Down
79 changes: 26 additions & 53 deletions cmd/cryptship-loader/clock.go
Original file line number Diff line number Diff line change
@@ -1,17 +1,14 @@
package main

import (
"crypto/hkdf"
"crypto/sha256"
"encoding/binary"
"bytes"
"errors"
"fmt"
"io/fs"
"os"
"path/filepath"
"time"

"github.com/AI2TH/cryptship/pkg/crypto"
"github.com/AI2TH/cryptship/pkg/license"
)

Expand All @@ -25,81 +22,57 @@ const clockStateInfo = "cryptship/clock-state/v1"

// checkClock is a best-effort clock-rollback check for licenses that expire.
// It keeps the latest start time seen for the license in the state dir,
// sealed (AES-GCM) under a key derived from the content key, so the file
// cannot be edited to an earlier time without the key. If the clock is now
// more than clockTolerance behind that time, the loader refuses to start.
// sealed (AES-GCM) under a key derived from stateKey — the binding-derived
// state key (crypto.DeriveStateKey of this machine's fingerprint or the
// server secret, and the license claims) — so the file cannot be edited, or
// copied from another license or machine, without that binding. If the clock
// is now more than clockTolerance behind that time, the loader refuses to
// start.
//
// A record written by an older loader (sealed under a key derived from the
// content key, legacyKey) is still honoured once and rewritten under
// stateKey, so upgrading the loader does not reset the check.
//
// Limits, by design: deleting the state file (or running with a fresh state
// dir) resets the check, and a state dir that cannot be written disables it
// with a warning. It raises the bar against casually setting the clock back
// to keep an expired license running; for enforced expiry use the online
// provider.
func checkClock(dir string, c license.Claims, contentKey []byte, now time.Time) error {
func checkClock(dir string, c license.Claims, stateKey, legacyKey []byte, now time.Time) error {
if c.NotAfter == 0 {
return nil // nothing expires, nothing to protect
}
key, err := hkdf.Key(sha256.New, contentKey, []byte(c.LicenseID), clockStateInfo, crypto.KeySize)
if err != nil {
return err
}
defer crypto.Wipe(key)
aad := []byte(clockStateInfo + "\x00" + c.LicenseID)
path := filepath.Join(dir, "clock-"+escapeID(c.LicenseID))
st := sealedState{info: clockStateInfo, licenseID: c.LicenseID, path: filepath.Join(dir, "clock-"+escapeID(c.LicenseID))}

latest := now.Unix()
switch blob, err := os.ReadFile(path); {
case err == nil:
pt, oerr := crypto.Open(key, blob, aad)
if oerr != nil || len(pt) != 8 {
warnf("clock state %s is not valid for this license and build; starting it again", path)
break
last, err := st.read(stateKey)
if errors.Is(err, errBadState) && legacyKey != nil && !bytes.Equal(legacyKey, stateKey) {
if l, lerr := st.read(legacyKey); lerr == nil {
last, err = l, nil // migrate a record from an older loader
}
last := int64(binary.BigEndian.Uint64(pt))
}
switch {
case err == nil:
if now.Unix() < last-int64(clockTolerance/time.Second) {
return fmt.Errorf("system clock (%s) is more than %s behind the latest start recorded for license %s (%s); refusing to start. Correct the clock; the record is %s",
now.UTC().Format(time.RFC3339), clockTolerance, c.LicenseID, time.Unix(last, 0).UTC().Format(time.RFC3339), path)
now.UTC().Format(time.RFC3339), clockTolerance, c.LicenseID, time.Unix(last, 0).UTC().Format(time.RFC3339), st.path)
}
if last > latest {
latest = last
}
case errors.Is(err, fs.ErrNotExist):
case errors.Is(err, errBadState):
warnf("clock state %s is not valid for this license and build; starting it again", st.path)
default:
warnf("clock-rollback check: cannot read %s: %v", path, err)
warnf("clock-rollback check: cannot read %s: %v", st.path, err)
}

var b [8]byte
binary.BigEndian.PutUint64(b[:], uint64(latest))
sealed, err := crypto.Seal(key, b[:], aad)
if err != nil {
return err
}
if err := writeFileAtomic(path, sealed); err != nil {
warnf("clock-rollback check disabled: cannot write %s: %v", path, err)
if err := st.write(stateKey, latest); err != nil {
warnf("clock-rollback check disabled: cannot write %s: %v", st.path, err)
}
return nil
}

// writeFileAtomic writes via a temp file and rename, so a crash never leaves
// a truncated state file.
func writeFileAtomic(path string, data []byte) error {
if err := os.MkdirAll(filepath.Dir(path), 0o700); err != nil {
return err
}
tmp, err := os.CreateTemp(filepath.Dir(path), ".tmp-"+filepath.Base(path)+"-*")
if err != nil {
return err
}
defer os.Remove(tmp.Name())
if _, err := tmp.Write(data); err != nil {
tmp.Close()
return err
}
if err := tmp.Close(); err != nil {
return err
}
return os.Rename(tmp.Name(), path)
}

func warnf(format string, args ...any) {
fmt.Fprintf(os.Stderr, "cryptship-loader: WARNING: "+format+"\n", args...)
}
46 changes: 37 additions & 9 deletions cmd/cryptship-loader/clock_test.go
Original file line number Diff line number Diff line change
Expand Up @@ -18,23 +18,23 @@ func TestCheckClockDetectsRollback(t *testing.T) {
now := time.Now()
c := license.Claims{LicenseID: "lic_clock", NotAfter: now.Add(30 * 24 * time.Hour).Unix()}

if err := checkClock(dir, c, key, now); err != nil {
if err := checkClock(dir, c, key, nil, now); err != nil {
t.Fatalf("first start: %v", err)
}
// Small step back (NTP correction): allowed.
if err := checkClock(dir, c, key, now.Add(-time.Hour)); err != nil {
if err := checkClock(dir, c, key, nil, now.Add(-time.Hour)); err != nil {
t.Fatalf("1h back: %v", err)
}
// The record keeps the latest time, not the last one.
if err := checkClock(dir, c, key, now.Add(-clockTolerance-time.Hour)); err == nil || !strings.Contains(err.Error(), "behind") {
if err := checkClock(dir, c, key, nil, now.Add(-clockTolerance-time.Hour)); err == nil || !strings.Contains(err.Error(), "behind") {
t.Fatalf("rollback past tolerance: err = %v", err)
}
// Moving forward is fine and raises the record.
later := now.Add(10 * 24 * time.Hour)
if err := checkClock(dir, c, key, later); err != nil {
if err := checkClock(dir, c, key, nil, later); err != nil {
t.Fatal(err)
}
if err := checkClock(dir, c, key, now); err == nil {
if err := checkClock(dir, c, key, nil, now); err == nil {
t.Fatal("rollback below the raised record accepted")
}
}
Expand All @@ -44,7 +44,7 @@ func TestCheckClockStateIsSealed(t *testing.T) {
key, _ := crypto.RandomKey()
now := time.Now()
c := license.Claims{LicenseID: "lic_seal", NotAfter: now.Add(time.Hour).Unix()}
if err := checkClock(dir, c, key, now.Add(48*time.Hour)); err != nil {
if err := checkClock(dir, c, key, nil, now.Add(48*time.Hour)); err != nil {
t.Fatal(err)
}
path := filepath.Join(dir, "clock-lic_seal")
Expand All @@ -60,11 +60,11 @@ func TestCheckClockStateIsSealed(t *testing.T) {
if err := os.WriteFile(filepath.Join(dir, "clock-lic_other"), blob, 0o600); err != nil {
t.Fatal(err)
}
if err := checkClock(dir, other, key, now); err != nil {
if err := checkClock(dir, other, key, nil, now); err != nil {
t.Fatalf("a record copied from another license must be ignored, got %v", err)
}
// Licenses without expiry are not checked and leave no state.
if err := checkClock(dir, license.Claims{LicenseID: "lic_forever"}, key, now); err != nil {
if err := checkClock(dir, license.Claims{LicenseID: "lic_forever"}, key, nil, now); err != nil {
t.Fatal(err)
}
if _, err := os.Stat(filepath.Join(dir, "clock-lic_forever")); !os.IsNotExist(err) {
Expand All @@ -81,7 +81,35 @@ func TestCheckClockUnwritableStateDirDoesNotBlock(t *testing.T) {
key, _ := crypto.RandomKey()
now := time.Now()
c := license.Claims{LicenseID: "lic_ro", NotAfter: now.Add(time.Hour).Unix()}
if err := checkClock(filepath.Join(file, "state"), c, key, now); err != nil {
if err := checkClock(filepath.Join(file, "state"), c, key, nil, now); err != nil {
t.Fatalf("unwritable state dir must not stop the loader: %v", err)
}
}

// A record sealed by an older loader (content-key-derived) is honoured once
// and rewritten under the binding-derived state key.
func TestCheckClockMigratesLegacyRecord(t *testing.T) {
dir := t.TempDir()
contentKey, _ := crypto.RandomKey()
stateKey, _ := crypto.RandomKey()
now := time.Now()
c := license.Claims{LicenseID: "lic_mig", NotAfter: now.Add(90 * 24 * time.Hour).Unix()}
// Older loader: record sealed under the content key, 10 days ahead.
if err := checkClock(dir, c, contentKey, nil, now.Add(10*24*time.Hour)); err != nil {
t.Fatal(err)
}
if err := checkClock(dir, c, stateKey, contentKey, now); err == nil {
t.Fatal("legacy record ignored: rollback after upgrade not detected")
}
// After a valid start the record is under the state key only.
if err := checkClock(dir, c, stateKey, contentKey, now.Add(10*24*time.Hour)); err != nil {
t.Fatal(err)
}
st := sealedState{info: clockStateInfo, licenseID: c.LicenseID, path: filepath.Join(dir, "clock-lic_mig")}
if _, err := st.read(stateKey); err != nil {
t.Fatalf("record not rewritten under the state key: %v", err)
}
if _, err := st.read(contentKey); err == nil {
t.Fatal("record still readable with the content key")
}
}
Loading
Loading