tpmkms

package
v0.56.0 Latest Latest
Warning

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

 Go to latest Published: Dec 19, 2024 License: Apache-2.0 Imports: 27 Imported by: 4

Documentation

Index

Constants

View Source 
const (
	// DefaultRSASize is the number of bits of a new RSA key if no size has been
	// specified. Whereas we're generally defaulting to 3072 bits for new RSA keys,
	// 2048 is used as the default for the TPMKMS, because we've observed the TPMs
	// we're testing with to be supporting this as the maximum RSA key size. We might
	// increase the default in the (near) future, but we want to be more confident
	// about the supported size for a specific TPM (model) in that case.
	DefaultRSASize = 2048
)
View Source 
const Scheme = string(apiv1.TPMKMS)

Scheme is the scheme used in TPM KMS URIs, the string "tpmkms".

Variables

View Source 
var (
	ErrIdentityCertificateUnavailable = errors.New("AK certificate not available")
	ErrIdentityCertificateNotYetValid = errors.New("AK certificate not yet valid")
	ErrIdentityCertificateExpired     = errors.New("AK certificate has expired")
	ErrIdentityCertificateIsExpiring  = errors.New("AK certificate will expire soon")
	ErrIdentityCertificateInvalid     = errors.New("AK certificate does not contain valid identity")
)

Functions

func PreferredSignatureAlgorithms added in v0.52.0 

func PreferredSignatureAlgorithms() []apiv1.SignatureAlgorithm

PreferredSignatureAlgorithms returns the preferred signature algorithms to select from when explicit values are omitted in CreateKeyRequest

Experimental

Notice: This method is EXPERIMENTAL and may be changed or removed in a later release.

func SetPreferredSignatureAlgorithms added in v0.52.0 

func SetPreferredSignatureAlgorithms(algs []apiv1.SignatureAlgorithm)

SetPreferredSignatureAlgorithms sets the preferred signature algorithms to select from when explicit values are omitted in CreateKeyRequest

Experimental

Notice: This method is EXPERIMENTAL and may be changed or removed in a later release.

Types

type TPMKMS 

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

TPMKMS is a KMS implementation backed by a TPM.

func New 

func New(ctx context.Context, opts apiv1.Options) (kms *TPMKMS, err error)

New initializes a new KMS backed by a TPM.

A new TPMKMS can be initialized with a configuration by providing a URI in the options: 

New(ctx, &apiv1.Options{
    URI: tpmkms:device=/dev/tpmrm0;storage-directory=/path/to/tpmstorage/directory
})

It's also possible to set the storage directory as follows: 

New(ctx, &apiv1.Options{
    URI: tpmkms:device=/dev/tpmrm0
	StorageDirectory: /path/to/tpmstorage/directory
})

The default storage location for serialized TPM objects when an instance of TPMKMS is created, is the relative path "tpm".

The system default TPM device will be used when not configured. A specific TPM device can be selected by setting the device: 

tpmkms:device=/dev/tpmrm0

By default newly created TPM objects won't be persisted, so can't be readily used. The location for storage can be set using storage-directory: 

tpmkms:storage-directory=/path/to/tpmstorage/directory

On Windows the TPMKMS implementation has an option to use the native certificate stores for certificate storage and retrieval instead of using the storage directory for those. TPM keys will still be persisted to the storage directory, because that's how the KMS keeps track of which keys it manages, but it'll use the Windows certificate stores for operations that involve certificates for TPM keys. Use the "enable-cng" option to enable this optional integration: 

tpmkms:enable-cng=true

If the CryptoAPI Next Generation (CNG) integration is enabled, the TPMKMS will use an instance of the CAPIKMS to manage certificates. It'll use the the "Personal" ("My") user certificate store by default. A different location and store to be used for all operations against the TPMKMS can be defined as follows: 

tpmkms:store-location=machine;store=CA

The location and store to use can be overridden for a specific operation against a TPMKMS instance, if required. It's not possible to change the crypto provider to user; that will always be the "Microsoft Platform Crypto Provider"

For operations that involve certificate chains, it's possible to set the intermediate CA store location and store name at initialization time. The same options can be used for a specific operation, if needed. By default the "CA" user certificate store is used.

tpmkms:intermediate-store-location=machine;intermediate-store=CustomCAStore

For attestation use cases that involve the Smallstep Attestation CA or a compatible one, several properties can be set. The following specify the Attestation CA base URL, the path to a bundle of root CAs to trust when setting up a TLS connection to the Attestation CA and disable TLS certificate validation, respectively. 

tpmkms:attestation-ca-url=https://my.attestation.ca
tpmkms:attestation-ca-root=/path/to/trusted/roots.pem
tpmkms:attestation-ca-insecure=true

The system may not always have a PermanentIdentifier assigned, so when initializing the TPMKMS, it's possible to set this value: 

tpmkms:permanent-identifier=<some-unique-identifier>

By default, an AK (identity) certificate will be renewed early if it's expiring soon. The default certificate lifetime is 60%, meaning that the renewal for the AK certificate will be kicked off when it's past 60% of its lifetime. It's possible to disable early renewal by setting disable-early-renewal to true: 

tpmkms:disable-early-renewal=true

The default lifetime percentage can be changed by setting renewal-percentage: 

tpmkms:renewal-percentage=70

Attestation support in the TPMKMS is considered EXPERIMENTAL. It is expected that there will be changes to the configuration that be provided and the attestation flow.

