PKCSSTATS(1)

💖 PKCSSTATS 💖

okay bestie, welcome to pkcsstats(1) — the openCryptoki manual page, but make it cute. this is the little utility that spills the tea on which crypto mechanisms are actually getting used. let's get into it 🫶

---

✨ NAME ✨

pkcsstats — a utility to display mechanism usage statistics for openCryptoki. that's it, that's the whole vibe. she counts things and she tells you about them 💅

---

✨ SYNOPSIS ✨

pkcsstats [OPTIONS]

pkcsstats --help|-h

---

✨ DESCRIPTION ✨

so. pkcsstats displays mechanism usage statistics for openCryptoki. no cap. 🌸

the stats are collected by openCryptoki on a per user basis. for each user, mechanism usage is counted per configured slot and per mechanism. and for each mechanism there's a whole set of counters — one for each cryptographic strength of the cryptographic key used with the mechanism. it's giving organized. it's giving thorough. we love her.

the available strengths live in the strength configuration file /etc/opencryptoki/strength.conf. the supported strengths are 112, 128, 192, and 256 — those are the corresponding strength in bits, bestie. that config file is what decides how the strength gets determined for the various key types. and a strength of zero is used to count those mechanisms that don't use a key at all, or where the key strength is less than 112 bits.

💀 note: the strength does not specify the cryptographic strength of the mechanism. it specifies the cryptographic strength of the key used with the mechanism (if any). like, read that again, it matters.

for example, usage of mechanism CKM_SHA256 is reported under strength 0, because no key is used with this mechanism. but usage of mechanism CKM_AES_CBC is reported under strength 128, 192, or 256, dependent on the cryptographic size of the AES key used with it — and also dependent on the definitions in the strength configuration file. see how that works? iconic behavior honestly 🎀

---

statistics collection is enabled by default. it can be disabled and configured in the openCryptoki configuration file /etc/opencryptoki/opencryptoki.conf. by default only explicit mechanism usage statistics from PKCS#11 applications are collected.

optionally, implicit mechanism usage statistics can be collected, where additional mechanisms are specified in mechanism parameters. like, for example:

• RSA-PSS or RSA-OAEP lets you specify a hash mechanism and a mask generation function (MGF) in the mechanism parameter
• ECDH lets you specify a key derivation function (KDF) in the mechanism parameter
• the PBKDF2 mechanism lets you specify a pseudo random function (PRF) in the mechanism parameter

also optionally, opencryptoki-internal mechanism usage statistics can be collected. this one collects usage statistics for crypto operations used internally for pin handling and encryption of private token objects in the data store. the deep lore 😭

💀 note: implicit or internal mechanism usage can not be distinguished from explicit mechanism usage of PKCS#11 applications in the displayed statistics. so don't come for her about it.

---

okay now the storage part, stay with me 🦋

statistics are collected in a POSIX shared memory segment per user. this shared memory segment contains all counters for all configured slots, mechanisms, and strengths. the shared memory segments are named var.lib.opencryptoki_stats_<uid>, where uid is the numeric user-id of the user the statistics belong to. ✨

the shared memory segments are automatically created for a user on the first attempt to collect statistics — but only when not already existent, obviously. and they can be deleted using the pkcsstats command with the --delete, or --delete-all options. slay, cleanup.

---

so when does something get counted? the usage of a mechanism is counted once when the cryptographic operation is sucessfully initialized, i.e. during C_DigestInit, C_EncryptInit, C_DecryptInit, C_SignInit, C_SignRecoverInit, and C_VerifyInit. multi-part operations involving the update functions like C_DigestUpdate, C_EncryptUpdate, C_DecryptUpdate, C_SignUpdate, and C_VerifyUpdate, are not counted additionally. one count per vibe. periodt.

other operations such as key generation, key derivation, key wrapping and unwrapping are counted during the respective functions like C_GenerateKey, C_GenerateKeyPair, C_DeriveKey, C_DeriveKey, C_UnwrapKey.

---

✨ OPTIONS ✨

• -U, --user user-id — specifies the user-id of the user to display, reset, or delete statistics for. if you omit this option, the statistics of the current user are displayed, resetted, or deleted. and heads up: only the root user can display, reset, or delete statistics of other users. root privileges only, bestie 👑
• -S, --summary — shows the accumulated statistics from all users. only the root user can display the accumulated statistics from other users.
• -A, --all — shows the statistics from all users. only the root user can display statistics from all users.
• -a, --all-mechs — shows the statistics for all mechanisms, also those with all-zero counters. if this option is omitted, only those mechanisms are displayed where at least one counter is non-zero. so like, the quiet ones stay quiet unless you ask 🫶
• -s, --slot slot-id — specifies the slot-id to display statistics for. if this option is omitted, the statistics for all configured slots are displayed.
• -r, --reset — resets the statistics counters for the current user, or for the user specified with the --user option. only the root user can reset the statistics from other users. fresh start energy ✨
• -R, --reset-all — resets the statistics counters for all users. only the root user can reset the statistics from other users.
• -d, --delete — deletes the shared memory segment containing the statistics counters for the current user, or for the user specified with the --user option. only the root user can delete the statistics from other users. bye bye segment 💀
• -D, --delete-all — deletes the shared memory segment containing the statistics counters for all users. only the root user can delete the statistics from other users.
• -j, --json — shows the statistics in JSON format. this is usefull to get the statistics in a machine readable format. robots need love too 🤖💖
• -h, --help — displays help text and exits. the classic.

---

✨ SEE ALSO ✨

• opencryptoki.conf(5).
• strength.conf(5),
• opencryptoki(7),

---

and that's the whole page, bestie!! 🎀 this was openCryptoki's pkcsstats(1), version 3.27.0, dated October 2021. go forth and count your mechanisms, i'm so proud of you 💜🌸✨