NAME

       kcapi-dgst - Kernel Crypto API Message Digest Crypto Helper

SYNOPSIS

       kcapi-dgst [OPTION]

DESCRIPTION

       The  kcapi-dgst  application  provides  tool  to  use  the message digest as well as keyed message digest
       ciphers of the Linux kernel crypto API from the command line.

       The input data can be provided either via STDIN or via a file that is  referenced  with  a  command  line
       option.  Similarly, the output data can either be sent to a file referenced with a command line option or
       to STDOUT.

       The key used for the keyed message digest operation can either be provided via a file descriptor or via a
       password. When using a file descriptor, the provided data is taken directly as the keyed  message  digest
       key.  When providing a password, the kcapi-dgst application derives a 256 bit key from the password using
       PBKDF2.  PBKDF2 with HMAC-SHA256 as default transforms the password into a  key.   The  PBKDF2  operation
       requires two additional input values: a salt and an iteration count. Both can be provided via the command
       line.  If  the  iteration count is not specified, kcapi-dgst determines the iteration count internally by
       counting how many iterations are necessary to surpass 100ms operation  time.  The  determined  number  is
       provided via STDERR and must be re-used when verifying the keyed message digest created from the data. If
       the  salt is not provided via command line, kcapi-dgst generates a 256 bit salt and sends its hexadecimal
       representation to STDERR. This salt must be  used  during  decryption  to  ensure  the  PBKDF2  operation
       generates the correct key.

       The following options are supported when invoking kcapi-dgst:

       -c, --cipher NAME
              The  NAME  argument specifies the digest cipher to be used. The allowed ciphers are defined by the
              Linux kernel. Currently registered ciphers can be reviewed at /proc/crypto.  The content  of  this
              file,  however, can change when new ciphers are registered. The NAME argument is given directly to
              the Linux kernel crypto API. The chosen cipher must be either of type ahash or of  type  shash  as
              marked in /proc/crypto.

       -i, --infile FILE
              Use  the  file  referenced with FILE as the input data. If this option is not provided, kcapi-dgst
              expects the input data via STDIN.

       -o, --outfile FILE
              Use the file referenced with  FILE  as  the  destination  for  the  output  of  the  cryptographic
              operation. If this option is not provided, kcapi-dgst will provide the output via STDOUT.

       --salt SALT
              When  performing  the  PBKDF2  operation  to  obtain the key for the keyed message digest from the
              password, the SALT value is used as one input parameter. To ensure the same key is generated  from
              a given password, the same salt value must be used.

       -p, --passwd PASSWORD
              The  PASSWORD  parameter provides the password from which the keyed message digest key is derived.
              WARNING The password provided with the command line can be seen from other applications  or  users
              when  inspecting  the  /proc file system! Thus, a password SHOULD NOT be used via the command line
              and the passwdfd option should be used instead.

       --passwdfd FD
              Instead of providing the password via command line, it can be injected  into  kcapi-dgst  using  a
              file descriptor. The file descriptor number the password will be send through can be provided with
              the FD option.

       --pbkdfiter NUM
              Perform  NUM  iterations  of  the PBKDF2 operation to derive the keyed message digest key. If this
              option is not supplied, kcapi-dgst determines a number of  iterations  that  is  large  enough  to
              surpass  100ms operational time for the PBKDF2 function. The determined iteration number is logged
              and must be reused if the same keyed message digest key is to be generated from the same password.

       --pbkdfmac MAC
              Use the keyed message digest referenced with MAC for the PBKDF2 operation. If this option  is  not
              supplied, the default of hmac(sha256) is used.

       --keyfd FD
              To  provide a keyed message digest key that is directly used for the message digest operation, the
              file descriptor referenced with FD must be used. Using a file descriptor is intentionally the only
              way to provide a key to kcapi-dgst.

       --hex  The generated message digest is print out in hexadecimal notation instead of as binary string.

       -v, --verbose
              Enable a verbose operation  of  kcapi-dgst.   Using  this  option  multiple  times  increases  the
              verbosity.

       -q, --quiet
              Prevent  the  generation  of  any  log  output.  Note,  some log output would be needed for proper
              operation like the display of the number of PBKDF2 iterations or the internally  generated  PBKDF2
              salt.   During quiet operation, none of this information is displayed.  Note, both information can
              also be supplied via the  command  line  so  that  kcapi-dgst  does  not  need  to  generate  this
              information.

       -h, --help
              Display the help text.

       --version
              Display the version number of the kcapi-dgst application.

SEE ALSO

       kcapi-enc(1) kcapi-hasher(1) kcapi-rng(1)

                                                   2017-08-14                                      KCAPI-DGST(1)