1.. SPDX-License-Identifier: BSD-3-Clause 2 Copyright(c) 2015-2018 Intel Corporation. 3 4AES-NI Multi Buffer Crypto Poll Mode Driver 5=========================================== 6 7 8The AESNI MB PMD (**librte_crypto_aesni_mb**) provides poll mode crypto driver 9support for utilizing Intel multi buffer library, see the white paper 10`Fast Multi-buffer IPsec Implementations on Intel® Architecture Processors 11<https://www.intel.com/content/dam/www/public/us/en/documents/white-papers/fast-multi-buffer-ipsec-implementations-ia-processors-paper.pdf>`_. 12 13The AES-NI MB PMD supports synchronous mode of operation with 14``rte_cryptodev_sym_cpu_crypto_process`` function call. 15 16Features 17-------- 18 19AESNI MB PMD has support for: 20 21Cipher algorithms: 22 23* RTE_CRYPTO_CIPHER_AES128_CBC 24* RTE_CRYPTO_CIPHER_AES192_CBC 25* RTE_CRYPTO_CIPHER_AES256_CBC 26* RTE_CRYPTO_CIPHER_AES128_CTR 27* RTE_CRYPTO_CIPHER_AES192_CTR 28* RTE_CRYPTO_CIPHER_AES256_CTR 29* RTE_CRYPTO_CIPHER_AES_DOCSISBPI 30* RTE_CRYPTO_CIPHER_DES_CBC 31* RTE_CRYPTO_CIPHER_3DES_CBC 32* RTE_CRYPTO_CIPHER_DES_DOCSISBPI 33* RTE_CRYPTO_CIPHER_AES128_ECB 34* RTE_CRYPTO_CIPHER_AES192_ECB 35* RTE_CRYPTO_CIPHER_AES256_ECB 36* RTE_CRYPTO_CIPHER_ZUC_EEA3 37* RTE_CRYPTO_CIPHER_SNOW3G_UEA2 38* RTE_CRYPTO_CIPHER_KASUMI_F8 39* RTE_CRYPTO_CIPHER_SM4_CBC 40* RTE_CRYPTO_CIPHER_SM4_ECB 41* RTE_CRYPTO_CIPHER_SM4_CTR 42 43Hash algorithms: 44 45* RTE_CRYPTO_AUTH_MD5_HMAC 46* RTE_CRYPTO_AUTH_SHA1_HMAC 47* RTE_CRYPTO_AUTH_SHA224_HMAC 48* RTE_CRYPTO_AUTH_SHA256_HMAC 49* RTE_CRYPTO_AUTH_SHA384_HMAC 50* RTE_CRYPTO_AUTH_SHA512_HMAC 51* RTE_CRYPTO_AUTH_AES_XCBC_HMAC 52* RTE_CRYPTO_AUTH_AES_CMAC 53* RTE_CRYPTO_AUTH_AES_GMAC 54* RTE_CRYPTO_AUTH_SHA1 55* RTE_CRYPTO_AUTH_SHA224 56* RTE_CRYPTO_AUTH_SHA256 57* RTE_CRYPTO_AUTH_SHA384 58* RTE_CRYPTO_AUTH_SHA512 59* RTE_CRYPTO_AUTH_ZUC_EIA3 60* RTE_CRYPTO_AUTH_SNOW3G_UIA2 61* RTE_CRYPTO_AUTH_KASUMI_F9 62* RTE_CRYPTO_AUTH_SM3 63* RTE_CRYPTO_AUTH_SM3 HMAC 64 65AEAD algorithms: 66 67* RTE_CRYPTO_AEAD_AES_CCM 68* RTE_CRYPTO_AEAD_AES_GCM 69* RTE_CRYPTO_AEAD_CHACHA20_POLY1305 70 71Protocol offloads: 72 73* RTE_SECURITY_PROTOCOL_DOCSIS 74 75Limitations 76----------- 77 78* Out-of-place is not supported for combined Crypto-CRC DOCSIS security 79 protocol. 80* RTE_CRYPTO_CIPHER_DES_DOCSISBPI is not supported for combined Crypto-CRC 81 DOCSIS security protocol. 82 83AESNI MB PMD selection over SNOW3G/ZUC/KASUMI PMDs 84-------------------------------------------------- 85 86This PMD supports wireless cipher suite (SNOW3G, ZUC and KASUMI). 87On Intel processors, it is recommended to use this PMD 88instead of SNOW3G, ZUC and KASUMI PMDs, as it enables algorithm mixing 89(e.g. cipher algorithm SNOW3G-UEA2 with authentication algorithm AES-CMAC-128) 90and performance over IMIX (packet size mix) traffic is significantly higher. 91 92AESNI MB PMD selection over CHACHA20-POLY1305 PMD 93------------------------------------------------- 94 95This PMD supports Chacha20-Poly1305 algorithm. 96On Intel processors, it is recommended to use this PMD instead of CHACHA20-POLY1305 PMD, 97as it delivers better performance on single segment buffers. 98For multi-segment buffers, it is still recommended to use CHACHA20-POLY1305 PMD, 99until the new SGL API is introduced in the AESNI MB PMD. 100 101Installation 102------------ 103 104To build DPDK with the AESNI_MB_PMD the user is required to download the multi-buffer 105library from `here <https://github.com/01org/intel-ipsec-mb>`_ 106and compile it on their user system before building DPDK. 107The latest version of the library supported by this PMD is v1.5, which 108can be downloaded from `<https://github.com/01org/intel-ipsec-mb/archive/v1.5.zip>`_. 109 110.. code-block:: console 111 112 make 113 make install 114 115The library requires NASM to be built. Depending on the library version, it might 116require a minimum NASM version (e.g. v0.54 requires at least NASM 2.14). 117 118NASM is packaged for different OS. However, on some OS the version is too old, 119so a manual installation is required. In that case, NASM can be downloaded from 120`NASM website <https://www.nasm.us/pub/nasm/releasebuilds/?C=M;O=D>`_. 121Once it is downloaded, extract it and follow these steps: 122 123.. code-block:: console 124 125 ./configure 126 make 127 make install 128 129As a reference, the following table shows a mapping between the past DPDK versions 130and the Multi-Buffer library version supported by them: 131 132.. _table_aesni_mb_versions: 133 134.. table:: DPDK and Multi-Buffer library version compatibility 135 136 ============== ============================ 137 DPDK version Multi-buffer library version 138 ============== ============================ 139 20.11 - 21.08 0.53 - 1.3 140 21.11+ 1.0 - 1.5 141 ============== ============================ 142 143Initialization 144-------------- 145 146In order to enable this virtual crypto PMD, user must: 147 148* Build the multi buffer library (explained in Installation section). 149 150To use the PMD in an application, user must: 151 152* Call rte_vdev_init("crypto_aesni_mb") within the application. 153 154* Use --vdev="crypto_aesni_mb" in the EAL options, which will call rte_vdev_init() internally. 155 156The following parameters (all optional) can be provided in the previous two calls: 157 158* socket_id: Specify the socket where the memory for the device is going to be allocated 159 (by default, socket_id will be the socket where the core that is creating the PMD is running on). 160 161* max_nb_queue_pairs: Specify the maximum number of queue pairs in the device (8 by default). 162 163* max_nb_sessions: Specify the maximum number of sessions that can be created (2048 by default). 164 165Example: 166 167.. code-block:: console 168 169 ./dpdk-l2fwd-crypto -l 1 -n 4 --vdev="crypto_aesni_mb,socket_id=0,max_nb_sessions=128" \ 170 -- -p 1 --cdev SW --chain CIPHER_HASH --cipher_algo "aes-cbc" --auth_algo "sha1-hmac" 171 172Extra notes 173----------- 174 175For AES Counter mode (AES-CTR), the library supports two different sizes for Initialization 176Vector (IV): 177 178* 12 bytes: used mainly for IPsec, as it requires 12 bytes from the user, which internally 179 are appended the counter block (4 bytes), which is set to 1 for the first block 180 (no padding required from the user) 181 182* 16 bytes: when passing 16 bytes, the library will take them and use the last 4 bytes 183 as the initial counter block for the first block. 184