kcapi-enc

KCAPI-ENC(1)                General Commands Manual               KCAPI-ENC(1)



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)