Policies

Policies allow tenants to perform additional evaluation of attestation evidence that is not covered by a particular attestation scheme. The policy can be used to override the overall attestation status and/or the trust vector values in the result (e.g. rejecting a token considered valid by the scheme if the more stringent constraints described in the policy are not met).

The syntax of the policy depends on the agent used to evaluate it. At the moment, the following policy agents are supported:

"opa" -- Open Policy Agent is a flexible, generic Open Source policy agent that utilizes its own policy language called Rego. See README.opa.md.

Configuration

Configuration for the policy agent is specified under top-level entry po-agent.

po-agent configuration

The following policy agent configuration directives are currently supported:

• backend: specified which policy backend will be used. Currently supported backends: opa.
• <backend name>: an entry with the name of a backend is used to specify configuration for that backend. Multiple such entries may exist in a single config, but only the one for the backend specified by the backend directive will be used.

opa backend configuration

Currently, opa backend does not support any configuration.

Policy Identification

There are three different ways of identifying a policy:

appraisal policy ID

This is an identifier used in the attestation result as defined by EAR Internet draft. Note that in this case, "policy" is used in the sense of "Appraisal Policy for Evidence" as per RATS architecture. In Veraison, this encompasses both, the scheme, and the policy applied from the policy store by a policy engine.

An appraisal policy ID is a URI with the scheme policy followed by a rootless path indicating the (RATS) policy using which the appraisal has been generated. The first segment of the path is the name of the scheme used to create the appraisal. The second segment, if present, is the individual policy ID (see below) of the policy that has been applied to the appraisal created by the scheme.

For example:

• policy:TPM_ENACTTRUST: the appraisal has been created using "TPM_ENACTTRUST" scheme, with no additional policy applied.
• policy:PSA_IOT/340d22f7-9eda-499f-9aa2-5af295d6d812: the appraisal has been created using "PSA_IOT" scheme and has subsequently been updated by the policy with unique policy ID "ae19cc27-a449-1fb8-6c10-00f47ad1c55c".

Potential future extensions

These indicate potential future enhancements, and are not supported by the current implementation.

Cascading policies

In the future we may support applying multiple individual policies to a single appraisal. In that case, each path segment after the first (the scheme) is the individual policy ID of a policy that has been applied. The ordering of the segments matches the order in which the policies were applied.

For example:

• policy:PSA_IOT/340d22f7-9eda-499f-9aa2-5af295d6d812/ae19cc27-a449-1fb8-6c10-00f47ad1c55c: the appraisal has been created using "PSA_IOT" scheme, it was then updated by a policy with the individual policy id 340d22f7-9eda-499f-9aa2-5af295d6d812, followed by a policy with the individual policy ID ae19cc27-a449-1fb8-6c10-00f47ad1c55c.

policy store key

Policies are stored, retrieved from, and updated in the policy store using a key. The key is a string consisting of the tenant id, scheme, and policy name delimited by colons.

For example:

• 0:PSA_IOT:opa: the key for tenant "0"'s policy for scheme "PSA_IOT" with name "opa".

policy name

The name exists to support cascading policies in the future (see above). At the moment, as there is only one active policy allowed per appraisal, the name is not necessary and is always set to the name of the policy engine ("opa"). While this unnecessarily increases the key size and is somewhat wasteful, given that the number of the policies a typical deployment is expected to be, at most, in the hundreds, and the relatively negligible overhead compared to the size of the policies themselves, this is not deemed to be a major concern.

individual policy ID

The individual policy ID identifies the specific policy that was applied to an appraisal. It forms a component of the appraisal policy ID (which also includes the scheme, and possibly, in the future, individual IDs from multiple policies). It differs from the policy store key in that it also incorporates versioning information.

The individual policy id is the UUID of the specific policy instance.

For example: 340d22f7-9eda-499f-9aa2-5af295d6d812

Writing Policies

Please see the OPA official documentation for information on how to write Rego policies. This section describes what is necessary to implement a valid Veraison policy, and assumes a general familiarity with Rego.

