libipsec-mb(7)

✨ libipsec-mb — the manual page, but make it a vibe ✨

okay bestie, sit down, hydrate, and let me tell you about libipsec-mb from the Linux Programmer's Manual 💖 this is the overview of the Intel(R) Multi-Buffer Crypto for IPSec library and honestly? it's giving optimized. it's giving packet processing. periodt.

---

🌸 NAME 🌸

libipsec-mb — an overview of the Intel(R) Multi-Buffer Crypto for IPSec library. that's the whole name, no notes, we love a title that tells you exactly what it is 💅

---

🦋 DESCRIPTION 🦋

so the Intel Multi-Buffer Crypto for IPsec Library is out here providing highly-optimized software crypto implementations that target packet processing applications — think IPsec, TLS, Wireless (RAN), Cable and MPEG DRM 🎀 and it brings industry-leading performance across a whole range of Intel(R) Processors. iconic behavior, truly.

the library offers an API crafted for applications where a buffer is the subject of encryption and/or integrity operations. no cap.

and for best processor utilization it uses multi buffer technology for algorithms that don't allow multi block processing. slay.

there's more lore in the Intel White Paper: "Fast Multi-buffer IPsec Implementations on Intel Architecture Processors" by Jim Guilford, Sean Gulley, et. al. — and the easiest way to find it is literally just to search the Internet for the title 🔍 iykyk.

more info can be found at intel-ipsec-mb ✨

🔐 ENCRYPTION ALGORITHMS 🔐

the lineup, and yes every single one of them:

AES128-GCM, AES192-GCM, AES256-GCM, AES128-CBC, AES192-CBC, AES256-CBC, AES128-CTR, AES192-CTR, AES256-CTR, AES128-CCM, AES256-CCM, AES128-ECB, AES192-ECB, AES256-ECB, NULL, AES128-DOCSIS, AES256-DOCSIS, DES-DOCSIS, 3DES, DES, KASUMI-F8, ZUC-EEA3, ZUC-EEA3-256, SNOW3G-UEA2, AES128-CBCS, CHACHA20, CHACHA20 AEAD, SNOW-V, SNOW-V AEAD and PON-CRC-BIP. the whole roster showed up and ate 🍓

🛡️ INTEGRITY ALGORITHMS 🛡️

same energy, same energy:

AES-XCBC-96, HMAC-MD5-96, HMAC-SHA1-96, HMAC-SHA2-224_112, HMAC-SHA2-256_128, HMAC-SHA2-384_192, HMAC-SHA2-512_256, AES128-GMAC, AES192-GMAC, AES256-GMAC, NULL, AES128-CCM, AES256-CCM, AES128-CMAC-96, AES256-CMAC-96, KASUMI-F9, ZUC-EIA3, ZUC-EIA3-256, SNOW3G-UIA2, DOCSIS-CRC32, HEC, POLY1305, POLY1305 AEAD, SNOW-V AEAD, GHASH, PON-CRC-BIP as well as multiple CRC types 💜 (the hyphenated ones like HMAC-SHA2-224_112 are spelled exactly like that, do not come for me, I am just the messenger)

💀 RECOMMENDATIONS 💀

listen. this is the part where I get a little stern, because I love you:

• DES algorithm should be avoided, and AES encryption should be used instead.
• 3DES is a legacy algorithm, and AES encryption is recommended to use instead.
• HMAC-MD5-96 is a legacy algorithm, and HMAC-SHA1 is recommended to use instead.
• DES, 3DES and HMAC-MD5-96 are implemented in the library to support legacy applications — they're here for the old stuff, not the new stuff.
• AES-ECB algorithm should be avoided, and AES-CBC or AES-CNTR encryption should be used instead.

bestie the legacy ones are legacy for a REASON. no cap. do not build your new thing on DES. I'm begging 🙏

🔑 KEY STORAGE 🔑

the library doesn't offer any solution for secure key storage or storage of sensitive information. it is up to the application to arrange safe storage of sensitive information.

so yeah — key management? not this library's job. that's on you, bestie. protect your keys, they're the whole main character 👑

🎀 API 🎀

the library offers four sets of identical API's. each set corresponds to one architecture: SSE, AVX, AVX2 and AVX512. four flavors, same vibe.

it comprises of init_mb_mgr, get_next_job, submit_job, get_completed_job and flush_job operations. here's what each one does:

• init_mb_mgr() — initializes the instance of the multi-buffer manager 🌱
• get_next_job() — obtains pointer to next available job entry 📥
• submit_job() — submits job for processing 🚀
• get_completed_job() — returns already completed jobs ✅
• flush_job() — flushes multi-buffer manager and completes any outstanding operations 🚿

the basic usage of the API is presented by this pseudo code:

init_mb_mgr(&mb_mgr);
...
while (work_to_be_done) {
        job = get_next_job(&mb_mgr);
        /* TODO: Fill in job fields */
        job = submit_job(&mb_mgr);
        while (job != NULL) {
                /* TODO: Complete processing on job */
                 job = get_completed_job(&mb_mgr);
        }
}

job = flush_job(&mb_mgr);
while (job != NULL) {
        /* TODO: Complete processing on job */
         job = flush_job(&mb_mgr);
}

(those /* TODO: ... */ lines are literally in the source, so I'm leaving them exactly where they are, bestie 💖)

the library provides more interface functions i.e. single block hash functions for HMAC OPAD and IPAD calculations ✨

---

🐛 BUGS 🐛

report bugs at intel-ipsec-mb/issues — go tell the maintainers, they wanna know, they're so nice about it 🫶

---

👑 AUTHORS 👑

Jim Guilford <james.guilford@intel.com>, Tomasz Kantecki <tomasz.kantecki@intel.com> — legends, honestly.

this is free software; see the source for copying conditions. there is NO warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.

okay that last bit is real important and I need you to actually read it: NO WARRANTY. none. zero. not even the implied ones. it's giving "use at your own risk" but make it legal 🫠

---

and that's the whole page, bestie 🎀 this one's from the Linux manual, libipsec-mb(7), dated 2018-03-01 — go forth and encrypt responsibly, you absolute icon 💅✨🦋