Policy calculation module
Feature API » Internals of Feature API

## Functions

TSS2_RC | ifapi_calculate_policy (TPML_POLICYELEMENTS *policy, TPML_DIGEST_VALUES *policyDigests, TPMI_ALG_HASH hash_alg, size_t hash_size, size_t digest_idx)
TSS2_RC | ifapi_calculate_policy_authorize (TPMS_POLICYAUTHORIZE *policy, TPML_DIGEST_VALUES *current_digest, TPMI_ALG_HASH current_hash_alg)
TSS2_RC | ifapi_calculate_policy_authorize_nv (TPMS_POLICYAUTHORIZENV *policy, TPML_DIGEST_VALUES *current_digest, TPMI_ALG_HASH current_hash_alg)
TSS2_RC | ifapi_calculate_policy_command_code (TPMS_POLICYCOMMANDCODE *policy, TPML_DIGEST_VALUES *current_digest, TPMI_ALG_HASH current_hash_alg)
TSS2_RC | ifapi_calculate_policy_counter_timer (TPMS_POLICYCOUNTERTIMER *policy, TPML_DIGEST_VALUES *current_digest, TPMI_ALG_HASH current_hash_alg)
TSS2_RC | ifapi_calculate_policy_cp_hash (TPMS_POLICYCPHASH *policy, TPML_DIGEST_VALUES *current_digest, TPMI_ALG_HASH current_hash_alg)
TSS2_RC | ifapi_calculate_policy_digest_hash (TPM2B_DIGEST *digest, TPML_DIGEST_VALUES *current_digest, TPMI_ALG_HASH current_hash_alg, TPM2_CC command_code)
TSS2_RC | ifapi_calculate_policy_duplicate (TPMS_POLICYDUPLICATIONSELECT *policy, TPML_DIGEST_VALUES *current_digest, TPMI_ALG_HASH current_hash_alg)
TSS2_RC | ifapi_calculate_policy_locality (TPMS_POLICYLOCALITY *policy, TPML_DIGEST_VALUES *current_digest, TPMI_ALG_HASH current_hash_alg)
TSS2_RC | ifapi_calculate_policy_name_hash (TPMS_POLICYNAMEHASH *policy, TPML_DIGEST_VALUES *current_digest, TPMI_ALG_HASH current_hash_alg)
TSS2_RC | ifapi_calculate_policy_nv (TPMS_POLICYNV *policy, TPML_DIGEST_VALUES *current_digest, TPMI_ALG_HASH current_hash_alg)
TSS2_RC | ifapi_calculate_policy_nv_written (TPMS_POLICYNVWRITTEN *policy, TPML_DIGEST_VALUES *current_digest, TPMI_ALG_HASH current_hash_alg)
TSS2_RC | ifapi_calculate_policy_or (TPMS_POLICYOR *policyOr, TPML_DIGEST_VALUES *current_digest, TPMI_ALG_HASH hash_alg, size_t hash_size, size_t digest_idx)
TSS2_RC | ifapi_calculate_policy_secret (TPMS_POLICYSECRET *policy, TPML_DIGEST_VALUES *current_digest, TPMI_ALG_HASH current_hash_alg)
TSS2_RC | ifapi_calculate_policy_signed (TPMS_POLICYSIGNED *policy, TPML_DIGEST_VALUES *current_digest, TPMI_ALG_HASH current_hash_alg)
TSS2_RC | ifapi_calculate_simple_policy (TPM2_CC command_code1, TPM2_CC command_code2, TPML_DIGEST_VALUES *current_digest, TPMI_ALG_HASH current_hash_alg)
TSS2_RC | ifapi_compute_policy_pcr (TPMS_POLICYPCR *policy, TPML_DIGEST_VALUES *current_digest, TPMI_ALG_HASH current_hash_alg)

## Detailed Description

Provides functions for policy calculation (without TPM).

## Function Documentation

## ifapi_calculate_policy()

TSS2_RC ifapi_calculate_policy | ( | TPML_POLICYELEMENTS * | policy,
|  | TPML_DIGEST_VALUES * | policyDigests,
|  | TPMI_ALG_HASH | hash_alg,
|  | size_t | hash_size,
|  | size_t | digest_idx )

Compute policy digest for a list of policies.

Every policy in the list will update the previous policy. Thus the final policy digest will describe the sequential execution of the policy list.

Parameters

  [in] | policy | The policy with the policy list.
  [in,out] | policyDigests | The digest list which has to be updated.
  [in] | hash_alg | The hash algorithm used for the policy computation.
  [in] | hash_size | The size of the policy digest.
  [in] | digest_idx | The index of the current policy in the passed digest list.

