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                                         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
 329 What:           /sys/class/firmware-attributes/*/attributes/pending_reboot
 330 Date:           February 2021
 331 KernelVersion:  5.11
 332 Contact:        Divya Bharathi <Divya.Bharathi@Dell.com>,
 333                 Prasanth KSR <prasanth.ksr@dell.com>
 334                 Dell.Client.Kernel@dell.com
 335 Description:
 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
 358 What:           /sys/class/firmware-attributes/*/attributes/reset_bios
 359 Date:           February 2021
 360 KernelVersion:  5.11
 361 Contact:        Divya Bharathi <Divya.Bharathi@Dell.com>,
 362                 Prasanth KSR <prasanth.ksr@dell.com>
 363                 Dell.Client.Kernel@dell.com
 364 Description:
 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
 386 What:           /sys/class/firmware-attributes/*/attributes/save_settings
 387 Date:           August 2023
 388 KernelVersion:  6.6
 389 Contact:        Mark Pearson <mpearson-lenovo@squebb.ca>
 390 Description:
 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
 416 What:           /sys/class/firmware-attributes/*/attributes/debug_cmd
 417 Date:           July 2021
 418 KernelVersion:  5.14
 419 Contact:        Mark Pearson <markpearson@lenovo.com>
 420 Description:
 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
 431 What:           /sys/class/firmware-attributes/*/authentication/SPM/kek
 432 Date:           March 2023
 433 KernelVersion:  5.18
 434 Contact:        "Jorge Lopez" <jorge.lopez2@hp.com>
 435 Description:
 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
 443 What:           /sys/class/firmware-attributes/*/authentication/SPM/sk
 444 Date:           March 2023
 445 KernelVersion:  5.18
 446 Contact:        "Jorge Lopez" <jorge.lopez2@hp.com>
 447 Description:
 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
 454 What:           /sys/class/firmware-attributes/*/authentication/SPM/status
 455 Date:           March 2023
 456 KernelVersion:  5.18
 457 Contact:        "Jorge Lopez" <jorge.lopez2@hp.com>
 458 Description:
 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
 469 What:           /sys/class/firmware-attributes/*/attributes/Sure_Start/audit_log_entries
 470 Date:           March 2023
 471 KernelVersion:  5.18
 472 Contact:        "Jorge Lopez" <jorge.lopez2@hp.com>
 473 Description:
 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
 481 What:           /sys/class/firmware-attributes/*/attributes/Sure_Start/audit_log_entry_count
 482 Date:           March 2023
 483 KernelVersion:  5.18
 484 Contact:        "Jorge Lopez" <jorge.lopez2@hp.com>
 485 Description:
 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.