The purpose for this patch is add documentation for the HP WMI driver.
It describes how to use and manage BIOS settings & security
solutions on HP Inc.’s commercial platforms. Patches to integrate
the security features in hp-wmi driver will follow shortly.
Many features of HP Commercial PC’s can be managed using Windows
Management Instrumentation (WMI). WMI is an implementation of Web-Based
Enterprise Management (WBEM) that provides a standards-based interface
for changing and monitoring system settings. HP WMI driver provides
a native Linux solution and the exposed features facilitates the
migration to Linux environments.
The Linux security features to be provided in hp-wmi driver enables
managing the BIOS settings and security solutions via sysfs, a virtual
filesystem that can be used by usermode applications. The new
documentation cover features such Secure Platform Management, Sure
Admin, and Sure Start. Each section provides security feature
description and identifies sysfs directories and files exposed by
the driver.
Many HP Commercial PC’s include a feature called Secure Platform
Management (SPM), which replaces older password-based BIOS settings
management with public key cryptography. PC secure product management
begins when a target system is provisioned with cryptographic keys
that are used to ensure the integrity of communications between system
management utilities and the BIOS.
HP Commercial PC’s have several BIOS settings that control its behaviour
and capabilities, many of which are related to security. To prevent
unauthorized changes to these settings, the system can be configured
to use a Sure Admin cryptographic signature-based authorization string
that the BIOS will use to verify authorization to modify the setting.
Document contents was reviewed and approved by HP internal team for
accuracy.
Signed-off-by: Jorge Lopez <jorge.lopez2@xxxxxx>
---
Based on the latest platform-drivers-x86.git/for-next
---
Documentation/admin-guide/hp_wmi.rst | 115 +++++++++++++++++++++++++++
Documentation/admin-guide/index.rst | 1 +
2 files changed, 116 insertions(+)
create mode 100644 Documentation/admin-guide/hp_wmi.rst
diff --git a/Documentation/admin-guide/hp_wmi.rst b/Documentation/admin-guide/hp_wmi.rst
new file mode 100644
index 000000000000..745de80a7386
--- /dev/null
+++ b/Documentation/admin-guide/hp_wmi.rst
@@ -0,0 +1,115 @@
+.. SPDX-License-Identifier: GPL-2.0
+===========================
+HP Inc. WMI driver (hp_wmi)
+===========================
+
+Purpose
+=======
+To document the use of the HP WMI driver to manage BIOS settings & security
+solutions on HP Inc.’s commercial platforms
+
+Scope
+=====
+This document discusses the functionality of the hp_wmi driver only.
+It does not cover the support needed from applications to configure the BIOS
+settings and enable the security features.
+
+Overview
+========
+Many features of HP Commercial PC’s can be managed using Windows Management
+Instrumentation (WMI). WMI is an implementation of Web-Based Enterprise
+Management (WBEM) that provides a standards-based interface for changing and
+monitoring system settings.
+
+The hp-wmi driver enables managing the BIOS settings and security solutions
+via sysfs, a virtual filesystem that can be used by usermode applications.
+
+When the driver loads, it creates the following directories and files in the
+/sys file system: ::
+
+ /sys/devices/platform/hp-wmi/spm/kek
+ /sys/devices/platform/hp-wmi/spm/sk
+ /sys/devices/platform/hp-wmi/spm/status
+ /sys/devices/platform/hp-wmi/spm/statusbin
+ /sys/devices/platform/hp-wmi/sure_admin/settings
+ /sys/devices/platform/hp-wmi/sure_start/audit_log_entries
+ /sys/devices/platform/hp-wmi/sure_start/audit_log_entry_count
+
+If the driver is unloaded, all the allocated memory is freed and directories
+and files in the /sys file system removed.
+
+Secure Platform Management
+==========================
+Many HP Commercial PC’s include a feature called Secure Platform Management
+(SPM), which replaces older password-based BIOS settings management with public
+key cryptography. PC secure product management begins when a target system is
+provisioned with cryptographic keys that are used to ensure the integrity of
+communications between system management utilities and the BIOS.
+
+The private key is used by system management utilities to sign payloads
+containing configuration changes. The BIOS on a target system uses the
+associated public key to verify the integrity of the payload and apply the
+changes.
+
+At the end of the PC’s lifecycle a signed deprovisioning command restores
+the factory default state.
+
+KEK Certificate (KEK) and Signing Key (SK) get provisioned and status can
+be read either as text from the status file or binary from statusbin. ::
+
+ /sys/devices/platform/hp-wmi/spm/kek
+ /sys/devices/platform/hp-wmi/spm/sk
+ /sys/devices/platform/hp-wmi/spm/status
+ /sys/devices/platform/hp-wmi/spm/statusbin
+
+**status** is a read-only file that returns ASCII text reporting the
+following values: ::
+
+ State: Not Provisioned / Provisioned / Provisioning in progress
+ Version: Major. Minor
+ Feature Bit Mask: <16-bit unsigned number display in hex>
+ SPM Counter: <16-bit unsigned number display in base 10>
+ Signing Key Public Key Modulus (base64):
+ KEK Public Key Modulus (base64):
+
+**kek** is a write-only file that can be used to configure the RSA public
+key that will be used by the BIOS to verify signatures when setting the
+signing key. When written, the bytes should correspond to the KEK
+certificate (x509 .DER format containing an OU). The size of the
+certificate must be less than or equal to 4095 bytes.
+
+**sk** is a write-only file that can be used to configure the RSA public
+key that will be used by the BIOS to verify signatures when configuring
+BIOS settings and security features. When written, the bytes should
+correspond to the modulus of the public key. The exponent is assumed
+to be 0x10001.
+
+Sure Admin
+==========
+HP Commercial PC’s have several BIOS settings that control its behaviour and
+capabilities, many of which are related to security. To prevent unauthorized
+changes to these settings, the system can be configured to use a Sure Admin
+cryptographic signature-based authorization string that the BIOS will use to
+verify authorization to modify the setting.
+Behind the scenes, Sure Admin uses Secure Platform Management (SPM) and WMI
+
+**settings** is a file associated with Sure Admin. BIOS settings can be read
+or written through the Sure Admin settings file in sysfs. ::
+
+ /sys/devices/platform/hp-wmi/sure_admin/settings
+
+Sure Start
+==========
+Sure Start provides advanced firmware protection and resiliency by identifying
+and repairing unauthorized BIOS changes. It maintains an audit log of these
+events and other important system configuration changes. The following sysfs
+entries can be used to read the contents of the audit log.
+
+**audit_log_entry_count** is a read-only file that returns the number of
+existing audit log events available to be read. ::
+
+ /sys/devices/platform/hp-wmi/sure_start/audit_log_entry_count
+
+**audit_log_entries** is a read-only file that returns the events in the log. ::
+
+ /sys/devices/platform/hp-wmi/sure_start/audit_log_entries
diff --git a/Documentation/admin-guide/index.rst b/Documentation/admin-guide/index.rst
index 1bedab498104..58b9b0541cb5 100644
--- a/Documentation/admin-guide/index.rst
+++ b/Documentation/admin-guide/index.rst
@@ -86,6 +86,7 @@ configure specific aspects of kernel behavior to your liking.
nfs/index
gpio/index
highuid
+ hp_wmi
hw_random
initrd
iostats
--
2.25.1
