.. Copyright

   Copyright 2023 United States Government

   Licensed under the Apache License, Version 2.0 (the "License");
   you may not use this file except in compliance with the License.
   You may obtain a copy of the License at

       http://www.apache.org/licenses/LICENSE-2.0

   Unless required by applicable law or agreed to in writing, software
   distributed under the License is distributed on an "AS IS" BASIS,
   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
   See the License for the specific language governing permissions and
   limitations under the License.

.. currentmodule:: maat

APBs are responsible for understanding the requirements of a particular attestation scenario as defined by the Measurement Specification, selecting an appropriate sequence of ASPs to execute to satisfy the scenario, and collecting the results generated by individual ASPs into a cohesive whole that is consumable by the remote party. Dually, an APB may implement an appraisal component that evaluates evidence by invoking a sequence of ASPs to verify properties of the measurement data and synthesizing a final report indicating the overall determination of integrity along with any required supporting evidence. Protocols may be implemented either as two separate APBs, one for the attester and one for the appraiser, or as a single APB that determines which role to execute based on context provided by the AM. We have implemented both options, but favor the former as it leads to simpler implementations and an unambiguous mapping between an APB’s UUID and its behavior.

APBs rely on ASPs and/or other APBs to produce or evaluate measurements. Upon registration with the AM, each APB must provide an XML metadata file that statically lists supported Measurement Specifications and defines the set of ASPs and sub-APBs that may be required to execute the protocol. With this information, the AM can ensure that all dependencies can be satisfied, and can invalidate a protocol if any of its dependencies are de-registered. Maat includes an optional library that defines default mechanisms for parsing measurement specifications, spawning ASPs, and managing and serializing evidence.
We separate evidence collection and collation into ASP and APB functionality respectively to allow for greater reuse of components, to support finer-grained policy decisions, and to enable more granular access control decisions to isolate pieces of M&A functionality. However, Maat is flexible and can accommodate “fat” APBs that collect evidence directly or “fat” ASPs that collect multiple types of data. It is up to the negotiation peer to decide which APBs it will accept evidence from.


Measurement Specifications
--------------------------

Measurement Specifications define exactly what evidence the requester requires for a specific scenario. Separating the evidence requirements from the protocol needed to collect and transmit evidence (APBs) allows the construction of generic APBs that can be re-used for multiple attestation scenarios. Like APBs, Measurement Specifications are registered with the AM and are identified by a well-known UUID. Once a Copland phrase is negotiated, an APB that implements the selected Copland phrase is launched using the correct Measurement Specification for the phrase as input.

Measurement Specifications contain as much information as necessary to define the type of evidence required. Implementations may define a specification language that provides rich syntax for defining complex evidence relationships. Any such language will need to be understood by the APBs which must parse the specification into a series of actionable instructions. Maat includes an implementation of one such language as part of the optional APB library. Specifications in this language define a set of measurement variables that identify particular data requiring measurement, and measurement instructions that define what measurements are required for variables of a given type. During evaluation, measurement instructions may introduce new variables that must be measured. The complete measurement requires recursively evaluating these measurement obligations until no new variables are introduced.


For more information about modifying measurement specifications, go to
:ref:`Modifying Measurement Specification <measSpec>`

APBs Currently Available
########################

.. table:: Sample APB Table

  ============================= ==============================================================
  Name                          Description
  ============================= ==============================================================
  appraiser                     Initial implementation of an appraiser APB
  complex_attestation           Combined measurements of two different platforms
  hashdir                       Returns a sha1 hash of all files in a directory
  hashfile                      Returns a sha1 hash of a file
  kim                           Placeholder for kernel integrity measurement
  layered_appraiser             Appraisal of layered measurement
  layered_att                   Layered measurement of a multi privilege-level platform
  no_op                         Forward measurement with no processing
  passport_userspace_appraiser  Appraise a userspace measurement and create a signed passport
  process_measurement           SHA1 hash open files of process
  request_passport              Requests a passport from a third party appraiser
  userspace                     Userspace measurement
  userspace_appraiser           Basic appraisal of userspace measurement
  ============================= ==============================================================

