Commit 1d72a02d authored by Nayna Jain's avatar Nayna Jain Committed by Madhavan Srinivasan
Browse files

docs: trusted-encryped: add PKWM as a new trust source 



Update Documentation/security/keys/trusted-encrypted.rst and Documentation/
admin-guide/kernel-parameters.txt with PowerVM Key Wrapping Module (PKWM)
as a new trust source

Signed-off-by: default avatarNayna Jain <nayna@linux.ibm.com>
Signed-off-by: default avatarSrish Srinivasan <ssrish@linux.ibm.com>
Tested-by: default avatarNayna Jain <nayna@linux.ibm.com>
Reviewed-by: default avatarMimi Zohar <zohar@linux.ibm.com>
Signed-off-by: default avatarMadhavan Srinivasan <maddy@linux.ibm.com>
Link: https://patch.msgid.link/20260127145228.48320-7-ssrish@linux.ibm.com
parent c99fcb0d

Documentation/admin-guide/kernel-parameters.txt

+1 −0
Original line number Diff line number Diff line
@@ -7755,6 +7755,7 @@ Kernel parameters 
			- "tee"

			- "caam"

			- "dcp"

			- "pkwm"

			If not specified then it defaults to iterating through

			the trust source list starting with TPM and assigns the

			first trust source as a backend which is initialized

Documentation/security/keys/trusted-encrypted.rst

+50 −0
Original line number Diff line number Diff line
@@ -81,6 +81,14 @@ safe. 
         and the UNIQUE key. Default is to use the UNIQUE key, but selecting

         the OTP key can be done via a module parameter (dcp_use_otp_key).



     (5) PKWM (PowerVM Key Wrapping Module: IBM PowerVM + Platform KeyStore)



         Rooted to a unique, per-LPAR key, which is derived from a system-wide,

         randomly generated LPAR root key. Both the per-LPAR keys and the LPAR

         root key are stored in hypervisor-owned secure memory at runtime,

         and the LPAR root key is additionally persisted in secure locations

         such as the processor SEEPROMs and encrypted NVRAM.



  *  Execution isolation



     (1) TPM
@@ -102,6 +110,14 @@ safe. 
         environment. Only basic blob key encryption is executed there.

         The actual key sealing/unsealing is done on main processor/kernel space.



     (5) PKWM (PowerVM Key Wrapping Module: IBM PowerVM + Platform KeyStore)



         Fixed set of cryptographic operations done on on-chip hardware

         cryptographic acceleration unit NX. Keys for wrapping and unwrapping

         are managed by PowerVM Platform KeyStore, which stores keys in an

         isolated in-memory copy in secure hypervisor memory, as well as in a

         persistent copy in hypervisor-encrypted NVRAM.



  * Optional binding to platform integrity state



     (1) TPM
@@ -129,6 +145,11 @@ safe. 
         Relies on Secure/Trusted boot process (called HAB by vendor) for

         platform integrity.



     (5) PKWM (PowerVM Key Wrapping Module: IBM PowerVM + Platform KeyStore)



         Relies on secure and trusted boot process of IBM Power systems for

         platform integrity.



  *  Interfaces and APIs



     (1) TPM
@@ -149,6 +170,11 @@ safe. 
         Vendor-specific API that is implemented as part of the DCP crypto driver in

         ``drivers/crypto/mxs-dcp.c``.



     (5) PKWM (PowerVM Key Wrapping Module: IBM PowerVM + Platform KeyStore)



         Platform Keystore has well documented interfaces in PAPR document.

         Refer to ``Documentation/arch/powerpc/papr_hcalls.rst``



  *  Threat model



     The strength and appropriateness of a particular trust source for a given
@@ -191,6 +217,10 @@ selected trust source: 
     a dedicated hardware RNG that is independent from DCP which can be enabled

     to back the kernel RNG.



   * PKWM (PowerVM Key Wrapping Module: IBM PowerVM + Platform KeyStore)



     The normal kernel random number generator is used to generate keys.



Users may override this by specifying ``trusted.rng=kernel`` on the kernel

command-line to override the used RNG with the kernel's random number pool.
@@ -321,6 +351,26 @@ Usage:: 
specific to this DCP key-blob implementation.  The key length for new keys is

always in bytes. Trusted Keys can be 32 - 128 bytes (256 - 1024 bits).



Trusted Keys usage: PKWM

------------------------



Usage::



    keyctl add trusted name "new keylen [options]" ring

    keyctl add trusted name "load hex_blob" ring

    keyctl print keyid



    options:

       wrap_flags=   ascii hex value of security policy requirement

                       0x00: no secure boot requirement (default)

                       0x01: require secure boot to be in either audit or

                             enforced mode

                       0x02: require secure boot to be in enforced mode



"keyctl print" returns an ASCII hex copy of the sealed key, which is in format

specific to PKWM key-blob implementation.  The key length for new keys is

always in bytes. Trusted Keys can be 32 - 128 bytes (256 - 1024 bits).



Encrypted Keys usage

--------------------