common

package module
v0.1.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jun 10, 2026 License: BSD-3-Clause Imports: 0 Imported by: 0

README

go-tpm2/common

The transport-agnostic, platform-agnostic foundation shared by every layer of the pure-Go TPM 2.0 stack in the go-tpm2 family. It mirrors the role of go-virtio/common: it owns the small plug-in interfaces, the big-endian TPM 2.0 wire codec, and the spec-derived constants. The higher layer (the tpm2 command layer) and the lower layers (the crb/tis/passthrough/socket transports) sit on either side and import this package.

Interfaces

Two interfaces stitch the stack together.

Transport (transport.go)

The contract a concrete transport implements and the command layer consumes. Deliberately minimal:

type Transport interface {
        Send(cmd []byte) (rsp []byte, err error)
}

The command layer marshals a complete command buffer (header + parameters, via BuildCommand), hands it to Send, and gets the complete response buffer back (ready for ParseResponse). Framing, MMIO handshakes, locality, and retry stay inside the transport.

Regs (regs.go)

The platform-provided MMIO accessor that the register-level drivers (CRB, TIS) use to touch the TPM register block — the analogue of go-virtio's BAR accessor. off is a byte offset within the TPM register window.

type Regs interface {
        Read8(off uint32) uint8
        Read32(off uint32) uint32
        Write8(off uint32, v uint8)
        Write32(off uint32, v uint32)
}

Plus byte-stream helpers for the CRB command buffer / TIS FIFO:

func ReadBytes(r Regs, off uint32, p []byte)
func WriteBytes(r Regs, off uint32, p []byte)

Wire codec (codec.go) — BIG-ENDIAN

The TPM 2.0 wire encoding is big-endian throughout (TCG "TPM 2.0 Part 1: Architecture", data marshaling / canonicalization). Every multi-byte field is most-significant-byte first.

func BuildCommand(tag uint16, cc uint32, params []byte) []byte
func ParseResponse(rsp []byte) (tag uint16, rc uint32, params []byte, err error)

func MarshalTPM2B(b []byte) []byte
func UnmarshalTPM2B(b []byte) (val, rest []byte, err error)

Command/response header (10 bytes, HeaderSize):

command:  [ tag:u16 | commandSize:u32  | commandCode:u32  | params... ]
response: [ tag:u16 | responseSize:u32 | responseCode:u32 | params... ]

TPM2B: [ size:u16 | bytes... ].

Big-endian primitive helpers (PutU8/16/32/64, GetU8/16/32/64) back the framing code; the bounds-checked getters return ok=false rather than panic. Typed sentinel errors ErrShortBuffer and ErrSizeMismatch cover every short/inconsistent-buffer branch.

Constants (const.go)

Typed, spec-cited starter sets: TPM_ST, TPM_CC, TPM_RC, TPM_SU, TPM_ALG, and well-known TPM_RH handles. Each cites TCG "TPM 2.0 Part 2: Structures".

Conventions

  • Pure Go, CGO_ENABLED=0, no architecture-specific assembly.
  • BSD-3-Clause on every file.
  • 100% statement coverage (GOWORK=off go test -cover ./...).
  • GOWORK=off — this module is not part of any workspace.
  • Spec-traceable: every struct/const cites its TCG TPM 2.0 Part number.

License

BSD-3-Clause. See LICENSE.

Documentation

Overview

Package common holds the transport-agnostic, platform-agnostic foundation shared by every layer of the pure-Go TPM 2.0 stack in the go-tpm2 family. It mirrors the role of go-virtio/common: it owns the small plug-in interfaces, the big-endian TPM 2.0 wire codec, and the spec-derived constants, while the higher layers (the tpm2 command layer) and the lower layers (the crb/tis/passthrough/socket transports) sit on either side and import this package.

Two interfaces stitch the stack together:

  • Transport: the contract a transport implements and the tpm2 command layer consumes. It exchanges one fully-marshaled TPM command buffer for the full response buffer (see transport.go).

  • Regs: the platform-provided MMIO accessor that the register-level drivers (CRB, TIS) use to touch the TPM register window. It is the analogue of go-virtio's BAR accessor (see regs.go).

The wire codec (codec.go) builds and parses the 10-byte TPM 2.0 command/response header and the ubiquitous TPM2B size-prefixed blob.

Wire format note: the TPM 2.0 wire encoding is BIG-ENDIAN throughout (TCG "TPM 2.0 Part 1: Architecture", clause "Data Marshaling" / "Canonicalization"). Every multi-byte field in this package is encoded most-significant-byte first.

Conventions: pure Go, CGO_ENABLED=0, no architecture-specific assembly, BSD-3-Clause on every file, 100% statement coverage, and GOWORK=off (the module is not part of any workspace).

Index

Constants

