kcapi-dgst

KCAPI-DGST(1)               General Commands Manual              KCAPI-DGST(1)



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-rng(1)



                                  2017-08-14                     KCAPI-DGST(1)