README
¶
tpmlib
A Go library for interfacing with Trusted Platform Module (TPM) devices. This library enables applications to:
- Connect to a local TPM device
- Generate and use TPM-backed keys for cryptographic operations
- Perform signing operations using ECDSA
- Execute ECDH key exchanges
- Access TPM's hardware random number generator
- Generate attestation data
- Create BottleFmt-compatible ID cards and keychains
Installation
go get github.com/KarpelesLab/tpmlib
Usage Examples
Basic Signing Operation
import (
"crypto"
"crypto/rand"
"github.com/BottleFmt/gobottle"
"github.com/KarpelesLab/tpmlib"
)
func signSomething(v []byte) ([]byte, error) {
k, err := tpmlib.GetKey()
if err != nil {
return nil, err
}
return k.Sign(rand.Reader, gobottle.Hash(v, crypto.SHA256), crypto.SHA256)
}
ECDH Key Exchange
import (
"crypto/ecdh"
"github.com/KarpelesLab/tpmlib"
)
func performECDH(remotePubKey *ecdh.PublicKey) ([]byte, error) {
k, err := tpmlib.GetKey()
if err != nil {
return nil, err
}
// Get shared secret
return k.ECDH(remotePubKey)
}
Hardware Random Number Generation
import "github.com/KarpelesLab/tpmlib"
func getRandomBytes(size int) ([]byte, error) {
k, err := tpmlib.GetKey()
if err != nil {
return nil, err
}
// Use TPM as a source of randomness
data := make([]byte, size)
_, err = k.Read(data)
if err != nil {
return nil, err
}
return data, nil
}
Working with ID Cards
import "github.com/KarpelesLab/tpmlib"
func getIDCard() (*gobottle.IDCard, error) {
k, err := tpmlib.GetKey()
if err != nil {
return nil, err
}
// Generate an unsigned ID card
return k.IDCard()
}
Platform Support
- Linux: Uses
/dev/tpmrm0then falls back to/dev/tpm0 - Windows: Connects to the TPM using platform-specific mechanisms
Features
- Thread-safe TPM access with proper locking
- Singleton TPM connection to avoid resource conflicts
- Support for NIST P-256 elliptic curve cryptography
- Compatible with the BottleFmt ecosystem
- Self-test functionality to verify TPM operations
Development
# Build the library
go build -v
# Run tests
go test -v
# Run a specific test
go test -v -run TestName
License
See the LICENSE file for details.
Documentation
¶
Overview ¶
Package tpmlib provides TPM device connectivity and operations.
Package tpmlib provides an interface to Trusted Platform Module (TPM) devices.
It enables applications to utilize TPM-backed keys for cryptographic operations including signing (ECDSA), key exchange (ECDH), hardware random number generation, and attestation. The library is designed to work with TPM 2.0 devices and supports Linux and Windows platforms.
This package manages a singleton connection to the TPM device and provides thread-safe access through proper locking mechanisms. It automatically generates and caches keys for signing and encryption operations.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func OpenTPM ¶
func OpenTPM() (io.ReadWriteCloser, error)
OpenTPM connects to the local TPM device.
This function provides access to the TPM device using platform-specific mechanisms. On Linux, it attempts to connect to /dev/tpmrm0 first, then falls back to /dev/tpm0. On Windows, it uses platform-specific mechanisms to access the TPM.
OpenTPM implements a singleton pattern - multiple calls will always return the same connection object. This prevents resource conflicts when accessing the TPM. The function is thread-safe through the use of a mutex lock.
It returns an io.ReadWriteCloser interface for communicating with the TPM device. If connection to the TPM fails, an error is returned.
Types ¶
type Intf ¶
type Intf interface {
// Implements crypto.Signer for signing operations using TPM-protected keys
crypto.Signer
// ECDH performs a key exchange operation with the provided remote public key.
// It returns the shared secret or an error if ECDH operations are not available.
ECDH(remote *ecdh.PublicKey) ([]byte, error)
// ECDHPublic returns the local public key for ECDH operations.
// Returns an error if ECDH operations are not available.
ECDHPublic() (*ecdh.PublicKey, error)
// Keychain returns a gobottle.Keychain containing all available TPM keys.
// This includes both signing and encryption keys if available.
Keychain() *gobottle.Keychain
// IDCard returns a non-signed gobottle.IDCard with all TPM keys included.
// The ID card can be used with the BottleFmt ecosystem for secure operations.
IDCard() (*gobottle.IDCard, error)
// Read implements io.Reader to access the TPM's True Random Number Generator.
// It reads random bytes directly from the TPM hardware.
Read(b []byte) (int, error)
}
Intf is the generic interface for TPM operations. It extends the crypto.Signer interface with additional TPM-specific functionality for key exchange, random number generation, and identity management.
func GetKey ¶
GetKey returns an object that corresponds to the local machine's TPM.
This function connects to the TPM device, creates or retrieves cached keys for signing and ECDH operations. Multiple calls to GetKey will return the same object as the TPM connection is managed as a singleton. This function is thread-safe.
It returns an Intf interface that provides access to all TPM functionality. If the connection to the TPM fails or key creation fails, an error is returned.
Source Files