diff options
Diffstat (limited to 'Documentation/ABI/testing/sysfs-class-firmware-attributes')
| -rw-r--r-- | Documentation/ABI/testing/sysfs-class-firmware-attributes | 240 |
1 files changed, 230 insertions, 10 deletions
diff --git a/Documentation/ABI/testing/sysfs-class-firmware-attributes b/Documentation/ABI/testing/sysfs-class-firmware-attributes index 3348bf80a37c..2713efa509b4 100644 --- a/Documentation/ABI/testing/sysfs-class-firmware-attributes +++ b/Documentation/ABI/testing/sysfs-class-firmware-attributes @@ -2,8 +2,8 @@ What: /sys/class/firmware-attributes/*/attributes/*/ Date: February 2021 KernelVersion: 5.11 Contact: Divya Bharathi <Divya.Bharathi@Dell.com>, - Mario Limonciello <mario.limonciello@dell.com>, Prasanth KSR <prasanth.ksr@dell.com> + Dell.Client.Kernel@dell.com Description: A sysfs interface for systems management software to enable configuration capability on supported systems. This directory @@ -22,6 +22,11 @@ Description: - integer: a range of numerical values - string + HP specific types + ----------------- + - ordered-list - a set of ordered list valid values + + All attribute types support the following values: current_value: @@ -116,7 +121,7 @@ Description: <value>[ForceIf:<attribute>=<value>] <value>[ForceIfNot:<attribute>=<value>] - For example: + For example:: LegacyOrom/dell_value_modifier has value: Disabled[ForceIf:SecureBoot=Enabled] @@ -126,12 +131,27 @@ Description: value will not be effective through sysfs until this rule is met. + HP specific class extensions + ------------------------------ + + On HP systems the following additional attributes are available: + + "ordered-list"-type specific properties: + + elements: + A file that can be read to obtain the possible + list of values of the <attr>. Values are separated using + semi-colon (``;``) and listed according to their priority. + An element listed first has the highest priority. Writing + the list in a different order to current_value alters + the priority order for the particular attribute. + What: /sys/class/firmware-attributes/*/authentication/ Date: February 2021 KernelVersion: 5.11 Contact: Divya Bharathi <Divya.Bharathi@Dell.com>, - Mario Limonciello <mario.limonciello@dell.com>, Prasanth KSR <prasanth.ksr@dell.com> + Dell.Client.Kernel@dell.com Description: Devices support various authentication mechanisms which can be exposed as a separate configuration object. @@ -161,10 +181,19 @@ Description: power-on: Representing a password required to use the system + system-mgmt: + Representing System Management password. + See Lenovo extensions section for details + HDD: + Representing HDD password + See Lenovo extensions section for details + NVMe: + Representing NVMe password + See Lenovo extensions section for details mechanism: The means of authentication. This attribute is mandatory. - Only supported type currently is "password". + Supported types are "password" or "certificate". max_password_length: A file that can be read to obtain the @@ -197,16 +226,23 @@ Description: Drivers may emit a CHANGE uevent when a password is set or unset userspace may check it again. - On Dell and Lenovo systems, if Admin password is set, then all BIOS attributes + On Dell, Lenovo and HP systems, if Admin password is set, then all BIOS attributes require password validation. On Lenovo systems if you change the Admin password the new password is not active until the next boot. Lenovo specific class extensions - ------------------------------ + -------------------------------- On Lenovo systems the following additional settings are available: + role: system-mgmt This gives the same authority as the bios-admin password to control + security related features. The authorities allocated can be set via + the BIOS menu SMP Access Control Policy + + role: HDD & NVMe This password is used to unlock access to the drive at boot. Note see + 'level' and 'index' extensions below. + lenovo_encoding: The encoding method that is used. This can be either "ascii" or "scancode". Default is set to "ascii" @@ -216,12 +252,87 @@ Description: two char code (e.g. "us", "fr", "gr") and may vary per platform. Default is set to "us" + level: + Available for HDD and NVMe authentication to set 'user' or 'master' + privilege level. + If only the user password is configured then this should be used to + unlock the drive at boot. If both master and user passwords are set + then either can be used. If a master password is set a user password + is required. + This attribute defaults to 'user' level + + index: + Used with HDD and NVME authentication to set the drive index + that is being referenced (e.g hdd1, hdd2 etc) + This attribute defaults to device 1. + + certificate, signature, save_signature: + These attributes are used for certificate based authentication. This is + used in conjunction with a signing server as an alternative to password + based authentication. + The user writes to the attribute(s) with a BASE64 encoded string obtained + from the signing server. + The attributes can be displayed to check the stored value. + + Some usage examples: + + Installing a certificate to enable feature:: + + echo "supervisor password" > authentication/Admin/current_password + echo "signed certificate" > authentication/Admin/certificate + + Updating the installed certificate:: + + echo "signature" > authentication/Admin/signature + echo "signed certificate" > authentication/Admin/certificate + + Removing the installed certificate:: + + echo "signature" > authentication/Admin/signature + echo "" > authentication/Admin/certificate + + Changing a BIOS setting:: + + echo "signature" > authentication/Admin/signature + echo "save signature" > authentication/Admin/save_signature + echo Enable > attribute/PasswordBeep/current_value + + You cannot enable certificate authentication if a supervisor password + has not been set. + Clearing the certificate results in no bios-admin authentication method + being configured allowing anyone to make changes. + After any of these operations the system must reboot for the changes to + take effect. + Admin and System certificates are supported from 2025 systems onward. + + certificate_thumbprint: + Read only attribute used to display the MD5, SHA1 and SHA256 thumbprints + for the certificate installed in the BIOS. + + certificate_to_password: + Write only attribute used to switch from certificate based authentication + back to password based. + Usage:: + + echo "signature" > authentication/Admin/signature + echo "password" > authentication/Admin/certificate_to_password + + HP specific class extensions + -------------------------------- + + On HP systems the following additional settings are available: + + role: enhanced-bios-auth: + This role is specific to Secure Platform Management (SPM) attribute. + It requires configuring an endorsement (kek) and signing certificate (sk). + + What: /sys/class/firmware-attributes/*/attributes/pending_reboot Date: February 2021 KernelVersion: 5.11 Contact: Divya Bharathi <Divya.Bharathi@Dell.com>, - Mario Limonciello <mario.limonciello@dell.com>, Prasanth KSR <prasanth.ksr@dell.com> + Dell.Client.Kernel@dell.com Description: A read-only attribute reads 1 if a reboot is necessary to apply pending BIOS attribute changes. Also, an uevent_KOBJ_CHANGE is @@ -230,7 +341,7 @@ Description: == ========================================= 0 All BIOS attributes setting are current 1 A reboot is necessary to get pending BIOS - attribute changes applied + attribute changes applied == ========================================= Note, userspace applications need to follow below steps for efficient @@ -249,8 +360,8 @@ What: /sys/class/firmware-attributes/*/attributes/reset_bios Date: February 2021 KernelVersion: 5.11 Contact: Divya Bharathi <Divya.Bharathi@Dell.com>, - Mario Limonciello <mario.limonciello@dell.com>, Prasanth KSR <prasanth.ksr@dell.com> + Dell.Client.Kernel@dell.com Description: This attribute can be used to reset the BIOS Configuration. Specifically, it tells which type of reset BIOS configuration is being @@ -268,7 +379,116 @@ Description: # echo "factory" > /sys/class/firmware-attributes/*/device/attributes/reset_bios # cat /sys/class/firmware-attributes/*/device/attributes/reset_bios - # builtinsafe lastknowngood [factory] custom + builtinsafe lastknowngood [factory] custom Note that any changes to this attribute requires a reboot for changes to take effect. + +What: /sys/class/firmware-attributes/*/attributes/save_settings +Date: August 2023 +KernelVersion: 6.6 +Contact: Mark Pearson <mpearson-lenovo@squebb.ca> +Description: + On Lenovo platforms there is a limitation in the number of times an attribute can be + saved. This is an architectural limitation and it limits the number of attributes + that can be modified to 48. + A solution for this is instead of the attribute being saved after every modification, + to allow a user to bulk set the attributes, and then trigger a final save. This allows + unlimited attributes. + + Read the attribute to check what save mode is enabled (single or bulk). + E.g: + # cat /sys/class/firmware-attributes/thinklmi/attributes/save_settings + single + + Write the attribute with 'bulk' to enable bulk save mode. + Write the attribute with 'single' to enable saving, after every attribute set. + The default setting is single mode. + E.g: + # echo bulk > /sys/class/firmware-attributes/thinklmi/attributes/save_settings + + When in bulk mode write 'save' to trigger a save of all currently modified attributes. + Note, once a save has been triggered, in bulk mode, attributes can no longer be set and + will return a permissions error. This is to prevent users hitting the 48+ save limitation + (which requires entering the BIOS to clear the error condition) + E.g: + # echo save > /sys/class/firmware-attributes/thinklmi/attributes/save_settings + +What: /sys/class/firmware-attributes/*/attributes/debug_cmd +Date: July 2021 +KernelVersion: 5.14 +Contact: Mark Pearson <markpearson@lenovo.com> +Description: + This write only attribute can be used to send debug commands to the BIOS. + This should only be used when recommended by the BIOS vendor. Vendors may + use it to enable extra debug attributes or BIOS features for testing purposes. + + Note that any changes to this attribute requires a reboot for changes to take effect. + + + HP specific class extensions - Secure Platform Manager (SPM) + -------------------------------- + +What: /sys/class/firmware-attributes/*/authentication/SPM/kek +Date: March 2023 +KernelVersion: 5.18 +Contact: "Jorge Lopez" <jorge.lopez2@hp.com> +Description: + 'kek' Key-Encryption-Key is a write-only file that can be used to configure the + RSA public key that will be used by the BIOS to verify + signatures when setting the signing key. When written, + the bytes should correspond to the KEK certificate + (x509 .DER format containing an OU). The size of the + certificate must be less than or equal to 4095 bytes. + +What: /sys/class/firmware-attributes/*/authentication/SPM/sk +Date: March 2023 +KernelVersion: 5.18 +Contact: "Jorge Lopez" <jorge.lopez2@hp.com> +Description: + 'sk' Signature Key is a write-only file that can be used to configure the RSA + public key that will be used by the BIOS to verify signatures + when configuring BIOS settings and security features. When + written, the bytes should correspond to the modulus of the + public key. The exponent is assumed to be 0x10001. + +What: /sys/class/firmware-attributes/*/authentication/SPM/status +Date: March 2023 +KernelVersion: 5.18 +Contact: "Jorge Lopez" <jorge.lopez2@hp.com> +Description: + 'status' is a read-only file that returns ASCII text in JSON format reporting + the status information. + + "State": "not provisioned | provisioned | provisioning in progress", + "Version": "Major.Minor", + "Nonce": <16-bit unsigned number display in base 10>, + "FeaturesInUse": <16-bit unsigned number display in base 10>, + "EndorsementKeyMod": "<256 bytes in base64>", + "SigningKeyMod": "<256 bytes in base64>" + +What: /sys/class/firmware-attributes/*/attributes/Sure_Start/audit_log_entries +Date: March 2023 +KernelVersion: 5.18 +Contact: "Jorge Lopez" <jorge.lopez2@hp.com> +Description: + 'audit_log_entries' is a read-only file that returns the events in the log. + + Audit log entry format + + Byte 0-15: Requested Audit Log entry (Each Audit log is 16 bytes) + Byte 16-127: Unused + +What: /sys/class/firmware-attributes/*/attributes/Sure_Start/audit_log_entry_count +Date: March 2023 +KernelVersion: 5.18 +Contact: "Jorge Lopez" <jorge.lopez2@hp.com> +Description: + 'audit_log_entry_count' is a read-only file that returns the number of existing + audit log events available to be read. Values are separated using comma. (``,``) + + [No of entries],[log entry size],[Max number of entries supported] + + log entry size identifies audit log size for the current BIOS version. + The current size is 16 bytes but it can be up to 128 bytes long in future BIOS + versions. |