View Source 
const (
	// ErrShortBuffer is returned when a buffer is too small to hold the
	// structure being parsed (header, size prefix, or declared payload).
	ErrShortBuffer = Error("tpm2: buffer too short")
	// ErrSizeMismatch is returned when an embedded length field does not
	// agree with the actual buffer length.
	ErrSizeMismatch = Error("tpm2: declared size does not match buffer length")
)

Codec error sentinels. They are typed (Error) and constant, so callers may compare with ==.

View Source 
const HeaderSize = 10

HeaderSize is the byte length of the common TPM 2.0 command and response header: a 16-bit tag, a 32-bit size, and a 32-bit code. 

command:  [ tag:u16 | commandSize:u32  | commandCode:u32  | params... ]
response: [ tag:u16 | responseSize:u32 | responseCode:u32 | params... ]

TCG "TPM 2.0 Part 1: Architecture", "Command/Response Structure"; TCG "TPM 2.0 Part 2: Structures", TPM2_COMMAND_HEADER / TPM2_RESPONSE_HEADER.

Variables

This section is empty.

Functions

func BuildCommand 

func BuildCommand(tag uint16, cc uint32, params []byte) []byte

BuildCommand marshals a TPM 2.0 command buffer: 

[ tag:u16 | commandSize:u32 | commandCode:u32 | params... ]

commandSize is the total byte length of the buffer (HeaderSize plus len(params)).

func GetU8 

func GetU8(b []byte, off int) (v uint8, ok bool)

GetU8 reads one byte from b at off. ok is false if b is too short.

func GetU16 

func GetU16(b []byte, off int) (v uint16, ok bool)

GetU16 reads a big-endian uint16 from b at off. ok is false if b is too short.

func GetU32 

func GetU32(b []byte, off int) (v uint32, ok bool)

GetU32 reads a big-endian uint32 from b at off. ok is false if b is too short.

func GetU64 

func GetU64(b []byte, off int) (v uint64, ok bool)

GetU64 reads a big-endian uint64 from b at off. ok is false if b is too short.

func MarshalTPM2B 

func MarshalTPM2B(b []byte) []byte

MarshalTPM2B wraps b in a TPM2B structure: 

[ size:u16 | bytes... ]

TCG "TPM 2.0 Part 2: Structures", clause "TPM2B Types".

func ParseResponse 

func ParseResponse(rsp []byte) (tag uint16, rc uint32, params []byte, err error)

ParseResponse validates and decomposes a TPM 2.0 response buffer: 

[ tag:u16 | responseSize:u32 | responseCode:u32 | params... ]

It checks len(rsp) >= HeaderSize and that the embedded responseSize equals len(rsp), then returns the tag, the responseCode (rc), and the parameter bytes that follow the 10-byte header. params aliases rsp; it is not copied.

func PutU8 

func PutU8(dst []byte, v uint8) []byte

PutU8 appends v to dst.

func PutU16 

func PutU16(dst []byte, v uint16) []byte

PutU16 appends v to dst in big-endian order.

func PutU32 

func PutU32(dst []byte, v uint32) []byte

PutU32 appends v to dst in big-endian order.

func PutU64 

func PutU64(dst []byte, v uint64) []byte

PutU64 appends v to dst in big-endian order.

func ReadBytes 

func ReadBytes(r Regs, off uint32, p []byte)

ReadBytes fills p by reading len(p) consecutive bytes from r starting at off, one byte at a time via Read8. It is used to drain the CRB command/response buffer and the TIS data FIFO, where the data is a byte stream rather than width-defined registers.

func UnmarshalTPM2B 

func UnmarshalTPM2B(b []byte) (val, rest []byte, err error)

UnmarshalTPM2B decodes a TPM2B from the front of b and returns the payload (val), the remaining bytes after it (rest), and an error if b is too short to hold the 2-byte size or the declared payload. val and rest alias b; they are not copied.

func WriteBytes 

func WriteBytes(r Regs, off uint32, p []byte)

WriteBytes writes p to r starting at off, one byte at a time via Write8. It is the counterpart of ReadBytes for filling the CRB command buffer / TIS FIFO.

Types

type Error 

type Error string

Error is the typed error returned by this package. Using a string-kind error lets callers compare against the exported sentinels with == and keeps every error value a compile-time constant (no allocation, safe for comparison across package boundaries).

func (Error) Error 

func (e Error) Error() string

Error implements the error interface.

type Regs 

type Regs interface {
	Read8(off uint32) uint8
	Read32(off uint32) uint32
	Write8(off uint32, v uint8)
	Write32(off uint32, v uint32)
}

Regs is the platform-provided MMIO accessor that the register-level TPM drivers (CRB, TIS) use to touch the TPM register block. It is the analogue of go-virtio's BAR accessor: the platform owns the actual mapping (a physical MMIO window, an mmap of /dev/mem, or a test stub) and exposes it through these four primitives.

