1# Google Specific APIs - A New Service Root for Google
2
3Author:
4 Feras Aldahlawi (faldahlawi)
5
6Other contributors:
7  None
8
9Created:
10 March 30, 2021
11
12## Problem Description
13Redfish API does not have a resource type that is similar to Google's Root of
14Trust (RoT) chips. Google needs APIs that are not in the Redfish standard yet.
15There are working groups dedicated to bring RoT chips support to the Redfish
16standard already. Hence adding this support under a Google namespace would avoid
17conflict with those working groups. This document provides the schema of what
18Google needs for its new service root.
19
20## Background and References
21At Google, we rely on communicating with RoT chips using a variety of transport
22mechanisms. Google wants to extend the support to include REST based APIs. The
23future of RoT devices at Google will adopt the [SPDM protocol](https://www.dmtf.org/sites/default/files/PMCI_Security-Architecture_12-11-2019.pdf).
24However, this design doc is targeting a group of RoT devices that will never be
25capable of supporting standards based interface.
26
27## Requirements
28- Create a new service root of Google specific APIs.
29- Create a schema for a RootOfTrust resource.
30- Be able to execute RoT actions (attestation etc) from the API.
31
32## Proposed Design
33A new service root under `google/v1`. This service root will contain a
34collection of `RootOfTrust` entities that have the following properties and
35Actions:
36- Chip type string
37- Unique Hardware id string
38- Firmware version map string to string
39- Mailbox API
40
41This new API is designed to forward calls to RoT devices and avoid and
42inspections of data. An example call would be:
43
44```
45{
46  "#RootOfTrust.Mailbox": {
47      "target": "/redfish/v1/RootsOfTrust/0/Actions.Mailbox",
48      "@Redfish.ActionInfo": "/redfish/v1/RootsOfTrust/0/Actions.Mailbox"
49    }
50  "RawRequest": "some_bytes_to_be_parsed_by_receiver"
51}
52```
53
54This new service root is very similar to `/ibm/v1`. This would require a new
55dbus interface to service this API:
56```
57description: >
58    Forward bytes to Google RoT devices.
59methods:
60    - name: Mailbox
61      description: >
62          A method to forward bytes to RoT device.
63      parameters:
64        - name: rawRequest
65          type: array[byte]
66          description: >
67              Value to be updated for the keyword.
68      errors:
69        - xyz.openbmc_project.Common.Error.InvalidArgument
70        - xyz.openbmc_project.Common.Error.InternalFailure
71```
72
73## Alternatives Considered
74Considered adding the new APIs as an OEM extension to the TPM resource. However,
75it was an unnatural extension. Here are the reason why it is somewhat unnatural
76to use TPM for Google's RoT:
77
78- FirmwareVersion1/2
79  * Somewhat closely fixed to the design of TPM. TPM 1.2 had 32-bit firmware
80  version and TPM 2.0 extended it clumsily by just tacking on another firmware
81  version 32-bit field.
82  * TPM "Firmware 1" and "Firmware 2" together refer to the 64-bit firmware
83  version number. Most TPM2.0 vendors divide this into 4 fields each 2 bytes
84  wide: (big-endian, each character is a byte:) 0xMMmmrrbb (M major, m minor, r
85  rev, b build). Infineon uses a different convention for firmware version
86  numbers than the rest of the TPM vendors, reserving some bits and expressing
87  only a 1-byte wide "build number" as 0xMMmm_rrb
88  * These being exposed as a string out to the Redfish interface works for
89  Google. But I am just trying to provide info on how uniform this currently
90  is (not) within the TPM ecosystem.
91- InterfaceType
92  * Currently closely fixed to the ecosystem of TPM variants.
93  * Which flavor of TPM interface is implemented. TCM is the "China version"
94  of TPM 1.2. The Chinese TPM switched over to TPM 2.0 after that version of the
95   spec was available.
96  * TPM 1.2 and 2.0 are entirely different API surfaces, analogous to the
97  difference between any TPM and Google's RoT chips.
98- InterfaceTypeSelection
99  * Currently closely fixed to the ecosystem of TPM variants.
100  * Some TPMs can be switched between TPM 1.2 and 2.0. This could be ignorable
101  by Google unless Google start shipping an open sourced RoT that could be
102  switched into a TPM mode via firmware update. (Which would be a good move)
103
104Though we can put everything under TPM's OEM (e.g. version numbers and other
105functionality), most of the fields will be unusable for Google's RoT.
106
107## Impacts
108New daemon, new Rest API.
109
110## Testing
111Testing will be done in Google internally. This feature should not impact CI
112testing. We will try golden paths and bad paths. We will also implement fuzz
113tests as well.
114