tpm

package
v0.49.0 Latest Latest
Warning

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

 Go to latest Published: Jul 9, 2024 License: Apache-2.0 Imports: 35 Imported by: 1

Documentation

Index

Constants

This section is empty.

Variables

View Source 
var ErrExists = errors.New("already exists")

ErrExists is returned when a Key or AK already exists

View Source 
var ErrNotFound = errors.New("not found")

ErrNotFound is returned when a Key or AK cannot be found

Functions

func CreateTSS2Signer added in v0.37.0 

func CreateTSS2Signer(ctx context.Context, t *TPM, key *tss2.TPMKey) (csigner crypto.Signer, err error)

CreateTSS2Signer returns a crypto.Signer using the given TPM and tss2.TPMKey.

func NewContext 

func NewContext(ctx context.Context, t *TPM) context.Context

NewContext adds TPM `t` to the context.

Types

type AK 

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

AK models a TPM 2.0 Attestation Key. An AK can be used to attest the creation of a Key. Attestation Keys are restricted, meaning that they can only sign data generated by the TPM.

func (*AK) ActivateCredential 

func (ak *AK) ActivateCredential(ctx context.Context, in EncryptedCredential) (secret []byte, err error)

ActivateCredential decrypts the secret using the key to prove that the AK was generated on the same TPM as the EK. This operation is synonymous with TPM2_ActivateCredential.

func (*AK) AttestationParameters 

func (ak *AK) AttestationParameters(ctx context.Context) (params attest.AttestationParameters, err error)

AttestationParameters returns information about the AK, typically used to generate a credential activation challenge.

func (*AK) Blobs 

func (ak *AK) Blobs(ctx context.Context) (blobs *Blobs, err error)

Blobs returns a container for the private and public AK blobs. The resulting blobs are compatible with tpm2-tools, so can be used like this (after having been written to ak.priv and ak.pub): 

tpm2_load -C 0x81000001 -u ak.pub -r ak.priv -c ak.ctx

func (*AK) Certificate 

func (ak *AK) Certificate() *x509.Certificate

Certificate returns the AK certificate, if set. Will return nil in case no AK certificate is available.

func (*AK) CertificateChain 

func (ak *AK) CertificateChain() []*x509.Certificate

CertificateChain returns the AK certificate chain. It can return an empty chain if the AK public key has not been certified yet.

func (*AK) CreatedAt 

func (ak *AK) CreatedAt() time.Time

CreatedAt returns the creation time of the AK.

func (*AK) Data 

func (ak *AK) Data() []byte

Data returns the AK data blob. The data blob contains all information required for the AK to be loaded into the TPM that created it again, so that it can be used for attesting new keys.

func (*AK) HasValidPermanentIdentifier 

func (ak *AK) HasValidPermanentIdentifier(permanentIdentifier string) bool

HasValidPermanentIdentifier indicates if the AK has a certificate with the `permanentIdentifier` as one of its Subject Alternative Names.

func (*AK) MarshalJSON 

func (ak *AK) MarshalJSON() ([]byte, error)

MarshalJSON marshals the AK to JSON.

func (*AK) Name 

func (ak *AK) Name() string

Name returns the AK name. The name uniquely identifies an AK if a TPM with persistent storage is used.

func (*AK) Public added in v0.32.0 

func (ak *AK) Public() crypto.PublicKey

Public returns the AK public key. This is backed by a call to the TPM, so it can fail. If it fails, nil is returned.

TODO: see improvement described in the private method to always return a non-nil crypto.PublicKey.

func (*AK) SetCertificateChain 

func (ak *AK) SetCertificateChain(ctx context.Context, chain []*x509.Certificate) (err error)

SetCertificateChain associates an X.509 certificate chain with the AK. If the AK public key doesn't match the public key in the first certificate in the chain (the leaf), an error is returned.

func (*AK) ToTSS2 added in v0.37.0 

func (ak *AK) ToTSS2(ctx context.Context) (*tss2.TPMKey, error)

ToTSS2 gets the public and private blobs and returns a *tss2.TPMKey.

type AttestKeyConfig 

type AttestKeyConfig struct {
	// Algorithm to be used, either RSA or ECDSA.
	Algorithm string
	// Size is used to specify the bit size of the key or elliptic curve. For
	// example, '256' is used to specify curve P-256.
	Size int
	// QualifyingData is additional data that is passed to the TPM.
	// It can be used as a nonce to ensure freshness of an attestation.
	// When used with ACME `device-attest-01`, this contains a hash of
	// the key authorization.
	QualifyingData []byte
}