The TPMKMS implementation is backed by an instance of the TPM from the `tpm` package. If the TPMKMS operations aren't sufficient for your use case, use a tpm.TPM instance instead.

func (*TPMKMS) Close 

func (k *TPMKMS) Close() (err error)

Close releases the connection to the TPM.

func (*TPMKMS) CreateAttestation 

func (k *TPMKMS) CreateAttestation(req *apiv1.CreateAttestationRequest) (*apiv1.CreateAttestationResponse, error)

CreateAttestation implements the apiv1.Attester interface for the TPMKMS. It can be used to request the required information to verify that an application key was created in and by a specific TPM.

It is expected that an application key has been attested at creation time by an attestation key (AK) before calling this method. An error will be returned otherwise.

The response will include an attestation key (AK) certificate (chain) issued to the AK that was used to certify creation of the (application) key, as well as the key certification parameters at the time of key creation. Together these can be used by a relying party to attest that the key was created by a specific TPM.

If no valid AK certificate is available when calling CreateAttestation, an enrolment with an instance of the Smallstep Attestation CA is performed. This will use the TPM Endorsement Key and the AK as inputs. The Attestation CA will return an AK certificate chain on success.

When CreateAttestation is called for an AK, the AK certificate chain will be returned. Currently no AK creation parameters are returned.

func (*TPMKMS) CreateKey 

func (k *TPMKMS) CreateKey(req *apiv1.CreateKeyRequest) (*apiv1.CreateKeyResponse, error)

CreateKey generates a new key in the TPM KMS and returns the public key.

The `name` in the apiv1.CreateKeyRequest can be used to specify some key properties. These are as follows:

  • name=<name>: specify the name to identify the key with
  • ak=true: if set to true, an Attestation Key (AK) will be created instead of an application key
  • tss2=true: is set to true, the PrivateKey response will contain a tss2.TPMKey.
  • attest-by=<akName>: attest an application key at creation time with the AK identified by `akName`
  • qualifying-data=<random>: hexadecimal coded binary data that can be used to guarantee freshness when attesting creation of a key

Some examples usages:

Create an application key, without attesting it: 

tpmkms:name=my-key

Create an Attestation Key (AK): 

tpmkms:name=my-ak;ak=true

Create an application key, attested by `my-ak` with "1234" as the Qualifying Data: 

tpmkms:name=my-attested-key;attest-by=my-ak;qualifying-data=61626364

func (*TPMKMS) CreateSigner 

func (k *TPMKMS) CreateSigner(req *apiv1.CreateSignerRequest) (crypto.Signer, error)

CreateSigner creates a signer using a key present in the TPM KMS.

The `signingKey` in the apiv1.CreateSignerRequest can be used to specify some key properties. These are as follows:

  • name=<name>: specify the name to identify the key with
  • path=<file>: specify the TSS2 PEM file to use

func (*TPMKMS) DeleteCertificate added in v0.44.6 

func (k *TPMKMS) DeleteCertificate(req *apiv1.DeleteCertificateRequest) error

DeleteCertificate deletes a certificate for the key identified by name from the TPMKMS. If the instance is configured to use the Windows certificate store, it'll delete the certificate from the certificate store, backed by a CAPIKMS instance.

It's possible to delete a specific certificate for a key by specifying it's SHA1 or serial. This is only supported if the instance is configured to use the Windows certificate store.

Experimental

Notice: This method is EXPERIMENTAL and may be changed or removed in a later release.

func (*TPMKMS) DeleteKey added in v0.46.0 

func (k *TPMKMS) DeleteKey(req *apiv1.DeleteKeyRequest) error

DeleteKey deletes a key identified by name from the TPMKMS.

Experimental

Notice: This method is EXPERIMENTAL and may be changed or removed in a later release.

func (*TPMKMS) GetPublicKey 

func (k *TPMKMS) GetPublicKey(req *apiv1.GetPublicKeyRequest) (crypto.PublicKey, error)

GetPublicKey returns the public key present in the TPM KMS.

The `name` in the apiv1.GetPublicKeyRequest can be used to specify some key properties. These are as follows:

  • name=<name>: specify the name to identify the key with
  • ak=true: if set to true, an Attestation Key (AK) will be read instead of an application key
  • path=<file>: specify the TSS2 PEM file to read from

func (*TPMKMS) LoadCertificate 

func (k *TPMKMS) LoadCertificate(req *apiv1.LoadCertificateRequest) (cert *x509.Certificate, err error)

LoadCertificate loads the certificate for the key identified by name from the TPMKMS.

func (*TPMKMS) LoadCertificateChain 

func (k *TPMKMS) LoadCertificateChain(req *apiv1.LoadCertificateChainRequest) ([]*x509.Certificate, error)

LoadCertificateChain loads the certificate chain for the key identified by name from the TPMKMS.

func (*TPMKMS) StoreCertificate 

func (k *TPMKMS) StoreCertificate(req *apiv1.StoreCertificateRequest) error

StoreCertificate stores the certificate for the key identified by name to the TPMKMS.

func (*TPMKMS) StoreCertificateChain 

func (k *TPMKMS) StoreCertificateChain(req *apiv1.StoreCertificateChainRequest) error

StoreCertificateChain stores the certificate for the key identified by name to the TPMKMS.

Source Files

View all Source files

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.