objectutil

package
v1.8.0 Latest Latest
Warning

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

 Go to latest Published: Dec 20, 2024 License: LGPL-3.0 Imports: 14 Imported by: 2

Documentation

Overview

Package objectutil contains utilities for creating and working with objects.

Index

Constants

View Source 
const (
	// UsageSign indicates that a key can be used for signing.
	UsageSign Usage = 1 << iota

	// UsageDecrypt indicates that a key can be used for decryption.
	UsageDecrypt

	// UsageEncrypt indicates that a key can be used for encryption.
	UsageEncrypt = UsageSign

	// UsageKeyAgreement indicates that a key can be used for key agreement.
	UsageKeyAgreement = UsageDecrypt
)

Variables

This section is empty.

Functions

func ComputeQualifiedName 

func ComputeQualifiedName(object Named, rootQn tpm2.Name, ancestors ...Named) (tpm2.Name, error)

ComputeQualifiedName computes the qualified name of an object from the specified qualified name of a root object and a list of ancestor objects. The ancestor objects are ordered starting with the immediate child of the object associated with the root qualified name.

func ComputeQualifiedNameInHierarchy 

func ComputeQualifiedNameInHierarchy(object Named, hierarchy tpm2.Handle, ancestors ...Named) (tpm2.Name, error)

ComputeQualifiedNameInHierarchy computes the qualified name of an object protected in the specified hierarchy from a list of ancestor objects. The ancestor objects are ordered starting from the primary object.

func CreateImportable 

func CreateImportable(rand io.Reader, sensitive *tpm2.Sensitive, public, parentPublic *tpm2.Public, innerSymmetricKey tpm2.Data, innerSymmetricAlg *tpm2.SymDefObject) (innerSymmetricKeyOut tpm2.Data, duplicate tpm2.Private, outerSecret tpm2.EncryptedSecret, err error)

CreateImportable creates a duplication object that can be imported in to a TPM with the tpm2.TPMContext.Import command from the supplied sensitive area.

If parentPublic is supplied, an outer duplication wrapper will be applied to the duplication object. The parentPublic argument should correspond to the public area of the storage key to which the duplication object will be imported. A secret structure will be returned as tpm2.EncryptedSecret which can be used by the private part of parentPublic in order to recover the seed used to generate the outer wrapper.

If innerSymmetricAlg is supplied and the Algorithm field is not tpm2.SymObjectAlgorithmNull, this function will apply an inner duplication wrapper to the duplication object. If innerSymmetricKey is supplied, it will be used as the symmetric key for the inner wrapper. It must have a size appropriate for the selected symmetric algorithm. If innerSymmetricKey is not supplied, a symmetric key will be created and returned as tpm2.Data.

func MakeCredential 

func MakeCredential(rand io.Reader, key *tpm2.Public, credential tpm2.Digest, objectName tpm2.Name) (credentialBlob tpm2.IDObject, secret tpm2.EncryptedSecret, err error)

MakeCredential performs the duties of a certificate authority in order to create an activation credential. It establishes a seed which is used to protect the activation credential (see section 24 - "Credential Protection" of Part 1 of the Trusted Platform Module Library specification).

The encrypted and integrity protected credential blob and a secret are returned, and these can be supplied to the TPM2_ActivateCredential command on the TPM on which both the private part of key and the object associated with objectName are loaded in order to recover the activation credential.

func NewDerivationParentTemplate 

func NewDerivationParentTemplate(options ...PublicTemplateOption) *tpm2.Public

NewDerivationParentTemplate returns a template for a derivation parent. The template can be customized by supplying additional options.

Without any options, the template will have the following properties:

func NewECCAttestationKeyTemplate 

func NewECCAttestationKeyTemplate(options ...PublicTemplateOption) *tpm2.Public

NewECCAttestationKeyTemplate returns a template for a ECC attestation key. The template can be customized by supplying additional options.

Without any options, the template will have the following properties:

func NewECCKeyTemplate 

func NewECCKeyTemplate(usage Usage, options ...PublicTemplateOption) *tpm2.Public

NewECCKeyTemplate returns a template for a ECC key with the specicied usage. The template can be customized by supplying additional options.