AttestKeyConfig is used to pass configuration when creating Keys that are to be attested by an AK.

type Blobs 

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

Blobs is a container for the private and public blobs of data that represent a TPM2 object.

func (*Blobs) Private 

func (b *Blobs) Private() (blob []byte, err error)

Private returns the private data blob of a TPM2 object including a 16-bit header. The blob can be used with tpm2-tools.

func (*Blobs) Public 

func (b *Blobs) Public() (blob []byte, err error)

Public returns the public data blob of a TPM2 object including a 16-bit header. The blob can be used with tpm2-tools.

type CommandChannel added in v0.32.2 

type CommandChannel attest.CommandChannelTPM20

type CreateKeyConfig 

type CreateKeyConfig struct {
	// Algorithm to be used, either RSA or ECDSA.
	Algorithm string
	// Size is used to specify the bit size of the key or elliptic curve. For
	// example, '256' is used to specify curve P-256.
	Size int
}

CreateKeyConfig is used to pass configuration when creating Keys.

type EK 

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

EK models a TPM Endorsement Key. The EK can be used to identify a specific TPM. The EK is certified by a TPM manufacturer.

func (*EK) Certificate 

func (ek *EK) Certificate() *x509.Certificate

Certificate returns the EK certificate. This can return nil.

func (*EK) CertificateURL 

func (ek *EK) CertificateURL() string

CertificateURL returns the URL from which the EK certificate can be retrieved. Not all EKs have a certificate URL.

func (*EK) Fingerprint 

func (ek *EK) Fingerprint() (string, error)

Fingerprint returns the EK public key fingerprint. The fingerprint is the base64 encoded SHA256 of the EK public key, encoded to PKIX, ASN.1 DER format.

func (*EK) FingerprintURI 

func (ek *EK) FingerprintURI() (*url.URL, error)

func (*EK) MarshalJSON 

func (ek *EK) MarshalJSON() ([]byte, error)

MarshalJSON marshals the EK to JSON.

func (*EK) PEM 

func (ek *EK) PEM() (string, error)

PEM returns the EK certificate as a PEM formatted string. It returns an error if the EK doesn't have a certificate.

func (*EK) Public 

func (ek *EK) Public() crypto.PublicKey

Public returns the EK public key.

func (*EK) Type 

func (ek *EK) Type() string

Type returns the EK public key type description.

type EncryptedCredential 

type EncryptedCredential attest.EncryptedCredential

EncryptedCredential represents encrypted parameters which must be activated against a key.

type FirmwareVersion 

type FirmwareVersion struct {
	Major int
	Minor int
}

FirmwareVersion models the TPM firmware version.

func (FirmwareVersion) MarshalJSON 

func (fv FirmwareVersion) MarshalJSON() ([]byte, error)

MarshalJSON marshals the TPM firmware version to JSON.

func (FirmwareVersion) String 

func (fv FirmwareVersion) String() string

String returns a textual representation of the TPM firmware version.

type Info 

type Info struct {
	Version         Version         `json:"version"`
	Interface       Interface       `json:"interface"`
	Manufacturer    Manufacturer    `json:"manufacturer"`
	VendorInfo      string          `json:"vendorInfo,omitempty"`
	FirmwareVersion FirmwareVersion `json:"firmwareVersion,omitempty"`
}

Info models information about a TPM. It contains the TPM version, interface, manufacturer, vendor info and firmware version.

type Interface 

type Interface attest.TPMInterface

Interface models a TPM interface.

func (Interface) MarshalJSON 

func (i Interface) MarshalJSON() ([]byte, error)

MarshalJSON marshals the TPM interface into JSON.

func (Interface) String 

func (i Interface) String() string

String returns a textual representation of the TPM interface.

type Key 

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

Key models a TPM 2.0 Key. A Key can be used to sign data. When a Key is created, it can be attested by an AK, to be able to prove that it was created by a specific TPM.

func (*Key) AttestedBy 

func (k *Key) AttestedBy() string

AttestedBy returns the name of the AK the Key was attested (certified) by at creation time.

func (*Key) Blobs 

func (k *Key) Blobs(ctx context.Context) (blobs *Blobs, err error)

Blobs returns a container for the private and public key blobs. The resulting blobs are compatible with tpm2-tools, so can be used like this (after having been written to key.priv and key.pub): 

tpm2_load -C 0x81000001 -u key.pub -r key.priv -c key.ctx

func (*Key) Certificate 

