Skip to contentSkip to conversation

Introduction-of-HP-BIOSCFG-driver-documentation

PATCH Superseded Jorge Lopez 4 participants 10 messages Apr 3, 2023 – Apr 14, 2023

Subsystems (4)

v7 of 17 Superseded Latest is v17 →

lore
Share & tools
lore
#0 lore raw

PATCH v7 1/1 Introduction-of-HP-BIOSCFG-driver-documentation

HP BIOS Configuration driver purpose is to provide a driver supporting the latest sysfs class firmware attributes framework allowing the user to change BIOS settings and security solutions on HP Inc.’s commercial notebooks.

Many features of HP Commercial notebooks 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 BIOSCFG 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-bioscfg driver enables managing the BIOS settings and security solutions via sysfs, a virtual filesystem that can be used by user-mode applications. The new documentation cover features such Secure Platform Management and Sure Start. Each section provides security feature description and identifies sysfs directories and files exposed by the driver.

Many HP Commercial notebooks 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 notebooks 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 cryptographic signature-based authorization string that the BIOS will use to verify authorization to modify the setting.

---
Based on the latest platform-drivers-x86.git/for-next

History

Version 7
Includes only sysfs-class-firmware-attributes documentation

Version 6
Breaks down the changes into 4 patches
SureAdmin-attributes was removed

Version 5
Remove version 4 patch 1
Address review changes proposed in Version 4 Reorganize all patches number and file order

---
 .../testing/sysfs-class-firmware-attributes   | 119 ++++++++++++++++--
 1 file changed, 107 insertions(+), 12 deletions(-)
Documentation/ABI/testing/sysfs-class-firmware-attributes +107 -12
index 4cdba3477176..10afbb78baec 100644
@@ -22,6 +22,12 @@ Description:
 			- integer: a range of numerical values
 			- string
 
+		HP specific types
+		-----------------
+			- ordered-list - a set of ordered list valid values
+			- sure-start
+
+
 		All attribute types support the following values:
 
 		current_value:
@@ -42,16 +48,16 @@ Description:
 				description of the at <attr>
 
 		display_name_language_code:
-						A file that can be read to obtain
-						the IETF language tag corresponding to the
-						"display_name" of the <attr>
+				A file that can be read to obtain
+				the IETF language tag corresponding to the
+				"display_name" of the <attr>
 
 		"enumeration"-type specific properties:
 
 		possible_values:
-					A file that can be read to obtain the possible
-					values of the <attr>. Values are separated using
-					semi-colon (``;``).
+				A file that can be read to obtain the possible
+				values of the <attr>. Values are separated using
+				semi-colon (``;``).
 
 		"integer"-type specific properties:
 
@@ -64,8 +70,8 @@ Description:
 				bound value of the <attr>
 
 		scalar_increment:
-					A file that can be read to obtain the scalar value used for
-					increments of current_value this attribute accepts.
+				A file that can be read to obtain the scalar value used for
+				increments of current_value this attribute accepts.
 
 		"string"-type specific properties:
 
@@ -126,6 +132,40 @@ Description:
 					value will not be effective through sysfs until this rule is
 					met.
 
+		HP specific class extensions
+		------------------------------
+
+		On HP systems the following additional attributes are available:
+
+		"ordered-list"-type specific properties:
+
+		elements:
+					A file that can be read to obtain the possible
+					list of values of the <attr>. Values are separated using
+					semi-colon (``;``). The order individual elements are listed
+					according to their priority.  An Element listed first has the
+					highest priority. Writing the list in a different order to
+					current_value alters the priority order for the particular
+					attribute.
+
+		"sure-start"-type specific properties:
+
+		audit_log_entries:
+					A read-only file that returns the events in the log.
+					Values are separated using semi-colon (``;``)
+
+					Audit log entry format
+
+					Byte 0-15:   Requested Audit Log entry  (Each Audit log is 16 bytes)
+					Byte 16-127: Unused
+
+		audit_log_entry_count:
+					A read-only file that returns the number of existing audit log events available to be read.
+					Values are separated using comma (``,``)
+
+					[No of entries],[log entry size],[Max number of entries supported]
+
+
 What:		/sys/class/firmware-attributes/*/authentication/
 Date:		February 2021
 KernelVersion:	5.11
@@ -139,8 +179,7 @@ Description:
 		For example a "BIOS Admin" password and "System" Password can be set,
 		reset or cleared using these attributes.
 
-		- An "Admin" password is used for preventing modification to the BIOS
-		  settings.
+		- An "Admin" password is used for preventing modification to the BIOS settings.
 		- A "System" password is required to boot a machine.
 
 		Change in any of these two authentication methods will also generate an
@@ -206,7 +245,7 @@ Description:
 		Drivers may emit a CHANGE uevent when a password is set or unset
 		userspace may check it again.
 
-		On Dell and Lenovo systems, if Admin password is set, then all BIOS attributes
+		On Dell, Lenovo and HP systems, if Admin password is set, then all BIOS attributes
 		require password validation.
 		On Lenovo systems if you change the Admin password the new password is not active until
 		the next boot.
@@ -296,6 +335,15 @@ Description:
 						echo "signature" > authentication/Admin/signature
 						echo "password" > authentication/Admin/certificate_to_password
 
+		HP specific class extensions
+		--------------------------------
+
+		On HP systems the following additional settings are available:
+
+		role: enhanced-bios-auth:
+					This role is specific to Secure Platform Management (SPM) attribute.
+					It requires configuring an endorsement (kek) and signing certificate (sk).
+
 
 What:		/sys/class/firmware-attributes/*/attributes/pending_reboot
 Date:		February 2021
