tpm

Documentation

Overview

Package tpm provides TPM 2.0 functionality using native Go. This implementation uses google/go-tpm with the tpmdirect API which provides native PolicyAuthorizeNV support required for pcrlock tokens.

Index

• Constants
• Variables
• func DeriveAuthValue(pin string, salt []byte) []byte
• func HashPIN(pin string) []byte
• func ParseBlob(blob []byte) (private, public []byte, err error)
• type Client
  • func New() *Client
  • func NewWithDevice(device string) *Client
  • func (c *Client) FindPCRLockNVIndex() (uint32, error)
  • func (c *Client) GetLockoutStatus() (*LockoutStatus, error)
  • func (c *Client) ListNVIndexes() (map[uint32][]byte, error)
  • func (c *Client) NVReadPublic(index uint32) ([]byte, error)
  • func (c *Client) ReadAllPCRValues(bank HashAlgorithm) (map[uint][]byte, error)
  • func (c *Client) ReadPCRValues(bank HashAlgorithm, pcrs []uint) (map[uint][]byte, error)
  • func (c *Client) ReadPCRs(bank HashAlgorithm, pcrs []int) (map[int][]byte, error)
  • func (c *Client) Unseal(public, private []byte, pcrs []int, bank HashAlgorithm, ...) ([]byte, error)
  • func (c *Client) UnsealWithOpts(opts UnsealOpts) ([]byte, error)
  • func (c *Client) WaitForDevice(timeout time.Duration) bool
• type HashAlgorithm
  • func ParsePCRBank(bank string) HashAlgorithm
• type LockoutStatus
• type UnsealOpts

Constants

const (
	AlgSHA1   = tpm2.TPMAlgSHA1
	AlgSHA256 = tpm2.TPMAlgSHA256
	AlgSHA384 = tpm2.TPMAlgSHA384
	AlgSHA512 = tpm2.TPMAlgSHA512
)

Algorithm constants for PCR banks.

const DefaultDevice = "/dev/tpmrm0"

DefaultDevice is the default TPM device path.

const DefaultPCRLockNV = 0x01c20000

DefaultPCRLockNV is the default NV index for systemd-pcrlock.

const FallbackDevice = "/dev/tpm0"

FallbackDevice is used if the resource manager is unavailable.

Variables

var ErrPCRMismatch = errors.New("PCR policy mismatch")

ErrPCRMismatch indicates PCR policy verification failed.

var ErrTPMLockout = errors.New("TPM is in dictionary attack lockout")

ErrTPMLockout indicates the TPM is in DA lockout mode.

var ErrTPMUnavailable = errors.New("TPM device not available")

ErrTPMUnavailable indicates the TPM device is not available.

var ErrWrongPIN = errors.New("incorrect PIN")

ErrWrongPIN indicates incorrect PIN/password.

Functions

func DeriveAuthValue

func DeriveAuthValue(pin string, salt []byte) []byte

DeriveAuthValue derives the TPM auth value from a PIN using PBKDF2-HMAC-SHA256. This matches systemd's tpm2_util_pbkdf2_hmac_sha256 function. The salt is provided in the token JSON as "tpm2-salt".

func HashPIN

func HashPIN(pin string) []byte

HashPIN hashes a PIN using SHA-256 for TPM2 auth value (legacy). Use DeriveAuthValue when salt is available.

func ParseBlob

func ParseBlob(blob []byte) (private, public []byte, err error)

ParseBlob parses a systemd-tpm2 blob into private and public components. The blob format is: <2-byte private size><private data><2-byte public size><public data>

Types

type Client

type Client struct {
	// contains filtered or unexported fields
}

Client provides TPM 2.0 operations.

func New

func New() *Client

New creates a new TPM client.

func NewWithDevice

func NewWithDevice(device string) *Client

NewWithDevice creates a new TPM client with a specific device path.

func (*Client) FindPCRLockNVIndex

func (c *Client) FindPCRLockNVIndex() (uint32, error)

FindPCRLockNVIndex finds the PCRLock NV index by searching for NV indexes that have a PolicyAuthorizeNV policy set up. Returns the NV index if found, 0 if not found.

func (*Client) GetLockoutStatus

func (c *Client) GetLockoutStatus() (*LockoutStatus, error)

GetLockoutStatus reads the TPM lockout status.

func (*Client) ListNVIndexes

func (c *Client) ListNVIndexes() (map[uint32][]byte, error)

ListNVIndexes lists all defined NV indexes in the TPM. Returns a map of NV index to NV public area bytes.

func (*Client) NVReadPublic

func (c *Client) NVReadPublic(index uint32) ([]byte, error)

NVReadPublic reads the public area of an NV index.

func (*Client) ReadAllPCRValues

func (c *Client) ReadAllPCRValues(bank HashAlgorithm) (map[uint][]byte, error)

ReadAllPCRValues reads all PCR values for a specific bank.

func (*Client) ReadPCRValues

func (c *Client) ReadPCRValues(bank HashAlgorithm, pcrs []uint) (map[uint][]byte, error)

ReadPCRValues reads the current PCR values from the TPM. Returns a map of PCR number to PCR value (digest).

func (*Client) ReadPCRs

func (c *Client) ReadPCRs(bank HashAlgorithm, pcrs []int) (map[int][]byte, error)

ReadPCRs reads the specified PCRs from the TPM. Returns a map of PCR index to raw value.

func (*Client) Unseal

func (c *Client) Unseal(public, private []byte, pcrs []int, bank HashAlgorithm, policyHash, authValue []byte, primaryAlg string) ([]byte, error)

Unseal unseals data using the TPM with PCR policy. Deprecated: Use UnsealWithOpts instead.

func (*Client) UnsealWithOpts

func (c *Client) UnsealWithOpts(opts UnsealOpts) ([]byte, error)

UnsealWithOpts unseals data using the TPM with the given options. This is the main entry point for unsealing systemd-tpm2 tokens.

func (*Client) WaitForDevice

func (c *Client) WaitForDevice(timeout time.Duration) bool

WaitForDevice waits for the TPM device to become available. Returns true if the device is ready, false if timeout.

type HashAlgorithm

type HashAlgorithm = tpm2.TPMAlgID

HashAlgorithm is the TPM hash algorithm type.

func ParsePCRBank

func ParsePCRBank(bank string) HashAlgorithm

ParsePCRBank converts a bank name string to TPM algorithm.

type LockoutStatus

type LockoutStatus struct {
	InLockout       bool
	LockoutCounter  uint64
	MaxAuthFail     uint64
	LockoutRecovery uint64 // seconds to wait for recovery
}

LockoutStatus contains TPM dictionary attack lockout information.

type UnsealOpts

type UnsealOpts struct {
	Public               []byte        // TPM public blob
	Private              []byte        // TPM private blob
	PCRs                 []int         // PCR indices (empty for pcrlock)
	Bank                 HashAlgorithm // PCR hash algorithm
	PolicyHash           []byte        // Expected policy hash
	AuthValue            []byte        // PIN/password (raw)
	Salt                 []byte        // Salt for PBKDF2 (systemd uses this)
	PrimaryAlg           string        // "ecc" or "rsa"
	UsePCRLock           bool          // True for pcrlock-based tokens
	PCRLockNV            uint32        // NV index for pcrlock (0 = default 0x01c20000)
	SRKHandle            uint32        // Persistent SRK handle (0 = create transient)
	SkipPolicyHashVerify bool          // Skip policy hash verification (for PIN-only tokens)
}

UnsealOpts contains options for unsealing a TPM-protected secret.