policyutil

package
v1.15.0 Latest Latest
Warning

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

 Go to latest Published: Feb 25, 2026 License: LGPL-3.0 Imports: 17 Imported by: 2

Documentation

Overview

Package policyutil contains utilties for constructing and executing authorization policies.

Index

Constants

This section is empty.

Variables

View Source 
var (
	// ErrMissingDigest is returned from [Policy.Execute] when a TPM2_PolicyCpHash or
	// TPM2_PolicyNameHash assertion is missing a digest for the selected session algorithm.
	ErrMissingDigest = errors.New("missing digest for session algorithm")
)

Functions

func ComputeCpHash 

func ComputeCpHash(alg tpm2.HashAlgorithmId, command tpm2.CommandCode, handles []Named, params ...interface{}) (tpm2.Digest, error)

ComputeCpHash computes a command parameter digest from the specified command code, the supplied handles, and parameters using the specified digest algorithm.

The required parameters is defined in part 3 of the TPM 2.0 Library Specification for the specific command.

The result of this is useful for extended authorization commands that bind an authorization to a command and set of command parameters, such as tpm2.TPMContext.PolicySigned, tpm2.TPMContext.PolicySecret, tpm2.TPMContext.PolicyTicket and tpm2.TPMContext.PolicyCpHash.

func ComputeNameHash 

func ComputeNameHash(alg tpm2.HashAlgorithmId, handles ...Named) (tpm2.Digest, error)

ComputeNameHash computes a digest from the supplied handles using the specified digest algorithm.

The result of this is useful with tpm2.TPMContext.PolicyNameHash.

func ComputePCRDigest 

func ComputePCRDigest(alg tpm2.HashAlgorithmId, pcrs tpm2.PCRSelectionList, values tpm2.PCRValues) (tpm2.Digest, error)

ComputePCRDigest computes a digest using the specified algorithm from the provided set of PCR values and the provided PCR selections. The digest is computed the same way as PCRComputeCurrentDigest as defined in the TPM reference implementation. It is most useful for computing an input to tpm2.TPMContext.PolicyPCR or [TrialAuthPolicy.PolicyPCR], and for validating quotes and creation data.

func ComputePCRDigestFromAllValues 

func ComputePCRDigestFromAllValues(alg tpm2.HashAlgorithmId, values tpm2.PCRValues) (tpm2.PCRSelectionList, tpm2.Digest, error)

ComputePCRDigestFromAllValues computes a digest using the specified algorithm from all of the provided set of PCR values. The digest is computed the same way as PCRComputeCurrentDigest as defined in the TPM reference implementation. It returns the PCR selection associated with the computed digest.

func ComputePolicyAuthorizationTBSDigest 

func ComputePolicyAuthorizationTBSDigest(alg crypto.Hash, message []byte, policyRef tpm2.Nonce) []byte

ComputePolicyAuthorizationTBSDigest computes the TBS digest for a policy authorization from the supplied message and policy reference. For a TPM2_PolicyAuthorize assertion, message is the approved policy digest.

This will panic if the specified digest algorithm is not available.

Types

type AuthorizedPolicies added in v1.15.0 

type AuthorizedPolicies interface {
	// AuthorizedPolicies returns a set of policies that are signed by the key with
	// the specified name, appropriate for a TPM2_PolicyAuthorize assertion with the
	// specified reference.
	AuthorizedPolicies(keySign tpm2.Name, policyRef tpm2.Nonce) ([]*Policy, error)
}

AuthorizedPolicies provides a way for Policy.Branches, Policy.Details and Policy.Stringer to access authorized policies that are required by a policy.

func NewAuthorizedPolicies added in v1.15.0 

func NewAuthorizedPolicies(policies []*Policy, nvPolicies []NVAuthorizedPolicy) AuthorizedPolicies

type Authorizer 

type Authorizer func(tpm2.ResourceContext) error

Authorizer provides a way to supply authorizations to Policy.Execute. The implementation sets the authorization value for the supplied resource.

type CpHash 

type CpHash interface {
	// Digest returns the command parameter digest for the specified algorithm.
	Digest(alg tpm2.HashAlgorithmId) (tpm2.Digest, error)
}

CpHash provides a way to obtain a command parameter digest.

func CommandParameterDigest 

func CommandParameterDigest(alg tpm2.HashAlgorithmId, digest tpm2.Digest) CpHash

CommandParameterDigest returns a CpHash implementation for the specified algorithm and digest.

func CommandParameters 

func CommandParameters(command tpm2.CommandCode, handles []Named, params ...interface{}) CpHash

CommandParameters returns a CpHash implementation for the specified command code, handles and parameters. The required parameters are defined in part 3 of the TPM 2.0 Library Specification for the specific command.

type ExternalSensitiveGetter added in v1.15.0 

type ExternalSensitiveGetter func(tpm2.Name) (*tpm2.Sensitive, error)

ExternalSensitiveGetter provides a way to supply sensitive areas to Policy.Execute. The implementation returns the sensitive area for the object with the specified name.

type LoadPolicyParams 

type LoadPolicyParams struct {
	Tickets              []*PolicyTicket         // See [PolicyExecuteParams.Tickets]
	IgnoreAuthorizations []PolicyAuthorizationID // See [PolicyExecuteParams.IgnoreAuthorizations]
	IgnoreNV             []Named                 // See [PolicyExecuteParams.IgnoreNV]
}

LoadPolicyParams contains parameters for policy sessions that are required to execute TPM2_Load commands via [PolicyResources.LoadedResource].

type NVAuthorizedPolicy added in v1.5.0 

type NVAuthorizedPolicy struct {
	Name   tpm2.Name
	Policy *Policy
}

type NameHash added in v1.11.0 

type NameHash interface {
	// Digest returns the name digest for the specified algorithm.
	Digest(alg tpm2.HashAlgorithmId) (tpm2.Digest, error)
}

NameHash provides a way to obtain a name digest.

func CommandHandleDigest added in v1.11.0 

func CommandHandleDigest(alg tpm2.HashAlgorithmId, digest tpm2.Digest) NameHash

CommandHandleDigest returns a NameHash implementation for the specified algorithm and digest.

func CommandHandles added in v1.11.0 

func CommandHandles(handles ...Named) NameHash

CommandHandles returns a NameHash implementation for the supplied command handles.

type Named 

type Named interface {
	Name() tpm2.Name
}

Named is some resource that has a name.

type NamedHandle added in v1.5.0 

type NamedHandle interface {
	Handle() tpm2.Handle
	Named
}

NamedHandle is some resource that has a name and a handle.

type NewPolicyExecuteSessionFn added in v1.15.0 

type NewPolicyExecuteSessionFn func(*tpm2.TPMContext, tpm2.SessionContext, ...tpm2.SessionContext) PolicyExecuteSession

type NewTPMHelperFn added in v1.4.0 

type NewTPMHelperFn func(*tpm2.TPMContext, ...tpm2.SessionContext) TPMHelper

type PersistentResource 

type PersistentResource struct {
	Name   tpm2.Name
	Handle tpm2.Handle

	Policy *Policy
}

PersistentResource contains details associated with a persistent object or NV index.

type Policy 

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

Policy corresponds to an authorization policy. It can be serialized with github.com/canonical/go-tpm2/mu.

func (*Policy) AddDigest added in v1.4.0 

func (p *Policy) AddDigest(alg tpm2.HashAlgorithmId) (tpm2.Digest, error)

AddDigest computes and adds an additional digest to this policy for the specified algorithm. The policy should be persisted after calling this if it is going to be used for a resource wth the specified algorithm. On success, it returns the computed digest.