@@ -311,7 +359,7 @@ Description:
 			==	=========================================
 			0	All BIOS attributes setting are current
 			1	A reboot is necessary to get pending BIOS
-			        attribute changes applied
+				attribute changes applied
 			==	=========================================
 
 		Note, userspace applications need to follow below steps for efficient
@@ -364,3 +412,50 @@ Description:
 		use it to enable extra debug attributes or BIOS features for testing purposes.
 
 		Note that any changes to this attribute requires a reboot for changes to take effect.
+
+
+		HP specific class extensions - Secure Platform Manager (SPM)
+		--------------------------------
+
+What:		/sys/class/firmware-attributes/*/authentication/SPM/kek
+Date:		March 29
+KernelVersion:	5.18
+Contact:	"Jorge Lopez" <[email protected]>
+Description:	'kek' Key-Encryption-Key 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/class/firmware-attributes/*/authentication/SPM/sk
+Date:		March 29
+KernelVersion:	5.18
+Contact:	"Jorge Lopez" <[email protected]>
+Description:	'sk' Signature Key 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/class/firmware-attributes/*/authentication/SPM/status
+Date:		March 29
+KernelVersion:	5.18
+Contact:	"Jorge Lopez" <[email protected]>
+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/class/firmware-attributes/*/authentication/SPM/statusbin
+Date:		March 29
+KernelVersion:	5.18
+Contact:	"Jorge Lopez" <[email protected]>
+Description:	'statusbin' is a read-only file that returns identical status
+		information reported by 'status' file in binary format.
Signature · 1 line
2.34.1
#1 lore raw
Quoted 26 lines · Jorge Lopez

HP BIOS Configuration driver purpose is to provide a driver supporting the latest sysfs class firmware attributes framework allowing the user to change BIOS settings and security solutions on HP Inc.’s commercial notebooks.

Many features of HP Commercial notebooks 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 BIOSCFG 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-bioscfg driver enables managing the BIOS settings and security solutions via sysfs, a virtual filesystem that can be used by user-mode applications. The new documentation cover features such Secure Platform Management and Sure Start. Each section provides security feature description and identifies sysfs directories and files exposed by the driver.

Many HP Commercial notebooks 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.

Quoted 5 lines

HP Commercial notebooks 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 cryptographic signature-based authorization string that the BIOS will use to verify authorization to modify the setting.

If this is single patch, I'd like to write the patch subject as "Documentation: sysfs: document HP-specific firmware attributes".

And also, adjust the patch description accordingly, since as it is written above, it looks like general documentation of HP-specific feature (which should be in actual diff).

Quoted 2 lines

Version 7
Includes only sysfs-class-firmware-attributes documentation

Where is the rest of patches if this is a series? Had they been merged?

Thanks.

Signature · 1 line
An old man doll... just what I always wanted! - Clara
#2 lore raw

Hi Bagas,

Quoted 3 lines

Where is the rest of patches if this is a series? Had they been merged?

There is only one change as requested by Thomas Weißschuh

Quoted 3 lines

Feel free to ONLY submit the patch with the documentation for the next revision. Then we can nail down the interface and initial functionality and you don't always have to adapt the code to the changing interface.

Perhaps, I misunderstood Thomas request. I will address a few other
comments and will submit all files again.

Regards,

Jorge

#3 lore raw

Hi All,

FWIW I have been reading along with both the v6 and this v7 posting.

Thomas, Mark, thank you for your review / feedback on this series.

Quoted 6 lines · Jorge Lopez

Hi Bagas,

Quoted 3 lines

Where is the rest of patches if this is a series? Had they been merged?

Quoted 8 lines

There is only one change as requested by Thomas Weißschuh

Quoted 3 lines

Feel free to ONLY submit the patch with the documentation for the next revision. Then we can nail down the interface and initial functionality and you don't always have to adapt the code to the changing interface.

Perhaps, I misunderstood Thomas request. I will address a few other
comments and will submit all files again.

I think that Thomas' suggestion to first focus on getting the userspace API right and then implement the agreed upon API is a good idea.

So for the next version just post only the documentation patch again please.

Note it is not the intention to merge just the documentation patch without merging the code first.

The idea is to first nail the API down and then modify the code once to implement the agreed upon API.

Then once the API has been agreed upon post newer versions which also include the code again.

And then once people are also happy with the code we can merge both the code + documentation in one go.

Regards,

Hans

Quoted 5 lines

Regards,

Jorge

#4 lore raw

Hi there,

Version 9 review for the sysfs-class-firmware-attributes document was
submitted and I look forward to getting your comments. I understand
you have other things happening, but as soon as the document is finalized, I can move to submit the rest of the files.

While the document review is ongoing, I proceeded to address all comments made by Thomas, Hans, Bagas, and Mark regarding both documentation and source code changes. The code compiles with W=1 flag without any issues and the refactoring proposed by Thomas was incorporated. Testing on multiple platforms continues to validate the driver proper operation between reviews.

