KCAPI-ENC(1)

💖 NAME 💖

kcapi-enc — Kernel Crypto API Symmetric Cipher Crypto Helper

---

🦋 SYNOPSIS 🦋

kcapi-enc [OPTION]

---

🌸 DESCRIPTION 🌸

okay so bestie, kcapi-enc is the little command-line bestie that lets you use the symmetric ciphers of the Linux kernel crypto API straight from your terminal. no kernel module drama, no writing C, just vibes. ✨

Your input data can come in either way: through STDIN, or from a file that you point at with a command line option. Same energy on the way out — the output either goes into a file you named with a command line option, or it goes to STDOUT. 💅

Now, the tea: most symmetric ciphers are block ciphers, and block ciphers are picky — they need the input data to be multiples of the block size. So kcapi-enc automatically adds padding when you're using a block cipher and your input data's size isn't a multiple of the cipher's block size, but only during encryption. The automated unpadding during decryption? That only happens when both the input and output data are provided as files. If either your input comes in via STDIN or your output goes out via STDOUT, the unpadding is not applied. no cap. 🫶

The padding schema used is consistent with OpenSSL's enc application. So data encrypted with OpenSSL's enc tool can be decrypted with kcapi-enc and vice versa. it's giving interoperability, we love to see it. 😭💖

The symmetric key used for the cryptographic operation can be provided either via a file descriptor or via a password. When you use a file descriptor, the data you provide is taken directly as the symmetric key. Here's the thing though — the Linux kernel crypto API does not allow specifying the used key size with the cipher algorithm name (so like, AES-128 or AES-256 cannot be specified, only AES), which means the size of the provided key defines which cipher operation is used. When you provide a password, kcapi-enc derives a 256 bit key from that password using PBKDF2. PBKDF2 with HMAC-SHA256 as default transforms the password into a key.

The PBKDF2 operation needs two extra 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. That 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. write it down bestie, fr fr. 📝

The following options are supported when invoking kcapi-enc:

---

✨ OPTIONS ✨

• -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.
• --key-len LENGTH — LENGTH specifies length of the key passed to the cipher algorithm. kcapi-enc uses 32-byte key by default.
• --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-hasher(1) kcapi-rng(1)

---

and that's the whole page bestie, you ate that 💅✨ this one's dated 2017-08-14 and it lives in the KCAPI-ENC(1) corner of the General Commands Manual — go forth and encrypt responsibly, mwah 🎀🦋💖