This will fail for policies that contain TPM2_PolicyCpHash or TPM2_PolicyNameHash assertions, These can only be computed for a single digest algorithm, because they are bound to a specific resource via its name.

It will also fail for policies that contain TPM2_PolicyPCR assertions that were added by PolicyBuilderBranch.PolicyPCRDigest. In order to compute policies containing TPM2_PolicyPCR assertions for more than one digest, use the PolicyBuilderBranch.PolicyPCRValues API, which stores the raw PCR values from which a new digest can be computed (but may occupy more space for an assertion that contains more than a single PCR value, depending on the selection of algorithms).

func (*Policy) Authorize 

func (p *Policy) Authorize(rand io.Reader, authKey *tpm2.Public, policyRef tpm2.Nonce, signer crypto.Signer, opts crypto.SignerOpts) (err error)

Authorize signs this policy with the supplied signer so that it can be used as an authorized policy for a TPM2_PolicyAuthorize assertion with the supplied authKey and policyRef. Calling this updates the policy, so it should be persisted afterwards. This signs every digest that the policy has been computed for.

TPM2_PolicyAuthorize expects the digest algorithm of the signature to match the name algorithm of the public key, so the name algorithm of authKey must match the algorithm supplied through the opts argument.

This expects the policy to contain a digest for the selected algorithm already.

func (*Policy) Branches 

func (p *Policy) Branches(alg tpm2.HashAlgorithmId, authorizedPolicies AuthorizedPolicies) ([]string, error)

Branches returns the path of every branch in this policy.

If the authorizedPolicies argument is supplied, associated authorized policies will be merged into the result, otherwise missing authorized policies will be represented by a path component of the form "<authorize:key:%#x,ref:%#x>". The supplied algorithm is only really required for policies that make use of authorized policies, and is used to select the algorithm for encoding the path component for an authorized policy, which is the policy digest. Setting this to tpm2.HashAlgorithmNull selects the first digest algorithm that this policy is computed for.

func (*Policy) Details 

func (p *Policy) Details(alg tpm2.HashAlgorithmId, path string, authorizedPolicies AuthorizedPolicies) (map[string]PolicyBranchDetails, error)

Details returns details of all branches with the supplied path prefix, for the specified algorithm. If the specified algorithm is tpm2.HashAlgorithmNull, then the first algorithm the policy is computed for is used.

If the authorizedPolicies argument is supplied, details of branches from associated authorized policies will be inserted into the result.

func (*Policy) Digest 

func (p *Policy) Digest(alg tpm2.HashAlgorithmId) (tpm2.Digest, error)

Digest returns the digest for this policy for the specified algorithm, if it has been computed. If it hasn't been computed, ErrMissingDigest is returned.

func (*Policy) Execute 

func (p *Policy) Execute(session PolicyExecuteSession, options ...PolicyExecuteOption) (result *PolicyExecuteResult, err error)

Execute runs this policy using the supplied policy session.

TPM2_PolicyNV assertions will create a session for authorizing the associated NV index. The auth type is determined automatically from the NV index attributes, but where both HMAC and policy auth is supported, policy auth is used.

TPM2_PolicySecret assertions will create a session for authorizing the associated resource. The auth type is determined automatically based on the public attributes for NV indices and ordinary objects, but where both HMAC and policy auth is supported, HMAC auth is used. If the resource is a permanent resource, then only HMAC auth is used.

The caller may explicitly select branches and authorized policies to execute with the WithPathConstraint option. Alternatively, if a path is not specified explicitly, or it contains a pattern that matches multiple branches, an appropriate execution path is chosen automatically where possible. This works by selecting the first suitable path, with a preference for paths that don't include TPM2_PolicySecret, TPM2_PolicySigned, TPM2_PolicyAuthValue, and TPM2_PolicyPassword assertions. It also has a preference for paths that don't include TPM2_PolicyNV assertions that require authorization to use or read, and for paths without TPM2_PolicyCommandCode, TPM2_PolicyCpHash, TPM2_PolicyNameHash and TPM2_PolicyDuplicatiionSelect assertions where no session usage contraints are supplied. A path is omitted from the set of suitable paths if any of the following conditions are true:

  • It contains a command code, command parameter hash, or name hash that doesn't match those supplied via WithSessionUsageCommandConstraint or [WithSessionUsageHandlesConstraint].
  • It contains a TPM2_PolicyAuthValue or TPM2_PolicyPassword assertion and this isn't permitted because of the [WithSessionUsageNoAuthValue] option.
  • It uses TPM2_PolicyNvWritten with a value that doesn't match the public area of the NV index that the session will be used to authorize, provided via the WithSessionUsageCommandConstraint or [WithSessionUsageHandlesConstraint]..
  • It uses TPM2_PolicySigned, TPM2_PolicySecret or TPM2_PolicyAuthorize and the specific authorization was supplied to WithIgnoreAuthorizationsConstraint.
  • It uses TPM2_PolicyNV and the NV index was supplied to WithIgnoreNVConstraint.
  • It uses TPM2_PolicyNV with conditions that will fail against the current NV index contents, if the index has an authorization policy that permits the use of TPM2_NV_Read without any other conditions, else the condition isn't checked.
  • It uses TPM2_PolicyPCR with values that don't match the current PCR values.
  • It uses TPM2_PolicyCounterTimer with conditions that will fail.

Note that this automatic selection makes the following assumptions:

  • TPM2_PolicySecret assertions always succeed. Where they are known to not succeed because the authorization value isn't known or the resource can't be loaded, supply the assertion details to WithIgnoreAuthorizationsConstraint.
  • TPM2_PolicySigned assertions always succeed. Where they are known to not succeed because an assertion can't be provided or it is invalid, supply the assertion details to WithIgnoreAuthorizationsConstraint.
  • TPM2_PolicyAuthorize assertions always succeed if policies are returned from the implementation of [PolicyExecuteResources.AuthorizedPolicies]. Where these are known to not succeed, supply the assertion details to WithIgnoreAuthorizationsConstraint.
  • TPM2_PolicyNV assertions on NV indexes that require authorization to read will always succeed. Where these are known to not suceed, supply the NV index name to WithIgnoreNVConstraint.

On success, the supplied policy session may be used for authorization in a context that requires that this policy is satisfied. Information about the result of executing the session is also returned.

func (Policy) Marshal 

func (p Policy) Marshal(w io.Writer) error

Marshal implements mu.CustomMarshaller.Marshal.

func (*Policy) String added in v1.5.0 

func (p *Policy) String() string

func (*Policy) Stringer added in v1.5.0 

func (p *Policy) Stringer(alg tpm2.HashAlgorithmId, authorizedPolicies AuthorizedPolicies) fmt.Stringer

Stringer returns a fmt.Stringer that will print a string representation of the policy for the specified digest algorithm. The policy must already include this algorithm. If the algorithm is tpm2.HashAlgorithmNull, then the first computed algorithm will be used. If authorizedPolicies is supplied, the string representation will include the relevant authorized policies as well.

func (*Policy) Unmarshal 

func (p *Policy) Unmarshal(r io.Reader) error

Unmarshal implements mu.CustomMarshaller.Unarshal.

func (*Policy) Validate 

func (p *Policy) Validate(alg tpm2.HashAlgorithmId) (tpm2.Digest, error)

Validate performs some checking of every element in the policy, and verifies that every branch is consistent with their stored digests. On success, it returns the digest correpsonding to this policy for the specified digest algorithm.

type PolicyAuthorization 

