icastats - Show use of libica functions
The command also shows which specific functions of libica are used. For a standard user, icastats shows a statistics table with all crypto operations that are used by the user’s processes. For the root user, icastats provides statistics for all users, or processes, on the system.
The shared memory segment that holds the statistic data is created when a user starts icastats or when a program is started, that performs cryptographic operations using libica. Once the shared memory segment exists, it can only be removed by one of the delete options (-d or -D) provided with the icastats utility. Thus, this function collects crypto statistics independently from the process context for continuing availability of data. All cryptographic operations using libica are counted into the statistics.
Format
Where:
- -A or --all
- Shows the statistic tables from all users (for root users only).
- -d or --delete
- Removes the user specific shared memory segment.
- -D or --delete-all
- Removes all shared memory segments (for root users only).
- -r or --reset
- Resets the user statistic data table.
- -R or --reset-all
- Resets all statistic data tables from all users (for root users only).
- -S or --summary
- Shows accumulated statistics from all users (for root users only).
- -U <username> or --user <username>
- Shows statistic data for a dedicated user (for root users only).
- -k or --key-sizes
- Displays the per-key-size counters for the usage of AES, RSA and ECC algorithms.
For AES algorithms, separate counters exist for key sizes of 128, 192 and 256 bits.
For RSA algorithms, separate counters exist for RSA keys of 512, 1024, 2048, and 4096 bits. RSA key sizes below 512 bits are counted as 512 bits. RSA key sizes in between the counted key sizes, are counted as the next smaller one (for example, 3072 bits is counted as 2048 bits). RSA key sizes higher than 4096 bits are counted as 4096 bits.
For ECC algorithms, separate counters exist for key sizes of 160, 192, 224, 256, 320, 384, 512, and 521 bits. This maps to the curves supported by libica.
If omitted, per default, only the overall usage of the algorithms are displayed.
- -j or --json
- Produces a machine readable JSON output format to enable automatic processing of libica statistics.
- -h or --help
- Displays help information for the command.
- -v or --version
- Displays the version number of icastats, then exits.
Examples
To display the current use of libica functions issue: icastats
# icastats
function | # hardware | # software
--------------+--------------------------+-------------------------
| ENC CRYPT DEC | ENC CRYPT DEC
--------------+--------------------------+-------------------------
SHA-1 | 0 | 0
SHA-224 | 0 | 0
...
SHA3-384 | 507 | 0
...
SHAKE-256 | 8276 | 0
...
P_RNG | 55 | 0
DRBG-SHA-512 | 29400 | 0
ECDH | 4188 | 0
ECDSA Sign | 1480 | 0
ECDSA Verify | 1480 | 0
EC Keygen | 132 | 0
RSA-ME | 351 | 1
RSA-CRT | 64 | 0
DES ECB | 0 0 | 0 0
DES CBC | 0 0 | 0 0
...
AES CMAC | 0 0 | 0 0
AES XTS | 0 0 | 0 0
AES GCM | 0 0 | 0 0
To display the current use of libica functions, broken down to key sizes, issue: icastats --key-sizes
# icastats --key-sizes
function | hardware | software
----------------+------------------------------+-----------------------------
| ENC CRYPT DEC | ENC CRYPT DEC
----------------+------------------------------+-----------------------------
SHA-1 | 81 | 0
SHA-224 | 39 | 0
SHA-256 | 43 | 0
SHA-384 | 507 | 0
SHA-512 | 13 | 0
...
SHAKE-128 | 0 | 0
SHAKE-256 | 8276 | 0
...
...
P_RNG | 55 | 0
DRBG-SHA-512 | 168 | 0
ECDH | 0 | 0
- 160 | 0 | 0
- 192 | 0 | 0
...
...
EC Keygen | 0 | 0
- 160 | 0 | 0
- 192 | 0 | 0
- 224 | 0 | 0
...
RSA-ME | 2799 | 0
- 512 | 0 | 0
- 1024 | 392 | 0
- 2048 | 1607 | 0
- 4096 | 800 | 0
RSA-CRT | 64 | 0
- 512 | 0 | 0
- 1024 | 0 | 0
- 2048 | 12 | 0
- 4096 | 52 | 0
AES ECB | 0 0 | 0 0
- 128 | 0 0 | 0 0
...
AES GCM | 0 0 | 0 0
- 128 | 0 0 | 0 0
...
Example of a JSON output
icastats --key-sizes --j
"host": {
"nodename": "system1.lnxne.boe",
"sysname": "Linux",
"release": "5.14.0-20210817.rc6.git0.8cdcf75aa9ff.300.fc34.s390x",
"machine": "s390x",
"date": "2022-03-10T15:45:02Z"
},
"users": [
{
"user": "root",
"functions": [
{
"function": "SHA-1",
"hw-crypt": 81,
"sw-crypt": 0
},
{
"function": "SHA-224",
"hw-crypt": 39,
"sw-crypt": 0
},
...
...
...
{
"function": "DRBG-SHA-512",
"hw-crypt": 168,
"sw-crypt": 0
},
{
"function": "ECDH - 160",
"hw-crypt": 0,
"sw-crypt": 0
},
...
...
...
{
"function": "RSA-ME - 512",
"hw-crypt": 0,
"sw-crypt": 0
},
{
"function": "RSA-ME - 1024",
"hw-crypt": 392,
"sw-crypt": 0
},
...
...
...
{
"function": "AES ECB - 128",
"hw-enc": 0,
"sw-enc": 0,
"hw-dec": 0,
"sw-dec": 0
},
]
}
]
}
- ENC
- is shown for a two way function performing encryption.
- CRYPT
- indicates cryptographic functions that produce a one-way result on given data, for example, creating a digital hash value from a given input text, or creating/verifying a digital signature.
- DEC
- is shown for a two way function performing decryption.
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.
Logging and error handling
Access failures to the shared memory segments that are used by the icastats utility, are logged once via the syslog interface. After a failed attempt to access the shared memory segment, the library no longer collects any statistic data for this application (related to application lifetime and user).
Example of syslog message:
<date> <machine> <application>: failed to create or access shared memory segment.The icastats utility prints an error message if it cannot create, access, or remove the shared memory segment.
You can view the shared memory segments and information about creators and owners with an ipcs command, for example:
ipcs -i ID ipcs -m