1# Redfish resource supplement for Platform Firmware Resilience (PFR)
2
3Author: AppaRao Puli
4
5Other contributors: None
6
7Created: 2019-09-12
8
9## Problem description
10
11The platform is a collection of fundamental hardware and firmware components
12needed to boot and operate a system. The Platform Firmware Resiliency(PFR)
13in NIST SP 800-193 provides technical guidelines and recommendations
14supporting resiliency of platform firmware and data against potentially
15destructive attacks.
16
17Currently Redfish schema's defined by DMTF doesn't cover properties or
18resources to represent the PFR provisioned and locked states.
19
20This document covers the new OEM properties under ComputerSystem resource
21to represent the PFR provisioning status such as platform firmware is
22provisioned or not as well as provisioning is locked or not. This also covers
23the Redfish OpenBMC message registry metadata for logging events associated
24with PFR.
25
26## Background and references
27
28Platform Firmware Resilience technology in NIST SP 800-93 provide common
29guidelines to implementers, including Original Equipment Manufacturers (OEMs)
30and component/device suppliers, to build stronger security mechanisms into
31platforms. Server platforms consist of multiple devices which must provide
32resiliency by protecting, detecting and recovering platform assets. Management
33controller running on server platform can be used to indicate the status of
34resiliency and event logs associated with it.
35
36 - [NIST.SP.180-193](https://nvlpubs.nist.gov/nistpubs/SpecialPublications/NIST.SP.800-193.pdf)
37 - [Redfish schema supplement](https://www.dmtf.org/sites/default/files/standards/documents/DSP0268_2019.1a.pdf)
38 - [Redfish Logging in bmcweb](https://github.com/openbmc/docs/blob/master/architecture/redfish-logging-in-bmcweb.md)
39
40## Requirements
41
42High level requirements:
43
44  - BMC shall provide the way to represent Platform Firmware Resilience
45    provisioning status over Redfish.
46
47  - Event logs should be logged to redfish for Platform Firmware Resilience.
48
49## Proposed design
50
51Different OEM's has there own way of implementing the Platform Firmware
52Resilience by using guidelines provided by NIST SP 800-193. Some of the
53component protected under this includes(not limited) ES/SIO, BMC/ME Flash,
54Host Processors, Trusted Platform Modules(TPM), PSU's, Memory etc...
55For example Intel uses the "Intel PFR" design to resiliency platform
56components.
57
58NOTE: This document doesn't cover design aspects of how OEM's implements
59the Platform Firmware Resilience. It covers only generic redfish ComputerSystem
60OEM properties and Redfish message registry metadata entries which are
61implementation agnostic.
62
63OpenBMC is moving to Redfish as its standard for out of band management.
64The bmcweb implements all the Redfish schema's to represent different
65properties and resources. ComputerSystem schema doesn't cover the properties
66associated with Platform Firmware Resilience but it provides OEM objects for
67manufacturer/provider specific extension moniker.
68
69Below are property is defined to represent the Platform Firmware
70Resilience provisioning status.
71
72  - ProvisiongStatus: The value of this property indicates the provisioning
73    status of platform firmware. It is of Enum Type with below values.
74
75    1) NotProvisioned: Indicates platform firmware is not provisioned.
76       This is an unsecured state.
77
78    2) ProvisionedButNotLocked: Indicates that the platform firmware is
79       provisioned but not locked. So re-provisioning is allowed in this
80       state.
81
82    3) ProvisionedAndLocked: Indicates that the platform firmware is
83       provisioned and locked. So re-provisioning is not allowed in this
84       state.
85
86PFR enabled platforms can provision or re-provision the platform resilience
87multiple times when it is in "NotProvisioned" or "ProvisionedButNotLocked"
88states. But once the platform is transitioned to "ProvisionedAndLocked" state,
89it can not be re-provisioned.
90
91New OemComputerSystem schema can be found at
92[link](https://gerrit.openbmc.org/#/c/openbmc/bmcweb/+/24253/)
93
94PFR in OpenBMC must support logging of resiliency error detection and
95correction. Below are two metadata entries in redfish message registry
96for redfish event logging capability. For more details on how to log redfish
97events can be found at document [Redfish logging in bmcweb
98](https://github.com/openbmc/docs/blob/master/redfish-logging-in-bmcweb.md).
99
100Below type of events should be logged as part of PFR or provisioning. These
101redfish events are created for basic firmware components BIOS, BMC, CPLD and
102ME and must be extended whenever new firmware modules are supported under PFR.
103
104  1) Platform Firmware Resiliency Errors:
105     This is used to log the platform firmware resiliency errors.
106
107     MessageID's:
108       - BIOSFirmwareResiliencyError
109       - BMCFirmwareResiliencyError
110       - CPLDFirmwareResiliencyError
111       - MEFirmwareResiliencyError
112       - FirmwareResiliencyError
113     Severity: Critical
114
115     Below are some cases, where firmware resiliency error events logged
116     for specific components.
117       - Boot failure
118       - Update Failure
119
120  2) Platform Firmware Panic reason:
121     This is used to log the reason for platform firmware panic.
122
123     MessageID's:
124       - BIOSFirmwarePanicReason
125       - BMCFirmwarePanicReason
126       - CPLDFirmwarePanicReason
127       - MEFirmwarePanicReason
128     Severity: Warning
129
130     Below are some cases, where these events can be logged.
131       - Boot time watchdog expired
132       - Firmware authentication failure
133
134  3) Platform Firmware Recovery reasons:
135     This is used to log the reason for last platform firmware
136     component recovery.
137
138     MessageID's:
139       - BIOSFirmwareRecoveryReason
140       - BMCFirmwareRecoveryReason
141       - CPLDFirmwareRecoveryReason
142       - MEFirmwareRecoveryReason
143     Severity: Warning
144
145     Below are few cases, where these events can be logged.
146       - Launch failures
147       - Update failures
148       - Authentication failures
149
150Event logs associated with BMC component is specified here as example.
151```
152    MessageEntry{"BMCFirmwareResiliencyError",
153                 {
154                     "Indicates BMC firmware encountered resilience error",
155                     "BMC firmware resiliency error. Error reason: %1.",
156                     "Critical",
157                     1,
158                     {
159                         "string",
160                     },
161                     "None.",
162                 }},
163    MessageEntry{"BMCFirmwarePanicReason",
164                 {
165                     "Indicates the reason for last BMC firmware panic.",
166                     "BMC firmware panic occurred due to %1.",
167                     "Warning",
168                     1,
169                     {
170                         "string",
171                     },
172                     "None.",
173                 }},
174    MessageEntry{"BMCFirmwareRecoveryReason",
175                 {
176                     "Indicates the reason for last BMC firmware recovery.",
177                     "BMC firmware recovery occurred due to %1.",
178                     "Warning",
179                     1,
180                     {
181                         "string",
182                     },
183                     "None.",
184                 }},
185```
186
187
188## Alternatives considered
189
190None
191
192## Impacts
193
194None
195
196## Testing
197
198Provisiong status:
199
200  - User can provision the PFR in OEM specific way and test using below URI
201    and Method. Intel uses "Intel PFR" design (via BIOS) to provision and
202    lock the PFR provisioning status.
203```
204URI: /redfish/v1/Systems/system
205METHOD: GET
206RESPONSE:
207
208{
209  "@odata.context": "/redfish/v1/$metadata#ComputerSystem.ComputerSystem",
210  "@odata.id": "/redfish/v1/Systems/system",
211  "@odata.type": "#ComputerSystem.v1_6_0.ComputerSystem",
212  ...................
213  ...................
214  "Description": "Computer System",
215  "Oem": {
216    "OpenBmc": {
217      "FirmwareProvisioning": {
218        "ProvisioningStatus": "NotProvisioned"
219      }
220    }
221  },
222  ...................
223  ...................
224}
225```
226
227Event logs:
228
229  - User can induce security attack and validate the panic event logs as well as
230    recovery mechanism using below URI.
231
232    Few examples to attack Firmware components and validate PFR:
233
234     1) Corrupt the BMC/BIOS etc... firmware and check Panic events and recovery
235        actions events.
236
237     2) Induce hardware watchdog trigger using known methods and check.
238     etc..
239
240     3) Corrupt the security key's by directly mocking hardware and validate.
241
242```
243URI: /redfish/v1/Systems/system/LogServices/EventLog/Entries
244METHOD: GET
245```
246