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