Displaying usage statistics - pkcsstats utility
openCryptoki provides a command line program pkcsstats to display usage statistics of mechanisms per slot IDs, either on the basis of individual users or accumulated for all users, and broken down to available key-sizes.
Description
The pkcsstats utility displays mechanism usage statistics for openCryptoki. Usage statistics are collected per user. For each user, mechanism usage is counted per configured slot and mechanism. For each mechanism, one counter exists for each cryptographic strength of the key used with the mechanism. The available strengths are defined in the strength configuration file /etc/opencryptoki/ strength.conf (see Strength configuration file). A strength of zero is used to count those mechanisms that do not use a key, or where the key strength is less than 112 bits.
Statistics collection is enabled by default. You can disable and configure the collection in the openCryptoki configuration file /etc/opencryptoki/opencryptoki.conf using option statistics (off|on[,implicit][,internal]). For example, you can collect only mechanisms that are explicitly called by a PKCS #11 application or also collect those mechanisms that are called implicitly by another mechanism. So before using the pkcsstats utility, be sure to understand the information provided in Collecting statistics.
The usage of a mechanism is counted once when the cryptographic operation is successfully initialized, that is, 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. 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_UnwrapKey().
Statistics are collected in a POSIX shared memory segment per user. This shared memory segment contains all counters for all configured slots, mechanisms, and key-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. All users can only display their own statistics, and only the root user can display all users' statistics.
Invocation and usage
Get an overview about available options using the pkcsstats -h command:
# pkcsstats -h
Usage: pkcsstats [OPTIONS]
Display mechanism usage statistics for openCryptoki.
OPTIONS:
-U, --user USERID show the statistics from one user. (root user only)
-S, --summary show the accumulated statistics from all users. (root user only)
-A, --all show the statistic tables from all users. (root user only)
-a, --all-mechs show all mechanisms, also those with all zero counters.
-s, --slot SLOTID show the statistics from one slot only.
-r, --reset set the own statistics to zero.
-R, --reset-all reset the statistics from all users. (root user only)
-d, --delete delete your own statistics.
-D, --delete-all delete the statistics from all users. (root user only)
-j, --json output the statistics in JSON format.
-h, --help display help information.
where
- -U, --user <user_id>
- specifies the user ID of the user who wants to display, reset, or delete statistics. If this option is omitted, the statistics of the current user are displayed, reset, or deleted. Only the root user can display, reset, or delete statistics of other users.
- -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.
- −s, −−slot <slot_id>
- specifies the slot ID for which to display statistics. 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.
- −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.
- −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 to obtain the values in a machine readable format for automatic processing.
- −h, −−help
- displays help text and exits.
Example (default table format):
To obtain the statistics for the root user in slot 2, where a CCA token is installed, enter the shown command:
# pkcsstats -s 2 -U root
User: root
Slot: 2 (label: 'cca' model: 'CCA')
-------------------------------+--------------------------------------------------------------------------
mechanism | strength 0 strength 112 strength 128 strength 192 strength 256
| or no key
-------------------------------+--------------------------------------------------------------------------
CKM_AES_CBC | 0 0 16 16 16
CKM_AES_CBC_PAD | 0 0 8 8 8
CKM_AES_ECB | 0 0 18 16 16
CKM_AES_KEY_GEN | 0 0 22 20 20
CKM_RSA_PKCS_KEY_PAIR_GEN | 24 0 0 0 0
-------------------------------+--------------------------------------------------------------------------
Example (JSON format):
The example from Figure 1 requested in JSON format looks like shown in Figure 2:
[root@system1 opencryptoki]# pkcsstats -s 2 -U root --json
"host": {
"nodename": "a1251960.domain.com",
"sysname": "system1",
"release": "6.0.7-301.fc37.s390x",
"machine": "s390x",
"date": "2023-06-02T11:14:25Z"
},
"users": [
{
"user": "root",
"slots": [
{
"slot": 2,
"token-present": true,
"label": "cca",
"model": "CCA",
"mechanisms": [
{
"mechanism": "CKM_AES_CBC",
"strength-0": 0,
"strength-112": 0,
"strength-128": 16,
"strength-192": 16,
"strength-256": 16
},
{
"mechanism": "CKM_AES_CBC_PAD",
"strength-0": 0,
"strength-112": 0,
"strength-128": 8,
"strength-192": 8,
"strength-256": 8
},
{
"mechanism": "CKM_AES_ECB",
"strength-0": 0,
"strength-112": 0,
"strength-128": 18,
"strength-192": 16,
"strength-256": 16
},
{
"mechanism": "CKM_AES_KEY_GEN",
"strength-0": 0,
"strength-112": 0,
"strength-128": 22,
"strength-192": 20,
"strength-256": 20
},
{
"mechanism": "CKM_RSA_PKCS_KEY_PAIR_GEN",
"strength-0": 24,
"strength-112": 0,
"strength-128": 0,
"strength-192": 0,
"strength-256": 0
}
]
}
]
}
]
}For further information you can read the pkcsstats man page.