type PolicyAuthorization struct {
	AuthKey   *tpm2.Public    // The public key of the signer, associated with the corresponding assertion.
	PolicyRef tpm2.Nonce      // The policy ref of the corresponding assertion
	Signature *tpm2.Signature // The actual signature
}

PolicyAuthorization corresponds to a signed authorization for a TPM2_PolicyAuthorize or TPM2_PolicySigned assertion.

func SignPolicyAuthorization 

func SignPolicyAuthorization(rand io.Reader, message []byte, authKey *tpm2.Public, policyRef tpm2.Nonce, signer crypto.Signer, opts crypto.SignerOpts) (*PolicyAuthorization, error)

SignPolicyAuthorization signs a new policy authorization using the supplied signer and options. Note that only RSA-SSA, RSA-PSS, ECDSA and HMAC signatures can be created.

The authKey argument is the corresponding public key. Both the authKey and policyRef arguments bind the authorization to a specific assertion in a policy.

If the authorization is for use with TPM2_PolicyAuthorize then the supplied message is the approved policy digest. This can sign authorizations for TPM2_PolicySigned as well, but SignPolicySignedAuthorization is preferred for that because it constructs the message appropriately.

func (*PolicyAuthorization) Verify 

func (a *PolicyAuthorization) Verify(message []byte) (ok bool, err error)

Verify verifies the signature of this authorization. If the authorization is for use with TPM2_PolicyAuthorize then the supplied message is the approved policy digest. This can verify authorizations for TPM2_PolicySigned as well, but PolicySignedAuthorization.Verify is preferred for that because it constructs the message appropriately.

type PolicyAuthorizationDetails 

type PolicyAuthorizationDetails struct {
	AuthName  tpm2.Name
	PolicyRef tpm2.Nonce
}

PolicyAuthorizationDetails contains the properties of a TPM2_PolicySecret, TPM2_PolicySigned or TPM2_PolicyAuthorize assertion.

type PolicyAuthorizationError 

type PolicyAuthorizationError struct {
	AuthName  tpm2.Name
	PolicyRef tpm2.Nonce
	// contains filtered or unexported fields
}

PolicyAuthorizationError is returned from Policy.Execute if:

  • the policy uses TPM2_PolicySecret and the associated resource could not be authorized. When this occurs because there was an error loading the associated resource, this will wrap a *ResourceLoadError. If there was an error authorizing use of the resource with a policy session, this will wrap a *ResourceAuthorizeError.
  • the policy uses TPM2_PolicySigned and no or an invalid signed authorization was supplied.
  • the policy uses TPM2_PolicyAuthorize and no or an invalid authorized policy was supplied.

func (*PolicyAuthorizationError) Error 

func (e *PolicyAuthorizationError) Error() string

func (*PolicyAuthorizationError) Unwrap 

func (e *PolicyAuthorizationError) Unwrap() error

type PolicyAuthorizationID 

type PolicyAuthorizationID = PolicyAuthorizationDetails

PolicyAuthorizationID contains an identifier for a TPM2_PolicySecret, TPM2_PolicySigned or TPM2_PolicyAuthorize assertion.

type PolicyBranchDetails 

type PolicyBranchDetails struct {
	NV              []PolicyNVDetails            // TPM2_PolicyNV assertions
	Secret          []PolicyAuthorizationDetails // TPM2_PolicySecret assertions
	Signed          []PolicyAuthorizationDetails // TPM2_PolicySigned assertions
	Authorize       []PolicyAuthorizationDetails // TPM2_PolicyAuthorize assertions
	AuthValueNeeded bool                         // The branch contains a TPM2_PolicyAuthValue or TPM2_PolicyPassword assertion

	CounterTimer []PolicyCounterTimerDetails // TPM2_PolicyCounterTimer assertions

	PCR []PolicyPCRDetails // TPM2_PolicyPCR assertions
	// contains filtered or unexported fields
}

PolicyBranchDetails contains the properties of a single policy branch.

func (*PolicyBranchDetails) CommandCode 

func (r *PolicyBranchDetails) CommandCode() (code tpm2.CommandCode, set bool)

The command code associated with a branch if set, either set by the TPM2_PolicyCommandCode or TPM2_PolicyDuplicationSelect assertion.

func (*PolicyBranchDetails) CpHash 

func (r *PolicyBranchDetails) CpHash() (cpHashA tpm2.Digest, set bool)

The cpHash associated with a branch if set, either set by the TPM2_PolicyCpHash, TPM2_PolicySecret, or TPM2_PolicySigned assertions.

func (*PolicyBranchDetails) IsValid 

func (r *PolicyBranchDetails) IsValid() bool

IsValid indicates whether the corresponding policy branch is valid.

func (*PolicyBranchDetails) NameHash 

func (r *PolicyBranchDetails) NameHash() (nameHash tpm2.Digest, set bool)

The nameHash associated with a branch if set, either set by the TPM2_PolicyNameHash or TPM2_PolicyDuplicationSelect assertion.

func (*PolicyBranchDetails) NvWritten 

func (r *PolicyBranchDetails) NvWritten() (nvWrittenSet bool, set bool)

The nvWrittenSet value associated with a branch if set.

type PolicyBuilder 

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

PolicyBuilder provides a way to compute an authorization policy. A policy consists of a sequence of assertions, and may contain sub-branches in order to create a policy that can satisfy multiple conditions. A policy can be arbitrarily complex.

All policies have a root branch and execution with Policy.Execute starts with this branch. Whenever a branch node is encountered, a sub-branch is chosen. Execution then continues with the chosen sub-branch until all assertions in it have been executed. Execution then resumes in the parent branch, with the assertion immediately following the branch node.

The PolicyBuilder API only allows a policy to be appended to.

The PolicyBuilder instance will be marked as failed whenever an error occurs. This means that it isn't necessary to check errors for every call. In the event of an earlier error, calls to PolicyBuilder.Policy and PolicyBuilder.Digest will return an error.

XXX: Note that the PolicyBuilder API may change.

func NewPolicyBuilder 

func NewPolicyBuilder(alg tpm2.HashAlgorithmId) *PolicyBuilder

NewPolicyBuilder returns a new PolicyBuilder. It will panic if the supplied algorithm is not available.

func NewPolicyBuilderOR added in v1.4.0 

func NewPolicyBuilderOR(alg tpm2.HashAlgorithmId, policies ...*Policy) *PolicyBuilder

NewPolicyBuilderOR returns a new PolicyBuilder initialized with a TPM2_PolicyOR assertion of the supplied policies. This is to make it possible to use this API to compute digests of policies with branches without having to use the Policy API to execute them, or to build policies with branches with low-level control of branch execution by manually executing a sequence of Policy structures corresponding to each branch. Applications that use Policy for execution should normally just make use of PolicyBuilderBranch.AddBranchNode and PolicyBuilderBranchNode.AddBranch for constructing policies with branches though.

func (*PolicyBuilder) Digest added in v1.5.0 

func (b *PolicyBuilder) Digest() (tpm2.Digest, error)

Digest returns the current digest. This will commit the current PolicyBuilderBranchNode to the root PolicyBuilderBranch if it hasn't been done already.

This will return an error if any call when building the policy failed.

func (*PolicyBuilder) Policy 

func (b *PolicyBuilder) Policy() (tpm2.Digest, *Policy, error)

Policy returns the current policy and digest. This will commit the current PolicyBuilderBranchNode to the root PolicyBuilderBranch if it hasn't been done already.

This will return an error if any call when building the policy failed.

func (*PolicyBuilder) RootBranch 

func (b *PolicyBuilder) RootBranch() *PolicyBuilderBranch

RootBranch returns the root branch associated with the policy that is being built.

type PolicyBuilderBranch 

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