Regards,

Jorge

Quoted 60 lines · Hans de Goede

Hi All,

FWIW I have been reading along with both the v6 and this v7 posting.

Thomas, Mark, thank you for your review / feedback on this series.

Quoted 6 lines · Jorge Lopez

Hi Bagas,

Quoted 3 lines

Where is the rest of patches if this is a series? Had they been merged?

Quoted 8 lines

There is only one change as requested by Thomas Weißschuh

Quoted 3 lines

Feel free to ONLY submit the patch with the documentation for the next revision. Then we can nail down the interface and initial functionality and you don't always have to adapt the code to the changing interface.

Perhaps, I misunderstood Thomas request. I will address a few other
comments and will submit all files again.

I think that Thomas' suggestion to first focus on getting the userspace API right and then implement the agreed upon API is a good idea.

So for the next version just post only the documentation patch again please.

Note it is not the intention to merge just the documentation patch without merging the code first.

The idea is to first nail the API down and then modify the code once to implement the agreed upon API.

Then once the API has been agreed upon post newer versions which also include the code again.

And then once people are also happy with the code we can merge both the code + documentation in one go.

Regards,

Hans

Quoted 5 lines

Regards,

Jorge

#5 lore raw
In reply to Bagas Sanjaya

Hi Bagas,

Quoted 36 lines · Bagas Sanjaya
Quoted 26 lines · Jorge Lopez

HP BIOS Configuration driver purpose is to provide a driver supporting the latest sysfs class firmware attributes framework allowing the user to change BIOS settings and security solutions on HP Inc.’s commercial notebooks.

Many features of HP Commercial notebooks 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 BIOSCFG 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-bioscfg driver enables managing the BIOS settings and security solutions via sysfs, a virtual filesystem that can be used by user-mode applications. The new documentation cover features such Secure Platform Management and Sure Start. Each section provides security feature description and identifies sysfs directories and files exposed by the driver.

Many HP Commercial notebooks 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.

Quoted 5 lines

HP Commercial notebooks 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 cryptographic signature-based authorization string that the BIOS will use to verify authorization to modify the setting.

If this is single patch, I'd like to write the patch subject as "Documentation: sysfs: document HP-specific firmware attributes".

Quoted 8 lines

And also, adjust the patch description accordingly, since as it is written above, it looks like general documentation of HP-specific feature (which should be in actual diff).

Quoted 2 lines

Version 7
Includes only sysfs-class-firmware-attributes documentation

Where is the rest of patches if this is a series? Had they been merged?

It was my proposal to focus on the documentation first in a single patch.
So we can nail down the scope and details of the user-facing API without Jorge and the reviewers spending time on polishing internals that will change anyways.

The code exists and will be submitted with future revisions again. You can find v6 with the code here:
https://lore.kernel.org/all/[email protected]/

I should have also requested a note to that point with this revision.

Thomas

#6 lore raw
In reply to Jorge Lopez

Hi Jorge!

Comments inline.

Please also Cc reviewers of past revisions to future revisions.

Quoted 59 lines · Jorge Lopez

HP BIOS Configuration driver purpose is to provide a driver supporting the latest sysfs class firmware attributes framework allowing the user to change BIOS settings and security solutions on HP Inc.’s commercial notebooks.

Many features of HP Commercial notebooks 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 BIOSCFG 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-bioscfg driver enables managing the BIOS settings and security solutions via sysfs, a virtual filesystem that can be used by user-mode applications. The new documentation cover features such Secure Platform Management and Sure Start. Each section provides security feature description and identifies sysfs directories and files exposed by the driver.

Many HP Commercial notebooks 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 notebooks 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 cryptographic signature-based authorization string that the BIOS will use to verify authorization to modify the setting.

---
Based on the latest platform-drivers-x86.git/for-next

History

Version 7
Includes only sysfs-class-firmware-attributes documentation

Version 6
Breaks down the changes into 4 patches
SureAdmin-attributes was removed

Version 5
Remove version 4 patch 1
Address review changes proposed in Version 4 Reorganize all patches number and file order

---
 .../testing/sysfs-class-firmware-attributes   | 119 ++++++++++++++++--
 1 file changed, 107 insertions(+), 12 deletions(-)
Documentation/ABI/testing/sysfs-class-firmware-attributes +0 -0
index 4cdba3477176..10afbb78baec 100644

Documentation/ABI/testing/sysfs-class-firmware-attributes Description: · line 28

Quoted 7 lines
Documentation/ABI/testing/sysfs-class-firmware-attributes +4 -0
@@ -22,6 +22,12 @@ Description:
 			- integer: a range of numerical values
 			- string
 
+		HP specific types
+		-----------------
+			- ordered-list - a set of ordered list valid values
+			- sure-start

Could you explain what "sure-start" does?
Is it actually an attribute type of which multiple attributes can exist?

