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)