1PKCSSTATS(1)                     openCryptoki                     PKCSSTATS(1)
2
3
4

NAME

6       pkcsstats - utility to display mechanism usage statistics for openCryp‐
7       toki.
8
9

SYNOPSIS

11       pkcsstats [OPTIONS]
12
13       pkcsstats --help|-h
14
15

DESCRIPTION

17       Displays mechanism usage statistics for openCryptoki. Usage  statistics
18       are collected by openCryptoki on a per user basis. For each user, mech‐
19       anism usage is counted per configured  slot  and  mechanism.  For  each
20       mechanism  a set of counters exist, one for each cryptographic strength
21       of the cryptographic key used with the mechanism.
22
23       The available strengths are defined in the strength configuration  file
24       /etc/opencryptoki/strength.conf. Supported strengths are 112, 128, 192,
25       and 256 representing the corresponding strength in bits.  The  strength
26       configuration file defines how the strength is determined for the vari‐
27       ous key types. A strength of zero is used  to  count  those  mechanisms
28       that do not use a key, or where the key strength is less than 112 bits.
29
30       Note:  The  strength does not specify the cryptographic strength of the
31       mechanism, but the cryptographic strength of  the  key  used  with  the
32       mechanism  (if any).  For example, usage of mechanism CKM_SHA256 is re‐
33       ported under strength 0, because no key is used  with  this  mechanism.
34       However, usage of mechanism CKM_AES_CBC is reported under strength 128,
35       192, or 256, dependent on the cryptographic size of the  AES  key  used
36       with it (and the definitions in the strength configuration file).
37
38       Statistics  collection  is  enabled  by default. It can be disabled and
39       configured  in  the  openCryptoki  configuration  file   /etc/opencryp‐
40       toki/opencryptoki.conf.   By default only explicit mechanism usage sta‐
41       tistics from PKCS#11 applications are collected.
42
43       Optionally, implicit mechanism usage statistics can be collected, where
44       additional  mechanisms are specified in mechanism parameters. For exam‐
45       ple, RSA-PSS or RSA-OAEP allows to specify a hash mechanism and a  mask
46       generation  function  (MGF)  in the mechanism parameter. ECDH allows to
47       specify a key derivation function (KDF) in the mechanism parameter. The
48       PBKDF2  mechanism  allows  to specify a pseudo random function (PRF) in
49       the mechanism parameter.
50
51       Also optionally, opencryptoki-internal mechanism usage  statistics  can
52       be collected. This collects usage statistics for crypto operations used
53       internally for pin handling and encryption of private token objects  in
54       the data store.
55
56       Note:  Implicit  or  internal  mechanism usage can not be distinguished
57       from explicit mechanism usage of PKCS#11 applications in the  displayed
58       statistics.
59
60       Statistics  are  collected  in  a POSIX shared memory segment per user.
61       This shared memory segment contains all  counters  for  all  configured
62       slots,  mechanisms, and strengths. The shared memory segments are named
63       var.lib.opencryptoki_stats_<uid>, where uid is the numeric  user-id  of
64       the user the statistics belong to. The shared memory segments are auto‐
65       matically created for a user on the first attempt to collect statistics
66       (when  not already existent). The shared memory segments can be deleted
67       using the pkcsstats command with the --delete, or --delete-all options.
68
69       The usage of a mechanism is counted once when the cryptographic  opera‐
70       tion  is  sucessfully  initialized, i.e. during C_DigestInit, C_Encryp‐
71       tInit, C_DecryptInit, C_SignInit, C_SignRecoverInit, and  C_VerifyInit.
72       Multi-part  operations  involving the update functions like C_DigestUp‐
73       date, C_EncryptUpdate, C_DecryptUpdate, C_SignUpdate,  and  C_VerifyUp‐
74       date, are not counted additionally.
75
76       Other  operations  such as key generation, key derivation, key wrapping
77       and unwrapping are counted during the respective functions like  C_Gen‐
78       erateKey, C_GenerateKeyPair, C_DeriveKey, C_DeriveKey, C_UnwrapKey.
79
80

OPTIONS

82       -U, --user user-id
83              Specifies  the  user-id of the user to display, reset, or delete
84              statistics for.  If this option is omitted,  the  statistics  of
85              the  current  user are displayed, resetted, or deleted. Only the
86              root user can display, reset,  or  delete  statistics  of  other
87              users.
88
89       -S, --summary
90              Shows  the  accumulated statistics from all users. Only the root
91              user can display the accumulated statistics from other users.
92
93       -A, --all
94              Shows the statistics from all users. Only the root user can dis‐
95              play statistics from all users.
96
97       -a, --all-mechs
98              Shows  the  statistics  for  all  mechanisms,  also  those  with
99              all-zero counters.  If this option is omitted, only those mecha‐
100              nisms are displayed where at least one counter is non-zero.
101
102       -s, --slot slot-id
103              Specifies  the slot-id to display statistics for. If this option
104              is omitted, the statistics for all  configured  slots  are  dis‐
105              played.
106
107       -r, --reset
108              Resets  the statistics counters for the current user, or for the
109              user specified with the --user option. Only the  root  user  can
110              reset the statistics from other users.
111
112       -R, --reset-all
113              Resets the statistics counters for all users. Only the root user
114              can reset the statistics from other users.
115
116       -d, --delete
117              Deletes the shared  memory  segment  containing  the  statistics
118              counters  for  the  current user, or for the user specified with
119              the --user option.  Only the root user can delete the statistics
120              from other users.
121
122       -D, --delete-all
123              Deletes  the  shared  memory  segment  containing the statistics
124              counters for all users. Only the root user can delete  the  sta‐
125              tistics from other users.
126
127       -j, --json
128              Shows  the statistics in JSON format. This is usefull to get the
129              statistics in a machine readable format.
130
131       -h, --help
132              Displays help text and exits.
133
134

SEE ALSO

136       opencryptoki.conf(5).
137       strength.conf(5),
138       opencryptoki(7),
139
140
141
142
1433.21.0                           October 2021                     PKCSSTATS(1)
Impressum