Or are there just some global properties that need to be exposed? If it is global it should be directly under /sys/class/firmware-attributes/*/authentication/ without needing the type.

Quoted 6 lines
Documentation/ABI/testing/sysfs-class-firmware-attributes +2 -0
+
+
 		All attribute types support the following values:
 
 		current_value:

Documentation/ABI/testing/sysfs-class-firmware-attributes Description: · line 53

Quoted 9 lines
Documentation/ABI/testing/sysfs-class-firmware-attributes +3 -3
@@ -42,16 +48,16 @@ Description:
 				description of the at <attr>
 
 		display_name_language_code:
-						A file that can be read to obtain
-						the IETF language tag corresponding to the
-						"display_name" of the <attr>
+				A file that can be read to obtain
+				the IETF language tag corresponding to the
+				"display_name" of the <attr>

Are these reindentations and other cleanups intentional?

If they are intentional and there are no interactions with your actual patch you could split them into their own patch and submit them separately.

This way we wouldn't have to worry about them here anymore.

Note:
These indentations are different from the newly introduced documentation.

Quoted 44 lines
Documentation/ABI/testing/sysfs-class-firmware-attributes +21 -5
 		"enumeration"-type specific properties:
 
 		possible_values:
-					A file that can be read to obtain the possible
-					values of the <attr>. Values are separated using
-					semi-colon (``;``).
+				A file that can be read to obtain the possible
+				values of the <attr>. Values are separated using
+				semi-colon (``;``).
 
 		"integer"-type specific properties:
 
@@ -64,8 +70,8 @@ Description:
 				bound value of the <attr>
 
 		scalar_increment:
-					A file that can be read to obtain the scalar value used for
-					increments of current_value this attribute accepts.
+				A file that can be read to obtain the scalar value used for
+				increments of current_value this attribute accepts.
 
 		"string"-type specific properties:
 
@@ -126,6 +132,40 @@ Description:
 					value will not be effective through sysfs until this rule is
 					met.
 
+		HP specific class extensions
+		------------------------------
+
+		On HP systems the following additional attributes are available:
+
+		"ordered-list"-type specific properties:
+
+		elements:
+					A file that can be read to obtain the possible
+					list of values of the <attr>. Values are separated using
+					semi-colon (``;``). The order individual elements are listed
+					according to their priority.  An Element listed first has the
+					highest priority. Writing the list in a different order to
+					current_value alters the priority order for the particular
+					attribute.
+

Documentation/ABI/testing/sysfs-class-firmware-attributes Description: · line 160

Quoted 10 lines
Documentation/ABI/testing/sysfs-class-firmware-attributes +10 -0
+		"sure-start"-type specific properties:
+
+		audit_log_entries:
+					A read-only file that returns the events in the log.
+					Values are separated using semi-colon (``;``)
+
+					Audit log entry format
+
+					Byte 0-15:   Requested Audit Log entry  (Each Audit log is 16 bytes)
+					Byte 16-127: Unused

How to interpret each log entry?

If it is an opaque thing from the firmware that would also be useful to know.

Documentation/ABI/testing/sysfs-class-firmware-attributes Description: · line 166

Quoted 6 lines
Documentation/ABI/testing/sysfs-class-firmware-attributes +6 -0
+
+		audit_log_entry_count:
+					A read-only file that returns the number of existing audit log events available to be read.
+					Values are separated using comma (``,``)
+
+					[No of entries],[log entry size],[Max number of entries supported]

Will log entry size always be 16? Or can it be bigger in the future when more bytes are used?
This should be mentioned.

Is audit_log_entry_count ever used without reading audit_log_entries right after?
If not the count file could be dropped.

Quoted 79 lines
Documentation/ABI/testing/sysfs-class-firmware-attributes +40 -4
+
+
 What:		/sys/class/firmware-attributes/*/authentication/
 Date:		February 2021
 KernelVersion:	5.11
@@ -139,8 +179,7 @@ Description:
 		For example a "BIOS Admin" password and "System" Password can be set,
 		reset or cleared using these attributes.
 
-		- An "Admin" password is used for preventing modification to the BIOS
-		  settings.
+		- An "Admin" password is used for preventing modification to the BIOS settings.
 		- A "System" password is required to boot a machine.
 
 		Change in any of these two authentication methods will also generate an
@@ -206,7 +245,7 @@ Description:
 		Drivers may emit a CHANGE uevent when a password is set or unset
 		userspace may check it again.
 
-		On Dell and Lenovo systems, if Admin password is set, then all BIOS attributes
+		On Dell, Lenovo and HP systems, if Admin password is set, then all BIOS attributes
 		require password validation.
 		On Lenovo systems if you change the Admin password the new password is not active until
 		the next boot.
@@ -296,6 +335,15 @@ Description:
 						echo "signature" > authentication/Admin/signature
 						echo "password" > authentication/Admin/certificate_to_password
 
