README
¶
Service Keys (service_keys)
service_keys provides a hardware-bound identity and session management layer for service-to-service communication. By leveraging TPM 2.0 (Trusted Platform Module) and DBSC (Device Bound Session Credentials), this package ensures that machine-to-machine requests are cryptographically pinned to specific hardware, mitigating the risks of token theft and replay attacks.
Architecture
The service authentication flow follows a zero-trust model:
- Registration: Agents register their TPM-backed public key with the central authority.
- Attestation: The central server validates the TPM structure using
go-tpmprotocols. - Verification: Instead of static secrets, agents generate an ephemeral signature using their local TPM hardware.
- Binding: The server validates the hardware signature against the registered key, ensuring the session is strictly bound to the physical device.
Getting Started
Prerequisites
go-tpmfor TPM 2.0 communication.ultimate_dbfor secure persistence.webauthnextfor core identity structures.
Installation
go get github.com/gddisney/service_keys
Usage
1. Service Agent Registration
Register a machine identity by providing its TPM 2.0 public key structure (as a TPM2B_PUBLIC byte slice).
skm := &service_keys.ServiceKeyManager{DB: db}
err := skm.RegisterServiceIdentity("my-internal-agent", tpmPubBytes)
2. Protecting API Routes
Use the VerifyServiceSession middleware to protect internal API endpoints. Agents must provide a custom header X-DBSC-Hardware-Proof.
r.Mux.HandleFunc("POST /api/v1/internal/agent/task", skm.VerifyServiceSession(func(w http.ResponseWriter, r *http.Request) {
w.Write([]byte("Authorized"))
}))
3. Agent-Side Proof Generation
Agents construct a proof by signing a payload containing a timestamp (nonce) and the request path:
{service_name}:{nonce}:{signature_base64}
Security Guarantees
- Hardware Pinning: Identity is tied to the physical TPM, making keys non-exportable and resistant to extraction.
- Replay Protection: Every request requires a fresh, time-limited nonce signed by the TPM.
- Minimal Trust Surface: Removes the need to manage and rotate long-lived
client_secretstrings.
Testing
Run the comprehensive test suite to verify hardware identity decoding and signature verification logic:
go test -v ./...
License
This project is licensed under the MIT License.
Documentation
¶
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type ServiceKeyManager ¶
type ServiceKeyManager struct {
Provider *webauthnext.Provider
SdfEngine *secure_data_format.SecureDataEngine
Logger *logger.LogDispatcher
}
ServiceKeyManager handles TPM-backed machine identities and hardware attestations.
func LoadOrCreateManager ¶
func LoadOrCreateManager( sdf *secure_data_format.SecureDataEngine, sysLog *logger.LogDispatcher, ) (*ServiceKeyManager, error)
LoadOrCreateManager validates context properties and instantiates the manager cleanly.
func NewServiceKeyManager ¶
func NewServiceKeyManager( sdf *secure_data_format.SecureDataEngine, provider *webauthnext.Provider, sysLog *logger.LogDispatcher, ) *ServiceKeyManager
NewServiceKeyManager creates an active service identity coordinator instance.
func (*ServiceKeyManager) RegisterServiceIdentity ¶
func (s *ServiceKeyManager) RegisterServiceIdentity( name string, tpmPublicBytes []byte, ) error
RegisterServiceIdentity binds a machine asset configuration record to the local and distributed index tiers.
func (*ServiceKeyManager) VerifyServiceSession ¶
func (s *ServiceKeyManager) VerifyServiceSession( next http.HandlerFunc, ) http.HandlerFunc
VerifyServiceSession acts as a high-performance HTTP network guardian enforcing continuous DBSC cryptographic proofs.
func (*ServiceKeyManager) VerifySignature ¶
func (s *ServiceKeyManager) VerifySignature( serviceID string, payload []byte, signature []byte, ) bool
VerifySignature validates an inbound payload signature against the cryptographic key material stored inside the hardware layout.
Source Files