PolicyBuilderBranch corresponds to a branch in a policy that is being computed.

func (*PolicyBuilderBranch) AddBranchNode 

func (b *PolicyBuilderBranch) AddBranchNode(fn PolicyBuilderBranchNodeContinuation) error

AddBranchNode adds a branch node to this branch from which sub-branches can be added. This makes it possible to create policies that can be satisified with different sets of conditions. One of the sub-branches will be selected during execution, and will be executed before the remaining assertions in this branch.

func (*PolicyBuilderBranch) PolicyAuthValue 

func (b *PolicyBuilderBranch) PolicyAuthValue() (tpm2.Digest, error)

PolicyAuthValue adds a TPM2_PolicyAuthValue assertion to this branch so that the policy requires knowledge of the authorization value of the resource on which the policy session is used.

func (*PolicyBuilderBranch) PolicyAuthorize 

func (b *PolicyBuilderBranch) PolicyAuthorize(policyRef tpm2.Nonce, keySign *tpm2.Public) (tpm2.Digest, error)

PolicyAuthorize adds a TPM2_PolicyAuthorize assertion to this branch so that the policy can be changed by allowing the authorizing entity to sign new policies.

When Policy.Execute runs this assertion, it will select an execute an appropriate authorized policy.

Note that authorizations signed by the owner of the key must use a digest algorithm that matches the name algorithm of the key. This is a TPM limitation. Policies can only be authorized by asymmetric signatures.

This assertion must come before any other assertions in a policy. Whilst this is not a limitation of how this works on the TPM, the Policy.Authorize and Policy.Execute APIs currently do not support authorized policies with a non-empty starting digest.

func (*PolicyBuilderBranch) PolicyCommandCode 

func (b *PolicyBuilderBranch) PolicyCommandCode(code tpm2.CommandCode) (tpm2.Digest, error)

PolicyCommandCode adds a TPM2_PolicyCommandCode assertion to this branch to bind the policy to the specified command.

func (*PolicyBuilderBranch) PolicyCounterTimer 

func (b *PolicyBuilderBranch) PolicyCounterTimer(operandB tpm2.Operand, offset uint16, operation tpm2.ArithmeticOp) (tpm2.Digest, error)

PolicyCounterTimer adds a TPM2_PolicyCounterTimer assertion to this branch to bind the policy to the contents of the tpm2.TimeInfo structure.

func (*PolicyBuilderBranch) PolicyCpHash 

func (b *PolicyBuilderBranch) PolicyCpHash(cpHash CpHash) (tpm2.Digest, error)

PolicyCpHash adds a TPM2_PolicyCpHash assertion to this branch in order to bind the policy to the supplied command parameters.

As this binds the authorization to an object and and a policy has to have the same algorithm as this, policies with this assertion can only be computed for a single digest algorithm.

func (*PolicyBuilderBranch) PolicyDuplicationSelect 

func (b *PolicyBuilderBranch) PolicyDuplicationSelect(object, newParent Named, includeObject bool) (tpm2.Digest, error)

PolicyDuplicationSelect adds a TPM2_PolicyDuplicationSelect assertion to this branch in order to permit duplication of object to newParent with the tpm2.TPMContext.Duplicate function. If includeObject is true, then the assertion is bound to both object and newParent. If includeObject is false then the assertion is only bound to newParent. In this case, supplying object is optional. Note that when the TPM2_PolicyDuplicationSelect assertions is executed, the object name must be supplied because the assertion sets the name hash of the session. If object is supplied here, then it will be included in the policy and used when the assertion is executed. If it isn't supplied here, then it will be obtained from the [PolicySessionUsage] supplied to Policy.Execute.

func (*PolicyBuilderBranch) PolicyNV 

func (b *PolicyBuilderBranch) PolicyNV(nvIndex *tpm2.NVPublic, operandB tpm2.Operand, offset uint16, operation tpm2.ArithmeticOp) (tpm2.Digest, error)

PolicyNV adds a TPM2_PolicyNV assertion to this branch in order to bind the policy to the contents of the specified index. The caller specifies a value to be used for the comparison via the operandB argument, an offset from the start of the NV index data from which to start the comparison via the offset argument, and a comparison operator via the operation argument.

When using this assertion, it is generally good practise for the NV index to have an authorization policy that permits the use of TPM2_PolicyNV and TPM2_NV_Read without any conditions (ie, a policy with branches for those commands without any additional assertions). Where this assertion appears in a policy with multiple branches or a policy that is authorized, the contents of the NV index will be tested in the process of automatic branch selection if the index has a policy that permits the use of TPM2_NV_Read without any other conditions.

func (*PolicyBuilderBranch) PolicyNameHash 

func (b *PolicyBuilderBranch) PolicyNameHash(nameHash NameHash) (tpm2.Digest, error)

PolicyNameHash adds a TPM2_PolicyNameHash assertion to this branch in order to bind the policy to the supplied command handles.

As this binds the authorization to an object and and a policy has to have the same algorithm as this, policies with this assertion can only be computed for a single digest algorithm.

func (*PolicyBuilderBranch) PolicyNvWritten 

func (b *PolicyBuilderBranch) PolicyNvWritten(writtenSet bool) (tpm2.Digest, error)

PolicyNvWritten adds a TPM2_PolicyNvWritten assertion to this branch in order to bind the policy to the status of the tpm2.AttrNVWritten attribute for the NV index on which the session is used.

func (*PolicyBuilderBranch) PolicyOR added in v1.6.0 

func (b *PolicyBuilderBranch) PolicyOR(pHashList ...tpm2.Digest) (tpm2.Digest, error)

PolicyOR adds a TPM2_PolicyOR assertion to this branch for low-level control of policies that can be satisfied with different sets of conditions. This is to make it possible to use this API to compute digests of policies with branches without having to use the Policy API to execute them, or to build policies with branches with low-level control of branch execution by manually executing a sequence of Policy structures corresponding to each branch. Applications that use Policy for execution should normally just make use of PolicyBuilderBranch.AddBranchNode and PolicyBuilderBranchNode.AddBranch for constructing policies with branches though.

func (*PolicyBuilderBranch) PolicyPCRDigest added in v1.11.0 

func (b *PolicyBuilderBranch) PolicyPCRDigest(pcrDigest tpm2.Digest, pcrs tpm2.PCRSelectionList) (tpm2.Digest, error)

PolicyPCRDigest adds a TPM2_PolicyPCR assertion to this branch in order to bind the policy to the supplied PCR selection and digest. The digest used to compute pcrDigest must match the algorithm that this PolicyBuilder was constructed with.

The downside of this API instead of using [PolicyPCRValues] is that policies with this element in can only be computed for a single digest. It does have the advantage of potentially being more space efficient when the assertion contains more than a single PCR, depending on algorithm selection.

func (*PolicyBuilderBranch) PolicyPCRValues added in v1.11.0 

func (b *PolicyBuilderBranch) PolicyPCRValues(values tpm2.PCRValues) (tpm2.Digest, error)

PolicyPCRValues adds a TPM2_PolicyPCR assertion to this branch in order to bind the policy to the supplied PCR values. This stores the raw PCR values in the policy which permits it to be computed for multiple digests using Policy.AddDigest. A downside of this is that it may occupy more space for an assertion that contains more than a single PCR value compared with [PolicyPCRDigest], depending on the selection of algorithms.

func (*PolicyBuilderBranch) PolicyPassword 

func (b *PolicyBuilderBranch) PolicyPassword() (tpm2.Digest, error)

PolicyPassword adds a TPM2_PolicyPassword assertion to this branch so that the policy requires knowledge of the authorization value of the resource on which the policy session is used.

