KCAPI-DGST(1)

💖 KCAPI-DGST 💖

okay bestie, gather round, because we're about to talk about kcapi-dgst — the Kernel Crypto API Message Digest Crypto Helper, living its best life in section 1 of the manual (General Commands Manual, for the record 👑). She's a command-line queen and she does message digests. Keyed ones too. Let's get into it. ✨

---

✨ SYNOPSIS ✨

kcapi-dgst [OPTION]

that's it. that's the whole vibe. one command, a pile of options, infinite possibilities 🦋

---

🌸 DESCRIPTION 🌸

so the whole point of kcapi-dgst is that it's a tool to use the message digest as well as keyed message digest ciphers of the Linux kernel crypto API — from the command line. no cap. you just run it and the kernel does the fancy math. 💅

Where does the data come in, you ask? Two ways, bestie:

• via STDIN, or
• via a file that you reference with a command line option.

And where does the data go out? Also two ways:

• to a file referenced with a command line option, or
• to STDOUT.

Balance. Symmetry. Iconic. 🎀

Now, the key for the keyed message digest operation — this is the part where you need to pay attention, fr fr. You can provide it either:

• via a file descriptor, or
• via a password.

When you use a file descriptor, the data you hand over is taken directly as the keyed message digest key. Straight up. No middleman, no transformation, the raw thing. 💯

When you provide a password, though, kcapi-dgst goes and derives a 256 bit key from the password using PBKDF2. And the default? PBKDF2 with HMAC-SHA256 as default transforms the password into a key. That's the setup. 🧚

But listen, PBKDF2 is needy — she requires two additional input values:

1. a salt, and
2. an iteration count.

Both can be provided via the command line. And if you don't?

• If the iteration count is not specified, kcapi-dgst 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 verifying the keyed message digest created from the data. Do not lose that number, bestie, I am begging. 😭
• If the salt is not provided via command line, kcapi-dgst 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 key. So screenshot it, copy it, tattoo it, whatever — just keep it. 💀

The following options are supported when invoking kcapi-dgst:

---

🎀 OPTIONS 🎀

• -c, --cipher NAME — this one sets the digest cipher to be used. The allowed ciphers are defined by the Linux kernel (so the kernel is the one gatekeeping here 👑). Currently registered ciphers can be reviewed at /proc/crypto. Fair warning though: the content of this file can change when new ciphers are registered. The NAME argument is given directly to the Linux kernel crypto API. And the chosen cipher must be either of type ahash or of type shash as marked in /proc/crypto. no exceptions, bestie.
• -i, --infile FILE — use the file referenced with FILE as the input data. If you don't provide this option, kcapi-dgst expects the input data via STDIN. pick your fighter 🦋
• -o, --outfile FILE — use the file referenced with FILE as the destination for the output of the cryptographic operation. If you don't provide this option, kcapi-dgst will provide the output via STDOUT. slay ✨
• --salt SALT — when performing the PBKDF2 operation to obtain the key for the keyed message digest from the password, the SALT value is used as one input parameter. And to ensure the same key is generated from a given password, the same salt value must be used. consistency is key, literally. 🔑
• -p, --passwd PASSWORD — the PASSWORD parameter provides the password from which the keyed message digest key is derived.

⚠️ 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. like, seriously, don't do it. the whole group chat can read it. 😭

• --passwdfd FD — instead of providing the password via command line, it can be injected into kcapi-dgst using a file descriptor. The file descriptor number the password will be send through can be provided with the FD option. this is the safe way, do this one. 🫶
• --pbkdfiter NUM — perform NUM iterations of the PBKDF2 operation to derive the keyed message digest key. If this option is not supplied, kcapi-dgst 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 keyed message digest key is to be generated from the same password. write it down. on your hand. in your notes app. wherever. 💅
• --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. the default is lowkey perfect but you do you. 🌈
• --keyfd FD — to provide a keyed message digest key that is directly used for the message digest operation, the file descriptor referenced with FD must be used. And here's the thing: using a file descriptor is intentionally the only way to provide a key to kcapi-dgst. intentional. on purpose. by design. 💅
• --hex — the generated message digest is printed out in hexadecimal notation instead of as a binary string. cute, readable, no weird characters in your terminal. 🎀
• -v, --verbose — enable a verbose operation of kcapi-dgst. Using this option multiple times increases the verbosity. stack it like your skincare routine. ✨
• -q, --quiet — prevent the generation of any log output. But heads up bestie: 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. The good news? Both pieces of information can also be supplied via the command line, so that kcapi-dgst does not need to generate this information. so quiet mode works fine as long as you bring the numbers. 🤫
• -h, --help — display the help text. when in doubt, ask for help. very main character of you. 💖
• --version — display the version number of the kcapi-dgst application. 📌

---

👑 SEE ALSO 👑

• kcapi-enc(1)
• kcapi-hasher(1)
• kcapi-rng(1)

go read those too, they're all part of the same iconic little family. 🦋

---

💜 and that's the page!! this one is dated 2017-08-14, from the General Commands Manual, section 1 — so if you ever need to cite her, you know exactly where she lives. stay hydrated, use --passwdfd instead of --passwd, and never lose your salt. bye bestie!! 🎀✨💖