Complex Attestation 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

.. _complex_attestation_tutorial:


Introduction
============

These instructions give you the steps to set up and perform a multi-realm
complex attestation demonstration, with a test client requesting a
kernel runtime and userspace measurement (in that order) from a second set of
VMs, one representing an instance of Maat running in userspace, and the second
representing an instance of Maat running in a secure enclave in the first VM.

Setup
======

In order to install Maat, follow the directions that are located in the
:ref:`Quick Start Guide <quick_start>` and ensure that Maat is working correctly
with the example scenarios outlined in the
:ref:`Basic Tutorial <basic_tutorial>`.

Complex-Attestation Demonstration
=================================

This demo involves two AMs on two VMs:
- AM_1 : USM Target (in VM 1)
- AM_2 : KIM Target (in VM 2)

You may also wish to have a seperate VM (VM 0) which triggers the measurement,
although this can be done from either VM 1 or VM 2. A seperate VM adds to the
verisimilitude of the demo, but the either of the latter is more practical as it
requires fewer VMs.

Every measurement request received by the Maat Attestation Manager (AM) triggers
a negotiation to determine the appropriate Copland phrase to handle the request.
When the request is asking the current AM to perform and appraise a measurement,
the AM will negotiate with itself to determine if the requested measurement is
included in its policy. To better explain what is happening in the
demonstration, we will show the negotiations of, for example, AM_1 with itself
in the illustrations below as AM_1_0 and AM_1_1.

Clone the VM you created in the setup step in order to get the proper number of
VMs.

Explanation of Demo
-------------------
The demo represents the execution of the following Copland phrase:

          .. code-block:: none

              @_1(@_1(@_2((KIM runtime_meas)->SIG)-<-(USM mtab)))

Here's what will happen in the demo:

1. The requester sends a request to AM_1 running in VM_1 to perform a "verified userspace" measurement of itself.

          .. image:: images/complex_attestation_request.png
             :scale: 30
             :align: center

2. AM_1 triggers a negotiation with itself in order to determine if it is willing and able to take the measurement represented by the phrase. This is where the AM_1_0 and AM_1_1 notation will introduced. AM_1_0 refers to the thread acting as an initiator for the phrase while AM_1_1 acts as the responder.

          .. image:: images/complex_am10_nego_am11.png
             :scale: 30
             :align: center

   AM_1 negotiates with itself over the following phrase:

          .. code-block:: none

   	          @_1(@_2((KIM runtime_meas)->SIG)-<-(USM mtab))

3. After deciding that the phrase is satisfatory, AM_1_0 forks the no-op APB to forward the completed measurement to the requester, while AM_1_1 launches the complex attestation APB to take the measurement.

          .. image:: images/complex_am11_complex_att.png
             :scale: 30
             :align: center

4. Since the Copland phrase that AM_1_1 is tasked with executing begins with AM_2, the complex attestation APB launches the send_request ASP, in order to request a negotiation between AM_1_1 and AM_2 over the following Copland phrase:

          .. code-block:: none

              @_2((KIM runtime_meas)->SIG)

   In order to get a kernel measurement of AM_2:

          .. image:: images/complex_am11_complex_att.png
             :scale: 30
             :align: center

5. AM_2 spawns a KIM APB and ASP to measure the kernel in VM_2 while AM_1_1 spawns the no-op APB to receive and forward the measurement to the send request ASP.

   It should be noted here, again, that for the purposes of this demo, VM_2 is representing a secure area of VM_1. The measurement of the kernel should give the requestor a sense of the integrity of the realm in which AM_1 is running. In short, in a real implementation, AM_2 should be measuring the kernel of AM_1.

          .. image:: images/complex_am2_kim.png
             :scale: 30
             :align: center

6. The results of the KIM measurement are sent from the KIM APB in VM_2 to the forwarding APB forked from AM_1_1.

   At this point, AM_2 plays no further role in the scenario

          .. image:: images/complex_am2_ret_kim_am11.png
             :scale: 30
             :align: center

7. The no-op APB bundles the measurement into a response contract, and forwards the contract to the send request ASP.

          .. image:: images/complex_am11_nop_to_send.png
             :scale: 30
             :align: center

8. The complex attestation APB on AM_1_1 invokes the required ASPs to take the userspace measurement specified by the phrase (USM mtab), which, in this case, is a mtab userspace measurement.

          .. image:: images/complex_am11_usm.png
             :scale: 30
             :align: center

   At this point, the complex attestation APB has executed all of the required measurements.