Without any options, the template will have the following properties:

func NewECCPublicKey 

func NewECCPublicKey(key *ecdsa.PublicKey, options ...PublicTemplateOption) (*tpm2.Public, error)

NewECCPublicKey returns a public area for the supplied elliptic key which can be used to verify signatures. The public area can be customized with additional options.

Without any options, the public area will have the following properties:

The returned public area can be loaded into a TPM with tpm2.TPMContext.LoadExternal.

func NewECCStorageKeyTemplate 

func NewECCStorageKeyTemplate(options ...PublicTemplateOption) *tpm2.Public

NewECCStorageKeyTemplate returns a template for a ECC storage key. The template can be customized by supplying additional options.

Without any options, the template will have the following properties:

func NewHMACKey 

func NewHMACKey(rand io.Reader, key []byte, authValue tpm2.Auth, options ...PublicTemplateOption) (*tpm2.Public, *tpm2.Sensitive, error)

NewHMACKey returns a public and sensitive area for the supplied HMAC key with the specified auth value. The supplied io.Reader is used to generate the seed parameter for the sensitive area. The public area can be customized with additional options.

Without any options, the public area will have the following properties:

The returned public and sensitive area can be loaded into a TPM with tpm2.TPMContext.LoadExternal or imported into a hierarchy by creating an importable object with CreateImportable.

func NewHMACKeyTemplate 

func NewHMACKeyTemplate(options ...PublicTemplateOption) *tpm2.Public

NewHMACKeyTemplate returns a template for a HMAC key. The template can be customized by supplying additional options.

Without any options, the template will have the following properties:

func NewRSAAttestationKeyTemplate 

func NewRSAAttestationKeyTemplate(options ...PublicTemplateOption) *tpm2.Public

NewRSAAttestationKeyTemplate returns a template for a RSA attestation key. The template can be customized by supplying additional options.

Without any options, the template will have the following properties:

func NewRSAKeyTemplate 

func NewRSAKeyTemplate(usage Usage, options ...PublicTemplateOption) *tpm2.Public

NewRSAKeyTemplate returns a template for a RSA key with the specicied usage. The template can be customized by supplying additional options.

Without any options, the template will have the following properties:

func NewRSAPublicKey 

func NewRSAPublicKey(key *rsa.PublicKey, options ...PublicTemplateOption) (*tpm2.Public, error)

NewRSAPublicKey returns a public area for the supplied RSA key which can be used to verify signatures. The public area can be customized with additional options.

Without any options, the public area will have the following properties:

The returned public area can be loaded into a TPM with tpm2.TPMContext.LoadExternal.

func NewRSAStorageKeyTemplate 

func NewRSAStorageKeyTemplate(options ...PublicTemplateOption) *tpm2.Public

NewRSAStorageKeyTemplate returns a template for a RSA storage key. The template can be customized by supplying additional options.

Without any options, the template will have the following properties:

func NewSealedObject 

func NewSealedObject(rand io.Reader, data []byte, authValue tpm2.Auth, options ...PublicTemplateOption) (*tpm2.Public, *tpm2.Sensitive, error)

NewSealedObject returns a public and sensitive area for a sealed data object containing the supplied data and with the specified auth value. The supplied io.Reader is used to generate the seed parameter for the sensitive area. The public area can be customized with additional options.

Without any options, the public area will have the following properties:

The returned public and sensitive area can be loaded into a TPM with tpm2.TPMContext.LoadExternal or imported into a hierarchy by creating an importable object with CreateImportable.

func NewSealedObjectTemplate 

func NewSealedObjectTemplate(options ...PublicTemplateOption) *tpm2.Public

NewSealedObjectTemplate returns a template for a sealed object. The template can be customized by supplying additional options.

Without any options, the template will have the following properties:

func NewSymmetricKey 

func NewSymmetricKey(rand io.Reader, usage Usage, key []byte, authValue tpm2.Auth, options ...PublicTemplateOption) (*tpm2.Public, *tpm2.Sensitive, error)