+		HP specific class extensions
+		--------------------------------
+
+		On HP systems the following additional settings are available:
+
+		role: enhanced-bios-auth:
+					This role is specific to Secure Platform Management (SPM) attribute.
+					It requires configuring an endorsement (kek) and signing certificate (sk).
+
 
 What:		/sys/class/firmware-attributes/*/attributes/pending_reboot
 Date:		February 2021
@@ -311,7 +359,7 @@ Description:
 			==	=========================================
 			0	All BIOS attributes setting are current
 			1	A reboot is necessary to get pending BIOS
-			        attribute changes applied
+				attribute changes applied
 			==	=========================================
 
 		Note, userspace applications need to follow below steps for efficient
@@ -364,3 +412,50 @@ Description:
 		use it to enable extra debug attributes or BIOS features for testing purposes.
 
 		Note that any changes to this attribute requires a reboot for changes to take effect.
+
+
+		HP specific class extensions - Secure Platform Manager (SPM)
+		--------------------------------
+
+What:		/sys/class/firmware-attributes/*/authentication/SPM/kek
+Date:		March 29
+KernelVersion:	5.18
+Contact:	"Jorge Lopez" <[email protected]>
+Description:	'kek' Key-Encryption-Key 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/class/firmware-attributes/*/authentication/SPM/sk
+Date:		March 29
+KernelVersion:	5.18
+Contact:	"Jorge Lopez" <[email protected]>
+Description:	'sk' Signature Key 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.
+
+

Documentation/ABI/testing/sysfs-class-firmware-attributes Description: · line 450

Quoted 10 lines
Documentation/ABI/testing/sysfs-class-firmware-attributes +10 -0
+What:		/sys/class/firmware-attributes/*/authentication/SPM/status
+Date:		March 29
+KernelVersion:	5.18
+Contact:	"Jorge Lopez" <[email protected]>
+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>

How are these bits to be interpreted?

Documentation/ABI/testing/sysfs-class-firmware-attributes Description: · line 453

Quoted 3 lines
Documentation/ABI/testing/sysfs-class-firmware-attributes +3 -0
+		  SPM Counter: <16-bit unsigned number display in base 10>
+		  Signing Key Public Key Modulus (base64):
+		  KEK Public Key Modulus (base64):

Is " (base64)" supposed to be part of the contents of the file?

Documentation/ABI/testing/sysfs-class-firmware-attributes Description: · line 461

Quoted 8 lines
Documentation/ABI/testing/sysfs-class-firmware-attributes +8 -0
+
+
+What:		/sys/class/firmware-attributes/*/authentication/SPM/statusbin
+Date:		March 29
+KernelVersion:	5.18
+Contact:	"Jorge Lopez" <[email protected]>
+Description:	'statusbin' is a read-only file that returns identical status
+		information reported by 'status' file in binary format.

This documentation should contain enough information to understand the files contents.

I understand that one WMI call will return all the fields that are part of the "status" and "statusbin" in one response.

Are these WMI calls especially expensive or called especially frequently?

If not I would still argue to split them into one file per field and remove the statusbin file.

It is much more intuitive to read for example the KEK from the file "kek" where it is also updated from.

This interface will be used by various applications and it is much easier to read simple files than having to parse single fields from bespoke text or binary files.

Thomas

#7 lore raw

Hi Thomas,

BTW, I decided to submit all files individually to facilitate the review process. Only Makefile and Kconfig files will be provided as a single patch.
I will be out of town until April 11 and will reply back upon my return.

Please see my comments below.

Quoted 9 lines

Documentation/ABI/testing/sysfs-class-firmware-attributes Description: · line 28

Quoted 5 lines
Documentation/ABI/testing/sysfs-class-firmware-attributes +4 -0
+             HP specific types
+             -----------------
+                     - ordered-list - a set of ordered list valid values
+                     - sure-start

Could you explain what "sure-start" does?
Is it actually an attribute type of which multiple attributes can exist?

It is an attribute type of which multiple attributes can exist. At this moment Sure-Start reports both the number of audit logs and all logs reported by BIOS.
Sure-Start is exposed directly under
/sys/class/firmware-attributes/*/attributes/. Sure Start does not
provide any authentication.

Quoted 23 lines

Or are there just some global properties that need to be exposed? If it is global it should be directly under /sys/class/firmware-attributes/*/authentication/ without needing the type.

Quoted 6 lines
Documentation/ABI/testing/sysfs-class-firmware-attributes +2 -0
+
+
              All attribute types support the following values:
 
              current_value:

Documentation/ABI/testing/sysfs-class-firmware-attributes Description: · line 53

Quoted 9 lines
Documentation/ABI/testing/sysfs-class-firmware-attributes +3 -3
@@ -42,16 +48,16 @@ Description:
                              description of the at <attr>
 
              display_name_language_code:
-                                             A file that can be read to obtain
-                                             the IETF language tag corresponding to the
-                                             "display_name" of the <attr>
+                             A file that can be read to obtain
+                             the IETF language tag corresponding to the
+                             "display_name" of the <attr>

Are these reindentations and other cleanups intentional?

Quoted 5 lines

If they are intentional and there are no interactions with your actual patch you could split them into their own patch and submit them separately.

This way we wouldn't have to worry about them here anymore.

They were unintentionally. I will reset them back in the next review

Quoted 5 lines

Note:
These indentations are different from the newly introduced documentation.

Quoted 1 line
Quoted 11 lines

Documentation/ABI/testing/sysfs-class-firmware-attributes Description: · line 160

Quoted 8 lines
Documentation/ABI/testing/sysfs-class-firmware-attributes +8 -0
+             audit_log_entries:
+                                     A read-only file that returns the events in the log.
+                                     Values are separated using semi-colon (``;``)
+
+                                     Audit log entry format
+
+                                     Byte 0-15:   Requested Audit Log entry  (Each Audit log is 16 bytes)
+                                     Byte 16-127: Unused

How to interpret each log entry?

Byte 0: status
1: event id
2: msg number
3: severity
4: source ID
5: system state at event
6-12 Time stamp
13-15: internal buffer data

Application needs to have knowledge of the data provided by BIOS in order to interpret the audit log.

Quoted 13 lines

If it is an opaque thing from the firmware that would also be useful to know.

Documentation/ABI/testing/sysfs-class-firmware-attributes Description: · line 166

Quoted 6 lines
Documentation/ABI/testing/sysfs-class-firmware-attributes +6 -0
+
+             audit_log_entry_count:
+                                     A read-only file that returns the number of existing audit log events available to be read.
+                                     Values are separated using comma (``,``)
+
+                                     [No of entries],[log entry size],[Max number of entries supported]

Will log entry size always be 16? Or can it be bigger in the future when more bytes are used?
This should be mentioned.

Log entry size is always 16 bytes in size. The reason is to report a maximum of 256 entries. Total 4096 bytes

Quoted 3 lines

Is audit_log_entry_count ever used without reading audit_log_entries right after?

Yes. The counter is necessary to determine how many logs are available to be read.

Quoted 14 lines

If not the count file could be dropped.

Documentation/ABI/testing/sysfs-class-firmware-attributes Description: · line 450

Quoted 10 lines
Documentation/ABI/testing/sysfs-class-firmware-attributes +10 -0
+What:                /sys/class/firmware-attributes/*/authentication/SPM/status
+Date:                March 29
+KernelVersion:       5.18
+Contact:     "Jorge Lopez" <[email protected]>
+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>

