DOKK / manpages / debian 10 / kcapi-tools / kcapi-dgst.1.en
KCAPI-DGST(1) General Commands Manual KCAPI-DGST(1)

kcapi-dgst - Kernel Crypto API Message Digest Crypto Helper

kcapi-dgst [OPTION]

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:

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.
Use the file referenced with FILE as the input data. If this option is not provided, kcapi-dgst expects the input data via STDIN.
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.
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.
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.
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.
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.
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.
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.
The generated message digest is print out in hexadecimal notation instead of as binary string.
Enable a verbose operation of kcapi-dgst. Using this option multiple times increases the verbosity.
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.
Display the help text.
Display the version number of the kcapi-dgst application.

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

2017-08-14