Return values

  TSS2_RC_SUCCESS | on success.
  TSS2_FAPI_RC_BAD_VALUE | if an invalid value was passed into the function.
  TSS2_FAPI_RC_GENERAL_FAILURE | if an internal error occurred.
  TSS2_FAPI_RC_BAD_REFERENCE | a invalid null pointer is passed.
  TSS2_FAPI_RC_MEMORY | if not enough memory can be allocated.

## ifapi_calculate_policy_authorize()

TSS2_RC ifapi_calculate_policy_authorize | ( | TPMS_POLICYAUTHORIZE * | policy,
|  | TPML_DIGEST_VALUES * | current_digest,
|  | TPMI_ALG_HASH | current_hash_alg )

Calculate a policy digest for a placeholder policy.

The placeholder policy can be extended during execution by a signed policy, which can be verified by using the parameters of this placeholder policy. Based on the command code, the key name of the signing key and a policy reference the new policy digest is computed by the function calculate_policy_key_param().

Parameters

  [in] | policy | The policy with the name of the public key and the policy reference.
  [in,out] | current_digest | The digest list which has to be updated.
  [in] | current_hash_alg | The hash algorithm used for the policy computation.

Return values

  TSS2_RC_SUCCESS | on success.
  TSS2_FAPI_RC_BAD_VALUE | if an invalid value was passed into the function.
  TSS2_FAPI_RC_GENERAL_FAILURE | if an internal error occurred.
  TSS2_FAPI_RC_BAD_REFERENCE | a invalid null pointer is passed.
  TSS2_FAPI_RC_MEMORY | if not enough memory can be allocated.

## ifapi_calculate_policy_authorize_nv()

TSS2_RC ifapi_calculate_policy_authorize_nv | ( | TPMS_POLICYAUTHORIZENV * | policy,
|  | TPML_DIGEST_VALUES * | current_digest,
|  | TPMI_ALG_HASH | current_hash_alg )

Calculate a policy digest for a policy stored in an approved NV index.

Based on the command code, and the computed NV name the new policy digest is computed by the function calculate_policy_key_param().

Parameters

  [in] | policy | The policy with the public information of the NV index.
  [in,out] | current_digest | The digest list which has to be updated.
  [in] | current_hash_alg | The hash algorithm used for the policy computation.

Return values

  TSS2_RC_SUCCESS | on success.
  TSS2_FAPI_RC_BAD_VALUE | if an invalid value was passed into the function.
  TSS2_FAPI_RC_BAD_REFERENCE | a invalid null pointer is passed.
  TSS2_FAPI_RC_MEMORY | if not enough memory can be allocated.
  TSS2_FAPI_RC_GENERAL_FAILURE | if an internal error occurred.

## ifapi_calculate_policy_command_code()

TSS2_RC ifapi_calculate_policy_command_code | ( | TPMS_POLICYCOMMANDCODE * | policy,
|  | TPML_DIGEST_VALUES * | current_digest,
|  | TPMI_ALG_HASH | current_hash_alg )

Update policy command code with a command code defined in the policy.

For the update two command codes will be used. The command code of policy command code and the passed command code. The policy will be updated with the function ifapi_calculate_simple_policy()

Parameters

  [in] | policy | The policy command code with the second command code.
  [in,out] | current_digest | The digest list which has to be updated.
  [in] | current_hash_alg | The hash algorithm used for the policy computation.

Return values

  TSS2_RC_SUCCESS | on success.
  TSS2_FAPI_RC_BAD_VALUE | if an invalid value was passed into the function.
  TSS2_FAPI_RC_GENERAL_FAILURE | if an internal error occurred.
  TSS2_FAPI_RC_BAD_REFERENCE | a invalid null pointer is passed.
  TSS2_FAPI_RC_MEMORY | if not enough memory can be allocated.

## ifapi_calculate_policy_counter_timer()

TSS2_RC ifapi_calculate_policy_counter_timer | ( | TPMS_POLICYCOUNTERTIMER * | policy,
|  | TPML_DIGEST_VALUES * | current_digest,
|  | TPMI_ALG_HASH | current_hash_alg )

Calculate a policy for for comparing current TPM timers with the policy.

The timer value and the operation for comparison defined in the policy will bu used to update the policy digest. The offset which is supported by the TPM policy for FAPI will be 0.

