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