1KCAPI-DGST(1) General Commands Manual KCAPI-DGST(1)
2
6 kcapi-dgst - Kernel Crypto API Message Digest Crypto Helper
7
9 kcapi-dgst [OPTION]
10
12 The kcapi-dgst application provides tool to use the message digest as
13 well as keyed message digest ciphers of the Linux kernel crypto API
14 from the command line.
15 The input data can be provided either via STDIN or via a file that is
17 referenced with a command line option. Similarly, the output data can
18 either be sent to a file referenced with a command line option or to
19 STDOUT.
20 The key used for the keyed message digest operation can either be pro‐
22 vided via a file descriptor or via a password. When using a file
23 descriptor, the provided data is taken directly as the keyed message
24 digest key. When providing a password, the kcapi-dgst application
25 derives a 256 bit key from the password using PBKDF2. PBKDF2 with
26 HMAC-SHA256 as default transforms the password into a key. The PBKDF2
27 operation requires two additional input values: a salt and an iteration
28 count. Both can be provided via the command line. If the iteration
29 count is not specified, kcapi-dgst determines the iteration count
30 internally by counting how many iterations are necessary to surpass
31 100ms operation time. The determined number is provided via STDERR and
32 must be re-used when verifying the keyed message digest created from
33 the data. If the salt is not provided via command line, kcapi-dgst gen‐
34 erates a 256 bit salt and sends its hexadecimal representation to
35 STDERR. This salt must be used during decryption to ensure the PBKDF2
36 operation generates the correct key.
37 The following options are supported when invoking kcapi-dgst:
39 -c, --cipher NAME
41 The NAME argument specifies the digest cipher to be used. The
42 allowed ciphers are defined by the Linux kernel. Currently reg‐
43 istered ciphers can be reviewed at /proc/crypto. The content of
44 this file, however, can change when new ciphers are registered.
45 The NAME argument is given directly to the Linux kernel crypto
46 API. The chosen cipher must be either of type ahash or of type
47 shash as marked in /proc/crypto.
48 -i, --infile FILE
50 Use the file referenced with FILE as the input data. If this
51 option is not provided, kcapi-dgst expects the input data via
52 STDIN.
53 -o, --outfile FILE
55 Use the file referenced with FILE as the destination for the
56 output of the cryptographic operation. If this option is not
57 provided, kcapi-dgst will provide the output via STDOUT.
58 --salt SALT
60 When performing the PBKDF2 operation to obtain the key for the
61 keyed message digest from the password, the SALT value is used
62 as one input parameter. To ensure the same key is generated from
63 a given password, the same salt value must be used.
64 -p, --passwd PASSWORD
66 The PASSWORD parameter provides the password from which the
67 keyed message digest key is derived. WARNING The password pro‐
68 vided with the command line can be seen from other applications
69 or users when inspecting the /proc file system! Thus, a password
70 SHOULD NOT be used via the command line and the passwdfd option
71 should be used instead.
72 --passwdfd FD
74 Instead of providing the password via command line, it can be
75 injected into kcapi-dgst using a file descriptor. The file
76 descriptor number the password will be send through can be pro‐
77 vided with the FD option.
78 --pbkdfiter NUM
80 Perform NUM iterations of the PBKDF2 operation to derive the
81 keyed message digest key. If this option is not supplied, kcapi-
82 dgst determines a number of iterations that is large enough to
83 surpass 100ms operational time for the PBKDF2 function. The
84 determined iteration number is logged and must be reused if the
85 same keyed message digest key is to be generated from the same
86 password.
87 --pbkdfmac MAC
89 Use the keyed message digest referenced with MAC for the PBKDF2
90 operation. If this option is not supplied, the default of
91 hmac(sha256) is used.
92 --keyfd FD
94 To provide a keyed message digest key that is directly used for
95 the message digest operation, the file descriptor referenced
96 with FD must be used. Using a file descriptor is intentionally
97 the only way to provide a key to kcapi-dgst.
98 --hex The generated message digest is print out in hexadecimal nota‐
100 tion instead of as binary string.
101 -v, --verbose
103 Enable a verbose operation of kcapi-dgst. Using this option
104 multiple times increases the verbosity.
105 -q, --quiet
107 Prevent the generation of any log output. Note, some log output
108 would be needed for proper operation like the display of the
109 number of PBKDF2 iterations or the internally generated PBKDF2
110 salt. During quiet operation, none of this information is dis‐
111 played. Note, both information can also be supplied via the
112 command line so that kcapi-dgst does not need to generate this
113 information.
114 -h, --help
116 Display the help text.
117 --version
119 Display the version number of the kcapi-dgst application.
120
122 kcapi-enc(1) kcapi-rng(1)
123 2017-08-14 KCAPI-DGST(1)