off is a byte offset within the TPM register window (for example, the TIS register file conventionally begins at the locality base and the CRB control area at its own base; the driver adds the field offset). Multi-byte accesses use the platform's native register width; the TPM register semantics for which width to use at which offset belong to the driver, not here.

type TPM_ALG 

type TPM_ALG uint16

TPM_ALG is an algorithm identifier. TCG "TPM 2.0 Part 2: Structures", clause "TPM_ALG_ID", with the registered values published in the TCG "Algorithm Registry". 

const (
	AlgSHA1   TPM_ALG = 0x0004
	AlgSHA256 TPM_ALG = 0x000B
	AlgSHA384 TPM_ALG = 0x000C
	AlgNull   TPM_ALG = 0x0010
)

type TPM_CC 

type TPM_CC uint32

TPM_CC is a command code. TCG "TPM 2.0 Part 2: Structures", clause "TPM_CC (Command Codes)". This is a starter set; the full table is large and grows with the command layer. 

const (
	CCStartup       TPM_CC = 0x00000144
	CCShutdown      TPM_CC = 0x00000145
	CCGetCapability TPM_CC = 0x0000017A
	CCGetRandom     TPM_CC = 0x0000017B
	CCPCRRead       TPM_CC = 0x0000017E
	CCPCRExtend     TPM_CC = 0x00000182
	CCQuote         TPM_CC = 0x00000158
	CCPCRReset      TPM_CC = 0x0000013D
	CCSelfTest      TPM_CC = 0x00000143
	CCCreate        TPM_CC = 0x00000153
	CCCreatePrimary TPM_CC = 0x00000131
	CCLoad          TPM_CC = 0x00000157
)

type TPM_RC 

type TPM_RC uint32

TPM_RC is a response code. TCG "TPM 2.0 Part 2: Structures", clause "TPM_RC (Response Codes)". 

const (
	// RCSuccess indicates the command completed without error.
	RCSuccess TPM_RC = 0x000
)

type TPM_RH 

type TPM_RH uint32

TPM_RH is a permanent (well-known) handle. TCG "TPM 2.0 Part 2: Structures", clause "TPM_RH (Permanent Handles)" and "TPM_HT (Handle Types)". PCR handles occupy the 0x00000000..0x0000001F range; this stack uses 0..23 (PCRFirst..PCRLast). 

const (
	// RHOwner is the Owner (Storage) hierarchy handle.
	RHOwner TPM_RH = 0x40000001
	// RHNull is the null hierarchy / null handle.
	RHNull TPM_RH = 0x40000007
	// RHPlatform is the Platform hierarchy handle.
	RHPlatform TPM_RH = 0x4000000C

	// PCRFirst is the handle of PCR[0]; PCR handles run 0..23.
	PCRFirst TPM_RH = 0x00000000
	// PCRLast is the handle of PCR[23], the last architecturally
	// defined PCR.
	PCRLast TPM_RH = 0x00000017
)

type TPM_ST 

type TPM_ST uint16

TPM_ST is a structure tag. TCG "TPM 2.0 Part 2: Structures", clause "TPM_ST (Structure Tags)". 

const (
	// TagNoSessions tags a command/response whose body carries no
	// session area.
	TagNoSessions TPM_ST = 0x8001
	// TagSessions tags a command/response that carries one or more
	// authorization/audit sessions after the handle area.
	TagSessions TPM_ST = 0x8002
)

type TPM_SU 

type TPM_SU uint16

TPM_SU is a startup/shutdown type, the parameter to TPM2_Startup and TPM2_Shutdown. TCG "TPM 2.0 Part 2: Structures", clause "TPM_SU (Startup Type)". 

const (
	// SUClear requests a Startup(CLEAR) / Shutdown(CLEAR).
	SUClear TPM_SU = 0x0000
	// SUState requests a Startup(STATE) / Shutdown(STATE).
	SUState TPM_SU = 0x0001
)

type Transport 

type Transport interface {
	// Send transmits one fully-marshaled TPM command buffer and returns
	// the full response buffer. The returned buffer includes the 10-byte
	// TPM 2.0 response header and is suitable for ParseResponse.
	Send(cmd []byte) (rsp []byte, err error)
}

Transport is the contract a concrete TPM transport (CRB, TIS, passthrough to a host /dev/tpm0, or a TCP socket to a software TPM) implements, and that the tpm2 command layer consumes.

It is deliberately minimal: the command layer marshals a complete TPM 2.0 command buffer (header + parameters, as produced by BuildCommand), hands it to Send, and receives the complete response buffer (header + parameters) back. Framing, MMIO register handshakes, locality, and retry are entirely the transport's concern and never leak into this interface.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.