Understanding Contracts
************************

.. 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

.. |cp| raw:: latex

   \clearpage

Purpose and Intended Audience
==============================

This section will explain the different varieties of contracts
that Maat uses to perform an attestation.

The intended audience for this section is anyone that wants to
understand Maat contracts to better understand attestation results and
what was tested.

Contract Flow
=============

The Maat infrastructure uses a series of XML documents called
contracts to request, negotiate, and respond to attestations.  All
contracts share the root node type "<contract>" with an attribute
indicating the type of the contract. The message flow of an
attestation is as follows:

.. image:: images/contracts_flow.png
    :align: center

In the sequence diagram above:

  - The Requester sends a :ref:`request contract<RequestContract>` to the Appraiser
  - The Appraiser sends an :ref:`initial contract<InitialContract>` to the Attester
  - The Attester sends a :ref:`modified contract<ModifiedContract>` to the Appraiser
  - The Appraiser sends an :ref:`execute contract<ExecuteContract>` to the Attester
  - The actual attestation occurs, the Attester may send a :ref:`measurement contract<MeasurementContract>`
    to the Appraiser, or it may use a custom transmission to
    convey measurements.
  - The Appraiser sends a :ref:`response contract<ResponseContract>` to the Requester.

.. note::
    If at any step the Appraiser decides
    that the attestation on the target machine is not possible, the
    Appraiser will send a response contract back to the Requester
    indicating that an error occurred.

.. _RequestContract:

Request Contract
================

Used by a requester to request attestation of a
target. Generated by the libmaat_client library
function ``create_integrity_request()``.  The Appraiser uses the
information in the request contract (a) to determine its supported
Copland Phrases that can satisfy the requester's needs, and (b)
initiate a connection with the Attester's Attestation Manager.

Example:

.. code-block:: xml

        <contract version="2.0" type="request">
            <target type="host-port"/>10.0.0.2:2432</target>
            <!-- request a measurement of 10.0.0.2 on port 2432 -->
            <resource>ipsec</resource>
            <!-- allow access to the ipsec resource -->
            <nonce>NULL</nonce>
            <!-- carry the nonce value in the contract to be used for subsequent negotiations -->
            <tunnel>/tmp/tunnel.sock</tunnel>
            <!-- tunnel communications through this socket rather than connecting directly -->
        </contract>

.. _InitialContract:

Initial Contract
================

Sent from the appraiser AM to the (target) attester AM immediately
after the appraiser receives a request contract. The initial contract
contains a list of Copland Phrases called initial options (represented
as <option> nodes). From the appraiser's perspective, any of the options
listed can satisfy the attestation request.