Package declaration

Your policy should specify policy as the package.

package policy

Evaluation Data

Data to be evaluated is defined as the following variables in the policy package:

evidence contains the JSON representation of proto.EvidenceContext.Evidence structure. This is the scheme-specific values extracted from the attestation token.

endorsements is an array of endorsement JSON objects. Their structure is scheme-specific.

result is a JSON object representing proto.AttestationResult that was generated by the scheme.

scheme is the name of the attestation scheme.

Rules

You can update the attestation result by defining one or more of the following rules:

• status
• hw_authenticity
• sw_integrity
• sw_up_to_dateness
• config_integrity
• runtime_integrity
• certification_status

The first overwrites the overall attestation result status. The subsequent rules overwrite the corresponding entries in the trust vector.

The rules must be defined such that they produce the string "SUCCESS" if the conditions have been met, and the string "FAILURE" otherwise.

As various versions are often represented using Semantic Versioning, policy package provides a utility function, semver_cmp to aid in their comparison (note: currently, pre-release suffixes are not supported).

For example:

sw_integrity = "SUCCESS" {
    # note: This is an example. The evidence entries do not correspond to any
    #       actual scheme.
    evidence["application-hash"] == "h0KPxSKAPTEGXnvOPPA/5HUJZjHl4Hu9eg/eYMTPJcc="
    evidence["firmware-hash"] == "h0KPxSKAPTEGXnvOPPA/5HUJZjHl4Hu9eg/eYMTPJcc="
    semver_cmp(evidence["firmware-version"], "1.2.0") >= 0
} else = "FAILURE"

Dealing With Multiple Attestation Schemes

If you expect your policy to be applied to inputs from multiple attestation schemes, you differentiate between them using the format variable defined by the policy package. For example you can define rules for each scheme, and then alias the generic rules above to one of them based on the value of the format variable. For example:

sw_up_to_dateness = psa_sw_up_to_dateness { format == "PSA_IOT" }
             else = enacttrust_sw_up_to_dateness { format == "TPM_ENACTTRUST" }

psa_sw_up_to_dateness = "SUCCESS" {
    # ...
} else = "FAILURE"

enacttrust_sw_up_to_dateness = "SUCCESS" {
    # ...
} else = "FAILURE"

Example Policy

This is a example of a policy that sets the SoftwareUpToDateness value in the trust vector for PSA_IOT and TPM_ENACTTRUST schemes (neither scheme has built-in definition for software up-to-dateness, and so that entry is undefined in the results generated by the schemes).

package policy

# Use the psa_sw_up_to_dateness rules iff the attestation format is PSA_IOT, and
# to enacttrust_sw_up_to_dateness iff the format is TPM_ENACTTRUST, otherwise,
# sw_up_to_dateness will remain undefined.
sw_up_to_dateness = psa_sw_up_to_dateness { format == "PSA_IOT" }
             else = enacttrust_sw_up_to_dateness { format == "TPM_ENACTTRUST" }

# This sets sw-up-to-dateness trust vector value to success iff BL version is
# 3.5 or greater, and to failure otherwise.
psa_sw_up_to_dateness = "SUCCESS" {
  # there exisists some i such that...
  some i
  # ...the i'th software component has type "BL", and...
  evidence["psa-software-components"][i]["measurement-type"] == "BL"

  # ...the version of this component is greater or equal to 3.5.
  # (semver_cmp is defined by the policy package. It returns 1 if the first
  # parameter is greater than the second, -1 if it is less than the second,
  # and 0 if they are equal.)
  semver_cmp(evidence["psa-software-components"][i].version, "3.5") >= 0
} else = "FAILURE" # unless the above condition is met, return "FAILURE"

# Unlike the PSA token, the EnactTrust token does not include information about
# multiple sofware componets and instead has a single "firmware" entry.
enacttrust_sw_up_to_dateness = "SUCCESS" {
  evidence["firmware"] >= 8
} else = "FAILURE"

Managing Policies

Policies can be added to, and later managed in, the service using pocli command line tool.