1KCAPI-ENC(1) General Commands Manual KCAPI-ENC(1)
2
3
4
6 kcapi-enc - Kernel Crypto API Symmetric Cipher Crypto Helper
7
9 kcapi-enc [OPTION]
10
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
188 kcapi-dgst(1) kcapi-rng(1)
189
190
191
192 2017-08-14 KCAPI-ENC(1)