How are these bits to be interpreted?

This information is provided by BIOS. It is one of those obscure values from BIOS.

Quoted 6 lines

Documentation/ABI/testing/sysfs-class-firmware-attributes Description: · line 453

Quoted 4 lines
Documentation/ABI/testing/sysfs-class-firmware-attributes +3 -0
+               SPM Counter: <16-bit unsigned number display in base 10>
+               Signing Key Public Key Modulus (base64):
+               KEK Public Key Modulus (base64):

Is " (base64)" supposed to be part of the contents of the file?

The information reported for Signing Key and KEK public key are reported as base64 values. It applies only to the data and not to the file contents.

Quoted 14 lines

Documentation/ABI/testing/sysfs-class-firmware-attributes Description: · line 461

Quoted 9 lines
Documentation/ABI/testing/sysfs-class-firmware-attributes +8 -0
+
+
+What:                /sys/class/firmware-attributes/*/authentication/SPM/statusbin
+Date:                March 29
+KernelVersion:       5.18
+Contact:     "Jorge Lopez" <[email protected]>
+Description: 'statusbin' is a read-only file that returns identical status
+             information reported by 'status' file in binary format.

This documentation should contain enough information to understand the files contents.

Quoted 6 lines

I understand that one WMI call will return all the fields that are part of the "status" and "statusbin" in one response.

Are these WMI calls especially expensive or called especially frequently?

Unfortunately the WMI to read the Status binary data is expensive hence the reason of only calling once.

Quoted 3 lines

If not I would still argue to split them into one file per field and remove the statusbin file.

Regards,

Jorge

#8 lore raw

Hi Jorge!

Apr 4, 2023 22:24:36 Jorge Lopez <[email protected]>:

Quoted 6 lines

Hi Thomas,

BTW, I decided to submit all files individually to facilitate the review process.  Only Makefile and Kconfig files will be provided as a single patch.
I will be out of town until April 11 and will reply back upon my return.

Sorry for the slow response.

Quoted 13 lines

Please see my comments below.

Quoted 9 lines
Quoted 5 lines

+             HP specific types
+             -----------------
+                     - ordered-list - a set of ordered list valid values +                     - sure-start

Could you explain what "sure-start" does?
Is it actually an attribute type of which multiple attributes can exist?

Quoted 6 lines

It is an attribute type of which multiple attributes can exist. At this moment  Sure-Start reports both the number of audit logs and all logs reported by BIOS.
Sure-Start is exposed directly under /sys/class/firmware-attributes/*/attributes/.   Sure Start does not provide any authentication.

But what does it mean?
For ordered-list there is a nice explanation.

Quoted 74 lines
Quoted 24 lines

