Provide documentation for three new security features introduced in
the hp-wmi driver. The security features include Secure Platform
Management, Sure Admin, and Sure Start. Each documentation section
provides security feature description, identifies sysfs directories,
and files exposed by the driver.
Signed-off-by: Jorge Lopez <jorge.lopez2@xxxxxx>
---
Based on the latest platform-drivers-x86.git/for-next
This patch replaces and provides missing ABI/testing file in
v1-0001-HP-Security-Features-solutions-Documentation patch.
Signed-off-by: Jorge Lopez <jorge.lopez2@xxxxxx>
---
Based on the latest platform-drivers-x86.git/for-next
---
.../ABI/testing/sysfs-platform-hp-wmi | 96 ++++++++++++
Documentation/admin-guide/hp_wmi.rst | 141 ++++++++++++++++++
Documentation/admin-guide/index.rst | 1 +
3 files changed, 238 insertions(+)
create mode 100644 Documentation/ABI/testing/sysfs-platform-hp-wmi
create mode 100644 Documentation/admin-guide/hp_wmi.rst
diff --git a/Documentation/ABI/testing/sysfs-platform-hp-wmi b/Documentation/ABI/testing/sysfs-platform-hp-wmi
new file mode 100644
index 000000000000..836b1cdbc260
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-platform-hp-wmi
@@ -0,0 +1,96 @@
+
+What: /sys/devices/platform/hp-wmi/spm/kek
+Date: March 29
+KernelVersion: 5.18
+Contact: "Jorge Lopez" <jorge.lopez2@xxxxxx>
+Description: '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.
+
+
+What: /sys/devices/platform/hp-wmi/sk
+Date: March 29
+KernelVersion: 5.18
+Contact: "Jorge Lopez" <jorge.lopez2@xxxxxx>
+Description: '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.
+
+
+What: /sys/devices/platform/hp-wmi/status
+Date: March 29
+KernelVersion: 5.18
+Contact: "Jorge Lopez" <jorge.lopez2@xxxxxx>
+Description: 'status' is a read-only file that returns ASCII text reporting
+ the status information.
+
+ 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):
+
+
+What: /sys/devices/platform/hp-wmi/statusbin
+Date: March 29
+KernelVersion: 5.18
+Contact: "Jorge Lopez" <jorge.lopez2@xxxxxx>
+Description: 'statusbin' is a read-only file that returns identical status
+ information reported by 'status' file in binary format.
+
+
+What: /sys/devices/platform/hp-wmi/sure_admin/settings
+Date: March 29
+KernelVersion: 5.18
+Contact: "Jorge Lopez" <jorge.lopez2@xxxxxx>
+Description: 'settings' is a file associated with Sure Admin. BIOS settings can
+ be read or written through the Sure Admin settings file in sysfs.
+
+ Expected data format to update BIOS setting
+
+ [BIOS setting],[new value],[auth token]
+
+ Sample settings reported data
+
+ {
+ "Class": "HPBIOS_BIOSEnumeration",
+ "Name": "USB Storage Boot",
+ "Path": "\\Advanced\\Boot Options",
+ "IsReadOnly": 0,
+ ...
+ "Value": "Enable",
+ "Size": 2,
+ "PossibleValues": [
+ "Disable",
+ "Enable"
+ ]
+ }
+
+
+What: /sys/devices/platform/hp-wmi/sure_start/audit_log_entry_count
+Date: March 29
+KernelVersion: 5.18
+Contact: "Jorge Lopez" <jorge.lopez2@xxxxxx>
+Description: audit_log_entry_count is a read-only file that returns the
+ number of existing audit log events available to be read.
+
+ [No of entries],[log entry size],[Max number of entries supported]
+
+
+What: /sys/devices/platform/hp-wmi/sure_start/audit_log_entries
+Date: March 29
+KernelVersion: 5.18
+Contact: "Jorge Lopez" <jorge.lopez2@xxxxxx>
+Description: audit_log_entries is a read-only file that returns the events
+ in the log.
+
+ Audit log entry format
+
+ Byte 0-15: Requested Audit Log entry (Each Audit log is 16 bytes)
+ Byte 16-127: Unused
diff --git a/Documentation/admin-guide/hp_wmi.rst b/Documentation/admin-guide/hp_wmi.rst
new file mode 100644
index 000000000000..4dcb416bbf08
--- /dev/null
+++ b/Documentation/admin-guide/hp_wmi.rst
@@ -0,0 +1,141 @@
+.. 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 information::
+
+ 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
+
+Expected data format to update BIOS setting::
+
+ [BIOS setting],[new value],[auth token]
+
+Sample settings reported data::
+
+ {
+ "Class": "HPBIOS_BIOSEnumeration",
+ "Name": "USB Storage Boot",
+ "Path": "\\Advanced\\Boot Options",
+ "IsReadOnly": 0,
+ ...
+ "Value": "Enable",
+ "Size": 2,
+ "PossibleValues": [
+ "Disable",
+ "Enable"
+ ]
+ }
+
+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
+
+Reported data format::
+
+ [No of entries],[log entry size in bytes],[Max number of entries supported]
+
+
+**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