9. The APB invokes the serialize ASP to serialize the userspace measurement. It then spawns the merge ASP, which concatenates the KIM measurement and the serialized userspace measurement.

   These two measurements together represent the evidence requested with the Copland phrase:

         .. code-block:: none

   	         @_1(@_2((KIM runtime_meas)->SIG)-<-(USM mtab))

         .. image:: images/complex_am11_merge_meas.png
             :scale: 30
             :align: center

10. The complex attestation APB on AM_1_1 then invokes all of the ASPs required to sign and send the measurement to AM_1_0 (these are not all drawn out for the sake of brevity). Each ASP takes the results of the previous measurement (starting with the result of the merge ASP in (9)) and forward their result to the next ASP through pipes set up in the APB. The relevant ASPS include the:

        * Compress ASP - compresses the serialized measurement buffer
        * Create Contract ASP - creates the measurement contract which holds the measurement
        * Encrypt ASP - encrypts the measurement and contract
        * Send ASP - sends the encrypted buffer to the intended recipient

        .. image:: images/complex_am11_send_meas_am10.png
           :scale: 30
           :align: center


11. The no-op APB spawned by AM_1_0 receives the mtab measurement from AM_1_1,
    bundles it in a response contract, and forwards it to the requester.

    At this point, the scenario is complete.

        .. image:: images/complex_am10_forward_rely.png
           :scale: 30
           :align: center

Process
-------

This demo uses 3 seperate VMs to simulate the interaction in a more realistic manner.

The demo setup will look as follows, with the test client being spawned on the distinct VM_0:

Directions to set up the VMs are located in the :ref:`Setup Multirealms Guide <setup_multirealms>`.

        .. image:: images/complex_full_setup.png
           :scale: 30
           :align: center

On VM_0:

   Set IP to 192.168.0.5 and open port 2342

On VM_1:

   Set IP to 192.168.0.10 and open port 2343

On VM_2:

   Set IP to 192.168.0.7 and open port 2342

The complex attestation use case will rely upon a backend database on VM_1 with the
IP address and port information for VM_1 and VM_2. This is intended to simulate
an environment in which machines are registed with the appraiser in some fashion
and the appraiser can use this information about other AMs in order to carry out
functionality within APBs. A simple XML example file is provided with Maat,
and can be placed where Maat will use it with the following command:

        .. code-block:: none

            sudo cp demo/ancillary_files/places.xml /opt/maat/etc/maat

To start the scenario, you must start AM_0 and AM_1. To do so, run

On VM_1:

        .. code-block:: none

            sudo LIBMAAT_LOG_SYSLOG=0 /opt/maat/bin/attestmgr -i 192.168.0.10:2343 \
                -C /opt/maat/etc/maat/minimal-am-config.xml -m COPLAND \
                -s /opt/maat/share/maat/selector-configurations/complex-att-selector.xml

On VM_2:

       .. code-block:: none

            sudo LIBMAAT_LOG_SYSLOG=0 /opt/maat/bin/attestmgr -i 192.168.0.7:2342 \
                -C /opt/maat/etc/maat/minimal-am-config.xml -m COPLAND \
                -s /opt/maat/share/maat/selector-configurations/complex-att-selector.xml

To take the measurement, you must invoke the test client on VM_0 using the following:

      .. code-block:: none

          /opt/maat/bin/test_client -l 192.168.0.10 -t 192.168.0.10 -a 2343 \
            -p 2343 -r complex-attestation

The expected output at the test client is similar to the following (with the
measurement, signature, and certificate info omitted for brevity):

      .. code-block:: xml

        <contract version="2.0" type="response"><target type="host-port">192.168.0.10</target><resource>complex-attestation</resource><result>UNKN</result><data><entry><key>No-op appraisal</key><value>
        (...)
        </value></entry></data><AttestationCredential fingerprint="A5:2C:D0:4E:1A:75:1F:7D:60:9F:2B:A6:D1:7D:EA:53:BD:42:B7:FD">
        (...)
        </AttestationCredential><signature><signedinfo><canonicalizationmethod algorithm="XML C14N 1.0"/><signaturemethod algorithm="RSA"/><digestmethod algorithm="SHA-1"/></signedinfo><signaturevalue>
        (...)
        </signaturevalue><keyinfo>A5:2C:D0:4E:1A:75:1F:7D:60:9F:2B:A6:D1:7D:EA:53:BD:42:B7:FD</keyinfo></signature></contract>

The 'UNKN' result indicates that the no-op appraisal was performed in this use
case (meaning that the measurement was packaged inside the response contract
without appraisal). The forthcoming 'complex appraisal' use case will cover
appraisal of this measurement.