func (k *Key) Certificate() *x509.Certificate

Certificate returns the certificate for the Key, if set. Will return nil in case no AK certificate is available.

func (*Key) CertificateChain 

func (k *Key) CertificateChain() []*x509.Certificate

CertificateChain returns the certificate chain for the Key. It can return an empty chain.

func (*Key) CertificationParameters 

func (k *Key) CertificationParameters(ctx context.Context) (params attest.CertificationParameters, err error)

CertificationParameters returns information about the key that can be used to verify key certification.

func (*Key) CreatedAt 

func (k *Key) CreatedAt() time.Time

CreatedAt returns the the creation time of the Key.

func (*Key) Data 

func (k *Key) Data() []byte

Data returns the Key data blob. The data blob contains all information required for the Key to be loaded into the TPM that created it again, so that it can be used for signing data.

func (*Key) MarshalJSON 

func (k *Key) MarshalJSON() ([]byte, error)

MarshalJSON marshals the Key to JSON.

func (*Key) Name 

func (k *Key) Name() string

Name returns the Key name. The name uniquely identifies the Key if a TPM with persistent storage is used.

func (*Key) SetCertificateChain 

func (k *Key) SetCertificateChain(ctx context.Context, chain []*x509.Certificate) (err error)

SetCertificateChain associates an X.509 certificate chain with the Key. If the public key doesn't match the public key in the first certificate in the chain (the leaf), an error is returned.

func (*Key) Signer 

func (k *Key) Signer(ctx context.Context) (crypto.Signer, error)

Signer returns a crypto.Signer backed by the Key.

func (*Key) ToTSS2 added in v0.37.0 

func (k *Key) ToTSS2(ctx context.Context) (*tss2.TPMKey, error)

ToTSS2 gets the public and private blobs and returns a *tss2.TPMKey.

func (*Key) WasAttested 

func (k *Key) WasAttested() bool

WasAttested returns whether or not the Key was attested (certified) by an AK at creation time.

func (*Key) WasAttestedBy 

func (k *Key) WasAttestedBy(ak *AK) bool

WasAttestedBy returns whether or not the Key was attested (certified) by the provided AK at creation time.

type Manufacturer 

type Manufacturer struct {
	ID    manufacturer.ID `json:"id"`
	Name  string          `json:"name"`
	ASCII string          `json:"ascii"`
	Hex   string          `json:"hex"`
}

Manufacturer models a TPM Manufacturer.

func GetManufacturerByID 

func GetManufacturerByID(id manufacturer.ID) (m Manufacturer)

GetManufacturerByID returns a Manufacturer based on its Manufacturer ID code.

func (Manufacturer) String 

func (m Manufacturer) String() string

String returns a textual representation of the TPM manufacturer. An example looks like this: 

ST Microelectronics (STM, 53544D20, 1398033696)

type NewTPMOption 

type NewTPMOption func(o *options) error

NewTPMOption is used to provide options when instantiating a new instance of TPM.

func WithCommandChannel added in v0.32.2 

func WithCommandChannel(commandChannel CommandChannel) NewTPMOption

func WithDeviceName 

func WithDeviceName(name string) NewTPMOption

WithDeviceName is used to provide the `name` or path to the TPM device.

func WithDisableDownload 

func WithDisableDownload() NewTPMOption

WithDisableDownload disables EK certificates from being downloaded from online hosts.

func WithSimulator 

func WithSimulator(sim simulator.Simulator) NewTPMOption

WithSimulator is used to configure a TPM simulator implementation that simulates TPM operations instead of interacting with an actual TPM.

func WithStore 

func WithStore(store storage.TPMStore) NewTPMOption

WithStore is used to set the TPMStore implementation to use for persisting TPM objects, including AKs and Keys.

type ShortRandomReadError added in v0.32.0 

type ShortRandomReadError struct {
	Requested int
	Generated int
}

func (ShortRandomReadError) Error added in v0.32.0 

func (s ShortRandomReadError) Error() string

type TPM 

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

TPM models a Trusted Platform Module. It provides an abstraction over the google/go-tpm and google/go-attestation packages, allowing functionalities of these packages to be performed in a uniform manner. Besides that, it provides a transparent method for persisting TPM objects, so that referencing and using these is simplified.

func FromContext 

func FromContext(ctx context.Context) *TPM

FromContext returns a TPM from the context.

It panics when there's no TPM in the context.

func New 

func New(opts ...NewTPMOption) (*TPM, error)

New creates a new TPM instance. It takes `opts` to configure the instance.