NewSymmetricKey returns a public and sensitive area for the supplied symmetric key with the specified usage and auth value. The supplied io.Reader is used to generate the seed parameter for the sensitive area. The public area can be customized with additional options.

Without any options, the public area will have the following properties:

The returned public and sensitive area can be loaded into a TPM with tpm2.TPMContext.LoadExternal or imported into a hierarchy by creating an importable object with CreateImportable.

func NewSymmetricKeyTemplate 

func NewSymmetricKeyTemplate(usage Usage, options ...PublicTemplateOption) *tpm2.Public

NewSymmetricKeyTemplate returns a template for a symmetric key with the specicied usage. The template can be customized by supplying additional options.

Without any options, the template will have the following properties:

func NewSymmetricStorageKeyTemplate 

func NewSymmetricStorageKeyTemplate(options ...PublicTemplateOption) *tpm2.Public

NewSymmetricStorageKeyTemplate returns a template for a symmetric storage key. The template can be customized by supplying additional options.

Without any options, the template will have the following properties:

func UnwrapDuplicated 

func UnwrapDuplicated(duplicate tpm2.Private, public *tpm2.Public, privKey crypto.PrivateKey, outerHashAlg tpm2.HashAlgorithmId, outerSymmetricAlg *tpm2.SymDefObject, outerSecret tpm2.EncryptedSecret, innerSymmetricKey tpm2.Data, innerSymmetricAlg *tpm2.SymDefObject) (*tpm2.Sensitive, error)

UnwrapDuplicated unwraps the supplied duplication object and returns the corresponding sensitive area. The duplication object will normally be created by executing the tpm2.TPMContext.Duplicate command.

If outerSecret is supplied then it is assumed that the object has an outer duplication wrapper. For an object duplicated with tpm2.TPMContext.Duplicate, outerSecret is the secret structure returned by this command. In this case, privKey, outerHashAlg and outerSymmetricAlg must be supplied - privKey is the key that recovers the seed used to generate the outer wrapper (the new parent when using tpm2.TPMContext.Duplicate), outerHashAlg is the algorithm used for integrity checking and key derivation (the new parent's name algorithm when using tpm2.TPMContext.Duplicate) and must not be tpm2.HashAlgorithmNull, and outerSymmetricAlg defines the symmetric algorithm for the outer wrapper (the new parent's symmetric algorithm when using tpm2.TPMContext.Duplicate) and must not be tpm2.SymObjectAlgorithmNull).

If innerSymmetricAlg is supplied and the Algorithm field is not tpm2.SymObjectAlgorithmNull, then it is assumed that the object has an inner duplication wrapper. In this case, the symmetric key for the inner wrapper must be supplied using the innerSymmetricKey argument.

Types

type AuthMode 

type AuthMode int

AuthMode represents an authorization mode for an object. 

const (
	// AllowAuthValue indicates that an object's auth value can be used for authorization with a
	// passphrase or HMAC session, in addition to a policy session.
	AllowAuthValue AuthMode = iota + 1

	// RequirePolicy indicates that only a policy session can be used for authorization.
	RequirePolicy
)

type DuplicationMode 

type DuplicationMode int

DuplicationMode describes whether an object can be duplicated directly. 

const (
	// FixedParent indicates that the object cannot be duplicated directory. This implies that
	// tpm2.AttrFixedParent is set.
	FixedParent DuplicationMode = iota + 1

	// DuplicationRoot indicates that the object is a duplication root. This implies that
	// tpm2.AttrFixedParent is not set.
	DuplicationRoot

	// DuplicationRootEncrypted indicates that the object is a duplication root and duplication
	// requires encryption. This implies that tpm2.AttrFixedParent is not set and
	// tpm2.AttrEncryptedDuplication is set.
	DuplicationRootEncrypted
)

type Named 

type Named interface {
	Name() tpm2.Name
}

Named is some type that represents an object.

type ProtectionGroupMode 

type ProtectionGroupMode int

ProtectionGroupMode describes the protection group that an object is created within. 

