1What:		/sys/class/firmware-attributes/*/attributes/*/
2Date:		February 2021
3KernelVersion:	5.11
4Contact:	Divya Bharathi <Divya.Bharathi@Dell.com>,
5		Prasanth KSR <prasanth.ksr@dell.com>
6		Dell.Client.Kernel@dell.com
7Description:
8		A sysfs interface for systems management software to enable
9		configuration capability on supported systems.  This directory
10		exposes interfaces for interacting with configuration options.
11
12		Unless otherwise specified in an attribute description all attributes are optional
13		and will accept UTF-8 input.
14
15		type:
16		    A file that can be read to obtain the type of attribute.
17		    This attribute is mandatory.
18
19		The following are known types:
20
21			- enumeration: a set of pre-defined valid values
22			- integer: a range of numerical values
23			- string
24
25		HP specific types
26		-----------------
27			- ordered-list - a set of ordered list valid values
28
29
30		All attribute types support the following values:
31
32		current_value:
33				A file that can be read to obtain the current
34				value of the <attr>.
35
36				This file can also be written to in order to update the value of a
37				<attr>
38
39				This attribute is mandatory.
40
41		default_value:
42				A file that can be read to obtain the default
43				value of the <attr>
44
45		display_name:
46				A file that can be read to obtain a user friendly
47				description of the at <attr>
48
49		display_name_language_code:
50						A file that can be read to obtain
51						the IETF language tag corresponding to the
52						"display_name" of the <attr>
53
54		"enumeration"-type specific properties:
55
56		possible_values:
57					A file that can be read to obtain the possible
58					values of the <attr>. Values are separated using
59					semi-colon (``;``).
60
61		"integer"-type specific properties:
62
63		min_value:
64				A file that can be read to obtain the lower
65				bound value of the <attr>
66
67		max_value:
68				A file that can be read to obtain the upper
69				bound value of the <attr>
70
71		scalar_increment:
72					A file that can be read to obtain the scalar value used for
73					increments of current_value this attribute accepts.
74
75		"string"-type specific properties:
76
77		max_length:
78				A file that can be read to obtain the maximum
79				length value of the <attr>
80
81		min_length:
82				A file that can be read to obtain the minimum
83				length value of the <attr>
84
85		Dell specific class extensions
86		------------------------------
87
88		On Dell systems the following additional attributes are available:
89
90		dell_modifier:
91				A file that can be read to obtain attribute-level
92				dependency rule. It says an attribute X will become read-only or
93				suppressed, if/if-not attribute Y is configured.
94
95				modifier rules can be in following format::
96
97				    [ReadOnlyIf:<attribute>=<value>]
98				    [ReadOnlyIfNot:<attribute>=<value>]
99				    [SuppressIf:<attribute>=<value>]
100				    [SuppressIfNot:<attribute>=<value>]
101
102				For example::
103
104				    AutoOnFri/dell_modifier has value,
105					    [SuppressIfNot:AutoOn=SelectDays]
106
107				This means AutoOnFri will be suppressed in BIOS setup if AutoOn
108				attribute is not "SelectDays" and its value will not be effective
109				through sysfs until this rule is met.
110
111		Enumeration attributes also support the following:
112
113		dell_value_modifier:
114					A file that can be read to obtain value-level dependency.
115					This file is similar to dell_modifier but here,	an
116					attribute's current value will be forcefully changed based
117					dependent attributes value.
118
119					dell_value_modifier rules can be in following format::
120
121					    <value>[ForceIf:<attribute>=<value>]
122					    <value>[ForceIfNot:<attribute>=<value>]
123
124					For example::
125
126					    LegacyOrom/dell_value_modifier has value:
127						    Disabled[ForceIf:SecureBoot=Enabled]
128
129					This means LegacyOrom's current value will be forced to
130					"Disabled" in BIOS setup if SecureBoot is Enabled and its
131					value will not be effective through sysfs until this rule is
132					met.
133
134		HP specific class extensions
135		------------------------------
136
137		On HP systems the following additional attributes are available:
138
139		"ordered-list"-type specific properties:
140
141		elements:
142					A file that can be read to obtain the possible
143					list of values of the <attr>. Values are separated using
144					semi-colon (``;``) and listed according to their priority.
145					An element listed first has the highest priority. Writing
146					the list in a different order to current_value alters
147					the priority order for the particular attribute.
148
149What:		/sys/class/firmware-attributes/*/authentication/
150Date:		February 2021
151KernelVersion:	5.11
152Contact:	Divya Bharathi <Divya.Bharathi@Dell.com>,
153		Prasanth KSR <prasanth.ksr@dell.com>
154		Dell.Client.Kernel@dell.com
155Description:
156		Devices support various authentication mechanisms which can be exposed
157		as a separate configuration object.
158
159		For example a "BIOS Admin" password and "System" Password can be set,
160		reset or cleared using these attributes.
161
162		- An "Admin" password is used for preventing modification to the BIOS
163		  settings.
164		- A "System" password is required to boot a machine.
165
166		Change in any of these two authentication methods will also generate an
167		uevent KOBJ_CHANGE.
168
169		is_enabled:
170					A file that can be read to obtain a 0/1 flag to see if
171					<attr> authentication is enabled.
172					This attribute is mandatory.
173
174		role:
175					The type of authentication used.
176					This attribute is mandatory.
177
178					Known types:
179						bios-admin:
180							Representing BIOS administrator password
181						power-on:
182							Representing a password required to use
183							the system
184						system-mgmt:
185							Representing System Management password.
186							See Lenovo extensions section for details
187						HDD:
188							Representing HDD password
189							See Lenovo extensions section for details
190						NVMe:
191							Representing NVMe password
192							See Lenovo extensions section for details
193
194		mechanism:
195					The means of authentication.  This attribute is mandatory.
196					Only supported type currently is "password".
197
198		max_password_length:
199					A file that can be read to obtain the
200					maximum length of the Password
201
202		min_password_length:
203					A file that can be read to obtain the
204					minimum length of the Password
205
206		current_password:
207					A write only value used for privileged access such as
208					setting	attributes when a system or admin password is set
209					or resetting to a new password
210
211					This attribute is mandatory when mechanism == "password".
212
213		new_password:
214					A write only value that when used in tandem with
215					current_password will reset a system or admin password.
216
217		Note, password management is session specific. If Admin password is set,
218		same password must be written into current_password file (required for
219		password-validation) and must be cleared once the session is over.
220		For example::
221
222			echo "password" > current_password
223			echo "disabled" > TouchScreen/current_value
224			echo "" > current_password
225
226		Drivers may emit a CHANGE uevent when a password is set or unset
227		userspace may check it again.
228
229		On Dell, Lenovo and HP systems, if Admin password is set, then all BIOS attributes
230		require password validation.
231		On Lenovo systems if you change the Admin password the new password is not active until
232		the next boot.
233
234		Lenovo specific class extensions
235		--------------------------------
236
237		On Lenovo systems the following additional settings are available:
238
239		role: system-mgmt	This gives the same authority as the bios-admin password to control
240					security related features. The authorities allocated can be set via
241					the BIOS menu SMP Access Control Policy
242
243		role: HDD & NVMe	This password is used to unlock access to the drive at boot. Note see
244					'level' and 'index' extensions below.
245
246		lenovo_encoding:
247					The encoding method that is used. This can be either "ascii"
248					or "scancode". Default is set to "ascii"
249
250		lenovo_kbdlang:
251					The keyboard language method that is used. This is generally a
252					two char code (e.g. "us", "fr", "gr") and may vary per platform.
253					Default is set to "us"
254
255		level:
256					Available for HDD and NVMe authentication to set 'user' or 'master'
257					privilege level.
258					If only the user password is configured then this should be used to
259					unlock the drive at boot. If both master and user passwords are set
260					then either can be used. If a master password is set a user password
261					is required.
262					This attribute defaults to 'user' level
263
264		index:
265					Used with HDD and NVME authentication to set the drive index
266					that is being referenced (e.g hdd1, hdd2 etc)
267					This attribute defaults to device 1.
268
269		certificate, signature, save_signature:
270					These attributes are used for certificate based authentication. This is
271					used in conjunction with a signing server as an alternative to password
272					based authentication.
273					The user writes to the attribute(s) with a BASE64 encoded string obtained
274					from the signing server.
275					The attributes can be displayed to check the stored value.
276
277					Some usage examples:
278
279						Installing a certificate to enable feature::
280
281							echo "supervisor password" > authentication/Admin/current_password
282							echo "signed certificate" > authentication/Admin/certificate
283
284						Updating the installed certificate::
285
286							echo "signature" > authentication/Admin/signature
287							echo "signed certificate" > authentication/Admin/certificate
288
289						Removing the installed certificate::
290
291							echo "signature" > authentication/Admin/signature
292							echo "" > authentication/Admin/certificate
293
294						Changing a BIOS setting::
295
296							echo "signature" > authentication/Admin/signature
297							echo "save signature" > authentication/Admin/save_signature
298							echo Enable > attribute/PasswordBeep/current_value
299
300					You cannot enable certificate authentication if a supervisor password
301					has not been set.
302					Clearing the certificate results in no bios-admin authentication method
303					being configured allowing anyone to make changes.
304					After any of these operations the system must reboot for the changes to
305					take effect.
306
307		certificate_thumbprint:
308					Read only attribute used to display the MD5, SHA1 and SHA256 thumbprints
309					for the certificate installed in the BIOS.
310
311		certificate_to_password:
312					Write only attribute used to switch from certificate based authentication
313					back to password based.
314					Usage::
315
316						echo "signature" > authentication/Admin/signature
317						echo "password" > authentication/Admin/certificate_to_password
318
319		HP specific class extensions
320		--------------------------------
321
322		On HP systems the following additional settings are available:
323
324		role: enhanced-bios-auth:
325					This role is specific to Secure Platform Management (SPM) attribute.
326					It requires configuring an endorsement (kek) and signing certificate (sk).
327
328
329What:		/sys/class/firmware-attributes/*/attributes/pending_reboot
330Date:		February 2021
331KernelVersion:	5.11
332Contact:	Divya Bharathi <Divya.Bharathi@Dell.com>,
333		Prasanth KSR <prasanth.ksr@dell.com>
334		Dell.Client.Kernel@dell.com
335Description:
336		A read-only attribute reads 1 if a reboot is necessary to apply
337		pending BIOS attribute changes. Also, an uevent_KOBJ_CHANGE is
338		generated when it changes to 1.
339
340			==	=========================================
341			0	All BIOS attributes setting are current
342			1	A reboot is necessary to get pending BIOS
343				attribute changes applied
344			==	=========================================
345
346		Note, userspace applications need to follow below steps for efficient
347		BIOS management,
348
349		1.	Check if admin password is set. If yes, follow session method for
350			password management as briefed under authentication section above.
351		2.	Before setting any attribute, check if it has any modifiers
352			or value_modifiers. If yes, incorporate them and then modify
353			attribute.
354
355		Drivers may emit a CHANGE uevent when this value changes and userspace
356		may check it again.
357
358What:		/sys/class/firmware-attributes/*/attributes/reset_bios
359Date:		February 2021
360KernelVersion:	5.11
361Contact:	Divya Bharathi <Divya.Bharathi@Dell.com>,
362		Prasanth KSR <prasanth.ksr@dell.com>
363		Dell.Client.Kernel@dell.com
364Description:
365		This attribute can be used to reset the BIOS Configuration.
366		Specifically, it tells which type of reset BIOS configuration is being
367		requested on the host.
368
369		Reading from it returns a list of supported options encoded as:
370
371			- 'builtinsafe' (Built in safe configuration profile)
372			- 'lastknowngood' (Last known good saved configuration profile)
373			- 'factory' (Default factory settings configuration profile)
374			- 'custom' (Custom saved configuration profile)
375
376		The currently selected option is printed in square brackets as
377		shown below::
378
379		    # echo "factory" > /sys/class/firmware-attributes/*/device/attributes/reset_bios
380		    # cat /sys/class/firmware-attributes/*/device/attributes/reset_bios
381		    builtinsafe lastknowngood [factory] custom
382
383		Note that any changes to this attribute requires a reboot
384		for changes to take effect.
385
386What:		/sys/class/firmware-attributes/*/attributes/debug_cmd
387Date:		July 2021
388KernelVersion:	5.14
389Contact:	Mark Pearson <markpearson@lenovo.com>
390Description:
391		This write only attribute can be used to send debug commands to the BIOS.
392		This should only be used when recommended by the BIOS vendor. Vendors may
393		use it to enable extra debug attributes or BIOS features for testing purposes.
394
395		Note that any changes to this attribute requires a reboot for changes to take effect.
396
397
398		HP specific class extensions - Secure Platform Manager (SPM)
399		--------------------------------
400
401What:		/sys/class/firmware-attributes/*/authentication/SPM/kek
402Date:		March 2023
403KernelVersion:	5.18
404Contact:	"Jorge Lopez" <jorge.lopez2@hp.com>
405Description:
406		'kek' Key-Encryption-Key is a write-only file that can be used to configure the
407		RSA public key that will be used by the BIOS to verify
408		signatures when setting the signing key.  When written,
409		the bytes should correspond to the KEK certificate
410		(x509 .DER format containing an OU).  The size of the
411		certificate must be less than or equal to 4095 bytes.
412
413What:		/sys/class/firmware-attributes/*/authentication/SPM/sk
414Date:		March 2023
415KernelVersion:	5.18
416Contact:	"Jorge Lopez" <jorge.lopez2@hp.com>
417Description:
418		'sk' Signature Key is a write-only file that can be used to configure the RSA
419		public key that will be used by the BIOS to verify signatures
420		when configuring BIOS settings and security features.  When
421		written, the bytes should correspond to the modulus of the
422		public key.  The exponent is assumed to be 0x10001.
423
424What:		/sys/class/firmware-attributes/*/authentication/SPM/status
425Date:		March 2023
426KernelVersion:	5.18
427Contact:	"Jorge Lopez" <jorge.lopez2@hp.com>
428Description:
429		'status' is a read-only file that returns ASCII text in JSON format reporting
430		the status information.
431
432		  "State": "not provisioned | provisioned | provisioning in progress",
433		  "Version": "Major.Minor",
434		  "Nonce": <16-bit unsigned number display in base 10>,
435		  "FeaturesInUse": <16-bit unsigned number display in base 10>,
436		  "EndorsementKeyMod": "<256 bytes in base64>",
437		  "SigningKeyMod": "<256 bytes in base64>"
438
439What:		/sys/class/firmware-attributes/*/attributes/Sure_Start/audit_log_entries
440Date:		March 2023
441KernelVersion:	5.18
442Contact:	"Jorge Lopez" <jorge.lopez2@hp.com>
443Description:
444		'audit_log_entries' is a read-only file that returns the events in the log.
445
446			Audit log entry format
447
448			Byte 0-15:   Requested Audit Log entry  (Each Audit log is 16 bytes)
449			Byte 16-127: Unused
450
451What:		/sys/class/firmware-attributes/*/attributes/Sure_Start/audit_log_entry_count
452Date:		March 2023
453KernelVersion:	5.18
454Contact:	"Jorge Lopez" <jorge.lopez2@hp.com>
455Description:
456		'audit_log_entry_count' is a read-only file that returns the number of existing
457		audit log events available to be read. Values are separated using comma. (``,``)
458
459			[No of entries],[log entry size],[Max number of entries supported]
460
461		log entry size identifies audit log size for the current BIOS version.
462		The current size is 16 bytes but it can be up to 128 bytes long in future BIOS
463		versions.
464