func (*TPM) AttestKey 

func (t *TPM) AttestKey(ctx context.Context, akName, name string, config AttestKeyConfig) (key *Key, err error)

AttestKey creates a new Key identified by `name` and attested by the AK identified by `akName`. If no name is provided, a random 10 character name is generated. If a Key with the same name exists, `ErrExists` is returned.

func (*TPM) Available added in v0.32.2 

func (t *TPM) Available() (err error)

func (*TPM) CreateAK 

func (t *TPM) CreateAK(ctx context.Context, name string) (ak *AK, err error)

CreateAK creates and stores a new AK identified by `name`. If no name is provided, a random 10 character name is generated. If an AK with the same name exists, `ErrExists` is returned.

func (*TPM) CreateKey 

func (t *TPM) CreateKey(ctx context.Context, name string, config CreateKeyConfig) (key *Key, err error)

CreateKey creates a new Key identified by `name`. If no name is provided, a random 10 character name is generated. If a Key with the same name exists, `ErrExists` is returned. The Key won't be attested by an AK.

func (*TPM) DeleteAK 

func (t *TPM) DeleteAK(ctx context.Context, name string) (err error)

DeleteAK removes the AK identified by `name`. It returns `ErrNotfound` if it doesn't exist. Keys that were attested by the AK have to be removed before removing the AK, otherwise an error will be returned.

func (*TPM) DeleteKey 

func (t *TPM) DeleteKey(ctx context.Context, name string) (err error)

DeleteKey removes the Key identified by `name`. It returns `ErrNotfound` if it doesn't exist.

func (*TPM) GenerateRandom 

func (t *TPM) GenerateRandom(ctx context.Context, size uint16) (random []byte, err error)

GenerateRandom returns `size` number of random bytes generated by the TPM.

func (*TPM) GetAK 

func (t *TPM) GetAK(ctx context.Context, name string) (ak *AK, err error)

GetAK returns the AK identified by `name`. It returns `ErrNotfound` if it doesn't exist.

func (*TPM) GetAKByPermanentIdentifier 

func (t *TPM) GetAKByPermanentIdentifier(ctx context.Context, permanentIdentifier string) (ak *AK, err error)

GetAKByPermanentIdentifier returns an AK for which a certificate exists with `permanentIdentifier` as one of the Subject Alternative Names. It returns `ErrNotFound` if it doesn't exist.

func (*TPM) GetEKs 

func (t *TPM) GetEKs(ctx context.Context) (eks []*EK, err error)

GetEKs returns a slice of TPM EKs. It will return an error when interaction with the TPM fails. It will loop through the TPM EKs and download the EK certificate if it's available online. The TPM EKs don't change after the first lookup, so the result is cached for future lookups.

func (*TPM) GetKey 

func (t *TPM) GetKey(ctx context.Context, name string) (key *Key, err error)

GetKey returns the Key identified by `name`. It returns `ErrNotfound` if it doesn't exist.

func (*TPM) GetKeysAttestedBy 

func (t *TPM) GetKeysAttestedBy(ctx context.Context, akName string) (keys []*Key, err error)

GetKeysAttestedBy returns a slice of Keys attested by the AK identified by `akName`. The result is (currently) not ordered.

func (*TPM) GetSigner 

func (t *TPM) GetSigner(ctx context.Context, name string) (csigner crypto.Signer, err error)

GetSigner returns a crypto.Signer for a TPM Key identified by `name`.

func (*TPM) Info 

func (t *TPM) Info(ctx context.Context) (info *Info, err error)

Info returns info about the TPM. The info doesn't change, so it's cached after the first lookup.

func (*TPM) ListAKs 

func (t *TPM) ListAKs(ctx context.Context) (aks []*AK, err error)

ListAKs returns a slice of AKs. The result is (currently) not ordered.

func (*TPM) ListKeys 

func (t *TPM) ListKeys(ctx context.Context) (keys []*Key, err error)

ListKeys returns a slice of Keys. The result is (currently) not ordered.

func (*TPM) RandomReader added in v0.32.0 

func (t *TPM) RandomReader() (io.Reader, error)

type Version 

type Version attest.TPMVersion

Version models the TPM specification version supported by the TPM.

func (Version) MarshalJSON 

func (v Version) MarshalJSON() ([]byte, error)

MarshalJSON marshals the version into JSON.

func (Version) String 

func (v Version) String() string

Source Files

View all Source files

Directories

Path Synopsis
internal
close
key
open
socket

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.