Or are there just some global properties that need to be exposed? If it is global it should be directly under /sys/class/firmware-attributes/*/authentication/ without needing the type.

Quoted 8 lines
(quoted diff) +2 -0
+
+

              All attribute types support the following values:

              current_value:

(quoted diff) +0 -0
@@ -42,16 +48,16 @@ Description:

                              description of the at <attr>

Quoted 7 lines

              display_name_language_code:
-                                             A file that can be read to obtain -                                             the IETF language tag corresponding to the -                                             "display_name" of the <attr> +                             A file that can be read to obtain
+                             the IETF language tag corresponding to the
+                             "display_name" of the <attr>

Are these reindentations and other cleanups intentional?

Quoted 5 lines

If they are intentional and there are no interactions with your actual patch you could split them into their own patch and submit them separately.

This way we wouldn't have to worry about them here anymore.

They were unintentionally.  I will reset them back in the next review

Quoted 5 lines

Note:
These indentations are different from the newly introduced documentation.

Quoted 1 line
Quoted 11 lines

Documentation/ABI/testing/sysfs-class-firmware-attributes Description: · line 160

Quoted 8 lines

+             audit_log_entries:
+                                     A read-only file that returns the events in the log. +                                     Values are separated using semi-colon (``;``)

Documentation/ABI/testing/sysfs-class-firmware-attributes +5 -0
+
+                                     Audit log entry format
+
+                                     Byte 0-15:   Requested Audit Log entry  (Each Audit log is 16 bytes)
+                                     Byte 16-127: Unused

How to interpret each log entry?

Byte 0: status
1: event id
2: msg number
3: severity
4: source ID
5: system state at event
6-12 Time stamp
13-15: internal buffer data

Application needs to have knowledge of the data provided by BIOS in order to interpret the audit log.

Quoted 13 lines

If it is an opaque thing from the firmware that would also be useful to know.

Documentation/ABI/testing/sysfs-class-firmware-attributes Description: · line 166

Quoted 6 lines
Documentation/ABI/testing/sysfs-class-firmware-attributes +6 -0
+
+             audit_log_entry_count:
+                                     A read-only file that returns the number of existing audit log events available to be read.
+                                     Values are separated using comma (``,``)
+
+                                     [No of entries],[log entry size],[Max number of entries supported]

Will log entry size always be 16? Or can it be bigger in the future when more bytes are used?
This should be mentioned.

Quoted 2 lines

Log entry size is always 16 bytes in size.  The reason is to report a maximum of 256 entries.  Total 4096 bytes

Does it make sense to expose the number 16 from sysfs if it never can change anyways?

Note you can also customize the filesize reported in sysfs to expose the maximum size to be used by userspace.

Quoted 5 lines
Quoted 3 lines

Is audit_log_entry_count ever used without reading audit_log_entries right after?

Yes. The counter is necessary to determine how many logs are available to be read.

I think the cleaner interface would be to have users provide a buffer to read into and then they check the return value of read(). Users can't trust the count value anyways as it is prone to TOCTOU races.

Quoted 22 lines
Quoted 15 lines

If not the count file could be dropped.

Documentation/ABI/testing/sysfs-class-firmware-attributes Description: · line 450

Quoted 10 lines
Documentation/ABI/testing/sysfs-class-firmware-attributes +10 -0
+What:                /sys/class/firmware-attributes/*/authentication/SPM/status
+Date:                March 29
+KernelVersion:       5.18
+Contact:     "Jorge Lopez" <[email protected]>
+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>

How are these bits to be interpreted?

This information is provided by BIOS.  It is one of those obscure values from BIOS.

Quoted 5 lines
Quoted 4 lines

+               SPM Counter: <16-bit unsigned number display in base 10> +               Signing Key Public Key Modulus (base64):
+               KEK Public Key Modulus (base64):

Quoted 5 lines
Quoted 1 line

Is " (base64)" supposed to be part of the contents of the file?

The information reported for Signing Key and KEK public key are reported as base64 values.  It applies only to the data and not to the file contents.

Put is the file format:
KEK Public Key Modulus (base64): ...
KEK Public Key Modulus: ...

The docs indicate the former.

Quoted 17 lines
Quoted 17 lines

Documentation/ABI/testing/sysfs-class-firmware-attributes Description: · line 461

