1KCAPI-DGST(1)               General Commands Manual              KCAPI-DGST(1)
2
3
4

NAME

6       kcapi-dgst - Kernel Crypto API Message Digest Crypto Helper
7

SYNOPSIS

9       kcapi-dgst [OPTION]
10

DESCRIPTION

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
16       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
21       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 de‐
23       scriptor, the provided data is taken directly as the keyed message  di‐
24       gest key. When providing a password, the kcapi-dgst application derives
25       a 256 bit key from the password using PBKDF2.  PBKDF2 with  HMAC-SHA256
26       as  default  transforms  the password into a key.  The PBKDF2 operation
27       requires two additional input values: a salt and  an  iteration  count.
28       Both  can  be  provided via the command line. If the iteration count is
29       not specified, kcapi-dgst determines the iteration count internally  by
30       counting  how  many iterations are necessary to surpass 100ms operation
31       time. The determined number is provided via STDERR and must be  re-used
32       when  verifying  the keyed message digest created from the data. If the
33       salt is not provided via command line, kcapi-dgst generates a  256  bit
34       salt and sends its hexadecimal representation to STDERR. This salt must
35       be used during decryption to ensure the PBKDF2 operation generates  the
36       correct key.
37
38       The following options are supported when invoking kcapi-dgst:
39
40       -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
49       -i, --infile FILE
50              Use the file referenced with FILE as the input data. If this op‐
51              tion is not provided, kcapi-dgst  expects  the  input  data  via
52              STDIN.
53
54       -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
59       --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
65       -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
73       --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  de‐
76              scriptor  number  the  password will be send through can be pro‐
77              vided with the FD option.
78
79       --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 de‐
84              termined 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
88       --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
93       --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
99       --hex  The  generated  message digest is print out in hexadecimal nota‐
100              tion instead of as binary string.
101
102       -v, --verbose
103              Enable a verbose operation of  kcapi-dgst.   Using  this  option
104              multiple times increases the verbosity.
105
106       -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
115       -h, --help
116              Display the help text.
117
118       --version
119              Display the version number of the kcapi-dgst application.
120

SEE ALSO

122       kcapi-enc(1) kcapi-rng(1)
123
124
125
126                                  2017-08-14                     KCAPI-DGST(1)
Impressum