Parameters

  [in] | policy | The policy with the timer value and the operation for comparison.
  [in,out] | current_digest | The digest list which has to be updated.
  [in] | current_hash_alg | The hash algorithm used for the policy computation.

Return values

  TSS2_RC_SUCCESS | on success.
  TSS2_FAPI_RC_BAD_VALUE | if an invalid value was passed into the function.
  TSS2_FAPI_RC_GENERAL_FAILURE | if an internal error occurred.
  TSS2_FAPI_RC_BAD_REFERENCE | a invalid null pointer is passed.
  TSS2_FAPI_RC_MEMORY | if not enough memory can be allocated.

## ifapi_calculate_policy_cp_hash()

TSS2_RC ifapi_calculate_policy_cp_hash | ( | TPMS_POLICYCPHASH * | policy,
|  | TPML_DIGEST_VALUES * | current_digest,
|  | TPMI_ALG_HASH | current_hash_alg )

Compute policy bound to a specific command and command parameters.

The cp hash value and the command code will be updated by the function ifapi_calculate_policy_digest_hash().

Parameters

  [in] | policy | The policy with the cp hash value.
  [in,out] | current_digest | The digest list which has to be updated.
  [in] | current_hash_alg | The hash algorithm used for the policy computation.

Return values

  TSS2_RC_SUCCESS | on success.
  TSS2_FAPI_RC_BAD_VALUE | if an invalid value was passed into the function.
  TSS2_FAPI_RC_GENERAL_FAILURE | if an internal error occurred.
  TSS2_FAPI_RC_BAD_REFERENCE | a invalid null pointer is passed.
  TSS2_FAPI_RC_MEMORY | if not enough memory can be allocated.

## ifapi_calculate_policy_digest_hash()

TSS2_RC ifapi_calculate_policy_digest_hash | ( | TPM2B_DIGEST * | digest,
|  | TPML_DIGEST_VALUES * | current_digest,
|  | TPMI_ALG_HASH | current_hash_alg,
|  | TPM2_CC | command_code )

Compute policy if only a digest and a command code are needed for extension.

Parameters

  [in] | digest | the digest which will be used for policy extension.
  [in,out] | current_digest | The digest list which has to be updated.
  [in] | current_hash_alg | The hash algorithm used for the policy computation.
  [in] | command_code | The compute of the command which did compute the digest.

Return values

  TSS2_RC_SUCCESS | on success.
  TSS2_FAPI_RC_BAD_VALUE | if an invalid value was passed into the function.
  TSS2_FAPI_RC_GENERAL_FAILURE | if an internal error occurred.
  TSS2_FAPI_RC_BAD_REFERENCE | a invalid null pointer is passed.
  TSS2_FAPI_RC_MEMORY | if not enough memory can be allocated.

## ifapi_calculate_policy_duplicate()

TSS2_RC ifapi_calculate_policy_duplicate | ( | TPMS_POLICYDUPLICATIONSELECT * | policy,
|  | TPML_DIGEST_VALUES * | current_digest,
|  | TPMI_ALG_HASH | current_hash_alg )

Calculate a policy digest to allow duplication force a selected new parent.

Based on the command code, the name of the new parent, and the include object switch the new policy digest is computed.

Parameters

  [in] | policy | The policy with the new parent information.
  [in,out] | current_digest | The digest list which has to be updated.
  [in] | current_hash_alg | The hash algorithm used for the policy computation.

Return values

  TSS2_RC_SUCCESS | on success.
  TSS2_FAPI_RC_BAD_VALUE | if an invalid value was passed into the function.
  TSS2_FAPI_RC_GENERAL_FAILURE | if an internal error occurred.
  TSS2_FAPI_RC_BAD_REFERENCE | a invalid null pointer is passed.
  TSS2_FAPI_RC_MEMORY | if not enough memory can be allocated.

## ifapi_calculate_policy_locality()

TSS2_RC ifapi_calculate_policy_locality | ( | TPMS_POLICYLOCALITY * | policy,
|  | TPML_DIGEST_VALUES * | current_digest,
|  | TPMI_ALG_HASH | current_hash_alg )

Compute policy which limits authorization to a specific locality.

Parameters

  [in] | policy | The policy with the locality.
  [in,out] | current_digest | The digest list which has to be updated.
  [in] | current_hash_alg | The hash algorithm used for the policy computation.

Return values

  TSS2_RC_SUCCESS | on success.
  TSS2_FAPI_RC_BAD_VALUE | if an invalid value was passed into the function.
  TSS2_FAPI_RC_GENERAL_FAILURE | if an internal error occurred.
  TSS2_FAPI_RC_BAD_REFERENCE | a invalid null pointer is passed.
  TSS2_FAPI_RC_MEMORY | if not enough memory can be allocated.