const (
	// NonDuplicable indicates that the protection group is not duplicable. This implies
	// tpm2.AttrFixedTPM and tpm2.AttrFixedParent are both set.
	NonDuplicable ProtectionGroupMode = iota + 1

	// Duplicable indicates that the protection group is duplicable. This implies that
	// tpm2.AttrFixedTPM is not set.
	Duplicable

	// DuplicableEncrypted indicates that the protection group is duplicable with encryption.
	// This implies that tpm2.AttrFixedTPM is not set and tpm2.AttrEncryptedDuplication is set.
	DuplicableEncrypted
)

type PublicTemplateOption 

type PublicTemplateOption func(*tpm2.Public)

PublicTemplateOption provides a way to customize the parameters of a public area or public template.

func WithAdminAuthMode 

func WithAdminAuthMode(mode AuthMode) PublicTemplateOption

WithAdminAuthMode returns an option that specifies the supplied mode should be used for authorization with the admin role.

func WithAuthPolicy added in v1.2.0 

func WithAuthPolicy(policy tpm2.Digest) PublicTemplateOption

WithAuthPolicy returns an option that sets the specified authorization policy digest.

func WithDerivationScheme 

func WithDerivationScheme(hashAlg tpm2.HashAlgorithmId, kdf tpm2.KDFAlgorithmId) PublicTemplateOption

WithDerivationScheme returns an option for the specified derivation scheme. This will panic for objects with a type other than tpm2.ObjectTypeKeyedHash, a scheme other than tpm2.KeyedHashSchemeXOR and objects that aren't parents. This option is intended for derivation parents.

func WithDictionaryAttackProtection 

func WithDictionaryAttackProtection() PublicTemplateOption

WithDictionaryAttackProtection returns an option that enables DA protection for an object.

func WithDuplicationMode 

func WithDuplicationMode(mode DuplicationMode) PublicTemplateOption

WithDuplicationMode returns an option for the specified duplication mode, which describes whether an object can be duplicated.

If mode is FixedParent then the tpm2.AttrFixedParent attribute is set.

If mode is DuplicationRoot, this unsets both tpm2.AttrFixedTPM and tpm2.AttrFixedParent, and doesn't change tpm2.AttrEncryptedDuplication. In this case, whether encrypted duplication is required will be determined by the protection group, which is inherited from the result of WithProtectionGroupMode.

If mode is DuplicationRootEncrypted, this behaves like DuplicationRoot but also sets tpm2.AttrEncryptedDuplication so that duplication requires encryption. Note that this is only valid if the protection group the object is created within is not duplicable (the parent object has the tpm2.AttrFixedTPM attribute set) or the protection group is already duplicable with encryption (the parent object has the tpm2.AttrFixedTPM attribute unset and the tpm2.AttrEncryptedDuplication attribute set).

func WithECCCurve 

func WithECCCurve(curve tpm2.ECCCurve) PublicTemplateOption

WithECCCurve returns an option for the specified elliptic curve. This will panic for objects with a type other than tpm2.ObjectTypeECC.

func WithECCScheme 

func WithECCScheme(scheme tpm2.ECCSchemeId, hashAlg tpm2.HashAlgorithmId) PublicTemplateOption

WithECCScheme returns an option for the specified ECC scheme. This will panic for objects with a type other than tpm2.ObjectTypeECC.

Attestation keys always have a signing scheme. Storage keys never have a scheme set. Key exchange or signing keys may have an appropriate scheme set.

func WithECCUnique 

func WithECCUnique(unique *tpm2.ECCPoint) PublicTemplateOption

WithECCUnique returns an option for the specified public identity. This will panic for objects with a type other than tpm2.ObjectTypeECC.

This is useful when creating templates for primary keys.

func WithExternalSensitiveData 

func WithExternalSensitiveData() PublicTemplateOption

WithExternalSensitiveData returns an option that indicates the sensitive data for an object was or is to be generated outside of the TPM.

func WithHMACDigest 

func WithHMACDigest(alg tpm2.HashAlgorithmId) PublicTemplateOption

WithHMACDigest returns an option for the specified HMAC digest algorithm. This will panic for objects with a type other than tpm2.ObjectTypeKeyedHash and a scheme other than tpm2.KeyedHashSchemeHMAC.

func WithInternalSensitiveData 

