NAME

       pkcsstats - utility to display mechanism usage statistics for openCryptoki.

SYNOPSIS

       pkcsstats [OPTIONS]

       pkcsstats --help|-h

DESCRIPTION

       Displays  mechanism  usage  statistics for openCryptoki. Usage statistics are collected by
       openCryptoki on a per user basis. For each user, mechanism usage is counted per configured
       slot and mechanism. For each mechanism a set of counters exist, one for each cryptographic
       strength of the cryptographic key used with the mechanism.

       The   available   strengths   are   defined   in   the   strength    configuration    file
       /etc/opencryptoki/strength.conf.   Supported   strengths   are  112,  128,  192,  and  256
       representing the corresponding strength in bits.  The strength configuration file  defines
       how  the  strength  is determined for the various key types. 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.

       Note:  The  strength does not specify the cryptographic strength of the mechanism, but the
       cryptographic strength of the key used with the mechanism (if any).  For example, usage of
       mechanism  CKM_SHA256  is  reported  under  strength  0,  because no key is used with this
       mechanism. However, 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 the definitions
       in the strength configuration file).

       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. For example, RSA-PSS or RSA-OAEP allows
       to specify a hash mechanism  and  a  mask  generation  function  (MGF)  in  the  mechanism
       parameter.  ECDH  allows  to  specify  a  key  derivation  function (KDF) in the mechanism
       parameter. The PBKDF2 mechanism allows to specify a pseudo random function  (PRF)  in  the
       mechanism parameter.

       Also  optionally,  opencryptoki-internal mechanism usage statistics can be collected. This
       collects usage statistics for crypto operations  used  internally  for  pin  handling  and
       encryption of private token objects in the data store.

       Note:  Implicit  or  internal  mechanism  usage  can  not  be  distinguished from explicit
       mechanism usage of PKCS#11 applications in the displayed statistics.

       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  (when  not
       already  existent).  The shared memory segments can be deleted using the pkcsstats command
       with the --delete, or --delete-all options.

       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.

       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
              this option is omitted, the statistics of the current user are displayed, resetted,
              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  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.

       -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. This is usefull to get the statistics in a
              machine readable format.

       -h, --help
              Displays help text and exits.

SEE ALSO

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