The appraiser can sign contracts either with OpenSSL, or by using features
provided by a TPM. In either case, the appraiser includes its public
certificate in the initial contract, and uses the corresponding private key to
sign the contract (and all subsequent contracts). When using OpenSSL to sign a
contract, the signature protects the contract itself.  In the case of TPM, the
signature protects an enclosed TPM quote, which in turn contains a hash of the
contract, thereby protecting that contract. The signatures and quotes (if any)
are compatible with the XML Sig standard (http://www.w3.org/TR/xmldsig-core/),
although the standard's namespace is not used.


Example using OpenSSL signatures:

.. code-block:: xml

  <contract version="2.0" type="initial">
    <subcontract> <!-- There's only ever one subcontract -->
      <option>
        <!--
         ! each option node should have one value node as a child,
         ! which contains the candidate Copland phrase
         !-->
        <value name="APB_phrase">((USM full) -> SIG)</value>
      </option>
      ...
    </subcontract>
    <nonce>0542ebfe07ac3da972d23196e73330ef6eb2c1d4</nonce>
    <AttestationCredential fingerprint="BB:65:51:9E:4C:5F:18:D6:A7:CA:13:13:7F:5E:32:98:E1:4A:C1:15">
        <!-- PEM encoded certificate elided -->
        ...
    </AttestationCredential>
    <signature>
      <signedinfo>
        <canonicalizationmethod algorithm="XML C14N 1.0"/>
        <signaturemethod algorithm="RSA"/>
        <digestmethod algorithm="SHA-256"/>
      </signedinfo>
      <signaturevalue>
          <!-- base 64 encoded signature elided -->
          ...
      </signaturevalue>
      <keyinfo>BB:65:51:9E:4C:5F:18:D6:A7:CA:13:13:7F:5E:32:98:E1:4A:C1:15</keyinfo>
    </signature>
  </contract>


Example using TPM signatures:

.. code-block:: xml

  <contract version="2.0" type="initial">
    <subcontract> <!-- There's only ever one subcontract -->
      <option>
        <!--
         ! each option node should have one value node as a child,
         ! which contains the candidate Copland phrase
         !-->
        <value name="APB_phrase">((USM full) -> SIG)</value>
      </option>
      ...
    </subcontract>
    <nonce>0542ebfe07ac3da972d23196e73330ef6eb2c1d4</nonce>
    <AttestationCredential fingerprint="BB:65:51:9E:4C:5F:18:D6:A7:CA:13:13:7F:5E:32:98:E1:4A:C1:15">
        <!-- PEM encoded certificate elided -->
        ...
    </AttestationCredential>
    <signature>
      <signedinfo>
        <canonicalizationmethod algorithm="XML C14N 1.0"/>
        <signaturemethod algorithm="RSA"/>
        <digestmethod algorithm="SHA-256"/>
        <reference URI="#tpms_attest" />
      </signedinfo>
      <signaturevalue>
          <!-- base 64 encoded signature elided -->
          ...
      </signaturevalue>
      <keyinfo>BB:65:51:9E:4C:5F:18:D6:A7:CA:13:13:7F:5E:32:98:E1:4A:C1:15</keyinfo>
      <object id="tpms_attest">
          <!-- base 64 encoded quote elided -->
          ...
      </object>
    </signature>
  </contract>


.. _ModifiedContract:

Modified Contract
=================

Sent from the attester AM back to the appraiser AM in response to an
initial contract. The modified contract contains a list of Copland Phrases
that are acceptable to the attester. This list should be a subset (though
possibly reordered) of the list in the initial contract. The down select
should be based on the identity of the appraiser performing the evaluation.

The format of the modified contract is the same as that of the initial
contract with the following exceptions:

* The type attribute of the contract node is set to "modified"

* The certificate included is that of the attester (which generated the
  contract) rather than the appraiser

* The signature is made with the attester's private key

.. _ExecuteContract:

Execute Contract
================

Sent from the appraiser AM to the attester in response to a modified
contract as the final phase of contract negotiation. This contract
contains a single Copland Phrase chosen from the list provided by the
attester in the modified contract. After this contract is sent,
the attester is expected to spawn the selected APB to complete the
attestation.

The execute contract is the same format as the modified and initial contracts
with the following exceptions:

* The type attribute of the contract node is set to "execute"

* There is exactly one <option> node.

* No certificate is included (since both parties already have the other party's certificate).

* The nonce may be included twice

* The signature is performed by the appraiser using the appraiser's key pair

.. _MeasurementContract:

Measurement Contract
====================

Sent from the attester's APB to the appraiser's APB following the completion of
the attester's APB's measurement activities. This contract contains the
serialized measurement data produced to satisfy the agreed-upon measurement
specification. After this contract is sent, the attester's role is complete.

The libmaat-apb has API functions for generating and sending
measurement contracts. Measurement contracts are the "Maat native"
mechanism for transmitting measurement data to the appraiser.

The measurement contract follows the same structure as the previous
three contracts but adds a node with tag "measurement" to the "option"
node containing the measurement data. By default, the measurement data
is compressed, encrypted, and base-64 encoded (in that order) before
the contract is signed.

.. _ResponseContract:

Response Contract
=================

Sent from the appraiser's APB back to the original client that sent
the request contract. This contract includes a final evaluation
(PASS/FAIL) and a list of key/value pairs with any reporting data
required to satisfy the client (see :ref:`Appraisal and Reporting<AppraisalandReporting>`
for a detailed discussion of report data).

Example:

.. code-block:: xml

        <contract version="2.0" type="response">
             <target type="[type]">[identifier]</target>
             <resource>[resource]</resource>
             <result>[PASS|FAIL]</result>
             <data identifier="[key]">[value]</data>*
        </contract>



Contract Nodes Reference
========================

The following subsections give a complete list of the node types present in
the various contracts used by Maat.

.. rst-class:: html-toggle

Contract
--------

Tag Name:
        contract

Relevant Contracts:
        All

Description:
        Root node of all documents.

Attributes:
	* version - Required. Should be 2.0
	* type - Required. Must be one of "request", "initial", "modified", "execute", "measurement", "response"

Children:
	* target - Required iff type = request or reponse
	* resource - Required iff type = request or response
	* subcontract - Required iff type = initial, modified, execute, or measurement
	* nonce - Required iff type = initial, modified, execute, or measurement
	* AttestationCredential - Optional
	* signature - Optional
	* result - Required iff type = response
	* data - Zero or more iff type = response

|cp|

.. rst-class:: html-toggle

Target
------

Tag Name:
        target

Relevant Contracts:
        Request

Description:
        Identifies the target of the attestation. Text value should contain hostname:port, public key fingerprint, or MAC address in colon-separated hex notation depending on the type attribute.

        **NB:** if target type isn't host-port, then a tunnel node must be included to allow the AM to communicate with the target.

Attributes:
	* type must be one of "host-port", "credential", or "MAC Address"

Children:
	*none*

.. rst-class:: html-toggle

Resource
--------

Tag Name:
        resource

Relevant Contracts:
         Request

Description:
        Identifies the resource the target is attempting to access. Text value
        is a free-form identifier used by the selector to determine which
        Copland phrases are suitable for this attestation.

Attributes:
        *none*

Children:
        *none*


.. rst-class:: html-toggle

Tunnel
------

Tag Name:
        Tunnel

Relevant Contracts:
        Request

Description:
        Path to a UNIX domain socket used to tunnel connections to the
        target. Text value is the path to the socket. This node is required if
        the target type is not host-port.

Attributes:
        *none*

Children:
        *none*


.. rst-class:: html-toggle

Subcontract
-----------

Tag Name:
        subcontract

Relevant Contracts:
        Initial, Modified, Execute, Measurement

Description:
        Body of the contract

Attributes:
        *none*

Children:
	* option - zero or more


.. rst-class:: html-toggle

Nonce
-----

Tag Name:
        nonce

Relevant Contracts:
        Initial, Modified, Execute, Measurement

Description:
        Session nonce. Text content is the hexadecimal encoded nonce value.

Attributes:
        *none*

Children:
        *none*


.. rst-class:: html-toggle

AttestationCredential
---------------------

Tag Name:
        AttestationCredential

Relevant Contracts:
        Initial, Modified, Execute, Measurement

Description:
        Certificate for the public key used by the sender to sign contracts. Text content should contain a PEM encoded certificate.

Attributes:
	* fingerprint - the colon delimited hexadecimal encoded fingerprint of the certificate

Children:
        *none*


.. rst-class:: html-toggle

Signature
---------

Tag Name:
        signature

Relevant Contracts:
        Initial, Modified, Execute, Measurement

Description:
        W3C compatible XML signature block. See http://www.w3.org/TR/xmldsig-core/

Attributes:
        *none*

Children:
	* SignedInfo
	* SignatureValue
	* KeyValue
	* Object (only used with TPM signatures)


.. rst-class:: html-toggle

Result
------

Tag Name:
        response

Relevant Contracts:
        Response

Description:
        Indicator of the result of the attestation. Text value will be either "PASS" or "FAIL"

Attributes:
        *none*

Children:
        *none*


.. rst-class:: html-toggle
        
Data
----

Tag Name:
        data

Relevant Contracts:
        Response

Description:
        Report data generated by the attestation. May include raw or
        summarized measurement data or other information that may be
        of interest to a requester.

Attributes:
	* identifier - Required. Unique identifier for this data.

Children:
        *none*


.. rst-class:: html-toggle

Option
------

Tag Name:
        option

Relevant Contracts:
        Initial, Modified, Execute, Measurement

Description:
        A Copland phrase that may be used to satisfy this attestation
        request. Must contain one value node with the name="APB_phrase".
        At each stage, the options provided must be a subset of the options
        available in the previous contract.

Attributes:
        *none*

Children:
	* value - Must contain one iff Initial, Modified, or Execute contract
	* measurement - Optional

.. rst-class:: html-toggle

Value
-----

Tag Name:
        value

Relevant Contracts:
        Initial, Modified, Execute, Measurement

Description:
        An string representing a Copland phrase

Attributes:
	* name - must be "APB_phrase"

Children:
        *none*

|cp|

.. rst-class:: html-toggle

Measurement
-----------

Tag Name:
        measurement

Relevant Contracts:
        Measurement

Description:
        Contains measurement data. The text content is the base-64
        encoded measurement data. It may be compressed and/or
        encrypted (in that order) based on attributes.

Attributes:
	* compressed - "true" or "false"
	* encrypted  - "true" or "false"

Children:
        *none*


.. rst-class:: html-toggle

SignedInfo
----------

Tag Name:
        SignedInfo

Relevant Contracts:
        Initial, Modified, Execute, Measurement

Description:
        Metadata describing the signature block, and potentially pointing to
        a TPM quote.

Attributes:
        *none*

Children:
	* CanonicalizationMethod - Required
	* SignatureMethod - Required
	* DigestMethod - Required
	* Reference - Only used with TPM signatures


.. rst-class:: html-toggle

SignatureValue
--------------

Tag Name:
        SignatureValue

Relevant Contracts:
        Initial, Modified, Execute, Measurement

Description:
        Signature computed for the contract excluding the enclosing
        <signature> node. Content is the base-64 encoded signature.

Attributes:
        *none*

Children:
        *none*


.. rst-class:: html-toggle

KeyInfo
-------

Tag Name:
        KeyInfo

Relevant Contracts:
        Initial, Modified, Execute, Measurement

Description:
        Fingerprint of the public half of the key used to sign the
        contract in colon-delimited hexadecimal notation.

Attributes:
        *none*

Children:
        *none*


.. rst-class:: html-toggle

Object
------

Tag Name:
        Object

Relevant Contracts:
        Initial, Modified, Execute, Measurement

Description:
        Contains a base-64 encoded TPM quote, which in turn contains a digest
        of the contract.  If this node exists, then the signature covers the
        quote, and not the contract itself.

Attributes:
        * id - Required. Should be "tpms_attest"

Children:
        *none*

.. rst-class:: html-toggle

CanonicalizationMethod
----------------------

Tag Name:
        CanonicalizationMethod

Relevant Contracts:
        Initial, Modified, Execute, Measurement

Description:
        Indicates the algorithm used to canonicalize the XML contract for
	signing. Only XML C14N 1.0 is known to work.

Attributes:
        * algorithm - Required. Should be "XML C14N 1.0"

Children:
        *none*


.. rst-class:: html-toggle

SignatureMethod
---------------

Tag Name:
        SignatureMethod

Relevant Contracts:
        Initial, Modified, Execute, Measurement

Description:
        Indicates the cryptographic algorithm used to sign the
	contract.  Only RSA is known to work.

Attributes:
        * algorithm - Required. Should be "RSA"

Children:
        *none*


.. rst-class:: html-toggle

DigestMethod
------------

Tag Name:
        DigestMethod

Relevant Contracts:
        Initial, Modified, Execute, Measurement

Description:
        Indicates the hash algorithm used to digest the contract for
	signing. Only SHA-256 is supported as SHA-1 is considered weak.

Attributes:
        algorithm - required

Children:
        *none*


.. rst-class:: html-toggle

Reference
---------

Tag Name:
        Reference

Relevant Contracts:
        Initial, Modified, Execute, Measurement

Description:
        Points to the Object node where the TPM quote is located

Attributes:
        URI - required. Should be "#tpms_attest"

Children:
        *none*

