Re: [PATCH v6 6/6] docs: trusted-encryped: add PKWM as a new trust source

[Jarkko Sakkinen <jarkko@kernel.org>]

On Sun, Feb 01, 2026 at 07:29:30PM +0530, Srish Srinivasan wrote:
> From: Nayna Jain <nayna@linux.ibm.com>
> 
> 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: Nayna Jain <nayna@linux.ibm.com>
> Signed-off-by: Srish Srinivasan <ssrish@linux.ibm.com>
> Reviewed-by: Mimi Zohar <zohar@linux.ibm.com>

Reviewed-by: Jarkko Sakkinen <jarkko@kernel.org>

And you are free to take 5/6 and 6/6 to a pull request if you prefer
that route.

> ---
>  .../admin-guide/kernel-parameters.txt         |  1 +
>  .../security/keys/trusted-encrypted.rst       | 50 +++++++++++++++++++
>  2 files changed, 51 insertions(+)
> 
> diff --git a/Documentation/admin-guide/kernel-parameters.txt b/Documentation/admin-guide/kernel-parameters.txt
> index 1058f2a6d6a8..aac15079b33d 100644
> --- a/Documentation/admin-guide/kernel-parameters.txt
> +++ b/Documentation/admin-guide/kernel-parameters.txt
> @@ -7790,6 +7790,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
> diff --git a/Documentation/security/keys/trusted-encrypted.rst b/Documentation/security/keys/trusted-encrypted.rst
> index eae6a36b1c9a..ddff7c7c2582 100644
> --- a/Documentation/security/keys/trusted-encrypted.rst
> +++ b/Documentation/security/keys/trusted-encrypted.rst
> @@ -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
>  --------------------
>  
> -- 
> 2.47.3
> 

BR, Jarkko