Documentation/ABI/testing/sysfs-class-firmware-attributes

   1 What:           /sys/class/firmware-attributes/*/attributes/*/
   2 Date:           February 2021
   3 KernelVersion:  5.11
   4 Contact:        Divya Bharathi <Divya.Bharathi@Dell.com>,
   5                 Prasanth KSR <prasanth.ksr@dell.com>
   6                 Dell.Client.Kernel@dell.com
   7 Description:
   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
 149 What:           /sys/class/firmware-attributes/*/authentication/
 150 Date:           February 2021
 151 KernelVersion:  5.11
 152 Contact:        Divya Bharathi <Divya.Bharathi@Dell.com>,
 153                 Prasanth KSR <prasanth.ksr@dell.com>
 154                 Dell.Client.Kernel@dell.com
 155 Description:
 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
 330 What:           /sys/class/firmware-attributes/*/attributes/pending_reboot
 331 Date:           February 2021
 332 KernelVersion:  5.11
 333 Contact:        Divya Bharathi <Divya.Bharathi@Dell.com>,
 334                 Prasanth KSR <prasanth.ksr@dell.com>
 335                 Dell.Client.Kernel@dell.com
 336 Description:
 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
 359 What:           /sys/class/firmware-attributes/*/attributes/reset_bios
 360 Date:           February 2021
 361 KernelVersion:  5.11
 362 Contact:        Divya Bharathi <Divya.Bharathi@Dell.com>,
 363                 Prasanth KSR <prasanth.ksr@dell.com>
 364                 Dell.Client.Kernel@dell.com
 365 Description:
 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
 387 What:           /sys/class/firmware-attributes/*/attributes/save_settings
 388 Date:           August 2023
 389 KernelVersion:  6.6
 390 Contact:        Mark Pearson <mpearson-lenovo@squebb.ca>
 391 Description:
 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
 417 What:           /sys/class/firmware-attributes/*/attributes/debug_cmd
 418 Date:           July 2021
 419 KernelVersion:  5.14
 420 Contact:        Mark Pearson <markpearson@lenovo.com>
 421 Description:
 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
 432 What:           /sys/class/firmware-attributes/*/authentication/SPM/kek
 433 Date:           March 2023
 434 KernelVersion:  5.18
 435 Contact:        "Jorge Lopez" <jorge.lopez2@hp.com>
 436 Description:
 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
 444 What:           /sys/class/firmware-attributes/*/authentication/SPM/sk
 445 Date:           March 2023
 446 KernelVersion:  5.18
 447 Contact:        "Jorge Lopez" <jorge.lopez2@hp.com>
 448 Description:
 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
 455 What:           /sys/class/firmware-attributes/*/authentication/SPM/status
 456 Date:           March 2023
 457 KernelVersion:  5.18
 458 Contact:        "Jorge Lopez" <jorge.lopez2@hp.com>
 459 Description:
 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
 470 What:           /sys/class/firmware-attributes/*/attributes/Sure_Start/audit_log_entries
 471 Date:           March 2023
 472 KernelVersion:  5.18
 473 Contact:        "Jorge Lopez" <jorge.lopez2@hp.com>
 474 Description:
 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
 482 What:           /sys/class/firmware-attributes/*/attributes/Sure_Start/audit_log_entry_count
 483 Date:           March 2023
 484 KernelVersion:  5.18
 485 Contact:        "Jorge Lopez" <jorge.lopez2@hp.com>
 486 Description:
 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.