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