Google Specific APIs - A New Service Root for Google

Author: Feras Aldahlawi (faldahlawi)

Other contributors: None

Created: March 30, 2021

Problem Description

Redfish API does not have a resource type that is similar to Google's Root of Trust (RoT) chips. Google needs APIs that are not in the Redfish standard yet. There are working groups dedicated to bring RoT chips support to the Redfish standard already. Hence adding this support under a Google namespace would avoid conflict with those working groups. This document provides the schema of what Google needs for its new service root.

Background and References

At Google, we rely on communicating with RoT chips using a variety of transport mechanisms. Google wants to extend the support to include REST based APIs. The future of RoT devices at Google will adopt the SPDM protocol. However, this design doc is targeting a group of RoT devices that will never be capable of supporting standards based interface.

Requirements

  • Create a new service root of Google specific APIs.
  • Create a schema for a RootOfTrust resource.
  • Be able to execute RoT actions (attestation etc) from the API.

Proposed Design

A new service root under google/v1. This service root will contain a collection of RootOfTrust entities that have the following properties and Actions:

  • Chip type string
  • Unique Hardware id string
  • Firmware version map string to string
  • Mailbox API

This new API is designed to forward calls to RoT devices and avoid and inspections of data. An example call would be:

{
  "#RootOfTrust.Mailbox": {
      "target": "/redfish/v1/RootsOfTrust/0/Actions.Mailbox",
      "@Redfish.ActionInfo": "/redfish/v1/RootsOfTrust/0/Actions.Mailbox"
    }
  "RawRequest": "some_bytes_to_be_parsed_by_receiver"
}

This new service root is very similar to /ibm/v1. This would require a new dbus interface to service this API:

description: >
    Forward bytes to Google RoT devices.
methods:
    - name: Mailbox
      description: >
          A method to forward bytes to RoT device.
      parameters:
        - name: rawRequest
          type: array[byte]
          description: >
              Value to be updated for the keyword.
      errors:
        - xyz.openbmc_project.Common.Error.InvalidArgument
        - xyz.openbmc_project.Common.Error.InternalFailure

Alternatives Considered

Considered adding the new APIs as an OEM extension to the TPM resource. However, it was an unnatural extension. Here are the reason why it is somewhat unnatural to use TPM for Google's RoT:

  • FirmwareVersion1/2
    • Somewhat closely fixed to the design of TPM. TPM 1.2 had 32-bit firmware version and TPM 2.0 extended it clumsily by just tacking on another firmware version 32-bit field.
    • TPM "Firmware 1" and "Firmware 2" together refer to the 64-bit firmware version number. Most TPM2.0 vendors divide this into 4 fields each 2 bytes wide: (big-endian, each character is a byte:) 0xMMmmrrbb (M major, m minor, r rev, b build). Infineon uses a different convention for firmware version numbers than the rest of the TPM vendors, reserving some bits and expressing only a 1-byte wide "build number" as 0xMMmm_rrb
    • These being exposed as a string out to the Redfish interface works for Google. But I am just trying to provide info on how uniform this currently is (not) within the TPM ecosystem.
  • InterfaceType
    • Currently closely fixed to the ecosystem of TPM variants.
    • Which flavor of TPM interface is implemented. TCM is the "China version" of TPM 1.2. The Chinese TPM switched over to TPM 2.0 after that version of the spec was available.
    • TPM 1.2 and 2.0 are entirely different API surfaces, analogous to the difference between any TPM and Google's RoT chips.
  • InterfaceTypeSelection
    • Currently closely fixed to the ecosystem of TPM variants.
    • Some TPMs can be switched between TPM 1.2 and 2.0. This could be ignorable by Google unless Google start shipping an open sourced RoT that could be switched into a TPM mode via firmware update. (Which would be a good move)

Though we can put everything under TPM's OEM (e.g. version numbers and other functionality), most of the fields will be unusable for Google's RoT.

Impacts

New daemon, new Rest API.

Testing

Testing will be done in Google internally. This feature should not impact CI testing. We will try golden paths and bad paths. We will also implement fuzz tests as well.