Provided by: kcapi-tools_1.4.0-1_amd64 
NAME
kcapi-enc - Kernel Crypto API Symmetric Cipher Crypto Helper
SYNOPSIS
kcapi-enc [OPTION]
DESCRIPTION
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.
SEE ALSO
kcapi-dgst(1) kcapi-rng(1)
2017-08-14 KCAPI-ENC(1)