func (*PolicyBuilderBranch) PolicySecret 

func (b *PolicyBuilderBranch) PolicySecret(authObject Named, policyRef tpm2.Nonce) (tpm2.Digest, error)

PolicySecret adds a TPM2_PolicySecret assertion to this branch so that the policy requires knowledge of the authorization value of the object associated with authObject.

func (*PolicyBuilderBranch) PolicySigned 

func (b *PolicyBuilderBranch) PolicySigned(authKey *tpm2.Public, policyRef tpm2.Nonce) (tpm2.Digest, error)

PolicySigned adds a TPM2_PolicySigned assertion to this branch so that the policy requires an assertion signed by the owner of the supplied key. This supports HMAC assertions, but the [PolicyResources] implementation supplied to Policy.Execute must implement the ExternalSensitive method in order to obtain the sensitive part of the key, which is not stored inside the policy.

type PolicyBuilderBranchContinuation added in v1.14.0 

type PolicyBuilderBranchContinuation func(*PolicyBuilderBranch)

type PolicyBuilderBranchNode 

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

PolicyBuilderBranchNode is a point in a PolicyBuilderBranch to which sub-branches can be added.

func (*PolicyBuilderBranchNode) AddBranch 

func (n *PolicyBuilderBranchNode) AddBranch(name string, fn PolicyBuilderBranchContinuation) error

AddBranch adds a new branch to this branch node. The branch can be created with an optional name which can be used to select it during execution.

type PolicyBuilderBranchNodeContinuation added in v1.14.0 

type PolicyBuilderBranchNodeContinuation func(*PolicyBuilderBranchNode)

type PolicyCounterTimerDetails 

type PolicyCounterTimerDetails struct {
	OperandB  tpm2.Operand
	Offset    uint16
	Operation tpm2.ArithmeticOp
}

PolicyCounterTimerDetails contains the properties of a TPM2_PolicyCounterTimer assertion.

type PolicyError 

type PolicyError struct {
	Path string // the path of the branch at which the error occurred
	// contains filtered or unexported fields
}

PolicyError is returned from Policy.Execute and other methods when an error is encountered during some processing of a policy. It provides an indication of where an error occurred.

func (*PolicyError) Error 

func (e *PolicyError) Error() string

func (*PolicyError) Unwrap 

func (e *PolicyError) Unwrap() error

type PolicyExecuteOption added in v1.15.0 

type PolicyExecuteOption func(*policyExecuteParams)

func WithExternalTPMHelper added in v1.15.0 

func WithExternalTPMHelper(tpm TPMHelper) PolicyExecuteOption

WithExternalTPMHelper allows Policy.Execute to make use of other TPM functions. This must be supplied for any policy that executes TPM2_PolicyNV, TPM2_PolicySecret, TPM2_PolicySigned, or TPM2_PolicyAuthorize assertions, or any policy that contains branches with TPM2_PolicyPCR or TPM2_PolicyCounterTimer assertions where branches aren't selected explicitly.

func WithIgnoreAuthorizationsConstraint added in v1.15.0 

func WithIgnoreAuthorizationsConstraint(ids []PolicyAuthorizationID) PolicyExecuteOption

WithIgnoreAuthorizationsConstraint tells Policy.Execute which branches or authorized policies containing TPM2_PolicySigned, TPM2_PolicySecret or TPM2_PolicyAuthorize assertions that should not be automatically chosen. The assertions are identified by an ID. This can be used where these assertions have failed on previous runs. This propagates to sub-policies.

func WithIgnoreNVConstraint added in v1.15.0 

func WithIgnoreNVConstraint(nv []Named) PolicyExecuteOption

WithIgnoreNVConstraint tells Policy.Execute which branches or authorized policies containing TPM2_PolicyNV assertions that should not be automatically chosen. The assertions are identified by the NV index name. This can be used where these assertions have failed due to an authorization issue on previous runs. This propagates to sub-policies.

func WithPathConstraint added in v1.15.0 

func WithPathConstraint(path string) PolicyExecuteOption

WithPathConstraint provides a way to explicitly select which branches or authorized policies Policy.Execute should execute, or constraining which of these can be considered when automatically choosing them, by specifying patterns.

A path consists of zero or more components separated by a '/' character, with each component identifying a branch to select when a branch node is encountered (or a policy to select when an authorized policy is required) during execution. When a branch node or authorized policy is encountered, the selected sub-branch or policy is executed before resuming execution in the original branch.

When selecting a branch, a component can either identify a branch by its name (if it has one), or it can be a numeric identifier of the form "{n}" which selects the branch at index n.

When selecting an authorized policy, a component identifies the policy by specifying the digest of the policy for the current session algorithm.

If a component is "**", then Policy.Execute will attempt to automatically choose an execution path for the entire sub-tree associated with the current branch node or authorized policy. This includes choosing additional branches and authorized policies encountered during the execution of the selected sub-tree. Remaining path components will be consumed when resuming execution in the original branch

A component can be a pattern that is compatible with filepath.Match. In the case where the pattern matches more than one branch, then Policy.Execute will attempt to automatically choose an immediate sub-branch or authorized policy, but additional branches and authorized policies encountered during the execution of the selected sub-tree will consume additional path components.

If the path has insufficent components for the branch nodes or authorized policies encountered in a policy, Policy.Execute will attempt to automatically choose an appropriate execution path for the remainder of the policy.

func WithPolicyExecuteResources added in v1.15.0 

func WithPolicyExecuteResources(resources PolicyExecuteResources) PolicyExecuteOption

WithPolicyExecuteResources allows Policy.Execute to obtain resources required by a policy. This must be supplied for any policy that executes TPM2_PolicyNV, TPM2_PolicySecret, TPM2_PolicySigned or TPM2_PolicyAuthorize assertions.

func WithResources added in v1.15.0 

func WithResources(tpm *tpm2.TPMContext, options ...PolicyExecuteResourcesOption) PolicyExecuteOption

WithResources allows Policy.Execute to obtain resources required by a policy, using an implementation of PolicyExecuteResources created by NewPolicyExecuteResources. This must be supplied for any policy that executes TPM2_PolicyNV, TPM2_PolicySecret, TPM2_PolicySigned or TPM2_PolicyAuthorize assertions.

func WithSessionUsageAuthIndex added in v1.15.0 

func WithSessionUsageAuthIndex(index uint8) PolicyExecuteOption

WithSessionUsageAuthIndex tells Policy.Execute the index (zero indexed) of the handle that the executed policy will be used for. This is zero for most commands, where most commands only have a single handle that requires authorization. There are a few commands that require authorization for 2 handles: TPM2_ActivateCredential, TPM2_EventSequenceComplete, TPM2_Certify, TPM2_GetSessionAuditDigest, TPM2_GetCommandAuditDigest, TPM2_GetTime, TPM2_CertifyX509, TPM2_NV_UndefineSpaceSpecial, TPM2_NV_Certify, and TPM2_AC_Send.

This must be used after [WithSessionUsageHandlesConstraint] or WithSessionUsageCommandConstraint.

func WithSessionUsageCommandConstraint added in v1.15.0 

func WithSessionUsageCommandConstraint(commandCode tpm2.CommandCode, handles []NamedHandle, params ...any) PolicyExecuteOption

WithSessionUsageHandlesConstraint tells Policy.Execute which command, handles and parameters will be used with the executed policy, and assists with automatically choosing branches where a policy has branches containing TPM2_PolicyCommandCode, TPM2_PolicyCpHash, TPM2_PolicyNameHash, TPM2_PolicyDuplicationSelect or TPM2_PolicyNvWritten assertions.

