NAME

       libipsec-mb - overview of Intel(R) Multi-Buffer Crypto for IPSec library

DESCRIPTION

       Intel  Multi-Buffer  Crypto  for  IPsec Library provides highly-optimized software crypto implementations
       targeting packet processing applications such as IPsec, TLS, Wireless  (RAN),  Cable  and  MPEG  DRM  and
       provides industry-leading performance on a range of Intel(R) Processors.
       The  library offers API crafted for applications where a buffer is subject of encryption and/or integrity
       operations.
       For best processor utilization it uses multi buffer technology for  algorithms  that  don't  allow  multi
       block processing.
       See  more  in  the  Intel  White  Paper:  "Fast  Multi-buffer IPsec Implementations on Intel Architecture
       Processors".  Jim Guilford, Sean Gulley, et. al.
       The easiest way to find it is to search the Internet for the title.

       More information can be found at intel-ipsec-mb ⟨https://github.com/intel/intel-ipsec-mb⟩.

   ENCRYPTION ALGORITHMS
       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.

   INTEGRITY ALGORITHMS
       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.

   RECOMMENDATIONS
       DES algorithm should be avoided and AES encryption should be used instead.
       3DES is a legacy algorithms 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.
       AES-ECB algorithm should be avoided and AES-CBC or AES-CNTR encryption should be used instead.

   KEY STORAGE
       The library doesn't offer any solution for secure key storage or storage of sensitive information.  It is
       up to application to arrange safe storage of sensitive information.

   API
       The library offers four sets of identical API's. Each set corresponds to one architecture: SSE, AVX, AVX2
       and AVX512.
       It comprises of init_mb_mgr, get_next_job, submit_job, get_completed_job and flush_job operations.
       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);
               }

       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 ⟨https://github.com/intel/intel-ipsec-mb/issues⟩.

AUTHORS

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

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