Parent blog : Enabling Platform Key Store capability for User-Space applications on AIX

Link : https://community.ibm.com/community/user/blogs/soumya-mukherjee/2024/12/19/pks-for-userspace

Recap of the parent blog ,  The Platform Key Store (PKS) is a hardware backed NVRAM solution designed to securely store sensitive materials such as keys, certificates, and other secrets.

PKS is a feature provided by the Power firmware or Power Hypervisor (PHYP), and it serves both firmware and guest operating systems.

Existing exploiters of PKS include Secure Boot, Self-Encrypted Drives (SED), and Logical/Physical Volume (LV/PV) encryption, which utilize PKS from the kernel space.

In 2024, with the release of AIX 7.3 TL3, a new framework called AIX Key Manager (also known as pksus) was introduced. This framework enables user-space applications to access PKS/NVRAM, providing a mechanism for securely storing and retrieving secrets.

With the introduction of this framework, the number of PKS exploiters has increased. However, the storage capacity of NVRAM is limited. To address this limitation, starting from P11 (FW1110), PKS introduced a new capability called object wrapping.

Introduction

The PKS object wrapping capability provides a secure wrapping service for AIX, allowing secrets to be wrapped using a wrapping key that is known only to PKS.

Both AIX kernel space and user-space applications (via the pksus framework) can wrap an object using a wrapping key stored in PKS. The wrapped object is then returned to the caller.

To unwrap an object previously wrapped by PKS, the user space (pksus) invokes the base kernel, which in turn issues a call to the hypervisor to perform the unwrap operation.

For the wrapping function, a new object of type GENKEY is created for each consumer, with a policy specifically designated for wrapping. This object is referred to as the wrap key.

As usual, these keys are created with a user specified label. Under the hood, PHYP/PKS generates an object containing the wrapping key, which is then used consistently for both wrapping and unwrapping operations.

Wrap Object flow from User Space to Phyp

                                                                                                    Fig 1:

pksctl utility and pksus wrap/unwrap API

Two new access types have been introduced for pksus user registration:

• ·      WRAP:

o   Allows only wrap and unwrap operations.

o   No user quota will be created for the secret store.

o   Intended for single-session use.

• ·      WRAP_PLUS:

o   Allows all standard operations including wrap, unwrap, and secret store interactions.

o   A user quota will be created in the secret store.

o   Also intended for single-session use.

For multi-session use, the following types should be used:

o WRAP_MULTI
o WRAP_PLUS_MULTI

pksctl register help

Usage: pksctl register <flags>, where <flags> can be:

For pksus user, new access types WRAP and WRAP_PLUS has been added while registering, if user register with WRAP type, then user will be allowed to use only wrap and unwrap capability, and no user quota will be created for secret store.
With access type WRAP_PLUS user will be allowed to do all usual operation which includes wrap and unwrap, secret store User quota will be created in this case. 

WRAP and WRAP_PLUS type is for single session for multi session use WRAP_MULTI and WRAP_PLUS_MULTI type should be used. 

Currently for pksctl register, “--type " flag has below option 

pksctl register help

Usage: pksctl register <flags>, where <flags> can be:

                                                                                                        Fig 2:   

Example:
                                                            Fig 3:

New APIs Exported by libpksus Library

The following two APIs are now exported by the libpksus library.
These functions are used by user applications to wrap and unwrap objects:

int pks_wrap_obj(sess_t  sid, object_t  input , object_t output,int wrap_policy_flag)
Function: pks_wrap_obj
Parameters:

• sess_t sid: Session ID created using pks_sess_open API.
• object_t input: Object to be wrapped.
• object_t output: Output object after wrapping.
• int wrap_policy_flag: Wrap policy specified by the user

int pks_unwrap_obj( (sess_t  sid, object_t  input , object_t output,int wrap_policy_flag)
Function: pks_unwrap_obj
Parameters:

• sess_t sid: Session ID created using pks_sess_open API.
• object_t input: Object to be unwrapped.
• object_t output: Output object after unwrapping.
• int wrap_policy_flag: Wrap policy specified by the user

/* WRAP policy */
Wrapping Algorithm:
• 0x1 = AES-256-GCM
• 0x2 – 0xF = Reserved

Buffer Requirements for pksus Wrap and Unwrap Functions

• Wrap Operation (pks_wrap_obj):
  • The output buffer must be at least 1 KB larger than the input buffer.
  • This extra 1 KB is used by PHYP to store metadata, which may be required during the unwrap operation
• Unwrap Operation (pks_unwrap_obj):
  
  • The output buffer must be at least the same size as the input buffer, or input buffer size minus 1 KB (to account for the metadata added during wrapping).

                                             Fig 4:

Compile and execute the program to wrap and unwrap an object:

                                           Fig 5:

Wrap and Unwrap object call from the Consumer at user space to Power Hypervisor :

• To utilize the wrapping capability, the consumer must register with access type WRAP or WRAP_PLUS.
• During registration, the pksus Kernel Extension (KE) generates a wrapping key for the consumer.
• This key is used later when the consumer invokes the pks_wrap_obj system call to wrap an object.
•   Only one wrapping key is generated per consumer.
• The label of the key is stored internally within the pksus Kernel Extension and is not exposed to the user.
• The pksus consumer cannot list or delete the wrapping key.
• Upon unregistration of the consumer, the pksus Kernel Extension automatically handles deletion of the wrapping key.

Summary
AIX application can use PKS object wrapping capability to wrap secret with a wrapping key known only to PKS,
after wrapping the object PKS, return the object to the caller. To unwrap the object previously wrapped by PKS, call the unwrap subroutine, it will unwrap and return the object backto the caller.

References
https://ibmdocs-test.dcs.ibm.com/docs/en/ssw_aix_73F_test?topic=p-pksctl-command – Web-link for the man page of ‘pksctl’ command.
https://www.ibm.com/docs/en/power10/9080-HEX?topic=partitions-enabling-platform-keystore-capability-logical-partition – Enable PKS

Contributions
Soumya Mukherjee (soumya.mukherjee@ibm.com)
Mansi Jaiswal (mansjais@in.ibm.com)
Madan Chukka(madan.chukka@in.ibm.com)
Narasimha swamy B A(narasimha.swamy.b.a@ibm.com)