func WithInternalSensitiveData() PublicTemplateOption

WithInternalSensitiveData returns an option that indicates the sensitive data for an object was or is to be generated by the TPM.

func WithKeyedHashUnique 

func WithKeyedHashUnique(unique tpm2.Digest) PublicTemplateOption

WithKeyedHashUnique returns an option for the specified public identity. This will panic for objects with a type other than tpm2.ObjectTypeKeyedHash.

This is useful when creating templates for primary keys.

func WithNameAlg 

func WithNameAlg(alg tpm2.HashAlgorithmId) PublicTemplateOption

WithNameAlg returns an option for the specified name algorithm.

func WithProtectionGroupMode 

func WithProtectionGroupMode(mode ProtectionGroupMode) PublicTemplateOption

WithProtectionGroupMode returns an option for the specified protection group mode, which describes the hierarchy that an object is created within.

If mode is NonDuplicable, then tpm2.AttrFixedTPM will be set and tpm2.AttrEncryptedDuplication will be unset. tpm2.AttrFixedParent will also be set, which is equivalent to setting DuplicationMode to FixedParent.

If mode is Duplicable, then both tpm2.AttrFixedTPM and tpm2.AttrEncryptedDuplication will be unset.

If mode is DuplicableEncrypted, then tpm2.AttrFixedTPM will be unset and tpm2.AttrEncryptedDuplication will be set.

func WithProtectionGroupModeFromParent added in v1.2.0 

func WithProtectionGroupModeFromParent(parent *tpm2.Public) PublicTemplateOption

WithProtectionGroupModeFromParent returns an option that sets the protection group mode based on the attributes of the supplied parent public area.

func WithRSAKeyBits 

func WithRSAKeyBits(keyBits uint16) PublicTemplateOption

WithRSAKeyBits returns an option for the specified RSA key size in bits. This will panic for objects with a type other than tpm2.ObjectTypeRSA.

func WithRSAParams 

func WithRSAParams(keyBits uint16, exponent uint32) PublicTemplateOption

WithRSAParams returns an option for the specified RSA key size in bits and the specified pbulic exponent. This will panic for objects with a type other than tpm2.ObjectTypeRSA.

func WithRSAScheme 

func WithRSAScheme(scheme tpm2.RSASchemeId, hashAlg tpm2.HashAlgorithmId) PublicTemplateOption

WithRSAScheme returns an option for the specified RSA scheme. This will panic for objects with a type other than tpm2.ObjectTypeRSA.

Attestation keys always have a signing scheme. Storage keys never have a scheme set. Decrypt or signing keys may have an appropriate scheme set.

func WithRSAUnique 

func WithRSAUnique(unique tpm2.PublicKeyRSA) PublicTemplateOption

WithRSAUnique returns an option for the specified public identity. This will panic for objects with a type other than tpm2.ObjectTypeRSA.

This is useful when creating templates for primary keys.

func WithSymmetricScheme 

func WithSymmetricScheme(alg tpm2.SymObjectAlgorithmId, keyBits uint16, mode tpm2.SymModeId) PublicTemplateOption

WithSymmetricScheme returns an option for the specified symmetric mode. This will panic for objects with the type tpm2.ObjectTypeKeyedHash.

Symmetric keys and asymmetric storage keys always have a symmetric scheme. Other keys never have a symmetric scheme. Only tpm2.SymModeCFB is valid for storage keys.

func WithSymmetricUnique 

func WithSymmetricUnique(unique tpm2.Digest) PublicTemplateOption

WithSymmetricUnique returns an option for the specified public identity. This will panic for objects with a type other than tpm2.ObjectTypeSymCipher.

This is useful when creating templates for primary keys.

func WithUserAuthMode 

func WithUserAuthMode(mode AuthMode) PublicTemplateOption

WithUserAuthMode returns an option that specifies the supplied mode should be used for authorization with the user role.

func WithoutDictionaryAttackProtection 

func WithoutDictionaryAttackProtection() PublicTemplateOption

WithoutDictionaryAttackProtection returns an option that disables DA protection for an object.

type Usage 

type Usage int

Usage describes the usage of a key.

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.