Basic Maat Tutorial ******************* .. 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 .. _basic_tutorial: Introduction ============ These instructions will help you to get started taking userspace measurements. Setup ===== Follow the :ref:`Quick Start Guide ` to install the Maat dependencies and to build Maat. This tutorial will use the demo credentials provided with Maat. *DO NOT USE DEMO CREDENTIALS IN A REAL DEPLOYMENT* Copy the demo credentials to the appropriate install directory with: .. code-block:: bash cd ~/maat/demo/credentials sudo cp client.key client.pem server.key server.pem \ /opt/maat/etc/maat/credentials/ If you are running with TPM2.0 enabled, you will also need to copy the demo credentials used by TPM2.0. : .. code-block:: bash sudo cp ak.ctx akpub.pem /opt/maat/etc/maat/credentials/ If these files don't exist, refer to ../../lib/util/tpm2/README.md for information on how to create them. If you are running with Maat's SELinux policy loaded, you will have to reset the security context of the files you just copied over with: .. code-block:: bash sudo restorecon -r /opt/maat/ You may use different credentials in this tutorial by editing your attestation manager configuration as described in the :ref:`Quick Start guide`. The instructions provided in these demonstrations also assume that Maat is installed in `/opt/maat`, as described in the Quick Start guide. If you installed in a different directory, please modify commands accordingly. Demonstrations ============== The Maat attestation manager (AM) is capable of acting as both an appraiser and an attester, depending on the current scenario taking place. In these demonstrations, we will have two instances of the AM running simultaneously on the same machine. A Test Client will trigger one AM to take a specific measurement of the second AM. For these demos, we will be using the minimal attestation manager (`attestmgr`) config file (`minimal-am-config.xml`) to set many of these arguments, and will be passing the remainder via the command line. The attestmgr configuration file used in this demo gives the AM the paths to various components needed for execution, and instructs the AM to use the `userspace-selector.xml` selector policy. This selector policy selects Copland phrases based on the resource passed to the appraiser AM by the requestor. These demos use attestation managers listening on ports 2342 and 2343. If you're using the Maat SELinux policy, these ports need to be given the `attestmgr_port_t` type in order for the attestation manager to be able to bind to them. If you haven't already done so, add these ports to SELinux management with: .. code-block:: bash sudo semanage port -a -t attestmgr_port_t -p tcp 2342 sudo semanage port -a -t attestmgr_port_t -p tcp 2343 Demo 1 - Package Inventory Measurement --------------------------------------- For ease of demonstration, it is recommended that you open three terminals, and designate them "Attester", "Appraiser", and "Test Client". If you are running with TPM2.0 enabled, you will need additional arguments to indicate that you want to sign and verify with TPM2.0. Add the arguments in the Appraiser and Attester terminals below: .. code-block:: bash -T 1 -v 1 For the purposes of demonstration, we will need to generate a whitelist of packages installed on the host. For hosts using an RPM based packaging system (RHEL, CentOS, etc.), you can use the following command to generate the whitelist and place it into the proper file system location: .. code-block:: bash sudo rpm -qa --qf "%{NAME}\n" | sudo tee -a /opt/maat/share/maat/asps/packages.whitelist For hosts using a dpkg based packaging system, you can use the following command to generate the whitelist: .. code-block:: bash dpkg-query -W | cut -f1 | sudo tee -a /opt/maat/share/maat/asps/packages.whitelist In the Appraiser Terminal, run .. code-block:: bash sudo /opt/maat/bin/attestmgr -i 127.0.0.1:2342 -u /tmp/app.sock \ -C /opt/maat/etc/maat/minimal-am-config.xml in the Attester Terminal, run .. code-block:: bash sudo /opt/maat/bin/attestmgr -i 127.0.0.1:2343 -u /tmp/att.sock \ -C /opt/maat/etc/maat/minimal-am-config.xml and in the Test Client Terminal, run .. code-block:: bash /opt/maat/bin/test_client -l localhost -a 2342 -t localhost -p 2343 \ -r packages This measurement may take a few minutes. During this time, you should see activity in the Attester Terminal as various ASPs take measurements. After the measurement is appraised, the Test Client will receive the result of the attestation, which will be printed to STDOUT in the Test Client Terminal. Look for `PASS` near the beginning of the test client output, this means the appraisal passed. **What just happened?** The test client requested the appraiser AM to perform an appraisal of the measurement of the attester AM's resource 'packages'. This triggered the appraiser to consult its selector policy and send an initial contract to the attester. The attester returned a modified contract (also after consulting its selector policy), and the appraiser finally chose a Copland phrase based on the the resource requested by the test client. The selected Copland phrase was mapped to an appropriate APB and Measurement Specification, which was then executed. (here, the resource 'packages' resulted in the execution of the userspace APB and the userspace-packages measurement specification). See the description of userspace_packages_mspec.xml to learn the internals of how this selection dictated what the userspace APB should measure. At a high level: the measurement specification instructed the userspace APB to, 1. take a 'system' measurement to determine what type of operating system the target machine is running 2. take an inventory of all of the software packages installed on the system 3. take detailed measurement of each of the software packages found in step 2 For (much) more verbose output, set the environment variable `LIBMAAT_LOG_SYSLOG` to `0` for the appraiser and the attester. This will re-direct output to the terminal. During various measurements, you may need to set this variable to see output for the appraiser execution. Example: .. code-block:: bash sudo LIBMAAT_LOG_SYSLOG=0 /opt/maat/bin/attestmgr -i 127.0.0.1:2342 \ -u /tmp/app.sock -C /opt/maat/etc/maat/minimal-am-config.xml The verbosity can be further controlled by the environment variable 'LIBMAAT_DEBUG_LEVEL'. More verbosity is achieved by increasing this value. See maat_environment_variables.txt for more information. Demo 2 - Appraiser vs. Attester ------------------------------- Notice that there is nothing that specifies that the Appraiser AM must be the appraiser and that the Attester AM must be the attester. In fact, they are interchangeable and the same AM can act as either, or even both. The AM that recieves a request takes on the role of Appraiser, and the AM that recieves an initial contract takes on the role of Attester. To demonstrate this, keep your AM's running (or restart them with the instructions from demo 1) and run the test client with .. code-block:: bash /opt/maat/bin/test_client -l localhost -a 2343 -t localhost -p 2342 \ -r packages Notice, the port numbers passed to -a and -p are swapped. The same attestation took place, but the appraiser and the atteser AMs exchanged the roles they had in demo 1. This is because the ports passed to the test client were interchanged, and the test client requested an appraisal from the opposite AM. To further this point, try running test client with both ports set to `2343`: .. code-block:: bash /opt/maat/bin/test_client -l localhost -a 2343 -t localhost -p 2343 \ -r packages This time only one AM was activated, and it played the role of both the attester and the appraiser. The rest of the demos will treat the two AMs as the Appraiser and the Attester, respectively, just as in the first demo. But keep in mind that this setup is for clarity of the demo, not out of necessity. Demo 3 - Processes Measurement ------------------------------ The Appraiser and Attester should still be running in their respective terminals. If not, restart them with the commands provided in Demo 1. In the Test Client Terminal, run .. code-block:: bash /opt/maat/bin/test_client -l localhost -a 2342 -t localhost -p 2343 \ -r processes Again, the output in the Test Client Terminal is the result of the attestation. If the appraisal passed, you should see `PASS` near the beginning of the output. **What just happened?** This time the test client requested a measurement of the attester's resource 'processes'. This resulted in the selection of a different Copland phrase and the execution of the userspace_apb with the userspace-processes measurement specification. See the description of userspace_processes_mspec.xml to learn what this selection measured. This measurement should take more time than the 'packages' measurement described above (ancedotally > 10 minutes) because the measurement specification used this time instructed the userspace APB to do much more: 1. take a 'system' measurement to determine what type of operating system the target machine is running 2. take an inventory and gather details of all of the processes running on the system 3. gather details on the memory mappings of all of the root-owned processes found in step 2 4. take a hash of all of the files currently open by root-owned processes found in step 2 5. take detailed measurement of each of the software packages associated with files examined in step 3 or 4 Demo 4 ------ In summary, the test client requests a measurement of a specific resource, the selector policy is consulted, and a Copland phrase is selected (then mapped to an APB-measurement specification pair). The selector policy used in these demonstrations is largely guided by the resource requested by the test client. The selector policy's other possible resources and the resulting Copland terms can be explored by searching for ` SIG) | userspace APB | userspace_packages_mspec.xml | +-------------+--------------------------------------------+---------------+--------------------------------+ | processes | ((USM processes) -> SIG) | userspace APB | userspace_processes_mspec.xml | +-------------+--------------------------------------------+---------------+--------------------------------+ | hashfiles | ((USM hashfiles) -> SIG) | userspace APB | userspace_hashfiles_mspec.xml | +-------------+--------------------------------------------+---------------+--------------------------------+ | mtab | ((USM mtab) -> SIG) | userspace APB | userspace_mtab_mspec.xml | +-------------+--------------------------------------------+---------------+--------------------------------+ | got_measure | ((USM got) -> SIG) | userspace APB | got_measure_mspec.xml | +-------------+--------------------------------------------+---------------+--------------------------------+ | hashfile | ((USM hashfile file) -> SIG):file=/bin/ls" | hashfile APB | n/a | +-------------+--------------------------------------------+---------------+--------------------------------+ | userspace | ((USM full) -> SIG) | userspace APB | userspace_measurement_mspec.xml| +-------------+--------------------------------------------+---------------+--------------------------------+ Notice that the userspace APB is capable of utilizing different measurement specifications to fulfill multiple Copland phrases. The hashfile APB can only fulfill one Copland phrase, and so it doesn't require a measurement specification to guide its measurement. That last option is interesting: passing the resource `userspace` will result in the selection of the userspace_measurement_mspec.xml, which is a superset of all of the other measurements listed above. Try it out with: .. code-block:: bash /opt/maat/bin/test_client -l localhost -a 2342 -t localhost -p 2343 \ -r userspace Again, the output in the Test Client terminal is the result of the measurement, and you're looking for `PASS`. For a more complex demonstration of Maat's usage in a simulated multirealm environment, please continue to the :ref:`Multirealm Tutorial`. Alternatively, please see the :ref:`AM Configuration Guide` to explore how to configure the Maat AM for your particular use case. If you would like to set up a web-based UI for Maat instead of interacting with the Maat AM via the command line, please follow the instructions at :ref:`UI Tutorial`.