cpacfstats - Monitor CPACF cryptographic activity

Ubuntu 22.04 LTS LPAR mode

Use the cpacfstats command to display the number of cryptographic operations that are performed by the Central Processor Assist for Cryptographic Function (CPACF). You can display and enable, disable, or reset specific hardware counters for AES, DES, ECC, TDES, SHA, and pseudo random functions.

CPACF performance counters are available on LPARs only.

All counters are initially disabled and must be enabled in the LPAR activation profile on the SE or HMC to measure CPACF activities. There is a slight performance penalty with CPACF counters enabled.

Prerequisites

The performance monitoring event library libpfm version 4 or later is required. You can obtain the libpfm4 package from Debian.
On the HMC or SE, authorize the LPAR for each counter set you want to use. Customize the LPAR activation profile and modify the Counter Facility Security Options. You need to activate the "Crypto activity counter set authorization control" checkbox.
The cpacfstatsd daemon must be running. Check the syslog for the message:cpacfstatsd: Running. To start the daemon, issue:
```
# cpacfstatsd
```
The daemon requires root privileges to open and work with the perf kernel API functions. Issue man cpacfstatsd for more information about the daemon.

Note: The counter value is increased once per API call and also for every additional 4096 bytes of data.

Setting up the cpacfstats group

Only root and members of the group cpacfstats are allowed to communicate with the daemon process. You must create the group and add users to it.

Create the group cpacfstats:
```
# groupadd cpacfstats
```
Add all users who are allowed to run the cpacfstats client application to the group:
```
usermod -a -G cpacfstats <user>
```

All users in the cpacfstats group are also able to modify the CPACF counter states (enable, disable, reset).

cpacfstats syntax

Where:

-e <counter> or --enable <counter>

enables one or all CPACF performance counters. The optional counter argument can be one of:

aes: counts all AES-related cipher message CPACF instructions.
des: counts all DES- and 3DES-related cipher message CPACF instructions.
ecc: counts all ECC (elliptic curve cryptography) related CPACF instructions.
rng: counts all pseudo-random related CPACF instructions.
sha: counts all message digest (that is, SHA-1 through SHA-512) related CPACF instructions.
all: counts all CPACF instructions.

If you omit the counter, all performance counters are enabled. Enabling a counter does not reset it. New events are added to the current counter value.

-d <counter> or --disable <counter>

disables one or all CPACF performance counters. If you omit the counter, all performance counters are disabled. Disabling a counter does not reset it. The counter value is preserved when a counter is disabled, and counting resumes with the preserved value when the counter is re-enabled.

-r <counter> or --reset <counter>

resets one or all CPACF performance counters. If you omit the counter, all performance counters are reset to 0.

-p <counter> or --print <counter>

displays the value of one or all CPACF performance counters. If you omit the counter, all performance counters are displayed.

-h or --help

displays help information for the command. To view the command man page, enter man cpacfstats.

-v or --version

displays version information for cpacfstats.

The default command is --print all.

Examples

To print status and values of all CPACF performance counters:

# cpacfstats 
des counter: disabled
aes counter: disabled
sha counter: disabled
rng counter: disabled

To enable the AES CPACF performance counter:
```
# cpacfstats --enable aes
aes counter: 0
```
To enable all CPACF performance counters:
```
# cpacfstats -e
des counter: 0
aes counter: 192
sha counter: 0
rng counter: 0
```
For the already enabled aes counter, the value is not reset.