kcapi-enc - Kernel Crypto API Symmetric Cipher Crypto Helper
The kcapi-enc application provides tool to use the
symmetric 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 majority of symmetric ciphers are block ciphers requiring the
input data to be multiples of the block size. kcapi-enc automatically
adds padding when using block ciphers and input data whose size is not a
multiple of the cipher's block size during encryption. An automated
unpadding during decryption is only applied when the input and output data
is provided as files. If either the input data is provided via STDIN or the
output data is obtained via STDOUT, the unpadding is not applied.
The used padding schema is consistent with OpenSSL's enc
application. Data encrypted with OpenSSL's enc tool can be decrypted
with kcapi-enc and vice versa.
The symmetric key used for the cryptographic 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 symmetric key. As the
Linux kernel crypto API does not allow specifying the used key size with the
cipher algorithm name (e.g. AES-128 or AES-256 cannot be specified, but only
AES), the size of the provided key defines which cipher operation is used.
When providing a password, the kcapi-enc 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-enc 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 decrypting
the data. If the salt is not provided via command line, kcapi-enc
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 symmetric key.
The following options are supported when invoking
kcapi-enc:
- -c, --cipher
NAME
- The NAME argument specifies the symmetric 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 skcipher or of type aead as
marked in /proc/crypto.
- -e, --encrypt
- Perform an encryption operation on the input data. This is the default
behavior which implies that this option can be skipped. The input data is
automatically padded if the the data size is not a multiple of the block
size of the chosen cipher.
- -d, --decrypt
- Perform a decryption operation on the input data. Automated unpadding is
performed only when the input and output data is provided via files
referenced with the command line options.
- -i, --infile
FILE
- Use the file referenced with FILE as the input data. If this option
is not provided, kcapi-enc expects the input data via STDIN.
- -o, --outfile
FILE
- Use the file referenced with FILE as the destination for the output
of the cryptographic operation. If this option is not provided,
kcapi-enc will provide the output via STDOUT.
- --iv IV
- Use the IV data as initialization vector for the cryptographic
operation. That IV value is expected to be a hexadecimal notation
and must match the block size of the chosen cipher. When the CTR block
chaining mode is used, the IV value is the start value of the
counter. When using the CCM cipher, the IV must specify the
initialization vector. If the CCM nonce should be specified instead, the
option --ccm-nonce must be used instead.
- --aad AAD
- For AEAD ciphers like CCM, GCM or the authenc ciphers of the Linux kernel
crypto API, the additional authentication data can be provided with the
AAD parameter. The data is expected in hexadecimal format.
- --tag TAG
- The AEAD tag value required for the decryption operation is provided with
the TAG parameter. This parameter is expected in hexadecimal
format.
- --taglen
LENGTH
- During encryption operation of AEAD ciphers, the tag is generated. It is
permissible to generate differently sized tags where the parameter
LENGTH specifies the size of the tag value to be generated in
bytes.
- --ccm-nonce
NONCE
- Use the NONCE data as CCM nonce as defined in SP800-38C Appendix
A.2. That NONCE value is expected to be a hexadecimal notation and
must match the constraints of SP800-38C Appendix A.2.
- --salt
SALT
- When performing the PBKDF2 operation to obtain the symmetric key from the
password, the SALT value is used as one input parameter. To ensure
the same symmetric key is generated from a given password, the same salt
value must be used. This implies that during decryption, the same salt
used during the encryption operation must be referenced. kcapi-enc
is unable to determine whether the symmetric key derived from the password
is the correct one to decrypt the data, because any symmetric key will
always successfully decrypt data. Yet, the resulting data may be different
from what is expected.
- -p, --passwd
PASSWORD
- The PASSWORD parameter provides the password from which the
symmetric key is derived used to encrypt or decrypt the data.
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.
- --passwdfd
FD
- Instead of providing the password via command line, it can be injected
into kcapi-enc using a file descriptor. The file descriptor number
the password will be send through can be provided with the FD
option.
- --pbkdfiter
NUM
- Perform NUM iterations of the PBKDF2 operation to derive the
symmetric key. If this option is not supplied, kcapi-enc 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 symmetric key is to be generated from the
same password.
- --pbkdfmac
MAC
- 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.
- --keyfd
FD
- To provide a symmetric key that is directly used for the cryptographic
operation, the file descriptor referenced with FD must be used.
Using a file descriptor is intentionally the only way to provide a
symmetric key to kcapi-enc.
- --nounpad
- During decryption and when the input data is provided via a file as well
as the output is written to a file, kcapi-enc automatically tries
to detect a padding and removes the padding data. If this automated
unpadding is not desired, the nounpad option will prevent the
unpadding.
- -v, --verbose
- Enable a verbose operation of kcapi-enc. Using this option multiple
times increases the verbosity.
- -q, --quiet
- 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-enc does
not need to generate this information.
- -h, --help
- Display the help text.
- --version
- Display the version number of the kcapi-enc application.