{"id":51461015,"url":"https://github.com/deploymenttheory/go-sdk-vtpm2","last_synced_at":"2026-07-06T05:30:30.176Z","repository":{"id":366898655,"uuid":"1278236148","full_name":"deploymenttheory/go-sdk-vtpm2","owner":"deploymenttheory","description":"A pure Go software TPM 2.0 (vTPM) implementation. Including features such as measured boot, BitLocker sealing \u0026 attestation for Windows 11 guests under QEMU, built from the TCG spec.","archived":false,"fork":false,"pushed_at":"2026-06-30T20:54:31.000Z","size":6196,"stargazers_count":0,"open_issues_count":5,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-30T22:24:33.346Z","etag":null,"topics":["attestation","bitlocker","emulator","go","golang","measured-boot","qemu","security","swtpm","tcg","tpm","tpm2","trusted-computing","virtualization","vtpm","windows-11"],"latest_commit_sha":null,"homepage":"https://trustedcomputinggroup.org/resource/tpm-library-specification/","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/deploymenttheory.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-06-23T15:41:48.000Z","updated_at":"2026-06-30T20:54:27.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/deploymenttheory/go-sdk-vtpm2","commit_stats":null,"previous_names":["deploymenttheory/go-sdk-vtpm2"],"tags_count":0,"template":false,"template_full_name":"deploymenttheory/Template","purl":"pkg:github/deploymenttheory/go-sdk-vtpm2","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/deploymenttheory%2Fgo-sdk-vtpm2","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/deploymenttheory%2Fgo-sdk-vtpm2/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/deploymenttheory%2Fgo-sdk-vtpm2/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/deploymenttheory%2Fgo-sdk-vtpm2/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/deploymenttheory","download_url":"https://codeload.github.com/deploymenttheory/go-sdk-vtpm2/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/deploymenttheory%2Fgo-sdk-vtpm2/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35179683,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-07-06T02:00:07.184Z","response_time":106,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["attestation","bitlocker","emulator","go","golang","measured-boot","qemu","security","swtpm","tcg","tpm","tpm2","trusted-computing","virtualization","vtpm","windows-11"],"created_at":"2026-07-06T05:30:28.416Z","updated_at":"2026-07-06T05:30:30.160Z","avatar_url":"https://github.com/deploymenttheory.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# go-sdk-vtpm2\n\n**A pure-Go TPM 2.0 — no cgo, no `swtpm`, no `libtpms`.**\n\n`go-sdk-vtpm2` is a TPM 2.0 device implemented from scratch in Go: the command\nprocessor, the cryptography, the state persistence, and the QEMU transport — all\nbuilt directly from the [TCG TPM 2.0 Library\nSpecification](https://trustedcomputinggroup.org/resource/tpm-library-specification/),\nwith no external (non-Go) dependencies and no cgo.\n\nIt gives a hypervisor a **virtual TPM for Windows 11 guests** — measured boot,\nBitLocker sealing, and attestation — that you `go build` into a single static\nbinary, instead of shipping and managing a native service like `swtpm` or\n`libtpms`. It speaks the swtpm control/data protocol, so QEMU's `tpm-emulator`\nbackend connects to it unmodified.\n\nThis is the **TPM itself** (the responder that executes commands), not a client\nlibrary, driver, or set of bindings. The entire public surface of the core is:\n\n```go\nfunc (t *tpm2.TPM) Execute(command []byte) (response []byte)\n```\n\nRaw TPM command blob in, raw response blob out.\n\n## Why it exists / design targets\n\n| Target | What it means |\n|---|---|\n| **Zero native dependencies** | Pure Go. No cgo, no `swtpm`/`libtpms` binaries, no Homebrew. One `go build` produces a static, cross-compilable binary. |\n| **Embeddable, transport-agnostic core** | The command processor is just `Execute([]byte) []byte`. Drop it behind QEMU, a unit test, a fuzzer, or your own transport. |\n| **swtpm / QEMU wire-compatible** | Implements the swtpm control + data channels (incl. `SET_DATAFD`, state-blob save/restore, locality), so QEMU's `-tpmdev emulator` is a drop-in. |\n| **Reboot-persistent** | Versioned snapshots persist the EK/SRK, NV, PCRs, and clock. Sealed secrets (the BitLocker VMK) survive guest reboots — the requirement that makes a vTPM actually usable. |\n| **Spec-correct** | Every command code and response code is checked against the reference implementation. The HMAC/`cpHash` authorization path is validated against golden vectors. Format-one response codes are encoded correctly (a class of bug a lot of toy TPMs get wrong). |\n\nThe whole build is sequenced toward one concrete goal: **a real Windows 11 guest\nbooting with BitLocker** against this vTPM under QEMU.\n\n## What it implements\n\n**125 TPM 2.0 commands** — essentially the full v1.85 surface a software TPM can\nmeaningfully implement (the 11 unimplemented are firmware-upgrade, Attached-Component\nand a couple of v2 NV/capability variants that need physical hardware; the dispatcher\nreturns `TPM_RC_COMMAND_CODE` for those, as the spec prescribes):\n\n| Area | Commands |\n|---|---|\n| **Boot \u0026 test** | `Startup`, `Shutdown`, `SelfTest`, `IncrementalSelfTest`, `GetTestResult`, `GetRandom`, `StirRandom`, `TestParms` |\n| **Capabilities \u0026 management** | `GetCapability`, `SetAlgorithmSet`, `PP_Commands`, `SetCommandCodeAuditStatus`, `ReadOnlyControl`, `ACT_SetTimeout` |\n| **Measured boot (PCR)** | `PCR_Read`, `PCR_Extend`, `PCR_Event`, `PCR_Reset`, `PCR_Allocate`, `PCR_SetAuthValue`, `PCR_SetAuthPolicy` |\n| **Hierarchies \u0026 clock** | `Clear`, `ClearControl`, `HierarchyChangeAuth`, `HierarchyControl`, `SetPrimaryPolicy`, `ChangeEPS`, `ChangePPS`, `ReadClock`, `ClockSet`, `ClockRateAdjust` |\n| **Sessions \u0026 DA** | `StartAuthSession`, `FlushContext`, `DictionaryAttackLockReset`, `DictionaryAttackParameters` |\n| **Policy (full set)** | all ~23 assertions — `PolicyPCR`, `PolicyOR`, `PolicyAuthValue`/`Password`, `PolicySecret`, `PolicySigned`, `PolicyAuthorize`(`NV`), `PolicyCommandCode`, `PolicyCpHash`, `PolicyNameHash`, `PolicyNV`, `PolicyCounterTimer`, `PolicyTicket`, `PolicyDuplicationSelect`, `PolicyTemplate`, `PolicyParameters`, `PolicyCapability`, `PolicyTransportSPDM`, … |\n| **Objects \u0026 key lifecycle** | `CreatePrimary`, `Create`, `CreateLoaded`, `Load`, `LoadExternal`, `ReadPublic`, `EvictControl`, `ObjectChangeAuth`, `ContextSave`, `ContextLoad` |\n| **Duplication \u0026 credentials** | `Duplicate`, `Import`, `Rewrap`, `MakeCredential`, `ActivateCredential` |\n| **Signing, hashing \u0026 attestation** | `Sign`, `SignDigest`, `VerifySignature`, `VerifyDigestSignature`, sign/verify **sequences**, `Hash`, `HMAC`, hash sequences, `Quote`, `Certify`, `CertifyCreation`, `CertifyX509`, `GetTime`, `NV_Certify`, `GetSessionAuditDigest`, `GetCommandAuditDigest`, `Unseal` |\n| **Asymmetric \u0026 symmetric crypto** | `RSA_Encrypt`/`Decrypt`, `ECC_Encrypt`/`Decrypt`, `ECDH_KeyGen`/`ZGen`, `ZGen_2Phase`, `Commit`, `EC_Ephemeral`, `Encapsulate`/`Decapsulate`, `EncryptDecrypt`/`2`, `ECC_Parameters` |\n| **NV storage** | `NV_DefineSpace`, `NV_UndefineSpace`(`Special`), `NV_ReadPublic`, `NV_Read`, `NV_Write`, `NV_Increment`, `NV_Extend`, `NV_SetBits`, `NV_ReadLock`/`WriteLock`, `NV_GlobalWriteLock`, `NV_ChangeAuth` |\n\n**Authorization:** password, HMAC, and policy sessions with real HMAC\nverify/respond, salted and bound sessions, **parameter encryption in both\ndirections** (XOR and AES-CFB), and session + command **audit**.\n\n**Cryptography (Go standard library only):** RSA (RSASSA / RSA-PSS / OAEP),\nECC (NIST P-256 / P-384 / P-521; ECDSA / ECDH / ECDAA commit / SM2-style\nencryption / KEM), AES in CFB/OFB/CTR/CBC/ECB, HMAC, SHA-1/256/384/512, and the\nTPM key-derivation functions KDFa / KDFe, with the SP800-90A Hash_DRBG used for\ndeterministic primary derivation. Primary keys (EK/SRK) are **derived\ndeterministically** from the hierarchy seed, so a recreated SRK matches its\npersisted form and previously sealed blobs still load.\n\n## Architecture\n\n| Package | Responsibility |\n|---|---|\n| `tpm2/` | The TPM 2.0 command processor (the **responder**): wire types \u0026 marshalling, the command dispatch, the crypto, the auth/session engine, and versioned state snapshots. `Execute([]byte) []byte`. |\n| `client/` | The typed, in-process-native **client**: turns the raw `Execute` boundary into ergonomic Go calls (templates, typed commands), over any transport. No external TPM stack needed. |\n| `state/` | Atomic, per-VM persistence of a snapshot to disk (JSON, crash-safe temp-file + rename). |\n| `swtpm/` | The swtpm control + data channel protocol QEMU's `tpm-emulator` backend speaks (Unix sockets, fd passing, state blobs, locality). |\n| `emulator/` | Top-level wiring: TPM + persistence + transport into one runnable device, plus `Provision()`. |\n| `cmd/vtpm/` | A runnable vTPM server you point QEMU at. |\n\n## Usage\n\n### Embed it (typed client)\n\nThe `client` package gives you an in-process TPM with typed commands — no wire\nblobs, no external stack:\n\n```go\nc, _ := client.OpenLocal()                                  // an in-process TPM, started\nsrk, _ := c.CreatePrimary(client.HandleOwner, client.ECCStorageKey(), nil)\nkey, _ := c.CreateAndLoad(srk, client.ECCSigningKey(), []byte(\"auth\"))\n```\n\nOr drop to the raw boundary that *is* the TPM:\n\n```go\ntpm := tpm2.New()\nresponse := tpm.Execute(command) // raw TPM 2.0 command → raw response\n```\n\n### Run it for QEMU\n\n```sh\ngo build -o ./vtpm ./cmd/vtpm\n./vtpm -ctrl /tmp/vtpm-ctrl.sock -state ./vtpm-state -provision\n```\n\nThen point QEMU at the control socket:\n\n```sh\nqemu-system-x86_64 \\\n  -chardev socket,id=chrtpm,path=/tmp/vtpm-ctrl.sock \\\n  -tpmdev emulator,id=tpm0,chardev=chrtpm \\\n  -device tpm-tis,tpmdev=tpm0 \\\n  ...\n```\n\n### Guides\n\n- **[Getting started](docs/getting-started.md)** — install, build, run, and send\n  your first command in a few minutes.\n- **[Usage guide](docs/usage-guide.md)** — embedding the core, driving it from a\n  TPM stack, persistence, sessions/auth, and the QEMU integration in depth.\n\n## Persistence\n\nState is snapshotted to a per-VM directory and reloaded on the next boot, so the\nvTPM — and everything sealed against it — survives guest reboots. The snapshot is\nversioned and migrates forward; it currently carries PCR banks, the authorization\nhierarchies and their primary seeds, dictionary-attack lockout state, persistent\nobjects (EK/SRK), NV indices, and the clock.\n\n## Correctness\n\nThe implementation is reconciled against the vendored spec\n(`docs/spec/v185/`, Parts 1–3) in [`VALIDATION.md`](VALIDATION.md): a\n**261-point accuracy sweep** (constants, attribute bitfields, structure wire\nlayouts, crypto constructions, the authorization/policy engine, and per-command\nsemantics), each row carrying a Part + page citation. The sweep found and fixed\nfour conformance bugs and documents seven by-design deviations.\n\n- The `cpHash` / authorization-HMAC path — the most interoperability-sensitive\n  part — is checked two ways: against an independent in-test reimplementation, and\n  against optional golden vectors captured from a real TPM stack (see\n  `tpm2/testdata/`).\n- The reboot guarantee is tested end to end\n  (`tpm2/seal_test.go`): seal a secret under a persistent SRK, snapshot, restore\n  into a fresh TPM, and unseal it.\n\n`go test ./...` exercises the full surface (200+ tests in the `tpm2` package).\n\n## Status \u0026 limitations\n\nThe TPM core, the swtpm/QEMU transport, and provisioning are implemented and\ntested. Honest caveats:\n\n- **Software TPM, not a hardware security boundary.** State lives in host memory\n  and on-disk snapshots. This provides the TPM 2.0 *protocol and semantics*, not\n  hardware-grade isolation or tamper resistance.\n- **The live Windows-11-on-QEMU boot is not yet verified** — that step needs a\n  real QEMU + Windows 11 environment. The runner, launch script, and harness are\n  ready for it (`cmd/vtpm`, `scripts/`).\n- **11 of 136 spec commands are unimplemented** — firmware upgrade, Attached\n  Components, and a few v2 NV/capability variants that require physical hardware a\n  software TPM cannot provide; the dispatcher returns `TPM_RC_COMMAND_CODE` for\n  them, which is the spec-faithful response.\n\n## License\n\nMIT — see [`LICENSE`](LICENSE). This is a clean-room implementation written from\nthe public TCG TPM 2.0 Library Specification; it contains no code from, and is not\nderived from, any GPL-licensed TPM implementation.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdeploymenttheory%2Fgo-sdk-vtpm2","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdeploymenttheory%2Fgo-sdk-vtpm2","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdeploymenttheory%2Fgo-sdk-vtpm2/lists"}