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

NAME

6       kcapi-enc - Kernel Crypto API Symmetric Cipher Crypto Helper
7

SYNOPSIS

9       kcapi-enc [OPTION]
10

DESCRIPTION

12       The kcapi-enc application provides tool to use the symmetric ciphers of
13       the Linux kernel crypto API from the command line.
14
15       The input data can be provided either via STDIN or via a file  that  is
16       referenced  with  a command line option. Similarly, the output data can
17       either be sent to a file referenced with a command line  option  or  to
18       STDOUT.
19
20       The majority of symmetric ciphers are block ciphers requiring the input
21       data to be multiples of the block size.  kcapi-enc  automatically  adds
22       padding  when  using  block  ciphers and input data whose size is not a
23       multiple of the cipher's block size  during  encryption.  An  automated
24       unpadding  during  decryption is only applied when the input and output
25       data is provided as files. If either the input  data  is  provided  via
26       STDIN  or  the output data is obtained via STDOUT, the unpadding is not
27       applied.
28
29       The used padding schema is consistent with OpenSSL's  enc  application.
30       Data  encrypted with OpenSSL's enc tool can be decrypted with kcapi-enc
31       and vice versa.
32
33       The symmetric key used for the cryptographic operation  can  either  be
34       provided  via  a  file  descriptor or via a password. When using a file
35       descriptor, the provided data is taken directly as the  symmetric  key.
36       As  the  Linux kernel crypto API does not allow specifying the used key
37       size with the cipher algorithm name (e.g. AES-128 or AES-256 cannot  be
38       specified,  but  only  AES), the size of the provided key defines which
39       cipher operation is used. When  providing  a  password,  the  kcapi-enc
40       application  derives  a  256  bit  key  from the password using PBKDF2.
41       PBKDF2 with HMAC-SHA256 as default transforms the password into a  key.
42       The  PBKDF2  operation requires two additional input values: a salt and
43       an iteration count. Both can be provided via the command line.  If  the
44       iteration  count  is  not specified, kcapi-enc determines the iteration
45       count internally by counting how many iterations are necessary to  sur‐
46       pass 100ms operation time. The determined number is provided via STDERR
47       and must be re-used when decrypting the data. If the salt is  not  pro‐
48       vided  via  command  line, kcapi-enc generates a 256 bit salt and sends
49       its hexadecimal representation to STDERR. This salt must be used during
50       decryption to ensure the PBKDF2 operation generates the correct symmet‐
51       ric key.
52
53       The following options are supported when invoking kcapi-enc:
54
55       -c, --cipher NAME
56              The NAME argument specifies the symmetric cipher to be used. The
57              allowed  ciphers are defined by the Linux kernel. Currently reg‐
58              istered ciphers can be reviewed at /proc/crypto.  The content of
59              this  file, however, can change when new ciphers are registered.
60              The NAME argument is given directly to the Linux  kernel  crypto
61              API.  The  chosen  cipher  must be either of type skcipher or of
62              type aead as marked in /proc/crypto.
63
64       -e, --encrypt
65              Perform an encryption operation on the input data. This  is  the
66              default  behavior which implies that this option can be skipped.
67              The input data is automatically padded if the the data  size  is
68              not a multiple of the block size of the chosen cipher.
69
70       -d, --decrypt
71              Perform  a  decryption  operation  on  the input data. Automated
72              unpadding is performed only when the input and  output  data  is
73              provided via files referenced with the command line options.
74
75       -i, --infile FILE
76              Use  the  file  referenced  with FILE as the input data. If this
77              option is not provided, kcapi-enc expects  the  input  data  via
78              STDIN.
79
80       -o, --outfile FILE
81              Use  the  file  referenced  with FILE as the destination for the
82              output of the cryptographic operation. If  this  option  is  not
83              provided, kcapi-enc will provide the output via STDOUT.
84
85       --iv IV
86              Use  the  IV data as initialization vector for the cryptographic
87              operation.  That IV value is expected to be a hexadecimal  nota‐
88              tion  and  must  match the block size of the chosen cipher. When
89              the CTR block chaining mode is used, the IV value is  the  start
90              value  of  the  counter.  When using the CCM cipher, the IV must
91              specify the initialization vector. If the CCM  nonce  should  be
92              specified instead, the option --ccm-nonce must be used instead.
93
94       --aad AAD
95              For  AEAD  ciphers  like  CCM, GCM or the authenc ciphers of the
96              Linux kernel crypto API, the additional authentication data  can
97              be  provided  with  the  AAD  parameter. The data is expected in
98              hexadecimal format.
99
100       --tag TAG
101              The AEAD tag value required for the decryption operation is pro‐
102              vided  with  the  TAG  parameter.  This parameter is expected in
103              hexadecimal format.
104
105       --taglen LENGTH
106              During encryption operation of AEAD ciphers, the tag  is  gener‐
107              ated. It is permissible to generate differently sized tags where
108              the parameter LENGTH specifies the size of the tag value  to  be
109              generated in bytes.
110
111       --ccm-nonce NONCE
112              Use the NONCE data as CCM nonce as defined in SP800-38C Appendix
113              A.2. That NONCE value is expected to be a  hexadecimal  notation
114              and must match the constraints of SP800-38C Appendix A.2.
115
116       --salt SALT
117              When performing the PBKDF2 operation to obtain the symmetric key
118              from the password, the SALT value is used as one  input  parame‐
119              ter.  To ensure the same symmetric key is generated from a given
120              password, the same salt value must be used.  This  implies  that
121              during  decryption,  the  same  salt  used during the encryption
122              operation must be referenced.  kcapi-enc is unable to  determine
123              whether  the symmetric key derived from the password is the cor‐
124              rect one to decrypt the data, because  any  symmetric  key  will
125              always successfully decrypt data. Yet, the resulting data may be
126              different from what is expected.
127
128       -p, --passwd PASSWORD
129              The PASSWORD parameter provides the password from which the sym‐
130              metric  key  is  derived  used  to  encrypt or decrypt the data.
131              WARNING The password provided with the command line can be  seen
132              from  other applications or users when inspecting the /proc file
133              system! Thus, a password SHOULD NOT be used via the command line
134              and the passwdfd option should be used instead.
135
136       --passwdfd FD
137              Instead  of  providing  the password via command line, it can be
138              injected into  kcapi-enc  using  a  file  descriptor.  The  file
139              descriptor  number the password will be send through can be pro‐
140              vided with the FD option.
141
142       --pbkdfiter NUM
143              Perform NUM iterations of the PBKDF2  operation  to  derive  the
144              symmetric key.  If this option is not supplied, kcapi-enc deter‐
145              mines a number of iterations that is  large  enough  to  surpass
146              100ms  operational  time for the PBKDF2 function. The determined
147              iteration number is logged and must be reused if the  same  sym‐
148              metric key is to be generated from the same password.
149
150       --pbkdfmac MAC
151              Use  the keyed message digest referenced with MAC for the PBKDF2
152              operation. If this  option  is  not  supplied,  the  default  of
153              hmac(sha256) is used.
154
155       --keyfd FD
156              To provide a symmetric key that is directly used for the crypto‐
157              graphic operation, the file descriptor referenced with  FD  must
158              be  used.  Using a file descriptor is intentionally the only way
159              to provide a symmetric key to kcapi-enc.
160
161       --nounpad
162              During decryption and when the input data is provided via a file
163              as  well as the output is written to a file, kcapi-enc automati‐
164              cally tries to detect a padding and removes the padding data. If
165              this automated unpadding is not desired, the nounpad option will
166              prevent the unpadding.
167
168       -v, --verbose
169              Enable a verbose operation of kcapi-enc.  Using this option mul‐
170              tiple times increases the verbosity.
171
172       -q, --quiet
173              Prevent  the generation of any log output. Note, some log output
174              would be needed for proper operation like  the  display  of  the
175              number  of  PBKDF2 iterations or the internally generated PBKDF2
176              salt.  During quiet operation, none of this information is  dis‐
177              played.   Note,  both  information  can also be supplied via the
178              command line so that kcapi-enc does not need  to  generate  this
179              information.
180
181       -h, --help
182              Display the help text.
183
184       --version
185              Display the version number of the kcapi-enc application.
186

SEE ALSO

188       kcapi-dgst(1) kcapi-rng(1)
189
190
191
192                                  2017-08-14                      KCAPI-ENC(1)
Impressum