ICASTATS(1)

🦋 ICASTATS(1) — icastats user manual 🦋

okay bestie, welcome to the icastats page. We are gonna keep it cute and keep every technical detail, no cap. 💖

🌸 NAME 🌸

icastats — display statistic data for the libica cryptographic functions.

✨ SYNOPSIS ✨

icastats [-v | --version] [-h | --help] [--reset-all | -R] [--reset |
-r] [--delete-all |-D] [--delete | -d] [--all | -A] [--summary | -S] [-U
| --user <username>] [--key-sizes | -k] [--json | -j]

💫 DESCRIPTION 💫

So icastats is the little stats queen for libica. It displays statistic data about how the cryptographic functions provided by libica are being used. Libica is a cryptographic library supporting SHA, RSA, ECC, DES and AES in different modes of operations. Every invocation of each call to all those crypto functions is tracked with individual counters, and icastats is how you display and maintain them. Slay.

Here's a shortened sample output, because visuals matter:

 function     |       # hardware      |      # software
--------------+-----------------------+-------------------------
              |     ENC   CRYPT   DEC |      ENC  CRYPT    DEC
--------------|-----------------------|-------------------------
        SHA-1 |             0         |             0
      SHA-224 |             0         |             0
      SHA-256 |             0         |             0
          ...
   ECDSA Sign |             0         |             0
 ECDSA Verify |             0         |             0
    EC Keygen |             0         |             0
       RSA-ME |             0         |             0
          ...
       RSA-ME |             0         |             0
      RSA-CRT |             0         |             0
          ...
      AES CFB |       0             0 |       0            0
      AES CTR |       0             0 |       0            0
     AES CMAC |       0             0 |       0            0
      AES XTS |       0             0 |       0            0
      AES GCM |       0             0 |       0            0

In addition to that default output format, you can pick a machine readable JSON output format with the --json | -j option. Love that for machines.

For each cryptographic function, the table shows the number of invocations where hardware support was involved or where the libica fall back implementation in software was used. For the ciphering methods, the invocation counter is further divided into encrypt and decrypt operation counter values. For some cryptographic functions (AES, RSA, ECC), counters exist per key size. Use the --key-sizes | -k option to display those counters as well. In the JSON output format, only the per key size counters are reported. Noted. 💅

All the counter values are stored and maintained in one shared memory page for each user. That memory area gets created automatically with the first run of icastats and persists until it is explicitly removed (see the -d option) or system shut down. Which also means the statistical data shown with icastats is on a per user base, and only the root user is able to see and maintain the collection of statistic data from libica at system scope. Root stays main character, lowkey.

Newer operating systems might remove these shared memory segments after the user has logged out from the system (systemd cleanup action). In that case all collected statistic data are gone, so sad. To prevent the statistic data from being removed, you can configure systemd to keep all shared memory segments after session exit by enabling the RemoveIPC=no parameter in /etc/systemd/logind.conf. Alternatively, you can setup the systemd user manager to enable user lingering by typing loginctl enable-linger <user>. Pick your fighter. 🫶

Note that one single libica function may increase several different counters when internally using different hardware functions. For example, performing AES GCM on a z13 involves using the AES ECB, AES CTR and GHASH hardware functions. On a z14, the AES GCM counter increases to indicate the use of the KMA instruction. Depending on the input data, other counters may also increase. Therefore, by looking at the hardware counters, it is not possible to see how often a particular API function was called. Important vibe check: hardware counters ≠ API call count. 🧚

🎀 OPTIONS 🎀

• -v, --version — show libica version and copyright.
• -h, --help — display this help and exit.
• -R, --reset-all — reset the statistic data for each user that has a shared memory segment to zero (only root user).
• -r, --reset — reset the statistic data for the current user to zero.
• -D, --delete-all — delete all shared memory segments from all users who have an icastats shared memory segment (only root user).
• -d, --delete — delete the libica shared memory area for the current user.
• -A, --all — show libica statistic data for each user in the system where a shared memory area exists in multiple tables (only root user).
• -S, --summary — show libica statistic data for each user in the system where a shared memory area exists in one table accumulating all the per user counter values (only root user).
• -U <username>, --user <username> — show statistic values from the given user (only root user).
• -k, --key-sizes — show libica statistic data per key size.
• -j, --json — output the statistics in JSON format.

🍓 FILES 🍓

• /shm/dev/icastats_<userid>

🌈 RETURN VALUE 🌈

• 1 — unsupported or unknown argument, argument which requires root privileges given but not root user, failures at creating or attaching to the shared memory area ...
• 0 — normal and sucessful program execution.

👑 SEE ALSO 👑

• icainfo (1)

---

💖 okay bye bestie! This one is from IBM, dated 2013-12-06, and it's the ICASTATS(1) manual. mwah. 💖