## ifapi_calculate_policy_name_hash()

TSS2_RC ifapi_calculate_policy_name_hash | ( | TPMS_POLICYNAMEHASH * | policy,
|  | TPML_DIGEST_VALUES * | current_digest,
|  | TPMI_ALG_HASH | current_hash_alg )

Compute policy bound to a specific set of TPM entities.

The policy digest will be updated with the function ifapi_calculate_policy_digest_hash() which will add the hash of the entity name list.

Parameters

  [in] | policy | The policy with the list of entity names.
  [in,out] | current_digest | The digest list which has to be updated.
  [in] | current_hash_alg | The hash algorithm used for the policy computation.

Return values

  TSS2_RC_SUCCESS | on success.
  TSS2_FAPI_RC_BAD_VALUE | if an invalid value was passed into the function.
  TSS2_FAPI_RC_GENERAL_FAILURE | if an internal error occurred.
  TSS2_FAPI_RC_BAD_REFERENCE | a invalid null pointer is passed.
  TSS2_FAPI_RC_MEMORY | if not enough memory can be allocated.

## ifapi_calculate_policy_nv()

TSS2_RC ifapi_calculate_policy_nv | ( | TPMS_POLICYNV * | policy,
|  | TPML_DIGEST_VALUES * | current_digest,
|  | TPMI_ALG_HASH | current_hash_alg )

Compute policy bound to the content of an NV index.

The value used for comparison, the compare operation and an offset for the NV index are part of the policy.

Parameters

  [in] | policy | The policy with the expected values used for comparison.
  [in,out] | current_digest | The digest list which has to be updated.
  [in] | current_hash_alg | The hash algorithm used for the policy computation.

Return values

  TSS2_RC_SUCCESS | on success.
  TSS2_FAPI_RC_GENERAL_FAILURE | if an internal error occurred.
  TSS2_FAPI_RC_BAD_REFERENCE | a invalid null pointer is passed.
  TSS2_FAPI_RC_MEMORY | if not enough memory can be allocated.
  TSS2_FAPI_RC_BAD_VALUE | if an invalid value was passed into the function.

## ifapi_calculate_policy_nv_written()

TSS2_RC ifapi_calculate_policy_nv_written | ( | TPMS_POLICYNVWRITTEN * | policy,
|  | TPML_DIGEST_VALUES * | current_digest,
|  | TPMI_ALG_HASH | current_hash_alg )

Compute policy bound to bound to the TPMA_NV_WRITTEN attributes.

The expected value of the NV written attribute is part of the policy.

Parameters

  [in] | policy | The policy with the expected attribute value.
  [in,out] | current_digest | The digest list which has to be updated.
  [in] | current_hash_alg | The hash algorithm used for the policy computation.

Return values

  TSS2_RC_SUCCESS | on success.
  TSS2_FAPI_RC_BAD_VALUE | if an invalid value was passed into the function.
  TSS2_FAPI_RC_GENERAL_FAILURE | if an internal error occurred.
  TSS2_FAPI_RC_BAD_REFERENCE | a invalid null pointer is passed.
  TSS2_FAPI_RC_MEMORY | if not enough memory can be allocated.

## ifapi_calculate_policy_or()

TSS2_RC ifapi_calculate_policy_or | ( | TPMS_POLICYOR * | policyOr,
|  | TPML_DIGEST_VALUES * | current_digest,
|  | TPMI_ALG_HASH | hash_alg,
|  | size_t | hash_size,
|  | size_t | digest_idx )

Compute a list of policies to enable authorization options.

First the policy digest will be computed for every branch. After that the policy digest will be reset to zero and extended by the list of computed policy digests of the branches.

Parameters

  [in] | policyOr | The policy with the possible policy branches.
  [in,out] | current_digest | The digest list which has to be updated.
  [in] | hash_alg | The hash algorithm used for the policy computation.
  [in] | hash_size | The size of the policy digest.
  [in] | digest_idx | The index of the current policy in the passed digest list.

Return values

  TSS2_RC_SUCCESS | on success.
  TSS2_FAPI_RC_BAD_VALUE | if an invalid value was passed into the function.
  TSS2_FAPI_RC_GENERAL_FAILURE | if an internal error occurred.
  TSS2_FAPI_RC_BAD_REFERENCE | a invalid null pointer is passed.
  TSS2_FAPI_RC_MEMORY | if not enough memory can be allocated.

