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 Supported types are "password" or "certificate". 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 Admin and System certificates are supported from 2025 systems onward. 307 308 certificate_thumbprint: 309 Read only attribute used to display the MD5, SHA1 and SHA256 thumbprints 310 for the certificate installed in the BIOS. 311 312 certificate_to_password: 313 Write only attribute used to switch from certificate based authentication 314 back to password based. 315 Usage:: 316 317 echo "signature" > authentication/Admin/signature 318 echo "password" > authentication/Admin/certificate_to_password 319 320 HP specific class extensions 321 -------------------------------- 322 323 On HP systems the following additional settings are available: 324 325 role: enhanced-bios-auth: 326 This role is specific to Secure Platform Management (SPM) attribute. 327 It requires configuring an endorsement (kek) and signing certificate (sk). 328 329 330What: /sys/class/firmware-attributes/*/attributes/pending_reboot 331Date: February 2021 332KernelVersion: 5.11 333Contact: Divya Bharathi <Divya.Bharathi@Dell.com>, 334 Prasanth KSR <prasanth.ksr@dell.com> 335 Dell.Client.Kernel@dell.com 336Description: 337 A read-only attribute reads 1 if a reboot is necessary to apply 338 pending BIOS attribute changes. Also, an uevent_KOBJ_CHANGE is 339 generated when it changes to 1. 340 341 == ========================================= 342 0 All BIOS attributes setting are current 343 1 A reboot is necessary to get pending BIOS 344 attribute changes applied 345 == ========================================= 346 347 Note, userspace applications need to follow below steps for efficient 348 BIOS management, 349 350 1. Check if admin password is set. If yes, follow session method for 351 password management as briefed under authentication section above. 352 2. Before setting any attribute, check if it has any modifiers 353 or value_modifiers. If yes, incorporate them and then modify 354 attribute. 355 356 Drivers may emit a CHANGE uevent when this value changes and userspace 357 may check it again. 358 359What: /sys/class/firmware-attributes/*/attributes/reset_bios 360Date: February 2021 361KernelVersion: 5.11 362Contact: Divya Bharathi <Divya.Bharathi@Dell.com>, 363 Prasanth KSR <prasanth.ksr@dell.com> 364 Dell.Client.Kernel@dell.com 365Description: 366 This attribute can be used to reset the BIOS Configuration. 367 Specifically, it tells which type of reset BIOS configuration is being 368 requested on the host. 369 370 Reading from it returns a list of supported options encoded as: 371 372 - 'builtinsafe' (Built in safe configuration profile) 373 - 'lastknowngood' (Last known good saved configuration profile) 374 - 'factory' (Default factory settings configuration profile) 375 - 'custom' (Custom saved configuration profile) 376 377 The currently selected option is printed in square brackets as 378 shown below:: 379 380 # echo "factory" > /sys/class/firmware-attributes/*/device/attributes/reset_bios 381 # cat /sys/class/firmware-attributes/*/device/attributes/reset_bios 382 builtinsafe lastknowngood [factory] custom 383 384 Note that any changes to this attribute requires a reboot 385 for changes to take effect. 386 387What: /sys/class/firmware-attributes/*/attributes/save_settings 388Date: August 2023 389KernelVersion: 6.6 390Contact: Mark Pearson <mpearson-lenovo@squebb.ca> 391Description: 392 On Lenovo platforms there is a limitation in the number of times an attribute can be 393 saved. This is an architectural limitation and it limits the number of attributes 394 that can be modified to 48. 395 A solution for this is instead of the attribute being saved after every modification, 396 to allow a user to bulk set the attributes, and then trigger a final save. This allows 397 unlimited attributes. 398 399 Read the attribute to check what save mode is enabled (single or bulk). 400 E.g: 401 # cat /sys/class/firmware-attributes/thinklmi/attributes/save_settings 402 single 403 404 Write the attribute with 'bulk' to enable bulk save mode. 405 Write the attribute with 'single' to enable saving, after every attribute set. 406 The default setting is single mode. 407 E.g: 408 # echo bulk > /sys/class/firmware-attributes/thinklmi/attributes/save_settings 409 410 When in bulk mode write 'save' to trigger a save of all currently modified attributes. 411 Note, once a save has been triggered, in bulk mode, attributes can no longer be set and 412 will return a permissions error. This is to prevent users hitting the 48+ save limitation 413 (which requires entering the BIOS to clear the error condition) 414 E.g: 415 # echo save > /sys/class/firmware-attributes/thinklmi/attributes/save_settings 416 417What: /sys/class/firmware-attributes/*/attributes/debug_cmd 418Date: July 2021 419KernelVersion: 5.14 420Contact: Mark Pearson <markpearson@lenovo.com> 421Description: 422 This write only attribute can be used to send debug commands to the BIOS. 423 This should only be used when recommended by the BIOS vendor. Vendors may 424 use it to enable extra debug attributes or BIOS features for testing purposes. 425 426 Note that any changes to this attribute requires a reboot for changes to take effect. 427 428 429 HP specific class extensions - Secure Platform Manager (SPM) 430 -------------------------------- 431 432What: /sys/class/firmware-attributes/*/authentication/SPM/kek 433Date: March 2023 434KernelVersion: 5.18 435Contact: "Jorge Lopez" <jorge.lopez2@hp.com> 436Description: 437 'kek' Key-Encryption-Key is a write-only file that can be used to configure the 438 RSA public key that will be used by the BIOS to verify 439 signatures when setting the signing key. When written, 440 the bytes should correspond to the KEK certificate 441 (x509 .DER format containing an OU). The size of the 442 certificate must be less than or equal to 4095 bytes. 443 444What: /sys/class/firmware-attributes/*/authentication/SPM/sk 445Date: March 2023 446KernelVersion: 5.18 447Contact: "Jorge Lopez" <jorge.lopez2@hp.com> 448Description: 449 'sk' Signature Key is a write-only file that can be used to configure the RSA 450 public key that will be used by the BIOS to verify signatures 451 when configuring BIOS settings and security features. When 452 written, the bytes should correspond to the modulus of the 453 public key. The exponent is assumed to be 0x10001. 454 455What: /sys/class/firmware-attributes/*/authentication/SPM/status 456Date: March 2023 457KernelVersion: 5.18 458Contact: "Jorge Lopez" <jorge.lopez2@hp.com> 459Description: 460 'status' is a read-only file that returns ASCII text in JSON format reporting 461 the status information. 462 463 "State": "not provisioned | provisioned | provisioning in progress", 464 "Version": "Major.Minor", 465 "Nonce": <16-bit unsigned number display in base 10>, 466 "FeaturesInUse": <16-bit unsigned number display in base 10>, 467 "EndorsementKeyMod": "<256 bytes in base64>", 468 "SigningKeyMod": "<256 bytes in base64>" 469 470What: /sys/class/firmware-attributes/*/attributes/Sure_Start/audit_log_entries 471Date: March 2023 472KernelVersion: 5.18 473Contact: "Jorge Lopez" <jorge.lopez2@hp.com> 474Description: 475 'audit_log_entries' is a read-only file that returns the events in the log. 476 477 Audit log entry format 478 479 Byte 0-15: Requested Audit Log entry (Each Audit log is 16 bytes) 480 Byte 16-127: Unused 481 482What: /sys/class/firmware-attributes/*/attributes/Sure_Start/audit_log_entry_count 483Date: March 2023 484KernelVersion: 5.18 485Contact: "Jorge Lopez" <jorge.lopez2@hp.com> 486Description: 487 'audit_log_entry_count' is a read-only file that returns the number of existing 488 audit log events available to be read. Values are separated using comma. (``,``) 489 490 [No of entries],[log entry size],[Max number of entries supported] 491 492 log entry size identifies audit log size for the current BIOS version. 493 The current size is 16 bytes but it can be up to 128 bytes long in future BIOS 494 versions. 495