This clears the effect of WithSessionUsageAuthIndex.

func WithSessionUsageHandlesContraint added in v1.15.0 

func WithSessionUsageHandlesContraint(handles ...NamedHandle) PolicyExecuteOption

WithSessionUsageHandlesConstraint tells Policy.Execute which handles will be used with the executed policy, and assists with automatically choosing branches where a policy has branches containing TPM2_PolicyNameHash, TPM2_PolicyDuplicationSelect or TPM2_PolicyNvWritten assertions.

This clears the effect of WithSessionUsageAuthIndex.

func WithSessionUsageNoAuthValueConstraint added in v1.15.0 

func WithSessionUsageNoAuthValueConstraint() PolicyExecuteOption

WithSessionUsageNoAuthValueConstraint tells Policy.Execute that an authorization value will not be available when the executed policy is used. This ensures that branches with TPM2_PolicyAuthValue or TPM2_PolicyPassword assertions will not be selected.

func WithTPMHelper added in v1.15.0 

func WithTPMHelper(tpm *tpm2.TPMContext, options ...TPMHelperOption) PolicyExecuteOption

WithTPMHelper allows Policy.Execute to make use of other TPM functions, using an implementation of TPMHelper created by NewTPMHelper. This must be supplied for any policy that executes TPM2_PolicyNV, TPM2_PolicySecret, TPM2_PolicySigned, or TPM2_PolicyAuthorize assertions, or any policy that contains branches with TPM2_PolicyPCR or TPM2_PolicyCounterTimer assertions where branches aren't selected explicitly.

func WithTickets added in v1.15.0 

func WithTickets(tickets []*PolicyTicket) PolicyExecuteOption

WithTickets supplies tickets for TPM2_PolicySecret and TPM2_PolicySigned assertions. These are also supplied to sub-policies.

type PolicyExecuteResources added in v1.15.0 

type PolicyExecuteResources interface {
	// LoadedResource loads the resource with the specified name if required, and returns
	// a context. The Flush method of the returned context will be called once the resource
	// is no longer needed.
	//
	// This should return an error if no resource can be returned.
	LoadedResource(name tpm2.Name, policyParams *LoadPolicyParams) (resource ResourceContext, newTickets []*PolicyTicket, invalidTickets []*PolicyTicket, err error)

	// Policy returns a policy for the resource with the specified name if there
	// is one. As a policy is optional, returning a nil policy isn't an error.
	Policy(name tpm2.Name) (*Policy, error)

	// AuthorizedPolicies returns a set of policies that are signed by the key with
	// the specified name, appropriate for a TPM2_PolicyAuthorize assertion with the
	// specified reference.
	AuthorizedPolicies(keySign tpm2.Name, policyRef tpm2.Nonce) ([]*Policy, error)

	// Authorize sets the authorization value of the specified resource context.
	Authorize(resource tpm2.ResourceContext) error

	// SignedAuthorization signs a TPM2_PolicySigned authorization for the specified key, policy ref
	// and session nonce. The supplied algorithm is the session algorithm, which should be
	// used to construct a cpHash if desired.
	SignedAuthorization(sessionAlg tpm2.HashAlgorithmId, sessionNonce tpm2.Nonce, authKey tpm2.Name, policyRef tpm2.Nonce) (*PolicySignedAuthorization, error)

	// ContextSave saves the context of the transient resource associated with the supplied
	// handle. This will return nil if it fails.
	ContextSave(resource tpm2.ResourceContext) *tpm2.Context

	// ContextLoad loads the supplied context and returns a transient handle. This will return
	// nil if the context can't be loaded or isn't a transient resource.
	ContextLoad(context *tpm2.Context, policy *Policy) ResourceContext

	// ExternalSensitive returns the sensitive area associated with the supplied name, to be
	// loaded with TPM2_LoadExternal.
	ExternalSensitive(name tpm2.Name) (*tpm2.Sensitive, error)
}

PolicyExecuteResources provides a way for Policy.Execute to access resources that are required by a policy.

func NewPolicyExecuteResources added in v1.15.0 

func NewPolicyExecuteResources(tpm *tpm2.TPMContext, options ...PolicyExecuteResourcesOption) PolicyExecuteResources

NewPolicyExecuteResources returns a PolicyExecuteResources implementation that communicates with the supplied TPM.

type PolicyExecuteResourcesOption added in v1.15.0 

type PolicyExecuteResourcesOption func(*policyExecuteResources)

PolicyExecuteResourcesOption is an option supplied to NewPolicyExecuteResources.

func WithAuthorizedPolicies added in v1.15.0 

func WithAuthorizedPolicies(policies []*Policy) PolicyExecuteResourcesOption

WithAuthorizedPolicies allows authorized policies required by a policy to be supplied.

func WithAuthorizer added in v1.15.0 

func WithAuthorizer(fn Authorizer) PolicyExecuteResourcesOption

WithAuthorizer allows resources used when executing a policy to be authorized. This may be required for policies that contain TPM2_PolicyNV or TPM2_PolicySecret assertions.

func WithExternalSensitiveGetter added in v1.15.0 

func WithExternalSensitiveGetter(fn ExternalSensitiveGetter) PolicyExecuteResourcesOption

WithExternalSensitiveGetter allows sensitive areas required when executing a policy to be supplied. This may be required for any policy that includes TPM2_PolicySigned assertions with HMAC keys.

func WithPersistentResources added in v1.15.0 

func WithPersistentResources(resources []PersistentResource) PolicyExecuteResourcesOption

WithPersistentResources allows information about persistent resources and NV indexes required by a policy to be supplied.

Information about persistent resources and NV indexes doesn't need to be supplied explicitly if there is no need to associate a policy with them. The created PolicyExecuteResources will query TPM handles whenever a policy requires a persistent resource or NV index for which there is no information.

The created PolicyExecuteResources doesn't support associating policies with permanent resources - policies that use permanent resources will only use HMAC authorization for these.

func WithPolicyExecuteResourcesNewPolicySessionFn added in v1.15.0 

func WithPolicyExecuteResourcesNewPolicySessionFn(fn NewPolicyExecuteSessionFn) PolicyExecuteResourcesOption

WithPolicyExecuteResourcesNewPolicySessionFn allows the function used to create a new [PolicySession] to be overridden. The default is NewPolicyExecuteSession.

func WithPolicyExecuteResourcesNewTPMHelperFn added in v1.15.0 

func WithPolicyExecuteResourcesNewTPMHelperFn(fn NewTPMHelperFn) PolicyExecuteResourcesOption

WithPolicyExecuteResourcesNewTPMHelperFn allows the function used to create a new TPMHelper to be overridden. The default is NewTPMHelper.

func WithPolicyExecuteResourcesSessions added in v1.15.0 

func WithPolicyExecuteResourcesSessions(sessions ...tpm2.SessionContext) PolicyExecuteResourcesOption

WithExecutePoliyResourcesSessions allows extra sessions to be supplied to TPM commands.

func WithSignedAuthorizer added in v1.15.0 

func WithSignedAuthorizer(fn SignedAuthorizer) PolicyExecuteResourcesOption

WithSignedAuthorizer allows signed authorizations required when executing a policy to be supplied. This is required for any policy that includes TPM2_PolicySigned assertions.

func WithTransientResources added in v1.15.0 

func WithTransientResources(resources []TransientResource) PolicyExecuteResourcesOption

WithTransientResources allows information about transient resources required by a policy to be supplied.

When loading transient objects to use for a policy, the created PolicyExecuteResources will automatically load any prerequisite parent objects first, as long as the details of these are supplied.

