tpmprovider.go

/*
 * Copyright (C) 2020 Intel Corporation
 * SPDX-License-Identifier: BSD-3-Clause
 */
package tpmprovider

// #include "tpm.h"
import "C"

type CertifiedKey struct {
	Version        int
	Usage          int
	PublicKey      []byte
	PrivateKey     []byte
	KeySignature   []byte
	KeyAttestation []byte
	KeyName        []byte
}

// provides go visibility to values defined in tpm.h (shared with c code)
const (
	None = C.TPM_VERSION_UNKNOWN
	V12  = C.TPM_VERSION_10
	V20  = C.TPM_VERSION_20

	NV_IDX_RSA_ENDORSEMENT_CERTIFICATE = C.NV_IDX_RSA_ENDORSEMENT_CERTIFICATE
	NV_IDX_ECC_ENDORSEMENT_CERTIFICATE = C.NV_IDX_ECC_ENDORSEMENT_CERTIFICATE
	NV_IDX_X509_P384_EK_CERTCHAIN      = C.NV_IDX_X509_P384_EK_CERTCHAIN
	NV_IDX_ASSET_TAG                   = C.NV_IDX_ASSET_TAG
	TPM_HANDLE_AIK                     = C.TPM_HANDLE_AIK
	TPM_HANDLE_EK                      = C.TPM_HANDLE_EK
	TPM_HANDLE_PRIMARY                 = C.TPM_HANDLE_PRIMARY
	TPM2_RH_OWNER                      = 0x40000001

	Binding = C.TPM_CERTIFIED_KEY_USAGE_BINDING
	Signing = C.TPM_CERTIFIED_KEY_USAGE_SIGNING

	TCTI_DEVICE = C.TCTI_DEVICE
	TCTI_MSSIM  = C.TCTI_MSSIM
	TCTI_TBS    = C.TCTI_TBS

	TPM_PROVIDER_ERROR_NO_EK_CERT     = C.TPM_PROVIDER_ERROR_NO_EK_CERT
	TPM_PROVIDER_EK_PUBLIC_MISMATCH   = C.TPM_PROVIDER_EK_PUBLIC_MISMATCH
	TPM_PROVIDER_INVALID_PCRSELECTION = C.TPM_PROVIDER_INVALID_PCRSELECTION
	TPM_PROVIDER_INVALID_PCRCOUNT     = C.TPM_PROVIDER_INVALID_PCRCOUNT

	// used to indicate that a TPM secret password is passed in hex
	// format:  ex. 'hex:decafbad'.
	HEX_PREFIX = "hex:"
)

type TpmProvider interface {

	//
	// Releases the resources associated with the TpmProvider.
	//
	Close()

	//
	// Reports the version of the TPM (assumes TPM 2.0).
	//
	Version() C.TPM_VERSION

	//
	// Provided a 40 character hex string, takes ownership of the TPM.
	//
	TakeOwnership(ownerSecretKey string) error

	//
	// Determines if the valid, 40 character hex string currently owns
	// the TPM.
	//
	IsOwnedWithAuth(ownerSecretKey string) (bool, error)

	//
	// Used by the go-trust-agent allocate an EK in the TPM.
	//
	CreateEk(ownerSecretKey string, handle uint32) error

	//
	// Used by the go-trust-agent allocate an AIK in the TPM.
	//
	CreateAik(ownerSecretKey string) error

	//
	// Used by the go-trust-agent to facilitate handshakes with HVS
	//
	GetAikBytes() ([]byte, error)

	//
	// Used by the go-trust-agent to facilitate handshakes with HVS
	//
	GetAikName() ([]byte, error)

	//
	// ActivateCredential uses the TPM to decrypt 'secretBytes'.
	//
	// Used by the go-trust-agent to decrypt HVS data.
	//
	ActivateCredential(ownerSecretKey string, credentialBytes []byte, secretBytes []byte) ([]byte, error)

	//
	// Used by the go-trust-agent to collect a tpm quote.
	//
	GetTpmQuote(nonce []byte, pcrBanks []string, pcrs []int) ([]byte, error)

	//
	// Checks to see if data has been written to nvram at 'nvIndex'
	//
	NvIndexExists(nvIndex uint32) (bool, error)

	//
	// Allocate nvram of size 'indexSize' at 'nvIndex'.  Creates the index using the
	// TPM2_RH_OWNER handle.
	//
	NvDefine(ownerSecretKey string, indexSecretKey string, nvIndex uint32, nvSize uint16) error

	//
	// Deletes data at nvram index 'nvIndex'
	//
	NvRelease(ownerSecretKey string, nvIndex uint32) error

	//
	// Reads data at nvram index 'nvIndex', using password 'indexSecretKey' to access
	// the nv index (ex. the owner-secret for EK certificate or tag-secret for
	// asset tag nvram).
	//
	NvRead(indexSecretKey string, authHandle uint32, nvIndex uint32) ([]byte, error)

	//
	// Writes data to nvram index 'nvIndex', using password 'indexSecretKey' to access
	// the nv index.
	//
	NvWrite(indexSecretKey string, authHandle uint32, nvIndex uint32, data []byte) error

	//
	// Used to allocate a primary key in the TPM hiearchy that can be used by WLA to
	// create signing/binding keys.
	//
	CreatePrimaryHandle(ownerSecretKey string, handle uint32) error

	//
	// Provided valid signing/aik secret keys for the TPM, creates a CertifiedKey
	// that can be used for signing.
	//
	CreateSigningKey(signingSecretKey string) (*CertifiedKey, error)

	//
	// Provided valid binding/aik secret keys for the TPM, creates a CertifiedKey
	// that can be used for binding.
	//
	CreateBindingKey(bindingSecretKey string) (*CertifiedKey, error)

	//
	// Used by WLA to decrypt data in 'encryptedData' (using the CertifiedKey generated
	// by 'CreateBindingKey').
	//
	Unbind(certifiedKey *CertifiedKey, bindingSecretKey string, encryptedData []byte) ([]byte, error)

	//
	// Used by WLA to sign attestation reports (using the CertifiedKey generated by
	// 'CreateSigningKey').  Hash must be 32bytes long (sha256).
	//
	Sign(certifiedKey *CertifiedKey, signingSecretKey string, hash []byte) ([]byte, error)

	//
	// Checks if a primary key in the TPM exists at 'handle'.
	//
	PublicKeyExists(handle uint32) (bool, error)

	//
	// Provided a valid EK 'handle', returns the public key's modulus.
	//
	ReadPublic(handle uint32) ([]byte, error)

	//
	// Compares the public key for the item at 'handle' against the public key of
	// the EK Certificate at 'nvIndex' (returns false if they don't match or error).
	//
	IsValidEk(ownerSecretKey string, handle uint32, nvIndex uint32) (bool, error)

	// IsPcrBankActive is used to determine if a PCR bank for the specified hash algo is enabled in the TPM
	IsPcrBankActive(pcrBank string) (bool, error)
}