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                 All attribute types support the following values:
  26
  27                 current_value:
  28                                 A file that can be read to obtain the current
  29                                 value of the <attr>.
  30
  31                                 This file can also be written to in order to update the value of a
  32                                 <attr>
  33
  34                                 This attribute is mandatory.
  35
  36                 default_value:
  37                                 A file that can be read to obtain the default
  38                                 value of the <attr>
  39
  40                 display_name:
  41                                 A file that can be read to obtain a user friendly
  42                                 description of the at <attr>
  43
  44                 display_name_language_code:
  45                                                 A file that can be read to obtain
  46                                                 the IETF language tag corresponding to the
  47                                                 "display_name" of the <attr>
  48
  49                 "enumeration"-type specific properties:
  50
  51                 possible_values:
  52                                         A file that can be read to obtain the possible
  53                                         values of the <attr>. Values are separated using
  54                                         semi-colon (``;``).
  55
  56                 "integer"-type specific properties:
  57
  58                 min_value:
  59                                 A file that can be read to obtain the lower
  60                                 bound value of the <attr>
  61
  62                 max_value:
  63                                 A file that can be read to obtain the upper
  64                                 bound value of the <attr>
  65
  66                 scalar_increment:
  67                                         A file that can be read to obtain the scalar value used for
  68                                         increments of current_value this attribute accepts.
  69
  70                 "string"-type specific properties:
  71
  72                 max_length:
  73                                 A file that can be read to obtain the maximum
  74                                 length value of the <attr>
  75
  76                 min_length:
  77                                 A file that can be read to obtain the minimum
  78                                 length value of the <attr>
  79
  80                 Dell specific class extensions
  81                 ------------------------------
  82
  83                 On Dell systems the following additional attributes are available:
  84
  85                 dell_modifier:
  86                                 A file that can be read to obtain attribute-level
  87                                 dependency rule. It says an attribute X will become read-only or
  88                                 suppressed, if/if-not attribute Y is configured.
  89
  90                                 modifier rules can be in following format::
  91
  92                                     [ReadOnlyIf:<attribute>=<value>]
  93                                     [ReadOnlyIfNot:<attribute>=<value>]
  94                                     [SuppressIf:<attribute>=<value>]
  95                                     [SuppressIfNot:<attribute>=<value>]
  96
  97                                 For example::
  98
  99                                     AutoOnFri/dell_modifier has value,
 100                                             [SuppressIfNot:AutoOn=SelectDays]
 101
 102                                 This means AutoOnFri will be suppressed in BIOS setup if AutoOn
 103                                 attribute is not "SelectDays" and its value will not be effective
 104                                 through sysfs until this rule is met.
 105
 106                 Enumeration attributes also support the following:
 107
 108                 dell_value_modifier:
 109                                         A file that can be read to obtain value-level dependency.
 110                                         This file is similar to dell_modifier but here, an
 111                                         attribute's current value will be forcefully changed based
 112                                         dependent attributes value.
 113
 114                                         dell_value_modifier rules can be in following format::
 115
 116                                             <value>[ForceIf:<attribute>=<value>]
 117                                             <value>[ForceIfNot:<attribute>=<value>]
 118
 119                                         For example::
 120
 121                                             LegacyOrom/dell_value_modifier has value:
 122                                                     Disabled[ForceIf:SecureBoot=Enabled]
 123
 124                                         This means LegacyOrom's current value will be forced to
 125                                         "Disabled" in BIOS setup if SecureBoot is Enabled and its
 126                                         value will not be effective through sysfs until this rule is
 127                                         met.
 128
 129 What:           /sys/class/firmware-attributes/*/authentication/
 130 Date:           February 2021
 131 KernelVersion:  5.11
 132 Contact:        Divya Bharathi <Divya.Bharathi@Dell.com>,
 133                 Prasanth KSR <prasanth.ksr@dell.com>
 134                 Dell.Client.Kernel@dell.com
 135 Description:
 136                 Devices support various authentication mechanisms which can be exposed
 137                 as a separate configuration object.
 138
 139                 For example a "BIOS Admin" password and "System" Password can be set,
 140                 reset or cleared using these attributes.
 141
 142                 - An "Admin" password is used for preventing modification to the BIOS
 143                   settings.
 144                 - A "System" password is required to boot a machine.
 145
 146                 Change in any of these two authentication methods will also generate an
 147                 uevent KOBJ_CHANGE.
 148
 149                 is_enabled:
 150                                         A file that can be read to obtain a 0/1 flag to see if
 151                                         <attr> authentication is enabled.
 152                                         This attribute is mandatory.
 153
 154                 role:
 155                                         The type of authentication used.
 156                                         This attribute is mandatory.
 157
 158                                         Known types:
 159                                                 bios-admin:
 160                                                         Representing BIOS administrator password
 161                                                 power-on:
 162                                                         Representing a password required to use
 163                                                         the system
 164                                                 system-mgmt:
 165                                                         Representing System Management password.
 166                                                         See Lenovo extensions section for details
 167                                                 HDD:
 168                                                         Representing HDD password
 169                                                         See Lenovo extensions section for details
 170                                                 NVMe:
 171                                                         Representing NVMe password
 172                                                         See Lenovo extensions section for details
 173
 174                 mechanism:
 175                                         The means of authentication.  This attribute is mandatory.
 176                                         Only supported type currently is "password".
 177
 178                 max_password_length:
 179                                         A file that can be read to obtain the
 180                                         maximum length of the Password
 181
 182                 min_password_length:
 183                                         A file that can be read to obtain the
 184                                         minimum length of the Password
 185
 186                 current_password:
 187                                         A write only value used for privileged access such as
 188                                         setting attributes when a system or admin password is set
 189                                         or resetting to a new password
 190
 191                                         This attribute is mandatory when mechanism == "password".
 192
 193                 new_password:
 194                                         A write only value that when used in tandem with
 195                                         current_password will reset a system or admin password.
 196
 197                 Note, password management is session specific. If Admin password is set,
 198                 same password must be written into current_password file (required for
 199                 password-validation) and must be cleared once the session is over.
 200                 For example::
 201
 202                         echo "password" > current_password
 203                         echo "disabled" > TouchScreen/current_value
 204                         echo "" > current_password
 205
 206                 Drivers may emit a CHANGE uevent when a password is set or unset
 207                 userspace may check it again.
 208
 209                 On Dell and Lenovo systems, if Admin password is set, then all BIOS attributes
 210                 require password validation.
 211                 On Lenovo systems if you change the Admin password the new password is not active until
 212                 the next boot.
 213
 214                 Lenovo specific class extensions
 215                 --------------------------------
 216
 217                 On Lenovo systems the following additional settings are available:
 218
 219                 role: system-mgmt       This gives the same authority as the bios-admin password to control
 220                                         security related features. The authorities allocated can be set via
 221                                         the BIOS menu SMP Access Control Policy
 222
 223                 role: HDD & NVMe        This password is used to unlock access to the drive at boot. Note see
 224                                         'level' and 'index' extensions below.
 225
 226                 lenovo_encoding:
 227                                         The encoding method that is used. This can be either "ascii"
 228                                         or "scancode". Default is set to "ascii"
 229
 230                 lenovo_kbdlang:
 231                                         The keyboard language method that is used. This is generally a
 232                                         two char code (e.g. "us", "fr", "gr") and may vary per platform.
 233                                         Default is set to "us"
 234
 235                 level:
 236                                         Available for HDD and NVMe authentication to set 'user' or 'master'
 237                                         privilege level.
 238                                         If only the user password is configured then this should be used to
 239                                         unlock the drive at boot. If both master and user passwords are set
 240                                         then either can be used. If a master password is set a user password
 241                                         is required.
 242                                         This attribute defaults to 'user' level
 243
 244                 index:
 245                                         Used with HDD and NVME authentication to set the drive index
 246                                         that is being referenced (e.g hdd0, hdd1 etc)
 247                                         This attribute defaults to device 0.
 248
 249                 certificate, signature, save_signature:
 250                                         These attributes are used for certificate based authentication. This is
 251                                         used in conjunction with a signing server as an alternative to password
 252                                         based authentication.
 253                                         The user writes to the attribute(s) with a BASE64 encoded string obtained
 254                                         from the signing server.
 255                                         The attributes can be displayed to check the stored value.
 256
 257                                         Some usage examples:
 258
 259                                                 Installing a certificate to enable feature::
 260
 261                                                         echo "supervisor password" > authentication/Admin/current_password
 262                                                         echo "signed certificate" > authentication/Admin/certificate
 263
 264                                                 Updating the installed certificate::
 265
 266                                                         echo "signature" > authentication/Admin/signature
 267                                                         echo "signed certificate" > authentication/Admin/certificate
 268
 269                                                 Removing the installed certificate::
 270
 271                                                         echo "signature" > authentication/Admin/signature
 272                                                         echo "" > authentication/Admin/certificate
 273
 274                                                 Changing a BIOS setting::
 275
 276                                                         echo "signature" > authentication/Admin/signature
 277                                                         echo "save signature" > authentication/Admin/save_signature
 278                                                         echo Enable > attribute/PasswordBeep/current_value
 279
 280                                         You cannot enable certificate authentication if a supervisor password
 281                                         has not been set.
 282                                         Clearing the certificate results in no bios-admin authentication method
 283                                         being configured allowing anyone to make changes.
 284                                         After any of these operations the system must reboot for the changes to
 285                                         take effect.
 286
 287                 certificate_thumbprint:
 288                                         Read only attribute used to display the MD5, SHA1 and SHA256 thumbprints
 289                                         for the certificate installed in the BIOS.
 290
 291                 certificate_to_password:
 292                                         Write only attribute used to switch from certificate based authentication
 293                                         back to password based.
 294                                         Usage::
 295
 296                                                 echo "signature" > authentication/Admin/signature
 297                                                 echo "password" > authentication/Admin/certificate_to_password
 298
 299
 300 What:           /sys/class/firmware-attributes/*/attributes/pending_reboot
 301 Date:           February 2021
 302 KernelVersion:  5.11
 303 Contact:        Divya Bharathi <Divya.Bharathi@Dell.com>,
 304                 Prasanth KSR <prasanth.ksr@dell.com>
 305                 Dell.Client.Kernel@dell.com
 306 Description:
 307                 A read-only attribute reads 1 if a reboot is necessary to apply
 308                 pending BIOS attribute changes. Also, an uevent_KOBJ_CHANGE is
 309                 generated when it changes to 1.
 310
 311                         ==      =========================================
 312                         0       All BIOS attributes setting are current
 313                         1       A reboot is necessary to get pending BIOS
 314                                 attribute changes applied
 315                         ==      =========================================
 316
 317                 Note, userspace applications need to follow below steps for efficient
 318                 BIOS management,
 319
 320                 1.      Check if admin password is set. If yes, follow session method for
 321                         password management as briefed under authentication section above.
 322                 2.      Before setting any attribute, check if it has any modifiers
 323                         or value_modifiers. If yes, incorporate them and then modify
 324                         attribute.
 325
 326                 Drivers may emit a CHANGE uevent when this value changes and userspace
 327                 may check it again.
 328
 329 What:           /sys/class/firmware-attributes/*/attributes/reset_bios
 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                 This attribute can be used to reset the BIOS Configuration.
 337                 Specifically, it tells which type of reset BIOS configuration is being
 338                 requested on the host.
 339
 340                 Reading from it returns a list of supported options encoded as:
 341
 342                         - 'builtinsafe' (Built in safe configuration profile)
 343                         - 'lastknowngood' (Last known good saved configuration profile)
 344                         - 'factory' (Default factory settings configuration profile)
 345                         - 'custom' (Custom saved configuration profile)
 346
 347                 The currently selected option is printed in square brackets as
 348                 shown below::
 349
 350                     # echo "factory" > /sys/class/firmware-attributes/*/device/attributes/reset_bios
 351                     # cat /sys/class/firmware-attributes/*/device/attributes/reset_bios
 352                     builtinsafe lastknowngood [factory] custom
 353
 354                 Note that any changes to this attribute requires a reboot
 355                 for changes to take effect.
 356
 357 What:           /sys/class/firmware-attributes/*/attributes/debug_cmd
 358 Date:           July 2021
 359 KernelVersion:  5.14
 360 Contact:        Mark Pearson <markpearson@lenovo.com>
 361 Description:
 362                 This write only attribute can be used to send debug commands to the BIOS.
 363                 This should only be used when recommended by the BIOS vendor. Vendors may
 364                 use it to enable extra debug attributes or BIOS features for testing purposes.
 365
 366                 Note that any changes to this attribute requires a reboot for changes to take effect.