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/save_settings 387Date: August 2023 388KernelVersion: 6.6 389Contact: Mark Pearson <mpearson-lenovo@squebb.ca> 390Description: 391 On Lenovo platforms there is a limitation in the number of times an attribute can be 392 saved. This is an architectural limitation and it limits the number of attributes 393 that can be modified to 48. 394 A solution for this is instead of the attribute being saved after every modification, 395 to allow a user to bulk set the attributes, and then trigger a final save. This allows 396 unlimited attributes. 397 398 Read the attribute to check what save mode is enabled (single or bulk). 399 E.g: 400 # cat /sys/class/firmware-attributes/thinklmi/attributes/save_settings 401 single 402 403 Write the attribute with 'bulk' to enable bulk save mode. 404 Write the attribute with 'single' to enable saving, after every attribute set. 405 The default setting is single mode. 406 E.g: 407 # echo bulk > /sys/class/firmware-attributes/thinklmi/attributes/save_settings 408 409 When in bulk mode write 'save' to trigger a save of all currently modified attributes. 410 Note, once a save has been triggered, in bulk mode, attributes can no longer be set and 411 will return a permissions error. This is to prevent users hitting the 48+ save limitation 412 (which requires entering the BIOS to clear the error condition) 413 E.g: 414 # echo save > /sys/class/firmware-attributes/thinklmi/attributes/save_settings 415 416What: /sys/class/firmware-attributes/*/attributes/debug_cmd 417Date: July 2021 418KernelVersion: 5.14 419Contact: Mark Pearson <markpearson@lenovo.com> 420Description: 421 This write only attribute can be used to send debug commands to the BIOS. 422 This should only be used when recommended by the BIOS vendor. Vendors may 423 use it to enable extra debug attributes or BIOS features for testing purposes. 424 425 Note that any changes to this attribute requires a reboot for changes to take effect. 426 427 428 HP specific class extensions - Secure Platform Manager (SPM) 429 -------------------------------- 430 431What: /sys/class/firmware-attributes/*/authentication/SPM/kek 432Date: March 2023 433KernelVersion: 5.18 434Contact: "Jorge Lopez" <jorge.lopez2@hp.com> 435Description: 436 'kek' Key-Encryption-Key is a write-only file that can be used to configure the 437 RSA public key that will be used by the BIOS to verify 438 signatures when setting the signing key. When written, 439 the bytes should correspond to the KEK certificate 440 (x509 .DER format containing an OU). The size of the 441 certificate must be less than or equal to 4095 bytes. 442 443What: /sys/class/firmware-attributes/*/authentication/SPM/sk 444Date: March 2023 445KernelVersion: 5.18 446Contact: "Jorge Lopez" <jorge.lopez2@hp.com> 447Description: 448 'sk' Signature Key is a write-only file that can be used to configure the RSA 449 public key that will be used by the BIOS to verify signatures 450 when configuring BIOS settings and security features. When 451 written, the bytes should correspond to the modulus of the 452 public key. The exponent is assumed to be 0x10001. 453 454What: /sys/class/firmware-attributes/*/authentication/SPM/status 455Date: March 2023 456KernelVersion: 5.18 457Contact: "Jorge Lopez" <jorge.lopez2@hp.com> 458Description: 459 'status' is a read-only file that returns ASCII text in JSON format reporting 460 the status information. 461 462 "State": "not provisioned | provisioned | provisioning in progress", 463 "Version": "Major.Minor", 464 "Nonce": <16-bit unsigned number display in base 10>, 465 "FeaturesInUse": <16-bit unsigned number display in base 10>, 466 "EndorsementKeyMod": "<256 bytes in base64>", 467 "SigningKeyMod": "<256 bytes in base64>" 468 469What: /sys/class/firmware-attributes/*/attributes/Sure_Start/audit_log_entries 470Date: March 2023 471KernelVersion: 5.18 472Contact: "Jorge Lopez" <jorge.lopez2@hp.com> 473Description: 474 'audit_log_entries' is a read-only file that returns the events in the log. 475 476 Audit log entry format 477 478 Byte 0-15: Requested Audit Log entry (Each Audit log is 16 bytes) 479 Byte 16-127: Unused 480 481What: /sys/class/firmware-attributes/*/attributes/Sure_Start/audit_log_entry_count 482Date: March 2023 483KernelVersion: 5.18 484Contact: "Jorge Lopez" <jorge.lopez2@hp.com> 485Description: 486 'audit_log_entry_count' is a read-only file that returns the number of existing 487 audit log events available to be read. Values are separated using comma. (``,``) 488 489 [No of entries],[log entry size],[Max number of entries supported] 490 491 log entry size identifies audit log size for the current BIOS version. 492 The current size is 16 bytes but it can be up to 128 bytes long in future BIOS 493 versions. 494