xref: /linux/Documentation/ABI/testing/sysfs-secvar (revision 5f5c9952b33cb4e8d25c70ef29f7a45cd26b6a9b)

What:		/sys/firmware/secvar
Date:		August 2019
Contact:	Nayna Jain <nayna@linux.ibm.com>
Description:	This directory is created if the POWER firmware supports OS
		secureboot, thereby secure variables. It exposes interface
		for reading/writing the secure variables

What:		/sys/firmware/secvar/vars
Date:		August 2019
Contact:	Nayna Jain <nayna@linux.ibm.com>
Description:	This directory lists all the secure variables that are supported
		by the firmware.

What:		/sys/firmware/secvar/format
Date:		August 2019
Contact:	Nayna Jain <nayna@linux.ibm.com>
Description:	A string indicating which backend is in use by the firmware.
		This determines the format of the variable and the accepted
		format of variable updates.

		On powernv/OPAL, this value is provided by the OPAL firmware
		and is expected to be "ibm,edk2-compat-v1".

		On pseries/PLPKS, this is generated by the kernel based on the
		version number in the SB_VERSION variable in the keystore. The
		version numbering in the SB_VERSION variable starts from 1. The
		format string takes the form "ibm,plpks-sb-v<version>" in the
		case of dynamic key management mode. If the SB_VERSION variable
		does not exist (or there is an error while reading it), it takes
		the form "ibm,plpks-sb-v0", indicating that the key management
		mode is static.

What:		/sys/firmware/secvar/vars/<variable name>
Date:		August 2019
Contact:	Nayna Jain <nayna@linux.ibm.com>
Description:	Each secure variable is represented as a directory named as
		<variable_name>. The variable name is unique and is in ASCII
		representation. The data and size can be determined by reading
		their respective attribute files.

		Only secvars relevant to the key management mode are exposed.
		Only in the dynamic key management mode should the user have
		access (read and write) to the secure boot secvars db, dbx,
		grubdb, grubdbx, and sbat. These secvars are not consumed in the
		static key management mode. PK, trustedcadb and moduledb are the
		secvars common to both static and dynamic key management modes.

What:		/sys/firmware/secvar/vars/<variable_name>/size
Date:		August 2019
Contact:	Nayna Jain <nayna@linux.ibm.com>
Description:	An integer representation of the size of the content of the
		variable. In other words, it represents the size of the data.

What:		/sys/firmware/secvar/vars/<variable_name>/data
Date:		August 2019
Contact:	Nayna Jain <nayna@linux.ibm.com>
Description:	A read-only file containing the value of the variable. The size
		of the file represents the maximum size of the variable data.

What:		/sys/firmware/secvar/vars/<variable_name>/update
Date:		August 2019
Contact:	Nayna Jain <nayna@linux.ibm.com>
Description:	A write-only file that is used to submit the new value for the
		variable. The size of the file represents the maximum size of
		the variable data that can be written.

What:		/sys/firmware/secvar/config
Date:		February 2023
Contact:	Nayna Jain <nayna@linux.ibm.com>
Description:	This optional directory contains read-only config attributes as
		defined by the secure variable implementation.  All data is in
		ASCII format. The directory is only created if the backing
		implementation provides variables to populate it, which at
		present is only PLPKS on the pseries platform.

What:		/sys/firmware/secvar/config/version
Date:		February 2023
Contact:	Nayna Jain <nayna@linux.ibm.com>
Description:	Config version as reported by the hypervisor in ASCII decimal
		format.

		Currently only provided by PLPKS on the pseries platform.

What:		/sys/firmware/secvar/config/max_object_size
Date:		February 2023
Contact:	Nayna Jain <nayna@linux.ibm.com>
Description:	Maximum allowed size of	objects in the keystore in bytes,
		represented in ASCII decimal format.

		This is not necessarily the same as the max size that can be
		written to an update file as writes can contain more than
		object data, you should use the size of the update file for
		that purpose.

		Currently only provided by PLPKS on the pseries platform.

What:		/sys/firmware/secvar/config/total_size
Date:		February 2023
Contact:	Nayna Jain <nayna@linux.ibm.com>
Description:	Total size of the PLPKS in bytes, represented in ASCII decimal
		format.

		Currently only provided by PLPKS on the pseries platform.

What:		/sys/firmware/secvar/config/used_space
Date:		February 2023
Contact:	Nayna Jain <nayna@linux.ibm.com>
Description:	Current space consumed by the key store, in bytes, represented
		in ASCII decimal format.

		Currently only provided by PLPKS on the pseries platform.

What:		/sys/firmware/secvar/config/supported_policies
Date:		February 2023
Contact:	Nayna Jain <nayna@linux.ibm.com>
Description:	Bitmask of supported policy flags by the hypervisor,
		represented as an 8 byte hexadecimal ASCII string. Consult the
		hypervisor documentation for what these flags are.

		Currently only provided by PLPKS on the pseries platform.

What:		/sys/firmware/secvar/config/signed_update_algorithms
Date:		February 2023
Contact:	Nayna Jain <nayna@linux.ibm.com>
Description:	Bitmask of flags indicating which algorithms the hypervisor
		supports for signed update of objects, represented as a 16 byte
		hexadecimal ASCII string. Consult the hypervisor documentation
		for what these flags mean.

		Currently only provided by PLPKS on the pseries platform.