type PolicyExecuteResult 

type PolicyExecuteResult struct {
	// NewTickets contains tickets that were created as a result of executing this policy.
	NewTickets []*PolicyTicket

	// InvalidTickets contains those tickets originally supplied to [Policy.Execute] that
	// were used but found to be invalid. These tickets shouldn't be supplied to
	// [Policy.Execute] again.
	InvalidTickets []*PolicyTicket

	// AuthValueNeeded indicates that the policy executed the TPM2_PolicyAuthValue or
	// TPM2_PolicyPassword assertion.
	AuthValueNeeded bool

	// Path indicates the executed path.
	Path string
	// contains filtered or unexported fields
}

PolicyExecuteResult is returned from Policy.Execute.

func (*PolicyExecuteResult) CommandCode added in v1.4.0 

func (r *PolicyExecuteResult) CommandCode() (code tpm2.CommandCode, set bool)

CommandCode returns the command code if a TPM2_PolicyCommandCode or TPM2_PolicyDuplicationSelect assertion was executed.

func (*PolicyExecuteResult) CpHash added in v1.4.0 

func (r *PolicyExecuteResult) CpHash() (cpHashA tpm2.Digest, set bool)

CpHash returns the command parameter hash if a TPM2_PolicyCpHash assertion was executed or a TPM2_PolicySecret or TPM2_PolicySigned assertion was executed with a cpHash.

func (*PolicyExecuteResult) NameHash added in v1.4.0 

func (r *PolicyExecuteResult) NameHash() (nameHash tpm2.Digest, set bool)

NameHash returns the name hash if a TPM2_PolicyNameHash or TPM2_PolicyDuplicationSelect assertion was executed.

func (*PolicyExecuteResult) NvWritten added in v1.4.0 

func (r *PolicyExecuteResult) NvWritten() (nvWrittenSet bool, set bool)

NvWritten returns the nvWrittenSet value if a TPM2_PolicyNvWritten assertion was executed.

type PolicyExecuteSession added in v1.15.0 

type PolicyExecuteSession interface {
	Context() SessionContext

	Name() tpm2.Name
	HashAlg() tpm2.HashAlgorithmId

	PolicySigned(authKey tpm2.ResourceContext, includeNonceTPM bool, cpHashA tpm2.Digest, policyRef tpm2.Nonce, expiration int32, auth *tpm2.Signature) (tpm2.Timeout, *tpm2.TkAuth, error)
	PolicySecret(authObject tpm2.ResourceContext, cpHashA tpm2.Digest, policyRef tpm2.Nonce, expiration int32, authObjectAuthSession tpm2.SessionContext) (tpm2.Timeout, *tpm2.TkAuth, error)
	PolicyTicket(timeout tpm2.Timeout, cpHashA tpm2.Digest, policyRef tpm2.Nonce, authName tpm2.Name, ticket *tpm2.TkAuth) error
	PolicyOR(pHashList tpm2.DigestList) error
	PolicyPCR(pcrDigest tpm2.Digest, pcrs tpm2.PCRSelectionList) error
	PolicyNV(auth, index tpm2.ResourceContext, operandB tpm2.Operand, offset uint16, operation tpm2.ArithmeticOp, authAuthSession tpm2.SessionContext) error
	PolicyCounterTimer(operandB tpm2.Operand, offset uint16, operation tpm2.ArithmeticOp) error
	PolicyCommandCode(code tpm2.CommandCode) error
	PolicyCpHash(cpHashA tpm2.Digest) error
	PolicyNameHash(nameHash tpm2.Digest) error
	PolicyDuplicationSelect(objectName, newParentName tpm2.Name, includeObject bool) error
	PolicyAuthorize(approvedPolicy tpm2.Digest, policyRef tpm2.Nonce, keySign tpm2.Name, verified *tpm2.TkVerified) error
	PolicyAuthValue() error
	PolicyPassword() error
	PolicyGetDigest() (tpm2.Digest, error)
	PolicyNvWritten(writtenSet bool) error
}

PolicyExecuteSession corresponds to a policy session used by Policy.Execute.

func NewPolicyExecuteSession added in v1.15.0 

func NewPolicyExecuteSession(tpm *tpm2.TPMContext, policySession tpm2.SessionContext, sessions ...tpm2.SessionContext) PolicyExecuteSession

type PolicyNVDetails 

type PolicyNVDetails struct {
	Auth      tpm2.Handle
	Index     tpm2.Handle
	Name      tpm2.Name
	OperandB  tpm2.Operand
	Offset    uint16
	Operation tpm2.ArithmeticOp
}

PolicyNVDetails contains the properties of a TPM2_PolicyNV assertion.

type PolicyNVError 

type PolicyNVError struct {
	Index tpm2.Handle // The NV index handle
	Name  tpm2.Name   // The NV index name
	// contains filtered or unexported fields
}

PolicyNVError is returned from Policy.Execute and other methods when an error is encountered when executing a TPM2_PolicyNV assertion. If there was an error authorizing use of the NV index with a policy session, this will wrap a *ResourceAuthorizeError.

func (*PolicyNVError) Error 

func (e *PolicyNVError) Error() string

func (*PolicyNVError) Unwrap 

func (e *PolicyNVError) Unwrap() error

type PolicyPCRDetails 

type PolicyPCRDetails struct {
	PCRDigest tpm2.Digest
	PCRs      tpm2.PCRSelectionList
}

PolicyPCRDetails contains the properties of a TPM2_PolicyPCR assertion.

type PolicySignedAuthorization 

type PolicySignedAuthorization struct {
	NonceTPM   tpm2.Nonce  // The TPM nonce of the session that this authorization is bound to
	CpHash     tpm2.Digest // The command parameters that this authorization is bound to
	Expiration int32       // The expiration time of this authorization
	PolicyAuthorization
}

PolicySignedAuthorization represents a signed authorization for a TPM2_PolicySigned assertion.

func SignPolicySignedAuthorization 

func SignPolicySignedAuthorization(rand io.Reader, params *PolicySignedParams, authKey *tpm2.Public, policyRef tpm2.Nonce, signer crypto.Signer, opts crypto.SignerOpts) (*PolicySignedAuthorization, error)

SignPolicySignedAuthorization creates a signed authorization that can be used by Policy.Execute for a TPM2_PolicySigned assertion or by using tpm2.TPMContext.PolicySigned directly. Note that only RSA-SSA, RSA-PSS, ECDSA and HMAC signatures can be created. The signer must be the owner of the corresponding authKey. The policyRef argument binds the authorization to a specific assertion in a policy.

The authorizing party chooses the values of the supplied parameters in order to limit the scope of the authorization.

If nonceTPM is supplied, the authorization will be bound to the session with the specified TPM nonce. If it is not supplied, the authorization is not bound to a specific session.

If cpHash is supplied, the authorization will be bound to the corresponding command parameters. If it is not supplied, the authorization is not bound to any specific command parameters. In this case, it is important to supply the current session digest.

If expiration is not zero, then the absolute value of this specifies an expiration time in seconds, after which the authorization will expire. If nonceTPM is also provided, the expiration time is measured from the time that nonceTPM was generated. If nonceTPM is not provided, the expiration time is measured from the time that this authorization is used in the TPM2_PolicySigned assertion.

The expiration field can be used to request a ticket from the TPM by specifying a negative value. The ticket can be used to satisfy the corresponding TPM2_PolicySigned assertion in future sessions, and its validity period and scope are restricted by the expiration and cpHashA arguments. If the authorization is not bound to a specific session, the ticket will expire on the next TPM reset if this occurs before the calculated expiration time

