Provided by: kcapi-tools_1.4.0-1_amd64 bug

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)