Intel(R) Multi-Buffer Crypto for IPsec Library

The Intel(R) Multi-Buffer Crypto for IPsec Library is a software crypto acceleration library designed primarily for packet processing applications. It is suitable for high-performance use cases such as IPsec, TLS, Wireless (RAN), Cable, or MPEG DRM.

Developers can integrate this library in two ways:

1. Via Frameworks: Use it as a software crypto provider within existing frameworks like DPDK, Intel(R) QAT Engine, or FD.io. This allows you to switch crypto providers without modifying your application code.
2. Directly: Use the library's native API for direct integration into your application.

Key technical features include:

• Operation Chaining: Combines encryption and authentication operations.
• Advanced Cryptographic Pipelining: Includes a job manager with scheduling and dispatching functions that abstracts implementation details.
• Performance Innovations: Utilizes multi-buffer and function stitching techniques.
• Hardware Optimization: Low-level implementations leverage the latest CPU instruction extensions.

If your application needs to support both WSM (SSE) and SNB (AVX) architectures to maximize performance, you can use one of two patterns to select the appropriate instruction set functions:

1. Conditional Branching: Use a macro or conditional check to call the specific implementation (e.g., submit_job_avx vs submit_job_sse).

#define submit_job(mb_mgr) \
   if (_use_avx) submit_job_avx(mb_mgr); \
   else          submit_job_sse(mb_mgr)

2. Function Table: Embed function addresses into a structure and switch the structure pointer at runtime.

struct funcs_t {
    init_mb_mgr_t       init_mb_mgr;
    get_next_job_t      get_next_job;
    submit_job_t        submit_job;
    get_completed_job_t get_completed_job;
    flush_job_t         flush_job;
};

funcs_t funcs_sse = { init_mb_mgr_sse, get_next_job_sse, submit_job_sse, get_completed_job_sse, flush_job_sse };
funcs_t funcs_avx = { init_mb_mgr_avx, get_next_job_avx, submit_job_avx, get_completed_job_avx, flush_job_avx };

funcs_t *funcs = &funcs_sse;
if (do_avx) funcs = &funcs_avx;

funcs->init_mb_mgr(&mb_mgr);

The library provides two distinct API paths that serve different performance and architectural needs:

1. GCM API: An optimized single-buffer implementation. It consists of simple computational routines with no associated state. Use this when you need high-performance processing for individual packets or when you want to manage GCM calls independently of your multi-buffer processing logic (e.g., calling them directly in a main thread while enqueuing multi-buffer jobs for a worker thread).

2. Multi-Buffer API: Designed for high-throughput processing of multiple requests. It uses two parallel interfaces based on processor capabilities:

   • _sse functions: For WSM and later processors.
   • _avx functions: For processors newer than WSM, offering better performance.

Critical Constraint: You cannot mix these interfaces on the same initialized object. If you initialize an MB_MGR structure using init_mb_mgr_sse(), you must only use the _sse suffixed functions with it. If you use init_mb_mgr_avx(), you must only use the _avx functions.

The library supports an optional build mode that uses Valgrind's memcheck to detect secret-dependent branches and memory accesses. This helps identify potential timing and cache side-channel leaks.

How it works

Secrets are marked as "undefined" for Valgrind. If the code branches on or indexes memory using a value derived from these secrets, Memcheck reports an error. This instrumentation propagates from C annotations into hand-written assembly implementations.

Coverage

• ML-DSA/ML-KEM: Full coverage via OpenSSL ML-DSA/ML-KEM sources.
• JOB API AEAD: Covers AES-GCM, SM4-GCM, AES-CCM, ChaCha20-Poly1305.
• JOB API Cipher: Covers AES (CBC, CTR, ECB, CFB), DOCSIS, PON-AES, SM4, ChaCha20, DES, 3DES.
• JOB API Wireless: Covers ZUC, SNOW3G, SNOW5G, KASUMI.
• JOB API Authentication: Covers HMAC (MD5, SHA-1, SHA-2, SHA-3, SM3), AES-GMAC, GHASH, Poly1305, AES-XCBC, AES-CMAC, ZUC, SNOW.
• Unkeyed Digests: Not applicable (e.g., SHA-1, SHA-2, SHA-3, CRC).

Limitations

• Only the JOB API is instrumented. The burst and direct APIs are not currently covered.
• Checks are dynamic and only observe code paths exercised by the test vectors.
• Requires Valgrind development headers and results in significantly slower execution.

Refer to the INSTALL guide for instructions on how to enable this build option.

The Intel(R) Multi-Buffer Crypto for IPsec Library optimizes performance based on the host processor's instruction set extensions. The library supports several architecture types ranging from SSE to AVX10. Understanding your hardware's capabilities helps in predicting performance characteristics.

Architecture Types Reference

The library operates on an asynchronous paradigm where the application submits 'jobs' to a Multi-Buffer Manager (MB_MGR) and retrieves them once processing is complete.

Core Workflow:

1. Acquire: Call get_next_job() to get a pointer to a new JOB_AES_HMAC structure. The library manages the lifecycle of these objects; data in a job is guaranteed to be valid until the next call to get_next_job().
2. Configure: Fill in the fields of the JOB_AES_HMAC structure (see Job Fields).
3. Submit: Call submit_job() to send the job to the manager. This returns a pointer to the job if it was completed immediately, or NULL if it is still outstanding.
4. Retrieve Completed Jobs: Use get_completed_job() to poll for completed jobs. This helps reduce latency and manage the number of outstanding jobs.
5. Flush: If there is a lull in incoming work, call flush_job() to force the completion of the earliest outstanding job. This prevents jobs from sitting in the manager with high latency during idle periods.

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