## ifapi_calculate_policy_secret()

TSS2_RC ifapi_calculate_policy_secret | ( | TPMS_POLICYSECRET * | policy,
|  | TPML_DIGEST_VALUES * | current_digest,
|  | TPMI_ALG_HASH | current_hash_alg )

Calculate a policy for adding secret-based authorization.

During execution proving the knowledge of the secrect auth value of a certain object is required. The name of this object and a policy reference is used for policy calculation. Based on the command code, the object name and a policy reference the new policy digest is computed by the function calculate_policy_key_param().

Parameters

  [in] | policy | The policy with the object name of the object to be authorized and the policy reference.
  [in,out] | current_digest | The digest list which has to be updated.
  [in] | current_hash_alg | The hash algorithm used for the policy computation.

Return values

  TSS2_RC_SUCCESS | on success.
  TSS2_FAPI_RC_BAD_VALUE | if an invalid value was passed into the function.
  TSS2_FAPI_RC_GENERAL_FAILURE | if an internal error occurred.
  TSS2_FAPI_RC_BAD_REFERENCE | a invalid null pointer is passed.
  TSS2_FAPI_RC_MEMORY | if not enough memory can be allocated.

## ifapi_calculate_policy_signed()

TSS2_RC ifapi_calculate_policy_signed | ( | TPMS_POLICYSIGNED * | policy,
|  | TPML_DIGEST_VALUES * | current_digest,
|  | TPMI_ALG_HASH | current_hash_alg )

Calculate a policy digest for a signed policy.

Based on the command code, the public key, and the policy reference stored in the policy the new policy digest is computed by the function calculate_policy_key_param().

Parameters

  [in] | policy | The policy with the public key and the policy reference.
  [in,out] | current_digest | The digest list which has to be updated.
  [in] | current_hash_alg | The hash algorithm used for the policy computation.

Return values

  TSS2_RC_SUCCESS | on success.
  TSS2_FAPI_RC_BAD_VALUE | if an invalid value was passed into the function.
  TSS2_FAPI_RC_GENERAL_FAILURE | if an internal error occurred.
  TSS2_FAPI_RC_BAD_REFERENCE | a invalid null pointer is passed.
  TSS2_FAPI_RC_MEMORY | if not enough memory can be allocated.

## ifapi_calculate_simple_policy()

TSS2_RC ifapi_calculate_simple_policy | ( | TPM2_CC | command_code1,
|  | TPM2_CC | command_code2,
|  | TPML_DIGEST_VALUES * | current_digest,
|  | TPMI_ALG_HASH | current_hash_alg )

Update policy if only the command codes are used.

Some simple policies use onle one or two command codes for policy calculation.

Parameters

  [in] | command_code1 | The first command code for policy extension. Can be NULL.
  [in] | command_code2 | The second command code for policy extension. Can be NULL.
  [in,out] | current_digest | The digest list which has to be updated.
  [in] | current_hash_alg | The hash algorithm used for the policy computation.

Return values

  TSS2_RC_SUCCESS | on success.
  TSS2_FAPI_RC_BAD_VALUE | if an invalid value was passed into the function.
  TSS2_FAPI_RC_GENERAL_FAILURE | if an internal error occurred.
  TSS2_FAPI_RC_BAD_REFERENCE | a invalid null pointer is passed.
  TSS2_FAPI_RC_MEMORY | if not enough memory can be allocated.

## ifapi_compute_policy_pcr()

TSS2_RC ifapi_compute_policy_pcr | ( | TPMS_POLICYPCR * | policy,
|  | TPML_DIGEST_VALUES * | current_digest,
|  | TPMI_ALG_HASH | current_hash_alg )

Calculate a policy digest for a certain PCR selection.

From a PCR list the list of PCR values and the corresponding PCR digest is computed. The passed policy digest will be extended with this data and also with the policy command code.

Parameters

  [in] | policy | The policy with the list of selected PCRs.
  [in,out] | current_digest | The digest list which has to be updated.
  [in] | current_hash_alg | The hash algorithm used for the policy computation.

Return values

  TSS2_RC_SUCCESS | on success.
  TSS2_FAPI_RC_BAD_VALUE | if an invalid value was passed into the function.
  TSS2_FAPI_RC_GENERAL_FAILURE | if an internal error occurred.
  TSS2_FAPI_RC_BAD_REFERENCE | a invalid null pointer is passed.
  TSS2_FAPI_RC_MEMORY | if not enough memory can be allocated.