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