func (*PolicySignedAuthorization) Verify 

func (a *PolicySignedAuthorization) Verify() (ok bool, err error)

Verify verifies the signature of this signed authorization.

type PolicySignedParams added in v1.4.0 

type PolicySignedParams struct {
	HashAlg    tpm2.HashAlgorithmId // The policy session digest algorithm
	NonceTPM   tpm2.Nonce           // The TPM nonce of the session that an authorization should be bound to
	CpHash     CpHash               // The command parameters that an authorization should be bound to
	Expiration int32                // The expiration time of an authorization
}

PolicySignedParams provide the parameters that a TPM2_PolicySigned assertion should be bound to and can be passed to SignPolicySignedAuthorization.

type PolicyTicket 

type PolicyTicket struct {
	AuthName  tpm2.Name    // The name of the auth object associated with the corresponding assertion
	PolicyRef tpm2.Nonce   // The policy ref of the corresponding assertion
	CpHash    tpm2.Digest  // The cpHash supplied to the assertion that generated this ticket
	Timeout   tpm2.Timeout // The timeout returned by the assertion that generated this ticket

	// Ticket is the actual ticket returned by the TPM for the assertion that generated this ticket.
	// The Tag field indicates whether this was generated by TPM2_PolicySigned or TPM2_PolicySecret.
	Ticket *tpm2.TkAuth
}

PolicyTicket corresponds to a ticket generated from a TPM2_PolicySigned or TPM2_PolicySecret assertion and is returned by Policy.Execute. Generated tickets can be supplied to Policy.Execute in the future in order to satisfy these assertions as long as they haven't expired.

type ResourceAuthorizeError 

type ResourceAuthorizeError struct {
	Name tpm2.Name
	// contains filtered or unexported fields
}

ResourceAuthorizeError is returned from Policy.Execute if an error is encountered when trying to authorize a resource required by a policy. This should be wrappped in either a *PolicyNVError or *PolicyAuthorizationError which indicates the assertion that the error occurred for. This may wrap another *PolicyError.

func (*ResourceAuthorizeError) Error 

func (e *ResourceAuthorizeError) Error() string

func (*ResourceAuthorizeError) Unwrap 

func (e *ResourceAuthorizeError) Unwrap() error

type ResourceContext 

type ResourceContext interface {
	Resource() tpm2.ResourceContext // The actual resource
	Policy() *Policy                // The policy associated with this resource, if there is one
	Flush()                         // Flush the resource once it's no longer needed
}

ResourceContext corresponds to a resource on the TPM.

type ResourceLoadError 

type ResourceLoadError struct {
	Name tpm2.Name
	// contains filtered or unexported fields
}

ResourceLoadError is returned from Policy.Execute if the policy uses TPM2_PolicySecret and the associated resource could not be loaded. If loading the resource required authorization with a policy session and that failed, this will wrap another *PolicyError.

func (*ResourceLoadError) Error 

func (e *ResourceLoadError) Error() string

func (*ResourceLoadError) Unwrap 

func (e *ResourceLoadError) Unwrap() error

type SessionContext added in v1.4.0 

type SessionContext interface {
	Session() tpm2.SessionContext
	Save() (restore func() error, err error)
	Flush()
}

SessionContext corresponds to a session on the TPM

type SignedAuthorizer 

type SignedAuthorizer func(sessionAlg tpm2.HashAlgorithmId, sessionNonce tpm2.Nonce, authKey tpm2.Name, policyRef tpm2.Nonce) (*PolicySignedAuthorization, error)

SignedAuthorizer provides a way to supplied signed authorizations to Policy.Execute.

type TPMHelper added in v1.4.0 

type TPMHelper interface {
	// StartAuthSession returns an authorization session with the specified type and
	// algorithm. It is required for any policy that includes TPM2_PolicySecret or
	// TPM2_PolicyNV assertions.
	StartAuthSession(sessionType tpm2.SessionType, alg tpm2.HashAlgorithmId) (SessionContext, PolicyExecuteSession, error)

	// LoadExternal loads the supplied external object into the TPM. It is required by
	// any policy that includes TPM2_PolicySigned or TPM2_PolicyAuthorize assertions.
	LoadExternal(inPrivate *tpm2.Sensitive, inPublic *tpm2.Public, hierarchy tpm2.Handle) (ResourceContext, error)

	// ReadPublic returns the public area of the resource at the specified handle. It
	// is required by any policy that includes TPM2_PolicySecret assertions on persistent or
	// transient objects.
	ReadPublic(handle tpm2.HandleContext) (*tpm2.Public, error)

	// VerifySignature verifies the supplied signature with the supplied key object. It
	// is required by any policy that includes TPM2_PolicyAuthorize assertions.
	VerifySignature(key tpm2.ResourceContext, digest tpm2.Digest, signature *tpm2.Signature) (*tpm2.TkVerified, error)

	// PCRRead returns the PCR values for the specified selection. It is required to
	// automatically resolve branches where branches include TPM2_PolicyPCR assertions.
	PCRRead(pcrs tpm2.PCRSelectionList) (tpm2.PCRValues, error)

	// ReadClock returns the current time info. It is required to automatically resolve
	// branches where branches include TPM2_PolicyCounterTimer assertions.
	ReadClock() (*tpm2.TimeInfo, error)

	// NVRead returns the contents of the specified NV index. It is required to automatically
	// resolve branches where branches include TPM2_PolicyNV assertions. This will only
	// be called if the index has an authorization policy with a branch that includes
	// TPM2_PolicyCommandCode for TPM2_NV_Read and no other assertions.
	NVRead(auth, index tpm2.ResourceContext, size, offset uint16, authAuthSession tpm2.SessionContext) (tpm2.MaxNVBuffer, error)

	// NVReadPublic returns the public area of the NV index at the specified handle. It
	// is required by any policy that includes TPM2_PolicyNV assertions or TPM2_PolicySecret
	// assertions on NV indices.
	NVReadPublic(handle tpm2.HandleContext) (*tpm2.NVPublic, error)

	// GetPermanentHandleAuthPolicy returns the auth policy digest for the specified
	// permanent handle, if there is one. If there isn't one, it returns a null hash.
	GetPermanentHandleAuthPolicy(handle tpm2.Handle) (tpm2.TaggedHash, error)
}

TPMHelper provides a way for Policy.Execute to communicate with a TPM.

func NewTPMHelper added in v1.4.0 

func NewTPMHelper(tpm *tpm2.TPMContext, options ...TPMHelperOption) TPMHelper

NewTPMHelper returns an implementation of TPMHelper that uses the supplied TPM context.

type TPMHelperOption added in v1.15.0 

type TPMHelperOption func(*tpmHelper)

TPMHelperOption is an option supplied to NewTPMHelper.

func WithTPMHelperNewPolicyExecuteSessionFn added in v1.15.0 

func WithTPMHelperNewPolicyExecuteSessionFn(fn NewPolicyExecuteSessionFn) TPMHelperOption

WithTPMHelperNewPolicyExecuteSessionFn allows the function used to create a new PolicyExecuteSession in StartAuthSession to be overridden. The default is NewPolicyExecuteSession.

func WithTPMHelperSessions added in v1.15.0 

func WithTPMHelperSessions(sessions ...tpm2.SessionContext) TPMHelperOption

WithTPMHelperSessions allows extra sessions to be supplied to TPM commands.

type TransientResource 

type TransientResource struct {
	ParentName tpm2.Name
	Public     *tpm2.Public
	Private    tpm2.Private

	Policy *Policy
}

TransientResource contains details associated with a transient object.

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.