Quoted 9 lines
Documentation/ABI/testing/sysfs-class-firmware-attributes +8 -0
+
+
+What:                /sys/class/firmware-attributes/*/authentication/SPM/statusbin
+Date:                March 29
+KernelVersion:       5.18
+Contact:     "Jorge Lopez" <[email protected]>
+Description: 'statusbin' is a read-only file that returns identical status
+             information reported by 'status' file in binary format.

This documentation should contain enough information to understand the files contents.

I understand that one WMI call will return all the fields that are part of the "status" and "statusbin" in one response.

Quoted 6 lines
Quoted 3 lines

Are these WMI calls especially expensive or called especially frequently?

Unfortunately the WMI to read the Status binary data is expensive hence the reason of only calling once.

Hm, I still dislike the interface, sorry.
What about caching the values in the driver and exposing them via different files?

Quoted 6 lines
Quoted 3 lines

If not I would still argue to split them into one file per field and remove the statusbin file.

Regards,

Quoted 1 line

Jorge

#9 lore raw

Hi Thomas,

Quoted 19 lines · Thomas Weißschuh

Hi Jorge!

Apr 4, 2023 22:24:36 Jorge Lopez <[email protected]>:

Quoted 6 lines

Hi Thomas,

BTW, I decided to submit all files individually to facilitate the review process. Only Makefile and Kconfig files will be provided as a single patch.
I will be out of town until April 11 and will reply back upon my return.

Sorry for the slow response.

Quoted 4 lines

Please see my comments below.

Quoted 1 line
Quoted 8 lines
Quoted 4 lines
Quoted 4 lines

Documentation/ABI/testing/sysfs-class-firmware-attributes Description: · line 28

Quoted 4 lines
Documentation/ABI/testing/sysfs-class-firmware-attributes +4 -0
+             HP specific types
+             -----------------
+                     - ordered-list - a set of ordered list valid values
+                     - sure-start

But what does it mean?
For ordered-list there is a nice explanation.

The latest submission includes a short explanation

HP specific types
-----------------
- ordered-list - a set of ordered list valid values
- sure-start - report audit logs read from BIOS

Quoted 6 lines
Quoted 6 lines
Quoted 6 lines
Quoted 5 lines
Documentation/ABI/testing/sysfs-class-firmware-attributes +5 -0
+             audit_log_entry_count:
+                                     A read-only file that returns the number of existing audit log events available to be read.
+                                     Values are separated using comma (``,``)
+
+                                     [No of entries],[log entry size],[Max number of entries supported]
Quoted 8 lines
Quoted 6 lines
Quoted 3 lines

Will log entry size always be 16? Or can it be bigger in the future when more bytes are used?
This should be mentioned.

Log entry size is always 16 bytes in size. The reason is to report a maximum of 256 entries. Total 4096 bytes

Does it make sense to expose the number 16 from sysfs if it never can change anyways?

The current audit log file is 16 bytes but future BIOS can expand the audit log to up to 128 bytes.
Additional details are now included in the audit_log_entry_count section. WMI reports only the total number of audit logs but not the individual audit log size hence the reason the size is hardcoded to 16 bytes in the driver. A patch will be provided when the audit log size changes or a new WMI is provided.

Quoted 3 lines

Note you can also customize the filesize reported in sysfs to expose the maximum size to be used by userspace.

This is another area with additional details in the latest review.

"sure-start"-type specific properties:

audit_log_entries:
A read-only file that returns
the events in the log.
Values are separated using
semi-colon (``;``)

Audit log entry format

Byte 0-15: Requested Audit
Log entry (Each Audit log is 16 bytes)
Byte 16-127: Unused

audit_log_entry_count:
A read-only file that returns
the number of existing audit log events available to be read.
Values are separated using comma (``,``)

[No of entries],[log entry
size],[Max number of entries supported]

log entry size identifies
audit log size for the current BIOS version.
The current size is 16 bytes
but it can be to up to 128 bytes long
in future BIOS versions.

Quoted 8 lines
Quoted 5 lines
Quoted 3 lines

Is audit_log_entry_count ever used without reading audit_log_entries right after?

Yes. The counter is necessary to determine how many logs are available to be read.

I think the cleaner interface would be to have users provide a buffer to read into and then they check the return value of read(). Users can't trust the count value anyways as it is prone to TOCTOU races.

Audit logs buffer information includes an audit log number associated
with each log entry. The log number information is added by the
driver. The audit log is read as a single continuous buffer and the application does not read individual audit logs while reading sysfs. The application copies the whole buffer, extracts and identifies each audit log from its local buffer.

Byte 0:       Audit log number
Byte 1-16:  Audit log information
Quoted 29 lines
Quoted 23 lines
Quoted 4 lines

If not the count file could be dropped.

Quoted 12 lines

Documentation/ABI/testing/sysfs-class-firmware-attributes Description: · line 450

Quoted 10 lines
Documentation/ABI/testing/sysfs-class-firmware-attributes +10 -0
+What:                /sys/class/firmware-attributes/*/authentication/SPM/status
+Date:                March 29
+KernelVersion:       5.18
+Contact:     "Jorge Lopez" <[email protected]>
+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>

How are these bits to be interpreted?

This information is provided by BIOS. It is one of those obscure values from BIOS.

Quoted 5 lines
Quoted 4 lines
Documentation/ABI/testing/sysfs-class-firmware-attributes +3 -0
+               SPM Counter: <16-bit unsigned number display in base 10>
+               Signing Key Public Key Modulus (base64):
+               KEK Public Key Modulus (base64):
Quoted 5 lines
Quoted 1 line

Is " (base64)" supposed to be part of the contents of the file?

The information reported for Signing Key and KEK public key are reported as base64 values. It applies only to the data and not to the file contents.

Quoted 5 lines

Put is the file format:
KEK Public Key Modulus (base64): ...
KEK Public Key Modulus: ...

The docs indicate the former.

Also included in the last review is additional clarification on how the Modules are reported.

What:           /sys/class/firmware-attributes/*/authentication/SPM/status
Date:           March 29
KernelVersion:  5.18
Contact:        "Jorge Lopez" <[email protected]>
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): <256 bytes
base64 in hex>
KEK Public Key Modulus (base64): <256 bytes base64 in hex>

Quoted 18 lines
Quoted 18 lines
Quoted 18 lines

Documentation/ABI/testing/sysfs-class-firmware-attributes Description: · line 461

Quoted 10 lines
Documentation/ABI/testing/sysfs-class-firmware-attributes +8 -0
+
+
+What:                /sys/class/firmware-attributes/*/authentication/SPM/statusbin
+Date:                March 29
+KernelVersion:       5.18
+Contact:     "Jorge Lopez" <[email protected]>
+Description: 'statusbin' is a read-only file that returns identical status
+             information reported by 'status' file in binary format.

This documentation should contain enough information to understand the files contents.

I understand that one WMI call will return all the fields that are part of the "status" and "statusbin" in one response.

Quoted 8 lines
Quoted 6 lines
Quoted 3 lines

Are these WMI calls especially expensive or called especially frequently?

Unfortunately the WMI to read the Status binary data is expensive hence the reason of only calling once.

Hm, I still dislike the interface, sorry.

No worries. The implementation is a legacy from the Windows driver and security applications define it.

Quoted 1 line

What about caching the values in the driver and exposing them via different files?

The information changes as a group during the SPM configuration process so caching would not help much. Version field is the only field that can be cached.
If the information is split in difference files, there are conditions when the user would read stale data in one field or another.

Quoted 4 lines
Quoted 3 lines

Regards,

Quoted 1 line

Jorge